Agent Skill: Generate and maintain AGENTS.md files following the public agents.md convention. Use when creating AI agent documentation, onboarding guides, or standardizing agent patterns. By Netresearch.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Agent Skill: Generate and maintain AGENTS.md files following the public agents.md convention. Use when creating AI agent documentation, onboarding guides, or standardizing agent patterns. By Netresearch.
AGENTS.md is FOR AGENTS, not humans. Human readability is a convenient side effect, not a design goal. Every section, format choice, and word exists to maximize AI coding agent efficiency. If something helps humans but wastes agent tokens, remove it.
Spec Compliance: This skill follows the official agents.md specification which has no required fields - all sections are recommendations based on best practices from 2,500+ repositories.
Language Choice
Default to English - AI coding agents perform best with English instructions because:
Programming keywords, libraries, and error messages are English
Zero "semantic friction" between instruction and code (Create user → createUser)
Most token-efficient encoding for technical instructions
Exception: Match your code's naming language. If your codebase uses non-English naming conventions (e.g., German class names like Rechnungssteller, French variables like id_client), write AGENTS.md in that language to prevent "naming hallucinations" where agents mix languages.
Rule: The language of AGENTS.md must match the language used for domain naming in the code.
When to Use This Skill
When creating new projects, use this skill to establish baseline AGENTS.md structure.
When standardizing existing projects, use this skill to generate consistent agent documentation.
When ensuring multi-repo consistency, use this skill to apply the same standards across repositories.
When checking if AGENTS.md files are up to date, use the freshness checking scripts to compare file timestamps with git commits.
Prerequisites
The generator scripts require:
Requirement
Version
Notes
Bash
4.3+
Required for nameref variables (local -n)
jq
1.5+
JSON processing
git
2.0+
For git history analysis
macOS Users
macOS ships with Bash 3.2 (GPLv2 licensed). Install a newer version:
# Install Bash 4.4+ via Homebrew
brew install bash
# Run scripts with newer bash
/opt/homebrew/bin/bash scripts/generate-agents.sh /path/to/project
# Or add to PATH (optional)export PATH="/opt/homebrew/bin:$PATH"
The scripts will detect incompatible Bash versions and exit with a helpful error message.
CRITICAL: Full Verification Required
NEVER trust existing AGENTS.md content as accurate. Always verify documented information against the actual codebase:
Mandatory Verification Steps
Extract actual state from source files:
List all modules/files with their actual docstrings
List all scripts and their actual purposes
Extract actual Makefile/package.json commands
List actual test files and structure
Compare extracted state against documented state:
Check if documented files actually exist
Check if documented commands actually work
Check if module descriptions match actual docstrings
Check if counts (modules, scripts, tests) are accurate
Identify and fix discrepancies:
Remove documentation for non-existent files
Add documentation for undocumented files
Correct inaccurate descriptions
Update outdated counts and references
Preserve unverifiable content:
Keep manually-written context that can't be extracted
Keep subjective guidance and best practices
Mark preserved content appropriately
What to Verify
Category
Verification Method
Module list
ls <dir>/*.py + read docstrings
Script list
ls scripts/*.sh + read headers
Commands
grep Makefile targets AND run them
Test files
ls tests/*.py
Data files
ls *.json in project root
Config files
Check actual existence
File names
EXACT match required (not just existence)
Numeric values
PHPStan level, coverage %, etc. from actual configs
Critical: Exact Name Matching
File names in AGENTS.md must match actual filenames exactly:
This mismatch confused agents trying to find the file
Critical: Command Verification
Commands documented in AGENTS.md must actually work when run:
# BAD: Document without testing
make test-mutation # May not exist!# GOOD: Verify before documenting
make -n test-mutation 2>/dev/null && echo"EXISTS" || echo"MISSING"
Real-world example from t3x-cowriter review:
AGENTS.md documented make test-mutation and make phpstan
Neither target existed (actual was make typecheck)
Agents failed when trying to run documented commands
Example Verification Commands
# Extract actual module docstringsfor f in cli_audit/*.py; dohead -20 "$f" | grep -A5 '"""'; done# List actual scriptsls scripts/*.sh
# Extract Makefile targets
grep -E '^[a-z_-]+:' Makefile*
# List actual test filesls tests/*.py tests/**/*.py
Anti-Patterns to Avoid
WRONG: Updating only dates and counts based on git commits
WRONG: Trusting that existing AGENTS.md was created correctly
WRONG: Copying file lists without verifying they exist
WRONG: Using extracted command output without running it
To extract information from .editorconfig, .vscode/, .idea/, etc.:
scripts/extract-ide-settings.sh /path/to/project
Extracting AI Agent Configs
To extract information from .cursor/, .claude/, copilot-instructions.md, etc.:
scripts/extract-agent-configs.sh /path/to/project
Verifying Content Accuracy
CRITICAL: Always run this before considering AGENTS.md files complete.
To verify that AGENTS.md content matches actual codebase state:
scripts/verify-content.sh /path/to/project
This script:
Checks if documented files actually exist
Verifies Makefile targets are real
Compares module/script counts against actual files
Reports undocumented files that should be added
Reports documented files that don't exist
Options:
--verbose, -v - Show detailed verification output
--fix - Suggest fixes for common issues
This verification step is MANDATORY when updating existing AGENTS.md files.
Verifying Commands Work
To prevent "command rot" (documented commands that no longer work):
scripts/verify-commands.sh /path/to/project
This script:
Extracts commands from AGENTS.md tables and code blocks
Verifies npm/yarn scripts exist in package.json
Verifies make targets exist in Makefile
Verifies composer scripts exist in composer.json
Updates "Last verified" timestamp on success
Options:
VERBOSE=true - Show detailed output
DRY_RUN=true - Don't update timestamp
Why this matters: Research shows broken commands waste 500+ tokens as agents debug non-existent commands. Verified commands enable confident execution.
Using Reference Documentation
AGENTS.md Analysis
When understanding best practices and patterns, consult references/analysis.md for analysis of 21 real-world AGENTS.md files.
Directory Coverage
When determining which directories need AGENTS.md files, consult references/directory-coverage.md for guidance on PHP/TYPO3, Go, and TypeScript project structures.
Real-World Examples
When needing concrete examples of AGENTS.md files, consult references/examples/:
Project
Files
Description
coding-agent-cli/
Root + scripts scope
CLI tool example
ldap-selfservice/
Root + internal scopes
Go web app with multiple scopes
simple-ldap-go/
Root + examples scope
Go library example
t3x-rte-ckeditor-image/
Root + Classes scope
TYPO3 extension example
Using Asset Templates
Root Templates
When generating root AGENTS.md files, the scripts use these templates:
assets/root-thin.md - Minimal root template (~30 lines) with precedence rules and scope index
assets/root-verbose.md - Detailed root template (~100 lines) with architecture overview and examples
Scoped Templates
When generating scoped AGENTS.md files, the scripts use language-specific templates:
assets/scoped/backend-go.md - Go backend patterns (packages, error handling, testing)
GitHub Copilot uses .github/copilot-instructions.md for repository-wide instructions. This skill extracts existing Copilot instructions and can coexist with AGENTS.md files.
Directory Coverage
When creating AGENTS.md files, create them in ALL key directories:
