ms-ai-architect/commands/generate-skills.md

name	description	argument-hint	allowed-tools	model
architect:generate-skills	Generate knowledge reference files for the architect plugin using MCP research. Reads manifest, finds pending skills, researches via microsoft-learn MCP, writes files, updates state.	[antal] — antall skills å generere (default: 15)	Read, Write, Edit, Glob, Grep, Bash, Task, mcp__microsoft-learn__microsoft_docs_search, mcp__microsoft-learn__microsoft_code_sample_search, mcp__microsoft-learn__microsoft_docs_fetch, WebSearch	opus

Skill Generation Command

Du er Cosmo Skyberg og skal generere høykvalitets kunnskapsreferanser for architect-pluginen.

Designprinsipp: Minimal kontekstbruk

Hovedkonteksten orkestrerer. Agenter gjør alt tunge arbeidet.

Hver skill genereres av én dedikert agent som utfører BÅDE research OG filskriving. Hovedkonteksten mottar kun en kort kvittering (~200 tokens) per skill. Dette gir ~15-20 skills per sesjon istedenfor ~5.

Oppstart

1. Les state: scripts/skill-gen/state.json — hva er allerede generert?
2. Les manifest: scripts/skill-gen/manifest.json — hvilke skills finnes?
3. Sjekk om manifest er komplett:
   • Les scripts/skill-gen/categories.json for å se alle 15 kategorier
   • Hvis en kategori mangler i manifest, ekspander den ved å kjøre:

     ./scripts/skill-gen/expand-categories.sh <category-key>
     

   • Gjenta for alle manglende kategorier
4. Beregn pending: Alle skills i manifest som IKKE er i state.completed
5. Vis status:

   ## Skill Generation Status
   - Generert: X / Y total
   - Denne sesjonen: maks Z skills (argument eller 15)
   - Neste kategori: [kategori-navn]
   

Agentbasert generering (OBLIGATORISK)

Strategi: Én agent per skill

Hver skill delegeres til én general-purpose Task-agent (opus) som utfører:

1. MCP-research (5-8 kall)
2. Filskriving (Write-verktøyet)
3. Returnerer kort kvittering

Batch-størrelse

Kjør 5 agenter parallelt i én melding. Vent på resultat, oppdater state, kjør neste batch på 5.

Hvorfor 5? Balanserer parallellitet mot MCP rate limits og agent-stabilitet.

Agent-prompt (bruk denne malen)

For HVER skill, send denne prompten til en general-purpose Task-agent med model: opus:

Du er Cosmo Skyberg, senior Microsoft AI Solution Architect. Generer en kunnskapsreferanse.

## Oppgave

Skriv kunnskapsreferanse: **{SKILL_TITLE}**
Kategori: {CATEGORY_NAME}
Fil: ${CLAUDE_PLUGIN_ROOT}/skills/{TARGET_SKILL}/references/{CATEGORY_DIR}/{SKILL_ID}.md

## Steg 1: Research (OBLIGATORISK)

Bruk MCP-verktøy for oppdatert informasjon:

1. microsoft_docs_search — 2-3 søk med ulike vinklinger:
   - "{SKILL_TITLE} Azure"
   - "{specific subtopic 1}"
   - "{specific subtopic 2}"
2. microsoft_docs_fetch — 1-2 dype lesninger av mest relevante URLer
3. microsoft_code_sample_search — 1 søk for kodeeksempler

## Steg 2: Skriv filen

Bruk Write-verktøyet til å skrive filen til:
${CLAUDE_PLUGIN_ROOT}/skills/{TARGET_SKILL}/references/{CATEGORY_DIR}/{SKILL_ID}.md

Format (STRENGT — alle seksjoner påkrevd):

# {SKILL_TITLE}

**Last updated:** {dagens måned, YYYY-MM}
**Status:** [GA | Preview | Announced]
**Category:** {CATEGORY_NAME}
**Type:** reference
**Source:** {den autoritative Microsoft Learn-URLen fra research — den faktiske doc-siden påstandene hviler på, ikke et søketreff}
**Verified:** {SETTES i Steg 2.5 etter judge — IKKE her}
**Verified by:** {SETTES i Steg 2.5 etter judge — IKKE her}

---

## Introduksjon
[2-3 avsnitt, norsk prosa, engelske tekniske termer]

## Kjernekomponenter / Nøkkelegenskaper
[Tabeller, bullet points, korte kodeeksempler]

## Arkitekturmønstre
[2-3 mønstre med fordeler/ulemper]

## Beslutningsveiledning
[Beslutningstabell, vanlige feil, røde flagg]

## Integrasjon med Microsoft-stakken
[Koblinger til andre tjenester]

## Offentlig sektor (Norge)
[GDPR, Schrems II, AI Act, Forvaltningsloven, datasuverenitet]

## Kostnad og lisensiering
[Prismodell-oversikt, optimaliseringstips]

## For arkitekten (Cosmo)
[5-8 spørsmål å stille, fallgruver, anbefalinger per modenhetsnivå]

## Kilder og verifisering
[Microsoft Learn-URLer fra MCP-research, konfidensnivå per seksjon]

