Skill-eval-rutinen — forbedringsspor (Pocock-lens + best-practice-triangulering)

Task-brief. Skrevet 2026-06-30. Stier relative til plugin-rot. Durabel (overlever /clear); STATE.md peker hit.

Status: SPEC / ikke startet. Lagt inn på operatørs eksplisitte forespørsel (utgangspunkt: Matt Pococks «Writing Great Skills»-talk). Forbedringen kjøres som eget spor — IKKE bland med KB-korrekthets-sprinten (judge v3.1). Research-grunnet 2026-06-30 (to Opus-agenter: offisiell Anthropic + community-triangulering).

0. Mål / hvorfor

Forbedre rutinen som scorer skill-kvalitet og deres referansefiler — scripts/kb-eval/lib/skill-score.mjs (ren rubrikk) + scripts/kb-eval/eval.mjs (deterministiske sjekker) + judge-laget — ved å folde inn Matt Pococks «Writing Great Skills»-rammeverk som en ny lens, triangulert mot offisiell Anthropic-guidance og eksisterende community-lintere. Pluginen er showcase (showcase-reusable-patterns); korrekthets-mekanismen (judge + gold + målt adopsjon) fra KB-sporet er det samme mønsteret som de nye judge-kriteriene under skal bruke — porter den, ikke gjenoppfinn.

Nordstjerne: høyest mulig kvalitet på skills + refs, målt objektivt, med klare forbedringspekere. Ikke flere kriterier for kriterienes skyld — hvert nytt punkt må enten fange en reell feilklasse rubrikken slipper i dag, eller erstatte et svakere signal.

1. Nåværende rutine (grounded — verifisert, ikke gjettet)

16-kriteriers vektet rubrikk med hardt gulv på de to last-bærende (K1 trigger-presisjon, K10 søsken-overlapp); score < 90 ⇒ under mål. Allerede grunnet i Anthropics offisielle «Skill authoring best practices» (nær 1:1 med deres deterministiske sjekkliste). Spec: docs/skill-quality-scoring-plan.md.

Dekket i dag (K/N/CT)	Kort
K1 trigger-presisjon (judge, gulv, v3) · K2 description-format · K10 søsken-overlapp (det, gulv)	trigger + scope
K3 body ≤500 linjer · K5 progressiv disclosure · K6 routing · N3 refs én nivå · N4 TOC >100 linjer	struktur
K4 ingen duplisering (judge) · K7 imperativ stil (judge) · K9 ingen volatil tid-info (judge)	steering/pruning-snitt
CT5 sourcedness (dormant til Port 1) · refCount · N1 name · N2 desc ≤1024 · N5 forward-slash	refs/hygiene

Fase 2 (allerede på roadmap, ikke bygget): uplift-eval — «hjelper skillen vs. ingen-skill-baseline» (with-skill vs baseline pass-rate-delta). Skill-eval-plan §5.

2. Tre kilde-lag (research 2026-06-30)

A. Anthropic offisiell (høyest autoritet, deterministisk ryggrad). «Skill authoring best practices», skill-creator, plugin-dev:skill-development, engineering-blogg. Bekrefter dagens rubrikk + avdekker offisielt-belagte signaler vi IKKE bruker ennå (se §3). Viktig: ingen offisiell 0–100-rubrikk finnes — vi fyller et reelt gap, men hvert punkt skal spores til en checklist-regel, ikke oppfinnes.

B. Matt Pocock «Writing Great Skills» (én sterk praktiker; opinion, ikke spec). Faktiske skill-seksjoner: Invocation · Writing the description · Information hierarchy · When to split · Pruning · Leading words · Failure modes. Premiss-korreksjon (verifiseringsplikt): talens «vertical slice»- og «grill-with-docs vs to-PRD»-eksempler finnes IKKE i den faktiske skillen — reelle leading-word-eksempler er lesson, fog of war, tracer bullets, samt refactors «fast, deterministic, low-overhead» → tight og «a loop you believe in» → red. Bruk de verifiserte, ikke talens parafrase.

C. Community + eksisterende lintere (sekundært — HØST sjekklistene, ikke gjenoppfinn). superpowers (TDD-for-skills, ord-budsjett per tier, «description = trigger-only»); og ferdige 0–100-scorere: skillcheck (description-score 0–100), skillscore, rubric-evaluator (to-lags BLOCKER/MAJOR/MINOR-gate + judge), agnix (156-regel-linter). Vårt høyeste løft: kopier deres deterministiske sjekker der de er bedre enn våre.

