Commandes personnalisées et skills - Erreurs courantes

Les commandes personnalisées, skills et hooks de Claude Code génèrent des gains de productivité considérables, mais leurs erreurs de configuration provoquent des dysfonctionnements silencieux. Ce guide recense les 10 pièges les plus fréquents lors de la mise en place de commandes slash custom, subagents et automatisations, avec les correctifs concrets pour chaque cas.

Les erreurs liées aux commandes personnalisées et skills dans Claude Code représentent la première cause de frustration chez les développeurs qui automatisent leurs workflows. Claude Code v2.1 propose un écosystème complet - commandes slash, skills, hooks et subagents - mais chaque composant possède ses propres contraintes de configuration.

plus de 40 % des tickets de support concernent des erreurs de syntaxe ou de structure dans les fichiers de personnalisation. Ces problèmes sont évitables si vous connaissez les pièges documentés ci-dessous.

Quelles sont les erreurs les plus fréquentes avec les commandes personnalisées ?

Voici un panorama des 10 erreurs classées par fréquence et sévérité. Chaque erreur est reproductible et corrigeable en moins de 5 minutes.

Pour une vue d'ensemble des fonctionnalités avant de plonger dans les erreurs, consultez le guide complet des commandes personnalisées et skills qui détaille chaque composant.

À retenir : Classez vos corrections par sévérité - les erreurs critiques provoquent des échecs silencieux, les avertissements dégradent la qualité des résultats.

Comment éviter l'erreur de structure de dossier pour les commandes slash ?

Erreur 1 - Sévérité : Critique. Placer les fichiers de commandes au mauvais emplacement empêche Claude Code de les détecter.

Claude Code attend vos commandes slash dans le répertoire .claude/commands/ à la racine du projet. Un fichier mal placé - par exemple dans .claude/slash/ ou commands/ - est ignoré sans message d'erreur. En pratique, 30 % des développeurs créent le dossier au mauvais niveau.

Le format attendu est un fichier Markdown portant le nom de la commande. Chaque fichier .md devient une commande invocable par /nom-du-fichier.

❌ Incorrect :

# Structure incorrecte - commandes non détectées
mkdir -p commands/
echo "Mon prompt" > commands/review.md
# Ou pire : fichier JSON au lieu de Markdown
echo '{"prompt": "review"}' > .claude/commands/review.json

✅ Correct :

# Structure correcte pour les commandes projet
mkdir -p .claude/commands/
echo "Analyse ce fichier et propose des améliorations" > .claude/commands/review.md

# Structure correcte pour les commandes globales (utilisateur)
mkdir -p ~/.claude/commands/
echo "Résume ce code en 3 points" > ~/.claude/commands/summarize.md

Concrètement, les commandes dans .claude/commands/ sont spécifiques au projet et partagées via Git, tandis que celles dans ~/.claude/commands/ sont globales à votre machine. Vous trouverez des détails sur les erreurs similaires dans le guide des commandes slash essentielles - erreurs courantes.

À retenir : Vérifiez toujours que vos commandes sont dans .claude/commands/ (projet) ou ~/.claude/commands/ (global), au format Markdown exclusivement.

Pourquoi un prompt trop vague rend-il un skill inutilisable ?

Erreur 2 - Sévérité : Critique. Un skill est un fichier de prompt réutilisable qui encode vos patterns de travail. Un prompt vague produit des résultats incohérents.

Un skill permet à Claude Code d'apprendre vos conventions. Mais si le prompt manque de contraintes, l'IA interprète librement et produit des résultats différents à chaque invocation. un skill efficace contient au minimum 3 contraintes explicites et 1 exemple de sortie attendue.

❌ Incorrect :

# .claude/commands/test.md
Écris des tests pour ce code.

✅ Correct :

