ktg-plugin-marketplace/plugins/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:** 2026-02
**Status:** [GA | Preview | Announced]
**Category:** {CATEGORY_NAME}

---

## 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 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. **Oppdater state.json:**
   - Legg til ferdige skill-IDer i `completed`
   - Legg til eventuelle feilede i `failed`
   - Oppdater `stats.total_generated` og `stats.total_bytes`
4. **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. **Commit:**
   ```bash
   git add skills/ms-ai-*/references/<dirs>/ scripts/skill-gen/state.json
   git commit -m "docs(architect): generate N knowledge skills (category-names)"
   ```

3. **Oppdater REMEMBER.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
- Markere oppdatert innhold med "Verified (MCP {måned})"
- Beholde eksisterende struktur og seksjoner

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