skill-audit

Skill Audit

Broad scan across all skills (or a filtered subset) to surface consistency issues, quality gaps, ownership conflicts, and ecosystem-level problems that individual reviews miss.

When to Use

• Periodic health check on the skill ecosystem
• After bulk edits or a new batch of skills is added
• Before a release to validate ecosystem integrity
• Investigating systemic issues (e.g., "why do none of my skills trigger?")

Inputs

• Scope — all (default), or a filter: category (roles, meta, contracts, workflows, orchestrator), or a list of specific skill names
• Focus (optional) — narrow the audit to specific checks (e.g., "just ownership", "just descriptions")

Process

Phase 1: Discovery

Enumerate all skills in scope:

1. Glob for skills/**/SKILL.md
2. Parse frontmatter from each
3. Build a skill inventory table:

| Skill | Category | Version | Description Length | Body Lines | Refs Count |

Phase 2: Bulk Checks

Run these checks across all skills in scope. Use subagents to parallelize where possible — each check category can run independently.

2a. Frontmatter Consistency

For every skill:

• Required fields present (name, version, description)
• Version is valid semver
• Name matches directory name
• Description starts with action verb
• Description length vs 200-char target

Produce a table of violations.

2b. Ownership Conflict Detection

For agent role skills only:

• Collect all owns.directories declarations
• Collect all owns.patterns declarations
• Check for overlaps (two agents claiming the same directory)
• Validate against the v1.1 resolved conflicts table in frontmatter-spec.md
• Flag any new conflicts

Produce a conflict map.

2c. Description Quality Scoring

For every skill:

• Has action verb? (boolean)
• Has ≥3 trigger contexts? (count)
• Has keyword variants? (boolean)
• States exclusions if ambiguous? (boolean)
• Estimated "pushiness" (low/medium/high)

Produce a ranked list from weakest to strongest descriptions.