# .claude/commands/test.md
Écris des tests unitaires pour le fichier $ARGUMENTS en respectant ces règles :
- Framework : Vitest
- Couverture minimale : 80% des branches
- Nommer les tests avec le pattern "should [action] when [condition]"
- Mocker les dépendances externes avec vi.mock()
- Inclure au moins 1 test de cas d'erreur

Exemple de sortie attendue :

typescript

describe('maFonction', () => { it('should return true when input is valid', () => { expect(maFonction('valid')).toBe(true); }); });

La variable $ARGUMENTS permet de passer des paramètres dynamiques à votre commande. Vous tapez /test src/utils.ts et Claude Code remplace $ARGUMENTS par src/utils.ts. En pratique, un skill bien contraint réduit de 60 % le nombre de corrections manuelles.

Pour approfondir la rédaction de prompts efficaces, consultez le tutoriel des commandes personnalisées qui propose des modèles prêts à l'emploi.

À retenir : Spécifiez le framework, les conventions de nommage, la couverture cible et un exemple concret dans chaque skill.

Comment corriger un hook sans gestion d'erreur ?

Erreur 3 - Sévérité : Critique. Un hook est une commande shell déclenchée automatiquement par un événement Claude Code. Sans gestion d'erreur, un hook défaillant bloque toute la session.

Les hooks sont des automatisations déterministes - contrairement aux skills basés sur l'IA, ils exécutent du code shell prévisible. Un hook configuré dans .claude/settings.json qui échoue silencieusement peut corrompre votre workflow sans que vous le remarquiez.

❌ Incorrect :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Ce hook formate chaque fichier écrit par Claude Code, mais si Prettier n'est pas installé ou si le chemin contient des espaces, l'échec passe inaperçu.

✅ Correct :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "if command -v npx >/dev/null 2>&1; then npx prettier --write \"$CLAUDE_FILE_PATH\" || echo 'Prettier failed' >&2; fi"
      }
    ]
  }
}

Concrètement, le hook corrigé vérifie que npx existe, encadre le chemin avec des guillemets et capture l'erreur. Les hooks supportent les événements PreToolUse, PostToolUse, Notification et Stop. Les erreurs de hooks partagent des patterns similaires avec les erreurs de permissions et sécurité - une commande mal sécurisée peut exposer votre système.

À retenir : Encadrez chaque hook avec une vérification de dépendance, des guillemets sur les chemins et un || echo 'error' >&2 pour capturer les échecs.

Pourquoi lancer un subagent sans contexte suffisant produit-il des résultats médiocres ?

Erreur 4 - Sévérité : Avertissement. Un subagent est une instance Claude lancée depuis Claude Code pour traiter une sous-tâche. Sans contexte, il travaille à l'aveugle.

Le système de subagents (ou « Task ») permet de paralléliser le travail en lançant des agents spécialisés. Mais chaque subagent démarre avec un contexte vierge - il ne voit pas votre conversation en cours. En 2026, le coût moyen d'un subagent mal configuré est de 15 000 tokens gaspillés par invocation.

❌ Incorrect :

# Prompt de subagent trop vague
Corrige les bugs dans le projet.

✅ Correct :

# Prompt de subagent contextualisé
Analyse le fichier src/api/auth.ts et corrige l'erreur TypeScript TS2345 
à la ligne 42. Le projet utilise :
- TypeScript 5.4 avec strict mode
- Express 4.18
- Le type attendu est `AuthRequest` défini dans src/types/auth.ts
Retourne uniquement le diff des modifications.

Vous devez fournir au subagent : le fichier cible, le langage, les types impliqués et le format de sortie attendu. Un subagent bien cadré consomme en moyenne 3 000 tokens contre 15 000 pour un subagent sans contexte - soit une réduction de 80 % du coût.

Si vous rencontrez aussi des problèmes de contexte trop large dans vos conversations principales, le guide des erreurs de gestion du contexte détaille les solutions pour optimiser la fenêtre de contexte.

À retenir : Fournissez au subagent le fichier cible, la stack technique, le type d'erreur et le format de sortie dans chaque invocation.

