Self-Healing Skill Library

A re-runnable system for keeping a Claude Code skill library lean, discoverable, and cheap on context.

The problem

Claude loads only each skill's name + description into context at the start of every session — never the bodies, never references/ files, never nested sub-skills. So as your library grows, two things go wrong on every session:

1. Context flooding — every skill's description loads up front, whether you need it or not. A sprawling, overlapping library spends your context budget before any work begins.
2. Wrong-skill / no-skill — the capability you need is buried behind a description that doesn't match the task, so the agent reaches for the wrong skill, or none.

The fix isn't deleting skills. It's hierarchy + sharp descriptions: a lean surface of well-described hubs, with detail one layer down, fetched on demand.

What's inside

• lint-skill-descriptions.sh — flags skills with missing descriptions, missing trigger phrases, or descriptions over the length ceiling. The mechanical half of the loop.
• references/discovery-and-consolidation.md — how loading actually works, the facet-vs-entity consolidation rule, the per-item trigger test, and the "body only loads for skills the description already selected" trap.
• references/maintenance-audit.md — the re-runnable audit checklist (the "healing" pass) + a healthy-library checklist.
• references/authoring-template.md — keyword-dense description rules and a SKILL.md template.
• SKILL.md — wires it together as a Claude Code skill, so you can just ask Claude to "audit my skill library".

Install

git clone https://github.com/REPLACE_ME/self-healing-skill-library.git \
  ~/.claude/skills/self-healing-skill-library

Then start a Claude Code session and ask to "audit my skill library", or run the lint directly:

bash ~/.claude/skills/self-healing-skill-library/lint-skill-descriptions.sh

The loop

1. Lint → fix missing/bloated descriptions and missing trigger phrases.
2. Audit → list buried items, apply the per-item trigger test, fix gaps.
3. Consolidate → merge overlapping skills into hubs (facet-vs-entity rule).
4. Re-author → tighten descriptions.
5. Re-run until clean. Re-run whenever the library grows.

---

Built by Gavriel Shaw — Human + AI Collaboration Engineer. More at gavrielshaw.com.

MIT licensed — see LICENSE.