Skills Claude Code avancées : scripts, ressources, architecture

Un SKILL.md simple suffit pour une procédure de quelques étapes. Mais dès qu'une skill doit calculer, parser ou agréger quelque chose, écrire la logique en prose dans le SKILL.md est une mauvaise idée : c'est verbeux, peu fiable, et ça gonfle le contexte. La bonne approche consiste à déporter le travail dans un script et à charger les ressources à la demande. Ce guide montre comment, avec un lab vérifié sur lab-claude.

Ce que vous allez apprendre

• Déporter la logique d'une skill dans un script que l'agent exécute
• Structurer une skill avec scripts/, references/ et assets/
• Charger des ressources à la demande sans alourdir le contexte
• Écrire une description qui déclenche et restreindre allowed-tools sans risque
• Faire tourner une skill dans un subagent isolé avec context: fork
• Connaître la conséquence de ce choix sur /rewind

Prérequis

• Les bases des skills maîtrisées (frontmatter, invocation)
• Le concept de progressive disclosure compris
• lab-claude opérationnel et Python disponible. Le champ context: fork traité plus bas demande une version récente : vérifiez avec claude --version

Pourquoi sortir la logique dans un script

Quand une skill embarque un script, l'agent exécute ce script et n'en récupère que la sortie. Le code lui-même n'entre jamais dans le contexte. C'est le troisième niveau de la progressive disclosure : les fichiers de scripts/ sont lancés sans que leur contenu coûte un seul token.

Deux bénéfices concrets. D'abord la fiabilité : un script Python qui parse du JSON ou compte des occurrences donne un résultat déterministe, là où des instructions en langage naturel laissent l'agent improviser. Ensuite l'économie de contexte : un script de 200 lignes ne pèse rien tant qu'il n'est pas exécuté, et même exécuté, seule sa sortie compte.

La règle qui en découle : tout ce qui est calculable doit être un script, le SKILL.md se contentant d'orchestrer (lancer le script, interpréter sa sortie, appliquer un format).

Anatomie d'une skill avancée

Une skill avancée est un dossier structuré. Sur lab-claude, voici une skill inventaire-todo qui recense la dette technique du projet :

• Répertoire.claude/

  • Répertoireskills/

    • Répertoireinventaire-todo/

      • SKILL.md
      • Répertoirescripts/

        • scan.py
      • Répertoirereferences/

        • criteres.md

Chaque dossier a un rôle précis :

• scripts/ : le code exécutable. Lancé par l'agent, jamais chargé en contexte.
• references/ : la documentation lue seulement si une étape la réclame (un format, des règles).
• assets/ (non utilisé ici) : des gabarits ou fichiers produits en sortie (modèles de document, par exemple).

Le SKILL.md reste mince et se contente d'enchaîner : lancer le script, puis mettre en forme selon references/.

Lab : une skill qui exécute un vrai script

Le script scan.py parcourt les fichiers Python et inventorie les marqueurs TODO, FIXME et XXX. Il renvoie du JSON sur la sortie standard :

# .claude/skills/inventaire-todo/scripts/scan.py (extrait)
PATTERN = re.compile(r"\b(TODO|FIXME|XXX)\b[:\s]*(.*)")

def scan(root: Path) -> dict:
    findings = []
    for path in root.rglob("*.py"):
        if any(part in SKIP_DIRS for part in path.parts):
            continue
        for n, line in enumerate(path.read_text().splitlines(), 1):
            if m := PATTERN.search(line):
                findings.append({"file": str(path.relative_to(root)),
                                 "line": n, "marker": m.group(1),
                                 "text": m.group(2).strip()[:120]})
    return {"total": len(findings), "findings": findings}

Le SKILL.md orchestre, sans refaire le travail du script :

---
name: inventaire-todo
description: Inventorie et priorise les marqueurs TODO, FIXME et XXX du projet Python. À utiliser quand l'utilisateur veut faire le point sur la dette technique ou les tâches en suspens dans le code.
allowed-tools: Bash(python3 .claude/skills/inventaire-todo/scripts/scan.py *)
---

1. Lance `python3 .claude/skills/inventaire-todo/scripts/scan.py .`
2. Mets en forme le JSON en suivant `references/criteres.md`
3. Termine par une recommandation : quel marqueur traiter en premier

Lancé seul, le script produit un résultat déterministe :

{
  "total": 3,
  "by_marker": { "TODO": 1, "FIXME": 1, "XXX": 1 },
  "findings": [
    { "file": "app/__init__.py", "line": 4, "marker": "FIXME",
      "text": "gerer le cas panier vide avant total" }
  ]
}

