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

---
name: architect:generate-skills
description: 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.
argument-hint: "[antal] — antall skills å generere (default: 15)"
allowed-tools: 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
model: 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:
     ```bash
     ./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 (sonnet) 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: sonnet`:

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

## Oppgave

Skriv kunnskapsreferanse: **{SKILL_TITLE}**
Kategori: {CATEGORY_NAME}
Fil: 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:
{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, sonnet): "Research + write skill: Hybrid Search..."
Task(general-purpose, sonnet): "Research + write skill: Semantic Ranker..."
Task(general-purpose, sonnet): "Research + write skill: Citation Tracking..."
Task(general-purpose, sonnet): "Research + write skill: RAG Evaluation..."
Task(general-purpose, sonnet): "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:
   ```bash
   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:
   ```bash
   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