skill-overlap
Skill49 starsChanged 13 days agoApache-2.0View on GitHub
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.
In this repository151 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- llms-full.txtllms.txt
- llms.txtllms.txt
- agent-readinessSkill
- appeal-scoreSkill
- bottleneck-mapSkill
- ci-repairSkill
- claim-repro-scoreSkill
- clear-out-wipSkill
- commit-cleanSkill
- conflation-scoreSkill
- cross-validateSkill
- curate-clusterSkill
- debt-cleanSkill
- debt-orchestratorSkill
- disambiguation-scoreSkill
- dojo-rsi-scoreSkill
- dos-dispatch-loopSkill
- dos-dispatchSkill
- dos-next-upSkill
- dos-replanSkill
- dos-witness-claimSkill
- field-borrowSkill
- fleet-waveSkill
- git-subagent-syncSkill
- goalSkill
- guard-rsi-scoreSkill
- harness-creatorSkill
- harness-gardenSkill
- industry-scoreSkill
- issue-orchestratorSkill
- issue-queueSkill
- issue-triageSkill
- lightgap-scoreSkill
- memory-compactSkill
- milestone-scoreSkill
- modularizeSkill
- negframe-scoreSkill
- opencode-waveSkill
- operator-heaviness-scoreSkill
- persona-scoreSkill
- phased-planSkill
- plan-auditSkill
- quality-scoreSkill
- question-loopSkill
- refresh-cachedoc-numbersSkill
- refresh-readmeSkill
- releaseSkill
- resume-watchdog-auditSkill
- run-it-all-nightSkill
- score-2xSkill
- scorecardSkill
- scout-loopSkill
- signal-firstSkill
- skill-lifecycleSkill
- skill-scoreSkill
- slop-scoreSkill
- sota-checkSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 0 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 51
Read both SKILL.md bodies.
- Very specific: line 53
If genuinely redundant → open an issue proposing the merge, or route the weaker one through skill-lifecycle to archive (reversible), never …
- Very specific: line 56
If distinct-but-similar → the overlap is a *discoverability* smell.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
/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
skill-score audits over-budget 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 builtfakbinary. - Default threshold 0.5; drop to
--threshold 0.4to see the long tail. shared_topnames 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:
- Read both
SKILL.mdbodies. Do they tend the same surface, or just share the scorecard idiom? - If genuinely redundant → open an issue proposing the merge, or route the
weaker one through
skill-lifecycleto archive (reversible), never a raw delete. - If distinct-but-similar → the overlap is a discoverability smell; sharpen
each
description:'s "Use when…" trigger viaskill-scoreso 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.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