3. Gap-analyse: Pocock × nåværende rubrikk

Pocock-dimensjon	Dekket i dag?	Gap (ny verdi)	Automatiserbar?
Invocation — user- vs model-invoked design; context-load (model-desc koster tokens hver request) vs cognitive-load	Nei (K1 scorer kun presisjon, ikke design-valget)	Side-effekt-skill (deploy/commit/push/send/delete) UTEN `disable-model-invocation` = warn (offisielt belagt, CC); kombinert `description`+`when_to_use` ≤1536 listing-cap; `context: fork` uten reell oppgave	Delvis (verb-heuristikk + lengde = det; «er model-invocation berettiget?» = judge)
Information hierarchy / when to split — steps m/ completion-criterion; reference i to lag; flytt én-grens-materiale bak context-pointer	Delvis (K3/K5/K6/N3/N4 = størrelse/lenker, ikke gren-bevissthet)	Step uten observerbart completion-criterion; én-grens-ref inlinet i SKILL.md; orphan-ref (fil i mappe ikke lenket fra SKILL.md); context-pointer mangler trigger-frase	Delvis (orphan/depth/size = det; «bør splittes?» / «criterion observerbart?» = judge)
Leading words — kompakt pretrent konsept agenten ekko-er i reasoning	Nei	Konsistens-proxy: et myntet begrep brukt konsistent + i description (det); høy-signal-kvalitet (judge)	Delvis (konsistens = det; «ekte leading word?» = judge)
Legwork / split-by-sequence — krevende criterion driver grundighet; skjul fremtidige steg	Nei	Vag gate-språk («make sure it works», «looks good») som ikke er binært; premature-completion	Judge (kjernen)
Pruning — no-ops / deletion-test — «endrer denne setningen atferd vs default?»	Delvis (K4 = duplisering)	Boilerplate-denylist (det, grovt); ekte no-op-test (judge); sediment (stale lag) (judge)	Mest judge (denylist fanger kun det åpenbare)
Massive skills / DRY på tvers	Delvis (K3 + K4 per-skill)	Nær-duplikat på tvers av HELE skill-korpuset (hashing/embedding)	Det (cross-corpus near-dup)

4. Foreslåtte forbedringer

4a. Nye deterministiske kriterier (eval.mjs + skill-score.mjs, TDD, billig):

Side-effekt-uten-gate-vakt: name/description matcher destruktive verb (deploy/commit/push/send/delete/publish) OG disable-model-invocation ikke satt → warn. (CC-belagt.)
Listing-cap: kombinert description+when_to_use ≤ 1536 tegn (Claude Code-spesifikk). Separat fra dagens N2 (1024 = hard felt-maks).
Body token-budsjett: body < 5k tokens (offisielt, i tillegg til <500 linjer).
Orphan-ref-deteksjon: ref-fil i skill-mappe ikke lenket fra SKILL.md = smell.
ALL-CAPS-vegg / rigid MUST: ALWAYS/NEVER-all-caps + tette MUST-vegger = skill-creator «yellow flag».
Cross-corpus near-duplicate: duplisert blokk/setning på tvers av skills (DRY-brudd over korpuset, ikke bare per-skill).
Vurder: ToC-terskel-konflikt (BP 100 vs SC 300 linjer — velg 100 som strengere, warn på 300); deskriptive filnavn (doc2.md/file1.md-denylist); fully-qualified MCP Server:tool.

4b. Nye judge-kriterier (utvider EKSISTERENDE judge-lag — samme mønster som KB-judge):

No-op / deletion-test: per setning, «endrer dette atferd vs default?» → kandidat for kutt. Pococks kjerneteknikk; ikke regex-reduserbar.
Leading-word-kvalitet: er et myntet begrep et ekte høy-signal pretrent konsept, brukt konsistent?
Completion-criterion-observerbarhet: er hvert stegs sluttbetingelse binær/observerbar vs fuzzy?
Sediment: stale/irrelevant akkumulert materiale.
(divergens-nøytral): «model-invocation berettiget?» — IKKE belønn disable-model-invocation-tilstedeværelse per se (se §5).

