Aller au contenu

ADR-011 — Catalogue partagé des skills bricks-OS et critères de création
Statut Proposed
Date 13/05/2026 (S20)
Décideurs Nicolas Léonard, Romain BAZIL
Origine Conversation Nicolas × Claude Code 13/05/2026, suite au ré-alignement post PR #13/#14/#15/#16

Contexte

Depuis la PR #13 (mention des skills dans CLAUDE.md) et l'ADR-010 (convention de PR), bricks-OS accueille un mélange croissant d'artefacts outillés :

  • 4 skills dans .claude/skills/ (déclenchés automatiquement par description) : add-adr, create-diagram, scan-feedback, update-rules
  • 7 slash commands dans .claude/commands/ (déclenchés explicitement par /<nom>) : create-issue, create-plan, document, execute, learning-opportunity, review, synchro-nico
  • Côté Cursor : équivalents dans .cursor/automations/ (workflow 2.0) et .cursor/rules/

Aujourd'hui aucune règle explicite ne dit quand créer un skill ou un command vs quand rester sur un prompt direct. Deux risques concrets :

  1. Doublons silencieux : un skill prep-synchro côté Nicolas + un command synchro-weekly côté Romain qui font la même chose → drift de méthodologie
  2. Explosion d'artefacts triviaux : tout transformer en skill dilue la valeur des skills utiles et rend l'OS illisible

Décision

1. Définition d'un skill (au sens large)

Un skill (incluant les .claude/skills/, .claude/commands/, et leurs équivalents Cursor) est une pratique récurrente caractérisée par :

  • Un output clair et identifiable (page Notion, ADR, rapport, PR, commit, fichier markdown structuré…)
  • Une méthodologie qu'on veut commune entre contributeurs (format, structure, contraintes de style, séquence d'étapes)

2. Critères pour créer un nouveau skill / command

  • Récurrence : usage répété attendu (au moins quelques fois par trimestre, pas one-shot)
  • Output identifiable : on doit pouvoir dire « ce skill produit X »
  • Méthodologie commune : on veut que toutes les invocations produisent un output cohérent en style et structure
  • Tooling cadré : allowed-tools dans le frontmatter, pas de liberté tooling totale

3. Anti-patterns (à NE PAS créer en skill / command)

  • One-shot ou rarissime : un prompt direct suffit
  • Trivial : 3 lignes de bash → script shell ou alias, pas skill
  • Sans méthodologie commune : chacun aborde le sujet à sa façon → reste informel
  • Trop générique : un skill qui « fait n'importe quoi sur n'importe quoi » dilue la valeur

4. Distinction skill (.claude/skills/) vs command (.claude/commands/)

  • Skill : description-driven, le LLM décide d'invoquer selon le contexte (frontmatter description rich)
  • Command : explicit-driven, le user tape /<nom> (frontmatter description courte, déclenchement contrôlé)
  • Critère de choix : si l'invocation gagne à être explicite (« je veux ça maintenant »), c'est une command. Si elle gagne à être contextuelle (« si je suis en train de faire X, propose-le-moi »), c'est un skill.

5. Catalogue partagé

Le catalogue complet des skills et commands bricks-OS vit dans wiki/operations/skills-catalogue.md. À chaque création / suppression, mettre à jour le catalogue dans la même PR.

CLAUDE.md garde uniquement une mention minimaliste qui pointe vers le catalogue et cet ADR — pour ne pas dupliquer l'info et garder le fichier sous 200 lignes.

6. Processus de création

