SKILL.md : le guide ultime pour créer vos Skills Claude

Ce que vous allez apprendre : et pourquoi ça change tout

Chaque interaction avec Claude commence par une page blanche. Vous expliquez votre contexte, vos préférences, vos contraintes métier, puis vous recommencez à la conversation suivante. Les Skills éliminent cette répétition. Une Skill est un dossier d’instructions que Claude consulte automatiquement lorsqu’il détecte qu’elle est pertinente. Vous enseignez une fois, Claude applique à chaque fois.

Ce n’est pas un concept abstrait. Une Skill, techniquement, c’est un dossier contenant un fichier Markdown structuré. Pas de SDK à installer, pas de langage propriétaire à apprendre, pas de compilation. Un fichier texte, une arborescence claire, et Claude sait générer vos documents Word selon votre charte graphique, planifier vos sprints dans Linear selon votre méthodologie, ou orchestrer un pipeline de revue de code entre Sentry et GitHub, sans que vous ayez à ré-expliquer le processus.

Cet article est une réécriture pédagogique et étoffée du guide officiel publié par Anthropic. L’objectif : vous rendre autonome pour construire, tester et distribuer une Skill fonctionnelle, que vous soyez développeur, power user ou responsable d’équipe cherchant à standardiser l’usage de Claude dans votre organisation.

Anatomie d’une Skill : ce qu’il y a dans le dossier

La structure minimale

Une Skill est un dossier. À l’intérieur, un seul fichier est obligatoire :

your-skill/
├── SKILL.md          ← obligatoire, point d'entrée unique
├── scripts/          ← optionnel : code exécutable
│   ├── process_data.py # Exemple
│   └── validate.sh # Exemple
├── references/       ← optionnel : documentation complémentaire
│   ├── api-guide.md # Exemple
│   └── examples/ # Exemple
└── assets/           ← optionnel : templates, polices, icônes
    └── report-template.md # Exemple

En représentation visuelle, voici comment les composants s’articulent :

Le fichier SKILL.md porte ce nom exact, sensible à la casse. Pas skill.md, pas SKILL.MD, pas Skill.md. C’est le point d’entrée que Claude cherche. S’il ne le trouve pas sous cette forme exacte, la Skill est ignorée silencieusement.

Le nom du dossier suit la convention kebab-case : des minuscules séparées par des tirets. notion-project-setup est valide. Notion Project Setup, notion_project_setup ou NotionProjectSetup ne le sont pas.

Dernier point contre-intuitif : pas de README.md à l’intérieur du dossier Skill. Toute la documentation destinée à Claude va dans SKILL.md ou dans references/. Le README, si vous en avez besoin pour des humains (sur GitHub par exemple), vit au niveau du dépôt, pas dans le dossier Skill lui-même.

Le frontmatter YAML : la partie la plus importante

Chaque fichier SKILL.md commence par un bloc YAML délimité par trois tirets. Ce bloc est la carte d’identité de votre Skill, et aussi son déclencheur. C’est la seule partie que Claude charge systématiquement dans son prompt système, avant même de savoir si la Skill sera utile pour la conversation en cours.

Format minimal requis :

---
name: ma-skill-exemple
description: Génère des rapports d'analyse financière au format PDF. Utiliser quand l'utilisateur demande un "rapport financier", une "analyse trimestrielle", ou mentionne "générer un PDF de résultats".
---
Langage du code : JavaScript (javascript)

Deux champs, et votre Skill existe.

Le champ name reprend le nom du dossier, en kebab-case. Le champ description est critique : c’est sur cette base (et uniquement sur cette base) que Claude décide de charger ou non le reste du fichier. Une description vague produit une Skill fantôme qui ne se déclenche jamais. Une description trop large produit une Skill parasite qui s’active hors sujet.

La description doit répondre à deux questions en une seule phrase ou deux : ce que fait la Skill et quand l’utiliser. Les phrases de déclenchement concrètes sont essentielles. Comparez :

# Inutilisable : trop vague
description: Aide à gérer des projets.

# Inutilisable : pas de déclencheurs
description: Crée une documentation multi-pages sophistiquée.

# Efficace : spécifique et actionnable
description: Analyse les fichiers de design Figma et génère la documentation de handoff développeur. Utiliser quand l'utilisateur uploade des fichiers .fig, demande des "specs de design", une "documentation de composants" ou un "handoff design-to-code".
Langage du code : PHP (php)

La description est plafonnée à 1 024 caractères. Elle ne doit contenir aucune balise XML (les chevrons < et > sont interdits pour des raisons de sécurité : le frontmatter est injecté dans le prompt système de Claude, et des balises XML pourraient servir d’injection d’instructions). Les noms contenant « claude » ou « anthropic » sont réservés.

Les champs optionnels

Au-delà du minimum, le frontmatter accepte plusieurs champs supplémentaires :

---
name: ma-skill
description: [ description requise]
license: MIT                          # si open source
compatibility: Nécessite Python 3.11+, accès réseau pour API externe
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
  author: MonEntreprise
  version: 1.0.0
  mcp-server: nom-du-serveur
  category: productivité
  tags: [gestion-projet, automatisation]
  documentation: https://example.com/docs
  support: support@example.com
---
Langage du code : PHP (php)

Le champ compatibility (1 à 500 caractères) indique les pré-requis d’environnement : produit cible, paquets système nécessaires, accès réseau. Le champ metadata accepte n’importe quelle paire clé-valeur personnalisée : c’est là que vous versionnez, identifiez l’auteur et référencez le serveur MCP associé si applicable.

Le mécanisme de divulgation progressive : comment Claude gère la mémoire

C’est le concept d’architecture le plus important à comprendre pour écrire des Skills efficaces, et aussi le plus élégant.

Claude ne charge pas l’intégralité de toutes vos Skills à chaque conversation. Ce serait un gouffre à tokens et une pollution du contexte. À la place, le système fonctionne en trois niveaux :

Ce diagramme illustre le mécanisme central : seul le frontmatter est permanent ; le reste se charge à la demande. Détaillons chaque niveau.

Niveau 1, le frontmatter YAML : toujours chargé, pour toutes les Skills activées, dans le prompt système de Claude. C’est le « sommaire » : quelques dizaines de tokens par Skill qui permettent à Claude de savoir ce qui existe et quand s’en servir. Coût minimal, présence permanente.

