gilles/claude-code-best-practice

Fork 0

Files

T

gilles e8f2b1a034 traduction

2026-06-02 23:24:21 +02:00

9.5 KiB

Raw Permalink Blame History

Agents vs Commandes vs Skills — Quand utiliser quoi

Une comparaison des trois mécanismes d'extension de Claude Code : sous-agents, commandes et skills.

← Retour à Claude Code Best Practice

En un coup d'œil

	Agent	Commande	Skill
Emplacement	`.claude/agents/<name>.md`	`.claude/commands/<name>.md`	`.claude/skills/<name>/SKILL.md`
Contexte	Processus de sous-agent séparé	Inline (conversation principale)	Inline (conversation principale)
Invocable par l'utilisateur	Pas de menu `/` — invoqué par Claude ou via l'outil Agent	Oui — `/command-name`	Oui — `/skill-name` (sauf `user-invocable: false`)
Auto-invoqué par Claude	Oui — via le champ `description`	Non	Oui — via le champ `description` (sauf `disable-model-invocation: true`)
Accepte des arguments	Via le paramètre `prompt`	`$ARGUMENTS`, `$0`, `$1`	`$ARGUMENTS`, `$0`, `$1`
Injection de contexte dynamique	Non	Oui — !`command`	Oui — !`command`
Fenêtre de contexte propre	Oui — isolée	Non — partage la principale	Non — partage la principale (sauf `context: fork`)
Surcharge de modèle	Frontmatter `model:`	Frontmatter `model:`	Frontmatter `model:`
Restrictions d'outils	`tools:` / `disallowedTools:`	`allowed-tools:`	`allowed-tools:`
Hooks	Frontmatter `hooks:`	—	Frontmatter `hooks:`
Mémoire	Frontmatter `memory:` (user/project/local)	—	—
Peut précharger des skills	Oui — frontmatter `skills:`	—	—
Serveurs MCP	Frontmatter `mcpServers:`	—	—

Quand utiliser chacun

Utilise un Agent quand :

La tâche est autonome et multi-étapes — l'agent doit explorer, décider et agir sans guidage constant
Tu as besoin d'isolation de contexte — le travail ne doit pas polluer la fenêtre de conversation principale
L'agent a besoin de mémoire persistante entre les sessions (par ex. un relecteur de code qui apprend des patterns)
Tu veux précharger de la connaissance de domaine via des skills sans encombrer le contexte principal
La tâche bénéficie d'une exécution en arrière-plan ou dans un worktree git
Tu as besoin de restrictions d'outils ou d'un mode de permissions différent (par ex. acceptEdits, plan)

Exemple : weather-agent — récupère de façon autonome les données météo via son skill préchargé weather-fetcher, tourne dans un contexte séparé avec des outils restreints.

Utilise une Commande quand :

Tu as besoin d'un point d'entrée initié par l'utilisateur — un workflow que l'utilisateur déclenche explicitement
Le workflow implique d'orchestrer d'autres agents ou skills
Tu veux garder le contexte léger — le contenu de la commande n'est pas injecté dans le contexte de session tant que l'utilisateur ne la déclenche pas

Exemple : weather-orchestrator — l'utilisateur le déclenche, il demande la préférence C/F, invoque l'agent, puis invoque le skill SVG.

Utilise un Skill quand :

Tu veux que Claude auto-invoque selon l'intention de l'utilisateur — les descriptions de skills sont injectées dans le contexte de session pour une correspondance sémantique
La tâche est une procédure réutilisable invocable depuis plusieurs endroits (commandes, agents, ou Claude lui-même)
Tu as besoin de préchargement d'agent — intégrer de la connaissance de domaine dans un agent spécifique au démarrage

Exemple : weather-svg-creator — Claude l'auto-invoque quand l'utilisateur demande une carte météo ; aussi appelable depuis des commandes.

L'architecture Commande → Agent → Skill

Ce dépôt démontre un pattern d'orchestration en couches :

L'utilisateur déclenche /command
    ↓
La commande orchestre le workflow
    ↓
La commande invoque l'Agent (contexte séparé, autonome)
    ↓
L'Agent utilise le Skill préchargé (connaissance de domaine)
    ↓
La commande invoque le Skill (inline, pour la génération de sortie)

Exemple concret — le système météo :