Comment résoudre les conflits de noms entre commandes locales et globales ?

Erreur 5 - Sévérité : Avertissement. Quand une commande projet et une commande globale portent le même nom, la commande projet écrase la globale sans avertissement.

Vous créez une commande /review dans ~/.claude/commands/review.md pour tous vos projets. Puis un collègue ajoute .claude/commands/review.md dans le dépôt. Votre commande globale disparaît pour ce projet. En pratique, cette collision affecte 1 développeur sur 5 dans les équipes utilisant des commandes partagées via Git.

❌ Incorrect :

# Commande globale
~/.claude/commands/review.md → "Review avec mes conventions perso"

# Commande projet (même nom)
.claude/commands/review.md → "Review selon les standards équipe"

# Résultat : la commande projet écrase la globale, SANS avertissement

✅ Correct :

# Convention de nommage pour éviter les collisions
~/.claude/commands/my-review.md    → Préfixe personnel "my-"
.claude/commands/team-review.md    → Préfixe équipe "team-"

# Ou utiliser des sous-dossiers (supportés depuis Claude Code v2.0)
.claude/commands/team/review.md    → Invoqué par /team:review
~/.claude/commands/perso/review.md → Invoqué par /perso:review

Adoptez une convention de préfixage dès le premier jour. Les sous-dossiers créent des espaces de noms naturels. Consultez les astuces pour les commandes personnalisées pour découvrir d'autres conventions de nommage éprouvées.

À retenir : Préfixez vos commandes globales avec my- ou perso- et vos commandes projet avec team- pour éliminer les collisions de noms.

Faut-il toujours renseigner le champ description dans un skill ?

Erreur 6 - Sévérité : Avertissement. Omettre la description empêche Claude Code de suggérer automatiquement le skill pertinent.

Le champ description en première ligne du fichier Markdown aide Claude Code à comprendre quand suggérer votre commande. Sans description, la commande existe mais n'apparaît jamais dans les suggestions contextuelles. La description doit tenir en 1 ligne et 120 caractères maximum.

❌ Incorrect :

# .claude/commands/migrate.md

Analyse le schéma Prisma et génère une migration SQL compatible PostgreSQL.
Vérifie les contraintes de clés étrangères.

✅ Correct :

# .claude/commands/migrate.md
# Description: Génère une migration Prisma/PostgreSQL à partir du schéma modifié

Analyse le schéma Prisma et génère une migration SQL compatible PostgreSQL.
Vérifie les contraintes de clés étrangères.
Utilise `prisma migrate dev --name $ARGUMENTS` pour appliquer.

Voici comment vérifier que vos skills sont bien détectés : Exécutez / dans Claude Code et parcourez la liste. Chaque commande avec description affiche un aperçu dans le menu. Les commandes sans description apparaissent avec un libellé générique, réduisant de 70 % la probabilité qu'un collègue les découvre. La FAQ des commandes personnalisées répond aux questions fréquentes sur les métadonnées de skills.

À retenir : Ajoutez un commentaire # Description: en première ligne de chaque fichier de commande pour activer les suggestions contextuelles.

Comment empêcher un hook de bloquer Claude Code indéfiniment ?

Erreur 7 - Sévérité : Critique. Un hook sans timeout peut geler votre session Claude Code pendant plusieurs minutes.

Un hook déclenché sur PostToolUse qui appelle un serveur distant ou exécute un build long bloque Claude Code tant que le processus tourne. Concrètement, un hook npm run build sur un monorepo de 200 000 lignes peut prendre 45 secondes - pendant lesquelles Claude Code est inutilisable.

❌ Incorrect :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npm run build && npm run test"
      }
    ]
  }
}

✅ Correct :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "timeout 10 npx eslint --fix \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  }
}

Limitez les hooks à des opérations rapides - lint, formatage - et réservez les builds et tests aux commandes explicites. Si vous automatisez aussi vos workflows Git avec des hooks, le guide des erreurs d'intégration Git couvre les pièges similaires côté pre-commit.