Maintenant le test qui compte : déclencher la skill sans la nommer, par une simple demande en langage naturel.

> fais le point sur la dette technique du code, les todo et fixme

# Inventaire dette technique

## FIXME (priorité 1 - bug connu)
- app/__init__.py:4 - gerer le cas panier vide avant total

## XXX (priorité 2 - code fragile)
- app/__init__.py:5 - arrondi monetaire a revoir (flottants)

## TODO (priorité 3 - amélioration)
- app/__init__.py:3 - paginer la liste des produits

## Recommandation
Attaquer le FIXME en premier : c'est un bug fonctionnel.

Trois mécanismes se sont enchaînés : la skill a été activée par sa description, elle a exécuté le script (dont le code n'est jamais entré dans le contexte), puis elle a lu references/criteres.md pour prioriser FIXME avant XXX avant TODO. Le travail de comptage est fait par Python ; l'agent ne fait que l'interpréter.

Charger des ressources à la demande

Le fichier references/criteres.md n'est lu que lorsque la skill s'exécute. Il porte les règles de priorisation :

## Ordre de priorité
1. FIXME : un bug connu. À traiter en premier.
2. XXX : code fragile ou hack assumé.
3. TODO : amélioration sans urgence.

C'est le bon endroit pour tout ce qui est détaillé mais pas toujours nécessaire : un format de sortie long, une table de correspondance, une convention d'équipe. En le sortant du SKILL.md, vous gardez ce dernier court et vous ne payez le coût de la référence que quand elle sert.

SKILL.md mince, références épaisses

Visez un SKILL.md qui tient sur un écran. Tout le détail volumineux part dans references/. Un SKILL.md de plusieurs milliers de tokens est rechargé à chaque activation, même pour une tâche adjacente : c'est du contexte gaspillé.

Écrire une description qui déclenche

Le déclenchement repose entièrement sur la description, sans aucun routage par mots-clés. Une description efficace décrit la tâche et le moment où l'utiliser, avec des termes concrets.

Description	Problème
Aide pour le code	Trop vague, ne se déclenche jamais
Analyse les endpoints Flask pour injections SQL PostgreSQL	Trop étroite, rate les cas généraux
Inventorie les marqueurs TODO, FIXME, XXX. À utiliser pour faire le point sur la dette technique	Tâche + moment d'usage concrets

Glissez pour voir

Testez toujours avec des phrases réelles (« fais le point sur la dette technique »), pas avec « déclenche ma skill ». Si elle ne part pas, resserrez la description vers le vocabulaire que vous emploieriez vraiment.

Sécurité : restreindre allowed-tools à la commande exacte

Le champ allowed-tools pré-autorise des commandes pendant l'exécution de la skill. La tentation est d'écrire Bash(*) pour ne plus être interrompu. Ne le faites pas : une skill avec Bash(*) peut lancer n'importe quoi sans confirmation, ce qui est exactement le vecteur d'abus des skills tierces.

Restreignez au chemin exact du script :

allowed-tools: Bash(python3 .claude/skills/inventaire-todo/scripts/scan.py *)

Cette ligne autorise le script de la skill, et rien d'autre. C'est le même principe de moindre privilège qu'ailleurs en sécurité, appliqué aux skills. Un deny du settings.json reste prioritaire sur allowed-tools : ne pré-autorisez jamais dans une skill ce qui est refusé au niveau du projet.

Faire tourner une skill dans un subagent isolé

Une skill s'exécute par défaut dans votre conversation. Elle voit l'historique, elle consomme votre fenêtre de contexte, et tout ce qu'elle produit s'y accumule. Pour une procédure qui lit beaucoup, c'est exactement le problème que résolvent les subagents.

Le champ context: fork répond à ce besoin : la skill part dans un subagent isolé, le contenu de la skill devient son prompt, et elle n'a pas accès à votre historique de conversation. Seul son résultat revient.

---
name: audit-dependances
description: Recense les dépendances du projet et signale celles qui sont abandonnées
context: fork
agent: Explore
allowed-tools: Read, Glob, Grep
---

Trois champs se combinent ici, et chacun décide d'autre chose :

Champ	Rôle	Défaut
context: fork	exécute la skill dans un subagent isolé	exécution en ligne, dans votre conversation
agent	quel type d'agent pilote le fork : Explore, Plan, ou un agent de .claude/agents/	general-purpose
background	attendre le résultat, ou continuer à travailler pendant l'exécution	true, donc arrière-plan

Glissez pour voir

Le défaut mérite qu'on s'y arrête : une skill forkée tourne en arrière-plan. Vous gardez la main, et son résultat arrive dans la conversation quand elle a fini. Poser background: false fait au contraire attendre le résultat dans le tour qui a invoqué la skill.

Une skill forkée en arrière-plan échappe à `/rewind`

C'est la conséquence à connaître avant d'activer context: fork. Une skill forkée qui tourne en arrière-plan applique ses modifications en dehors des checkpoints de votre session : le rembobinage ne les annule pas. La documentation renvoie explicitement à git pour revenir en arrière.

Une skill forkée exécutée au premier plan, avec background: false, modifie l'arbre de travail pendant votre propre tour : celle-là, /rewind la rattrape.

La règle qui en découle est simple. Une skill forkée qui écrit doit soit tourner au premier plan, soit être précédée d'un commit. Une skill forkée qui se contente de lire, comme l'exemple d'audit ci-dessus, ne pose aucun problème : c'est d'ailleurs son meilleur cas d'usage.

Quand forker, et quand ne pas forker

Forker coûte l'accès au contexte de la conversation. Ce n'est pas un détail : une skill forkée ne sait pas ce dont vous venez de parler, ce que vous avez décidé, ni quel fichier vous regardiez. Elle ne dispose que de son propre contenu.

Situation	Forker ?
La skill lit beaucoup et vous n'en voulez que la conclusion	oui, c'est le cas nominal
La skill doit s'appuyer sur ce qui vient d'être dit	non, elle perdrait l'information
La skill écrit dans le dépôt	au premier plan, ou après un commit
La skill est longue et vous voulez continuer à travailler	oui, en arrière-plan, en acceptant l'angle mort du rembobinage

Glissez pour voir

Les autres champs déclarables

Le frontmatter d'une skill accepte bien plus que name et description. Les champs ci-dessous reviennent le plus souvent, et les connaître évite d'écrire dans le prompt ce qu'une déclaration ferait mieux.

Champ	Ce qu'il règle
when_to_use	précise le moment d'emploi, en complément de description
argument-hint, arguments	ce que la skill attend quand on l'invoque
allowed-tools, disallowed-tools	le périmètre d'outils pendant la skill
model, effort	la gamme et le niveau de raisonnement pour cette skill
hooks	des hooks propres à l'exécution de la skill
disable-model-invocation, user-invocable	qui peut la déclencher, vous ou Claude
paths, shell	le périmètre de fichiers et l'interpréteur employé

Glissez pour voir

Un usage sous-estimé : model et effort par skill. Une skill d'inventaire qui parcourt des fichiers n'a pas besoin de la même gamme qu'une skill de revue d'architecture. Déclarer model: haiku sur la première réduit la facture sans rien changer au résultat.

Dépannage

Symptôme	Cause probable	Correction
Le script n'est pas trouvé	Chemin relatif erroné	Référencer depuis la racine du projet, vérifier le chemin réel
La skill redemande une autorisation	allowed-tools ne couvre pas la commande exacte	Aligner le motif sur la commande lancée
references/ jamais utilisé	Le SKILL.md n'y renvoie pas	Ajouter une étape explicite « suis references/... »
Sortie du script ignorée	Skill traitée comme un guide, pas une tâche	Formuler en impératif (« Lance », « Mets en forme »)
Le script se compte lui-même	Dossier .claude/ non exclu du scan	Exclure les dossiers d'outillage dans le script

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• Tout ce qui est calculable doit être un script : déterministe, et son code n'entre jamais dans le contexte.
• Une skill avancée se structure en scripts/ (exécutable), references/ (à la demande), assets/ (gabarits).
• Le SKILL.md orchestre, il ne refait pas le travail du script.
• Gardez le SKILL.md mince et déportez le détail dans references/.
• La description est la seule règle de déclenchement : concrète, testée avec de vraies phrases.
• Restreignez allowed-tools à la commande exacte, jamais Bash(*).

Pour aller plus loin

• Skills de sécurité : auditer son code : Une skill à script mise au service d'un audit, avec un cadre pour classer les résultats.
• Brancher un serveur MCP : L'alternative quand la donnée vit hors du dépôt et qu'un script local ne suffit plus.
• Subagents : isoler le contexte : L'exécution d'une skill lourde dans un contexte séparé, sans polluer la session principale.

×

📖 Voir la documentation →