Agent rules

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)