La Vérité Difficile sur les Skills des Agents

En décembre 2025, Anthropic a publié Agent Skills en tant que norme ouverte. Microsoft, Cursor et d'autres l'ont adopté. Il existe maintenant une spécification sur agentskills.io, une structure de répertoires, des exigences de frontmatter YAML, et tout un écosystème.

Mais avant de plonger dans les frameworks et les spécifications, comprenons ce que les skills sont vraiment.

Ce Qu'Anthropic Dit Que Les Skills Sont

D'après la documentation officielle :

Les Agent Skills sont des capacités modulaires qui étendent les fonctionnalités de Claude. Chaque Skill regroupe des instructions, des métadonnées et des ressources optionnelles (scripts, templates) que Claude utilise automatiquement quand c'est pertinent.

L'insight clé du blog d'ingénierie d'Anthropic : les skills sont des ressources basées sur le système de fichiers, réutilisables qui donnent à Claude une expertise spécifique au domaine. Au lieu d'expliquer la même chose à chaque conversation, vous l'écrivez une fois en tant que skill.

Le Problème Que Les Skills Résolvent

Sans skills :

• Vous réexpliquez les procédures à chaque session
• Le contexte se remplit d'instructions répétées
• Pas de cohérence entre les conversations

Avec les skills :

• Écrivez les instructions une fois
• Chargez-les seulement quand c'est pertinent
• Comportement cohérent entre les sessions

C'est le pitch. Et c'est logique.

La Structure Officielle

La spécification d'Anthropic nécessite une structure spécifique :

.claude/skills/youtube-transcribe/
├── SKILL.md              # Required
├── scripts/
│   └── transcript.sh     # Optional
└── references/
    └── api-docs.md       # Optional

Le fichier SKILL.md a besoin de frontmatter YAML :

---
name: youtube-transcribe
description: Transcribe YouTube videos to text. Use when user wants to extract transcript from a YouTube URL.
---

# YouTube Transcription

To transcribe a video:
1. Run: `scripts/transcript.sh "<youtube-url>"`
2. Output saves to: `transcripts/<video-id>.txt`

Divulgation Progressive

Anthropic a conçu les skills autour de trois niveaux de chargement :

L'idée : charger uniquement ce que vous avez besoin, quand vous en avez besoin. Ne pas tout déverser dans chaque conversation.

C'est une architecture véritablement intelligente pour la gestion du contexte.

Maintenant, La Vérité Difficile

Voici ce que la spécification n'insiste pas sur :

Les skills sont juste du texte.

Le frontmatter YAML ? Analysé en texte pour le prompt. La structure de répertoires ? Une convention pour l'organisation. La "divulgation progressive" ? Claude lisant des fichiers depuis le disque.

Enlevez le framework, et un skill est :

