Skills
Skills zijn gestructureerde kennispakketten die elke agent zijn domeinexpertise geven. Het zijn niet alleen prompts — ze bevatten uitvoeringsprotocollen, tech-stackreferenties, codesjablonen, foutoplossingshandleidingen, kwaliteitschecklists en few-shot voorbeelden, georganiseerd in een tweelaagse architectuur ontworpen voor tokenefficiency.
Het Tweelaagse Ontwerp
Laag 1: SKILL.md (~800 bytes, altijd geladen)
Elke skill heeft een SKILL.md-bestand in de root. Dit wordt altijd in het contextvenster geladen wanneer de skill wordt gerefereerd. Het bevat:
- YAML frontmatter met
nameendescription(gebruikt voor routering en weergave) - Wanneer gebruiken / Wanneer NIET gebruiken — expliciete activeringsvoorwaarden
- Kernregels — de 5-15 meest kritieke beperkingen voor het domein
- Architectuuroverzicht — hoe code gestructureerd moet zijn
- Bibliothekenlijst — goedgekeurde afhankelijkheden en hun doelen
- Referenties — verwijzingen naar Laag 2-bronnen (worden nooit automatisch geladen)
Voorbeeld frontmatter:
---
name: oma-frontend
description: Frontend specialist for React, Next.js, TypeScript with FSD-lite architecture, shadcn/ui, and design system alignment. Use for UI, component, page, layout, CSS, Tailwind, and shadcn work.
---
Het description-veld is cruciaal — het bevat de routeringstrefwoorden die het skill-routeringssysteem gebruikt om taken aan agenten te koppelen.
Laag 2: resources/ (op aanvraag geladen)
De resources/-directory bevat diepgaande uitvoeringskennis. Deze bestanden worden alleen geladen wanneer:
- De agent expliciet wordt ingezet (via
/commandof agent skills-veld) - De specifieke resource nodig is voor het huidige taaktype en de moeilijkheidsgraad
Deze on-demand loading wordt gestuurd door de contextladingsgids (.agents/skills/_shared/core/context-loading.md), die taaktypen koppelt aan vereiste resources per agent.
Bestandsstructuur Voorbeeld
.agents/skills/oma-frontend/
├── SKILL.md ← Laag 1: altijd geladen (~800 bytes)
└── resources/
├── execution-protocol.md ← Laag 2: stap-voor-stap workflow
├── tech-stack.md ← Laag 2: gedetailleerde technologiespecificaties
├── tailwind-rules.md ← Laag 2: Tailwind-specifieke conventies
├── component-template.tsx ← Laag 2: React componentsjabloon
├── snippets.md ← Laag 2: kopieer-en-plak codepatronen
├── error-playbook.md ← Laag 2: foutherstelprocedures
├── checklist.md ← Laag 2: kwaliteitsverificatie checklist
└── examples/ ← Laag 2: few-shot invoer/uitvoer voorbeelden
└── examples.md
.agents/skills/oma-backend/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── examples.md
│ ├── orm-reference.md ← Domeinspecifiek (ORM queries, N+1, transacties)
│ ├── checklist.md
│ └── error-playbook.md
└── stack/ ← Gegenereerd door /stack-set (taalspecifiek)
├── stack.yaml
├── tech-stack.md
├── snippets.md
└── api-template.*
.agents/skills/oma-design/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── anti-patterns.md
│ ├── checklist.md
│ ├── design-md-spec.md
│ ├── design-tokens.md
│ ├── prompt-enhancement.md
│ ├── stitch-integration.md
│ └── error-playbook.md
├── reference/ ← Diepgaand referentiemateriaal
│ ├── typography.md
│ ├── color-and-contrast.md
│ ├── spatial-design.md
│ ├── motion-design.md
│ ├── responsive-design.md
│ ├── component-patterns.md
│ ├── accessibility.md
│ └── shader-and-3d.md
└── examples/
├── design-context-example.md
└── landing-page-prompt.md
Per-Skill Resourcetypen
| Resourcetype | Bestandsnaampatroon | Doel | Wanneer Geladen |
|---|---|---|---|
| Uitvoeringsprotocol | execution-protocol.md | Stap-voor-stap workflow: Analyseren -> Plannen -> Implementeren -> Verifieren | Altijd (met SKILL.md) |
| Tech Stack | tech-stack.md | Gedetailleerde technologiespecificaties, versies, configuratie | Complexe taken |
| Foutoplossingshandleiding | error-playbook.md | Herstelprocedures met "3 strikes"-escalatie | Alleen bij fouten |
| Checklist | checklist.md | Domeinspecifieke kwaliteitsverificatie | Bij Verificatiestap |
| Fragmenten | snippets.md | Kopieer-en-plak klare codepatronen | Gemiddelde/Complexe taken |
| Voorbeelden | examples.md of examples/ | Few-shot invoer/uitvoer voorbeelden voor het LLM | Gemiddelde/Complexe taken |
| Varianten | stack/-directory | Taal/framework-specifieke referenties (gegenereerd door /stack-set) | Wanneer stack bestaat |
| Sjablonen | component-template.tsx, screen-template.dart | Boilerplate bestandssjablonen | Bij componentcreatie |
| Domeinreferentie | orm-reference.md, anti-patterns.md, etc. | Diepgaande domeinkennis voor specifieke subtaken | Taaktype-specifiek |
Gedeelde Bronnen (_shared/)
Alle agenten delen gemeenschappelijke fundamenten vanuit .agents/skills/_shared/. Deze zijn georganiseerd in drie categorieen:
Kernbronnen (.agents/skills/_shared/core/)
| Resource | Doel | Wanneer Geladen |
|---|---|---|
skill-routing.md | Koppelt taaktrefwoorden aan de juiste agent. Bevat de Skill-Agent Mapping-tabel, Complex Request Routing-patronen, Inter-Agent Afhankelijkheidsregels, Escalatieregels en Beurtlimietgids. | Gerefereerd door orchestrator en coordinatie-skills |
context-loading.md | Definieert welke bronnen geladen worden voor welk taaktype en moeilijkheid. Bevat per-agent taaktype-naar-resource mappingtabellen en conditionele protocollaadtriggers. | Bij workflowstart (Stap 0 / Fase 0) |
prompt-structure.md | Definieert de vier elementen die elke taakprompt moet bevatten: Doel, Context, Beperkingen, Klaar Wanneer. Bevat sjablonen voor PM, implementatie en QA-agenten. Lijst anti-patronen (beginnen met alleen een Doel). | Gerefereerd door PM-agent en alle workflows |
clarification-protocol.md | Definieert onzekerheidsniveaus (LOW/MEDIUM/HIGH) met acties voor elk. Bevat onzekerheidstriggers, escalatiesjablonen, vereiste verificatie-items per agenttype en subagentmodusgedrag. | Wanneer requirements dubbelzinnig zijn |
context-budget.md | Tokenbudgetbeheer. Definieert bestandsleesstrategie (gebruik find_symbol niet read_file), resource loading-budgetten per modeltier (Flash: ~3.100 tokens / Pro: ~5.000 tokens), grote bestandsafhandeling en symptomen van contextoverflow. | Bij workflowstart |
difficulty-guide.md | Criteria voor het classificeren van taken als Eenvoudig/Gemiddeld/Complex. Definieert verwachte beurtaantallen, protocolvertakking (Fast Track / Standaard / Uitgebreid) en herstel bij misinschatting. | Bij taakstart (Stap 0) |
reasoning-templates.md | Gestructureerde redeneersjablonen met invulvelden voor veelvoorkomende beslissingspatronen. | Tijdens complexe beslissingen |
quality-principles.md | 4 universele kwaliteitsprincipes toegepast over alle agenten. | Bij workflowstart voor kwaliteitsgerichte workflows (ultrawork) |
vendor-detection.md | Protocol voor het detecteren van de huidige runtime-omgeving (Claude Code, Codex CLI, Gemini CLI, Antigravity, CLI Fallback). Gebruikt markercontroles: Agent tool = Claude Code, apply_patch = Codex, @-syntaxis = Gemini. | Bij workflowstart |
session-metrics.md | Clarification Debt (CD)-scoring en sessiemetrieken bijhouden. Definieert gebeurtenistypen (verduidelijking +10, correctie +25, overdoen +40), drempelwaarden (CD >= 50 = RCA, CD >= 80 = pauze) en integratiepunten. | Tijdens orchestratiesessies |
common-checklist.md | Universele kwaliteitschecklist toegepast bij eindverificatie van Complexe taken (naast agentspecifieke checklists). | Verificatiestap van Complexe taken |
lessons-learned.md | Repository van eerdere sessieleerpunten, automatisch gegenereerd uit Clarification Debt-overschrijdingen en afgewezen experimenten. Georganiseerd per domeinsectie. | Gerefereerd na fouten en aan sessieeinde |
api-contracts/ | Directory met API-contractsjabloon en gegenereerde contracten. template.md definieert het per-endpoint formaat (methode, pad, request/response schema's, auth, fouten). | Wanneer cross-boundary werk gepland is |
Runtime Bronnen (.agents/skills/_shared/runtime/)
| Resource | Doel |
|---|---|
memory-protocol.md | Geheugenbestandsformaat en -bewerkingen voor CLI-subagenten. Definieert Bij Start, Tijdens Uitvoering en Bij Voltooiing protocollen met configureerbare geheugentools (lezen/schrijven/bewerken). Bevat experimentbijhouding-extensie. |
execution-protocols/claude.md | Claude Code-specifieke uitvoeringspatronen. Geinjecteerd door oma agent:spawn wanneer leverancier claude is. |
execution-protocols/gemini.md | Gemini CLI-specifieke uitvoeringspatronen. |
execution-protocols/codex.md | Codex CLI-specifieke uitvoeringspatronen. |
execution-protocols/qwen.md | Qwen CLI-specifieke uitvoeringspatronen. |
Leverancierspecifieke uitvoeringsprotocollen worden automatisch geinjecteerd door oma agent:spawn — agenten hoeven ze niet handmatig te laden.
Conditionele Bronnen (.agents/skills/_shared/conditional/)
Deze worden alleen geladen wanneer specifieke voorwaarden worden vervuld tijdens uitvoering:
| Resource | Triggerconditie | Geladen Door | Geschatte Tokens |
|---|---|---|---|
quality-score.md | VERIFY- of SHIP-fase begint in een workflow die kwaliteitsmeting ondersteunt | Orchestrator (doorgestuurd naar QA-agentprompt) | ~250 |
experiment-ledger.md | Eerste experiment geregistreerd na het vaststellen van een IMPL-basislijn | Orchestrator (inline, na basislijnmeting) | ~250 |
exploration-loop.md | Dezelfde poort faalt twee keer op hetzelfde probleem | Orchestrator (inline, voor het spawnen van hypothese-agenten) | ~250 |
Budgetimpact: ongeveer 750 tokens totaal als alle 3 worden geladen. Aangezien laden conditioneel is, laden typische sessies 1-2 hiervan. Flash-tier budget blijft binnen de circa 3.100 token-toewijzing.
Hoe Skills Routeren via skill-routing.md
De skill-routeringskaart definieert hoe taken aan agenten worden gekoppeld:
Eenvoudige Routering (Enkel Domein)
Een prompt met "Bouw een inlogformulier met Tailwind CSS" matcht de trefwoorden UI, component, form, Tailwind, en routeert naar oma-frontend.
Complexe Verzoekroutering
Multi-domein verzoeken volgen vastgestelde uitvoeringsvolgorden:
| Verzoekpatroon | Uitvoeringsvolgorde |
|---|---|
| "Maak een fullstack-app" | oma-pm -> (oma-backend + oma-frontend) parallel -> oma-qa |
| "Maak een mobiele app" | oma-pm -> (oma-backend + oma-mobile) parallel -> oma-qa |
| "Fix bug en review" | oma-debug -> oma-qa |
| "Ontwerp en bouw een landingspagina" | oma-design -> oma-frontend |
| "Ik heb een idee voor een functie" | oma-brainstorm -> oma-pm -> relevante agenten -> oma-qa |
| "Doe alles automatisch" | oma-orchestrator (intern: oma-pm -> agenten -> oma-qa) |
Inter-Agent Afhankelijkheidsregels
Kunnen parallel draaien (geen afhankelijkheden):
- oma-backend + oma-frontend (wanneer API-contract vooraf gedefinieerd is)
- oma-backend + oma-mobile (wanneer API-contract vooraf gedefinieerd is)
- oma-frontend + oma-mobile (onafhankelijk van elkaar)
Moeten sequentieel draaien:
- oma-brainstorm -> oma-pm (ontwerp komt voor planning)
- oma-pm -> alle andere agenten (planning komt eerst)
- implementatie-agent -> oma-qa (review na implementatie)
- oma-backend -> oma-frontend/oma-mobile (wanneer geen vooraf gedefinieerd API-contract)
QA is altijd laatste, behalve wanneer de gebruiker review van specifieke bestanden aanvraagt.
Tokenbesparingsberekening
Overweeg een 5-agent orchestratiesessie (pm, backend, frontend, mobile, qa):
Zonder progressieve onthulling:
- Elke agent laadt alle bronnen: ~4.000 tokens per agent
- Totaal: 5 x 4.000 = 20.000 tokens verbruikt voordat er werk begint
Met progressieve onthulling:
- Alleen Laag 1 voor alle agenten: 5 x 800 = 4.000 tokens
- Laag 2 alleen geladen voor actieve agenten (typisch 1-2 tegelijk): +1.500 tokens
- Totaal: ~5.500 tokens
Besparing: ongeveer 72-75%
Op flash-tier modellen (128K context) is dit het verschil tussen 108K tokens beschikbaar voor werk versus 125K tokens — een aanzienlijke marge voor complexe taken.
Resource Loading per Taakmoeilijkheid
De moeilijkheidsgids classificeert taken in drie niveaus, die bepalen hoeveel van Laag 2 wordt geladen:
Eenvoudig (3-5 beurten verwacht)
Enkele bestandswijziging, duidelijke requirements, herhaling van bestaande patronen.
Laadt: alleen execution-protocol.md. Sla analyse over, ga direct naar implementatie met minimale checklist.
Gemiddeld (8-15 beurten verwacht)
2-3 bestandswijzigingen, enige ontwerpbeslissingen nodig, patronen toepassen op nieuwe domeinen.
Laadt: execution-protocol.md + examples.md. Standaardprotocol met korte analyse en volledige verificatie.
Complex (15-25 beurten verwacht)
4+ bestandswijzigingen, architectuurbeslissingen vereist, nieuwe patronen introduceren, afhankelijkheden van andere agenten.
Laadt: execution-protocol.md + examples.md + tech-stack.md + snippets.md. Uitgebreid protocol met checkpoints, tussentijdse voortgangsregistratie en volledige verificatie inclusief common-checklist.md.
Context-Loading Taakkaarten (Per Agent)
De contextladingsgids biedt gedetailleerde taaktype-naar-resource mappings. Hier zijn de belangrijkste mappings:
Backend Agent
| Taaktype | Vereiste Bronnen |
|---|---|
| CRUD API-creatie | stack/snippets.md (route, schema, model, test) |
| Authenticatie | stack/snippets.md (JWT, wachtwoord) + stack/tech-stack.md |
| DB-migratie | stack/snippets.md (migratie) |
| Prestatieoptimalisatie | examples.md (N+1 voorbeeld) |
| Bestaande code aanpassen | examples.md + Serena MCP |
Frontend Agent
| Taaktype | Vereiste Bronnen |
|---|---|
| Componentcreatie | snippets.md + component-template.tsx |
| Formulierimplementatie | snippets.md (formulier + Zod) |
| API-integratie | snippets.md (TanStack Query) |
| Styling | tailwind-rules.md |
| Paginalayout | snippets.md (grid) + examples.md |
Design Agent
| Taaktype | Vereiste Bronnen |
|---|---|
| Designsysteemcreatie | reference/typography.md + reference/color-and-contrast.md + reference/spatial-design.md + design-md-spec.md |
| Landingspagina-ontwerp | reference/component-patterns.md + reference/motion-design.md + prompt-enhancement.md + examples/landing-page-prompt.md |
| Designaudit | checklist.md + anti-patterns.md |
| Design token-export | design-tokens.md |
| 3D / shader-effecten | reference/shader-and-3d.md + reference/motion-design.md |
| Toegankelijkheidsreview | reference/accessibility.md + checklist.md |
QA Agent
| Taaktype | Vereiste Bronnen |
|---|---|
| Beveiligingsreview | checklist.md (Beveiligingssectie) |
| Prestatiereview | checklist.md (Prestatiesectie) |
| Toegankelijkheidsreview | checklist.md (Toegankelijkheidssectie) |
| Volledige audit | checklist.md (volledig) + self-check.md |
| Kwaliteitsscore | quality-score.md (conditioneel) |
Orchestrator Promptsamenstelling
Wanneer de orchestrator prompts samenstelt voor subagenten, bevat deze alleen taakrelevante bronnen:
- De Kernregels-sectie van de agent SKILL.md
execution-protocol.md- Bronnen die overeenkomen met het specifieke taaktype (uit bovenstaande kaarten)
error-playbook.md(altijd inbegrepen — herstel is essentieel)- Serena Memory Protocol (CLI-modus)
Deze gerichte samenstelling voorkomt het laden van onnodige bronnen, waardoor de beschikbare context van de subagent voor daadwerkelijk werk wordt gemaximaliseerd.