ms-ai-architect/docs/skill-eval-routine-improvement-2026-06.md

# 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)

1. **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.
2. **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.
3. **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.
4. **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

0. **(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.
1. **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).
2. **TDD (Iron Law):** failing test først (fixtures i `tests/kb-eval/`), så implementer i `eval.mjs` (disk) + `skill-score.mjs` (ren scoring).
3. **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).
4. **Judge-bake-off** for §4b-kriteriene (gull + kalibrert prompt + målt adopsjon, §4c).
5. **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](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices) · [Agent Skills overview](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview) · [Extend Claude with skills (Claude Code)](https://code.claude.com/docs/en/skills) · [skill-creator SKILL.md](https://github.com/anthropics/skills/blob/main/skills/skill-creator/SKILL.md) · [Equipping agents for the real world](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Agent Skills open standard](https://agentskills.io/specification).
Community: [mattpocock/skills — writing-great-skills](https://github.com/mattpocock/skills/blob/main/skills/productivity/writing-great-skills/SKILL.md) · [obra/superpowers — writing-skills](https://github.com/obra/superpowers/blob/main/skills/writing-skills/SKILL.md) · [halfmoon-mind/rubric-evaluator](https://github.com/halfmoon-mind/rubric-evaluator) · [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) · [skillscore](https://dev.to/sayed_ali_alkamel/skillscore-a-cli-that-scores-your-ai-agents-skillmd-0-100-48l1) · [Test any skill without an LLM judge](https://medium.com/@nemadesumit/how-to-test-any-claude-code-skill-without-an-llm-judge-3da402de7146) · [MLflow — Evaluating Skills](https://mlflow.org/blog/evaluating-skills-mlflow/).