AGENTS.md Manager

Create and maintain AGENTS.md files and Codex CLI configuration for any project.

Core Workflow

Determine the mode:

Mode	When	Script
Create	New project needs AGENTS.md	`scripts/analyze_project.py` then write
Refresh	Existing AGENTS.md needs audit	`scripts/validate_agents_md.py`
Convert	Migrate from CLAUDE.md	`scripts/convert_claude_to_agents.py`
Config	Generate config.toml	`scripts/generate_config_toml.py`
Rules	Create .rules files	See `references/starlark-rules-spec.md`
Skills	Scaffold .agents/skills/	`scripts/scaffold_codex_skill.py`

1. Project Analysis

Run analysis to detect stack, existing config, and gaps:

python3 ~/.claude/skills/agents-md-manager/scripts/analyze_project.py [project_path]

Output: JSON report with tech stack, commands, directory structure, and Codex artifact inventory (AGENTS.md, config.toml, .rules, .agents/skills/, CLAUDE.md conversion candidates).

2. AGENTS.md Generation

Apply the WHAT/WHY/HOW framework in plain markdown only—no @import syntax, no YAML frontmatter.

Recommended Sections

# Project Name

Brief description.

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Build: `pnpm build`
- Lint: `pnpm lint`

## Structure
- `/src` — Application source
- `/tests` — Test suites

## Conventions
- [Critical convention 1]
- [Critical convention 2]

## Boundaries
- Always: Run tests before committing
- Ask: Before adding production dependencies
- Never: Modify migration files directly

## Troubleshooting
- [Common issue and fix]

Constraints

Target under 200 lines per file, under 100 for nested subdirectory files
Respect 32 KiB limit (project_doc_max_bytes)
Plain markdown only—no @import, no YAML frontmatter
Include a "Boundaries" section (Always/Ask/Never) for agent guardrails
See references/templates.md for project-type-specific templates
See references/agents-md-spec.md for discovery and concatenation rules

3. CLAUDE.md Conversion

Convert existing CLAUDE.md to AGENTS.md format:

python3 ~/.claude/skills/agents-md-manager/scripts/convert_claude_to_agents.py <claude_md_path> [output_path]

Outputs AGENTS.md plus conversion_report.json listing transformations and manual review items.

Key transformations: @import inlined or nested; hooks become .rules suggestions; skill invocations become prose; Claude-specific commands stripped.

See references/conversion-mapping.md for the complete field-by-field mapping.

4. Config Generation

Generate ~/.codex/config.toml (global) or .codex/config.toml (project-scoped):

python3 ~/.claude/skills/agents-md-manager/scripts/generate_config_toml.py [--global | --project <path>] [--model MODEL] [--sandbox MODE]

Covers: model, reasoning effort, personality, sandbox mode, MCP servers, profiles, trusted projects, writable roots.

See references/config-toml-reference.md for the complete field reference.

5. Rules Files

Create .rules files in Starlark for command approval. Location: ~/.codex/rules/ (global) or .codex/rules/ (project). Rules files are authored manually—no generation script exists for this format. All .rules files in the directory are loaded and merged.

Common patterns:

Allow package manager commands (npm, pip, cargo)
Block destructive operations (rm -rf, git push --force)
Prompt for review on sensitive commands (git commit, gh pr create)

See references/starlark-rules-spec.md for syntax and examples.

6. Codex Skills

Scaffold .agents/skills/<name>/ in Codex format (different from Claude .claude/skills/):

python3 ~/.claude/skills/agents-md-manager/scripts/scaffold_codex_skill.py <name> [--path <dir>]

Creates SKILL.md with name + description frontmatter (both required for Codex), plus agents/openai.yaml for UI metadata.

See references/codex-skills-format.md for format differences from Claude skills.

7. Audit Checklist

When refreshing existing AGENTS.md, validate:

Under 32 KiB? (project_doc_max_bytes limit)
No @import syntax? (not supported in AGENTS.md)
No YAML frontmatter? (not used in AGENTS.md)
All documented commands verified against project config?
Directory references match actual structure?
No secrets or credentials?
Nested hierarchy consistent with root?
No AGENTS.override.md conflicts?
Under 200 lines? (warn >200, error >400)

Run automated audit:

python3 ~/.claude/skills/agents-md-manager/scripts/validate_agents_md.py [project_path]

8. Nested AGENTS.md (Monorepos)

For monorepos, place AGENTS.md at multiple levels:

/AGENTS.md              # Repo-wide conventions
/services/
  payments/
    AGENTS.override.md  # Payments-specific overrides
  search/
    AGENTS.md           # Search service conventions

One file per directory maximum
Codex concatenates root to CWD (closer-to-CWD appears later, overrides earlier)
AGENTS.override.md takes precedence over AGENTS.md in the same directory
Keep each nested file focused and under 100 lines

Integration Notes

codex-orchestrator: This skill creates config files; codex-orchestrator executes subagents with them
claude-md-manager: Sister skill for Claude Code's CLAUDE.md; use conversion mode to bridge
For subagent profile management, use codex-orchestrator

Reference Documentation

File	Contents
`references/agents-md-spec.md`	AGENTS.md discovery, concatenation, override, size limits, cross-agent compatibility
`references/config-toml-reference.md`	Complete config.toml field reference
`references/starlark-rules-spec.md`	.rules file syntax, prefix_rule(), decision types
`references/codex-skills-format.md`	.agents/skills/ format, openai.yaml, Claude skill differences
`references/conversion-mapping.md`	CLAUDE.md to AGENTS.md field-by-field mapping
`references/templates.md`	AGENTS.md templates by project type