Skill Writer

Cette Skill vous aide à créer des Agent Skills bien structurées pour Claude Code qui suivent les meilleures pratiques et les exigences de validation.

Quand utiliser cette Skill

Utilisez cette Skill quand :

Vous créez une nouvelle Agent Skill
Vous écrivez ou mettez à jour des fichiers SKILL.md
Vous concevez la structure et le frontmatter d'une Skill
Vous dépannez des problèmes de découverte de Skill
Vous convertissez des prompts ou workflows existants en Skills

Instructions

Étape 1 : Déterminer la portée de la Skill

D'abord, comprenez ce que la Skill doit faire :

Posez des questions de clarification :
- Quelle capacité spécifique cette Skill doit-elle fournir ?
- Quand Claude doit-il utiliser cette Skill ?
- Quels outils ou ressources lui sont nécessaires ?
- Est-ce pour un usage personnel ou un partage d'équipe ?
Restez focalisé : Une Skill = une capacité
- Bon : « Remplissage de formulaires PDF », « Analyse de données Excel »
- Trop large : « Traitement de documents », « Outils de données »

Étape 2 : Choisir l'emplacement de la Skill

Déterminez où créer la Skill :

Skills personnelles (~/.claude/skills/) :

Workflows individuels et préférences
Skills expérimentales
Outils de productivité personnelle

Skills de projet (.claude/skills/) :

Workflows d'équipe et conventions
Expertise spécifique au projet
Utilitaires partagés (commités dans git)

Étape 3 : Créer la structure de la Skill

Créez le répertoire et les fichiers :

# Personnel
mkdir -p ~/.claude/skills/skill-name

# Projet
mkdir -p .claude/skills/skill-name

Pour les Skills multi-fichiers :

skill-name/
├── SKILL.md (obligatoire)
├── reference.md (optionnel)
├── examples.md (optionnel)
├── scripts/
│   └── helper.py (optionnel)
└── templates/
    └── template.txt (optionnel)

Étape 4 : Écrire le frontmatter SKILL.md

Créez un frontmatter YAML avec les champs obligatoires :

---
name: skill-name
description: Description brève de ce que cela fait et quand l'utiliser
---

Exigences des champs :

name :
- Lettres minuscules, chiffres, tirets uniquement
- Max 64 caractères
- Doit correspondre au nom du répertoire
- Bon : pdf-processor, git-commit-helper
- Mauvais : PDF_Processor, Git Commits!
description :
- Max 1024 caractères
- Incluez CE QU'ELLE FAIT ET QUAND L'UTILISER
- Utilisez des mots déclencheurs spécifiques que les utilisateurs diraient
- Mentionnez les types de fichiers, opérations et contexte

Champs frontmatter optionnels :

allowed-tools : Restreindre l'accès aux outils (liste séparée par des virgules)
```
allowed-tools: Read, Grep, Glob
```
Utilisez pour :
- Skills en lecture seule
- Workflows sensibles à la sécurité
- Opérations à portée limitée

Étape 5 : Écrire des descriptions efficaces

La description est critique pour que Claude découvre votre Skill.

Formule : [Ce qu'elle fait] + [Quand l'utiliser] + [Mots clés déclencheurs]

Exemples :

✅ Bon :

description: Extrayez du texte et des tableaux de fichiers PDF, remplissez des formulaires, fusionnez des documents. Utilisez quand vous travaillez avec des fichiers PDF ou quand l'utilisateur mentionne des PDF, des formulaires ou l'extraction de documents.

✅ Bon :

description: Analysez des feuilles de calcul Excel, créez des tableaux croisés dynamiques et générez des graphiques. Utilisez quand vous travaillez avec des fichiers Excel, des feuilles de calcul ou analysez des données tabulaires au format .xlsx.

❌ Trop vague :

description: Aide avec les documents
description: Pour l'analyse de données

Conseils :

Incluez les extensions de fichier spécifiques (.pdf, .xlsx, .json)
Mentionnez les phrases courantes des utilisateurs (« analyser », « extraire », « générer »)
Listez les opérations concrètes (pas de verbes génériques)
Ajoutez des indices de contexte (« Utilisez quand... », « Pour... »)

Étape 6 : Structurer le contenu de la Skill

Utilisez des sections Markdown claires :

# Nom de la Skill

Aperçu bref de ce que cette Skill fait.

## Démarrage rapide

Fournissez un exemple simple pour commencer immédiatement.

## Instructions

Guidance étape par étape pour Claude :
1. Première étape avec action claire
2. Deuxième étape avec résultat attendu
3. Gérez les cas limites

## Exemples

Montrez des exemples d'utilisation concrets avec code ou commandes.

## Meilleures pratiques

- Conventions clés à suivre
- Pièges courants à éviter
- Quand utiliser vs ne pas utiliser

## Exigences

Listez toutes les dépendances ou prérequis :
```bash
pip install package-name

Utilisation avancée

Pour les scénarios complexes, voir reference.md.


### Étape 7 : Ajouter des fichiers de support (optionnel)

Créez des fichiers supplémentaires pour la divulgation progressive :

**reference.md** : Documentation API détaillée, options avancées
**examples.md** : Exemples étendus et cas d'usage
**scripts/** : Scripts d'assistance et utilitaires
**templates/** : Modèles de fichiers ou code prêt à l'emploi

Référencez-les depuis SKILL.md :
```markdown
Pour l'utilisation avancée, voir [reference.md](reference.md).

