Building a Codex Harness - Overview of Settings, Rules, and Skills

Reliable Codex work requires more than repeating a long prompt in every thread. Repository rules, permissions, reusable procedures, and verification steps need versioned ownership. A Codex harness combines what Codex reads before work, what capabilities it can invoke, and what checks must pass after work.

The Codex Levels framework defines this area as Level 6: Harness Builder. For a practice-first route, build a minimal version in Level 6 Practice and then return here to design each component in detail.

What is a Codex harness?

A practical harness has three layers.

project-root/
├── AGENTS.md              # Entry point and working contract
├── shared/                # Shared rules, skills, and workflows
├── .agents/skills/        # Repository skills discovered by Codex
└── .codex/                # Codex-specific configuration and adapters
    ├── config.toml
    ├── rules/
    ├── hooks.json
    └── agents/

AGENTS.md defines the working agreement. shared/ owns detailed procedures that can be shared across runtimes. .codex/ and .agents/ expose Codex-specific configuration and capabilities. Required guidance belongs in Git; credentials and generated local state do not.

Section roadmap

Order	Page	Focus
1	AGENTS.md hierarchy design	Global, project, and subdirectory instruction chains
2	config.toml design	Models, approvals, sandboxes, and profiles
3	Rules file design	Allow, prompt, or forbid commands outside the sandbox
4	Commands and Workflows	Interactive commands, prompt files, and non-interactive execution
5	Skills design patterns	SKILL.md and progressive disclosure
6	Subagents design	Specialized roles and parallel work
7	Hooks implementation	Deterministic lifecycle automation
8	MCP and Plugins integration	External tools, apps, and MCP servers
9	Memories design	Local recall separated from mandatory rules
10	Harness testing and validation	Drift detection and CI validation
11	Plugin Marketplace publishing	Packaging and distributing reusable capabilities

Core design principles

1. Keep mandatory rules in AGENTS.md or checked-in documentation, not only in memory.
2. Grant the narrowest filesystem and network permissions that complete the task.
3. Separate explanatory guidance from enforceable Rules, Hooks, and CI checks.
4. Keep shared policy in shared/ and treat .codex/ as the Codex adapter layer.
5. Validate harness changes for syntax, references, synchronization, and behavior.

This repository is a working example: AGENTS.md routes Codex to shared/rules/, while .codex/agents/ is generated from shared/agents/. Start with AGENTS.md hierarchy design.

See the references for the external specifications and background sources used on this page.[1][2]

References

1. OpenAI, Codex documentation
2. OpenAI, OpenAI API documentation