Système de compétences Skills

源码版本v2026.7.20

Responsabilité

Une Skill est une unité de capacité plus haut-niveau qu'un Tool : un flux réutilisable, doté d'un frontmatter (façon spec agentskills.io), rangé par domaine sous skills/<category>/. Contrairement aux outils (tools) « fonctions statiques », les compétences peuvent être créées, réécrites, affinées par la boucle d'apprentissage ; elles sont le support par lequel l'agent « devient plus malin à l'usage ». Les compétences sont exposées à la boucle principale via skills_tool.

Mot de conception

Pourquoi ranger les skills par catégorie plutôt qu'à plat ? Le nombre de compétences grossit avec l'usage (ajoutées par l'utilisateur, synchronisées depuis le hub, générées par la boucle d'apprentissage — tout vit dans ~/.hermes/skills/), et une liste plate renvoyée par skills_list devient vite du bruit. La catégorie fait que la première couche de progressive disclosure n'expose que « voici un groupe de compétences research » plutôt que 50 noms de compétences spécifiques. Chaque SKILL.md est un fichier unique qui se définit lui-même (avec frontmatter), complété par des sous-fichiers dans skills/<category>/<skill>/references/ chargés à la demande — les tokens n'explosent pas d'un coup.

Un bundle est une couche supérieure : il charge plusieurs compétences via une seule slash command, parce qu'un scénario comme « dev backend » doit attacher simultanément code review, TDD et PR — les appeler une par une via /skill serait trop fragmenté.

Fichiers clés

• répertoire skills/ — groupé par domaine (apple, computer-use, research, software-development, yuanbao…), chaque compétence ressemble à :

skills/
├── my-skill/
│   ├── SKILL.md           # instruction principale (requis)
│   ├── references/        # documents de support
│   │   ├── api.md
│   │   └── examples.md
│   ├── templates/         # modèles de sortie
│   └── assets/            # pièces jointes (standard agentskills.io)
└── category/
    └── another-skill/
        └── SKILL.md

Le haut de SKILL.md est un frontmatter YAML (name/description/version/platforms/prerequisites…), suivi du corps d'instructions. name est limité à 64 caractères, description à 1024 — ces deux champs sont les seuls renvoyés par la première couche de progressive disclosure de skills_list, pour économiser des tokens.

• skills_tool — expose les compétences comme outil à la boucle principale. Il enregistre deux outils :

registry.register(
    name="skills_list",
    toolset="skills",
    schema=SKILLS_LIST_SCHEMA,
    handler=lambda args, **kw: skills_list(
        category=args.get("category"), task_id=kw.get("task_id")
    ),
    check_fn=check_skills_requirements,
    emoji="📚",
)

registry.register(
    name="skill_view",
    toolset="skills",
    schema=SKILL_VIEW_SCHEMA,
    handler=_skill_view_with_bump,
    check_fn=check_skills_requirements,
    emoji="📚",
)

skills_list ne renvoie que name + description + category (première couche de progressive disclosure) ; skill_view charge le SKILL.md complet (deuxième couche) ; les fichiers de support (reference/template, etc.) sont tirés à la demande via skill_view(name, file_path="references/api.md") (troisième couche). _skill_view_with_bump appelle après succès bump_view / bump_use pour mettre à jour les compteurs d'usage, sur lesquels le minuteur stale du curator s'appuie pour nettoyer les compétences plus utilisées.

• skill_manager_tool — gestion des compétences (liste / voir / activer)
• skills_hub — synchronisation avec le hub de compétences (compatible agentskills.io)
• skills_sync — synchronisation local / distant
• skill_bundles — empaquetage de faisceaux de compétences, injectés dans le prompt. Un bundle est un petit fichier dans ~/.hermes/skill-bundles/*.yaml :

name: backend-dev
description: Backend feature work — code review, testing, PR workflow.
skills:
  - github-code-review
  - test-driven-development
  - github-pr-workflow
instruction: |
  Optional extra guidance to inject above the skill bodies.

/<bundle-name> appelle build_bundle_invocation_message qui colle les SKILL.md de toutes les compétences membres dans un seul user message. En cas d'homonymie bundle/compétence, le bundle gagne — si l'utilisateur a explicitement choisi ce nom, c'est pour écraser la compétence qui collisionnait par hasard. Les compétences membres manquantes ne remontent pas d'erreur ; un indice « lesquelles ont été sautées » est juste annexé au résultat.

• skill_preprocessing — prétraitement du contenu des compétences. Remplace les variables template ${HERMES_SKILL_DIR} / ${HERMES_SESSION_ID} et exécute les inline shell snippets comme !date +%Y-%m-%d``. Un inline shell qui échoue renvoie un marqueur [inline-shell error: ...] plutôt que de lever — un mauvais snippet ne casse pas tout le message de compétence.
• nœuds et arêtes de compétences:125-193 — build_skill_nodes / build_edges, organisent les compétences dans le graphe d'apprentissage

Flux de données

1. Au démarrage, skill_preprocessing (agent/skill_preprocessing.py) scanne skills/<category>/ et lit les frontmatters.
2. skill_bundles (agent/skill_bundles.py) empaquète les compétences pertinentes et les injecte dans le prompt du tour (turn) via build_turn_context:268.
3. Le provider décide d'appeler une compétence → tool_call skills → tools/skills_tool.py charge et exécute le flux de la compétence.
4. Le résultat d'exécution est réinjecté dans la boucle principale.
5. La boucle d'apprentissage examine ce tour en arrière-plan et peut :
   • créer une nouvelle compétence (learning_mutations)
   • enregistrer la nouvelle compétence dans le graphe d'apprentissage agent/learning_graph.py:125
   • la synchroniser au hub via tools/skills_sync.py

Limites et échecs

• Traversal de chemin : le nom de skill est concaténé sur ~/.hermes/skills/ pour retrouver un fichier ; _skill_lookup_path_error rejette les segments .., les chemins absolus et les lettres de lecteur Windows. Sans ça, name="../outside" lirait des fichiers hors du répertoire skills.
• Injection de prompt : les contenus SKILL.md contenant des motifs comme « ignore previous instructions », « system prompt: », « ]]> » sont marqués par _INJECTION_PATTERNS. Les compétences tierces (synchronisées depuis le hub) sont du contenu non fiable ; la boucle principale doit sanitizer au chargement.
• Bundle membre manquant : build_bundle_invocation_message se contente de noter les membres manquants/désactivés dans des listes missing / disabled sans lever — le bundle est un chargement tolérant, en perdre quelques-uns n'affecte pas les autres.
• Cache périmé : scanner skills/ est un stat O(#dirs), la signature inclut le mtime du répertoire + l'ensemble désactivé + la plateforme. Mais l'édition sur place d'un seul SKILL.md ne bump que son propre mtime, invisible au niveau répertoire — d'où un TTL supplémentaire de 30 s en filet de sécurité.

Résumé

Compétence = flux haut-niveau évolutif, décrit par frontmatter, défini par fichier, réécrivable par la boucle d'apprentissage. Rapport aux outils : les outils sont les atomes appelés dans le flux d'une compétence, la compétence est la connaissance « comment combiner les outils pour accomplir une classe de tâches ». Le mécanisme d'évolution des compétences est décrit dans la boucle d'apprentissage.