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.
checkpoints.yaml
View on GitHub# SPDX-License-Identifier: MIT
# SPDX-FileCopyrightText: Netresearch DTT GmbH
# Checkpoints for AGENTS.md verification
# Ensures AGENTS.md exists, has proper structure, and stays accurate
version: 1
skill_id: agents
mechanical:
# === FILE EXISTENCE ===
- id: AG-01
type: file_exists
target: AGENTS.md
severity: error
desc: "AGENTS.md must exist in repository root"
# === RECOMMENDED SECTIONS ===
# Note: The agents.md spec has NO required fields - these are best practices
#
# Accepted heading spellings come from two sources inside this skill and
# nowhere else: the equivalence table in scripts/validate-structure.sh
# (check_scoped_sections) and the headings the two root templates emit
# (assets/root-thin.md, assets/root-verbose.md). A spelling that is only
# plausible is a finding, not an equivalent.
- id: AG-02
type: regex
target: AGENTS.md
pattern: "^#+ (.*Overview|Project|About)"
severity: warning
desc: "AGENTS.md should have an Overview/Project section (recommended but not required)"
- id: AG-03
type: regex
target: AGENTS.md
# Setup group of check_scoped_sections: Setup|Environment|Prerequisites|
# Getting Started (its fifth member, "Workflow files", is a scoped
# github-actions section that no root file carries).
# "Development Workflow" removed: root-verbose.md:69 spells a branch/PR
# sequence under that heading, not environment setup. AG-06 owns it.
# "Dev Environment" removed for the same reason: neither the equivalence
# table nor a root template emits it, so it was a plausible-only spelling
# under a rule that admits none. Adding it to check_scoped_sections
# instead would loosen validate-structure.sh to make this pattern true.
pattern: "^#+ (Setup|Getting Started|Prerequisites|Environment)"
severity: warning
desc: "AGENTS.md should have Setup/Environment section (recommended but not required)"
- id: AG-04
type: regex
target: AGENTS.md
pattern: "^#+ (Commands|Available Commands|Useful Commands)"
severity: warning
desc: "AGENTS.md should have Commands section"
- id: AG-05
type: regex
target: AGENTS.md
pattern: "^#+ (Architecture|Structure|Project Structure)"
severity: warning
desc: "AGENTS.md should describe project architecture"
- id: AG-06
type: regex
target: AGENTS.md
# "Workflow" added: root-thin.md:30 emits "## Workflow" as the development
# workflow section, so the canonical thin output matched only via
# "Contributing". "PR/Commit Checklist" is deliberately NOT accepted here —
# check_scoped_sections keeps Checklist (PR|Commit|Checklist) as a group of
# its own, separate from any workflow section.
# Bare "Development" removed: no source emits it, and being an unanchored
# prefix it made "Development Workflow" redundant while accepting any
# heading that merely starts with "Development".
pattern: "^#+ (Development Workflow|Contributing|Workflow)"
severity: warning
desc: "AGENTS.md should have Development workflow section"
- id: AG-07
type: regex
target: AGENTS.md
# Build/Tests group of check_scoped_sections:
# Build|Tests|Running|Commands|Common patterns. "Commands" is where this
# skill's own root templates and the assessed TYPO3 extensions put the test
# commands, so a "## Commands" section satisfies this check. That makes
# AG-07 overlap AG-04 on such files — the same shape AG-13 already has
# against AG-04, and not this checkpoint's to resolve.
pattern: "^#+ (Testing|Tests|Running Tests|Commands)"
severity: warning
desc: "AGENTS.md should have Testing section"
# === FRESHNESS INDICATORS ===
- id: AG-08
type: regex
target: AGENTS.md
pattern: "(Last [Uu]pdated|Updated|Modified).*20[0-9]{2}"
severity: warning
desc: "AGENTS.md should have Last Updated date"
# === STRUCTURE QUALITY ===
- id: AG-09
type: regex
target: AGENTS.md
pattern: "^## "
severity: error
desc: "AGENTS.md must use proper markdown heading structure"
- id: AG-10
type: regex
target: AGENTS.md
pattern: "```(bash|shell|sh|yaml|json|php|typescript|javascript)"
severity: warning
desc: "AGENTS.md should include code blocks with language hints"
# === COMMAND DOCUMENTATION ===
- id: AG-11
type: regex
target: AGENTS.md
# Python tools added: a Python repository documents `uv run`, `uvx`,
# `pytest`, `python -m`, `ruff`, `tox` or `nox` and failed this check.
# The tool names must stand alone: not inside a word ("toxic", "equinox")
# and not as a config file name (`pytest.ini`, `tox.ini`, `ruff.toml`),
# while a sentence-ending "Run pytest." still counts. No lookahead, so the
# pattern runs under grep -P and the -E fallback alike.
pattern: '(composer|npm|make|ddev|docker|uv run|uvx|python3? -m|\b(pytest|ruff|tox|nox)([^.a-z]|\.([^a-z]|$)|$))'
severity: warning
desc: "AGENTS.md should document build/run commands"
# === AGENT-OPTIMIZED SECTIONS ===
- id: AG-13
type: regex
target: AGENTS.md
pattern: '^#+ Commands( \(verified[^)]*\))?'
severity: warning
desc: "AGENTS.md should have Commands section (optionally with '(verified)' or '(verified DATE)' suffix for trust scoring)"
- id: AG-14
type: regex
target: AGENTS.md
pattern: "^#+ File Map"
severity: info
desc: "AGENTS.md should have File Map for navigation efficiency"
- id: AG-15
type: regex
target: AGENTS.md
pattern: "^#+ (Golden Samples|Canonical Patterns)"
severity: info
desc: "AGENTS.md should have Golden Samples to reduce pattern guessing"
- id: AG-16
type: regex
target: AGENTS.md
pattern: "^#+ (Utilities|Shared Utilities|Don't Reinvent)"
severity: info
desc: "AGENTS.md should list utilities to prevent duplicate code"
- id: AG-17
type: regex
target: AGENTS.md
pattern: "^#+ (Heuristics|Quick Decisions|Decision Rules)"
severity: info
desc: "AGENTS.md should have Heuristics for autonomous decisions"
- id: AG-18
type: regex
target: AGENTS.md
pattern: "Last verified.*20[0-9]{2}"
severity: info
desc: "AGENTS.md should have 'Last verified' timestamp for trust scoring"
# === OUTPUT QUALITY ===
- id: AG-19
type: regex_not
target: AGENTS.md
pattern: "\\{\\{[A-Z][A-Z0-9_]*\\}\\}"
severity: error
desc: "AGENTS.md must not contain unresolved placeholders like {{PLACEHOLDER}}"
- id: AG-20
type: regex_not
target: AGENTS.md
pattern: "\\{\\{[A-Z_]+\\}\\}"
severity: error
desc: "AGENTS.md has unresolved template placeholders - regenerate or fix template"
# === IMPORTANT CONTEXT ===
- id: AG-12
type: regex
target: AGENTS.md
# "Boundaries" added: it is this skill's canonical name for the section
# (assets/root-thin.md:80, assets/root-verbose.md:28, and the Root File
# table in references/output-structure.md — "Boundaries | Always/Ask/Never
# rules"). Without it the check failed against both of the skill's own root
# templates while no template ever emits any of the six original spellings.
pattern: "^#+ (Critical|Constraints|Critical Constraints|Important|Caveats|Warnings|Boundaries)"
severity: info
desc: "AGENTS.md should have Critical/Constraints section for important warnings"
# === CHANGELOG ===
- id: AG-32
type: regex
target: AGENTS.md
# Either a "## Changelog" section or a "**Changelog:**" bullet: the root
# templates emit the bullet under Always Do, and a root AGENTS.md at the
# 150-line cap (AH-02) has no room for a section of its own.
pattern: "(^#+ Changelog|\\*\\*Changelog)"
severity: error
desc: "AGENTS.md must say where changes are recorded (a Changelog section or a **Changelog:** entry)"
# === POINTER PRINCIPLE ===
- id: AG-26
type: regex
target: AGENTS.md
pattern: "(see |refer to |defined in |located at )[`/]"
severity: info
desc: "AGENTS.md should point to files rather than duplicating content (Pointer Principle)"
# === LANGUAGE ===
- id: AG-27
type: regex
target: AGENTS.md
pattern: "^# "
severity: error
desc: "AGENTS.md must have a top-level heading in English (default language)"
# === GIT HOOKS ===
- id: AG-29
type: command
# Was type "file_exists_any" with a "paths:" list. Neither is a runner type
# nor a runner key, so the runner reported this checkpoint as SKIPPED
# ("Unknown checkpoint type") on every project and it never measured
# anything. The same five markers as one allowlisted `test`. The four
# frameworks are those in references/git-hooks-setup.md, and the husky
# marker is the `.husky/` directory named in that doc's table (line 18).
# Requiring `.husky/pre-commit` warned at every repo that runs Husky for
# another hook, commit-msg only being the common one. Which hooks a
# framework installs and what they cover is AG-30's question, not this
# one's — the same reason an empty lefthook.yml satisfies this check.
pattern: "test -f lefthook.yml -o -f .lefthook.yml -o -f captainhook.json -o -d .husky -o -f .pre-commit-config.yaml"
severity: warning
desc: "Repository should have a git hooks framework configured (lefthook, captainhook, husky or pre-commit)"
# === CLAUDE CODE COMPATIBILITY ===
- id: AG-31
type: script
severity: warning
desc: "CLAUDE.md must exist when Claude Code environment detected (.claude/ directory present)"
# Was type "conditional" with "check_command:" — neither is read by the
# runner, so this reported SKIPPED everywhere. The old body was also
# inverted: `test -d .claude && test -f CLAUDE.md` FAILS when .claude/ is
# absent, which is exactly when the rule does not apply. An `if` with no
# else exits 0 in that case, so a repo without .claude/ passes.
command: |
if test -d .claude
then
test -f CLAUDE.md
fi
tags: [claude-code, compatibility]
# === SCOPED AGENTS.MD ===
- id: AG-28
type: regex
target: AGENTS.md
pattern: "\\|.*\\|"
severity: info
desc: "AGENTS.md should use tables for structured data (Structured over Prose principle)"
llm_reviews:
# === ACCURACY VERIFICATION ===
- id: AG-25
domain: repo-health
prompt: |
Verify that AGENTS.md accurately describes the actual project:
1. Check if mentioned files/directories actually exist
2. Verify mentioned commands work (check package.json scripts, composer.json scripts, Makefile targets)
3. Confirm the architecture description matches the actual codebase structure
4. Check for outdated version numbers or deprecated patterns
Report specific inaccuracies with file paths and line numbers.
severity: error
desc: "AGENTS.md content must match actual codebase"
- id: AG-21
domain: repo-health
prompt: |
Verify the Commands section is accurate:
1. Cross-reference with package.json "scripts", composer.json "scripts", or Makefile
2. Check that documented test commands exist
3. Verify build/install commands are correct
4. Look for undocumented important commands
List any commands that are documented but don't exist, or important commands that aren't documented.
severity: warning
desc: "Commands section must match actual available commands"
- id: AG-22
domain: repo-health
prompt: |
Check AGENTS.md for staleness indicators:
1. Are version numbers current? (PHP versions, Node versions, etc.)
2. Do mentioned dependencies match package.json/composer.json?
3. Are CI/CD references up to date with actual workflow files?
4. Is the "Last Updated" date recent (within last 3 months)?
Report any outdated information with specific details.
severity: warning
desc: "AGENTS.md should be kept current with codebase changes"
- id: AG-23
domain: repo-health
prompt: |
Evaluate AGENTS.md completeness for AI agent usage:
1. Does it explain the project purpose clearly?
2. Does it describe key entry points for understanding the code?
3. Are there warnings about gotchas or non-obvious behavior?
4. Does it explain test conventions and how to run tests?
5. Does it mention important environment variables?
Rate completeness and list missing information that would help an AI agent.
severity: info
desc: "AGENTS.md should provide comprehensive context for AI agents"
- id: AG-24
domain: repo-health
prompt: |
Check for drift between AGENTS.md and other documentation:
1. Compare with README.md - are they consistent?
2. Check against CONTRIBUTING.md if it exists
3. Verify consistency with inline code documentation
4. Look for contradictions between AGENTS.md and actual configs
Report any inconsistencies or contradictions found.
severity: warning
desc: "AGENTS.md must be consistent with other documentation"
- id: AG-33
domain: repo-health
prompt: |
Check the Changelog entry of the root AGENTS.md against the repository:
1. Does it name the file or page where changes are recorded (CHANGELOG.md, a changelog.d/ fragment directory, a Documentation changelog page, or the release notes when there is no file)?
2. Does it name the format (heading shape, sections) and link the fragment directory's README if one exists?
3. Does it say which pull request writes the entry (each feature/fix PR, or the release PR)? Compare with the last 20-40 merged PRs: which of them changed the changelog files?
4. Is a "TODO" left from generation?
Report each missing or contradicted point with the evidence (PR numbers, file paths).
severity: warning
desc: "The AGENTS.md Changelog entry must name the file, the format and who writes the entry, as recent merged PRs show it"
- id: AG-30
domain: repo-health
prompt: |
Check if git hooks are properly configured and cover key quality gates:
1. Is a hook framework present (lefthook.yml, captainhook.json, .husky/, .pre-commit-config.yaml)?
2. Do hooks cover at minimum: linting/formatting and commit message validation?
3. Are hook configs consistent with CI checks (e.g., same linters run locally and in CI)?
4. If no hooks exist, flag this as a gap and recommend adding them.
Report which hooks are configured, what they cover, and any gaps.
severity: warning
desc: "Repository should have git hooks covering linting, formatting, and commit validation"
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: 470k | 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: 197k | 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: 197k | 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: 197k | Updated | Claude CodeCodex | Verified | Install |