# Skill-kvalitetsscore (Spor D) — spec

_Objektiv 0–100 %-kvalitetsscore per skill, med 90 %-bar, forbedringsrapport og SessionStart-surfacing. Grunnet i Anthropics faktiske skill-authoring-guidance (ikke oppfunnet akademisk). Skrevet 2026-06-23 (S37). Stier relative til plugin-rot._

---

## 0. Mål

En **rutine som objektivt måler skill-kvalitet** og rapporterer hva som må forbedres, med målsetning **alle skills ≥ 90 % til enhver tid**. Bygger oppå den eksisterende K1–K10-rubrikken i `scripts/kb-eval/eval.mjs`, som research (under) viser er nesten 1:1 med Anthropics kanoniske «Skill authoring best practices»-sjekkliste — altså allerede grunnet i reell praksis, ikke akademisk oppfunnet.

## 1. Verifiseringskilder (Anthropic primær)

- **«Skill authoring best practices»** — platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices (hentet 2026-06-23). Kanonisk sjekkliste + eksakte tall.
- **`skill-creator` (Anthropic-shippet skill)** — `~/.claude/plugins/.../skill-creator/SKILL.md`. Description-optimizer (trigger-presisjon via 20 queries / 60-40 train-test / 3 kjøringer), eval-loop.
- **`plugin-dev:skill-development` (Anthropic-shippet)** — third-person description, imperativ form, progressiv disclosure, «avoid duplication».
- **«Equipping agents for the real world with Agent Skills»** — anthropic.com/engineering (hentet 2026-06-23). Progressiv disclosure, evaluering fra capability-gaps, baseline-uplift.

### Eksakte, målbare regler funnet (med kilde)
| Regel | Tall | Kilde |
|---|---|---|
| `name` | ≤64 tegn, `a-z0-9-`, ingen XML, ingen reserverte ord («claude»/«anthropic»), gerund-form anbefalt | best-practices §Skill structure |
| `description` | ≤1024 tegn, ikke-tom, 3.-person, «hva + når», spesifikke triggere | best-practices §Writing effective descriptions |
| SKILL.md body | **< 500 linjer** («token budget», «optimal performance») | best-practices §Token budgets + §Progressive disclosure |
| Refs én nivå dypt | ingen nøstede refs | best-practices §Avoid deeply nested references |
| TOC i ref-filer | for filer **> 100 linjer** | best-practices §Structure longer reference files |
| Ingen tid-sensitiv info i body | flytt til «old patterns»/`<details>` | best-practices §Avoid time-sensitive information |
| Forward-slash-stier | aldri Windows-stier | best-practices §Avoid Windows-style paths |
| Imperativ form | verb-først, ikke 2.-person | plugin-dev §Writing Style |
| Ingen duplisering SKILL.md↔refs | info bor ett sted | plugin-dev §Avoid duplication |
| Evaluering = sannhetskilde | ≥3 evals, **baseline uten skill → mål uplift** | best-practices §Evaluation and iteration |

## 2. Rubrikk → score-mapping (binding)

K1–K10 er allerede implementert i `eval.mjs` og validert mot tabellen over. Scoren legger til **fem nye deterministiske sjekker** fra Anthropic-sjekklista som rubrikken manglet (N1–N5), og aggregerer alt til 0–100.

**Modell: vektet delpoeng + hardt gulv** (operatør-besluttet S37).

