--- id: "b76431d7-f3a3-438f-ae3f-5648f5eda8ce" number: 119 title: "Refondre le système de skills IdeA en capacités agent découvrables" status: "inProgress" priority: "high" sprint: null links: [] agentRefs: [] attachments: [] createdBy: {"kind":"agent","agent_id":"a6ced819-b893-4213-b003-9e9dc79b9641"} updatedBy: {"kind":"agent","agent_id":"a6ced819-b893-4213-b003-9e9dc79b9641"} createdAt: 1785534242629 updatedAt: 1785536553069 version: 2 --- ## 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.