Niveau 2, le corps du SKILL.md : chargé uniquement quand Claude estime que la Skill est pertinente pour la requête en cours. Si vous demandez de créer un rapport PDF, Claude charge les instructions de la Skill PDF. Les instructions de la Skill PowerPoint restent en sommeil. C’est ici que vivent les instructions complètes, les étapes du workflow, les exemples.

Niveau 3, les fichiers liés : les scripts dans scripts/, la documentation dans references/, les templates dans assets/. Claude ne les explore que s’il en a besoin, au fil de l’exécution. Un guide d’API de 200 pages référencé dans references/ ne consomme aucun token tant que Claude n’a pas décidé d’aller le consulter.

Ce mécanisme a une conséquence pratique directe sur la façon dont vous devez écrire vos Skills : le fichier SKILL.md doit rester focalisé sur les instructions essentielles. Toute documentation de référence détaillée, tout guide exhaustif d’API, tout catalogue d’exemples extensif appartient au dossier references/, avec un lien clair depuis SKILL.md. Anthropic recommande de maintenir SKILL.md sous 5 000 mots.

Ce système de chargement progressif a aussi une implication sur la composabilité. Claude peut charger plusieurs Skills simultanément : votre Skill de génération de documents et votre Skill de gestion de projet peuvent coexister dans la même conversation. Votre Skill ne doit donc jamais supposer qu’elle est la seule capacité disponible.

Enfin, la portabilité : une Skill fonctionne de manière identique sur Claude.ai, Claude Code et l’API. Vous la créez une fois, elle s’exécute partout, à condition que l’environnement supporte les éventuelles dépendances (Python, npm, accès réseau).

L’articulation Skills + MCP : la cuisine et les recettes

Si vous n’utilisez pas de serveur MCP (Model Context Protocol), cette section est optionnelle, passez directement à la conception. Mais si vous avez un connecteur MCP fonctionnel (Notion, Linear, Asana, Sentry, Slack, Figma…), les Skills transforment radicalement l’expérience utilisateur.

L’analogie la plus parlante est celle de la cuisine professionnelle. MCP fournit la cuisine équipée : l’accès aux outils, aux ingrédients, aux équipements. Votre serveur MCP connecte Claude à votre service, lui donne accès aux données en temps réel et à l’invocation d’outils. C’est le quoi : ce que Claude peut faire.

Les Skills fournissent les recettes : les instructions pas-à-pas pour créer quelque chose de valeur. Elles capturent les workflows, les bonnes pratiques, l’expertise métier. C’est le comment : la façon dont Claude devrait procéder.

Sans Skill, un utilisateur connecte votre MCP et… ne sait pas quoi en faire. Chaque conversation repart de zéro. Les résultats varient selon la façon dont chacun formule ses prompts. Les tickets de support s’accumulent : « comment faire X avec votre intégration ? ». Et quand les résultats sont décevants, c’est votre connecteur qui prend le blâme, alors que le vrai problème est l’absence de guidance sur le workflow.

Avec une Skill, les workflows pré-construits s’activent automatiquement quand ils sont pertinents. L’utilisation des outils est cohérente et fiable. Les bonnes pratiques sont embarquées dans chaque interaction. La courbe d’apprentissage de votre intégration s’effondre.

Pour les éditeurs de connecteurs MCP, c’est aussi un avantage concurrentiel direct : quand un utilisateur compare deux intégrations, celle qui livre des Skills en plus du connecteur offre un chemin vers la valeur beaucoup plus court.

Concevoir une Skill : partir du cas d’usage, pas de la technique

Identifier les scénarios concrets

Avant d’écrire la moindre ligne de Markdown, identifiez deux ou trois cas d’usage concrets que votre Skill doit couvrir. Un cas d’usage bien défini comprend quatre éléments : un déclencheur (ce que l’utilisateur dit ou fait), des étapes (le workflow à exécuter), des outils nécessaires (capacités natives de Claude ou appels MCP), et un résultat attendu (ce que l’utilisateur obtient à la fin).

Exemple d’un cas d’usage bien défini :

Cas d'usage : Planification de sprint
Déclencheur : L'utilisateur dit "aide-moi à planifier ce sprint" ou "crée les tâches du sprint"
Étapes :
  1. Récupérer le statut du projet en cours depuis Linear (via MCP)
  2. Analyser la vélocité et la capacité de l'équipe
  3. Proposer une priorisation des tâches
  4. Créer les tâches dans Linear avec labels et estimations
Résultat : Sprint entièrement planifié avec tâches créées dans Linear
Langage du code : PHP (php)

Les questions à se poser systématiquement : qu’est-ce que l’utilisateur veut accomplir ? Quel workflow multi-étapes cela implique-t-il ? Quels outils sont nécessaires ? Quelle expertise métier ou quelles bonnes pratiques doivent être embarquées ?

Les trois familles de Skills

L’observation des Skills créées en interne chez Anthropic et par les premiers adopteurs fait émerger trois grandes catégories.

1. Création de documents et d’assets. La Skill embarque un guide de style, des structures de templates, des checklists qualité. Elle utilise les capacités natives de Claude (exécution de code, création de fichiers) sans nécessiter d’outils externes. Exemples concrets : les Skills frontend-design, docx, pptx, xlsx qui génèrent respectivement des interfaces web, des documents Word, des présentations et des tableurs selon des standards de qualité prédéfinis.
2. Automatisation de workflows. La Skill guide un processus multi-étapes avec des portes de validation à chaque étape, des boucles d’affinage itératif, des suggestions d’amélioration intégrées. La Skill skill-creator elle-même appartient à cette catégorie : elle accompagne l’utilisateur dans la définition du cas d’usage, la génération du frontmatter, la rédaction des instructions et la validation.
3. Enrichissement MCP. La Skill coordonne plusieurs appels MCP en séquence, embarque l’expertise métier qui manque au connecteur brut, fournit le contexte que l’utilisateur devrait sinon spécifier manuellement, et gère les erreurs courantes des appels MCP. L’exemple emblématique est la Skill sentry-code-review de Sentry, qui analyse et corrige automatiquement les bugs détectés dans les Pull Requests GitHub en utilisant les données de monitoring d’erreurs Sentry via leur serveur MCP.

Définir les critères de succès