À retenir : Encadrez chaque hook avec timeout N (en secondes) et redirigez stderr vers /dev/null pour éviter les blocages.

Pourquoi un subagent avec des permissions trop larges pose-t-il problème ?

Erreur 8 - Sévérité : Avertissement. Un subagent qui hérite de toutes les permissions peut modifier des fichiers critiques ou exécuter des commandes destructrices.

Par défaut, un subagent hérite du mode de permissions de la session parente. Si vous travaillez en mode bypassPermissions, le subagent peut supprimer des fichiers, modifier .env ou exécuter rm -rf sans confirmation. chaque subagent devrait recevoir le minimum de permissions nécessaires.

❌ Incorrect :

# Lancer un subagent en mode permissif pour une tâche de lecture
Utiliser mode: "bypassPermissions" pour analyser le code source

✅ Correct :

# Lancer un subagent en mode restreint adapté à la tâche
Utiliser subagent_type: "Explore" pour les tâches de recherche (lecture seule)
Utiliser subagent_type: "Plan" pour la planification (lecture seule)
Utiliser mode: "plan" pour les tâches nécessitant approbation avant modification

Le choix du subagent_type détermine les outils accessibles. Un agent Explore ne peut ni écrire ni éditer de fichiers - c'est le choix sécurisé pour la recherche de code. En pratique, 25 % des incidents de suppression accidentelle proviennent de subagents avec des permissions excessives. Pour maîtriser le modèle de permissions complet, référez-vous aux erreurs de permissions et sécurité.

À retenir : Choisissez le subagent_type le plus restrictif possible - Explore pour lire, Plan pour planifier, general-purpose uniquement pour modifier du code.

Comment éviter qu'une commande slash ignore ses arguments ?

Erreur 9 - Sévérité : Mineur. Oublier la variable $ARGUMENTS dans le prompt de votre commande rend les paramètres utilisateur inaccessibles.

Quand vous tapez /deploy staging, le mot staging est capturé dans $ARGUMENTS. Si votre fichier de commande ne référence jamais cette variable, l'argument est perdu. Le prompt s'exécute sans tenir compte de ce que vous avez tapé après le nom de la commande.

❌ Incorrect :

# .claude/commands/deploy.md
Déploie l'application sur l'environnement approprié.
Vérifie les variables d'environnement et lance le build.

✅ Correct :

# .claude/commands/deploy.md
# Description: Déploie l'application sur l'environnement spécifié

Déploie l'application sur l'environnement $ARGUMENTS.
Étapes :
1. Vérifier que le fichier .env.$ARGUMENTS existe
2. Lancer `npm run build -- --mode $ARGUMENTS`
3. Exécuter `npm run deploy:$ARGUMENTS`
Si $ARGUMENTS est vide, demander à l'utilisateur de préciser : staging ou production.

Vous pouvez aussi référencer $FILE pour passer le fichier actuellement ouvert. Testez chaque commande avec et sans arguments pour valider les deux chemins. Les erreurs courantes des premières conversations couvrent d'autres cas où les entrées utilisateur sont mal interprétées.

À retenir : Incluez $ARGUMENTS dans le prompt et gérez le cas où la variable est vide avec une instruction de fallback explicite.

Peut-on créer un skill qui duplique une fonctionnalité native de Claude Code ?

Erreur 10 - Sévérité : Mineur. Recréer une commande native génère des conflits de comportement et complexifie la maintenance.

Claude Code intègre nativement des commandes comme /init, /compact, /review, /memory depuis la version 2.0 (2025). Créer un skill /compact.md personnalisé entre en conflit avec la commande native. Le comportement résultant est imprévisible - parfois votre version s'exécute, parfois la native.

❌ Incorrect :

# Créer une commande qui porte le même nom qu'une commande native
echo "Résume la conversation" > .claude/commands/compact.md
echo "Initialise le projet" > .claude/commands/init.md

