Créer des skills

Les skills sont du markdown (plus des scripts optionnels) qui enseignent à l'agent un flux de travail ciblé. Gardez SKILL.md court—la context window est partagée avec le chat, le code et les autres skills.

Où les skills vivent

Ne mettez pas les skills personnalisés dans ~/.cursor/skills-cursor/—c'est réservé aux skills intégrés de Cursor.

Préférez les plugins .claude/plugins/n8n/skills/ pour tout ce qui devrait correspondre à la façon de travailler du reste de l'équipe.

Avant de l'écrire : rassemblez les exigences

Demandez (ou déduisez) brièvement :

1. Objectif — une tâche ou un flux de travail concret.
2. Déclencheurs — quand l'agent doit-il appliquer ce skill ?
3. Lacunes — qu'est-ce que l'agent ne connaît pas déjà (règles du projet, URLs, formats) ?
4. Résultats — modèles, listes de contrôle ou formats stricts ?
5. Exemples — suivez un skill existant dans .claude/plugins/n8n/skills/ s'il correspond.

Posez la question à l'utilisateur en langage clair quand vous avez besoin de plus de détails.

Disposition des fichiers

skill-name/
├── SKILL.md       # obligatoire
├── reference.md   # optionnel — le détail que l'agent ne lit que si nécessaire
├── examples.md    # optionnel
└── scripts/       # optionnel

Frontmatter (obligatoire)

---
name: skill-name          # minuscules, tirets, 64 caractères max
description: >-         # 1024 caractères max, non-vide — voir ci-dessous
  ...
---

Description (la découverte est tout—troisième personne, QUOI + QUAND, mots-clés déclencheurs) :

• Bon : Extracts tables from PDFs and fills forms. Use when the user works with PDFs, forms, or document extraction.
• Mauvais : Helps with documents ou I can help you with PDFs

Règles de rédaction

1. Concis — supposez que le modèle est capable ; n'ajoutez que les faits de domaine ou du projet non évidents.
2. Divulgation progressive — l'essentiel dans SKILL.md ; référence longue dans reference.md. Lien un niveau de profondeur depuis SKILL.md.
3. Préférez un seul défaut — par ex. une seule bibliothèque ou un seul flux de travail ; ajoutez une échappatoire seulement si nécessaire.
4. Vocabulaire stable — un terme par concept ; évitez les notes datées « jusqu'au mois X » sauf si vous les cachez derrière une brève note « Deprecated ».
5. Chemins — slashes forward uniquement (scripts/foo.py).

Taille approximative : visez bien moins de ~200 lignes dans SKILL.md ; si ça grandit, séparez les détails.

Portée : un travail par skill (et skills parents)

• Responsabilité unique — un flux de travail ou un arbre de décision principal par skill. Si les déclencheurs et les étapes divergent beaucoup (par ex. « créer issue » vs « créer PR » vs « flux complet ticket → PR »), divisez en skills plus petits et dédiés.
• Préférez petit + composable — deux ou trois skills ciblés gardent les détails non pertinents hors du contexte jusqu'à ce qu'ils soient nécessaires. Un skill parent (orchestrateur) peut dire quand suivre chaque flux de travail enfant et lier leur SKILL.md ; évitez de coller le contenu enfant complet dans le parent.
• Quand un large skill unique convient — un flux de bout en bout unique qui s'exécute toujours ensemble et partage une seule liste de contrôle serrée ;

MCPs, outils CLI et autres skills

• Préférez CLI et commandes repo quand elles résolvent le même problème — les agents les gèrent bien et elles ajoutent généralement moins de bruit de scaffolding au contexte que la découverte et les schémas d'outils MCP. Exemples : gh pour les PRs/issues, scripts pnpm de AGENTS.md.
• Les MCPs sont optionnels par utilisateur — tout le monde n'a pas les mêmes serveurs activés. Si un skill nécessite un MCP spécifique pour fonctionner comme écrit, dites-le explicitement :
  • Mettez un indice dans la description frontmatter (par ex. « Requires Linear MCP for … ») pour que les incompatibilités soient évidentes tôt.
  • Ajoutez un bloc Prerequisites (ou Requirements) court près du haut : quelle intégration, à quoi elle sert, et une fallback (par ex. interface web, gh, ou « demandez à l'utilisateur de coller … ») quand elle manque.
• Référencer d'autres skills — utilisez le nom d'invocation avec namespace (par ex. n8n:create-issue) pour que l'agent résolve le skill du plugin. Pour les liens lisibles par l'humain, donnez le chemin depuis la racine du repo (par ex. .claude/plugins/n8n/skills/create-issue/SKILL.md). Depuis un dossier frère, un lien relatif fonctionne aussi : [create-issue](../create-issue/SKILL.md). Les skills parents devraient déléguer les étapes au lieu de dupliquer de longues procédures.

Patterns (choisissez ce qui convient)

• Template — donnez la forme exacte du résultat (blocs markdown/code).
• Checklist — étapes numérotées ou - [ ] pour le travail multi-étapes.
• Branchement — « Si A → … ; si B → … » en haut d'un flux de travail.
• Scripts — documentez les commandes d'exécution ; dites si vous devez exécuter ou lire le script.

Flux de travail : créer → vérifier

1. Nom + description — nom avec tirets ; description avec déclencheurs.
2. Contour — sections minimales ; liez les fichiers optionnels.
3. Implémenter — SKILL.md d'abord ; ajoutez reference.md / scripts/ seulement s'ils économisent des tokens ou réduisent les erreurs.
4. Vérifier — description en troisième personne ; terminologie cohérente ; pas de contenu encyclopédique dupliqué que le modèle connaît déjà.

Anti-patterns

• Tutoriels verbeux (« qu'est-ce qu'un PDF ») à l'intérieur du skill.
• Beaucoup d'options équivalentes sans défaut.
• Noms vagues (helper, utils).
• Chaînes profondes de fichiers liés.
• Supposer qu'un MCP ou un outil est présent sans le dire ou proposer une fallback.
• Un skill surdimensionné qui mélange les flux de travail non liés au lieu de skills plus petits + un parent fin.

Stub d'exemple rapide

---
name: my-workflow
description: Does X using project convention Y. Use when the user asks for X or mentions Z.
---

# My workflow

1. …
2. …

## Output format

Use a fenced code block for the exact shape reviewers should see.

## More detail
See [reference.md](reference.md) if edge cases matter.