bluecraft/skills/agent-docs/SKILL.md

name, description

name	description
agent-docs	Use when a task involves AGENTS.md or agent-docs and you need to choose the correct specialized workflow for auditing, refactoring, consistency checks, repo alignment, or verification.

Agent Docs

Overview

Use this skill as the entrypoint for AGENTS.md and agent-docs/ work. It routes the task to the narrowest specialized skill and points to the shared templates and checklists under references/.

Treat covered files as required instructions. If one applies in scope, it must be followed, not treated as optional background reading.

When to Use

• The user asks to create, update, split, merge, delete, or refactor AGENTS.md or agent-docs/
• The user asks whether the instruction tree is rational, consistent, or easy for agents to follow
• The user asks whether agent docs match repository reality
• The user asks for post-change validation of AGENTS or agent-docs

Do not use this skill as the main workflow when the task is already clearly one of the specialized categories below. Switch directly to the matching skill. Do not use it for end-user documentation, product manuals, or README content that is not part of AGENTS or agent-docs.

Quick Triage

1. Identify the concrete scope first:
   • root AGENTS.md only
   • one or more child docs under agent-docs/
   • both root and child docs
   • documentation-tree refactor
2. Then choose the narrowest workflow:
   • read-only rationality or adherence review
   • structural graph or authority inspection
   • repository-fact comparison
   • document editing with follow-up checks

Routing

• Use agent-docs-audit when the task is read-only evaluation: rationality review, instruction-adherence assessment, problem listing, or findings-first reporting.
• Use agent-docs-refactor when the task requires editing files: create, split, merge, reroute, rename, delete, or rewrite AGENTS.md or agent-docs.
• Use agent-docs-consistency when the task is structural inspection: reachability, cycles, depth, duplicate authority, or rule-doc vs inventory-doc shape checks.
• Use agent-docs-repo-alignment when the task asks whether AGENTS or agent-docs match repository facts such as scripts, ports, directories, DTO ownership, or runtime behavior.
• Use agent-docs-verification when the task is to validate a completed doc change and summarize the verification evidence.
• After agent-docs-refactor, also use agent-docs-consistency when routing, authority ownership, reference depth, or document shape changed.
• After agent-docs-refactor, also use agent-docs-repo-alignment when the edited docs make claims about repository facts or when stale wording may depend on current code, config, or commands.
• Finish edited work with agent-docs-verification. Verification is the completion gate, not a substitute for structural or repo-fact review.

Conflict Resolution

• Prefer the most specific applicable document over a broader one.
• Prefer a child doc's scoped rule over a general reminder in the root file.
• Prefer a document with explicit Applies To coverage over background wording that only mentions the topic indirectly.
• Prefer rule-doc behavior constraints over inventory entry wording when both mention the same topic.
• If two active docs both appear to own the same rule, treat that as duplicate authority and route to agent-docs-consistency or agent-docs-refactor instead of guessing.
• If two active docs are equally specific and both explicitly apply, treat that as unresolved duplicate authority and report the ambiguity instead of choosing one.

Which Reference To Read

• Root AGENTS.md update: read references/root-agents-template.md.
• Child rule or policy doc: read references/rule-doc-template.md.
• Child inventory or registry doc: read references/inventory-doc-template.md.
• Unsure whether a child doc is a rule doc or inventory doc: read references/child-doc-template.md.
• Cross-reference or document-tree change: read references/linking-patterns.md.

Shared References

Read only the files needed for the current task.

• Root doc template: references/root-agents-template.md
• Rule doc template: references/rule-doc-template.md
• Inventory doc template: references/inventory-doc-template.md
• Child doc chooser: references/child-doc-template.md
• Linking patterns: references/linking-patterns.md
• Refactor checklist: references/refactor-checklist.md
• Audit checklist: references/audit-checklist.md
• Consistency checklist: references/consistency-checklist.md
• Repo-alignment checklist: references/repo-alignment-checklist.md
• Verification checklist: references/verification-checklist.md
• Skill-maintenance checklist: references/skill-maintenance-checklist.md
• Severity model: references/severity-model.md
• Report format: references/report-format.md
• Behavior check template: references/behavior-check-template.md

Shared Tool

• Validation script: scripts/validate_agent_docs.py

Shared Constraints

• Treat the root AGENTS.md as the starting point for required agent-docs.
• Keep one authoritative home for each rule.
• Keep repository-wide rules in the root file and topic-specific rules in child docs.
• In monorepos, keep common constraints in the root file and put subproject-specific rules in the relevant nearby docs.
• Match document shape to job: use rule docs for policy and inventory docs for maintained classifications or registries.
• Remove stale references and obsolete files in the same change when restructuring the tree.
• Write for maintainers. State actions, constraints, and decision criteria directly.
• Rules should be actionable, not slogan-like.
• Prefer standard Markdown headings and lists over wrapper tags for structure.
• Keep the root focused on the next reading decision and list only the child docs that are actually needed.
• Keep references directional and explicit: parent docs point to the child docs that refine them.
• Prefer stable, semantic filenames and direct titles that state purpose.
• When referencing repository files from AGENTS or agent-docs, use repository-relative paths in backticks, not Markdown links or machine-local absolute paths.
• Do not mix general agent-doc governance with project-specific business rules, product manuals, media planning, or end-user documentation in the same general-purpose document.
• Unless a document explicitly says otherwise, treat paths as relative to the root of the current Git worktree.