Claude-code-minoan agents-md-manager

install

source · Clone the upstream repo

git clone https://github.com/tdimino/claude-code-minoan

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/tdimino/claude-code-minoan "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/core-development/agents-md-manager" ~/.claude/skills/tdimino-claude-code-minoan-agents-md-manager && rm -rf "$T"

manifest: skills/core-development/agents-md-manager/SKILL.md

source content

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