/health:skill-audit
Produce triageable evidence for skill-to-skill quality: overlap clusters, split-pressure inside a skill body, and consolidation candidates. The analyzer reports only — every recommendation is editorial.
Complements the other skill audits — this skill assumes frontmatter hygiene is already green.
When to Use This Skill
| Use this skill when... | Use another approach when... |
|---|---|
| Finding overlapping skills ambiguous to an invoking agent | Frontmatter / size / body corruption (use scripts/plugin-compliance-check.sh) |
| Scoring split-pressure in an oversized skill body | Missing "Use when…" triggers (use scripts/audit-skill-descriptions.py) |
| Locating name-prefix or name-suffix clusters | CLI-flag compactness (use /health:check --scope=agentic) |
| Surfacing small sibling skills that could merge | Plugin ↔ stack relevance (use /health:check --scope=stack) |
Context
- Analyzer: !
find . -path '*/scripts/*' -maxdepth 3 -name audit-skill-structure.py -type f - Prior output: !
find . -path '*/tmp/skill-audit/*' -maxdepth 3 -type f - Compliance pre-check: !
find . -path '*/scripts/*' -maxdepth 3 -name plugin-compliance-check.sh -type f - Description pre-check: !
find . -path '*/scripts/*' -maxdepth 3 -name audit-skill-descriptions.py -type f
Parameters
Parse these from $ARGUMENTS:
| Parameter | Description |
|---|---|
--plugin <name> | Restrict scan to a single plugin directory (e.g. configure-plugin) |
--strict | Exit non-zero on warn-tier findings in addition to error-tier |
Execution
Execute this skill-structure audit:
Step 1: Confirm prerequisites are green
These audits own orthogonal concerns. Run them first and resolve their findings before triaging this skill's output:
scripts/plugin-compliance-check.sh— frontmatter, size budget, body corruptionpython3 scripts/audit-skill-descriptions.py --strict—descriptionfields have trigger phrases
If either reports errors, pause and ask the user whether to continue — a messy frontmatter baseline makes the overlap heuristics noisier.
Step 2: Run the analyzer
python3 scripts/audit-skill-structure.py $ARGUMENTS
This writes five artefacts into tmp/skill-audit/:
| File | Contents |
|---|---|
report.json | Canonical machine-readable output (source of truth) |
summary.md | Top-N by severity, intended for triage |
overlap-clusters.md | Side-by-side description comparison per cluster |
split-candidates.md | Per-skill evidence (lines, tables, fenced code, examples) |
consolidation-candidates.md | Conservative merge suggestions |
The schema for report.json and the rationale for every threshold live in REFERENCE.md.
Step 3: Triage summary.md first
Open tmp/skill-audit/summary.md. It lists:
- Top error-tier split candidates (SKILL.md bodies that exceed the hard line limit without a
REFERENCE.md) - Largest overlap clusters (by number of flagged pairs)
- Pointers to the three detail reports
Step 4: For each overlap cluster, decide the disposition
For each cluster in tmp/skill-audit/overlap-clusters.md, pick one:
| Disposition | When it fits |
|---|---|
| Merge | Two small skills describing the same intent → fold into one |
| Rename | Clear distinct intent but colliding names → disambiguate the slug |
| Rewrite descriptions | Intent is distinct but descriptions collide → sharpen trigger phrases |
| Leave | Cluster is a family by design (e.g. python-plugin ecosystem skills) — no change |
Do not auto-act. Each disposition lands in its own PR per the CLAUDE.md guidance.
Step 5: For each split candidate, decide the disposition
For each row in tmp/skill-audit/split-candidates.md, pick one:
| Disposition | When it fits |
|---|---|
Extract to REFERENCE.md | Warn/error-tier size or contiguous table block |
Extract to scripts/ | Fenced-code aggregate exceeds threshold |
Extract to examples/ | Multiple lengthy example blocks |
| Leave | Content is genuinely part of the skill's core instruction |
The report's reason column carries the quantitative evidence — cite it when opening the split PR.
Step 6: For each consolidation candidate, decide the disposition
Consolidation suggestions are conservative — both skills must be small, share a plugin, share a name prefix, and have high description similarity. Still, merge is editorial:
- Read both SKILL.md files
- Confirm the intents really are duplicative (not complementary)
- Choose the merge target name and fold the smaller skill into it
File a GitHub issue per consolidation decision rather than bundling them.
Post-actions
report.jsonis the source of truth for any follow-up PRs — cite the relevant JSON entries in PR descriptions- Each cluster or split candidate acted upon lands as its own PR
- Add a regression fixture under
tmp/fixtures/if a fix should be prevented from recurring (see.claude/rules/regression-testing.md)
Agentic Optimizations
| Context | Command |
|---|---|
| Full scan | python3 scripts/audit-skill-structure.py |
| Single-plugin scan | python3 scripts/audit-skill-structure.py --plugin configure-plugin |
| CI-gating run | python3 scripts/audit-skill-structure.py --strict |
| Top splits only | jq '.split_candidates | sort_by(-.lines) | .[:10]' tmp/skill-audit/report.json |
| Top clusters only | jq '.overlap_clusters | sort_by(-(.pairs | length)) | .[:10]' tmp/skill-audit/report.json |
See Also
.claude/rules/skill-quality.md— size limits and required sectionsscripts/plugin-compliance-check.sh— frontmatter and body corruption ownerscripts/audit-skill-descriptions.py— trigger-phrase coverage owner/health:check --scope=agentic— CLI-flag compactness audit- REFERENCE.md — heuristic rubric, thresholds, and JSON schema