ms-ai-architect/docs/skill-quality-scoring-plan.md

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-creators 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.