/skill-doctor : repérer les skills qui coûtent du contexte

Vous lancez Claude Code, vous n’avez encore rien demandé, et une part du contexte est déjà partie. Sur l’installation mesurée ici, 117 skills personnels sont chargés, 108 n’ont jamais été invoqués, et leur listing repart à chaque tour de conversation.

Ce que montre exactement /skill-doctor

La commande est arrivée avec Claude Code 2.1.261, publiée le 4 septembre 2026. La note de version l’annonce en une ligne : elle montre quels skills chargés restent inutilisés et ce qu’ils coûtent en contexte, pour que vous puissiez les élaguer.

La documentation précise le périmètre. Le rapport couvre les skills de votre session, à l’exception des skills groupés avec Claude Code et des skills d’entreprise. Il signale ceux qui n’ont jamais été invoqués, indique où les désactiver, et liste en prime les plugins que vous n’avez pas utilisés récemment. En session interactive, il s’ouvre dans l’onglet Stats du gestionnaire /plugin, en mode non interactif, avec -p, Claude Code l’imprime en texte.

Deux conditions à connaître avant d’essayer. Il faut Claude Code 2.1.252 ou plus récent. Et depuis Remote Control, sur téléphone ou navigateur, la commande refuse de répondre : elle renvoie Skill usage reports are not available on this connection. Lancez-la dans le terminal de la machine qui héberge la session.

Pourquoi un skill jamais invoqué coûte-t-il du contexte ?

Parce qu’un skill se charge en trois temps. Le standard ouvert Agent Skills appelle cela la divulgation progressive : au démarrage, l’agent ne lit que le nom et la description de chaque skill, quand une tâche correspond à cette description, il lit le corps du SKILL.md, il n’ouvre les fichiers annexes que s’il en a besoin. Le mécanisme est détaillé dans notre guide du format SKILL.md.

Le premier niveau, lui, est payé à chaque tour de conversation. La documentation de Claude Code est explicite : chaque skill du listing ajoute au contexte à chaque tour, que Claude s’en serve ou non. Et ce listing dispose d’un budget en caractères qui vaut 1 % de la fenêtre de contexte du modèle. Au-delà, Claude Code raccourcit les descriptions pour tenir dans le budget, au risque de supprimer justement les mots-clés qui déclenchent le bon skill.

Trop de skills coûte donc des tokens, et dégrade au passage le déclenchement de ceux que vous vouliez vraiment.

Le rapport, sur 117 skills

Sur une installation qui charge 117 skills personnels, la commande sort une ligne par skill et une phrase de conclusion. Le mode non interactif l’imprime en texte brut, ce qui permet de la garder :

claude -p '/skill-doctor'

Skills loaded this session

  skill                      source        context  7d tokens   uses  last used
  ab-test-setup              userSettings     ~270          -     0×  never
  cold-email                 userSettings     ~230          -     0×  never
  …
  seo-onpage                 userSettings     < 20          -     0×  never
  …
  seo-search-console         userSettings     ~190       1.2m     1×  6 days
  seo-keyword-research       userSettings     ~160      15.2m     1×  3 days
  video                      userSettings     ~210     548.4k     4×  3 days
  wp-article-thumbnails      userSettings     ~190      28.5m     8×  today

  context = this skill's one-line listing in the system prompt, included every turn
  (dash = not in the current listing, costs nothing; full SKILL.md loads only when it runs)
  7d tokens = tokens attributed to the skill over the last 7 days of sessions on this machine

108 skills loaded but never invoked. Each one adds to the system prompt every turn.
Disable in /skills, or remove from .claude/skills.

Quatre colonnes portent la décision. context donne le poids de la ligne de listing, celle qui repart à chaque tour : de moins de 20 à 360 tokens par skill ici, environ 8 800 en tout. 7d tokens compte ce que le skill a réellement consommé en sept jours, et affiche un tiret quand il n’a rien consommé. uses et last used disent le reste : sur 117 skills chargés, 108 n’ont jamais été invoqués, et cinq seulement ont consommé quelque chose dans la semaine.

Mesurer sans la commande

Sur une version antérieure à 2.1.252, ou simplement pour recouper l’ordre de grandeur, le niveau 1 se mesure directement dans les fichiers, puisqu’il n’est fait que du frontmatter YAML.

