agent-rules skill
✓ OfficialscriptsGenerate, validate, and maintain AGENTS.md files to standardize project onboarding and documentation for AI agents.
- GitHub stars
- 89
- Files
- 159
- Last commit
- Nov 10, 2026
- License
- See LICENSE
- Allowed tools
- 10
What does the agent-rules skill do?
agent-rules is an agent skill. Generate, validate, and maintain AGENTS.md files to standardize project onboarding and documentation for AI agents.
Summary generated from the skill's SKILL.md.
About the agent-rules skill
Standardizing project onboarding and documentation for AI agents is the primary function of this skill. It allows developers to generate, validate, and maintain AGENTS.md files that follow specific conventions designed for machine consumption rather than human reading. An agent should load this skill when scaffolding a new repository, updating existing documentation, or onboarding to an unfamiliar codebase to ensure all instructions are accurate and structured.
The skill utilizes a suite of specialized bash scripts to automate the documentation lifecycle. It can detect project languages and build tools, extract commands from configurations, and pull architectural rules or CI quality gates. To ensure reliability, it provides tools to verify that documented commands actually execute and that content matches the current state of the codebase. It relies on standard system tools like bash, jq, git, grep, and find to perform these operations. Users can generate different styles of documentation, such as thin or verbose versions, while maintaining strict line limits to prevent bloat.
What an agent can do with it
- 1Scaffold new repository documentationCreate an initial AGENTS.md file when starting a new project to provide immediate context for AI agents.
Written from the skill's SKILL.md. Every use case is checked against a quote from it.
How to install the agent-rules skill
Each command copies the skill folder into the client's skills directory. Restart the client or start a new session to load it.Install the agent-rules skill in Claude Code
~/.claude/skills/agent-rules/SKILL.md
$ npx degit netresearch/agent-rules-skill/skills/agent-rules ~/.claude/skills/agent-rulesInstall the agent-rules skill in Claude Code (project)
.claude/skills/agent-rules/SKILL.md
$ npx degit netresearch/agent-rules-skill/skills/agent-rules .claude/skills/agent-rulesInstall the agent-rules skill in Codex
~/.agents/skills/agent-rules/SKILL.md
$ npx degit netresearch/agent-rules-skill/skills/agent-rules ~/.agents/skills/agent-rulesInstall the agent-rules skill in Gemini CLI
~/.gemini/skills/agent-rules/SKILL.md
$ npx degit netresearch/agent-rules-skill/skills/agent-rules ~/.gemini/skills/agent-rulesInstall the agent-rules skill in Claude.ai
npx degit netresearch/agent-rules-skill/skills/agent-rules agent-rules && zip -r agent-rules.zip agent-rules # claude.ai → Customize → Skills → + → Create skill → Upload a skill → agent-rules.zip
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A skill needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablenetresearch/agent-rules-skill/skills/agent-rules is public and reachablegithub.com/netresearch/agent-rules-skill/tree/HEAD/skills/ag ↗Pass
- Open source license (OSI)License named in a file, not as an SPDX idNot checked
- Commit or release in the last yearLast commit 2026-11-10github.com/netresearch/agent-rules-skill/commits ↗Pass
- No download-and-run or credential theft in scripts5 of 52 scripts read; none of them downloads and runs code, the rest were not readFinding
- No hidden instructions in SKILL.mdNo override phrases, safeguard switches, credential requests or hidden charactersgithub.com/netresearch/agent-rules-skill/blob/HEAD/skills/ag ↗Pass
- Pre-approved tools are scopedPre-approved: Bash(${CLAUDE_SKILL_DIR}/scripts/*), Bash(bash, ${CLAUDE_SKILL_DIR}/scripts/*), Bash(git:*), Bash(jq:*), Bash(grep:*), …github.com/netresearch/agent-rules-skill/blob/HEAD/skills/ag ↗Pass
- SKILL.md follows the Agent Skills formatValid name and description; says when to use it; 94 linesgithub.com/netresearch/agent-rules-skill/blob/HEAD/skills/ag ↗Pass
SKILL.md
View on GitHubAGENTS.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
- Scaffolding a new repository — ship AGENTS.md with the initial commits; retrofitting later needs full re-verification
- Standardizing agent documentation across repositories
- Checking AGENTS.md freshness after code changes
- Onboarding AI agents to an unfamiliar codebase
Scripts
Call every script by its full path: bash ${CLAUDE_SKILL_DIR}/scripts/<name> PATH. Calling one relative to the working directory is not covered by the frontmatter rule and raises a permission prompt per call.
| Script | Purpose |
|---|---|
generate-agents.sh PATH |
Generate AGENTS.md files |
validate-structure.sh PATH |
Validate structure compliance |
check-freshness.sh PATH |
Check if files are outdated |
verify-content.sh PATH |
Verify documented files/commands match codebase |
verify-commands.sh PATH |
Verify documented commands execute |
score-agents.sh PATH |
Grade AGENTS.md quality, worst-first |
detect-project.sh PATH |
Detect language, version, build tools |
detect-scopes.sh PATH |
Identify directories needing scoped files |
extract-commands.sh PATH |
Extract commands from build configs |
extract-ci-rules.sh PATH |
Extract CI quality gates and version matrix |
extract-architecture-rules.sh PATH |
Extract module boundaries |
extract-adrs.sh PATH |
Extract architectural decision records |
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— stacks and subsystems - Extract:
extract-commands.sh,extract-ci-rules.sh— gather facts - Generate:
generate-agents.sh --style=thin(default) or--verbose - Verify:
verify-content.sh+verify-commands.sh-- MANDATORY before done. Replace the generated**Changelog:**TODO: name the file, its format and which PR writes the entry, read from the last merged PRs (AG-32, AG-33) - Line cap: before committing any root AGENTS.md edit,
wc -l AGENTS.mdmust be under 150 (harnessAH-02); run the repo'sverify-harness.shwhere it exists -- CI's harness check fails otherwise
--update preserves 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 by default (
ai-tool-compatibility.md)
References
| File | Contents |
|---|---|
verification-guide.md |
Verification steps, anti-bloat, preservation check |
fleet-sync-sweep.md |
Fleet-wide AGENTS.md sweeps |
scripts-guide.md |
Script options, validation checklist |
quality-rubric.md |
Grading rubric |
ai-tool-compatibility.md |
16-agent compatibility matrix |
output-structure.md |
Root/scoped sections |
git-hooks-setup.md |
Hook framework setup |
examples/ |
Complete examples |
ai-contribution-guidelines.md |
"3 Cs" AI-contribution framework |
directory-coverage.md |
Scoped-file coverage rationale |
feedback-memory-schema.md |
Approved-learning file format |
Templates
Root: assets/root-thin.md (default) or root-verbose.md. Scoped: assets/scoped/, one per stack (Go/PHP/Python/TYPO3/Symfony/Oro/CLI/TS/skill-repo).
Supported Projects
Go, PHP (Composer/Laravel/Symfony/TYPO3/Oro), TypeScript (React/Next/Vue/Node), Python (pip/poetry/ruff/mypy), skill repos, hybrid.
See Also
agent-harness-skill— agent-readiness harness (CI enforcement).skill-repo-skill— skill-repo structure (plugin.json, licensing, releases).
Files in this skill
159agent-rules skill questions
How do I install the agent-rules skill in Claude Code?
Run npx degit netresearch/agent-rules-skill/skills/agent-rules ~/.claude/skills/agent-rules. Claude Code loads skills from ~/.claude/skills (all projects) or .claude/skills (one project) and uses a skill when its description matches the task.
Which clients can use the agent-rules skill?
Any client that reads the Agent Skills format: Claude Code, Codex, Gemini CLI and claude.ai (upload as a ZIP). Scripts in the skill run only where the client allows code execution.
What is the purpose of AGENTS.md?
AGENTS.md is a file designed specifically for AI agents rather than humans to help them understand and navigate a project.
What programming languages and frameworks are supported?
The skill supports Go, PHP (including Laravel, Symfony, TYPO3, and Oro), TypeScript (React, Next, Vue, Node), and Python (pip, poetry, ruff, mypy).