split agent-docs skills

skills/agent-docs-audit/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: agent-docs-audit
+description: Use when auditing AGENTS.md or agent-docs without editing files, especially for instruction quality review, adherence-risk assessment, findings-first reports, or rationality critiques.
+---
+
+# Agent Docs Audit
+
+## Overview
+
+Use this skill for read-only assessment of AGENTS and `agent-docs`. The output should prioritize findings, evidence, residual risks, and adherence impact instead of proposing patches first.
+
+## When to Use
+
+- The user asks for a review, audit, rationality check, or instruction-adherence assessment
+- The user asks what remains wrong after a refactor
+- The user asks why agents still fail to follow the docs
+- The task is to list bugs, risks, or remaining problems before making changes
+
+Do not use this skill as the main workflow when the task is to edit files. Switch to `agent-docs-refactor` for that.
+
+## Workflow
+
+1. Read the root `AGENTS.md` and every active child doc in scope.
+2. Read `../agent-docs/references/audit-checklist.md`.
+3. Use `../agent-docs/references/refactor-checklist.md` as the structural baseline.
+4. Separate observed facts from inferences:
+   - observed facts: file contents, references, checklists, routing text, command output
+   - inferences: likely adherence impact, likely confusion points, likely maintenance risk
+5. Evaluate:
+   - routing clarity
+   - single authoritative rule ownership
+   - shape fitness: rule doc vs inventory doc
+   - instruction density and likely adherence load
+   - residual cycles or secondary-index behavior
+6. Report findings first, ordered by severity.
+
+## Reporting
+
+- Findings first
+- Then open questions or assumptions
+- Then an adherence assessment
+- Then any optional summary
+
+If no findings are discovered, state that explicitly and mention residual risks or coverage limits.