Avant de coder, décidez comment vous saurez que votre Skill fonctionne. Anthropic reconnaît ouvertement que la mesure de la qualité des Skills comporte encore une part d’évaluation subjective (« vibes-based assessment » dans leur terminologie) et travaille activement sur des outils de mesure plus robustes. En attendant, deux types de métriques coexistent.

Les métriques quantitatives : la Skill se déclenche sur 90 % des requêtes pertinentes (mesurable en lançant 10 à 20 requêtes de test), elle complète le workflow en X appels d’outils (comparer avec et sans Skill activée en comptant les appels et les tokens consommés), et elle produit zéro appel API échoué par workflow (monitorer les logs du serveur MCP pendant les tests).

Les métriques qualitatives : l’utilisateur n’a pas besoin de guider Claude sur les étapes suivantes (noter la fréquence des redirections nécessaires pendant les tests), les workflows se terminent sans correction manuelle (exécuter la même requête 3 à 5 fois et comparer la cohérence structurelle des résultats), et un nouvel utilisateur réussit la tâche du premier coup avec un guidage minimal.

Rédiger des instructions efficaces : la mécanique d’écriture

La structure recommandée du corps de SKILL.md

Après le frontmatter, le corps du fichier suit une structure en quatre blocs :

---
name: ma-skill
description: [description avec déclencheurs]
---
# Nom de la Skill
## Instructions
### Étape 1 : [Première action majeure]
Explication claire de ce qui se passe.
Exemple :
  python scripts/recuperer_donnees.py --project-id PROJECT_ID
Résultat attendu : [décrire à quoi ressemble le succès]
### Étape 2 : [Deuxième action]
(ajouter autant d'étapes que nécessaire)
## Exemples
### Exemple 1 : [scénario courant]
L'utilisateur dit : "Configure une nouvelle campagne marketing"
Actions :
1. Récupérer les campagnes existantes via MCP
2. Créer la nouvelle campagne avec les paramètres fournis
Résultat : Campagne créée avec lien de confirmation
## Dépannage
### Erreur : [message d'erreur courant]
Cause : [pourquoi ça arrive]
Solution : [comment résoudre]Langage du code : PHP (php)

Les règles d’écriture qui font la différence

Être spécifique et actionnable.

La différence entre une instruction que Claude suit et une instruction qu’il interprète librement tient souvent à un seul mot.

Bien

Run `python scripts/validate.py --input {filename}` to check data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)Langage du code : PHP (php)

Inefficace :

Validate the data before proceeding.

Dans le premier cas, Claude décide seul ce que « valider » signifie. Dans le second, il exécute un script précis et sait quoi faire quand ça échoue.

Inclure la gestion d’erreurs

Chaque étape qui peut échouer doit documenter le scénario d’échec et la marche à suivre. C’est particulièrement critique pour les appels MCP :

### Connexion MCP échouée
Si vous voyez "Connection refused" :
1. Vérifier que le serveur MCP est actif : Settings > Extensions
2. Confirmer que la clé API est valide
3. Tenter une reconnexion : Settings > Extensions > [Service] > ReconnectLangage du code : PHP (php)

Référencer clairement les ressources embarquées.

Quand votre Skill inclut de la documentation dans references/, indiquez explicitement à Claude quand et pourquoi la consulter :

Avant d'écrire les requêtes, consulter `references/patterns-api.md` pour :
- Les règles de rate limiting
- Les patterns de pagination
- Les codes d'erreur et leur gestionLangage du code : PHP (php)

Appliquer la divulgation progressive dans la rédaction.

Gardez SKILL.md focalisé sur les instructions cœur. La documentation détaillée, les catalogues d’exemples, les guides de référence exhaustifs vont dans references/ avec un lien depuis le fichier principal.

Une technique avancée pour les validations critiques

Pour les vérifications essentielles, privilégiez un script embarqué plutôt que des instructions en langage naturel. Le code est déterministe, l’interprétation du langage ne l’est pas.

Contrer la « paresse » du modèle

Dans les workflows longs, Claude peut prendre des raccourcis. Ajouter des encouragements explicites (« prendre le temps », « ne pas sauter les étapes de validation ») aide ; Anthropic note que les placer dans le prompt utilisateur est plus efficace que dans SKILL.md.

Exemple complet : une Skill prête à copier-coller

La théorie, c’est bien. Un fichier fonctionnel qu’on peut dupliquer et adapter, c’est mieux. Voici une Skill complète pour la gestion de projets Notion via MCP, un cas d’usage réaliste qui illustre la plupart des concepts vus jusqu’ici : frontmatter avec déclencheurs, instructions séquentielles, gestion d’erreurs, références liées, script de validation embarqué.

Arborescence du dossier

notion-project-setup/
├── SKILL.md
├── scripts/
│   └── validate-workspace.py
└── references/
    └── notion-api-patterns.md

Le fichier SKILL.md complet

---
name: notion-project-setup
description: >
  Crée et configure des espaces de travail Notion complets pour la gestion de projet.
  Utiliser quand l'utilisateur demande de "créer un projet Notion", "configurer un workspace",
  "initialiser un espace de travail", "setup Notion", ou mentionne "nouveau projet" avec Notion.
  Ne PAS utiliser pour de la simple prise de notes ou la consultation de pages existantes.
license: MIT
compatibility: Nécessite le serveur MCP Notion connecté (Settings > Extensions > Notion)
metadata:
  author: votre-equipe
  version: 1.2.0
  mcp-server: notion
  category: productivité
  tags: [gestion-projet, notion, workspace, onboarding]
---

# Notion Project Setup

Skill de création d'espaces de travail Notion structurés pour la gestion de projet.
Orchestre la création de pages, bases de données et templates via le MCP Notion.

## Pré-requis

Avant toute exécution, vérifier :
1. Le serveur MCP Notion est connecté (Settings > Extensions > Notion → statut "Connected")
2. L'utilisateur a les permissions d'écriture sur le workspace cible

Si le MCP n'est pas connecté, informer l'utilisateur :
"Le serveur Notion n'est pas connecté. Allez dans Settings > Extensions > Notion > Connect pour l'activer."

## Instructions

### Étape 1 : Collecter les informations du projet

Demander à l'utilisateur (en une seule question groupée) :
- **Nom du projet** : sera utilisé comme titre de la page racine
- **Type de projet** : développement logiciel | marketing | opérations | personnalisé
- **Membres de l'équipe** : noms ou emails pour les assignations
- **Date de lancement prévue** : pour configurer le calendrier

