105 lines
6.4 KiB
Markdown
105 lines
6.4 KiB
Markdown
---
|
|
name: agent-docs
|
|
description: 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.
|