Rediger un skill
Ecrire un SKILL.md de qualite : frontmatter, description CSO, template body, degrees of freedom, et limites.
La qualite d'un skill se joue en 3 zones : le frontmatter, la description, et le body. La description seule determine si l'agent trouve et utilise le skill.
Frontmatter obligatoire
---
name: mon-skill # lowercase-hyphens, max 64 caracteres
description: >- # max 1024 caracteres, 3e personne
Ce que ca fait ET quand l'utiliser.
Triggers explicites. Jamais le workflow.
allowed-tools: Read, Write, Edit, Glob, Grep, Bash
---| Champ | Obligatoire | Format |
|---|---|---|
name | Oui | lowercase-hyphens, max 64 caracteres |
description | Oui | Max 1024 caracteres, 3e personne, triggers explicites |
allowed-tools | Recommande | Liste des outils autorises |
La description -- le premier point de defaillance
La description sert au moteur de recherche de Claude (CSO -- Claude Search Optimization). Elle contient les triggers (quand utiliser le skill), jamais le workflow (comment il fonctionne).
| Pattern | Verdict | Pourquoi |
|---|---|---|
| "For code review" | Mauvais | Trop vague, ne trigger pas |
| "Analyzes diffs, runs linter, generates report" | Mauvais | Leak le workflow, l'agent saute le body |
| "Code review with style, security, perf checks. Use when reviewing PRs, auditing code, or user says 'review this'" | Bon | Triggers explicites, pas de workflow |
Description qui leak le workflow
Si un agent produit le bon output en lisant uniquement la description, sans ouvrir le body, ta description leak le workflow. Reecris-la avec des triggers seulement.
Template body
# Nom du Skill
1 phrase : ce que ca fait.
## When to Use
- [Bullet list : situations, triggers, mots-cles]
## How It Works
[Etapes numerotees -- concretes, pas theoriques]
## Reference
[Table de commandes/options/patterns pour scan rapide]
## Common Mistakes
[Table : erreur | fix]Le body suit toujours cette structure.
L'agent scanne les sections dans l'ordre : When to Use pour decider, How It Works pour agir, Reference pour les details.
Degrees of freedom
La liberte diminue de la reflexion a l'execution.
| Phase | Liberte | Exemple |
|---|---|---|
| Analyse / reflexion | Haute (prose) | "Analyse le code pour trouver les problemes" |
| Pattern / decision | Moyenne (parametre) | "Choisis le framework selon le package.json" |
| Validation / execution | Basse (commande exacte) | "Lance npm run build" |
Les sections d'analyse laissent l'agent reflechir. Les sections d'execution dictent les commandes exactes.
Principes de redaction
Chaque principe dans un skill est :
- Actionnable -- l'agent sait quoi faire en le lisant
- Testable -- tu peux verifier si c'est applique
- Court -- 1 phrase par principe, 2 maximum
BON PRINCIPE :
"Chaque paragraphe traite un seul concept."
MAUVAIS PRINCIPE :
"Il faut ecrire de maniere claire et concise en pensant
au lecteur et en structurant bien ses idees."Maximum 7 principes par skill. Au-dela, decoupe en 2 skills.
Limites
| Regle | Valeur |
|---|---|
Taille max du SKILL.md | 500 lignes |
| Debordement | references/ (1 niveau de profondeur) |
| Chaque regle a un WHY | Pas juste WHAT |
| Token efficiency quick start | Moins de 150 mots |
| Token efficiency sections standard | Moins de 500 mots |
| Contenu interdit | TODO, placeholder, stubs |
Un skill avec des TODO n'est pas publie.
Un skill au-dessus de 500 lignes deplace le surplus dans references/.
Lecture liee
- Lifecycle complet -- les 9 phases et les 3 chemins
- Tester un skill -- valider que le skill ameliore le resultat
- Creer un skill -- format initial et validation rapide