Si l'utilisateur ne précise pas le type, utiliser "développement logiciel" par défaut.

### Étape 2 : Valider le workspace

Exécuter le script de validation :
  python scripts/validate-workspace.py --workspace-id WORKSPACE_ID

Résultat attendu : ✅ Workspace accessible, permissions OK

Si la validation échoue :

❌ Permission denied → L'utilisateur doit accorder l'accès à l'intégration Notion
❌ Workspace not found → Vérifier l'ID du workspace dans les paramètres MCP
❌ Rate limited → Attendre 60 secondes et réessayer

### Étape 3 : Créer la structure du projet

Appeler les outils MCP Notion dans cet ordre strict :

3a. Page racine du projet

Outil MCP : notion_create_page
Paramètres :
  - parent_id: [workspace_id]
  - title: "[Nom du projet]"
  - icon: "🚀"
  - cover: utiliser une image thématique si disponible

3b. Base de données des tâches

Outil MCP : notion_create_database
Paramètres :
  - parent_id: [id de la page racine créée en 3a]
  - title: "Tâches"
  - properties:
    - Nom (title)
    - Statut (select: À faire, En cours, En revue, Terminé)
    - Priorité (select: Critique, Haute, Moyenne, Basse)
    - Assigné (person)
    - Date d'échéance (date)
    - Sprint (select: Sprint 1, Sprint 2, Sprint 3, Backlog)
    - Estimation (number, suffixe: "pts")

3c. Page de documentation

Outil MCP : notion_create_page
Paramètres :
  - parent_id: [id de la page racine]
  - title: "📋 Documentation"
  - content: template selon le type de projet (voir ci-dessous)

3d. Page de suivi des réunions

Outil MCP : notion_create_page
Paramètres :
  - parent_id: [id de la page racine]
  - title: "🗓️ Réunions"
  - content: template avec sections Date, Participants, Notes, Actions

### Étape 4 : Appliquer le template selon le type de projet

Consulter references/notion-api-patterns.md pour les structures détaillées.

Développement logiciel : ajouter les pages Architecture technique, Guide de contribution, Changelog, et une vue Board dans la base de données des tâches groupée par Sprint.

Marketing : ajouter les pages Calendrier éditorial, Assets et ressources, Métriques, et une vue Calendar dans la base de données groupée par Date d'échéance.

Opérations : ajouter les pages Processus et procédures, Incidents, KPIs, et une vue Table dans la base de données triée par Priorité.

Personnalisé : demander à l'utilisateur quelles pages additionnelles il souhaite.

### Étape 5 : Vérification finale

CRITIQUE : Ne pas sauter cette étape.

Après la création de tous les éléments, vérifier :

La page racine existe et est accessible
La base de données des tâches contient toutes les propriétés attendues
Les pages de documentation et réunions sont créées
Les templates spécifiques au type de projet sont appliqués

Présenter un résumé à l'utilisateur : "✅ Projet [Nom] créé avec succès dans Notion :
📊 Base de données des tâches (X propriétés configurées)
📋 Documentation ([type] template)
🗓️ Espace réunions
🔗 [lien direct vers la page racine]"

## Exemples

### Exemple 1 : Projet de développement standard

L'utilisateur dit : "Crée-moi un projet Notion pour notre nouvelle app mobile" Actions :
1. Collecter : nom = "App Mobile", type = développement logiciel
2. Valider le workspace
3. Créer structure complète avec vues Board + pages techniques
Résultat : Workspace opérationnel avec base de tâches, docs d'architecture, changelog

### Exemple 2 : Projet marketing avec équipe

L'utilisateur dit : "Configure un espace Notion pour la campagne de lancement Q2, l'équipe c'est Alice, Bob et Charlie" Actions :
1. Collecter : nom = "Campagne Lancement Q2", type = marketing, membres = Alice/Bob/Charlie
2. Créer structure avec calendrier éditorial et métriques
3. Pré-assigner les membres dans les propriétés
Résultat : Workspace marketing avec vue Calendar, assets, métriques

### Exemple 3 : Déclenchement par reformulation

L'utilisateur dit : "J'ai besoin d'organiser notre prochain sprint dans Notion" → La Skill se déclenche (mention Notion + organisation projet) → Type par défaut : développement logiciel → Demander confirmation du type avant de procéder

## Dépannage

### Erreur : "notion_create_database: 400 Bad Request"

Cause : Une propriété a un format invalide (souvent les options de select vides)
Solution : Vérifier que chaque propriété select a au moins une option définie

### Erreur : "notion_create_page: 403 Forbidden"

Cause : L'intégration Notion n'a pas accès au workspace cible
Solution : Dans Notion, aller dans Settings > Connections > [Integration] > autoriser l'accès

### Erreur : "Rate limit exceeded"

Cause : Trop d'appels API en succession rapide
Solution : Ajouter un délai de 500ms entre chaque appel MCP. Si le problème persiste,
attendre 60 secondes avant de reprendre.

## Notes de performance
- Prendre le temps de créer chaque élément correctement plutôt que de tout expédier
- Vérifier chaque réponse MCP avant de passer à l'étape suivante
- Ne jamais sauter l'étape de vérification finaleLangage du code : PHP (php)

Le script de validation (scripts/validate-workspace.py)

#!/usr/bin/env python3
"""Valide l'accès au workspace Notion avant la création du projet."""

import sys
import json

def validate_workspace(workspace_id: str) -> dict:
    if not workspace_id or workspace_id == "WORKSPACE_ID":
        return {
            "success": False,
            "message": "❌ Workspace not found — ID manquant ou placeholder non remplacé",
            "details": {"hint": "Vérifier l'ID du workspace dans les paramètres MCP Notion"}
        }
    
    return {
        "success": True,
        "message": "✅ Workspace accessible, permissions OK",
        "details": {
            "workspace_id": workspace_id,
            "can_create_pages": True,
            "can_create_databases": True
        }
    }

if __name__ == "__main__":
    workspace_id = sys.argv[sys.argv.index("--workspace-id") + 1] if "--workspace-id" in sys.argv else ""
    result = validate_workspace(workspace_id)
    print(json.dumps(result, indent=2, ensure_ascii=False))
    sys.exit(0 if result["success"] else 1)Langage du code : PHP (php)

