Bonnes pratiques

Les bonnes Skills sont concises, bien structurées et testées en usage réel. Ce guide présente des décisions pratiques de rédaction pour vous aider à écrire des Skills que Claude peut découvrir et utiliser efficacement.

Pour le contexte conceptuel sur le fonctionnement de Skills, consultez la vue d’ensemble des Skills.

Principes fondamentaux

La concision est essentielle

La fenêtre de contexte est un bien commun. Votre Skill la partage avec tout ce que Claude doit connaître: prompt système, historique de conversation, métadonnées d’autres Skills et demande réelle.

Tous les tokens d’une Skill n’ont pas un coût immédiat. Au démarrage, seules les métadonnées (name et description) de toutes les Skills sont préchargées. Claude lit SKILL.md seulement quand la Skill devient pertinente, et lit les fichiers supplémentaires seulement au besoin. Mais la concision reste importante: une fois SKILL.md chargé, chaque token concurrence l’historique de conversation et les autres contextes.

Hypothèse par défaut: Claude est déjà très intelligent.

Ajoutez uniquement le contexte que Claude n’a pas déjà. Interrogez chaque information:

• "Claude a-t-il vraiment besoin de cette explication?"
• "Puis-je supposer que Claude sait déjà cela?"
• "Ce paragraphe justifie-t-il son coût en tokens?"

Bon exemple: concis:

## Extract PDF text

Use pdfplumber for text extraction:
```python
import pdfplumber

with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

Mauvais exemple: trop verbeux:

## Extract PDF text

PDF (Portable Document Format) files are a common file format that contains
text, images, and other content. To extract text from a PDF, you'll need to
use a library. There are many libraries available for PDF processing, but we
recommend pdfplumber because it's easy to use and handles most cases well.
First, you'll need to install it using pip. Then you can use the code below...

La version concise suppose que Claude sait ce qu’est un PDF et comment fonctionnent les bibliothèques.

Définir le bon degré de liberté

Adaptez le niveau de précision à la fragilité et à la variabilité de la tâche.

Haute liberté: plusieurs approches sont valides, les décisions dépendent du contexte, et des heuristiques guident la démarche.

## Code review process

1. Analyze the code structure and organization
2. Check for potential bugs or edge cases
3. Suggest improvements for readability and maintainability
4. Verify adherence to project conventions

Liberté moyenne: un modèle préféré existe, une certaine variation est acceptable, et la configuration influence le comportement.

## Generate report

Use this template and customize as needed:
```python
def generate_report(data, format="markdown", include_charts=True):
    # Process data
    # Generate output in specified format
    # Optionally include visualizations
