agents-md-manager

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