agent-rules
npx machina-cli add skill netresearch/agent-rules-skill/agent-rules --openclawFiles (1)
SKILL.md
3.8 KB
AGENTS.md Generator Skill
Overview
Generate and maintain AGENTS.md files following the agents.md convention. AGENTS.md is FOR AGENTS, not humans.
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) |
Source
git clone https://github.com/netresearch/agent-rules-skill/blob/main/skills/agent-rules/SKILL.mdView on GitHub Overview
Generates and maintains AGENTS.md files following the agents.md convention. AGENTS.md is intended for AI agents, not humans, helping standardize agent documentation across repositories.
How This Skill Works
It generates AGENTS.md using the project’s scripts and templates, aligning with the agents.md convention. It then validates structure, freshness, and content through dedicated scripts to ensure commands and entries reflect the codebase.
When to Use It
- 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 Start
- Step 1: Run scripts/generate-agents.sh PATH to generate AGENTS.md from a baseline
- Step 2: Run scripts/validate-structure.sh PATH to ensure structural conformance
- Step 3: Run scripts/check-freshness.sh PATH and scripts/verify-content.sh PATH to confirm freshness and accuracy
Best Practices
- Structured over Prose - tables and maps parse faster than paragraphs
- Verified Commands - commands that don’t work waste 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
Example Use Cases
- Create a baseline AGENTS.md for a new Go service
- Standardize AGENTS.md across a multi-repo microservices project
- Onboard AI agents to an unfamiliar repository
- Validate AGENTS.md freshness after a major code change
- Migrate legacy AGENTS.md to the latest agents.md convention
Frequently Asked Questions
Add this skill to your agents
