---
name: skill-audit
description: >-
  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".
allowed-tools: Bash, Read, Edit
---

# 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.
3. Nanieś zmiany dopiero po potwierdzeniu autora.
4. 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.