/weather-orchestrator (commande — point d'entrée, demande C/F)
    ↓
weather-agent (agent — récupère la température de façon autonome)
    ├── weather-fetcher (skill d'agent — instructions API préchargées)
    ↓
weather-svg-creator (skill — crée le SVG inline)

Comparaison des frontmatters

Frontmatter d'Agent

---
name: my-agent
description: Use this agent PROACTIVELY when...
tools: Read, Write, Edit, Bash
model: sonnet
maxTurns: 10
permissionMode: acceptEdits
memory: user
skills:
  - my-skill
---

Frontmatter de Commande

---
description: Do something useful
argument-hint: [issue-number]
allowed-tools: Read, Edit, Bash(gh *)
model: sonnet
---

Frontmatter de Skill

---
name: my-skill
description: Do something when the user asks for...
argument-hint: [file-path]
disable-model-invocation: false
user-invocable: true
allowed-tools: Read, Grep, Glob
model: sonnet
context: fork
agent: general-purpose
---

Distinctions clés

Auto-invocation

Mécanisme	Claude peut-il auto-invoquer ?	Comment l'empêcher
Agent	Oui — via `description` (utilise « PROACTIVELY » pour l'encourager)	Retire ou adoucis la description
Commande	Non — toujours initiée par l'utilisateur via `/`	N/A
Skill	Oui — via `description`	Mets `disable-model-invocation: true`

Visibilité dans le menu `/`

Mécanisme	Apparaît dans le menu `/` ?	Comment masquer
Agent	Non	N/A
Commande	Oui — toujours	Ne peut être masquée
Skill	Oui — par défaut	Mets `user-invocable: false`

Isolation de contexte

Mécanisme	Tourne dans son propre contexte ?	Comment configurer
Agent	Toujours	Comportement intégré
Commande	Jamais	N/A
Skill	Optionnel	Mets `context: fork`

Exemple traité : « Quelle est l'heure actuelle ? »

Ce dépôt a les trois mécanismes définis pour la même tâche — afficher l'heure actuelle en PKT. Voici ce qui se passe quand un utilisateur tape « What is the current time? » sans invoquer explicitement une commande / :

Mécanisme	Va-t-il se déclencher ?	Pourquoi / Pourquoi pas
`time-command`	Non	Les commandes ne sont jamais auto-invoquées. L'utilisateur devrait taper explicitement `/time-command` pour l'exécuter. Les commandes n'ont pas de voie d'auto-découverte — elles sont strictement initiées par l'utilisateur.
`time-agent`	Oui (possible)	La `description` de l'agent dit « Use this agent to display the current time in Pakistan Standard Time ». Claude la met en correspondance avec l'intention de l'utilisateur et peut l'instancier via l'outil Agent. Cependant, les agents tournent dans une fenêtre de contexte séparée, les rendant plus lourds que nécessaire pour cette tâche simple.
`time-skill`	Oui (le plus probable)	La `description` du skill dit « Display the current time in Pakistan Standard Time (PKT, UTC+5). Use when the user asks for the current time, Pakistan time, or PKT. » Claude la met en correspondance et l'invoque via l'outil Skill. Comme il tourne inline sans surcoût de contexte, c'est la correspondance la plus efficace.

Ordre de résolution

Quand plusieurs mécanismes correspondent à la même intention, Claude préfère l'option la plus légère qui satisfait la requête :

1. Skill (inline, sans surcoût de contexte)     ← préféré
2. Agent (contexte séparé, autonome)            ← utilisé si le skill est indisponible ou la tâche complexe
3. Commande (jamais — requiert un / explicite)  ← uniquement si l'utilisateur tape /time-command

Et si `disable-model-invocation: true` était défini sur le skill ?

Alors Claude ne peut pas auto-invoquer le skill. L'agent devient la seule option auto-invocable, donc Claude instancierait time-agent à la place — au prix d'une fenêtre de contexte séparée pour une commande bash d'une ligne.

Et si skill et agent avaient tous deux l'auto-invocation désactivée ?

Alors rien ne se déclenche automatiquement. Claude se rabattrait sur sa propre connaissance générale et lancerait probablement juste TZ='Asia/Karachi' date directement — aucun mécanisme d'extension impliqué. L'utilisateur devrait taper explicitement /time-command ou /time-skill pour en utiliser un.

9.5 KiB Raw Permalink Blame History