Toute proposition de nouveau skill / command :

  • Passe par une PR au format ADR-010
  • La description PR contient explicitement : (a) la pratique, (b) l'output, (c) la méthodologie, (d) la récurrence attendue
  • L'auteur ajoute l'autre en reviewer (critère 2 de l'ADR-010 : « change le way of working »)
  • Le catalogue wiki/operations/skills-catalogue.md est mis à jour dans la même PR

7. Audit trimestriel des skills morts

À chaque fin de trimestre, audit léger du catalogue :

  • Pour chaque skill / command, vérifier qu'il a été utilisé ≥ 1 fois sur les 3 derniers mois
  • Si non utilisé → candidat à archivage (déplacement dans .claude/skills/.archive/ ou .claude/commands/.archive/)
  • L'archivage passe par une PR au format ADR-010 ; pas de suppression silencieuse

8. Convention multi-IDE (Claude Code × Cursor)

Différée : le sujet « symlink vs duplication entre .claude/ et .cursor/ » sera traité dans un ADR ultérieur quand le besoin se présentera concrètement (ex. premier skill à porter cross-IDE).

Aujourd'hui : - Les .claude/skills/ et .claude/commands/ vivent côté Claude Code uniquement (Nicolas) - Les .cursor/automations/ et .cursor/rules/ vivent côté Cursor uniquement (Romain) - Asymétrie assumée — chaque IDE a ses gestes outillés - Le catalogue wiki/operations/skills-catalogue.md recense les deux univers pour la visibilité partagée

Rationale

  • Mémoire collective : un catalogue partagé tenu dans wiki/operations/skills-catalogue.md rend les pratiques visibles à tous les contributeurs (Nicolas, Romain, futurs).
  • Pas de duplication silencieuse : avant de créer, on vérifie le catalogue.
  • Distinction skill / command explicite : on évite de transformer en skill ce qui mérite juste une command (et inversement).
  • Hygiène par audit : on évite l'accumulation de skills morts qui polluent la lecture.
  • Asymétrie IDE assumée : on ne force pas une convergence prématurée Claude / Cursor.

Alternatives écartées

  • Tout transformer en skill : dilue la valeur des skills utiles, charge le catalogue inutilement.
  • Pas de convention (statu quo) : drift inévitable, doublons silencieux dès que ≥ 2 contributeurs créent en parallèle.
  • Tableau complet maintenu dans CLAUDE.md : déjà commencé dans la PR #13, mais fait grossir le fichier au-delà des 200 lignes. Préférer un fichier dédié dans le wiki.
  • Convergence forcée Claude / Cursor maintenant : prématuré sans cas d'usage qui le justifie ; on attend le premier vrai besoin.

Conséquences

Ce qui change

  1. Nouveau fichier wiki/operations/skills-catalogue.md qui tient le catalogue complet (4 skills + 7 commands à date, plus les artefacts Cursor pour visibilité)
  2. CLAUDE.md § Skills est remplacé par une mention minimaliste pointant vers le catalogue et cet ADR
  3. Audit trimestriel léger ajouté au rituel de revue (à intégrer dans la routine S26 fin Q2)

Ce qu'il faut faire

  • À chaque création d'un skill / command : PR + reviewer + maj catalogue
  • Fin de trimestre : passer le catalogue en revue, archiver les skills non utilisés

Ce qu'il faut éviter

  • Créer un skill « parce que c'est cool » sans méthodologie commune en vue
  • Garder un skill mort dans le catalogue sans questionnement
  • Maintenir le tableau dans CLAUDE.md (faire grossir le fichier)

Verbatims

« Tout n'a pas vocation à être transformé en skills mais pense que la bonne définition pour l'usage d'un skill c'est de se dire que c'est une pratique avec un output clair + sur lequel on veut appliquer une méthodologie précise et commune. Ex : scanner les feedbacks collectés depuis l'outil d'analyse, analyser la trace LangSmith d'une analyse, ajouter un ADR. » — Nicolas, 13/05/2026

« Je veux également qu'on puisse documenter la liste des skills et commandes partagées entre Romain et moi. On doit avoir une mention minimaliste (une ligne dans CLAUDE.md qui rappelle là où il y a des skills et commandes disponibles déjà existants). » — Nicolas, 13/05/2026

Voir aussi

  • ADR-010 — Convention PR + review croisée (s'applique aux PR de création de skill)
  • wiki/operations/skills-catalogue.md — catalogue complet
  • .claude/skills/add-adr/SKILL.md — exemple canonique de skill outillé

Sources