agentskills.io implementation

Les tools sont atomiques. Les skills sont des recettes. Un tool lit un fichier, exécute une requête, récupère une URL. Les skills sont des procédures multi-étapes nommées qui combinent plusieurs tools avec des étapes de raisonnement dans un ordre fixe. Le standard agentskills.io définit à quoi ressemble un skill, et l'intégrer dans un agent qui utilise des tools est un petit changement qui se rentabilise vite.

Pourquoi une couche de skills au-dessus des tools

Après 50 tours avec un LLM qui utilise des tools, on remarque un motif : les mêmes workflows multi-tools sont réinventés à chaque fois, avec de petites variations. « Morning status » appelle les cinq mêmes tools dans à peu près le même ordre, mais le formatage dérive. « Weekly recap » a une forme similaire, mais en pire — plus de tools, plus d'endroits où dévier.

La solution : une couche de skills. Chaque workflow récurrent devient une recette nommée ; le LLM consulte la recette au lieu de tout replanifier à zéro à chaque fois.

Trois gains concrets :

1. Cohérence. Le même type de requête produit la même forme de sortie. Important pour les choses que l'on lit de façon répétée (briefings quotidiens, rapports).
2. Moins de raisonnement par tour. Le LLM n'a pas à replanifier un workflow connu ; il suit les étapes. Moins cher, plus rapide.
3. Maintenabilité. Tu veux changer « le fonctionnement des morning briefings » ? Modifie un seul fichier, pas le prompt du modèle.

Format SKILL.md

La spec agentskills.io est minimale. Un skill est un répertoire avec un fichier SKILL.md (éventuellement avec des sous-dossiers pour les scripts, les references, les assets). Le SKILL.md a un frontmatter YAML et un corps Markdown :

---
name: daily-status-report
description: "Compile yesterday's commits, today's calendar, open
nudges into a single morning briefing. Use when Nathan asks for a
status report or starts a new conversation after >6h silence."
---

# Daily status report

Run the tools below in order, then synthesise the markdown summary at
the bottom.

## Steps

1. Call `commit_log` for yesterday's commits across all projects
2. Call `calendar_today` for events
3. Call `nudges_open` for pending review items
4. Format the output as:
   - "Yesterday: <commits>"
   - "Today: <events>"
   - "Awaiting review: <nudges>"

Deux champs de frontmatter obligatoires : name (qui correspond au nom du répertoire) et description (max. 1024 caractères — c'est ce que le LLM voit au moment de choisir un skill).

Progressive disclosure

Le choix de conception clé : seules les métadonnées (frontmatter) sont chargées dans le contexte du LLM au démarrage. Le corps complet n'est chargé que lorsque le LLM décide d'invoquer un skill précis. Deux tools le permettent :

def list_skills() -> list[dict]:
    """Cheap: returns name + description for all skills."""
    return [parse_frontmatter(p) for p in glob("memory/_skills/*/SKILL.md")]

def run_skill(name: str) -> dict:
    """Loads full SKILL.md body. ~5000 token budget per spec."""
    return read_skill(name)

list_skills coûte ~100 tokens par skill — assez bon marché pour l'appeler à chaque tour ou le placer dans le system prompt. run_skill est l'opération coûteuse, appelée uniquement une fois que le LLM a choisi un skill précis.

Ce motif garde la taille du contexte maîtrisable, même lorsque tu as 50+ skills disponibles.

Comment le LLM l'utilise

En pratique, la boucle de prompt devient :

1. User : « donne-moi un morning status »
2. LLM (avec list_skills déjà dans le contexte) : reconnaît que cela correspond à la description de daily-status-report
3. Le LLM appelle run_skill("daily-status-report")
4. Le LLM reçoit le corps complet, suit les étapes, appelle les tools dans le bon ordre
5. Le LLM formate selon le template du skill

Le LLM fait encore du raisonnement (quel skill correspond, comment gérer les cas limites), mais le plan est canonique. Même requête, même forme de sortie.

Quand ajouter un skill

Heuristique : dès que tu rédiges le même workflow multi-étapes au LLM trois fois, fais-en un skill. L'écriture prend ~15 minutes ; le rendement est permanent.

Mauvais candidats pour un skill :

• Requêtes ponctuelles (laisse simplement le LLM planifier)
• Appels à un seul tool (un skill est exagéré)
• Workflows très variables (chaque invocation a des étapes différentes)

Bons candidats :

• Rapports de statut / briefing / recap
• Diagnostics multi-tools (« vérifie pourquoi X échoue »)
• Séquences d'onboarding (« mets en place un nouveau projet »)
• Tout ce qui s'exécute selon un planning

Suivi automatique de l'utilisation

Le frontmatter peut stocker le nombre d'invocations et les taux de succès au fil du temps. Chaque appel à run_skill ajoute un compteur au bas du frontmatter :

total_invocations: 47
total_successes: 45
success_rate: 0.957
last_used: "2026-06-02T08:30:22Z"

Télémétrie lente — basée sur des fichiers, sans base de données séparée. Mais suffisante pour voir quels skills tirent leur poids et lesquels ne sont jamais utilisés. Les inutilisés : à jeter. Les populaires : à approfondir.

Pourquoi agentskills.io en particulier

C'est la spec qu'Anthropic a adoptée pour Claude Skills. L'utiliser signifie que tes skills sont portables : ils fonctionnent dans ton orchestrateur local, ils fonctionnent dans Claude.ai, ils fonctionnent dans tout agent qui utilise des tools et qui prend en charge le standard. Tu peux aussi emprunter des skills de la communauté sans les réécrire.

Le standard est assez petit pour être lu en 10 minutes. L' investissement pour l'adopter est assez faible pour être un refactor d'un seul après-midi. Le bénéfice est permanent.