docs-audit

Docs Audit

Audit skills, commands, and agents in this repository against the canonical standards defined in docs/. Reads docs/audit-checklists.md as the single source of truth for check criteria, cross-references docs/best-practices.md for evaluation context, and docs/templates.md for valid frontmatter fields and structural patterns.

Produces a markdown report — not an interactive walkthrough. For interactive per-issue resolution, use the artifact-toolkit audit skills instead.

Input

$ARGUMENTS — one of:

• Single path: path to a SKILL.md, agent .md, or command .md file
• --all: audit every skill, agent, and command across all plugins
• --type skill|command|agent: audit all artifacts of one type
• --severity critical|warning|info (optional, combinable): filter report to show only findings at or above this severity (default: show all)

Process

Phase 1: Load Documentation

Read these three files from the project root. These are the authoritative references for all checks:

1. docs/audit-checklists.md — checklist tables with check IDs and severity levels
2. docs/best-practices.md — authoring standards, decision guides, naming conventions, quality criteria
3. docs/templates.md — canonical frontmatter field references, structural templates, string substitution reference

Parse and retain all three in context. Every check evaluation must trace back to specific criteria from these documents.

Phase 2: Identify Targets

Parse $ARGUMENTS to determine audit mode and targets.

Mode detection:

• If arguments contain --all: batch mode, all types
• If arguments contain --type skill: batch mode, skills only
• If arguments contain --type command: batch mode, commands only
• If arguments contain --type agent: batch mode, agents only
• Otherwise: single-artifact mode using the provided path

Severity filter:

• If --severity critical: report only 🔴 CRITICAL findings
• If --severity warning: report 🔴 CRITICAL and 🟡 WARNING findings
• If --severity info or omitted: report all findings