AGENTS.md Generator Skill
Overview
Generate and maintain AGENTS.md files following the public agents.md convention. AGENTS.md is FOR AGENTS, not humans -- every section exists to maximize AI coding agent efficiency.
When to Use
- Creating a new project and establishing baseline AGENTS.md
- Standardizing existing projects with consistent agent documentation
- Ensuring multi-repo consistency across repositories
- Checking if AGENTS.md files are current with recent code changes
- Onboarding AI agents to an unfamiliar codebase
Quick Reference
| 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 vs git commits |
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 |
See references/scripts-guide.md for full options and validation checklist.
Core Principles
- Structured over Prose -- tables and maps parse faster than paragraphs
- Verified Commands -- commands that don't work waste 500+ tokens debugging
- Pointer Principle -- point to files, don't duplicate content
- Golden Samples -- one example file beats pages of explanation
- Audit Before Generating -- discover existing docs and pain points before running scripts
Language Choice
Default to English. Exception: match your code's naming language to prevent agents mixing languages.
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Bash | 4.3+ | Nameref variables (local -n). macOS: brew install bash |
| jq | 1.5+ | JSON processing |
| git | 2.0+ | For git history analysis |
References
Detailed documentation in references/:
| File | Contents |
|---|---|
verification-guide.md | Verification steps, name matching, command verification, design principles |
scripts-guide.md | Script options, post-generation validation checklist |
ai-tool-compatibility.md | Claude Code shim, Codex stacking, Copilot integration |
output-structure.md | Root/scoped sections, auto-generate vs manual curation |
analysis.md | Analysis of 21 real-world AGENTS.md files |
directory-coverage.md | Coverage guidance for PHP/TYPO3, Go, TypeScript |
examples/ | Complete examples (coding-agent-cli, ldap-selfservice, simple-ldap-go, t3x-rte-ckeditor-image) |
Asset Templates
Root templates in assets/: root-thin.md (~30 lines, default), root-verbose.md (~100 lines).
Scoped templates in assets/scoped/: backend-go.md, backend-php.md, typo3.md, oro.md, cli.md, frontend-typescript.md.
Supported Project Types
| Language | Project Types |
|---|---|
| Go | Libraries, web apps (Fiber/Echo/Gin), CLI (Cobra/urfave) |
| PHP | Composer packages, Laravel/Symfony |
| PHP/TYPO3 | TYPO3 extensions (auto-detected via ext_emconf.php) |
| PHP/Oro | OroCommerce, OroPlatform, OroCRM bundles |
| TypeScript | React, Next.js, Vue, Node.js |
| Python | pip, poetry, Django, Flask, FastAPI |
| Hybrid | Multi-language projects (auto-creates scoped files per stack) |