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: ```bash 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 ```markdown # 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: ```bash 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): ```bash 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/`): ```bash 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: ```bash 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 |