```

Faible liberté: les opérations sont fragiles, la cohérence est critique ou une séquence précise doit être suivie.

## Database migration

Run exactly this script:
```bash
python scripts/migrate.py --verify --backup
```

Do not modify the command or add additional flags.

Imaginez Claude comme un robot qui explore un chemin. Sur un pont étroit avec des falaises des deux côtés, il n’existe qu’un chemin sûr: donnez des garde-fous précis et des instructions exactes. Dans un champ ouvert sans danger, de nombreux chemins mènent au succès: donnez une direction générale et laissez Claude trouver la meilleure route.

Tester avec tous les modèles prévus

Skills agissent comme des ajouts aux modèles; leur efficacité dépend donc du modèle sous-jacent. Testez votre Skill avec tous les modèles que vous prévoyez d’utiliser.

• Claude Haiku: la Skill donne-t-elle assez de guidance?
• Claude Sonnet: la Skill est-elle claire et efficace?
• Claude Opus: la Skill évite-t-elle d’expliquer excessivement?

Ce qui fonctionne parfaitement avec Opus peut nécessiter plus de détails pour Haiku. Si une Skill doit fonctionner avec plusieurs modèles, visez des instructions robustes pour tous.

Structure d’une Skill

Conventions de nommage

Utilisez des noms cohérents pour faciliter la référence et la discussion. Nous recommandons la forme en -ing en anglais pour les noms de Skills, car elle décrit clairement l’activité ou la capacité.

Bons exemples: "Processing PDFs", "Analyzing spreadsheets", "Managing databases", "Testing code", "Writing documentation".

Alternatives acceptables: groupes nominaux comme "PDF Processing" ou formes orientées action comme "Process PDFs".

À éviter: noms vagues ("Helper", "Utils", "Tools"), trop génériques ("Documents", "Data", "Files") ou incohérents dans une même collection.

Un nommage cohérent aide à référencer les Skills, comprendre leur rôle d’un coup d’œil, les organiser et maintenir une bibliothèque professionnelle.

Rédiger des descriptions efficaces

Le champ description permet la découverte de Skill et doit inclure ce que la Skill fait et quand l’utiliser.

Soyez spécifique et incluez les termes clés. Claude utilise cette description pour choisir la bonne Skill parmi potentiellement plus de 100 Skills. Les détails d’implémentation appartiennent au reste de SKILL.md.

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.

description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.

Évitez les descriptions vagues comme:

description: Helps with documents

description: Processes data

description: Does stuff with files

Modèles de divulgation progressive

SKILL.md sert de vue d’ensemble qui pointe Claude vers des ressources détaillées au besoin, comme une table des matières dans un guide d’intégration. Pour les détails, consultez Fonctionnement de Skills.

Conseils pratiques:

• Gardez le corps de SKILL.md sous 500 lignes
• Divisez le contenu en fichiers séparés à l’approche de cette limite
• Organisez instructions, code et ressources avec les modèles ci-dessous

Une Skill simple commence avec un seul fichier SKILL.md contenant métadonnées et instructions.

À mesure qu’elle grandit, vous pouvez regrouper des contenus supplémentaires que Claude charge uniquement au besoin.

pdf/
|-- SKILL.md
|-- FORMS.md
|-- reference.md
|-- examples.md
`-- scripts/
  |-- analyze_form.py
  |-- fill_form.py
  `-- validate.py

Modèle 1: guide de haut niveau avec références

---
name: PDF Processing
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

# PDF Processing

## Quick start

Extract text with pdfplumber:
```python
import pdfplumber
with pdfplumber.open("file.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

## Advanced features

**Form filling**: See [FORMS.md](FORMS.md) for complete guide
**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods
**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Claude ne charge ces fichiers que lorsqu’ils sont nécessaires.

Modèle 2: organisation par domaine

Pour les Skills couvrant plusieurs domaines, organisez par domaine afin d’éviter le contexte inutile. Une question sur les métriques sales ne doit pas charger finance ou marketing.

bigquery-skill/
|-- SKILL.md (overview and navigation)
`-- reference/
  |-- finance.md (revenue, billing metrics)
  |-- sales.md (opportunities, pipeline)
  |-- product.md (API usage, features)
  `-- marketing.md (campaigns, attribution)

# BigQuery Data Analysis

## Available datasets

**Finance**: Revenue, ARR, billing -> See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts -> See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption -> See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email -> See [reference/marketing.md](reference/marketing.md)

Modèle 3: détails conditionnels

Présentez le contenu de base et liez le contenu avancé.

# DOCX Processing

## Creating documents
Use docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

## Editing documents
For simple edits, modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)

Claude lit REDLINING.md ou OOXML.md seulement si ces fonctionnalités sont nécessaires.

Éviter les références trop imbriquées

Claude peut lire partiellement les fichiers référencés par d’autres fichiers référencés. Gardez les références à un niveau depuis SKILL.md et liez directement tous les fichiers importants.

# Mauvais
SKILL.md -> advanced.md -> details.md

# Bon
SKILL.md lie directement advanced.md, reference.md et examples.md

Ajouter une table des matières aux fichiers longs

Pour les fichiers de référence de plus de 100 lignes, mettez une table des matières au début afin que Claude voie l’ensemble des informations disponibles même lors d’une lecture partielle.

Workflows et boucles de feedback

Utiliser des workflows pour les tâches complexes

Découpez les opérations complexes en étapes claires. Pour les workflows particulièrement complexes, fournissez une checklist que Claude peut copier et cocher.

## Research synthesis workflow

Research Progress:
- [ ] Step 1: Read all source documents
- [ ] Step 2: Identify key themes
- [ ] Step 3: Cross-reference claims
- [ ] Step 4: Create structured summary
- [ ] Step 5: Verify citations

Ce modèle s’applique aussi aux tâches d’analyse sans code. Pour les Skills avec code, indiquez les scripts à exécuter:

## PDF form filling workflow

Task Progress:
- [ ] Step 1: Analyze the form (run analyze_form.py)
- [ ] Step 2: Create field mapping (edit fields.json)
- [ ] Step 3: Validate mapping (run validate_fields.py)
- [ ] Step 4: Fill the form (run fill_form.py)
- [ ] Step 5: Verify output (run verify_output.py)

Implémenter des boucles de feedback

Modèle courant: exécuter un validateur -> corriger les erreurs -> répéter.