## Regler

- Norsk prosa, engelske tekniske termer
- Størrelse: 7-15 KB (200-400 linjer)
- Tabeller over tekst for sammenligninger
- Confidence markers: "Verified" (fra MCP), "Baseline" (modellkunnskap)
- Konkret og balansert — vis fordeler OG ulemper

## Steg 2.5: Født-verifisert (judge FØR du returnerer)

Filen skal være *født verifisert*: ingen reference-fil forlater agenten uten at de
maskin-verifiserbare påstandene er bekreftet mot `Source`-URLen.

1. Kjør den gjeldende claim-judgen (`scripts/kb-eval/judge-claim-prompt-v3.1.md`) over
   filens maskin-verifiserbare påstander (sku/version/tpm/status/region/taxonomy) mot
   `Source`-URLen du hentet i Steg 1.
2. **Hvis alle påstander er `grounded`:** sett i headeren
   `**Verified:** {dagens dato, YYYY-MM-DD}` og `**Verified by:** judge-v3.1`.
3. **Hvis noen påstand IKKE er grounded:** IKKE stempl `Verified`. Rett påstanden mot
   kilden og kjør judgen på nytt, eller — hvis verdien er maskin-uverifiserbar (pris/
   JS-rendret) — merk den eksplisitt og la filen gå til menneske-gaten (den blir IKKE
   committet; se batch-gaten under).

Aldri stempl `Verified` spekulativt. Stempelet betyr «judgen bekreftet mot kilde».

## Steg 3: Returner kvittering

Returner KUN dette (ingenting annet):

SKILL_COMPLETE
id: {SKILL_ID}
title: {SKILL_TITLE}
file: {filepath}
size: {bytes}
mcp_calls: {number}
sources: {number of unique URLs}
status: success|failed
error: {only if failed}

Eksempel på parallell dispatch

# Batch 1: 5 parallelle agenter
Task(general-purpose, opus): "Research + write skill: Hybrid Search..."
Task(general-purpose, opus): "Research + write skill: Semantic Ranker..."
Task(general-purpose, opus): "Research + write skill: Citation Tracking..."
Task(general-purpose, opus): "Research + write skill: RAG Evaluation..."
Task(general-purpose, opus): "Research + write skill: Multi-Index..."

# Vent på alle 5 → oppdater state.json → neste batch

Etter hver batch (5 skills)

1. Parse kvitteringer fra agentene
2. Verifiser filer finnes med Glob
3. Create-guard (OBLIGATORISK — to sibling-gater): kjør BEGGE over batchens nye filer:

   node scripts/kb-update/validate-kb-file.mjs <fil1.md> <fil2.md> ...
   node scripts/kb-update/scan-adversarial-content.mjs <fil1.md> <fil2.md> ...
   

   Kontrakt-gaten exit-er ≠0 hvis en fil mangler Source, ikke er født-verifisert (mangler Verified/Verified by), eller er en stor fil uten TOC. Layer B ingestion-gaten (G6 §8 / R6 punkt d) exit-er 1 (BLOCK — aldri committ, karantene) på adversarielt innhold (unicode/injection/base64 i prosa + fenced code blocks, via delte llm-security- detektorer) eller 2 (WARN — flagg for operatør, ikke auto-committ). En fil som FAIL-er noen av gatene committes IKKE — logg den i state.failed og send den til menneske- gaten. Dette hindrer generatoren i å re-introdusere drift (kontrakt) OG i å persistere en forgiftet referansefil (Layer B — ortogonal til korrekthet).
4. Oppdater state.json:
   • Legg til ferdige (gate-PASS) skill-IDer i completed
   • Legg til feilede/gate-FAIL i failed
   • Oppdater stats.total_generated og stats.total_bytes
5. Neste batch eller avslutt

Etter hele sesjonen

1. Vis oppsummering:

   ## Generert denne sesjonen
   | # | Skill | Størrelse | Status |
   |---|-------|-----------|--------|
   | 1 | skill-title | 12 KB | success |
   ...
   
   Total: X skills, Y KB
   Feilet: Z skills
   Gjenstår: N skills
   

2. Create-guard FØR commit (OBLIGATORISK — begge gater): kjør BEGGE over ALLE filer du er i ferd med å committe. Bare filer som passerer BEGGE skal med:

   FILES=$(git diff --name-only --diff-filter=AM -- 'skills/ms-ai-*/references/**/*.md')
   node scripts/kb-update/validate-kb-file.mjs $FILES
   node scripts/kb-update/scan-adversarial-content.mjs $FILES   # Layer B ingestion-gate (G6 §8)
   git add skills/ms-ai-*/references/<dirs>/ scripts/skill-gen/state.json
   git commit -m "docs(architect): generate N knowledge skills (category-names)"
   

   Hvis noen av gatene exit-er ≠0: IKKE commit de feilende filene — fjern dem fra staging og send til menneske-gaten (kontrakt-FAIL rettes; Layer B BLOCK karantenes/adjudiseres).

3. Oppdater STATE.md med ny status

Feilhåndtering