Exécutez le script d'assistance :
\`\`\`bash
python scripts/helper.py input.txt
\`\`\`

Étape 8 : Valider la Skill

Vérifiez ces exigences :

✅ Structure de fichiers :

[ ] SKILL.md existe au bon emplacement
[ ] Le nom du répertoire correspond au name du frontmatter

✅ Frontmatter YAML :

[ ] Ouverture --- à la ligne 1
[ ] Fermeture --- avant le contenu
[ ] YAML valide (pas de tabulations, indentation correcte)
[ ] name suit les règles de nommage
[ ] description est spécifique et < 1024 caractères

✅ Qualité du contenu :

[ ] Instructions claires pour Claude
[ ] Exemples concrets fournis
[ ] Cas limites gérés
[ ] Dépendances listées (si applicable)

✅ Tests :

[ ] Description correspond aux questions des utilisateurs
[ ] La Skill s'active sur les requêtes pertinentes
[ ] Les instructions sont claires et actionnables

Étape 9 : Tester la Skill

Redémarrer Claude Code (s'il tourne) pour charger la Skill
Poser des questions pertinentes qui correspondent à la description :
```
Pouvez-vous m'aider à extraire du texte de ce PDF ?
```
Vérifier l'activation : Claude devrait utiliser la Skill automatiquement
Vérifier le comportement : Confirmez que Claude suit les instructions correctement

Étape 10 : Déboguer si nécessaire

Si Claude n'utilise pas la Skill :

Rendre la description plus spécifique :
- Ajouter des mots déclencheurs
- Inclure les types de fichiers
- Mentionner les phrases courantes des utilisateurs

Vérifier l'emplacement du fichier :

ls ~/.claude/skills/skill-name/SKILL.md
ls .claude/skills/skill-name/SKILL.md

Valider le YAML :
```
cat SKILL.md | head -n 10
```
Exécuter le mode débogage :
```
claude --debug
```

Patterns courants

Skill en lecture seule

---
name: code-reader
description: Lire et analyser du code sans apporter de modifications. Utilisez pour les révisions de code, la compréhension de bases de code ou la documentation.
allowed-tools: Read, Grep, Glob
---

Skill basée sur des scripts

---
name: data-processor
description: Traitez les fichiers de données CSV et JSON avec des scripts Python. Utilisez quand vous analysez des fichiers de données ou transformez des ensembles de données.
---

# Data Processor

## Instructions

1. Utilisez le script de traitement :
\`\`\`bash
python scripts/process.py input.csv --output results.json
\`\`\`

2. Validez la sortie avec :
\`\`\`bash
python scripts/validate.py results.json
\`\`\`

Skill multi-fichiers avec divulgation progressive

---
name: api-designer
description: Concevez des API REST en suivant les meilleures pratiques. Utilisez quand vous créez des endpoints API, concevez des routes ou planifiez l'architecture API.
---

# API Designer

Démarrage rapide : Voir [examples.md](examples.md)

Référence détaillée : Voir [reference.md](reference.md)

## Instructions

1. Recueillez les exigences
2. Concevez les endpoints (voir examples.md)
3. Documentez avec la spécification OpenAPI
4. Vérifiez contre les meilleures pratiques (voir reference.md)

Meilleures pratiques pour les auteurs de Skills

Une Skill, un objectif : Ne créez pas de mega-Skills
Descriptions spécifiques : Incluez les mots clés que les utilisateurs diront
Instructions claires : Écrivez pour Claude, pas pour les humains
Exemples concrets : Montrez du vrai code, pas du pseudocode
Listez les dépendances : Mentionnez les packages requis dans la description
Testez avec les coéquipiers : Vérifiez l'activation et la clarté
Versionnez vos Skills : Documentez les changements dans le contenu
Utilisez la divulgation progressive : Mettez les détails avancés dans des fichiers séparés

Checklist de validation

Avant de finaliser une Skill, vérifiez :

[ ] Le nom est en minuscules, tirets uniquement, max 64 caractères
[ ] La description est spécifique et < 1024 caractères
[ ] La description inclut « ce qu'elle fait » et « quand l'utiliser »
[ ] Le frontmatter YAML est valide
[ ] Les instructions sont étape par étape
[ ] Les exemples sont concrets et réalistes
[ ] Les dépendances sont documentées
[ ] Les chemins de fichiers utilisent des barres obliques avant
[ ] La Skill s'active sur les requêtes pertinentes
[ ] Claude suit les instructions correctement

Dépannage

La Skill ne s'active pas :

Rendez la description plus spécifique avec des mots déclencheurs
Incluez les types de fichiers et opérations dans la description
Ajoutez une clause « Utilisez quand... » avec des phrases des utilisateurs

Plusieurs Skills en conflit :

Rendez les descriptions plus distinctes
Utilisez des mots déclencheurs différents
Réduisez la portée de chaque Skill

La Skill a des erreurs :

Vérifiez la syntaxe YAML (pas de tabulations, indentation correcte)
Vérifiez les chemins de fichiers (utilisez des barres obliques avant)
Assurez-vous que les scripts ont les permissions d'exécution
Listez toutes les dépendances

Exemples

Voir la documentation pour des exemples complets :

Skill simple mono-fichier (commit-helper)
Skill avec permissions d'outils (code-reviewer)
Skill multi-fichiers (pdf-processing)

Format de sortie

Quand je crée une Skill, je vais :

Poser des questions de clarification sur la portée et les exigences
Suggérer un nom et un emplacement pour la Skill
Créer le fichier SKILL.md avec le bon frontmatter
Inclure des instructions claires et des exemples
Ajouter des fichiers de support si nécessaire
Fournir des instructions de test
Valider par rapport à toutes les exigences

Le résultat sera une Skill complète et fonctionnelle qui suit toutes les meilleures pratiques et règles de validation.

skill-writer