Dans une Skill sans code, le validateur peut être STYLE_GUIDE.md que Claude lit et compare au contenu. Dans une Skill avec code, validez immédiatement après modification, corrigez les erreurs, puis ne continuez que lorsque la validation passe.

## Document editing process

1. Make your edits to `word/document.xml`
2. **Validate immediately**: `python ooxml/scripts/validate.py unpacked_dir/`
3. If validation fails, fix XML and validate again
4. **Only proceed when validation passes**
5. Rebuild and test the output document

Directives de contenu

Éviter les informations sensibles au temps

N’incluez pas d’informations qui deviendront obsolètes. Préférez une méthode actuelle et une section "Old patterns" pour l’historique.

## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`

## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>

Utiliser une terminologie cohérente

Choisissez un terme et utilisez-le partout: "API endpoint", "field", "extract". Ne mélangez pas "URL", "route", "path", "box", "element", "pull" ou "retrieve" sans raison. La cohérence aide Claude à suivre les instructions.

Modèles courants

Modèle de template

Fournissez des modèles de format de sortie et adaptez leur rigidité au besoin.

## Report structure

ALWAYS use this exact template structure:
```markdown
# [Analysis Title]

## Executive summary
[One-paragraph overview of key findings]

## Key findings
- Finding 1 with supporting data
- Finding 2 with supporting data
- Finding 3 with supporting data

## Recommendations
1. Specific actionable recommendation
2. Specific actionable recommendation
```

Si l’adaptation est utile, donnez un format par défaut sensé et autorisez Claude à l’ajuster.

Modèle d’exemples

Quand la qualité dépend d’exemples, fournissez des paires entrée/sortie.

## Commit message format

Input: Added user authentication with JWT tokens
Output:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

Input: Fixed bug where dates displayed incorrectly in reports
Output:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

Les exemples transmettent le style et le niveau de détail mieux que des descriptions seules.

Modèle de workflow conditionnel

Guidez Claude dans les points de décision.

## Document modification workflow

1. Determine the modification type:
 **Creating new content?** -> Follow "Creation workflow" below
 **Editing existing content?** -> Follow "Editing workflow" below

2. Creation workflow:
 - Use docx-js library
 - Build document from scratch
 - Export to .docx format

3. Editing workflow:
 - Unpack existing document
 - Modify XML directly
 - Validate after each change
 - Repack when complete

Évaluation et itération

Construire les évaluations d’abord

Créez les évaluations avant d’écrire beaucoup de documentation. Cela garantit que la Skill résout de vrais problèmes.

1. Identifiez les lacunes en lançant Claude sans Skill sur des tâches représentatives
2. Créez trois scénarios testant ces lacunes
3. Mesurez la performance sans Skill
4. Écrivez des instructions minimales
5. Exécutez les évaluations, comparez et affinez

{
"skills": ["pdf-processing"],
"query": "Extract all text from this PDF file and save it to output.txt",
"files": ["test-files/document.pdf"],
"expected_behavior": [
  "Successfully reads the PDF file using an appropriate PDF processing library or command-line tool",
  "Extracts text content from all pages in the document without missing any pages",
  "Saves the extracted text to a file named output.txt in a clear, readable format"
]
}

Développer Skills itérativement avec Claude

Travaillez avec une instance ("Claude A") pour créer une Skill destinée à d’autres instances ("Claude B"). Claude A aide à concevoir les instructions; Claude B les teste sur des tâches réelles. Commencez par résoudre une tâche sans Skill, observez le contexte et les règles que vous répétez, demandez à Claude A de les transformer en Skill, puis testez avec Claude B. Si Claude B oublie une règle ou ne trouve pas une information, revenez à Claude A avec cette observation et améliorez la Skill.

Pour les Skills existantes, alternez entre amélioration avec Claude A, test avec Claude B et observation du comportement. Intégrez aussi les retours de l’équipe: activation attendue, clarté des instructions, manques éventuels.

Observer comment Claude navigue dans Skills

Surveillez les chemins d’exploration inattendus, les liens non suivis, la dépendance excessive à certains fichiers et les contenus jamais consultés. Itérez sur ces observations. name et description sont essentiels pour décider quand déclencher la Skill.

Antipatterns à éviter

Éviter les chemins Windows

Utilisez toujours des barres obliques.

• Bon: scripts/helper.py, reference/guide.md
• À éviter: scripts\helper.py, reference\guide.md

Éviter trop d’options

Ne proposez pas plusieurs approches si ce n’est pas nécessaire.

**Bad example: Too many choices**:
"You can use pypdf, or pdfplumber, or PyMuPDF, or pdf2image, or..."