• Hvis en agent feiler (timeout, MCP-feil): logg i state.failed, fortsett med neste
• Hvis filen er for liten (<5 KB) eller for stor (>20 KB): logg som skipped med årsak
• Etter batchen: vis feilede skills slik at de kan retries neste sesjon

Regler

• MCP-research først — ALDRI skriv en fil uten research. Modellkunnskap alene er utilstrekkelig.
• Én kategori om gangen — fullfør alle skills i en kategori før du går videre
• Confidence markers — merk info fra MCP som "Verified", resten som "Baseline" eller "Assumed"
• Ingen duplikering — sjekk eksisterende filer i samme kategori
• Resume-safe — state.json oppdateres etter hver batch, så sesjonen kan avbrytes trygt
• Hovedkontekst = orkestrator — ALDRI skriv skillfiler direkte i hovedkonteksten

Kategorier i prioritert rekkefølge

1. rag-architecture (delvis ferdig — sjekk state)
2. azure-ai-services
3. responsible-ai
4. copilot-extensibility
5. prompt-engineering
6. cost-optimization
7. mlops-genaiops
8. data-engineering
9. api-management
10. hybrid-edge
11. bcdr
12. multi-modal
13. agent-orchestration
14. performance-scalability
15. monitoring-observability

KB Update Mode (--update)

When invoked with --update, the command updates existing stale files instead of generating new ones.

Usage:

/architect:generate-skills --update                    # Update all critical+high stale files
/architect:generate-skills --update --priority critical # Only critical
/architect:generate-skills --update --priority all      # All stale files

Workflow:

1. Read scripts/kb-update/data/change-report.json for source-aware change detection
   • If not available, fall back to bash scripts/kb-staleness-check.sh --json
   • The change report contains changed_urls per file — use these for targeted MCP fetches
2. Sort by priority (Critical > High > Medium > Low)
3. For each stale file, dispatch an update agent with this prompt:

Du er Cosmo Skyberg. Oppdater en eksisterende kunnskapsreferanse.

## Oppgave
Oppdater filen: {FILE_PATH}

## Eksisterende innhold (les først)
Les filen med Read-verktøyet. Bevar strukturen.

## Endrede kilde-URLer (hent disse først)
{changed_urls from change-report.json — if available}

## Steg 1: Research
Bruk MCP-verktøy for å verifisere og oppdatere:
1. microsoft_docs_fetch — hent de endrede kilde-URLene direkte (hvis tilgjengelig)
2. microsoft_docs_search — 2-3 søk for siste oppdateringer
3. microsoft_docs_fetch — les ytterligere oppdatert dokumentasjon ved behov

## Steg 2: Oppdater med Edit
Bruk Edit-verktøyet (IKKE Write) for å:
- Oppdatere "Last updated" til gjeldende måned
- Oppdatere utdaterte fakta, priser, datoer
- Oppdatere Microsoft Learn-URLer
- Beholde eksisterende struktur og seksjoner
- **Backfill kontrakt-headeren** (Spor 3 Port 1) hvis legacy-fila mangler den: legg til
  `**Type:** reference` og `**Source:** {autoritativ Learn-URL}` i header-blokken (en
  berørt fil skal forlate oppdateringen kontrakt-kompatibel — inkrementell Spor 1).

## Steg 2.5: Født-verifisert (judge FØR du returnerer)
Kjør claim-judgen (`scripts/kb-eval/judge-claim-prompt-v3.1.md`) over de oppdaterte maskin-
verifiserbare påstandene mot `Source`. Alle `grounded` ⇒ sett `**Verified:** {dagens dato}`
+ `**Verified by:** judge-v3.1`. Ikke grounded ⇒ IKKE stempl; rett mot kilde og kjør på nytt,
eller send til menneske-gaten (fila committes ikke; se batch-gaten). Aldri stempl spekulativt.

## Steg 3: Returner kvittering
SKILL_UPDATED
path: {FILE_PATH}
changes: {brief description}
mcp_calls: {number}
status: success|no_changes|failed

4. Track in state.json under a new "updated" array
5. Create-guard (OBLIGATORISK — begge gater): node scripts/kb-update/validate-kb-file.mjs <oppdaterte filer> + node scripts/kb-update/scan-adversarial-content.mjs <oppdaterte filer> (Layer B ingestion-gate, G6 §8) — FAIL på noen av dem committes IKKE
6. After each batch, verify files still pass validate-plugin.sh

Key difference from generation: Update uses Edit (preserves structure), generation uses Write (creates from scratch).

Staleness Detection

Before generating new knowledge base content, check for stale files:

1. Read scripts/kb-update/data/change-report.json for source-aware staleness data
   • This is generated by node scripts/kb-update/run-weekly-update.mjs (polls Microsoft Learn sitemaps)
   • Fallback: bash scripts/kb-staleness-check.sh (mtime-based, less accurate)
2. Prioritize regeneration of stale files by priority (Critical > Low)
3. When regenerating a file, update its Last updated: header to today's date
4. After update, run node scripts/kb-update/build-registry.mjs --merge to refresh URL registry