L'architecture des compétences¶
Les compétences forment une couche d'orchestration transversale, posée en travers des cinq primitives existantes (Intelligence, Moteur, Agents, Mémoire/Outils, Apprentissage). Elles relient les outils, les agents, la mémoire et l'apprentissage en flux de travail réutilisables, sans remplacer ni absorber aucune primitive.
La conception du système¶
┌──────────────────────┐
│ SystemBuilder │
│ .build() │
└──────────┬───────────┘
│
┌──────────▼───────────┐
│ SkillManager │
│ • discover() │
│ • get_skill_tools()│
│ • get_catalog_xml()│
└──────────┬───────────┘
│
┌────────────────┼────────────────┐
│ │ │
┌─────────▼──────┐ ┌──────▼──────┐ ┌───────▼───────┐
│ SkillTool │ │ Catalogue │ │ Chargeur │
│ (BaseTool) │ │ XML │ │ d'overlay │
│ → liste des │ │ → prompt │ │ → description│
│ outils de │ │ système │ │ optimisée │
│ l'agent │ │ │ │ + few-shot │
└────────────────┘ └─────────────┘ └───────────────┘
Les composants clés¶
SkillManifest (skills/types.py)¶
La structure de données canonique d'une compétence chargée :
@dataclass(slots=True)
class SkillManifest:
name: str
version: str = "0.1.0"
description: str = ""
author: str = ""
steps: List[SkillStep] = field(default_factory=list)
required_capabilities: List[str] = field(default_factory=list)
signature: str = ""
metadata: Dict[str, Any] = field(default_factory=dict)
tags: List[str] = field(default_factory=list)
depends: List[str] = field(default_factory=list)
user_invocable: bool = True
disable_model_invocation: bool = False
markdown_content: str = ""
SkillManager (skills/manager.py)¶
Le coordinateur central. Créé par SystemBuilder.build() au moment de composer le système.
Le cycle de vie :
discover(paths)— balaie les dossiers de compétences dans l'ordre de priorité, charge les manifestes, valide le graphe de dépendances, applique les overlays d'optimisationget_skill_tools()— habille chaque compétence découverte enSkillTool(BaseTool)et branche les rappels de résolution des sous-compétencesget_catalog_xml()— engendre le XML léger<available_skills>à injecter dans le prompt systèmeget_few_shot_examples()— rend les chaînes few-shot mises en forme, tirées des overlays d'optimisation
SkillTool (skills/tool_adapter.py)¶
L'adaptateur qui fait passer n'importe quelle compétence pour un BaseTool ordinaire aux yeux des agents :
- la propriété
specdérive leToolSpecdu manifeste — elle extrait toute seule les paramètres d'entrée des gabarits d'arguments des étapes execute(**params)lance le pipeline (s'il y a des étapes), rend le contenu markdown (s'il y a un SKILL.md), ou les deux_build_result_metadata()marque chaque invocation avecskill,skill_sourceetskill_kind, pour l'analyse des traces en aval
SkillParser (skills/parser.py)¶
Un parseur en deux passes pour le front-matter des SKILL.md compatibles agentskills.io :
- La passe stricte — valide les champs obligatoires (
name,description), les limites de longueur et les règles de nommage en kebab-case - La passe tolérante — range les champs maison, hors spécification, à leur place canonique, par la table
FIELD_MAPPING. Les champs sans correspondance sont journalisés et conservés dansmetadata.diapason.original_frontmatter
La table de correspondance est une donnée, pas un chemin de code. Prendre en charge de nouveaux champs maison, c'est ajouter des entrées — aucune logique ne change.
SkillExecutor (skills/executor.py)¶
L'exécuteur de pipeline, séquentiel :
- les étapes portant
tool_name→ déléguées àToolExecutor.execute() - les étapes portant
skill_name→ déléguées à un rappel de résolution (posé par le SkillManager) - le rendu des gabarits : la syntaxe
{placeholder}est résolue depuis un dictionnaire de contexte partagé output_keygarde le résultat de chaque étape pour les étapes suivantes- publie les événements
SKILL_EXECUTE_START/SKILL_EXECUTE_ENDsur l'EventBus
Les résolveurs de source (skills/sources/)¶
Un résolveur par source d'import, tous implémentant la classe abstraite SourceResolver :
| Résolveur | Disposition du dépôt | Traitement particulier |
|---|---|---|
HermesResolver |
skills/<category>/<skill>/ |
Saute DESCRIPTION.md, lit les métadonnées maison de Hermes |
OpenClawResolver |
skills/<owner>/<skill>/ |
Lit les fichiers annexes _meta.json |
GitHubResolver |
Parcours récursif à la recherche des SKILL.md |
Générique — accepte l'URL de n'importe quel dépôt |
SkillImporter (skills/importer.py)¶
Prend un ResolvedSkill rendu par un résolveur de source et l'installe sur le disque :
- Analyser le SKILL.md source avec
SkillParser - Traduire les références aux outils (
Bash→shell_exec,Read→file_read, etc.) - Vérifier la compatibilité (plateforme, outils manquants)
- Copier le SKILL.md et les références, ressources et gabarits (les scripts restent derrière
--with-scripts) - Écrire le fichier de provenance
.source: SHA du commit, outils traduits, horodatages
SkillOverlay (skills/overlay.py)¶
Le stockage annexe de ce que produit l'optimisation, dans ~/.diapason/learning/skills/<name>/optimized.toml :
[optimized]
skill_name = "research-and-summarize"
optimizer = "dspy"
optimized_at = "2026-04-08T14:30:00Z"
trace_count = 47
description = "Une description optimisée"
[[optimized.few_shot]]
input = "les mécanismes d'attention des transformeurs"
output = "## Avancées récentes..."
L'overlay est le contrat entre l'optimiseur et le SkillManager. Les deux côtés s'entendent sur le schéma ; chacun peut être remplacé sans toucher à l'autre.
SkillOptimizer (learning/agents/skill_optimizer.py)¶
Une enveloppe autour de DSPy/GEPA, compétence par compétence :
- Range les traces par
metadata.skill(le marquage posé en C1) - Saute les compétences sous le seuil
min_traces_per_skill - Appelle
_run_dspy()ou_run_gepa()pour chaque compétence retenue - Écrit les fichiers TOML d'overlay
Les points d'intégration¶
Le branchement dans SystemBuilder¶
C'est SystemBuilder.build() qui intègre les compétences :
# 1. Créer le SkillManager
skill_manager = SkillManager(bus, capability_policy=...)
# 2. Découvrir les compétences sur le disque
skill_manager.discover(paths=[workspace_skills, user_skills])
# 3. Les habiller en outils et les fondre dans la liste d'outils
skill_tools = skill_manager.get_skill_tools(tool_executor=...)
tool_list.extend(skill_tools)
# 4. Récupérer les exemples few-shot pour les agents
system._skill_few_shot_examples = skill_manager.get_few_shot_examples()
Le cheminement des métadonnées de trace¶
Quand un agent invoque un SkillTool :
SkillTool.execute()
→ ToolResult(metadata={"skill": name, "skill_source": src, "skill_kind": kind})
→ ToolExecutor._json_safe_metadata() écarte les valeurs non sérialisables
→ événement TOOL_CALL_END, avec ses métadonnées
→ TraceCollector._on_tool_end() → TraceStep(metadata=...)
→ TraceStore enregistre dans SQLite (les métadonnées en JSON)
→ SkillOptimizer._bucket_traces_by_skill() lit metadata.skill
L'injection des exemples few-shot dans l'agent¶
Les exemples few-shot optimisés cheminent ainsi :
SkillManager.get_few_shot_examples()
→ system._skill_few_shot_examples (rangé sur DiapasonSystem)
→ _run_agent() → agent_kwargs["skill_few_shot_examples"]
→ ToolUsingAgent._skill_few_shot_examples
→ native_react.run() → REACT_SYSTEM_PROMPT.format(skill_examples=...)
Le graphe de dépendances¶
Une compétence peut en composer d'autres. À la découverte, le SkillManager vérifie :
- La détection des cycles — l'algorithme de Kahn, pour le tri topologique
- Le respect de la profondeur maximale — configurable (5 par défaut)
- L'union des capacités — le parent doit déclarer toutes les capacités de ses enfants, transitivement
La disposition des fichiers¶
src/diapason/skills/
├── __init__.py # Les exports publics
├── types.py # SkillManifest, SkillStep
├── manager.py # SkillManager
├── executor.py # SkillExecutor + délégation aux sous-compétences
├── loader.py # Chargement TOML + Markdown + dossier
├── tool_adapter.py # L'enveloppe SkillTool(BaseTool)
├── parser.py # Parseur agentskills.io strict + tolérant
├── tool_translator.py # Traduction des noms d'outils externes
├── importer.py # Installation depuis les sources résolues
├── overlay.py # Le stockage annexe de l'optimisation
├── dependency.py # Validation du graphe
├── security.py # Niveaux de confiance, validation des capacités
├── index.py # L'index des compétences, adossé à Git
└── sources/
├── base.py # La classe abstraite SourceResolver
├── hermes.py # HermesResolver
├── openclaw.py # OpenClawResolver
└── github.py # GitHubResolver