AGENTS.md Generator Skill
Generate and maintain AGENTS.md files following the agents.md convention. AGENTS.md is FOR AGENTS, not humans.
When to Use
- Creating or updating AGENTS.md for new/existing projects
- Standardizing agent documentation across repositories
- Checking if AGENTS.md files are current with recent code changes
- Onboarding AI agents to an unfamiliar codebase
Scripts
| Script |
Purpose |
scripts/generate-agents.sh PATH |
Generate AGENTS.md files |
scripts/validate-structure.sh PATH |
Validate structure compliance |
scripts/check-freshness.sh PATH |
Check if files are outdated |
scripts/verify-content.sh PATH |
Verify documented files/commands match codebase |
scripts/verify-commands.sh PATH |
Verify documented commands execute |
scripts/detect-project.sh PATH |
Detect language, version, build tools |
scripts/detect-scopes.sh PATH |
Identify directories needing scoped files |
scripts/extract-commands.sh PATH |
Extract commands from build configs |
scripts/extract-ci-rules.sh PATH |
Extract CI quality gates and version matrix |
scripts/extract-architecture-rules.sh PATH |
Extract module boundaries |
scripts/extract-adrs.sh PATH |
Extract architectural decision records |
scripts/extract-github-rulesets.sh PATH |
Extract GitHub rulesets and merge rules |
See references/scripts-guide.md for full options.
Workflow
- Detect:
detect-project.sh + detect-scopes.sh to identify stacks and subsystems
- Extract:
extract-commands.sh, extract-ci-rules.sh, etc. to gather facts
- Generate:
generate-agents.sh with --style=thin (default) or --verbose
- Verify:
verify-content.sh + verify-commands.sh -- MANDATORY before done
Use --update to preserve human-curated content outside <!-- GENERATED --> markers.
Core Principles
- Structured over Prose -- tables parse faster than paragraphs
- Never Fabricate -- only document what exists; verify every command and path
- Pointer Principle -- point to files, don't duplicate content
- Auto Symlinks -- CLAUDE.md/GEMINI.md symlinks by default (see
ai-tool-compatibility.md)
References
| File |
Contents |
verification-guide.md |
Verification steps, design principles |
scripts-guide.md |
Script options, validation checklist |
ai-tool-compatibility.md |
16-agent compatibility matrix |
output-structure.md |
Root/scoped sections |
git-hooks-setup.md |
Hook framework detection and setup |
examples/ |
Complete examples |
ai-contribution-guidelines.md |
"3 Cs" framework for AI contributions (Comprehension, Context, Continuity) |
directory-coverage.md |
Full coverage rationale for scoped AGENTS.md files |
Templates
Root: assets/root-thin.md (default), root-verbose.md. Scoped: assets/scoped/ -- backend-go.md, backend-php.md, python-modern.md, typo3.md, symfony.md, skill-repo.md, cli.md, frontend-typescript.md, oro.md.
Supported Projects
Go, PHP (Composer/Laravel/Symfony/TYPO3/Oro), TypeScript (React/Next/Vue/Node), Python (pip/poetry/ruff/mypy), Skill repos, Hybrid (multi-stack with auto-scoping).
See Also
agent-harness-skill — broader agent-readiness harness (CI verification, enforcement). Invokes this skill when AGENTS.md is missing.skill-repo-skill — skill-repo structure (plugin.json, split licensing, release workflows).
1---2name: agent-rules3description: Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.4license: (MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.05---67# AGENTS.md Generator Skill89Generate and maintain AGENTS.md files following the [agents.md convention](https://agents.md/). AGENTS.md is FOR AGENTS, not humans.1011## When to Use1213- Creating or updating AGENTS.md for new/existing projects14- Standardizing agent documentation across repositories15- Checking if AGENTS.md files are current with recent code changes16- Onboarding AI agents to an unfamiliar codebase1718## Scripts1920| Script | Purpose |21|--------|---------|22| `scripts/generate-agents.sh PATH` | Generate AGENTS.md files |23| `scripts/validate-structure.sh PATH` | Validate structure compliance |24| `scripts/check-freshness.sh PATH` | Check if files are outdated |25| `scripts/verify-content.sh PATH` | Verify documented files/commands match codebase |26| `scripts/verify-commands.sh PATH` | Verify documented commands execute |27| `scripts/detect-project.sh PATH` | Detect language, version, build tools |28| `scripts/detect-scopes.sh PATH` | Identify directories needing scoped files |29| `scripts/extract-commands.sh PATH` | Extract commands from build configs |30| `scripts/extract-ci-rules.sh PATH` | Extract CI quality gates and version matrix |31| `scripts/extract-architecture-rules.sh PATH` | Extract module boundaries |32| `scripts/extract-adrs.sh PATH` | Extract architectural decision records |33| `scripts/extract-github-rulesets.sh PATH` | Extract GitHub rulesets and merge rules |3435See `references/scripts-guide.md` for full options.3637## Workflow38391. **Detect**: `detect-project.sh` + `detect-scopes.sh` to identify stacks and subsystems402. **Extract**: `extract-commands.sh`, `extract-ci-rules.sh`, etc. to gather facts413. **Generate**: `generate-agents.sh` with `--style=thin` (default) or `--verbose`424. **Verify**: `verify-content.sh` + `verify-commands.sh` -- MANDATORY before done4344Use `--update` to preserve human-curated content outside `<!-- GENERATED -->` markers.4546## Core Principles4748- **Structured over Prose** -- tables parse faster than paragraphs49- **Never Fabricate** -- only document what exists; verify every command and path50- **Pointer Principle** -- point to files, don't duplicate content51- **Auto Symlinks** -- CLAUDE.md/GEMINI.md symlinks by default (see [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md))5253## References5455| File | Contents |56|------|----------|57| [`verification-guide.md`](references/verification-guide.md) | Verification steps, design principles |58| [`scripts-guide.md`](references/scripts-guide.md) | Script options, validation checklist |59| [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md) | 16-agent compatibility matrix |60| [`output-structure.md`](references/output-structure.md) | Root/scoped sections |61| [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework detection and setup |62| [`examples/`](references/examples/) | Complete examples |63| [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" framework for AI contributions (Comprehension, Context, Continuity) |64| [`directory-coverage.md`](references/directory-coverage.md) | Full coverage rationale for scoped AGENTS.md files |6566## Templates6768Root: `assets/root-thin.md` (default), `root-verbose.md`. Scoped: `assets/scoped/` -- `backend-go.md`, `backend-php.md`, `python-modern.md`, `typo3.md`, `symfony.md`, `skill-repo.md`, `cli.md`, `frontend-typescript.md`, `oro.md`.6970## Supported Projects7172Go, PHP (Composer/Laravel/Symfony/TYPO3/Oro), TypeScript (React/Next/Vue/Node), Python (pip/poetry/ruff/mypy), Skill repos, Hybrid (multi-stack with auto-scoping).7374## See Also7576- [`agent-harness-skill`](https://github.com/netresearch/agent-harness-skill) — broader agent-readiness harness (CI verification, enforcement). Invokes this skill when AGENTS.md is missing.77- [`skill-repo-skill`](https://github.com/netresearch/skill-repo-skill) — skill-repo structure (plugin.json, split licensing, release workflows).
dirien