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:

bash
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

1. Odpal audyt, przeczytaj raport.
2. 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.

1. Nanieś zmiany dopiero po potwierdzeniu autora.
2. 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.