---
id: "b76431d7-f3a3-438f-ae3f-5648f5eda8ce"
number: 119
title: "Refondre le système de skills IdeA en capacités agent découvrables"
status: "qa"
priority: "high"
sprint: null
links: []
agentRefs: []
attachments: []
createdBy: {"kind":"agent","agent_id":"a6ced819-b893-4213-b003-9e9dc79b9641"}
updatedBy: {"kind":"agent","agent_id":"a6c6ea12-bfc6-4bdc-8031-324102dfa34d"}
createdAt: 1785534242629
updatedAt: 1785748044163
version: 3
---
## Constat

Le système actuel de skills IdeA est techniquement fonctionnel, mais conceptuellement centré sur l'injection de contenu plutôt que sur l'exposition de capacités agent.

État actuel confirmé dans le code :
- `Skill` + `SkillRef` avec deux scopes `global` / `project`.
- assignation des skills sur les agents via le manifeste.
- résolution au lancement, puis composition du contexte effectif.
- en mode MCP : bloc `# Skills disponibles` + lazy-load via `idea_skill_read(name)`.
- en mode non-MCP : dump complet du corps des skills dans le contexte.
- `idea_list_agents` retourne la forme `Agent` du manifeste, donc seulement des `SkillRef` bruts (`skillId` + `scope`), pas un inventaire de capacités utile à un agent ou à Main.

Le défaut de fond est que le catalogue de skills n'existe pas comme objet métier interrogeable. Il n'existe qu'au moment du rendu markdown dans `compose_convention_file`. Le système se comporte donc comme un mécanisme d'injection de documentation, puis simule partiellement une surface de capacités en mode MCP.

## Problèmes à résoudre

1. Les skills assignés ne sont pas modélisés comme un inventaire de capacités agent de premier ordre.
2. `idea_list_agents` ne permet pas de savoir ce que les autres agents savent faire, seulement quels `SkillRef` opaques leur sont assignés.
3. L'asymétrie MCP / non-MCP est un patch : mode MCP = affordances bornées, mode non-MCP = dump lourd.
4. Le système ne distingue pas explicitement un skill procédural (`workflow`) d'un skill de référence (`reference`).
5. Le modèle actuel n'est pas pleinement aligné avec la frontière produit déjà actée : surface AGENT bornée/distillée/pointeur ; surface HUMAINE riche.

## Cible produit / architecture

Faire évoluer les skills IdeA d'un modèle "contenu injecté" vers un modèle "capacités agent assignées et découvrables".

### Décisions cibles

- Garder :
  - l'entité `Skill`.
  - les scopes `global` / `project`.
  - `SkillRef` dans le manifeste agent.
  - `idea_skill_read(name)` comme primitive de lazy-load autorisée uniquement sur les skills assignés au requester.

- Ajouter :
  - une nature explicite de skill, par exemple `SkillKind` avec au minimum :
    - `Workflow` : procédure exécutable à la demande.
    - `Reference` : savoir consultable, plus proche d'un contexte sélectif.

- Extraire un use case applicatif réutilisable, type :
  - `ResolveAgentCapabilities(agent) -> [{ name, description, kind }]`

Ce use case devient la source de vérité commune pour :
- le bloc `# Skills disponibles` injecté dans le contexte agent.
- l'exposition des capacités d'un agent dans les surfaces de découverte.

### Arbitrages

- Ne pas créer de `idea_list_skills` global.
  - Les skills ne sont pas des tools MCP uniformes de session.
  - Ce sont des capacités portées par un agent.
  - La bonne surface de découverte inter-agent est donc `idea_list_agents` enrichi, pas un catalogue global détaché des porteurs.

- Enrichir `idea_list_agents` avec un champ additif du type :
  - `capabilities: [{ name, description, kind }]`

- Supprimer à terme le dump complet des corps de skills en mode non-MCP.
  - Le remplacer par une surface bornée et homogène avec le mode MCP : catalogue compact + lecture à la demande via la surface adaptée au runtime.

- Distinguer la politique d'injection selon le type :
  - `Workflow` : jamais injecté en corps complet par défaut.
  - `Reference` : peut éventuellement être injecté de façon compacte selon des règles bornées (optionnel, à arbitrer plus tard).

## Frontières avec les autres surfaces IdeA

- Tools MCP :
  - les skills ne deviennent pas des tools MCP.
  - `idea_skill_read` reste un pont vers les skills, pas une matérialisation des skills comme tools.

- Contexte projet :
  - le contexte reste global au projet et commun.
  - un skill reste assignable sélectivement agent par agent.

- Mémoire durable :
  - la mémoire reste un savoir stabilisé écrit dynamiquement.
  - un skill reste une capacité/version de workflow éditée explicitement.

- Live-state :
  - aucun recouvrement fonctionnel ; pas de mélange.

- Templates :
  - à envisager plus tard : un template pourrait référencer des skills à assigner par défaut.
  - en revanche, un template ne doit pas dupliquer le corps des skills.

- Plugins :
  - hors périmètre ; ne pas confondre extension IDE humaine et capacité agent.

## Plan de migration incrémental

1. **Domaine**
   - ajouter `SkillKind` sur `Skill` avec rétrocompatibilité (`default`).

2. **Application**
   - extraire un use case dédié de résolution des capacités agent à partir des `SkillRef` assignés.

3. **Surfaces agent / orchestration**
   - faire reposer `# Skills disponibles` sur ce use case au lieu de recalculer localement pendant le rendu markdown.

4. **Découverte inter-agent**
   - enrichir `idea_list_agents` avec les capacités résolues de chaque agent, en gardant les `skills` bruts si nécessaire pour compatibilité.

5. **Unification MCP / non-MCP**
   - supprimer le dump intégral non-MCP et le remplacer par une surface bornée cohérente avec le modèle capability-first.

6. **Optionnel ensuite**
   - politique fine d'injection compacte pour certains skills `Reference` courts.

## Critères de succès

- Un agent neuf connaît immédiatement ses skills assignés sous forme d'affordances bornées, sans dépendre d'un dump lourd.
- Un agent ou Main peut découvrir les capacités utiles d'un autre agent sans manipuler des `SkillRef` opaques.
- Le système reste cohérent avec la séparation IdeA : surface agent bornée, surface humaine riche.
- Le modèle fonctionne proprement en MCP et hors MCP, sans dégradation conceptuelle majeure.
- `idea_skill_read` reste la primitive de lecture détaillée et d'autorisation.

## Notes

Ce ticket est un ticket de refonte/cadrage cible. Il ne demande pas de refaire le stockage ni de supprimer `idea_skill_read`. La refonte porte sur le modèle de capacité agent, la composition de contexte et les surfaces de découverte.