netresearch/agent-rules-skill / skills/agent-rules
agent-rules
FlaggedUse 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.
references/scripts-guide.md
View on GitHub<!-- SPDX-License-Identifier: CC-BY-SA-4.0 -->
<!-- SPDX-FileCopyrightText: Netresearch DTT GmbH -->
# Scripts Guide
Complete reference for all AGENTS.md generator scripts.
## Generating AGENTS.md Files
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/generate-agents.sh /path/to/project
```
Options:
- `--dry-run` - Preview changes without writing files
- `--json` - Emit the write manifest as JSON instead of prose (see below)
- `--verbose` - Show detailed output
- `--style=thin` - Use thin root template (~30 lines, default)
- `--style=verbose` - Use verbose root template (~100-200 lines)
- `--update` - Update existing files only (preserves human edits outside generated markers)
- `--claude-shim` - Generate CLAUDE.md that imports AGENTS.md (root only, legacy)
- `--no-symlinks` - Do not create CLAUDE.md/GEMINI.md at any level. They are created by default at every level where an AGENTS.md is generated, which is what enables Claude Code on-demand loading and Gemini CLI native loading.
- `--force` - Replace existing CLAUDE.md/GEMINI.md files that are not ours
### Write manifest (`--json`)
One entry per path the run touches, following the `schema: 1` shape the verifier
scripts use. With `--dry-run` it is a plan of what would be written; without it, a
receipt of what was. Paths are relative to the project root.
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/generate-agents.sh /path/to/project --dry-run --json
```
```json
{
"script": "generate-agents",
"schema": 1,
"dry_run": true,
"project": "/path/to/project",
"summary": { "write": 1, "symlink": 1, "keep": 1 },
"operations": [
{ "op": "write", "kind": "agents-file", "path": "AGENTS.md" },
{ "op": "symlink", "kind": "compat-file", "path": "CLAUDE.md", "target": "AGENTS.md" },
{ "op": "keep", "kind": "compat-file", "path": "GEMINI.md", "reason": "regular file" }
]
}
```
`op` is `write`, `symlink` or `keep`; `keep` means an existing file was left alone
and carries the reason. Human output is suppressed under `--json`, so stdout is
parseable on its own.
## Validating Structure
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/validate-structure.sh /path/to/project
```
Options:
- `--check-freshness, -f` - Also check if files are up to date with git commits
- `--verbose, -v` - Show detailed output
## Checking Freshness
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/check-freshness.sh /path/to/project
```
This script:
- Extracts the "Last updated" date from the AGENTS.md header
- Checks git commits since that date for files in the relevant scope
- Reports if there are commits that might require AGENTS.md updates
Options:
- `--verbose, -v` - Show commit details and changed files
- `--threshold=DAYS` - Days threshold to consider stale (default: 7)
Example with full validation:
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/validate-structure.sh /path/to/project --check-freshness --verbose
```
## Detecting Project Type
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/detect-project.sh /path/to/project
```
Detects project language, version, and build tools.
## Detecting Scopes
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/detect-scopes.sh /path/to/project
```
Identifies directories that should have scoped AGENTS.md files.
## Extracting Commands
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-commands.sh /path/to/project
```
Extracts build commands from Makefile, package.json, composer.json, or go.mod.
## Extracting Documentation
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-documentation.sh /path/to/project
```
Extracts information from README.md, CONTRIBUTING.md, SECURITY.md, and other documentation.
## Extracting Platform Files
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-platform-files.sh /path/to/project
```
Extracts information from .github/, .gitlab/, CODEOWNERS, dependabot.yml, etc.
## Extracting IDE Settings
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-ide-settings.sh /path/to/project
```
Extracts information from .editorconfig, .vscode/, .idea/, etc.
## Extracting AI Agent Configs
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/extract-agent-configs.sh /path/to/project
```
Extracts information from .cursor/, .claude/, copilot-instructions.md, etc.
## Verifying Content Accuracy
**CRITICAL: Always run this before considering AGENTS.md files complete.**
```bash
bash ${CLAUDE_SKILL_DIR}/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):
```bash
bash ${CLAUDE_SKILL_DIR}/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
- With `--update-verified`, records the date in the "Last verified" marker of AGENTS.md on success; without it, AGENTS.md is not changed
Options:
- `VERBOSE=true` - Show detailed output
- `DRY_RUN=true` - Don't write the results file or the `--update-verified` date
**Why this matters:** Research shows broken commands waste 500+ tokens as agents debug non-existent commands. Verified commands enable confident execution.
## Scoring Quality
```bash
bash ${CLAUDE_SKILL_DIR}/scripts/score-agents.sh /path/to/project # human report, worst-first
bash ${CLAUDE_SKILL_DIR}/scripts/score-agents.sh /path/to/project --json # machine-readable scoring
```
Aggregates the `--json` output of the four verifier scripts into a **reproducible**
0-100 grade per AGENTS.md file (A-F), ranked worst-first so you know where to spend
effort. Same tree → same grade (no model call; CI-friendly).
Axes: Structure 25 · Currency 20 · Content 20 · Commands 15 (root) · Conciseness 20.
Scoped files have no Commands axis and normalise over the remaining 85.
The four verifiers each gained a `--json` mode (strictly additive — default output
is unchanged). For the qualitative LLM overlay (Architecture / Actionability /
Non-obvious patterns), which is deliberately **not** part of the deterministic
number, see [`quality-rubric.md`](quality-rubric.md).
> Note: `score-agents.sh` grades whatever `validate-structure.sh` lists, which does
> not honour `.gitignore` (it will include generated/vendored AGENTS.md under the
> tree). Point it at a clean project root, or exclude such trees, for a clean grade.
## Post-Generation Validation Checklist
**After generating AGENTS.md files, ALWAYS validate the output:**
```bash
# 1. Run structure validation
bash ${CLAUDE_SKILL_DIR}/scripts/validate-structure.sh /path/to/project --verbose
# 2. Verify content accuracy
bash ${CLAUDE_SKILL_DIR}/scripts/verify-content.sh /path/to/project
# 3. Verify commands work
bash ${CLAUDE_SKILL_DIR}/scripts/verify-commands.sh /path/to/project
```
**Validation criteria:**
| Check | Pass Criteria | Common Issues |
|-------|---------------|---------------|
| **Thin root** | Root AGENTS.md <= 80 lines | Duplicated scope content in root |
| **All scopes covered** | Every major directory has AGENTS.md | Missing `Tests/`, `Configuration/` |
| **No duplication** | Content appears in ONE location | Commands duplicated in root + scope |
| **Commands verified** | All documented commands execute | Typos, renamed targets |
| **Files exist** | All referenced files are real | Hallucinated paths |
| **Links valid** | All cross-references resolve | Broken relative paths |
**Never consider generation complete until all checks pass.**
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |