skill-audit
Higiena skilli, które tworzysz — w DOWOLNYM projekcie. description to jedyny
sygnał routingu (brak wektorów/tagów pod spodem): za długi lub zaśmiecony opis
przepełnia listę i skill przestaje się triggerować. Ten skill mierzy to
mechanicznie i pomaga naprawić.
Uruchomienie
Z korzenia projektu:
python3 ~/.claude/skills/skill-audit/audit.py
python3 ~/.claude/skills/skill-audit/audit.py --sibling ../thumbforge-skills
python3 ~/.claude/skills/skill-audit/audit.py --selftest
Skanuje .claude/skills/, .agents/skills/ i plugins/*/skills/ (te, które
istnieją). Dla każdego skilla drukuje długość opisu i naruszenia; na końcu sumę
opisów per scope oraz listę niesync. --sibling <repo> dołącza scope'y drugiego
repo (np. dystrybucyjnego repo skilli) do sync-checku — drift kanon↔dystrybucja
wychodzi w audycie, nie u testera. --selftest odpala samotest na fixture w
tmp. Kod wyjścia ≠ 0, gdy są znaleziska.
Zero zależności (tylko stdlib python3) — działa wszędzie.
Reguły (dobre praktyki: Anthropic + warsztat Bohaczyka + feedback testerów)
Sprawdzane per skill:
- Długość
description: cel 200-300 zn., twardy limit 1024 (Anthropic).
Krótko — „nie idź w descriptionmaxxing", ale poniżej ~200 zn. opis przestaje
nieść triggery i routing słabnie (feedback Krisa).
- Bez cross-referencji do innych skilli w opisie („use X", „NOT for Y") —
routing należy do ciała SKILL.md, nie do frontmatter.
- Bez CLI/paid-boilerplate w opisie (dry-run, --confirm, „only spend",
triple-lock) — to reguła globalna / ciało skilla.
- Trzecia osoba: „Generuje…", „Use when…", nigdy „I help…", „You can use this to…".
- Komplet frontmatter:
name (= nazwa katalogu, lowercase, ≤64 zn., bez słów
zarezerwowanych claude/anthropic) + description.
- Bajt-identyczność kopii między scope'ami (odpowiednik
diff -qr).
- Suma długości opisów — ryzyko przepełnienia listy przy 40-60+ skillach.
Miękkie (nieraportowane, ale trzymaj): ciało SKILL.md krótkie (Anthropic < 500
linii; realny cel 200-300 słów), progressive disclosure (frontmatter → body →
references/ na żądanie), konkretne triggery w opisie („use when …"), kod
deterministyczny do skryptu (nie do promptu), przykłady input/output ponad suche
reguły, krytyczne instrukcje na górze pliku.
Procedura poprawy
- Odpal audyt, przeczytaj raport.
- Dla każdego znaleziska zaproponuj konkretny trim: skróć opis do CO robi +
KIEDY użyć + triggery; przenieś routing „NOT for…" i protokoły do ciała.
- Nanieś zmiany dopiero po potwierdzeniu autora.
- Po edycji skilla obecnego w wielu scope'ach zsynchronizuj WSZYSTKIE kopie
bajt-w-bajt i odpal audyt ponownie, aż zejdzie do zera.
Zakres poprawek trzymaj wąsko: rusz tylko te skille, o które proszono — nie
przepisuj hurtem cudzych/niepowiązanych skilli przy okazji.
1---2name: skill-audit3description: Audytuje higienę autorskich plików SKILL.md: długość opisu, cross-referencje, boilerplate, osobę, frontmatter oraz sync kopii między scope'ami i sibling repo. Use when authoring or editing a skill and you want its description checked before it degrades routing — triggers: "/skill-audit", "audyt skilli", "sprawdź opisy skilli", "higiena skilli".4---56# skill-audit78Higiena skilli, które tworzysz — w DOWOLNYM projekcie. `description` to jedyny9sygnał routingu (brak wektorów/tagów pod spodem): za długi lub zaśmiecony opis10przepełnia listę i skill przestaje się triggerować. Ten skill mierzy to11mechanicznie i pomaga naprawić.1213## Uruchomienie1415Z korzenia projektu:1617```bash18python3 ~/.claude/skills/skill-audit/audit.py19python3 ~/.claude/skills/skill-audit/audit.py --sibling ../thumbforge-skills20python3 ~/.claude/skills/skill-audit/audit.py --selftest21```2223Skanuje `.claude/skills/`, `.agents/skills/` i `plugins/*/skills/` (te, które24istnieją). Dla każdego skilla drukuje długość opisu i naruszenia; na końcu sumę25opisów per scope oraz listę niesync. `--sibling <repo>` dołącza scope'y drugiego26repo (np. dystrybucyjnego repo skilli) do sync-checku — drift kanon↔dystrybucja27wychodzi w audycie, nie u testera. `--selftest` odpala samotest na fixture w28tmp. Kod wyjścia ≠ 0, gdy są znaleziska.29Zero zależności (tylko stdlib python3) — działa wszędzie.3031## Reguły (dobre praktyki: Anthropic + warsztat Bohaczyka + feedback testerów)3233Sprawdzane per skill:3435- **Długość `description`**: cel 200-300 zn., twardy limit 1024 (Anthropic).36 Krótko — „nie idź w descriptionmaxxing", ale poniżej ~200 zn. opis przestaje37 nieść triggery i routing słabnie (feedback Krisa).38- **Bez cross-referencji do innych skilli w opisie** („use X", „NOT for Y") —39 routing należy do ciała SKILL.md, nie do frontmatter.40- **Bez CLI/paid-boilerplate w opisie** (dry-run, --confirm, „only spend",41 triple-lock) — to reguła globalna / ciało skilla.42- **Trzecia osoba**: „Generuje…", „Use when…", nigdy „I help…", „You can use this to…".43- **Komplet frontmatter**: `name` (= nazwa katalogu, lowercase, ≤64 zn., bez słów44 zarezerwowanych `claude`/`anthropic`) + `description`.45- **Bajt-identyczność kopii** między scope'ami (odpowiednik `diff -qr`).46- **Suma długości opisów** — ryzyko przepełnienia listy przy 40-60+ skillach.4748Miękkie (nieraportowane, ale trzymaj): ciało SKILL.md krótkie (Anthropic < 50049linii; realny cel 200-300 słów), progressive disclosure (frontmatter → body →50`references/` na żądanie), konkretne triggery w opisie („use when …"), kod51deterministyczny do skryptu (nie do promptu), przykłady input/output ponad suche52reguły, krytyczne instrukcje na górze pliku.5354## Procedura poprawy55561. Odpal audyt, przeczytaj raport.572. Dla każdego znaleziska zaproponuj konkretny trim: skróć opis do CO robi +58 KIEDY użyć + triggery; przenieś routing „NOT for…" i protokoły do ciała.593. Nanieś zmiany dopiero po potwierdzeniu autora.604. Po edycji skilla obecnego w wielu scope'ach zsynchronizuj WSZYSTKIE kopie61 bajt-w-bajt i odpal audyt ponownie, aż zejdzie do zera.6263Zakres poprawek trzymaj wąsko: rusz tylko te skille, o które proszono — nie64przepisuj hurtem cudzych/niepowiązanych skilli przy okazji.
Szewowsky