Écrire de bonnes règles et de bons skills pour Claude Code
Structure, en-têtes, choix entre règle, skill et agent, brièveté, avec trois exemples génériques (fonctions PowerShell, scripts SQL, pipelines).
Les règles et les skills sont le moyen le moins coûteux de faire respecter vos conventions par Claude Code, et le plus facile à rater. Après un an de réglages sur un dépôt de DBA, voici comment je les structure, comment je choisis entre règle, skill et agent, et trois courts exemples génériques.
Règle, skill ou agent ?
| Besoin | Outil | Pourquoi |
|---|---|---|
| Une convention valable chaque fois qu'on touche un type de fichier | Règle avec paths |
chargée automatiquement, au bon moment |
| Une convention valable dans toutes les sessions | CLAUDE.md |
toujours chargé, donc à garder minuscule |
| Une procédure à étapes ou un corpus de référence | Skill | chargé seulement si la tâche correspond |
| Un travail qui demande son propre contexte, ses outils ou une posture en lecture seule | Agent | isolé, rend un résumé |
| Quelque chose qui doit toujours arriver, de façon déterministe | Hook | du code, pas une consigne |
Test rapide : si vous diriez « chaque fois que tu modifies un fichier .sql... », écrivez une règle. Si vous diriez « quand je demande X, fais ces étapes », écrivez un skill. Si vous diriez « va vérifier ça pour moi », utilisez un agent.
Anatomie d'une règle
Une règle est un fichier Markdown dans .claude/rules/. L'en-tête liste les motifs glob qui la déclenchent.
---
paths:
- "**/*.ps1"
---
Le nommage aide beaucoup : <domaine>-<sujet>.md (powershell-function.md, sql-script.md, azure-pipeline.md). Un fichier par sujet, en anglais, en kebab-case. Quand quelqu'un demande où vit une convention, le nom du fichier répond.
Anatomie d'un skill
Un skill est un dossier contenant un SKILL.md. L'en-tête porte un name et une description. La description est la partie toujours en contexte et c'est elle qui décide si le skill est utilisé : écrivez-la comme un déclencheur, ce qu'il fait et les mots qu'un utilisateur emploierait.
---
name: run-triage
description: Diagnose a failed run of a scheduled job (red report mail, failed task, failed pipeline): where its status and logs are, how to group the errors, how to rerun safely. Use for "why did it fail", "rerun", "stuck".
---
# Run triage
1. Find the status store of the job (see reference/jobs.md).
2. Pull the logs of the last run, group errors by message.
3. Decide: recovers by itself, or needs a rerun, or needs a fix.
4. Never rerun a destructive job: propose the command, wait for approval.
Les longues références vont dans des sous-fichiers (reference/*.md) vers lesquels le corps du skill renvoie : ils ne sont lus qu'au besoin. Un skill qui ne doit jamais se déclencher seul (un workflow de changement de bout en bout, par exemple) peut être marqué manuel uniquement.
Les garder courts
- Une règle est une checklist, pas de la documentation. Dix puces valent mieux que deux pages.
- Énoncez la règle et sa raison en une ligne ; Claude généralise mieux à partir du « pourquoi ».
- Renvoyez, ne copiez jamais. Un agent dit « suis la règle X », il ne la colle pas.
- Mettez dans la règle les décisions déjà prises (« ne jamais activer l'option Y sur ces bases, testé, cela casse les écritures »), pour que l'assistant cesse de les proposer.
- Relisez-les comme du code : quand une règle dépasse un écran, découpez-la ou déplacez le détail dans la référence d'un skill.
Trois exemples génériques
Conventions des fonctions PowerShell
---
paths: ["**/*.ps1"]
---
# PowerShell functions
- Approved verb + PascalCase noun, `[CmdletBinding()]`, typed parameters.
- Return a hashtable: `@{ IsValid; Data; Reason }`. No exceptions across the public boundary.
- Log with the shared logging function, never `Write-Host`.
- `try/catch` with `-ErrorAction Stop`. Never set `$ErrorActionPreference` to SilentlyContinue.
- No credentials in code: Key Vault or managed identity.
Conventions des scripts SQL
---
paths: ["**/*.sql"]
---
# T-SQL scripts
- Header: purpose, parameters, example call.
- Templates use `{{Name}}` placeholders declared once at the top.
- `SET NOCOUNT ON`; `TRY...CATCH` that rethrows; explicit transaction for atomic DML.
- No `SELECT *`. Dynamic SQL only with `QUOTENAME`.
- DDL scripts are idempotent. Read-only queries on production are fine; DDL/DML is a change.
Conventions des pipelines
---
paths: ["pipelines/**"]
---
# Pipeline YAML
- An optional string parameter gets a sentinel default (`'auto'`), not `''`.
- A new scheduled pipeline is created disabled if another scheduler runs the same work.
- Pipelines that write to production keep a dry-run default; the write is an explicit parameter.
- Internal module versions default to `latest`; pinning belongs to the release process.
Retour d'expérience
- Précis plutôt que vague. « Formate bien le code » ne sert à rien ; « retourne
@{ IsValid; Data; Reason }» est vérifiable. - Chaque règle doit être vérifiable par un lint, un test ou une relecture. Si vous ne pouvez pas la contrôler, vous ne saurez pas si elle marche.
- Notez les échecs. Chaque fois que l'assistant répète une erreur, ajoutez une ligne à la bonne règle, puis vérifiez que cela cesse.
- Ne dupliquez pas entre couches. Deux copies divergeront en un mois.
- Testez une nouvelle règle en demandant une petite modification dans une session neuve et en regardant si elle est appliquée.