Rédiger des skills

Un skill est une procédure nommée que l'assistant peut invoquer au lieu de reconstituer les étapes à chaque fois. Les mémoires indiquent à l'assistant ce qui est vrai. Les règles lui indiquent ce qu'il ne doit pas faire. Les skills lui expliquent comment accomplir une tâche précise, étape par étape.

Cette page explique quand écrire un skill, ce qu'il contient, et comment les skills sont stockés et rattachés.

Quand écrire un skill

Pensez à un skill dès que vous remarquez le même schéma qui se répète. Le signal, c'est : « l'assistant repasse sans cesse par la même série d'étapes et en oublie parfois une ».

• Procédures opérationnelles. « Rejouer un webhook Stripe en local. » « Régénérer les fixtures de seed. » « Dérouler la checklist de pré-release. »
• Workflows personnalisés. « Ouvrir une PR en brouillon avec les bons labels et les bons reviewers. » « Incrémenter la version, taguer et pousser. »
• Conseils propres au domaine. « Créer un nouvel événement analytics de bout en bout : colonne, type, dashboard. »

Si le schéma tient en une ou deux lignes, une mémoire suffit. Optez pour un skill quand la procédure compte plus de trois étapes ou impose un ordre à respecter.

Sources

Un enregistrement de skill porte une valeur de source qui indique à Pathrule où se trouve son corps.

• manual. Le corps est rédigé directement dans Pathrule et stocké tel quel. C'est la valeur par défaut. Utilisez-la quand vous voulez que la procédure appartienne entièrement à l'espace de travail.
• template. Un skill de départ fourni par Pathrule, copié dans l'espace de travail et modifiable à partir de là.
• github_ref. Le skill pointe vers une URL GitHub externe. Utilisez cette source pour des skills publiés par des écosystèmes de skills en qui vous avez confiance.

Pour les skills github_ref, l'espace de travail conserve un instantané du corps récupéré depuis cette source, et le skill est en lecture seule dans l'espace de travail : VS Code vous invite à modifier la source à la place.

Structure d'un SKILL.md

Un skill est un petit fichier Markdown composé d'un frontmatter suivi du corps de la procédure.

---
name: replay-stripe-webhook
description: Replay a Stripe webhook against the local server with the right signing secret and the right idempotency key handling.
---

# Replay a Stripe webhook

Use this when a payment event from production needs to be reproduced locally.

## When to invoke

- A customer reports a missing receipt and you have the event id.
- You are debugging a webhook handler change.

## Procedure

1. Find the event in Stripe Dashboard. Copy its id.
2. Run `stripe events resend evt_xxx --webhook-endpoint we_local`.
3. Watch the local handler. It must accept and process the event without double charging.
4. If the handler returns 5xx, the customer support page is the next stop, not a retry.

## What NOT to do

- Do not replay against production webhooks.
- Do not skip the idempotency key check.

Le frontmatter doit contenir name et description. Tout ce qui suit constitue le corps que l'assistant applique. Ce corps peut être aussi court ou aussi long que nécessaire.

Rattachement

Un skill est rattaché à un seul chemin de l'espace de travail, comme une règle. Placez-le au chemin où la procédure est la plus pertinente. Le skill de rejeu de webhook va sur services/billing/webhooks. Le skill de release va à la racine de l'espace de travail. Un nouveau skill dont le nom correspond à un skill existant dans l'espace de travail est refusé : mettez donc à jour le skill existant plutôt que d'en ajouter une seconde copie.

L'assistant découvre les skills via le contexte que Pathrule fournit pour un chemin (de la même manière qu'il découvre les mémoires et les règles), grâce à pathrule_get_context, et en lit un en entier avec pathrule_read_skill. Lors de la synchronisation, Pathrule écrit aussi les skills dans les dossiers de skills des clients qui les lisent, par exemple .claude/skills pour Claude Code et .agents/skills pour Codex.

Invoquer un skill à la demande avec ::skill-name

En général, l'assistant choisit seul le bon skill. Si vous voulez imposer un skill précis, tapez :: suivi du nom du skill n'importe où dans votre prompt, par exemple ::release-check ou ::replay-stripe-webhook. Pour ce tour, l'assistant traite le skill nommé comme un workflow obligatoire à suivre, sans que vous ayez à rédiger de longues instructions. Dans Claude Code et Codex, le hook de prompt repère le marqueur avant que l'agent n'agisse ; dans les autres clients, l'assistant reçoit la même instruction lorsqu'il demande du contexte via MCP.

Le mécanisme est conçu pour échouer sans risque :

• Si le nom correspond à plusieurs skills, aucun skill n'est invoqué, plutôt que de tenter une supposition.
• Si le nom ne correspond à aucun skill, l'assistant reçoit la consigne de s'arrêter et de clarifier la situation avec vous avant de modifier quoi que ce soit. Il peut suggérer des candidats publiés, et attend votre approbation avant d'en ajouter un à l'espace de travail.
• Il ignore les usages de :: qui relèvent du code, comme button::before ou std::vector, pour que les prompts ordinaires ne soient pas mal interprétés.

::skill-name est donc un moyen rapide, indépendant du chemin, d'intégrer une procédure d'équipe connue au tour en cours.

Processus de création

Deux processus mènent au même résultat.

• Création manuelle. Dans VS Code, utilisez New Skill… au bon chemin et rédigez le corps du SKILL.md. Depuis le terminal, lancez pathrule skill add --path /services/billing/webhooks --name replay-stripe-webhook --description "Replay a Stripe webhook locally" ; sans --body, le CLI ouvre votre éditeur.
• Création par l'assistant. Dans Claude Code (ou tout client MCP), l'utilisateur demande à l'assistant d'« en faire un skill ». L'assistant suit un petit schéma de création de skill : cerner l'intention, interroger l'utilisateur, rédiger le SKILL.md, puis appeler pathrule_write_skill avec le corps complet.

Dans les scénarios où l'on veut s'engager a minima, l'assistant rédige le skill dans la conversation et attend votre approbation avant d'appeler pathrule_write_skill. L'enregistrement persisté est donc le brouillon relu, et non une écriture silencieuse en arrière-plan.

Versionnement et modifications concurrentes

Les skills portent un token de version, comme les mémoires et les règles. Lorsque deux membres de l'équipe modifient le même skill, un conflit est signalé proprement au lieu que l'un écrase le travail de l'autre, avec dans VS Code les mêmes options de résolution que pour une mémoire.

Anti-patterns

• Des skills qui sont en réalité des mémoires. Si le corps dit « voici ce qui est vrai sur notre façon de travailler », faites-en une mémoire.
• Des skills qui sont en réalité des règles. Si le corps dit « ne jamais faire X », faites-en une règle.
• Un skill qui en fait trop. Scindez-le en deux skills nommés si la procédure a deux points d'entrée distincts.
• Importer des skills externes auxquels vous ne faites pas confiance. Un skill github_ref est du code qui s'exécute dans les instructions de votre assistant. Traitez-le comme une dépendance.

Création en local et dans le Cloud

Les exemples add en terminal de cette page concernent un espace de travail Cloud. En mode local, créez et modifiez les entrées dans Local Console, dans VS Code ou via le MCP local ; les commandes de connaissances du CLI permettent de les lister, de les lire et de les rechercher.

Pour aller plus loin

• Rédiger des mémoires pour les faits et les décisions.
• Rédiger des règles pour les contraintes.
• Référence des outils MCP pour les outils qu'utilise l'assistant pour écrire des skills.