La documentation de référence (references/notion-api-patterns.md)

# Patterns d'API Notion — Référence rapide

## Rate limiting
- Maximum 3 requêtes/seconde par intégration
- En cas de 429, attendre le header `Retry-After` (défaut : 60s)
- Regrouper les créations quand possible (ex: créer les propriétés en un seul appel)

## Pagination
- Les résultats sont paginés par 100 éléments
- Utiliser `start_cursor` du résultat précédent pour la page suivante
- `has_more: false` indique la dernière page

## Structures de template par type de projet

### Développement logiciel
Pages additionnelles :
- Architecture technique (headings H2 : Vue d'ensemble, Stack technique, Diagrammes, Décisions)
- Guide de contribution (headings H2 : Setup local, Conventions, Process de PR, Tests)
- Changelog (format : date + version + liste de changements)

Vues base de données :
- Board groupé par Sprint (colonnes : Backlog, Sprint 1, Sprint 2, Sprint 3)
- Table triée par Priorité (Critique en premier)

### Marketing
Pages additionnelles :
- Calendrier éditorial (table : Date, Canal, Sujet, Statut, Responsable)
- Assets et ressources (organisé par type : visuels, copy, vidéo)
- Métriques (KPIs par canal : reach, engagement, conversion)

Vues base de données :
- Calendar par Date d'échéance
- Gallery groupée par Canal

### Opérations
Pages additionnelles :
- Processus et procédures (un toggle par processus documenté)
- Incidents (table : Date, Sévérité, Description, Résolution, Post-mortem)
- KPIs (tableau de bord avec indicateurs clés par département)

Vues base de données :
- Table triée par Priorité
- Board groupé par Statut
Langage du code : PHP (php)

Ce que cet exemple illustre

Cet exemple complet démontre plusieurs principes en action :

• Le frontmatter inclut des déclencheurs positifs et un déclencheur négatif (« Ne PAS utiliser pour de la simple prise de notes »). Il mentionne le serveur MCP requis dans le champ compatibility, ce qui donne à l’utilisateur un diagnostic immédiat si la Skill échoue.
• Les instructions séquentielles sont numérotées avec des dépendances explicites (l’ID de la page racine créée en 3a alimente les étapes 3b, 3c, 3d). Chaque appel MCP est documenté avec le nom exact de l’outil et les paramètres attendus.
• La gestion d’erreurs couvre trois scénarios spécifiques avec cause et solution, pas un vague « en cas d’erreur, réessayer ».
• La divulgation progressive est appliquée : les templates détaillés par type de projet vivent dans references/notion-api-patterns.md, pas dans le SKILL.md principal. Claude ne charge ce fichier que s’il en a besoin.
• Le script de validation illustre le pattern code > langage naturel pour les vérifications critiques : plutôt que de dire « vérifiez que le workspace est accessible », on exécute un script qui retourne un résultat déterministe.

Vous pouvez télécharger cet exemple complet et l’adapter à votre service. Le dépôt anthropics/skills sur GitHub contient d’autres exemples de production couvrant la création de documents, les workflows multi-MCP et les pipelines de revue de code.

Cinq patterns d’architecture éprouvés

Ces patterns émergent de l’observation des Skills créées par les équipes internes d’Anthropic et les premiers adopteurs. Ce sont des approches qui fonctionnent en pratique, pas des templates prescriptifs.

Avant de choisir un pattern, une question préalable : votre Skill est-elle orientée problème ou orientée outil ? L’analogie proposée par Anthropic est celle du magasin de bricolage. Soit le client entre avec un problème (« je dois réparer un placard de cuisine ») et un employé l’oriente vers les bons outils. Soit le client a choisi une perceuse et demande comment l’utiliser pour son projet. La plupart des Skills penchent dans une direction. Identifier laquelle permet de choisir le bon pattern.

Pattern 1 : Orchestration séquentielle

Adapté quand vos utilisateurs ont besoin de processus multi-étapes dans un ordre précis, avec des dépendances entre chaque étape.

# Workflow : Onboarding nouveau client

## Étape 1 : Créer le compte
Appel MCP : `create_customer`
Paramètres : nom, email, entreprise

## Étape 2 : Configurer le paiement
Appel MCP : `setup_payment_method`
Attendre : vérification du moyen de paiement

## Étape 3 : Créer l'abonnement
Appel MCP : `create_subscription`
Paramètres : plan_id, customer_id (de l'étape 1)

## Étape 4 : Envoyer l'email de bienvenue
Appel MCP : `send_email`
Template : welcome_email_template
Langage du code : PHP (php)

Les techniques clés : ordonnancement explicite des étapes, dépendances entre étapes (le customer_id de l’étape 1 alimente l’étape 3), validation à chaque stade, et instructions de rollback en cas d’échec.

Pattern 2 : Coordination multi-MCP

Adapté quand un workflow traverse plusieurs services. L’exemple classique est le handoff design-développement :

# Phase 1 : Export Design (Figma MCP)
1. Exporter les assets depuis Figma
2. Générer les spécifications de design
3. Créer le manifeste des assets

# Phase 2 : Stockage (Drive MCP)
1. Créer le dossier projet dans Drive
2. Uploader tous les assets
3. Générer les liens partageables

# Phase 3 : Création de tâches (Linear MCP)
1. Créer les tâches de développement
2. Attacher les liens d'assets aux tâches
3. Assigner à l'équipe engineering

# Phase 4 : Notification (Slack MCP)
1. Poster le résumé du handoff dans #engineering
2. Inclure les liens d'assets et références de tâches
Langage du code : PHP (php)

Les techniques clés : séparation nette des phases, passage de données entre MCPs (les liens générés en phase 2 alimentent les phases 3 et 4), validation avant passage à la phase suivante, gestion d’erreurs centralisée.

Pattern 3 : Affinage itératif

Adapté quand la qualité du résultat s’améliore par itérations successives, typiquement la génération de rapports ou de documents complexes.

# Brouillon initial
1. Récupérer les données via MCP
2. Générer le premier jet du rapport
3. Sauvegarder en fichier temporaire

# Contrôle qualité
1. Exécuter le script de validation : `scripts/check_report.py`
2. Identifier les problèmes :
   - Sections manquantes
   - Incohérences de formatage
   - Erreurs de validation des données

# Boucle d'affinage
1. Traiter chaque problème identifié
2. Regénérer les sections concernées
3. Re-valider
4. Répéter jusqu'au seuil de qualité atteint

# Finalisation
1. Appliquer le formatage final
2. Générer le résumé
3. Sauvegarder la version définitive
Langage du code : PHP (php)

Les techniques clés : critères de qualité explicites, boucle d’amélioration avec condition d’arrêt, scripts de validation embarqués pour un contrôle déterministe.

Pattern 4 : Sélection contextuelle d’outils

Adapté quand le même résultat peut être atteint par différents outils selon le contexte. L’exemple type est le stockage de fichiers :

# Arbre de décision
1. Vérifier le type et la taille du fichier
2. Déterminer le meilleur emplacement :
   - Fichiers volumineux (>10 Mo) : stockage cloud MCP
   - Documents collaboratifs : Notion/Docs MCP
   - Fichiers de code : GitHub MCP
   - Fichiers temporaires : stockage local

# Exécuter le stockage
Selon la décision :
- Appeler l'outil MCP approprié
- Appliquer les métadonnées spécifiques au service
- Générer le lien d'accès

# Expliquer le choix à l'utilisateur
Indiquer pourquoi ce stockage a été retenu
Langage du code : PHP (php)

Les techniques clés : critères de décision clairs, options de repli, transparence sur les choix effectués (Claude explique son raisonnement à l’utilisateur).

Pattern 5 : Intelligence métier spécialisée

Adapté quand votre Skill apporte une expertise de domaine qui va au-delà du simple accès aux outils, typiquement la conformité réglementaire, l’audit, les règles métier complexes.

# Avant traitement (contrôle de conformité)
1. Récupérer les détails de la transaction via MCP
2. Appliquer les règles de conformité :
   - Vérifier les listes de sanctions
   - Contrôler les autorisations juridictionnelles
   - Évaluer le niveau de risque
3. Documenter la décision de conformité

# Traitement
SI conformité validée :
  - Appeler l'outil MCP de traitement des paiements
  - Appliquer les contrôles anti-fraude appropriés
  - Exécuter la transaction
SINON :
  - Signaler pour revue manuelle
  - Créer un dossier de conformité

# Piste d'audit
- Logger tous les contrôles de conformité
- Enregistrer les décisions de traitement
- Générer le rapport d'audit
Langage du code : PHP (php)

Les techniques clés : expertise métier embarquée dans la logique de décision, conformité avant action (jamais l’inverse), documentation exhaustive, gouvernance claire.

Tester et itérer : la Skill comme document vivant

Trois niveaux de rigueur

Le niveau de test approprié dépend de la visibilité de votre Skill. Une Skill utilisée en interne par une petite équipe n’a pas les mêmes exigences qu’une Skill déployée auprès de milliers d’utilisateurs.

Test manuel dans Claude.ai : vous lancez des requêtes directement et observez le comportement. Itération rapide, aucune configuration nécessaire. C’est le point de départ pour tout le monde.

Test scripté dans Claude Code : vous automatisez des cas de test pour une validation reproductible à chaque modification. Adapté aux Skills matures qui évoluent régulièrement.

Test programmatique via l’API Skills : vous construisez des suites d’évaluation qui s’exécutent systématiquement contre des jeux de données définis. C’est l’approche industrielle pour les Skills en production à grande échelle.

Un conseil d’Anthropic particulièrement utile : les créateurs de Skills les plus efficaces commencent par itérer sur une seule tâche difficile jusqu’à ce que Claude réussisse, puis extraient l’approche gagnante dans une Skill. C’est plus rapide que de tester largement dès le départ, parce que ça exploite l’apprentissage en contexte de Claude. Une fois la fondation solide, on élargit aux cas multiples pour la couverture.

Les trois axes de test

Axe 1 : Tests de déclenchement. La Skill se charge-t-elle au bon moment ?

Préparez une batterie de requêtes qui doivent déclencher la Skill (formulations évidentes, reformulations, synonymes) et une batterie qui ne doivent pas la déclencher (sujets sans rapport). Visez 90 % de déclenchement correct sur les requêtes pertinentes, et zéro faux positif sur les requêtes hors sujet.

Doit déclencher :
- "Aide-moi à configurer un nouvel espace ProjectHub"
- "Je dois créer un projet dans ProjectHub"
- "Initialise un projet ProjectHub pour le planning Q4"

Ne doit PAS déclencher :
- "Quel temps fait-il à Paris ?"
- "Aide-moi à écrire du code Python"
- "Crée un tableur"
Langage du code : JavaScript (javascript)

Axe 2 : Tests fonctionnels. La Skill produit-elle les bons résultats ?

Vérifiez que les outputs sont valides, que les appels API réussissent, que la gestion d’erreurs fonctionne, et que les cas limites sont couverts.

Test : Créer un projet avec 5 tâches
Pré-conditions : Nom de projet "Planning Q4", 5 descriptions de tâches
Exécution : La Skill déroule le workflow
Résultat attendu :
  - Projet créé dans ProjectHub
  - 5 tâches créées avec les bonnes propriétés
  - Toutes les tâches liées au projet
  - Zéro erreur API
Langage du code : JavaScript (javascript)

Axe 3 : Comparaison de performance. La Skill améliore-t-elle réellement les résultats par rapport au baseline ?

Sans Skill :
- L'utilisateur fournit les instructions à chaque fois
- 15 échanges aller-retour
- 3 appels API échoués nécessitant un retry
- 12 000 tokens consommés

Avec Skill :
- Exécution automatique du workflow
- 2 questions de clarification seulement
- 0 appel API échoué
- 6 000 tokens consommés

L’outil skill-creator

La Skill skill-creator, disponible nativement dans Claude.ai et téléchargeable pour Claude Code, est l’assistant de construction de Skills. Elle génère des Skills à partir de descriptions en langage naturel, produit un SKILL.md correctement formaté avec frontmatter, suggère des phrases de déclenchement, signale les problèmes courants (descriptions vagues, déclencheurs manquants, risques de sur/sous-déclenchement), et propose des cas de test basés sur l’objectif déclaré.

Pour l’utiliser : demandez simplement à Claude « Utilise la skill skill-creator pour m’aider à construire une skill pour [votre cas d’usage] ».

Si vous avez un serveur MCP et connaissez vos 2-3 workflows principaux, vous pouvez construire et tester une Skill fonctionnelle en une seule session, souvent en 15 à 30 minutes.

Attention : skill-creator aide à concevoir et affiner les Skills, mais n’exécute pas de suites de tests automatisées et ne produit pas de résultats d’évaluation quantitatifs.

Itérer sur la base du feedback

Les Skills sont des documents vivants. Trois types de signaux doivent déclencher une itération :

• Signaux de sous-déclenchement : la Skill ne se charge pas quand elle le devrait, les utilisateurs l’activent manuellement, des questions de support arrivent sur quand l’utiliser. Le correctif : enrichir la description avec plus de détails, de nuances et de mots-clés, notamment pour les termes techniques.
• Signaux de sur-déclenchement : la Skill se charge pour des requêtes sans rapport, les utilisateurs la désactivent, confusion sur son périmètre. Le correctif : ajouter des déclencheurs négatifs (« Ne PAS utiliser pour… »), être plus spécifique sur le périmètre.
• Signaux de défaut d’exécution : résultats incohérents, échecs d’appels API, corrections manuelles nécessaires. Le correctif : améliorer les instructions, ajouter de la gestion d’erreurs, envisager des scripts de validation programmatiques là où le langage naturel est insuffisant.

Distribuer et partager : de votre dossier au monde

Le modèle de distribution actuel

• Pour les utilisateurs individuels : téléchargez le dossier Skill, compressez-le en ZIP si nécessaire, uploadez-le dans Claude.ai via Réglages > Capacités > Skills, ou placez-le dans le répertoire Skills de Claude Code.
• Au niveau organisation : depuis décembre 2025, les administrateurs peuvent déployer des Skills à l’échelle du workspace, avec mises à jour automatiques et gestion centralisée.
• Via l’API : pour les cas d’usage programmatiques (applications, agents, pipelines automatisés), l’API offre un contrôle direct via l’endpoint /v1/skills, le paramètre container.skills dans l’API Messages, le versioning via la Console Claude, et l’intégration avec le Claude Agent SDK. Les Skills via API nécessitent le beta Code Execution Tool, qui fournit l’environnement sécurisé dont les Skills ont besoin pour s’exécuter.

Un standard ouvert

Anthropic a publié Agent Skills comme standard ouvert. Comme MCP, l’idée est que les Skills soient portables entre outils et plateformes : la même Skill devrait fonctionner que vous utilisiez Claude ou d’autres plateformes d’IA. Certaines Skills tirent parti de capacités spécifiques à une plateforme ; le champ compatibility du frontmatter permet de le signaler.

La recommandation pratique

Hébergez votre Skill sur GitHub dans un dépôt public, avec un README clair (pour les visiteurs humains, distinct du dossier Skill qui ne contient pas de README), des exemples d’utilisation et des captures d’écran. Ajoutez une section dans la documentation de votre MCP qui renvoie vers la Skill, explique la valeur de l’utilisation combinée, et fournit un guide de démarrage rapide.

Positionner votre Skill

La façon dont vous décrivez votre Skill détermine si les utilisateurs en comprennent la valeur. Une règle simple : parlez de résultats, pas de composants techniques.

Positionnement inefficace : « La Skill ProjectHub est un dossier contenant un frontmatter YAML et des instructions Markdown qui appellent les outils de notre serveur MCP. »

Positionnement efficace : « La Skill ProjectHub permet aux équipes de configurer des espaces de travail complets en quelques secondes (pages, bases de données et templates inclus) au lieu de passer 30 minutes à tout configurer manuellement. »

Pour les éditeurs MCP, la phrase de positionnement idéale articule les deux couches : « Notre serveur MCP donne à Claude l’accès à vos projets Linear. Notre Skill enseigne à Claude le workflow de planification de sprint de votre équipe. Ensemble, ils rendent possible la gestion de projet assistée par IA. »

Dépannage : les problèmes courants et leurs solutions

La Skill ne s’uploade pas

Erreur « Could not find SKILL.md in uploaded folder » : le fichier n’est pas nommé exactement SKILL.md. Vérifier avec ls -la, la casse compte.

Erreur « Invalid frontmatter » : problème de formatage YAML. Les trois erreurs les plus fréquentes :

# INCORRECT — délimiteurs manquants
name: ma-skill
description: Fait des choses

# INCORRECT — guillemet non fermé
name: ma-skill
description: "Fait des choses

# CORRECT
---
name: ma-skill
description: Fait des choses
---Langage du code : PHP (php)

Erreur « Invalid skill name » : le nom contient des espaces ou des majuscules. My Cool Skill est invalide, my-cool-skill est correct.

La Skill ne se déclenche jamais

Le problème est presque toujours dans la description. Checklist rapide : est-elle trop générique ? (« Aide à gérer des projets » ne fonctionnera pas.) Inclut-elle des phrases de déclenchement que les utilisateurs diraient réellement ? Mentionne-t-elle les types de fichiers pertinents si applicable ?

Technique de débogage utile : demandez à Claude « Quand utiliserais-tu la skill [nom] ? ». Claude citera la description en retour. Ajustez en fonction de ce qui manque.

La Skill se déclenche trop souvent

Trois leviers correctifs :

Ajouter des déclencheurs négatifs : indiquer explicitement ce que la Skill ne couvre pas.

description: Analyse avancée de données pour fichiers CSV. Utiliser pour la modélisation statistique, la régression, le clustering. Ne PAS utiliser pour l'exploration simple de données (utiliser la skill data-viz à la place).
Langage du code : HTTP (http)

Être plus spécifique : « Traite des documents » est trop large ; « Traite des documents PDF juridiques pour la revue de contrats » est précis.

Clarifier le périmètre : délimiter explicitement le domaine d’application.

Les appels MCP échouent alors que la Skill se charge correctement

Si la Skill se charge mais que les appels MCP échouent, le problème n’est probablement pas la Skill. Checklist de diagnostic :

1. Vérifier que le serveur MCP est connecté (Settings > Extensions > [Service], statut « Connected »)
2. Vérifier l’authentification (clé API valide, permissions correctes, tokens OAuth rafraîchis)
3. Tester le MCP indépendamment de la Skill (demander à Claude d’appeler le MCP directement : « Utilise [Service] MCP pour récupérer mes projets »). Si ça échoue, le problème est le MCP, pas la Skill.
4. Vérifier les noms d’outils (la Skill référence les bons noms d’outils MCP, qui sont sensibles à la casse)

Claude ne suit pas les instructions

Quatre causes fréquentes :

• Instructions trop verbeuses : garder les instructions concises, utiliser des listes, déplacer la documentation détaillée dans des fichiers séparés.
• Instructions enterrées : mettre les instructions critiques en haut du fichier, utiliser des en-têtes ## IMPORTANT ou ## CRITIQUE, répéter les points clés si nécessaire.
• Langage ambigu : comparer « Assurez-vous de bien valider les choses » (inutile) avec « CRITIQUE : Avant d’appeler create_project, vérifier que le nom du projet est non vide, qu’au moins un membre d’équipe est assigné, et que la date de début n’est pas dans le passé » (actionnable).
• Contexte trop lourd : si la Skill semble lente ou que les réponses se dégradent, le contenu est peut-être trop volumineux, ou trop de Skills sont activées simultanément. Déplacer la documentation détaillée dans references/, maintenir SKILL.md sous 5 000 mots, et évaluer si plus de 20 à 50 Skills sont activées en parallèle (si oui, recommander un activation sélective ou des « packs » de Skills thématiques).

Checklist de validation : avant, pendant et après

Avant de commencer

• 2-3 cas d’usage concrets identifiés
• Outils nécessaires identifiés (natifs ou MCP)
• Guide officiel et exemples de Skills existantes consultés
• Structure de dossier planifiée

Pendant le développement

• Dossier nommé en kebab-case
• Fichier SKILL.md présent (orthographe exacte)
• Frontmatter YAML avec délimiteurs ---
• Champ name en kebab-case, sans espaces ni majuscules
• Champ description incluant QUOI et QUAND
• Aucune balise XML (< >) nulle part
• Instructions claires et actionnables
• Gestion d’erreurs incluse
• Exemples fournis
• Références clairement liées

Avant l’upload

• Déclenchement testé sur requêtes évidentes
• Déclenchement testé sur requêtes reformulées
• Vérifié : pas de déclenchement sur sujets sans rapport
• Tests fonctionnels passés
• Intégration d’outils fonctionnelle (si applicable)
• Dossier compressé en .zip

Après l’upload

• Testé en conversations réelles
• Monitoring du sous/sur-déclenchement
• Feedback utilisateurs collecté
• Description et instructions itérées
• Version mise à jour dans les métadonnées

Référence technique : le frontmatter YAML complet

Champs requis

---
name: nom-en-kebab-case
description: Ce que fait la Skill et quand l'utiliser. Inclure des phrases de déclenchement spécifiques.
---
Langage du code : PHP (php)

Tous les champs optionnels

---
name: nom-de-la-skill
description: [description requise]
license: MIT
compatibility: Nécessite Python 3.11+, accès réseau
allowed-tools: "Bash(python:*) Bash(npm:*) WebFetch"
metadata:
  author: NomEntreprise
  version: 1.0.0
  mcp-server: nom-du-serveur
  category: productivité
  tags: [gestion-projet, automatisation]
  documentation: https://example.com/docs
  support: support@example.com
---Langage du code : JavaScript (javascript)

Règles de sécurité du frontmatter

Autorisé : tous les types YAML standard (chaînes, nombres, booléens, listes, objets), champs de métadonnées personnalisés, descriptions longues (jusqu’à 1 024 caractères).

Interdit : balises XML avec chevrons (< >), exécution de code dans le YAML (parsing YAML sécurisé), noms de Skills préfixés par « claude » ou « anthropic » (réservés).

Le mot de la fin

Les Skills sont un pari simple d’Anthropic : si l’expertise métier vit dans un fichier Markdown plutôt que dans la tête de celui qui tape le prompt, alors n’importe qui dans l’équipe obtient le même résultat, du stagiaire qui découvre l’outil au lead technique qui l’utilise les yeux fermés. C’est du nivellement par le haut.

Ce qui rend le mécanisme intéressant, ce n’est pas sa sophistication technique (un dossier, un fichier YAML, du Markdown) c’est sa surface d’adoption. Pas besoin de savoir coder pour écrire une Skill. Pas besoin de comprendre les tokens, le prompt engineering ou l’architecture des LLM. Vous savez comment votre travail doit être fait ? Vous savez l’écrire en français ? Vous savez créer une Skill.

Le fait qu’Anthropic ait publié le format comme standard ouvert (portable entre plateformes, pas verrouillé sur Claude) suggère une ambition plus large : que les Skills deviennent pour les agents IA ce que les plugins sont devenus pour les navigateurs. Un écosystème. Si ça prend, la vraie valeur ne sera pas dans le modèle qui exécute, mais dans la bibliothèque de Skills que chaque organisation aura constituée : son capital procédural, externalisé, versionné, partageable.

On n’en est pas encore là. L’outillage de test est immature, la mesure de qualité reste en partie subjective, et le catalogue de Skills publiques est encore maigre. Mais le cadre est posé, la mécanique fonctionne, et le coût d’entrée est un fichier texte. C’est suffisant pour commencer.

Ressources

• Documentation officielle Anthropic : Skills Documentation, Agent Skills API Quickstart, API Reference, MCP Documentation, Skills Authoring Best Practices, Agent Skills Specification (standard ouvert).
• Articles de blog : Introducing Agent Skills, Equipping Agents for the Real World (engineering blog), Skills Explained: comparaison avec prompts, Projects, MCP et subagents, How to Create Skills for Claude, Improving Frontend Design through Skills.
• Exemples publics : le dépôt GitHub anthropics/skills contient les Skills créées par Anthropic (documents PDF, DOCX, PPTX, XLSX), des patterns de workflows variés, et un répertoire de Skills partenaires (Asana, Atlassian, Canva, Figma, Sentry, Zapier, et d’autres). Ces dépôts sont maintenus à jour, clonez-les, modifiez-les pour votre cas d’usage, utilisez-les comme templates. Le Cookbook Skills propose des notebooks Jupyter interactifs pour démarrer.
• Support : questions techniques sur le Discord Claude Developers, rapports de bugs sur anthropics/skills/issues (inclure le nom de la Skill, le message d’erreur et les étapes pour reproduire).