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:
- Glob for
skills/**/SKILL.md
- Parse frontmatter from each
- 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.
2d. Progressive Disclosure Check
For every skill:
- SKILL.md body line count
- Number of reference files
- Are references linked from body?
- Any body >500 lines? (flag)
- Any reference >300 lines without TOC? (flag)
2e. Cross-Skill Consistency
Check for ecosystem-level issues:
composes_with references that point to non-existent skills
spawned_by references that point to non-existent skills
- Circular
composes_with chains (A→B→A)
- Skills declaring
requires_agent_teams: true that don't degrade gracefully
- Orphan reference files (exist but aren't linked from any SKILL.md)
2f. Coverage Gap Analysis
Compare the skill inventory against the project's canonical documentation (docs/architecture.md, CLAUDE.md, and the orchestrator's File Ownership Map):
- Are all roles described in the architecture doc implemented as skills?
- Are all workflows the project depends on covered?
- Any capabilities the orchestrator's playbook references but no skill exists for?
Phase 3: Generate Audit Report
Produce a structured markdown report:
# Skill Ecosystem Audit Report
Audited: [timestamp]
Scope: [all / filtered description]
Skills scanned: [count]
## Executive Summary
- Total skills: X
- Passing: X (X%)
- Issues found: X (X critical, X high, X medium, X low)
- Ownership conflicts: X
## Skill Inventory
| Skill | Category | Version | Desc Length | Body Lines | Refs | Status |
|-------|----------|---------|------------|------------|------|--------|
## Ownership Map
[Visual or tabular representation of which agent owns what]
### Conflicts
[Any overlaps detected]
## Description Quality Ranking
| Rank | Skill | Score | Issues |
|------|-------|-------|--------|
[Weakest first]
## Bulk Issues
### Frontmatter Violations
| Skill | Field | Issue |
|-------|-------|-------|
### Progressive Disclosure Violations
| Skill | Body Lines | Issue |
|-------|-----------|-------|
### Cross-Skill Issues
| Issue Type | Skills Involved | Description |
|-----------|-----------------|-------------|
## Coverage Gaps
[Capabilities referenced in `docs/architecture.md`, `CLAUDE.md`, or orchestrator phase-guide that no existing skill covers]
## Recommendations
[Top 5 highest-impact improvements, ordered by priority]
## Per-Skill Scores
| Skill | Frontmatter | Description | Disclosure | Consistency | Overall |
|-------|-------------|-------------|------------|-------------|---------|
[Quick scores for each skill — details available via skill-deep-review]
Phase 4: Triage
After generating the report:
- Highlight the top 3–5 most impactful issues
- Suggest which skills would benefit from a skill-deep-review for further investigation
- Note any issues that skill-improvement-plan could address directly
Tell the user:
"Audit complete. [X] issues found across [Y] skills. The top priorities are [brief list]. Feed this report into /skill-improvement-plan to generate fix plans, or use /skill-deep-review on [specific skills] for deeper investigation."
Guidelines
- Optimize for speed — this is a broad scan, not a deep dive. Score quickly, flag issues, move on.
- Use subagents to parallelize check categories when available
- Don't read reference file contents unless checking for specific issues (orphans, broken links) — frontmatter + body line count is enough for most checks
- Focus on ecosystem-level patterns that individual reviews miss: conflicts, inconsistencies, gaps
- If scope is filtered, still check cross-skill references against the full inventory
Reference Files
references/audit-checklist.md — Quick-reference checklist for all bulk checks
1---2name: skill-audit3version: 1.2.04description: |5 Scan all skills (or a filtered subset) for consistency, quality issues, gaps, and ownership conflicts in bulk. Use this skill when auditing the full skill ecosystem, running a broad quality scan, checking for ownership overlaps across agents, finding inconsistencies between skills, doing a "health check" on all skills, or when someone says "audit skills", "scan all skills", "skill ecosystem health", "bulk review", or "what needs fixing". Not for single-skill deep dives — use skill-deep-review for that.6requires_agent_teams: false7requires_claude_code: true8min_plan: starter9owns:10 directories: []11 patterns: []12 shared_read: ["skills/"]13allowed_tools: ["Read", "Grep", "Glob", "Bash", "Agent"]14composes_with: ["skill-deep-review", "skill-improvement-plan", "skill-writer"]15spawned_by: []16metadata:17 source: https://skillmd.com/skills/ivy00johns/skill-audit18---1920# Skill Audit2122Broad scan across all skills (or a filtered subset) to surface consistency issues, quality gaps, ownership conflicts, and ecosystem-level problems that individual reviews miss.2324## When to Use2526- Periodic health check on the skill ecosystem27- After bulk edits or a new batch of skills is added28- Before a release to validate ecosystem integrity29- Investigating systemic issues (e.g., "why do none of my skills trigger?")3031## Inputs3233- **Scope** — `all` (default), or a filter: category (`roles`, `meta`, `contracts`, `workflows`, `orchestrator`), or a list of specific skill names34- **Focus (optional)** — narrow the audit to specific checks (e.g., "just ownership", "just descriptions")3536## Process3738### Phase 1: Discovery3940Enumerate all skills in scope:41421. Glob for `skills/**/SKILL.md`432. Parse frontmatter from each443. Build a skill inventory table:4546```markdown47| Skill | Category | Version | Description Length | Body Lines | Refs Count |48```4950### Phase 2: Bulk Checks5152Run these checks across all skills in scope. Use subagents to parallelize where possible — each check category can run independently.5354#### 2a. Frontmatter Consistency5556For every skill:57- Required fields present (`name`, `version`, `description`)58- Version is valid semver59- Name matches directory name60- Description starts with action verb61- Description length vs 200-char target6263Produce a table of violations.6465#### 2b. Ownership Conflict Detection6667For agent role skills only:68- Collect all `owns.directories` declarations69- Collect all `owns.patterns` declarations70- Check for overlaps (two agents claiming the same directory)71- Validate against the v1.1 resolved conflicts table in `frontmatter-spec.md`72- Flag any new conflicts7374Produce a conflict map.7576#### 2c. Description Quality Scoring7778For every skill:79- Has action verb? (boolean)80- Has ≥3 trigger contexts? (count)81- Has keyword variants? (boolean)82- States exclusions if ambiguous? (boolean)83- Estimated "pushiness" (low/medium/high)8485Produce a ranked list from weakest to strongest descriptions.8687#### 2d. Progressive Disclosure Check8889For every skill:90- SKILL.md body line count91- Number of reference files92- Are references linked from body?93- Any body >500 lines? (flag)94- Any reference >300 lines without TOC? (flag)9596#### 2e. Cross-Skill Consistency9798Check for ecosystem-level issues:99- `composes_with` references that point to non-existent skills100- `spawned_by` references that point to non-existent skills101- Circular `composes_with` chains (A→B→A)102- Skills declaring `requires_agent_teams: true` that don't degrade gracefully103- Orphan reference files (exist but aren't linked from any SKILL.md)104105#### 2f. Coverage Gap Analysis106107Compare the skill inventory against the project's canonical documentation (`docs/architecture.md`, `CLAUDE.md`, and the orchestrator's File Ownership Map):108- Are all roles described in the architecture doc implemented as skills?109- Are all workflows the project depends on covered?110- Any capabilities the orchestrator's playbook references but no skill exists for?111112### Phase 3: Generate Audit Report113114Produce a structured markdown report:115116```markdown117# Skill Ecosystem Audit Report118Audited: [timestamp]119Scope: [all / filtered description]120Skills scanned: [count]121122## Executive Summary123- Total skills: X124- Passing: X (X%)125- Issues found: X (X critical, X high, X medium, X low)126- Ownership conflicts: X127128## Skill Inventory129| Skill | Category | Version | Desc Length | Body Lines | Refs | Status |130|-------|----------|---------|------------|------------|------|--------|131132## Ownership Map133[Visual or tabular representation of which agent owns what]134135### Conflicts136[Any overlaps detected]137138## Description Quality Ranking139| Rank | Skill | Score | Issues |140|------|-------|-------|--------|141[Weakest first]142143## Bulk Issues144145### Frontmatter Violations146| Skill | Field | Issue |147|-------|-------|-------|148149### Progressive Disclosure Violations150| Skill | Body Lines | Issue |151|-------|-----------|-------|152153### Cross-Skill Issues154| Issue Type | Skills Involved | Description |155|-----------|-----------------|-------------|156157## Coverage Gaps158[Capabilities referenced in `docs/architecture.md`, `CLAUDE.md`, or orchestrator phase-guide that no existing skill covers]159160## Recommendations161[Top 5 highest-impact improvements, ordered by priority]162163## Per-Skill Scores164| Skill | Frontmatter | Description | Disclosure | Consistency | Overall |165|-------|-------------|-------------|------------|-------------|---------|166[Quick scores for each skill — details available via skill-deep-review]167```168169### Phase 4: Triage170171After generating the report:1721731. Highlight the top 3–5 most impactful issues1742. Suggest which skills would benefit from a **skill-deep-review** for further investigation1753. Note any issues that **skill-improvement-plan** could address directly176177Tell the user:178179> "Audit complete. [X] issues found across [Y] skills. The top priorities are [brief list]. Feed this report into `/skill-improvement-plan` to generate fix plans, or use `/skill-deep-review` on [specific skills] for deeper investigation."180181## Guidelines182183- Optimize for speed — this is a broad scan, not a deep dive. Score quickly, flag issues, move on.184- Use subagents to parallelize check categories when available185- Don't read reference file contents unless checking for specific issues (orphans, broken links) — frontmatter + body line count is enough for most checks186- Focus on ecosystem-level patterns that individual reviews miss: conflicts, inconsistencies, gaps187- If scope is filtered, still check cross-skill references against the full inventory188189## Reference Files190191- `references/audit-checklist.md` — Quick-reference checklist for all bulk checks