skill-overlap

name	skill-overlap
description	Flag content-redundant SKILL.md pairs as merge candidates — pairwise body cosine similarity over the skill pack, sorted highest-first. Use when the pack feels bloated or two skills seem to overlap, to find "skills A and B are N% token-similar — consider merging" candidates before a skill-lifecycle archive pass. Proposal only — never merges, edits, or deletes a skill.

/skill-overlap — flag content-redundant SKILL.md pairs (never merge)

The one context-cost technique from the Comet/Perplexity writeup that fak did not already cover (#3930): skill-to-skill content redundancy. skill-lifecycle archives dead skills and clean-skill trims fat ones — neither measures whether two live skills say the same thing. With 55+ SKILL.md files (many *-score scorecards), that overlap is where the pack quietly bloats.

This skill measures it and stops. Max action is to PRINT candidates for a human to judge — like skill-lifecycle's dry-run archive verdicts, it proposes, it never merges. Deciding two skills are genuinely one is a semantic call the detector deliberately does not make; there is no --apply.

The witnessed helper

skill_overlap.py runs a pairwise token-similarity primitive over every .claude/skills/*/SKILL.md body and emits the pairs above a threshold, sorted by similarity:

python .claude/skills/skill-overlap/skill_overlap.py [--threshold T] [--top N] [--json]

• Front-matter is stripped first — the shared name:/description: YAML skeleton is structural, not redundant, so it must not inflate the score.
• Similarity is body cosine over token frequency with a small function-word stoplist — "skills A and B are N% token-similar" in the issue's own words. Same posture as fak dup / fak traj (block- and query-level near-dup detection), self-contained so the witness runs with no built fak binary.
• Default threshold 0.5; drop to --threshold 0.4 to see the long tail.
• shared_top names the highest-weight tokens both bodies carry — the why behind each score, so a human can judge the merge without re-reading both.

Exit code is always 0: this is advisory, and "no candidates" is a clean answer.

How to read a candidate

A high score means lexical overlap, not that a merge is correct. Two *-score scorecards may share vocabulary (debt, scorecard, commit) yet tend genuinely different surfaces. Before proposing a merge:

1. Read both SKILL.md bodies. Do they tend the same surface, or just share the scorecard idiom?
2. If genuinely redundant → open an issue proposing the merge, or route the weaker one through skill-lifecycle to archive (reversible), never a raw delete.
3. If distinct-but-similar → the overlap is a discoverability smell; sharpen each description:'s "Use when…" trigger via skill-score so the two stop colliding in recall.

Witness

python .claude/skills/skill-overlap/skill_overlap_test.py — a fixture skill pack with one deliberately-overlapping pair asserts that pair is surfaced above the threshold while two unrelated skills are not, plus the front-matter-stripped, proposal-only, deterministic, and archived-skip invariants. This is the skill's proof-of-correctness; run it after any change to the detector.