# Agents vs Commandes vs Skills — Quand utiliser quoi

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

<table width="100%">
<tr>
<td><a href="../">← Retour à Claude Code Best Practice</a></td>
<td align="right"><img src="../../!/claude-jumping.svg" alt="Claude" width="60" /></td>
</tr>
</table>

![Menu slash montrant time-skill, time-command et time-agent](../../reports/assets/agent-command-skill-1.jpg)

---

## 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

```yaml
---
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

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

### Frontmatter de Skill

```yaml
---
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.

![Claude auto-invoquant time-skill quand l'utilisateur demande « What is the current time? »](../../reports/assets/agent-command-skill-2.png)

---

## Sources

- [Skills Claude Code — Documentation](https://code.claude.com/docs/en/skills)
- [Sous-agents Claude Code — Documentation](https://code.claude.com/docs/en/sub-agents)
- [Commandes slash Claude Code — Documentation](https://code.claude.com/docs/en/slash-commands)
- [Bonnes pratiques — Skills](../best-practice/claude-skills.md)
- [Bonnes pratiques — Commandes](../best-practice/claude-commands.md)
- [Bonnes pratiques — Sous-agents](../best-practice/claude-subagents.md)