dirien/yet-another-agent-harness / .claude/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# 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
- 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
pattern: "^#+ (Setup|Getting Started|Prerequisites|Dev Environment|Development Workflow)"
severity: warning
desc: "AGENTS.md should have Setup/Dev 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
pattern: "^#+ (Development|Development Workflow|Contributing)"
severity: warning
desc: "AGENTS.md should have Development workflow section"
- id: AG-07
type: regex
target: AGENTS.md
pattern: "^#+ (Testing|Tests|Running Tests)"
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
pattern: "(composer|npm|make|ddev|docker)"
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
pattern: "^#+ (Critical|Constraints|Critical Constraints|Important|Caveats|Warnings)"
severity: info
desc: "AGENTS.md should have Critical/Constraints section for important warnings"
# === 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: file_exists_any
paths:
- lefthook.yml
- .lefthook.yml
- captainhook.json
- .husky/pre-commit
- .pre-commit-config.yaml
severity: warning
desc: "Repository should have a git hooks framework configured"
# === CLAUDE CODE COMPATIBILITY ===
- id: AG-31
type: conditional
severity: warning
desc: "CLAUDE.md must exist when Claude Code environment detected (.claude/ directory present)"
check_command: "test -d .claude && test -f CLAUDE.md"
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-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: 471k | 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: 198k | 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: 198k | 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: 198k | Updated | Claude CodeCodex | Verified | Install |