✅ Correct :

# Étendre les commandes natives avec un nom distinct
echo "Résume la conversation ET met à jour CLAUDE.md" > .claude/commands/compact-plus.md
echo "Initialise le projet avec les standards SFEIR" > .claude/commands/init-sfeir.md

Voici comment vérifier les commandes natives existantes : Tapez / dans Claude Code et faites défiler la liste complète. Toute commande native a priorité sur une commande personnalisée de même nom dans certains contextes. Le guide de la mémoire CLAUDE.md - erreurs courantes explique comment éviter les conflits similaires avec le système de mémoire.

À retenir : Listez les commandes natives avec / avant de créer un skill, et choisissez un nom distinct pour éviter les conflits.

Comment structurer un projet avec commandes, skills et hooks sans confusion ?

Voici l'architecture recommandée par SFEIR Institute pour organiser vos personnalisations Claude Code. Cette structure sépare les responsabilités et facilite le partage en équipe.

mon-projet/
├── .claude/
│   ├── commands/           # Commandes slash projet
│   │   ├── team/           # Namespace équipe
│   │   │   ├── review.md
│   │   │   └── deploy.md
│   │   └── ci/             # Namespace CI/CD
│   │       └── validate.md
│   ├── settings.json       # Hooks et permissions
│   └── CLAUDE.md           # Mémoire projet

// .claude/settings.json - hooks minimalistes
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "timeout 5 npx prettier --write \"$CLAUDE_FILE_PATH\" 2>/dev/null || true"
      }
    ]
  },
  "permissions": {
    "allow": ["Read", "Glob", "Grep"],
    "deny": ["Bash(rm *)"]
  }
}

SFEIR Institute propose la formation Claude Code sur 1 jour pour maîtriser ces personnalisations en pratique, avec des labs guidés sur la création de commandes, skills et hooks. Pour aller plus loin, la formation Développeur Augmenté par l'IA couvre en 2 jours l'ensemble des workflows d'automatisation avec les agents IA, y compris les subagents et le chaînage de tâches.

Les développeurs expérimentés peuvent suivre la formation Développeur Augmenté par l'IA – Avancé sur 1 jour pour approfondir les patterns avancés de personnalisation et d'orchestration multi-agents.

À retenir : Séparez commandes, hooks et mémoire dans des fichiers dédiés, et utilisez des namespaces pour éviter les collisions en équipe.

Quels réflexes adopter pour déboguer une commande ou un hook défaillant ?

Quand une commande slash ou un hook ne fonctionne pas, appliquez cette checklist de diagnostic en 5 étapes :

1. Vérifiez l'emplacement : le fichier est-il dans .claude/commands/ (projet) ou ~/.claude/commands/ (global) ?
2. Confirmez l'extension : seuls les fichiers .md sont reconnus comme commandes
3. Testez le hook isolément : copiez la commande shell et exécutez-la manuellement dans le terminal
4. Inspectez les logs : Claude Code affiche les erreurs de hooks dans la sortie stderr
5. Validez le JSON : utilisez cat .claude/settings.json | python3 -m json.tool pour détecter les erreurs de syntaxe

# Diagnostic rapide d'un hook
$ cat .claude/settings.json | python3 -m json.tool
# Si erreur JSON → corriger la syntaxe
# Si JSON valide → tester la commande du hook manuellement
$ timeout 5 npx prettier --write "test.ts" 2>&1

En pratique, 55 % des problèmes de hooks proviennent d'une erreur de syntaxe JSON (virgule manquante, guillemet non fermé). Node.js 22 LTS est la version recommandée pour exécuter les outils CLI référencés dans les hooks.

Pour d'autres techniques de diagnostic, consultez les astuces des commandes personnalisées qui proposent des scripts de validation automatisée.

À retenir : Isolez le problème en testant chaque composant séparément - d'abord le JSON, puis la commande shell, puis l'intégration avec Claude Code.