agentleFS
anthony-chaudharyanthony-chaudhary/fak/.agents/skills/skill-overlap/SKILL.md

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.

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
  1. Very specific:

    Read both SKILL.md bodies.

    line 51
  2. Very specific:

    If genuinely redundant → open an issue proposing the merge, or route the weaker one through skill-lifecycle to archive (reversible), never …

    line 53
  3. Very specific:

    If distinct-but-similar → the overlap is a *discoverability* smell.

    line 56

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/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 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.