Skill Writer

Cette Skill vous aide à créer des Agent Skills bien structurés pour Claude Code qui respectent les bonnes 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 résolvez des problèmes de découverte de Skill
Vous convertissez des prompts ou workflows existants en Skills

Instructions

Étape 1 : Déterminer le périmètre 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 devrait-il utiliser cette Skill ?
- Quels outils ou ressources lui sont nécessaires ?
- Est-ce pour un usage personnel ou un partage en équipe ?
Restez concentré : Une Skill = une capacité
- Bon : « PDF form filling », « Excel data analysis »
- Trop large : « Document processing », « Data tools »

Étape 2 : Choisir l'emplacement de la Skill

Déterminez où créer la Skill :

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

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

Project Skills (.agents/skills/ ; .claude/skills fait un lien ici pour Claude Code) :

Workflows et conventions d'équipe
Expertise spécifique au projet
Utilitaires partagés (commités à 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 .agents/skills/skill-name

Pour les Skills multi-fichiers :

skill-name/
├── SKILL.md (requis)
├── 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 requis :

---
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-clés de déclenchement spécifiques que les utilisateurs diraient
- Mentionnez les types de fichiers, les opérations et le contexte

Champs frontmatter optionnels :

allowed-tools : Restreindre l'accès aux outils (liste séparée par des virgules)
```
allowed-tools: Read, Grep, Glob
```
À utiliser pour :
- Les Skills en lecture seule
- Les workflows sensibles à la sécurité
- Les opérations à périmètre limité

É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 de déclenchement]

Exemples :

✅ Bon :

description: Extraire du texte et des tableaux de fichiers PDF, remplir des formulaires, fusionner des documents. À utiliser quand vous travaillez avec des fichiers PDF ou quand l'utilisateur mentionne des PDF, des formulaires ou une extraction de documents.

✅ Bon :

description: Analyser des feuilles de calcul Excel, créer des tableaux croisés dynamiques et générer des graphiques. À utiliser quand vous travaillez avec des fichiers Excel, des feuilles de calcul ou l'analyse de 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 d'utilisateur courantes (« analyser », « extraire », « générer »)
Listez les opérations concrètes (pas les verbes génériques)
Ajoutez des indices de contexte (« Utiliser quand... », « Pour... »)

Étape 6 : Structurer le contenu de la Skill

Utilisez des sections Markdown claires :

# Skill Name

Présentation brève de ce que cette Skill fait.

## Quick start

Fournir un exemple simple pour commencer immédiatement.

## Instructions

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

## Examples

Montrer des exemples d'utilisation concrète avec du code ou des commandes.

## Best practices

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

## Requirements

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

Advanced usage

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


### Étape 7 : Ajouter des fichiers supplémentaires (optionnel)

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

**reference.md** : Docs API détaillée, options avancées
**examples.md** : Exemples étendus et cas d'utilisation
**scripts/** : Scripts d'aide et utilitaires
**templates/** : Modèles de fichiers ou code passe-partout

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

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

Étape 8 : Valider la Skill

Vérifiez ces exigences :

✅ Structure de fichier :

[ ] 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 respecte 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 (le cas échéant)

✅ Tests :

[ ] La description correspond aux questions des utilisateurs
[ ] La Skill s'active sur les requêtes pertinentes
[ ] Les instructions sont claires et réalisables

Étape 9 : Tester la Skill

Redémarrez Claude Code (s'il est en cours d'exécution) pour charger la Skill
Posez des questions pertinentes qui correspondent à la description :
```
Peux-tu m'aider à extraire du texte d'un PDF ?
```
Vérifiez l'activation : Claude devrait utiliser la Skill automatiquement
Vérifiez le comportement : Confirmez que Claude suit les instructions correctement

Étape 10 : Déboguer si nécessaire

Si Claude n'utilise pas la Skill :

Rendez la description plus spécifique :
- Ajoutez des mots de déclenchement
- Incluez les types de fichiers
- Mentionnez les phrases d'utilisateur courantes

Vérifiez l'emplacement du fichier :

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

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

Motifs courants

Skill en lecture seule

---
name: code-reader
description: Lire et analyser du code sans effectuer de modifications. À utiliser pour la revue 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: Traiter les fichiers de données CSV et JSON avec des scripts Python. À utiliser lors de l'analyse de fichiers de données ou de la transformation de datasets.
---

# 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: Concevoir des APIs REST en respectant les bonnes pratiques. À utiliser lors de la création de points d'accès API, de la conception de routes ou de la planification de 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. Recueillir les exigences
2. Concevoir les points d'accès (voir examples.md)
3. Documenter avec une spec OpenAPI
4. Vérifier contre les bonnes pratiques (voir reference.md)

Bonnes 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 diraient
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 vos coéquipiers : Vérifiez l'activation et la clarté
Versionnez vos Skills : Documentez les modifications dans le contenu
Utilisez la divulgation progressive : Mettez les détails avancés dans des fichiers séparés

Liste de vérification de validation

Avant de finaliser une Skill, vérifiez :

[ ] Le nom est en minuscules, avec 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 fichier 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 de déclenchement
Incluez les types de fichiers et les opérations dans la description
Ajoutez une clause « Utiliser quand... » avec les phrases d'utilisateur

Plusieurs Skills entrent en conflit :

Rendez les descriptions plus distinctes
Utilisez des mots de déclenchement différents
Réduisez le périmètre de chaque Skill

La Skill a des erreurs :

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

Exemples

Consultez la documentation pour des exemples complets :

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

Format de sortie

Lors de la création d'une Skill, je vais :

Poser des questions de clarification sur le périmètre et les exigences
Suggérer un nom et un emplacement de Skill
Créer le fichier SKILL.md avec un frontmatter approprié
Inclure des instructions et des exemples clairs
Ajouter des fichiers supplémentaires si nécessaire
Fournir des instructions de test
Valider par rapport à tous les exigences

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

skill-writer