ktg-plugin-marketplace/plugins/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 (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:

   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