| Kriterium | Kilde | Vekt | Gulv | Delpoeng (0–1) |
|---|---|---|---|---|
| **K1** trigger-presisjon | judge | 3 | **JA** | `precision` (korrekte/20) |
| **K10** søsken-ikke-overlapp | det | 3 | **JA** | `pass?1 : max(0, 1-(maxCombined-terskel)/terskel)` |
| **K3** body ≤500 linjer | det | 2 | — | `lines≤500?1 : max(0, 1-(lines-500)/500)` |
| **K4** ingen duplisering | judge | 2 | — | `score/5` |
| **K9** ingen volatil tid-info | judge | 2 | — | `pass?1:0` |
| **K2** description-format | det | 1 | — | `pass?1:0` |
| **K5** progressiv disclosure | det | 1 | — | `min(1, namedRatio/0.2)` |
| **K6** routing-pekere | det | 1 | — | `pass?1:0` |
| **K7** imperativ stil | judge | 1 | — | `ratio` |
| **K8** kildehenvisning refs | judge | 1 | — | `ratio` |
| ref-tall-konsistens | det | 1 | — | `consistent?1:0` |
| **N1** name-validitet | det | 1 | — | `pass?1:0` |
| **N2** description ≤1024 + ikke-tom | det | 1 | — | `pass?1:0` |
| **N3** refs én nivå dypt | det | 1 | — | `pass?1:0` |
| **N4** TOC i ref-filer >100 linjer | det | 1 | — | andel store filer med TOC |
| **N5** forward-slash-stier | det | 1 | — | `pass?1:0` |

**Aggregering:** `score = Σ(vekt·delpoeng for TILGJENGELIGE kriterier) / Σ(vekt for tilgjengelige) × 100`. «Tilgjengelig» = deterministiske alltid; judge-kriterier kun når `skill.judge` finnes (cachet i `data/judge-results.json`).

**Hardt gulv:** feiler et tilgjengelig gulv-kriterium (K1 eller K10) → `score = min(score, 89)`. En skill som ikke trigger riktig (K1) eller overlapper en søster (K10) kan aldri «bestå» 90 %, uansett form. (Anthropic: description/triggering «critical for skill selection».)

**Degradering:** mangler/stale judge → judge-kriteriene ekskluderes fra både teller og nevner; `judged:false` flagges + nudge om å kjøre judge-passet. K1-gulvet kan da ikke håndheves → `score` merkes `provisional`. K10-gulvet (deterministisk) gjelder alltid.

## 3. Komponenter (TDD, deterministisk-først)

1. **`scripts/kb-eval/eval.mjs` (utvidelse):** N1–N5 deterministiske sjekker under `deterministic`. Disk-tilgang bor her (har allerede body/frontmatter/ref-filer).
2. **`scripts/kb-eval/lib/skill-score.mjs` (NY, ren):** `scoreSkill(evalObj)` → `{name, score, rawScore, floored, judged, provisional, criteria[], improvements[], meetsTarget}`. Ingen disk — konsumerer eval-objektet → fullt testbar med fixtures.
3. **CLI `scripts/kb-eval/score-skill.mjs` (NY):** kjører eval-pipelinen → scorer alle skills → rapport. `--json`, `--gate 90` (non-zero exit + forbedringsrapport hvis noen < 90).
4. **`summarizeSkillQuality(report)` (i detection-schedule.mjs):** one-liner «Skill-kvalitet: N skills < 90 %», `null` ved alle ≥ 90. Wires i `session-start-context.mjs` (speiler kurs-/skill-signaler).

## 4. Verifisering (kjørbar)
- `node --test tests/kb-eval/test-skill-score.test.mjs` grønn: vektet aggregering, gulv kapper ved K1/K10-fail, degradering ekskluderer judge når `judge:null`, forbedringsliste sortert på poeng-tap, `meetsTarget`-grense.
- N1–N5 enhetstester i `test-eval.test.mjs` (gyldig/ugyldig name, >1024 description, nøstet ref, manglende TOC, Windows-sti).
- `score-skill.mjs --gate 90` returnerer non-zero når en fixture-skill er < 90; 0 når alle ≥ 90.
- `summarizeSkillQuality`-test (one-liner + null).
- kb-eval-suite + validate uendret-grønn (ingen regresjon).

## 5. Fase 2 (roadmap, ikke nå) — effektivitet/uplift
Anthropics *dypeste* mål: «does the skill actually help vs. no-skill baseline». Krever eval-harness (Claude-in-loop, operatør-gated) modellert på `skill-creator`s benchmark (with-skill vs baseline, `pass_rate`-delta, mean±stddev). Egen, tyngre fase — form-scoren over er nødvendig, men uplift er det endelige beviset. Spec-es separat ved opt-in.