Compétences Claude et SKILL.md pour les développeurs : VS Code, JetBrains, Cursor

La plupart des équipes utilisent mal les Compétences Claude de deux manières. Elles transforment soit SKILL.md en une poubelle, soit elles ne passent jamais à autre chose que des prompts géants copiés-collés.

Les deux approches sont négligées. Si vous voulez que les Compétences fonctionnent dans un flux de développement réel, vous devez les traiter comme du code et de la logique opérationnelle, et non comme de la poésie de prompt.

Les Compétences Claude sont des répertoires ancrés par SKILL.md, avec des scripts, des références et des actifs optionnels. Elles fonctionnent grâce à la divulgation progressive. L’agent commence par charger uniquement des métadonnées compactes telles que le nom de la compétence et la description, puis lit les instructions complètes uniquement lorsque la tâche correspond. Cela permet à un agent de garder de nombreuses compétences disponibles sans alourdir chaque session dès le début.

Les propres directives d’Anthropic rendent la division du travail prévue assez claire. CLAUDE.md est destiné à un contexte de projet durable et toujours actif. Les Compétences sont destinées aux connaissances réutilisables, aux livres de jeux et aux workflows invoquables qui doivent être chargés à la demande. Claude Code a même intégré les anciennes commandes personnalisées dans le même mécanisme, donc les fichiers legacy .claude/commands/*.md fonctionnent toujours, mais les Compétences sont maintenant la meilleure forme à long terme — et le bloc de construction le plus réutilisable dans tout flux de développement alimenté par l’IA.

Quand utiliser les Compétences Claude : CLAUDE.md vs Compétences vs Hooks

Une Compétence Claude vaut la peine d’être créée lorsque vous continuez à coller la même liste de contrôle, le même livre de déploiement, la même grille de revue de code ou les mêmes pièges d’API interne dans le chat. Anthropic recommande explicitement de créer une compétence lorsque vous réutilisez constamment la même procédure, ou lorsqu’une section de CLAUDE.md s’est transformée en processus plutôt qu’en fait. C’est la réponse pratique à la question de la FAQ « Qu’est-ce qu’une Compétence Claude et quand faut-il en utiliser une ». Utilisez une Compétence pour une procédure répétitive, pas pour un goût général ou des règles de dépôt larges.

La véritable victoire est le contrôle des coûts de contexte et du comportement. Une bonne Compétence est chargée uniquement lorsqu’elle est pertinente, tandis qu’un CLAUDE.md gonflé est chargé à chaque session. Anthropic recommande de garder CLAUDE.md court et de déplacer les connaissances de domaine ou les procédures vers des Compétences précisément parce que le chargement à la demande permet à l’agent de rester concentré sur la tâche qui se présente à lui.

Ma règle d’opinion est simple. Si l’instruction doit s’appliquer à chaque session, elle doit figurer dans CLAUDE.md. Si l’instruction est une méthode, une liste de contrôle ou un workflow réutilisable qui n’importe que parfois, elle doit figurer dans une Compétence. Si l’action doit se produire automatiquement à chaque événement correspondant, elle appartient probablement à un hook, pas à une Compétence. La vue d’ensemble des fonctionnalités d’Anthropic cadre ces outils dans un modèle de superposition presque exactement celui-ci.

Une odeur pratique pour chacun : si vous vous trouvez à coller les mêmes instructions dans chaque chat, c’est une Compétence. Si une section de CLAUDE.md s’est transformée en processus étape par étape, extrayez-la dans une Compétence. Si vous voulez que quelque chose se déclenche silencieusement à chaque fois qu’un fichier est enregistré, écrivez un hook à la place.

Prise en charge des IDE pour les Compétences Claude : VS Code, JetBrains, Cursor et Codex

Claude Code fonctionne sur CLI, Desktop, VS Code, JetBrains, web et flux de contrôle à distance liés aux mobiles. Anthropic décrit la CLI comme la surface locale la plus complète, tandis que les intégrations IDE sacrifient certaines capacités exclusives à la CLI pour une revue native de l’éditeur, un contexte de fichier et une ergonomie de flux de travail plus serrée. La configuration, la mémoire du projet et les serveurs MCP sont partagés entre les surfaces locales, donc votre configuration .claude vous suit plutôt que d’être piégée dans un seul éditeur.

Pour VS Code, Anthropic affirme que l’extension est l’interface recommandée à l’intérieur de l’éditeur. Elle fournit une revue de plan, des diffs en ligne, une prise en charge de la mention de fichiers et un accès intégré à la CLI. Le même flux d’installation expose également un chemin direct pour Cursor. Pour JetBrains, la liste actuellement prise en charge comprend IntelliJ IDEA, PyCharm, Android Studio, WebStorm, PhpStorm et GoLand, avec la visualisation de diffs, le partage de sélection, les raccourcis de référence de fichier et le partage de diagnostics intégrés au plugin.

La prise en charge JetBrains est meilleure que ce que de nombreux développeurs réalisent. Si vous exécutez claude depuis le terminal intégré de l’IDE, les fonctionnalités d’intégration sont actives automatiquement. Si vous démarrez depuis un terminal externe, Anthropic documente la commande /ide pour reconnecter Claude Code à la session JetBrains, et recommande explicitement de démarrer depuis la racine du même projet afin que Claude voie les mêmes fichiers que votre IDE. Si vous utilisez des modes de modification automatique dans JetBrains, Anthropic avertit également que les fichiers de configuration de l’IDE peuvent devenir partie de la surface modifiable, donc les approbations manuelles sont le défaut plus sûr dans cet environnement.

Maintenant, le point majeur. Les Compétences Claude ne sont pas seulement une chose de Claude Code. Agent Skills est un standard ouvert. Le démarrage rapide officiel des Compétences d’Agent dit que la même compétence peut fonctionner dans VS Code avec GitHub Copilot, Claude Code et OpenAI Codex, et les propres documents Codex d’OpenAI disent que les Compétences sont disponibles dans la CLI Codex, l’extension IDE et l’application. Le guide d’implémentation des Compétences d’Agent ajoute un détail de portabilité important : .agents/skills est apparu comme la convention inter-client, tandis que certains clients scannent également .claude/skills pour une compatibilité pragmatique.

Voici donc la règle de compatibilité pratique que je recommande. Si vous construisez pour Claude Code en premier et seulement, écrivez dans .claude/skills. Si vous voulez vraiment une portabilité inter-client, ciblez la forme ouverte des Compétences d’Agent et utilisez .agents/skills comme chemin canonique. Ne prétendez pas que ces deux objectifs sont identiques. Ils sont liés, pas identiques.

Référence de compatibilité rapide :

Structure de fichier SKILL.md, disposition de dossier et emplacements de stockage

Une vraie Compétence est un dossier, pas un fichier markdown aléatoire assis à la racine du dépôt. La spécification principale exige un répertoire avec un fichier SKILL.md et permet des répertoires optionnels scripts/, references/ et assets/. SKILL.md doit contenir un frontmatter YAML suivi d’instructions markdown. Dans la spécification, name et description sont requis, name est limité à 64 caractères utilisant des lettres minuscules, des chiffres et des tirets, compatibility est uniquement pour les exigences réelles de l’environnement, et allowed-tools est explicitement expérimental à travers les implémentations.

Claude Code est un peu plus souple que la spécification portable car il peut dériver un nom du répertoire et revenir au premier paragraphe lorsque description est manquant. Vous ne devriez pas vous fier à cela si vous vous souciez de la portabilité ou de la prédictibilité. Claude.ai exige que le nom du dossier corresponde au champ name, et son chemin de téléchargement de compétence personnalisé limite les descriptions à 200 caractères même si la spécification plus large en permet beaucoup plus. Le choix portable est de définir un name explicite, de garder le dossier identique et d’écrire une description précise qui tient dans des limites serrées. Cela répond au sujet de la FAQ « Que doit contenir un fichier SKILL.md » sans esquiver.

Commencez par une structure aussi ennuyeuse :

repo/
  .claude/
    skills/
      review-pr/
        SKILL.md
        scripts/
          review.sh
        references/
          checklist.md
        assets/
          comment-template.md

Si la portabilité à travers les clients compatibles Compétences est plus importante que la commodité de Claude Code, gardez la même forme interne et échangez .claude/skills/ contre .agents/skills/. La structure de dossier est la même idée dans les deux cas.

Pour Claude Code, les emplacements de stockage sont simples. Les compétences de projet vivent à .claude/skills/<skill-name>/SKILL.md. Les compétences personnelles vivent à ~/.claude/skills/<skill-name>/SKILL.md. Les compétences distribuées par plugin vivent sous <plugin>/skills/<skill-name>/SKILL.md. Anthropic documente la priorité à travers les portées intégrées comme entreprise sur personnel sur projet, tandis que les compétences de plugin évitent les collisions en utilisant une forme nommée comme plugin-name:skill-name. Sous Windows, ~/.claude se résout en %USERPROFILE%\.claude, et CLAUDE_CONFIG_DIR peut déplacer tout le répertoire de base.

Le choix entre la portée projet et personnelle est simple. Utilisez .claude/skills/ à l’intérieur du dépôt lorsque la Compétence est étroitement couplée à cette base de code — par exemple, un livre de déploiement qui connaît vos noms de cluster spécifiques ou une grille de revue adaptée aux conventions de votre équipe. Utilisez ~/.claude/skills/ pour les Compétences qui vous accompagnent à travers les projets : listes de contrôle personnelles, générateurs de changelog génériques, workflows de débogage préférés. Tout ce que vous mettriez dans un dépôt de dotfiles appartient à la portée personnelle.

Quelques arêtes vives valent la peine d’être mémorisées. SKILL.md doit être nommé exactement avec cette casse. Le guide PDF d’Anthropic recommande des noms de dossiers kebab-case et dit explicitement de ne pas placer un README.md à l’intérieur du dossier de compétence, car la documentation opérationnelle doit vivre dans SKILL.md ou references/. Ce même guide souligne également que le nommage de SKILL.md est sensible à la casse. Ce sont des contraintes ennuyeuses, mais les contraintes ennuyeuses sont ce qui rend les outils fiables.

Claude Code fait également la bonne chose pour les monorepos. Il découvre automatiquement les répertoires imbriqués .claude/skills/ lorsque vous travaillez à l’intérieur de sous-répertoires, ce qui est idéal pour les compétences au niveau des paquets ou des services. Il surveille également les répertoires de compétences existants pour les changements en direct pendant la session actuelle. Le piège de redémarrage unique est la création d’un répertoire de compétences de niveau supérieur qui n’existait pas au démarrage de la session. Anthropic documente cela comme le cas où vous avez besoin de redémarrer afin que le nouveau répertoire puisse être surveillé.

Meilleures pratiques pour les Compétences Claude : Descriptions, scripts et portée

Le moyen le plus rapide de créer une Compétence inutile est de demander à un LLM d’en inventer une à partir de connaissances de formation génériques. Le guide des meilleures pratiques d’Anthropic avertit contre exactement cela. Les bits précieux sont les corrections spécifiques au domaine, les cas limites, les choix d’outils et les conventions que le modèle n’inventerait pas de manière fiable par lui-même. Le bon flux de travail est de résoudre la tâche une fois avec l’agent, de la corriger jusqu’à ce qu’elle fonctionne, puis d’extraire la méthode dans une Compétence.

Définissez la portée de la Compétence comme une bonne fonction, pas comme un wiki. Anthropic dit que les Compétences doivent encapsuler une unité de travail cohérente. Trop étroit, et vous forcez plusieurs compétences à s’empiler pour une tâche. Trop large, et l’agent ne peut pas les activer précisément. Le guide des meilleures pratiques est franc : les compétences trop complètes peuvent nuire plus qu’aider car le modèle poursuit des instructions non pertinentes et perd le signal.

La qualité de la description n’est pas une préoccupation cosmétique. C’est la couche de routage. Anthropic et les documents Agent Skills disent que le champ description est le mécanisme principal que le modèle utilise pour décider de charger une Compétence ou non. Les bonnes descriptions disent ce que la Compétence fait, quand l’utiliser et les phrases de déclenchement ou les types de fichiers qu’un utilisateur mentionnerait réellement. Les mauvaises descriptions sont vagues, trop techniques ou assez larges pour correspondre à des bêtises. C’est la vraie réponse à la question de la FAQ « Pourquoi une Compétence Claude ne se déclenche pas ». Habituellement, c’est le routeur qui est mauvais, pas le modèle.

Le contraste est clair côte à côte :

Mauvaises descriptions — trop vagues pour router de manière fiable :

• Aide à la revue de code — correspond à tout, ne désambiguise rien
• Utile pour les tâches de développement — plus large qu’une requête de recherche
• Assiste à l'écriture — pas un routeur, juste une étiquette de catégorie

Bonnes descriptions — langage de déclenchement spécifique :

• Revue des demandes de fusion pour les problèmes de sécurité, les risques de migration et les tests manquants. Utiliser lors de la revue d'une PR, d'un git diff ou d'un changement critique de release.
• Générer un changelog à partir de la sortie de git log. Utiliser lors de la préparation d'une release, de l'écriture de notes de release ou de la résumation des commits depuis le dernier tag.
• Créer un gestionnaire HTTP Go avec validation de requête et middleware d'erreur. Utiliser lors de l'ajout d'une nouvelle extrémité ou d'une route à un service Go.

Le modèle est le même à chaque fois : énoncez ce que la Compétence fait, nommez les phrases exactes de l’utilisateur qui devraient l’activer et, facultativement, nommez les types de fichiers ou les outils pertinents. Si votre description correspondrait à une requête Google générique, elle n’est pas assez spécifique.

Si un flux de travail a des effets secondaires, rendez-le manuel. Claude Code expose cela directement. disable-model-invocation: true rend une Compétence uniquement invoquée par l’utilisateur, ce qu’Anthropic recommande pour des actions comme les déploiements, les commits ou les messages sortants. user-invocable: false va dans l’autre sens et cache la Compétence du menu slash tout en permettant à Claude de l’utiliser comme connaissance de fond. Cela répond au sujet de la FAQ « Quand une compétence devrait être manuelle plutôt qu’automatique » en une phrase : manuel pour le risque, automatique pour un guidage répétitif sûr.

Gardez SKILL.md assez petit pour rester intelligible. Anthropic recommande de le garder sous 500 lignes et autour de 5 000 jetons, puis de déplacer le matériel détaillé dans references/ ou des fichiers similaires avec des instructions de chargement explicites. « Lisez references/api-errors.md si l’API renvoie un non-200 » est un bon modèle. « Voir references/ » est paresseux. Claude Code injecte également la Compétence rendue dans la conversation comme un message et ne relit pas le fichier sur les tours suivants. Après la compaction de contexte, seul le contenu récent de la Compétence est transporté à l’intérieur des budgets de jetons. Les Compétences énormes ne sont donc pas seulement moches. Elles sont fragiles sur les longues sessions.

Un bon SKILL.md peut rester très simple :

---
name: review-pr
description: Revue des demandes de fusion pour les problèmes de sécurité, les risques de migration et les tests manquants. Utiliser lors de la revue d'une PR, d'un git diff ou d'un changement critique de release.
compatibility: Conçu pour Claude Code. Nécessite git et gh.
disable-model-invocation: true
allowed-tools: Bash(git diff *) Bash(gh pr diff *) Read Grep Glob
---
# Revue PR

Lisez references/checklist.md avant d'exécuter toute commande.

1. Collectez le diff et les fichiers modifiés.
2. Signalez les problèmes de correction, de sécurité et de couverture de test.
3. Retournez les résultats regroupés par sévérité avec des références de fichiers.
4. Suggérez d'abord la correction la plus petite et la plus sûre.

Utilisez des scripts lorsque la détermination prime sur l’éloquence. Le guide des scripts de Compétences est excellent ici. Il dit que les scripts tournés vers l’agent doivent éviter les invites interactives, documenter l’usage via --help, émettre des messages d’erreur utiles, privilégier une sortie structurée telle que JSON ou CSV sur stdout, envoyer les diagnostics à stderr et supporter une utilisation sûre de reprise. Il recommande également de figer les versions d’outils ponctuels et de décrire les exigences d’exécution explicitement dans SKILL.md ou le champ compatibility plutôt que de supposer que l’environnement a les bons paquets.

Un script tourné vers l’agent minimal mais correct ressemble à ceci :

#!/usr/bin/env bash
# scripts/collect-diff.sh — appelé par la compétence review-pr
# Usage: collect-diff.sh <base-ref> [<head-ref>]
set -euo pipefail

BASE="${1:?Usage: collect-diff.sh <base-ref> [<head-ref>]}"
HEAD="${2:-HEAD}"

# Sortie structurée vers stdout pour que l'agent puisse la parser
git diff "${BASE}...${HEAD}" --stat --name-only \
  | jq -Rs '{
      "changed_files": split("\n") | map(select(length > 0))
    }' \
  || { printf '{"error":"git diff failed"}\n' >&2; exit 1; }

Trois choses rendent cela sûr pour l’agent. set -euo pipefail assure que le script se termine bruyamment sur n’importe quelle erreur plutôt que de procéder silencieusement. JSON sur stdout donne à l’agent un format qu’il peut parser sans deviner. Les diagnostics vont à stderr afin que le flux stdout de l’agent reste propre. Rien de tout cela n’est intelligent. Tout cela est nécessaire.

Un piège subtil est allowed-tools. Dans la spécification, il est expérimental et le support varie. Dans Claude Code, il pré-approuve des outils spécifiques tandis que la Compétence est active, mais il ne restreint pas l’univers des outils appelables, et les règles de refus appartiennent encore aux permissions de Claude Code. Dans l’SDK Agent Claude, Anthropic dit explicitement que le frontmatter allowed-tools dans SKILL.md ne s’applique pas, donc les applications SDK doivent faire respecter l’accès aux outils dans la configuration principale allowed_tools ou allowedTools. Si vous ignorez cette différence, votre Compétence se comportera différemment dans la CLI et dans l’automatisation alimentée par SDK.

Un modèle avancé de plus vaut la peine d’être volé. Lorsqu’un flux de travail inonderait votre fil principal avec des logs, des recherches de fichiers ou une longue sortie de recherche, Claude Code permet à une Compétence de s’exécuter dans un sous-agent fourchu en utilisant context: fork et un agent tel que Explore. Anthropic montre cela pour les flux de travail de recherche, où le gros du travail se fait dans un contexte isolé et la conversation principale reçoit le résumé. Pour l’exploration approfondie d’une base de code, c’est un design bien meilleur qu’une Compétence en ligne géante qui pollue la session principale.

Une Compétence fourchue ressemble à ceci dans le frontmatter :

---
name: explore-codebase
description: Exploration approfondie d'une base de code inconnue. Utiliser lors de l'intégration à un nouveau dépôt, de l'audit d'architecture ou de la cartographie des dépendances de module.
context: fork
agent: Explore
compatibility: Nécessite la CLI Claude Code.
---
# Explorer la base de code

1. Parcourez l'arbre de répertoires et résumez les modules de niveau supérieur.
2. Identifiez les points d'entrée principaux et leurs responsabilités.
3. Cartographiez le graphe de dépendance entre les paquets.
4. Retournez un résumé structuré à la session principale — pas la liste brute des fichiers.

La ligne clé est context: fork. Sans cela, la sortie d’exploration atterrit en ligne dans votre conversation. Avec cela, le sous-agent s’exécute dans sa propre fenêtre de contexte et rend un résumé. La différence compte sur les grands dépôts où l’exploration seule peut consommer des milliers de jetons.

Tests des Compétences Claude : Déclencheurs, correction et comparaisons de base

Une Compétence n’est pas testée parce qu’un seul démonstration de chemin heureux a fonctionné une fois. Le guide d’Anthropic divise les tests en trois couches : tests manuels dans Claude.ai, tests scriptés dans Claude Code et tests programmatiques via l’API des Compétences. Les domaines d’évaluation recommandés sont le déclenchement, la correction fonctionnelle et la performance par rapport à une base sans la Compétence. C’est aussi la meilleure réponse à la question de la FAQ « Comment testez-vous si une compétence est fiable ». Vous testez la sélection de route, la qualité de sortie et l’efficacité, pas seulement si le modèle a semblé confiant.

La guidance officielle d’évaluation donne une structure propre pour les cas de test. Chaque cas devrait inclure une invite utilisateur réaliste, une description lisible par humain de la sortie attendue et des fichiers d’entrée optionnels. Les documents stockent ceux-ci dans evals/evals.json à l’intérieur du répertoire de la Compétence, ce qui est une convention sensée même si vous créez votre propre harnais.

Utilisez un fichier de fixture et une mise en page d’éval sans non-sens comme ceci :

{
  "skill_name": "review-pr",
  "evals": [
    {
      "id": 1,
      "prompt": "Revuez cette PR pour les problèmes de sécurité et les tests manquants",
      "expected_output": "Résultats regroupés par sévérité avec des références de fichiers et au moins une recommandation de test.",
      "files": ["evals/files/pr-diff.patch"]
    },
    {
      "id": 2,
      "prompt": "Résumez les commits de la semaine dernière",
      "expected_output": "La compétence ne devrait pas s'activer.",
      "files": []
    }
  ]
}

Ma propre règle de test est plus dure que la plupart des équipes, mais elle s’aligne avec la guidance officielle. Chaque Compétence sérieuse devrait avoir des requêtes qui devraient déclencher, des requêtes qui ne devraient pas déclencher, au moins un test de cas limite et une comparaison de base sans la Compétence. Les exemples d’Anthropic comparent les appels d’outil, les appels API échoués, les boucles de clarification et l’utilisation de jetons avec et sans la Compétence car « fonctionner » n’est pas la même chose que « améliorer le flux de travail ».

Si vous testez via le SDK Agent Claude, rappelez-vous la plomberie. Les Compétences sont des artefacts de système de fichiers là-bas, pas des enregistrements programmatiques. Anthropic dit que vous devez activer l’outil "Skill" et charger les paramètres de fichier pertinents via settingSources ou setting_sources. Si vous omettez user ou project, ou pointez cwd vers le mauvais endroit, le SDK ne découvrira pas la Compétence. Anthropic recommande même de demander « Quelles compétences sont disponibles ? » comme vérification de découverte directe.

Testez également sur le modèle et le client que vous avez réellement l’intention de livrer. Le démarrage rapide des Compétences d’Agent ouvert avertit explicitement que la fiabilité de l’utilisation d’outil varie entre les modèles, et certains modèles peuvent répondre directement au lieu d’exécuter la commande que la Compétence entend. Ce n’est pas toujours un problème de conception de Compétence. Parfois, c’est un problème de sélection de modèle, et votre matrice de test devrait l’exposer.

Dépannage des Compétences Claude : Échecs courants et corrections

Lorsqu’une Compétence se comporte mal, supposez l’emballage avant l’intelligence. Les échecs les plus courants sont encore les ennuyeux.

• Si la Compétence n’est pas trouvée du tout, vérifiez que le fichier est nommé exactement SKILL.md, avec la bonne casse, à l’intérieur du répertoire correct. Le guide de dépannage d’Anthropic pointe explicitement la casse du nom de fichier, et ses documents Claude Code et SDK vous pointent droit vers .claude/skills/*/SKILL.md et ~/.claude/skills/*/SKILL.md comme premières vérifications.
• Si le frontmatter est invalide, vérifiez d’abord les délimiteurs YAML et les guillemets. Les exemples d’Anthropic montrent les erreurs classiques : --- manquant, guillemets non fermés ou noms invalides avec des espaces et des majuscules. Les noms de compétences devraient être en minuscules et hyphenés.
• Si la Compétence existe mais ne se déclenche pas, la description est généralement trop vague. Le propre dépannage de Claude Code dit d’inclure des mots-clés que les utilisateurs diraient naturellement, de vérifier que la Compétence apparaît lorsque vous demandez « Quelles compétences sont disponibles ? », et d’essayer de reformuler plus proche de la description. Le guide PDF d’Anthropic ajoute une grande astuce de diagnostic : demandez à Claude quand il utiliserait la Compétence et écoutez comment il paraphrase la description vers vous.
• Si la Compétence se déclenche trop souvent, rétrécissez la portée. Anthropic recommande de rendre la description plus spécifique, d’ajouter des déclencheurs négatifs et d’utiliser disable-model-invocation: true pour les flux de travail que vous voulez uniquement par commande explicite. Le sur-déclenchement est généralement juste un langage de routage sous-spécifié.
• Si la Compétence semble perdre son influence dans les longues sessions, rappelez-vous que les descriptions peuvent être raccourcies dans le catalogue de Claude Code lorsque de nombreuses compétences sont présentes, et les Compétences invoquées sont ensuite transportées dans les budgets de jetons après compaction. Anthropic recommande de placer les mots-clés en tête de la description, de tailler le texte excédentaire et, pour Claude Code spécifiquement, d’ajuster SLASH_COMMAND_TOOL_CHAR_BUDGET si les listes de description sont comprimées trop agressivement.
• Si un script intégré se bloque ou se comporte de manière erratique, vérifiez s’il s’attend à une entrée interactive. Le guide des scripts dit que les agents s’exécutent dans des shells non interactifs, donc les invites TTY, les dialogues de mot de passe et les menus de confirmation sont des bugs de conception. Acceptez l’entrée via des drapeaux, des variables d’environnement ou stdin et rendez les échecs explicites.
• Si le SDK ne voit pas votre Compétence, confirmez que allowed_tools inclut "Skill", que settingSources ou setting_sources contient user et/ou project, et que cwd pointe vers le répertoire qui contient réellement .claude/skills/. Sans cette configuration, le système de Compétences n’est pas activé peu importe à quel point votre markdown semble correct.
• Si une Compétence soutenue par MCP se charge mais que les appels d’outil échouent, la checklist de dépannage d’Anthropic est sensée : vérifiez que le serveur MCP est connecté, confirmez l’authentification et les scopes, testez l’outil MCP directement sans la Compétence, puis vérifiez les noms d’outil exacts car ils sont sensibles à la casse.

La vérité ennuyeuse est que de bonnes Compétences Claude ressemblent à une bonne ingénierie opérationnelle. Noms clairs. Petits fichiers. Déclencheurs explicites. Scripts déterministes là où nécessaire. Vrais tests. Si votre Compétence lit comme un livre de runbook net, l’agent a une chance de se battre. Si elle lit comme un brainstorming, vous avez simplement caché le chaos dans un dossier.