laurigates/health-skill-audit

/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 scripts -maxdepth 1 -name audit-skill-structure.py -type f
• Prior output: !find tmp/skill-audit -maxdepth 1 -type f
• Compliance pre-check: !find scripts -maxdepth 1 -name plugin-compliance-check.sh -type f
• Description pre-check: !find scripts -maxdepth 1 -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:

1. scripts/plugin-compliance-check.sh — frontmatter, size budget, body corruption
2. python3 scripts/audit-skill-descriptions.py --strict — description fields 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:

1. Top error-tier split candidates (SKILL.md bodies that exceed the hard line limit without a REFERENCE.md)
2. Largest overlap clusters (by number of flagged pairs)
3. 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:

1. Read both SKILL.md files
2. Confirm the intents really are duplicative (not complementary)
3. 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.json is 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 sections
• scripts/plugin-compliance-check.sh — frontmatter and body corruption owner
• scripts/audit-skill-descriptions.py — trigger-phrase coverage owner
• /health:check --scope=agentic — CLI-flag compactness audit
• REFERENCE.md — heuristic rubric, thresholds, and JSON schema