**Good example: Provide a default**:
"Use pdfplumber for text extraction:
```python
import pdfplumber
```

For scanned PDFs requiring OCR, use pdf2image with pytesseract instead."

Avancé: Skills avec code exécutable

Ces sections concernent les Skills avec scripts exécutables. Si votre Skill n’utilise que Markdown, passez à la checklist.

Résoudre, ne pas déléguer

Dans les scripts, gérez les erreurs au lieu de les laisser à Claude.

def process_file(path):
  """Process a file, creating it if it doesn't exist."""
  try:
      with open(path) as f:
          return f.read()
  except FileNotFoundError:
      print(f"File {path} not found, creating default")
      with open(path, 'w') as f:
          f.write('')
      return ''
  except PermissionError:
      print(f"Cannot access {path}, using default")
      return ''

Documentez aussi les paramètres pour éviter les "voodoo constants".

# HTTP requests typically complete within 30 seconds
REQUEST_TIMEOUT = 30

# Three retries balances reliability vs speed
MAX_RETRIES = 3

Fournir des scripts utilitaires

Des scripts prêts à l’emploi sont plus fiables que du code généré, économisent des tokens et du temps, et garantissent la cohérence.

Précisez si Claude doit exécuter le script ou le lire comme référence.

## Utility scripts

**analyze_form.py**:
```bash
python scripts/analyze_form.py input.pdf > fields.json
```

**validate_boxes.py**:
```bash
python scripts/validate_boxes.py fields.json
```

**fill_form.py**:
```bash
python scripts/fill_form.py input.pdf fields.json output.pdf
```

Utiliser l’analyse visuelle

Si les entrées peuvent être rendues en images, faites-les analyser visuellement par Claude.

## Form layout analysis

1. Convert PDF to images:
```bash
   python scripts/pdf_to_images.py form.pdf
```
2. Analyze each page image to identify form fields

Créer des sorties intermédiaires vérifiables

Pour les tâches complexes, utilisez "plan-validate-execute": Claude produit un plan structuré, un script le valide, puis seulement il est exécuté. Cela détecte les erreurs tôt, permet une vérification objective, protège les originaux et rend le débogage plus clair.

Empaqueter les dépendances

• claude.ai peut installer depuis npm et PyPI et récupérer des dépôts GitHub
• Anthropic API n’a pas d’accès réseau ni d’installation de paquets à l’exécution

Listez les paquets requis dans SKILL.md et vérifiez leur disponibilité dans la documentation de l’outil d’exécution de code.

Environnement d’exécution

Skills disposent d’un système de fichiers, de bash et de l’exécution de code. Les métadonnées sont préchargées; les fichiers se lisent à la demande; les scripts s’exécutent sans charger tout leur contenu; les gros fichiers ne coûtent rien tant qu’ils ne sont pas lus. Utilisez des chemins avec /, des noms descriptifs, une organisation par domaine et des scripts pour les opérations déterministes.

Références aux outils MCP

Utilisez des noms complètement qualifiés.

Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.

Ne pas supposer que les outils sont installés

**Bad example: Assumes installation**:
"Use the pdf library to process the file."

**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`

Then use it:
```python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
```

Notes techniques

Exigences YAML frontmatter

Le frontmatter de SKILL.md inclut seulement name et description. Consultez la vue d’ensemble.

Budget de tokens

Gardez SKILL.md sous 500 lignes. Si le contenu dépasse cette limite, séparez-le en fichiers selon les modèles de divulgation progressive.

Checklist pour Skills efficaces

Qualité centrale

• La description est spécifique et contient des termes clés
• Elle dit ce que fait la Skill et quand l’utiliser
• SKILL.md fait moins de 500 lignes
• Les détails supplémentaires sont dans des fichiers séparés
• Pas d’informations sensibles au temps, ou section "old patterns"
• Terminologie cohérente
• Exemples concrets
• Références à un seul niveau
• Divulgation progressive utilisée correctement
• Workflows avec étapes claires

Code et scripts

• Les scripts résolvent au lieu de déléguer à Claude
• Gestion d’erreur explicite et utile
• Pas de "voodoo constants"
• Paquets requis listés et vérifiés
• Scripts documentés clairement
• Pas de chemins Windows
• Étapes de validation pour opérations critiques
• Boucles de feedback pour tâches critiques

Tests

• Au moins trois évaluations créées
• Testé avec Haiku, Sonnet et Opus
• Testé avec des scénarios réels
• Feedback d’équipe intégré si applicable

Étapes suivantes