Commandes, Skills, Subagents, Rules : ce que j'ai appris en organisant 139 extensions

Après avoir créé 95 hooks, 44 skills, 85 commandes et 11 fichiers de rules pour Claude Code, j’ai appris que choisir la mauvaise abstraction fait perdre plus de temps que de développer la mauvaise fonctionnalité. Un skill qui aurait dû être une rule a gonflé mon contexte de 40 %. Une commande qui aurait dû être un skill m’obligeait à me souvenir de taper /fastapi à chaque fois que je touchais un endpoint API.¹

TL;DR

Claude Code propose quatre façons d’étendre son comportement : les Commands (prompts déclenchés par l’utilisateur), les Skills (contexte invoqué automatiquement), les Subagents (exécuteurs de tâches délégués) et les Rules (contraintes permanentes). Après avoir organisé 139 extensions, j’ai constaté que le cadre de décision est simple : les Rules pour les invariants, les Skills pour l’expertise métier, les Commands pour les workflows, les Subagents pour l’isolation. Le plus difficile est de reconnaître quand vous avez fait le mauvais choix et de migrer.

Les quatre abstractions (avec des exemples concrets)

Commands : « /commit » et 84 autres

Les commandes s’activent lorsque je tape /command-name. Chacune se déploie en un modèle de prompt.²

Mes 85 commandes incluent /commit (commit git intelligent), /review (lancement d’agents de revue de code), /deploy (checklist de déploiement), /publish-check (validation pré-publication de blog) et /deliberate (recherche multi-agents).

L’erreur que j’ai commise : j’ai créé /fastapi comme une commande qui injectait les patterns FastAPI à la demande. Le problème : j’oubliais de la taper la moitié du temps. Chaque invocation oubliée signifiait que l’agent passait à côté de patterns que je voulais voir appliqués. La solution a été de migrer /fastapi vers un Skill avec activation automatique.

Skills : 44 modules de connaissances auto-activés

Les Skills s’activent automatiquement lorsque la conversation correspond à la description du skill. Je ne tape jamais de commande ; le système injecte l’expertise pertinente en fonction du contexte.³

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

Mes 44 skills couvrent : - Connaissances métier (8) : FastAPI, SwiftUI, HTMX/Alpine, base de données, tests, débogage, architecture, sécurité - Infrastructure blog (7) : blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - Philosophie/qualité (5) : Shokunin (Jiro), No Shortcuts, Rubin essence, design principles - Multi-agents (3) : délibération, revue, création de contenu - Spécifiques à un projet (4) : contenu du site personnel, blog ResumeGeni, capture Obsidian

L’incident des 40 % de surcharge de contexte : au début, j’avais mis mon guide complet de patterns FastAPI (800 lignes) dans un fichier Rule. Les Rules se chargent dans chaque session. Quand je travaillais sur des applications iOS, du CSS ou du contenu de blog, 800 lignes de patterns FastAPI non pertinents consommaient des tokens de contexte. Déplacer le contenu vers un Skill avec la description « FastAPI backend development » a résolu le problème : le skill ne se chargeait que pendant le travail sur l’API.⁴

Subagents : des relecteurs isolés

Les Subagents s’exécutent dans leur propre fenêtre de contexte avec un accès restreint aux outils et des permissions indépendantes.⁵

Mes subagents incluent security-reviewer (accès en lecture seule, analyse de vulnérabilités OWASP), test-runner (exécution des tests, analyse des échecs) et conventions-reviewer (vérification des standards du projet).

Pourquoi l’isolation est importante : lors d’une revue de code, le relecteur ne devrait pas pouvoir modifier les fichiers. Un Skill peut injecter des connaissances de revue, mais la revue se déroule toujours dans le contexte principal avec des permissions d’écriture complètes. Un Subagent impose l’accès en lecture seule de manière architecturale.

Rules : 11 fichiers de contraintes permanentes

Les Rules se chargent automatiquement dans chaque conversation. Mes 11 fichiers de rules couvrent :⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

La leçon du dimensionnement : mes rules totalisent environ 180 lignes réparties sur 11 fichiers. Chaque ligne se charge dans chaque session. À l’origine, j’avais plus de 400 lignes avant de migrer le contenu spécifique à un sujet vers les Skills. L’ensemble de 180 lignes de rules couvre les véritables invariants (contraintes de sécurité, workflow git, corrections). Tout le reste appartient aux Skills.

Le cadre de décision

Le schéma de migration

La structure de mon .claude/ a évolué en trois phases :

Phase 1 (Mois 1-2) : tout dans les Rules. Plus de 400 lignes de contexte chargé en permanence. Patterns iOS, patterns FastAPI, directives de design, standards de tests. Le contexte était surchargé dans chaque session.

Phase 2 (Mois 3-4) : migration du contenu spécifique à un sujet vers les Skills. Les Rules sont passées à 200 lignes. Les Skills ont atteint plus de 20 répertoires. La surcharge de contexte a diminué de 40 %.

Phase 3 (Mois 5+) : ajout de Subagents pour les tâches nécessitant de l’isolation (revue de code, audit de sécurité). Les Commands se sont stabilisées à 85 pour les workflows explicites. Les Skills ont atteint 44 à mesure que j’ajoutais de l’expertise spécifique à chaque domaine.⁷

La leçon : commencez par les Rules (peu coûteuses, toujours disponibles), identifiez ce qui est spécifique à un sujet (migrez vers les Skills), et n’ajoutez des Subagents que lorsque vous avez besoin d’isolation.

Les Skills au service des Subagents

Un pattern puissant : injecter des Skills dans le contexte d’un Subagent via le champ frontmatter skills :

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

Les skills security et testing-philosophy injectent leur contenu dans le prompt système du subagent. Le relecteur obtient des connaissances spécialisées au sein de son contexte isolé et en lecture seule.⁸

Mon pipeline de revue utilise ce pattern : trois subagents (correctness-reviewer, security-reviewer, conventions-reviewer) reçoivent chacun des injections de skills différentes. Le relecteur de correction reçoit debugging-philosophy. Le relecteur de sécurité reçoit l’ensemble de rules de sécurité. Le relecteur de conventions reçoit les standards de codage du projet.

Mon architecture de production

~/.claude/
├── commands/     # 85 — User-triggered workflows
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Auto-invoked expertise
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Isolated task executors
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 files, ~180 lines — Always-on constraints
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Lifecycle event handlers
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

Points clés à retenir

Pour les développeurs solo : - Commencez par les Rules pour les standards spécifiques au projet (restez sous 200 lignes au total) - Ajoutez des Skills pour vos piles technologiques les plus utilisées ; l’activation automatique élimine le problème du « j’ai oublié d’invoquer » - Créez d’abord des Commands pour vos trois workflows les plus courants - N’ajoutez des Subagents que lorsque vous avez besoin de restreindre les outils ou d’isoler le contexte

Pour les équipes : - Standardisez les Rules au niveau du projet pour assurer la cohérence de l’équipe - Partagez les Skills via un dépôt commun ; la portabilité des Skills entre les projets est leur principal avantage par rapport à la configuration au niveau du projet

Références