# Poids du niveau 1 : nom + description de chaque skill personnel
awk 'FNR==1{f=0;p=0}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{printf "%d skills, %d caracteres, ~%d tokens\n", ARGC-1, c, c/4}' \
  ~/.claude/skills/*/SKILL.md
# 117 skills, 45715 caracteres, ~11428 tokens

L’estimation « un token pour quatre caractères » annonce 11 428 tokens là où le rapport en compte environ 8 800 : elle majore, ce qui suffit largement pour décider. Le même calcul sur ~/.codex/skills donne 7 skills et environ 590 tokens : sur ce point, les deux agents ne jouent pas dans la même cour, comme le montre le comparatif Codex contre Claude Code.

La deuxième commande sort le classement. Elle suffit à trancher.

awk 'FNR==1{if(NR>1) print c, d; c=0; f=0; p=0; n=split(FILENAME,t,"/"); d=t[n-1]}
     /^---[[:space:]]*$/{f++; next}
     f!=1{next}
     /^[A-Za-z_-]+:/{p=($1=="name:"||$1=="description:"||$1=="when_to_use:")}
     p{c+=length($0)}
     END{print c, d}' ~/.claude/skills/*/SKILL.md | sort -rn | head -5
# 1101 elevenlabs-game-music
# 1078 elevenlabs-game-sfx
# 864 directory-submissions
# 855 customer-research
# 831 ab-test-setup

Ces 117 fichiers SKILL.md totalisent 778 142 caractères, soit environ 194 500 tokens, et le listing n’en représente que 6 %. La divulgation progressive fait donc son travail, ce qui pèse au quotidien reste le nombre de skills. Reste que 45 715 caractères sont dans l’ordre de grandeur du budget du listing : impossible de savoir sans /context si mes descriptions sont déjà rognées.

Couper ce qui ne sert pas

Ouvrez /skills, surlignez un skill, appuyez sur Espace pour faire défiler les états, puis Échap pour enregistrer. Le menu écrit lui-même le réglage skillOverrides dans .claude/settings.local.json. Quatre états existent.

name-only est le bon compromis pour un skill que vous appelez vous-même de temps en temps : le nom reste dans le listing, la description ne pèse plus. off convient à ceux que vous aviez installés « pour voir ».

Attention au cas des plugins : les skills apportés par un plugin ne sont pas concernés par skillOverrides. Il faut désactiver le plugin depuis /plugin, puis lancer /reload-plugins ou redémarrer la session pour que ses skills soient déchargés.

Vérifier que la coupe a servi

La ligne Skills de /context donne la taille du listing après application du budget : c’est exactement ce que reçoit le modèle. Relevez-la, coupez, redémarrez la session, relevez-la de nouveau. Si elle ne bouge pas alors que vous avez désactivé dix skills, c’est probablement que vous étiez déjà au plafond et que Claude Code tronquait vos descriptions, la coupe aura quand même gagné en précision de déclenchement.

Pour la facture, /cost et /usage restent les repères, mais attendez-vous à un gain modeste : le vrai bénéfice se lit en contexte, pas en euros. Si vous cherchez des économies d’un autre ordre de grandeur, c’est le routage des lectures de fichiers qu’il faut regarder, comme dans le retour d’expérience de Spotify sur les hooks.

Deux réglages permettent d’élargir le budget plutôt que de couper : skillListingBudgetFraction (par exemple 0.02 pour 2 %) et la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET, qui fixe un nombre de caractères. Élargir déplace le problème : le contexte gagné sur les skills est perdu ailleurs.

Ce qu’il faut retenir

• Un skill jamais invoqué coûte quand même son nom et sa description à chaque tour : c’est le niveau 1 de la divulgation progressive.
• /skill-doctor demande Claude Code 2.1.252 ou plus récent, et s’affiche dans l’onglet Stats du gestionnaire /plugin.
• Le rapport compte ici 117 skills chargés, 108 jamais invoqués, environ 8 800 tokens de listing. Deux lignes d’awk sur ~/.claude/skills/*/SKILL.md donnent le même ordre de grandeur sans la commande.
• On coupe avec /skills et la touche Espace, les skills de plugin se coupent depuis /plugin, puis /reload-plugins.
• On vérifie sur la ligne Skills de /context, qui reflète le budget réellement appliqué.