4c. Arkitektur — adopter to-lags-mønsteret eksplisitt (rubric-evaluator-mønster, speiler vårt eget): Deterministiske sjekker = gate/severity (vi har gulv-mekanismen); judge scorer den semantiske resten. Port judge-bake-off-disiplinen fra KB-sporet: bygg et lite gull-sett for skill-kvalitet, kalibrer judge-prompten mot dokumenterte feilmoduser, MÅL adopsjon (slå forrige) — IKKE ad-hoc-patch. gold-freshness-can-invert-adoption gjelder også her: et skill-kvalitets-gull eldes.

5. Divergenser å håndtere (ikke hardkod én side)

Description: «what + when» (Anthropic) vs «trigger-only» (superpowers). Superpowers MÅLTE at workflow-oppsummering i description får agenten til å hoppe over å lese skillen. → Ikke straff utelatt «what» som hard regel; gjør konfigurerbar.
Invocation-default: 1%-regel/model-default (superpowers) vs berettig-model-invocation (Pocock). → Ikke belønn disable-model-invocation per se; belønn berettiget valg (judge) eller vær nøytral.
Lengde-enhet: 500 linjer (Anthropic) vs 150/200/500 ord per tier (superpowers). → Velg én enhet; eksponer terskel som config; hyppig-lastede skills tåler strengere.
Cross-surface-konflikter (linter MÅ vite hvilken flate): name/description required (platform/spec) vs optional (Claude Code); allowed-tools restriktiv (spec experimental) vs IKKE-restriktiv i Claude Code; when_to_use kun Claude Code. Ikke hard-fail på feil flate.

6. Sekvensering

(valgfritt, men anbefalt FØRST) Dypere research hvis ønsket: /deep-research eller /trekresearch på de eksisterende linterne (skillcheck/skillscore/rubric-evaluator/agnix) — høst konkrete regel-lister + se hva de scorer som vi ikke gjør. Denne briefen har allerede triangulert hovedrammeverkene; en full deep-research-pass er for å hente implementerings-detaljer fra de eksisterende verktøyene.
Velg scope: hvilke §4a/§4b-kriterier gir mest signal? Start med §4a (billig, deterministisk, høy tillit) + ett judge-kriterium (no-op-test, høyest Pocock-verdi).
TDD (Iron Law): failing test først (fixtures i tests/kb-eval/), så implementer i eval.mjs (disk) + skill-score.mjs (ren scoring).
Re-score korpuset + kalibrer vekter (ikke la nye kriterier tanke alle skills under 90 % ukontrollert — degrader nye judge-kriterier til available:false til de er kalibrert, slik CT5 gjør i dag).
Judge-bake-off for §4b-kriteriene (gull + kalibrert prompt + målt adopsjon, §4c).
Wire i score-skill.mjs --write-cachen → Spor D SessionStart-surfacing.

7. Verifisering (kjørbare kriterier)

node --test tests/kb-eval/*.test.mjs grønn etter hver ny sjekk (nye fixtures: side-effekt-uten-gate, orphan-ref, ALL-CAPS-vegg, cross-corpus-dup, listing-cap >1536).
node scripts/kb-eval/score-skill.mjs --json kjører uten regresjon på de 5 nåværende skills; nye kriterier vises i forbedringsrapporten med konkret fix.
Hvert nytt deterministisk kriterium: vis at det FANGER en injisert feil-fixture OG ikke flagger en ren fixture (presisjon + recall, som G3-linten).
Judge-kriterier: bake-off mot skill-kvalitets-gull slår forrige judge (P OG R), ellers ikke adoptert (§4c, samme gate som KB-judge).
Ingen regresjon: full suite + validate grønn.

8. Kilder (verifisert 2026-06-30)

Offisielt: Skill authoring best practices · Agent Skills overview · Extend Claude with skills (Claude Code) · skill-creator SKILL.md · Equipping agents for the real world · Agent Skills open standard. Community: mattpocock/skills — writing-great-skills · obra/superpowers — writing-skills · halfmoon-mind/rubric-evaluator · thedaviddias/skill-check · skillscore · Test any skill without an LLM judge · MLflow — Evaluating Skills.

12 KiB Raw Blame History Unescape Escape