Compétences
Les compétences sont des paquets de connaissances structurés qui confèrent à chaque agent son expertise de domaine. Ce ne sont pas de simples prompts -- elles contiennent des protocoles d'exécution, des références de stack technique, des modèles de code, des guides de résolution d'erreurs, des checklists de qualité et des exemples few-shot, organisés dans une architecture en deux couches conçue pour l'efficacité en tokens.
La conception en deux couches
Couche 1 : SKILL.md (~800 octets, toujours chargée)
Chaque compétence possède un fichier SKILL.md à sa racine. Celui-ci est toujours chargé dans la fenêtre de contexte lorsque la compétence est référencée. Il contient :
- Frontmatter YAML avec
nameetdescription(utilisé pour le routage et l'affichage) - Quand utiliser / Quand NE PAS utiliser -- conditions d'activation explicites
- Règles fondamentales -- les 5 à 15 contraintes les plus critiques du domaine
- Aperçu de l'architecture -- comment le code doit être structuré
- Liste des bibliothèques -- dépendances approuvées et leurs usages
- Références -- pointeurs vers les ressources de la couche 2 (jamais chargées automatiquement)
Exemple de 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.
---
Le champ description est essentiel -- il contient les mots-clés de routage que le système de routage des compétences utilise pour faire correspondre les tâches aux agents.
Couche 2 : resources/ (chargement à la demande)
Le répertoire resources/ contient les connaissances d'exécution approfondies. Ces fichiers ne sont chargés que lorsque :
- L'agent est explicitement invoqué (via
/commandou le champ skills de l'agent) - La ressource spécifique est nécessaire pour le type de tâche et le niveau de difficulté en cours
Ce chargement à la demande est régi par le guide de chargement du contexte (.agents/skills/_shared/core/context-loading.md), qui associe les types de tâches aux ressources requises par agent.
Exemple de structure de fichiers
.agents/skills/oma-frontend/
├── SKILL.md ← Layer 1: always loaded (~800 bytes)
└── resources/
├── execution-protocol.md ← Layer 2: step-by-step workflow
├── tech-stack.md ← Layer 2: detailed technology specs
├── tailwind-rules.md ← Layer 2: Tailwind-specific conventions
├── component-template.tsx ← Layer 2: React component template
├── snippets.md ← Layer 2: copy-paste code patterns
├── error-playbook.md ← Layer 2: error recovery procedures
├── checklist.md ← Layer 2: quality verification checklist
└── examples/ ← Layer 2: few-shot input/output examples
└── examples.md
.agents/skills/oma-backend/
├── SKILL.md
├── resources/
│ ├── execution-protocol.md
│ ├── examples.md
│ ├── orm-reference.md ← Domain-specific (ORM queries, N+1, transactions)
│ ├── checklist.md
│ └── error-playbook.md
└── stack/ ← Generated by /stack-set (language-specific)
├── 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/ ← Deep reference material
│ ├── 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
Types de ressources par compétence
| Resource Type | Filename Pattern | Purpose | When Loaded |
|---|---|---|---|
| Execution Protocol | execution-protocol.md | Step-by-step workflow: Analyze -> Plan -> Implement -> Verify | Always (with SKILL.md) |
| Tech Stack | tech-stack.md | Detailed technology specs, versions, configuration | Complex tasks |
| Error Playbook | error-playbook.md | Recovery procedures with "3 strikes" escalation | On error only |
| Checklist | checklist.md | Domain-specific quality verification | At Verify step |
| Snippets | snippets.md | Copy-paste ready code patterns | Medium/Complex tasks |
| Examples | examples.md or examples/ | Few-shot input/output examples for the LLM | Medium/Complex tasks |
| Variants | stack/ directory | Language/framework-specific references (generated by /stack-set) | When stack exists |
| Templates | component-template.tsx, screen-template.dart | Boilerplate file templates | On component creation |
| Domain Reference | orm-reference.md, anti-patterns.md, etc. | Deep domain knowledge for specific subtasks | Task-type specific |
Ressources partagées (_shared/)
Tous les agents partagent des fondations communes depuis .agents/skills/_shared/. Celles-ci sont organisées en trois catégories :
Ressources centrales (.agents/skills/_shared/core/)
| Resource | Purpose | When Loaded |
|---|---|---|
skill-routing.md | Maps task keywords to the correct agent. Contains the Skill-Agent Mapping table, Complex Request Routing patterns, Inter-Agent Dependency Rules, Escalation Rules, and Turn Limit Guide. | Referenced by orchestrator and coordination skills |
context-loading.md | Defines which resources to load for which task type and difficulty. Contains per-agent task-type-to-resource mapping tables and conditional protocol loading triggers. | At workflow start (Step 0 / Phase 0) |
prompt-structure.md | Defines the four elements every task prompt must contain: Goal, Context, Constraints, Done When. Includes templates for PM, implementation, and QA agents. Lists anti-patterns (starting with only a Goal). | Referenced by PM agent and all workflows |
clarification-protocol.md | Defines uncertainty levels (LOW/MEDIUM/HIGH) with actions for each. Contains uncertainty triggers, escalation templates, required verification items per agent type, and subagent-mode behavior. | When requirements are ambiguous |
context-budget.md | Token budget management. Defines file reading strategy (use find_symbol not read_file), resource loading budgets per model tier (Flash: ~3,100 tokens / Pro: ~5,000 tokens), large file handling, and context overflow symptoms. | At workflow start |
difficulty-guide.md | Criteria for classifying tasks as Simple/Medium/Complex. Defines expected turn counts, protocol branching (Fast Track / Standard / Extended), and misjudgment recovery. | At task start (Step 0) |
reasoning-templates.md | Structured reasoning fill-in-the-blank templates for common decision patterns (e.g., Exploration Decision template #6 used by the Exploration Loop). | During complex decisions |
quality-principles.md | 4 universal quality principles applied across all agents. | At workflow start for quality-focused workflows (ultrawork) |
vendor-detection.md | Protocol for detecting the current runtime environment (Claude Code, Codex CLI, Gemini CLI, Antigravity, CLI Fallback). Uses marker checks: Agent tool = Claude Code, apply_patch = Codex, @-syntax = Gemini. | At workflow start |
session-metrics.md | Clarification Debt (CD) scoring and session metrics tracking. Defines event types (clarify +10, correct +25, redo +40), thresholds (CD >= 50 = RCA, CD >= 80 = pause), and integration points. | During orchestration sessions |
common-checklist.md | Universal quality checklist applied at final verification of Complex tasks (in addition to agent-specific checklists). | Verify step of Complex tasks |
lessons-learned.md | Repository of past session learnings, auto-generated from Clarification Debt breaches and discarded experiments. Organized by domain section. | Referenced after errors and at session end |
api-contracts/ | Directory containing API contract template and generated contracts. template.md defines the per-endpoint format (method, path, request/response schemas, auth, errors). | When cross-boundary work is planned |
Ressources d'exécution (.agents/skills/_shared/runtime/)
| Resource | Purpose |
|---|---|
memory-protocol.md | Memory file format and operations for CLI subagents. Defines On Start, During Execution, and On Completion protocols using configurable memory tools (read/write/edit). Includes experiment tracking extension. |
execution-protocols/claude.md | Claude Code-specific execution patterns. Injected by oma agent:spawn when vendor is claude. |
execution-protocols/gemini.md | Gemini CLI-specific execution patterns. |
execution-protocols/codex.md | Codex CLI-specific execution patterns. |
execution-protocols/qwen.md | Qwen CLI-specific execution patterns. |
Les protocoles d'exécution spécifiques au fournisseur sont injectés automatiquement par oma agent:spawn -- les agents n'ont pas besoin de les charger manuellement.
Ressources conditionnelles (.agents/skills/_shared/conditional/)
Celles-ci ne sont chargées que lorsque des conditions spécifiques sont remplies pendant l'exécution :
| Resource | Trigger Condition | Loaded By | Approx. Tokens |
|---|---|---|---|
quality-score.md | VERIFY or SHIP phase begins in a workflow that supports quality measurement | Orchestrator (passes to QA agent prompt) | ~250 |
experiment-ledger.md | First experiment is recorded after establishing an IMPL baseline | Orchestrator (inline, after baseline measurement) | ~250 |
exploration-loop.md | Same gate fails twice on the same issue | Orchestrator (inline, before spawning hypothesis agents) | ~250 |
Impact sur le budget : environ 750 tokens au total si les 3 sont chargées. Comme le chargement est conditionnel, les sessions typiques en chargent 1 à 2. Le budget de niveau flash reste dans l'allocation d'environ 3 100 tokens.
Comment les compétences sont routées via skill-routing.md
La carte de routage des compétences définit comment les tâches sont associées aux agents :
Routage simple (domaine unique)
Un prompt contenant « Build a login form with Tailwind CSS » correspond aux mots-clés UI, component, form, Tailwind, et est routé vers oma-frontend.
Routage de requêtes complexes
Les requêtes multi-domaines suivent des ordres d'exécution établis :
| Request Pattern | Execution Order |
|---|---|
| "Create a fullstack app" | oma-pm -> (oma-backend + oma-frontend) parallel -> oma-qa |
| "Create a mobile app" | oma-pm -> (oma-backend + oma-mobile) parallel -> oma-qa |
| "Fix bug and review" | oma-debug -> oma-qa |
| "Design and build a landing page" | oma-design -> oma-frontend |
| "I have an idea for a feature" | oma-brainstorm -> oma-pm -> relevant agents -> oma-qa |
| "Do everything automatically" | oma-orchestrator (internally: oma-pm -> agents -> oma-qa) |
Règles de dépendance inter-agents
Peuvent s'exécuter en parallèle (pas de dépendances) :
- oma-backend + oma-frontend (when API contract is pre-defined)
- oma-backend + oma-mobile (when API contract is pre-defined)
- oma-frontend + oma-mobile (independent of each other)
Doivent s'exécuter séquentiellement :
- oma-brainstorm -> oma-pm (design comes before planning)
- oma-pm -> all other agents (planning comes first)
- implementation agent -> oma-qa (review after implementation)
- oma-backend -> oma-frontend/oma-mobile (when no pre-defined API contract)
Le QA est toujours en dernier, sauf lorsque l'utilisateur demande la revue de fichiers spécifiques uniquement.
Calcul des économies de tokens
Considérons une session d'orchestration à 5 agents (pm, backend, frontend, mobile, qa) :
Sans divulgation progressive :
- Each agent loads all resources: ~4,000 tokens per agent
- Total: 5 x 4,000 = 20,000 tokens consumed before any work
Avec divulgation progressive :
- Layer 1 only for all agents: 5 x 800 = 4,000 tokens
- Layer 2 loaded only for active agents (typically 1-2 at a time): +1,500 tokens
- Total: ~5,500 tokens
Économies : environ 72-75 %
Sur les modèles de niveau flash (contexte 128 Ko), c'est la différence entre avoir 108 Ko de tokens disponibles pour le travail contre 125 Ko -- une marge significative pour les tâches complexes.
Chargement des ressources par difficulté de tâche
Le guide de difficulté classe les tâches en trois niveaux, qui déterminent la quantité de couche 2 chargée :
Simple (3-5 tours attendus)
Modification d'un seul fichier, exigences claires, répétition de patterns existants.
Charge : execution-protocol.md uniquement. Passer l'analyse, procéder directement à l'implémentation avec une checklist minimale.
Moyen (8-15 tours attendus)
2-3 modifications de fichiers, quelques décisions de conception nécessaires, application de patterns à de nouveaux domaines.
Charge : execution-protocol.md + examples.md. Protocole standard avec analyse brève et vérification complète.
Complexe (15-25 tours attendus)
4+ modifications de fichiers, décisions d'architecture requises, introduction de nouveaux patterns, dépendances avec d'autres agents.
Charge : execution-protocol.md + examples.md + tech-stack.md + snippets.md. Protocole étendu avec points de contrôle, enregistrement de la progression en cours d'exécution, et vérification complète incluant common-checklist.md.
Cartes de chargement du contexte par tâche (par agent)
Le guide de chargement du contexte fournit des mappings détaillés type-de-tâche/ressources. Voici les principaux mappings :
Agent Backend
| Task Type | Required Resources |
|---|---|
| CRUD API creation | stack/snippets.md (route, schema, model, test) |
| Authentication | stack/snippets.md (JWT, password) + stack/tech-stack.md |
| DB migration | stack/snippets.md (migration) |
| Performance optimization | examples.md (N+1 example) |
| Existing code modification | examples.md + Serena MCP |
Agent Frontend
| Task Type | Required Resources |
|---|---|
| Component creation | snippets.md + component-template.tsx |
| Form implementation | snippets.md (form + Zod) |
| API integration | snippets.md (TanStack Query) |
| Styling | tailwind-rules.md |
| Page layout | snippets.md (grid) + examples.md |
Agent Design
| Task Type | Required Resources |
|---|---|
| Design system creation | reference/typography.md + reference/color-and-contrast.md + reference/spatial-design.md + design-md-spec.md |
| Landing page design | reference/component-patterns.md + reference/motion-design.md + prompt-enhancement.md + examples/landing-page-prompt.md |
| Design audit | checklist.md + anti-patterns.md |
| Design token export | design-tokens.md |
| 3D / shader effects | reference/shader-and-3d.md + reference/motion-design.md |
| Accessibility review | reference/accessibility.md + checklist.md |
Agent QA
| Task Type | Required Resources |
|---|---|
| Security review | checklist.md (Security section) |
| Performance review | checklist.md (Performance section) |
| Accessibility review | checklist.md (Accessibility section) |
| Full audit | checklist.md (full) + self-check.md |
| Quality scoring | quality-score.md (conditional) |
Composition des prompts par l'orchestrateur
Lorsque l'orchestrateur compose les prompts pour les sous-agents, il n'inclut que les ressources pertinentes pour la tâche :
- Agent SKILL.md's Core Rules section
execution-protocol.md- Resources matching the specific task type (from the maps above)
error-playbook.md(always included — recovery is essential)- Serena Memory Protocol (CLI mode)
Cette composition ciblée évite le chargement de ressources inutiles, maximisant le contexte disponible du sous-agent pour le travail effectif.