agent-rules
Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI
Install
npx skills add https://github.com/netresearch/agent-rules-skill/tree/main/skills/agent-rules
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install netresearch-agent-rules-skill@llmmart
git clone https://github.com/netresearch/agent-rules-skill.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole netresearch/agent-rules-skill collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
AGENTS.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 (agent-rules-skill)
-
assets
-
example-workflows
-
validate-agents.yml 2.8 KB
Loading…
-
-
scoped
-
backend-go.md 3.6 KB
Loading… -
backend-php.md 3 KB
Loading… -
backend-python.md 2.6 KB
Loading… -
backend-typescript.md 2.8 KB
Loading… -
claude-code-skill.md 3.4 KB
Loading… -
cli.md 2.7 KB
Loading… -
concourse.md 5.2 KB
Loading… -
ddev.md 2.4 KB
Loading… -
docker.md 5.3 KB
Loading… -
documentation.md 3.5 KB
Loading… -
examples.md 3.4 KB
Loading… -
frontend-typescript.md 2.7 KB
Loading… -
github-actions.md 5.2 KB
Loading… -
gitlab-ci.md 4.6 KB
Loading… -
oro-bundle.md 6.5 KB
Loading… -
oro-project.md 5.5 KB
Loading… -
python-modern.md 6.1 KB
Loading… -
resources.md 3.5 KB
Loading… -
skill-repo.md 5.4 KB
Loading… -
symfony.md 5.3 KB
Loading… -
testing.md 3 KB
Loading… -
typo3-docs.md 3.6 KB
Loading… -
typo3-extension.md 5.1 KB
Loading… -
typo3-project.md 4.7 KB
Loading… -
typo3-testing.md 3 KB
Loading…
-
-
.markdownlint-cli2.jsonc 624 B · in bundle
-
root-thin.md 5.7 KB
Loading… -
root-verbose.md 5.5 KB
Loading…
-
-
evals
-
evals.json 22.9 KB
Loading…
-
-
references
-
examples
-
coding-agent-cli
-
AGENTS.md 2.5 KB
Loading… -
go.mod 45 B · in bundle
-
scripts-AGENTS.md 10.1 KB
Loading…
-
-
express-api-ts
-
src
-
controllers
-
userController.ts 2.1 KB
Loading…
-
-
middleware
-
errorHandler.ts 1 KB
Loading… -
requestLogger.ts 471 B
Loading…
-
-
routes
-
health.ts 428 B
Loading… -
users.ts 397 B
Loading…
-
-
utils
-
errors.ts 1.2 KB
Loading… -
logger.ts 441 B
Loading…
-
-
AGENTS.md 3.1 KB
Loading… -
config.ts 917 B
Loading… -
index.ts 671 B
Loading…
-
-
.env.example 232 B · in bundle
-
AGENTS.md 3.1 KB
Loading… -
package.json 758 B
Loading… -
pnpm-lock.yaml 101 B
Loading… -
tsconfig.json 630 B
Loading…
-
-
fastapi-app
-
src
-
models
-
item.py 1 KB
Loading… -
user.py 922 B
Loading… -
__init__.py 278 B
Loading…
-
-
routes
-
health.py 470 B
Loading… -
items.py 1.9 KB
Loading… -
users.py 1.7 KB
Loading… -
__init__.py 110 B
Loading…
-
-
services
-
item_service.py 2.5 KB
Loading… -
user_service.py 2.1 KB
Loading… -
__init__.py 174 B
Loading…
-
-
AGENTS.md 2.9 KB
Loading… -
config.py 1.1 KB
Loading… -
main.py 1.7 KB
Loading… -
__init__.py 58 B
Loading…
-
-
.env.example 348 B · in bundle
-
AGENTS.md 3.2 KB
Loading… -
pyproject.toml 1.8 KB
Loading… -
uv.lock 136 B · in bundle
-
-
go-api-with-react-admin
-
admin
-
src
-
App.tsx 101 B · in bundle
-
-
package.json 423 B
Loading…
-
-
cmd
-
api
-
main.go 75 B · in bundle
-
-
-
.scopes 93 B · in bundle
-
AGENTS.md 3 KB
Loading… -
go.mod 31 B · in bundle
-
main.go 71 B · in bundle
-
-
go-with-internal-web-tsx
-
internal
-
web
-
src
-
App.tsx 57 B · in bundle
-
Button.tsx 63 B · in bundle
-
Footer.tsx 63 B · in bundle
-
Header.tsx 63 B · in bundle
-
Sidebar.tsx 65 B · in bundle
-
-
AGENTS.md 3.1 KB
Loading… -
package.json 329 B
Loading…
-
-
-
.scopes 102 B · in bundle
-
AGENTS.md 3.1 KB
Loading… -
go.mod 34 B · in bundle
-
main.go 85 B · in bundle
-
package-lock.json 87 B
Loading… -
package.json 221 B
Loading…
-
-
ldap-selfservice
-
AGENTS.md 2.5 KB
Loading… -
go.mod 45 B · in bundle
-
internal-AGENTS.md 10 KB
Loading… -
internal-web-AGENTS.md 12.1 KB
Loading…
-
-
php-with-frontend
-
src
-
Controller.php 41 B · in bundle
-
-
web
-
src
-
App.tsx 63 B · in bundle
-
Button.tsx 215 B · in bundle
-
Footer.tsx 125 B · in bundle
-
Header.tsx 122 B · in bundle
-
main.tsx 68 B · in bundle
-
-
AGENTS.md 3.1 KB
Loading… -
package.json 515 B
Loading… -
tsconfig.json 280 B
Loading…
-
-
.scopes 89 B · in bundle
-
AGENTS.md 3.1 KB
Loading… -
composer.json 185 B
Loading… -
package.json 307 B
Loading… -
pnpm-lock.yaml 101 B
Loading…
-
-
pnpm-workspace
-
packages
-
web
-
src
-
index.ts 258 B
Loading…
-
-
package.json 187 B
Loading…
-
-
-
AGENTS.md 2.6 KB
Loading… -
package.json 105 B
Loading… -
pnpm-lock.yaml 920 B
Loading… -
pnpm-workspace.yaml 27 B
Loading…
-
-
simple-ldap-go
-
AGENTS.md 2.5 KB
Loading… -
examples-AGENTS.md 1.8 KB
Loading… -
go.mod 43 B · in bundle
-
-
t3x-rte-ckeditor-image
-
AGENTS.md 2.5 KB
Loading… -
Classes-AGENTS.md 12 KB
Loading… -
composer.json 174 B
Loading…
-
-
-
ai-contribution-guidelines.md 2.6 KB
Loading… -
ai-tool-compatibility.md 8 KB
Loading… -
directory-coverage.md 2.5 KB
Loading… -
feedback-memory-schema.md 6.2 KB
Loading… -
fleet-sync-sweep.md 4.8 KB
Loading… -
git-hooks-setup.md 2.5 KB
Loading… -
output-structure.md 5.4 KB
Loading… -
quality-rubric.md 6.2 KB
Loading… -
scripts-guide.md 7.7 KB
Loading… -
verification-guide.md 9.4 KB
Loading…
-
-
scripts
-
lib
-
config-root.sh 5.8 KB
Loading… -
git.sh 1.2 KB
Loading… -
summary.sh 11.7 KB
Loading… -
template.sh 15.9 KB
Loading…
-
-
tests
-
test-agents-file-write-boundary.sh 5.8 KB
Loading… -
test-agents-scan-dependency-trees.sh 4.5 KB
Loading… -
test-changelog-rule.sh 3.4 KB
Loading… -
test-claude-import-file.sh 3.3 KB
Loading… -
test-command-allowlist.sh 4.7 KB
Loading… -
test-dependency-tree-exclusion.sh 2.5 KB
Loading… -
test-extract-commands-real-scripts.sh 4 KB
Loading… -
test-git-history-counts.sh 3.6 KB
Loading… -
test-golden-sample-file-names.sh 2.2 KB
Loading… -
test-json-manifest.sh 5.5 KB
Loading… -
test-last-verified-opt-in.sh 1.6 KB
Loading… -
test-make-target-lookup.sh 2.5 KB
Loading… -
test-merge-heuristic.sh 1.8 KB
Loading… -
test-scope-index-heading.sh 4.4 KB
Loading… -
test-scope-index-keeps-existing.sh 2.5 KB
Loading… -
test-symlink-write-boundary.sh 6.3 KB
Loading… -
test-untrusted-git-config.sh 5 KB
Loading… -
test-verification-sidecar.sh 2.7 KB
Loading…
-
-
analyze-git-history.sh 10.2 KB
Loading… -
check-freshness.sh 8.9 KB
Loading… -
detect-golden-samples.sh 5.7 KB
Loading… -
detect-heuristics.sh 3.2 KB
Loading… -
detect-project.sh 19.6 KB
Loading… -
detect-scopes.sh 13.4 KB
Loading… -
detect-utilities.sh 4.6 KB
Loading… -
extract-adrs.sh 6.8 KB
Loading… -
extract-agent-configs.sh 9.3 KB
Loading… -
extract-architecture-rules.sh 19.9 KB
Loading… -
extract-ci-commands.sh 12.5 KB
Loading… -
extract-ci-rules.sh 16.1 KB
Loading… -
extract-commands.sh 11.9 KB
Loading… -
extract-documentation.sh 7.8 KB
Loading… -
extract-github-rulesets.sh 3.8 KB
Loading… -
extract-github-settings.sh 3.6 KB
Loading… -
extract-ide-settings.sh 7 KB
Loading… -
extract-platform-files.sh 8 KB
Loading… -
extract-quality-configs.sh 14.9 KB
Loading… -
generate-agents.sh 118.2 KB
Loading… -
generate-file-map.sh 4.6 KB
Loading… -
score-agents.sh 9.8 KB
Loading… -
validate-structure.sh 13.3 KB
Loading… -
verify-commands.sh 32.5 KB
Loading… -
verify-content.sh 13.2 KB
Loading…
-
-
AGENTS.md 4 KB
Loading… -
checkpoints.yaml 14.4 KB
Loading… -
SKILL.md 5.2 KB
--- # SPDX-License-Identifier: CC-BY-SA-4.0 # SPDX-FileCopyrightText: Netresearch DTT GmbH name: agent-rules description: "Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents." license: "(MIT AND CC-BY-SA-4.0). See LICENSE-MIT and LICENSE-CC-BY-SA-4.0" compatibility: "Requires bash 4.3+, jq 1.7+, git 2.0+." metadata: author: Netresearch DTT GmbH version: "3.17.0" repository: https://github.com/netresearch/agent-rules-skill allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/*) Bash(bash ${CLAUDE_SKILL_DIR}/scripts/*) Bash(git:*) Bash(jq:*) Bash(grep:*) Bash(find:*) Read Glob Grep --- # AGENTS.md Generator Skill Generate and maintain AGENTS.md files following the [agents.md convention](https://agents.md/). 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 1. **Detect**: `detect-project.sh` + `detect-scopes.sh` — stacks and subsystems 2. **Extract**: `extract-commands.sh`, `extract-ci-rules.sh` — gather facts 3. **Generate**: `generate-agents.sh --style=thin` (default) or `--verbose` 4. **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) 5. **Line cap**: before committing any root AGENTS.md edit, `wc -l AGENTS.md` must be under 150 (harness `AH-02`); run the repo's `verify-harness.sh` where 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/ai-tool-compatibility.md)) ## References | File | Contents | |------|----------| | [`verification-guide.md`](references/verification-guide.md) | Verification steps, anti-bloat, preservation check | | [`fleet-sync-sweep.md`](references/fleet-sync-sweep.md) | Fleet-wide AGENTS.md sweeps | | [`scripts-guide.md`](references/scripts-guide.md) | Script options, validation checklist | | [`quality-rubric.md`](references/quality-rubric.md) | Grading rubric | | [`ai-tool-compatibility.md`](references/ai-tool-compatibility.md) | 16-agent compatibility matrix | | [`output-structure.md`](references/output-structure.md) | Root/scoped sections | | [`git-hooks-setup.md`](references/git-hooks-setup.md) | Hook framework setup | | [`examples/`](references/examples/) | Complete examples | | [`ai-contribution-guidelines.md`](references/ai-contribution-guidelines.md) | "3 Cs" AI-contribution framework | | [`directory-coverage.md`](references/directory-coverage.md) | Scoped-file coverage rationale | | [`feedback-memory-schema.md`](references/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`](https://github.com/netresearch/agent-harness-skill) — agent-readiness harness (CI enforcement). - [`skill-repo-skill`](https://github.com/netresearch/skill-repo-skill) — skill-repo structure (plugin.json, licensing, releases).
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.