• Une description (pour que Claude sache quand l'utiliser)
• Des instructions (comment faire la chose)
• Peut-être un script (à exécuter)

C'est tout.

Ce Que Cela Signifie en Pratique

Considérez ces deux approches :

Approche A : Skill Formel

.claude/skills/youtube-transcribe/SKILL.md

---
name: youtube-transcribe
description: Transcribe YouTube videos to text files
---

# YouTube Transcription
Run: bun scripts/youtube-transcript.sh "<url>"

Approche B : Guide Simple

guides/how-to-transcribe-youtube.md

# How to Transcribe YouTube Videos
Run: bun scripts/youtube-transcript.sh "<url>"

Pour Claude, ces deux sont pratiquement identiques. Les deux sont des fichiers texte avec des instructions. Les deux peuvent être trouvés en cherchant. Les deux disent à Claude quoi faire.

La différence :

• Approche A : Le frontmatter est pré-chargé au démarrage (~100 tokens)
• Approche B : Claude cherche quand il a besoin de l'information

Le pré-chargement de la description vaut-il la surcharge structurelle ? Parfois oui, parfois non.

Quand la Structure Aide

La structure d'Anthropic aide véritablement quand :

Vous avez beaucoup de skills et avez besoin de découverte

Si vous avez 50 capacités, le pré-chargement des descriptions permet à Claude de savoir qu'elles existent sans lire 50 fichiers. Les métadonnées agissent comme un index.

Vous voulez l'invocation par slash-command

Les skills deviennent des commandes /youtube-transcribe. Les utilisateurs peuvent les invoquer directement. C'est un vrai bénéfice UX.

Vous avez besoin de restrictions sur les outils

Le champ allowed-tools limite ce qu'un skill peut faire. Bénéfice de sécurité pour les opérations sensibles.

Vous distribuez les skills à d'autres

La norme ouverte signifie que les skills fonctionnent sur Claude Code, Cursor, VS Code. La portabilité compte.

Quand Les Guides Simples Gagnent

Mais souvent, les guides markdown simples fonctionnent aussi bien :

Procédures ponctuelles

# Deploy to Production
1. Run tests: `bun test`
2. Build: `bun run build`
3. Deploy: `./deploy.sh production`

Cela a-t-il besoin d'être un skill formel ? Probablement pas. C'est un guide. Claude le trouve quand c'est pertinent.

Connaissances spécifiques au projet

# Our Brand Voice
- Professional but approachable
- No jargon unless explained
- Examples over abstractions

C'est du contexte, pas une capacité. Un fichier markdown dans docs/ suffit.

Références rapides

# API Credentials
- Google Analytics: Property 478766521
- Mailgun: Check .env for MAILGUN_API_KEY
- Sentry: Project teamday-cc

Information indexée. N'a pas besoin de divulgation progressive.

Le Spectre

Les skills existent sur un spectre du trivial au complet :

Une Ligne (peut-être ne pas avoir besoin de skills formels)

Email notifications: bun scripts/mailgun.send.js --to="x" --subject="y"

Références Rapides (à la limite)

# Google Analytics
Use the mcp__google-analytics tools.
Property ID: 478766521
Common queries: pageviews, sessions, top pages

Guides Étape par Étape (skill formel a du sens)

# Add YouTube Video to Newsfeed

1. Fetch transcript
2. Extract metadata with curl (not WebFetch!)
3. Create feed post
4. Update embeddings
5. Extract entities
6. Trigger translations

Workflows Complets (définitivement un skill)

Procédures multi-étapes avec scripts, validation, gestion des erreurs. Le skill de newsfeed que nous utilisons fait 250+ lignes avec sous-documents pour des tâches spécifiques.

Plus la capacité est complexe, plus la structure formelle est payante.

Le Système de Fichiers Est Votre Ami

Voici ce que le blog d'ingénierie d'Anthropic souligne et qui est souvent oublié :

Claude a accès au système de fichiers. Les scripts s'exécutent via bash. Les fichiers de référence existent sur le disque. Vous pouvez regrouper effectivement des matériaux de référence illimités.

Claude peut :

• Chercher des fichiers : grep -r "transcribe" docs/
• Lire ce qu'il trouve : Read: docs/how-to-transcribe.md
• Exécuter des scripts : bash scripts/transcribe.sh

La découverte progressive ne nécessite pas le framework des skills. Elle nécessite une bonne organisation de fichiers et une IA qui sait chercher.

Le framework des skills formalise cela avec des métadonnées. Mais le mécanisme sous-jacent est juste la navigation du système de fichiers.

Le Contexte Est Tout

L'insight réel du design d'Anthropic : les fenêtres de contexte sont limitées.

Le system prompt de Claude Code ferait reportedly 72kb. C'est ~18 000 tokens avant même de commencer à travailler. Chaque description de skill ajoute à cela.

Le design de divulgation progressive aborde cela :

• Métadonnées uniquement au démarrage (petit)
• Instructions complètes quand déclenché (moyen)
• Scripts/références quand nécessaire (illimité, pas dans le contexte)

Mais vous obtenez le même bénéfice de :

• Un system prompt minimal
• Claude cherche dans les docs quand nécessaire
• Lit seulement ce qui est pertinent

Le principe compte plus que la mise en œuvre.

Ce Qui Compte Vraiment

Après avoir construit des dizaines de workflows d'IA, voici ce que nous avons appris :

1. Des Instructions Claires Battent une Structure Intelligente

# Generate Blog Cover

We use FAL AI. Images save to public/images/.

Run:
bun scripts/generate-image.ts "prompt" name.webp

Good prompts:
- Include style ("minimalist illustration")
- Include subject ("AI agents collaborating")
- Include mood ("professional, tech-forward")

Claude suit cela, qu'il s'agisse d'un skill formel ou d'un fichier doc.

2. La Découvrabilité Est Réelle

Si Claude ne peut pas trouver vos instructions, la structure n'a pas d'importance. Que ce soit par les descriptions de skills ou de bons noms de fichiers, rendez les choses trouvables.

• ✅ guides/how-to-transcribe-youtube.md
• ✅ Skill avec description claire
• ❌ notes/misc/stuff-v2-final.md

3. Les Scripts Résolvent la Complexité

Quand les instructions deviennent complexes, écrivez un script :

# Instead of 20 lines of instructions:
bun scripts/add-video-to-newsfeed.ts "<youtube-url>"

Le script encapsule la complexité. Le skill documente juste comment l'invoquer.

4. Itérer Basé sur les Écheccs

Quand Claude fait quelque chose de mal :

• Instruction peu claire ? → Améliorez le texte
• Information manquante ? → Ajoutez-la
• Impossible à trouver ? → Meilleur nommage ou ajoutez à l'index de skill

N'ajoutez pas de règles défensives. Fixez le problème réel.

Le Résultat

Anthropic a construit un système réfléchi pour organiser les capacités d'IA. La divulgation progressive est intelligente. La norme ouverte permet la portabilité. Les slash commands améliorent l'UX.

Mais voici la vérité difficile :

Les skills sont juste des instructions textuelles que Claude lit depuis des fichiers.

Le framework ajoute :

• Des descriptions pré-chargées (index)
• Invocation par slash-command
• Restrictions sur les outils
• Portabilité multi-plateforme

Ce sont des bénéfices réels pour les setups complexes avec beaucoup de capacités.

Mais pour le travail quotidien :

• Un fichier markdown bien nommé fonctionne
• Claude peut chercher et trouver les choses
• Les instructions claires comptent plus que la structure
• Le système de fichiers est déjà un système de découverte

Ne pas sur-ingénier. Commencez par des guides simples. Ajoutez une structure de skill formel quand les bénéfices justifient la surcharge.

Écrivez clairement. Organisez sensiblement. Laissez Claude faire son travail.

Nous utilisons les deux approches chez TeamDay. Des skills formels pour les workflows complexes comme la gestion des newsfeeds. Des guides simples pour les procédures ponctuelles. La clé est d'adapter l'outil à la tâche.