Skillcrew : les skills de votre équipe, dans tous les agents, toujours à jour

Dans mon dernier article, je racontais comment une équipe a écrit sa première skill : démarrer un projet Symfony à ses standards, toujours de la même façon. J’avais terminé sur une phrase un peu rapide : « elle sera diffusée par le marketplace de skills de l’équipe, versionnée et relue comme le reste du code ».

Dans les faits, c’est là que les ennuis commencent. Une skill d’équipe, ce n’est pas un fichier qu’on envoie sur Slack. Il faut qu’elle arrive chez tout le monde, quel que soit l’agent utilisé, qu’elle soit mise à jour quand elle s’améliore, et qu’on puisse la retirer quand elle pose problème. Je n’ai pas trouvé d’outil qui fasse tout ça, alors je l’ai écrit : Skillcrew, un outil en ligne de commande open source (licence MIT).

Dans cet article, je vous présente l’outil, puis on fait une démo complète, de la création du registre jusqu’à la désinstallation. Tout se refait en une demi-heure avec un compte GitHub.

Le code est sur GitHub et la documentation sur skillcrew.yoandev.co. Le projet est jeune (v0.1.0) : il fonctionne de bout en bout, mais des changements incompatibles sont possibles avant la v1.

---

Le problème : des skills qui ne se diffusent pas

Une Agent Skill, c’est un dossier avec un fichier SKILL.md : un nom, une description qui dit quand l’utiliser, puis des instructions. L’agent la charge quand la tâche s’y prête. Le format est devenu un standard, lu par Claude Code, Codex, GitHub Copilot, Cursor, Gemini CLI et d’autres.

Écrire une skill est facile. La faire vivre dans une équipe l’est beaucoup moins :

• Les copies divergent. Chacun copie la skill à la main, la modifie un peu, et la correction faite trois semaines plus tard n’arrive jamais chez personne.
• Chaque agent a son dossier. Claude Code lit ~/.claude/skills, la plupart des autres ~/.agents/skills. Dans une équipe où cohabitent plusieurs agents, il faut penser à tous.
• Personne ne gouverne. Impossible de garantir que tout le monde a la skill de revue de sécurité, de proposer une skill réservée au backend, ou de retirer en urgence une skill qui fait des bêtises.
• Les mises à jour sont manuelles. Les outils existants demandent de lancer une commande update. Personne ne le fait.

Le marketplace de plugins de Claude Code règle une partie du problème, mais seulement pour Claude Code. Les gestionnaires de paquets de skills couvrent tous les agents, mais sans gouvernance ni mise à jour automatique.

Skillcrew en deux minutes

Skillcrew part d’un principe simple : un seul dépôt Git pour toute l’organisation, le registre, et aucune action à faire côté développeurs une fois qu’ils l’ont rejoint.

 Registre (un dépôt Git : marketplace Claude Code + skillcrew.yaml)
      │  git fetch (avec vos identifiants Git habituels)
      ▼
 skillcrew sync ── lancé au démarrage de chaque session d'agent (hook) + toutes les heures (timer)
      │
      ├─▶ ~/.agents/skills/<skill>    copies réelles (Codex, Copilot, Cursor, Gemini CLI…)
      └─▶ ~/.claude/skills/<skill>    liens symboliques (Claude Code)

Le registre

Le registre a la structure d’un marketplace Claude Code : des plugins, et dans chaque plugin des skills. Il reste donc utilisable comme marketplace dans Claude Code. On y ajoute un seul fichier, skillcrew.yaml, qui décide qui reçoit quoi.

Chaque skill a un identifiant plugin:skill, la notation de Claude Code : la skill plugins/git/skills/commit-message/SKILL.md s’appelle git:commit-message.

Cinq statuts

Ces statuts se définissent pour toute l’organisation, puis par équipe. Une équipe peut durcir une règle (rendre obligatoire une skill disponible), jamais l’assouplir. Chaque personne rejoint la ou les équipes dont elle fait partie.

La synchronisation, sans y penser

skillcrew init installe un hook de démarrage de session dans chaque agent détecté, plus un timer utilisateur (launchd sur macOS, systemd sur Linux) qui tourne toutes les heures. Pas de démon, pas de droits administrateur.

Le hook ne fait jamais attendre l’agent : il rend la main immédiatement et lance la synchronisation en arrière-plan si la dernière date de plus d’une minute. Si le registre est injoignable, Skillcrew garde la dernière version récupérée : tout continue de fonctionner hors ligne.

La version de l’équipe fait foi

Si vous modifiez une skill d’équipe sur votre machine, la synchronisation suivante sauvegarde votre version et remet celle de l’équipe. Pour faire évoluer une skill, on passe par skillcrew propose, qui ouvre une pull request sur le registre. Les skills partagées restent relues comme le reste du code.

Vos skills personnelles, elles, ne sont jamais touchées : Skillcrew ne modifie que ce qu’il a lui-même installé.

Et la sécurité ?

Un outil qui pousse du contenu sur toutes les machines d’une équipe doit être irréprochable. Les points principaux :

• Skillcrew n’exécute rien venant du registre : il copie des fichiers, rien de plus.
• Aucun secret stocké : l’authentification passe par vos identifiants Git existants (clé SSH, gh auth), et les URL contenant un mot de passe sont refusées.
• Mises à jour atomiques : chaque skill est préparée à part puis échangée d’un coup, aucun agent ne lit une skill à moitié écrite.
• Le registre est la racine de confiance : protégez sa branche principale avec des revues obligatoires, comme du code de production.

Le modèle complet est décrit dans la documentation.

---

La démo, de A à Z

On va jouer les deux rôles : d’abord l’administrateur ou l’administratrice qui crée le registre de l’organisation fictive acme, puis le développeur ou la développeuse qui le rejoint. Au programme :

1. Installer Skillcrew
2. Créer le registre
3. Ajouter deux skills, avec leurs statuts
4. Écrire les instructions des skills
5. Valider et publier
6. Rejoindre l’organisation
7. Utiliser les skills dans Claude Code
8. Publier une mise à jour
9. Modifier une skill en local, puis la proposer
10. Bloquer une skill
11. Diagnostiquer et désinstaller

Prérequis

• macOS ou Linux (sous Windows, WSL2)
• git
• un compte GitHub et la CLI gh, connectée (gh auth login)
• une clé SSH déclarée sur votre compte GitHub
• au moins un agent IA installé : j’utilise Claude Code, mais n’importe quel agent qui lit ~/.agents/skills fait l’affaire

Pour copier-coller les commandes telles quelles, définissez votre nom d’utilisateur GitHub :

export GH_USER=votre-compte-github

Attention : skillcrew init modifie votre vraie configuration (hooks des agents, timer). C’est voulu, c’est tout l’intérêt de l’outil, et l’étape 11 remet tout en ordre. Si vous préférez une démo sans aucun effet sur votre machine, ajoutez --no-hooks --no-timer à skillcrew init et lancez skillcrew sync à la main.

Étape 1 : installer Skillcrew

Skillcrew est un binaire unique, écrit en Go.

brew install yoanbernabeu/tap/skillcrew

Sans Homebrew :

curl -fsSL https://raw.githubusercontent.com/yoanbernabeu/skillcrew/main/install.sh | sh

Le script vérifie le binaire téléchargé avec les sommes de contrôle de la release (et leur signature Sigstore si cosign est installé). On vérifie :

$ skillcrew --version

Étape 2 : créer le registre

On commence côté administration, dans un dépôt vide :

$ mkdir ~/acme-skills && cd ~/acme-skills && git init
$ skillcrew registry init --org acme
Created a new Skillcrew registry.
  + .claude-plugin/marketplace.json
  + .github/workflows/validate.yml
  + AGENTS.md
  + CLAUDE.md
  + README.md
  + plugins/example/.claude-plugin/plugin.json
  + plugins/example/skills/hello-world/SKILL.md
  + skillcrew.yaml
Add skills with "skillcrew skill new <plugin:skill>", then commit and push.

On obtient un marketplace Claude Code avec un plugin d’exemple, le fichier de gouvernance, un README pour l’équipe, un workflow GitHub Actions qui valide le registre à chaque pull request, et un AGENTS.md (importé par CLAUDE.md) qui explique aux agents IA comment faire évoluer le registre.

Vous avez déjà un marketplace Claude Code ? Lancez la même commande à l’intérieur : elle se contente d’ajouter le skillcrew.yaml, avec toutes les skills en available.

Étape 3 : ajouter deux skills, avec leurs statuts

Une skill pour tout le monde, sur les messages de commit, et une pour l’équipe backend, sur les nouveaux projets Symfony. Une commande par skill :

$ skillcrew skill new git:commit-message --status required \
    --description "Writes commit messages following the team convention. Use it whenever you create a git commit."
Created skill git:commit-message.
  + plugins/git/.claude-plugin/plugin.json
  + plugins/git/skills/commit-message/SKILL.md
  ~ .claude-plugin/marketplace.json
  ~ skillcrew.yaml
Status: required for the organization.
Next: write the instructions in plugins/git/skills/commit-message/SKILL.md, run "skillcrew validate", then commit.

$ skillcrew skill new symfony:new-project --status required --team backend \
    --description "Creates a new Symfony project following the team standards. Use it when the user wants to start a new Symfony application."
Created skill symfony:new-project.
  + plugins/symfony/.claude-plugin/plugin.json
  + plugins/symfony/skills/new-project/SKILL.md
  ~ .claude-plugin/marketplace.json
  ~ skillcrew.yaml
  - team "backend" created in skillcrew.yaml
Status: required for team backend, available (the registry default) for the organization.
Next: write the instructions in plugins/symfony/skills/new-project/SKILL.md, run "skillcrew validate", then commit.

skill new s’occupe de toute la plomberie : le dossier de la skill et son SKILL.md, le plugin et sa déclaration dans le marketplace quand il est nouveau, et le statut dans skillcrew.yaml. La description est la ligne la plus importante d’une skill : c’est elle que l’agent lit pour décider s’il doit la charger.

Le fichier de gouvernance contient maintenant (sans les commentaires) :

org: acme
default: available

skills:
  example:hello-world: recommended
  git:commit-message: required

teams:
  backend:
    skills:
      symfony:new-project: required

En clair : tout le monde reçoit git:commit-message sans pouvoir la désactiver, et les membres de l’équipe backend reçoivent en plus symfony:new-project. Une équipe peut durcir une règle, jamais l’assouplir : skill new refuse par exemple de rendre recommended pour une équipe une skill obligatoire pour toute l’organisation.

Pour la suite de la démo, on met la skill d’exemple dans le catalogue au lieu de l’installer chez tout le monde. Les changements de statut se font directement dans skillcrew.yaml :

sed -i.bak 's/example:hello-world: recommended/example:hello-world: available/' skillcrew.yaml && rm skillcrew.yaml.bak

Étape 4 : écrire les instructions des skills

Il reste le vrai travail : le contenu. Le SKILL.md généré contient le frontmatter et un emplacement à remplir :

---
name: commit-message
description: Writes commit messages following the team convention. Use it whenever you create a git commit.
---

# Commit message

TODO: write the instructions the agent follows when it uses this skill.
Keep them short and specific. Put long reference material in other files of
this directory and say when to read them.

Deux options. La première : ouvrir votre agent dans le registre et lui demander d’écrire les instructions. Il lit l’AGENTS.md généré, qui lui donne les règles du registre, et s’il dispose d’une skill d’aide à l’écriture de skills, comme le skill-creator d’Anthropic, il s’en sert pour le contenu. La seconde : les écrire vous-même. Pour la démo, voici les deux fichiers complets :

cat > plugins/git/skills/commit-message/SKILL.md <<'EOF'
---
name: commit-message
description: Writes commit messages following the team convention. Use it whenever you create a git commit.
---

# Commit message

- Subject in English, imperative mood, 72 characters max.
- Start with a type: feat, fix, docs, refactor, test, chore.
- Reference the ticket at the end of the body: `Refs #123`.
EOF

cat > plugins/symfony/skills/new-project/SKILL.md <<'EOF'
---
name: new-project
description: Creates a new Symfony project following the team standards. Use it when the user wants to start a new Symfony application.
---

# New Symfony project

1. `symfony new <name> --webapp`
2. Add PHPStan at level 8 and PHP-CS-Fixer with the @Symfony rules.
3. Add a `compose.yaml` with PostgreSQL.
4. Write a README with the install steps.
EOF

Si vous oubliez une skill, skillcrew validate vous le rappelle : il signale tout SKILL.md qui contient encore le TODO.

Étape 5 : valider et publier

skillcrew validate vérifie que chaque identifiant existe, que les noms ne se télescopent pas et qu’aucune équipe n’assouplit une règle de l’organisation. C’est ce que lance le workflow de CI généré à l’étape 2.

$ skillcrew validate
Registry acme is valid: 3 skills.

On publie dans un dépôt privé :

git add -A && git commit -m "Create the skills registry"
gh repo create $GH_USER/acme-skills --private --source . --push

N’importe quel hébergement Git fonctionne (GitLab, serveur auto-hébergé, Azure DevOps…). Les développeurs n’ont besoin que d’un accès en lecture, avec leurs identifiants habituels.

Sur un vrai registre, c’est le moment de protéger la branche main avec des revues obligatoires : tout ce qui y est fusionné arrive sur toutes les machines.

Étape 6 : rejoindre l’organisation

On change de casquette. Côté développeur, tout tient en une commande :

$ cd ~
$ skillcrew init git@github.com:$GH_USER/acme-skills.git --team backend
Cloning git@github.com:votre-compte-github/acme-skills.git...
Joined organization acme (registry git@github.com:votre-compte-github/acme-skills.git, branch main).
  ✓ claude-code: session-start hook installed
  ✓ codex: session-start hook installed
  ✓ fallback timer installed (every 1h0m0s)
Synced registry 3e01546421c7:
  + commit-message (installed)
  + new-project (installed)
Start a new agent session to load the skills. "skillcrew list --available" shows the skills you can add.

J’utilise une URL SSH, qui passe par votre clé SSH habituelle. La forme courte github.com/$GH_USER/acme-skills fonctionne aussi : elle devient une URL HTTPS, authentifiée par votre credential helper Git (gh auth setup-git par exemple).

La liste des hooks dépend des agents installés sur votre machine. Les deux skills obligatoires pour un membre de l’équipe backend sont déjà là. On regarde ce qu’on a :

$ skillcrew status
Organization  acme
Registry      git@github.com:votre-compte-github/acme-skills.git (main @ 3e01546421c7)
Teams         backend
Last sync     2026-10-11 15:05

SKILL           ID                   STATUS    STATE  VERSION
commit-message  git:commit-message   required  ok     3e01546421c7
new-project     symfony:new-project  required  ok     3e01546421c7

Les skills sont copiées dans ~/.agents/skills, et Claude Code les voit par des liens symboliques :

$ ls -l ~/.claude/skills
commit-message -> /Users/vous/.agents/skills/commit-message
new-project -> /Users/vous/.agents/skills/new-project

Ce qui reste disponible dans le catalogue :

$ skillcrew list --available
SKILL        ID                   STATUS     STATE  VERSION
hello-world  example:hello-world  available  -      -
$ skillcrew install hello-world
Installed example:hello-world.
Synced registry 3e01546421c7:
  + hello-world (installed)

Et ce qui n’est pas négociable :

$ skillcrew disable commit-message
Error: git:commit-message is required for you; it cannot be disabled or removed

Les équipes se gèrent tout aussi simplement :

$ skillcrew team list
TEAM     MEMBER
backend  joined

skillcrew team join et skillcrew team leave ajoutent ou retirent les skills de l’équipe sur le champ.

Étape 7 : utiliser les skills dans Claude Code

On ouvre une nouvelle session Claude Code dans n’importe quel projet. La commande /skills liste les skills chargées : commit-message, new-project et hello-world y apparaissent.

Pour les voir à l’œuvre, on fait une petite modification dans un dépôt et on demande à l’agent de la commiter. Il charge commit-message tout seul, grâce à sa description, et produit un message au format de l’équipe : type en préfixe, sujet à l’impératif, référence de ticket.

C’est le même résultat dans Codex, Copilot ou Cursor, qui lisent ~/.agents/skills.

Étape 8 : publier une mise à jour

L’équipe décide qu’aucun message de commit ne doit mentionner d’outil d’IA. Côté administration, dans le registre :

cd ~/acme-skills
echo "- Never mention AI tools in the commit message." >> plugins/git/skills/commit-message/SKILL.md
git commit -am "Forbid AI mentions in commit messages" && git push

Dans la vraie vie, ce changement passerait par une pull request relue et validée par la CI. Puis il n’y a rien à faire : la prochaine session d’agent, ou le timer dans l’heure, récupère la nouvelle version. Pour la démo, on n’attend pas :

$ skillcrew sync
Synced registry ba83dd42c56b:
  ~ commit-message (updated)
$ skillcrew sync
Skills are up to date (registry ba83dd42c56b).

Claude Code recharge les skills à chaud ; les autres agents voient la mise à jour à leur session suivante.

Étape 9 : modifier une skill en local, puis la proposer

Maintenant, on joue celui ou celle qui préfère faire à sa façon et modifie la skill directement sur sa machine :

$ echo "- Use emojis." >> ~/.agents/skills/commit-message/SKILL.md
$ skillcrew status
...
SKILL           ID                   STATUS     STATE     VERSION
hello-world     example:hello-world  available  ok        ba83dd42c56b
commit-message  git:commit-message   required   modified  ba83dd42c56b
new-project     symfony:new-project  required   ok        ba83dd42c56b

À la synchronisation suivante, la version de l’équipe revient. Rien n’est perdu pour autant :

$ skillcrew sync
Synced registry ba83dd42c56b:
  ! local changes to commit-message were backed up to /Users/vous/.skillcrew/backups/commit-message; the team version is restored (use "skillcrew propose commit-message" to suggest them)

Si l’idée est bonne, elle doit profiter à toute l’équipe. On la propose :

$ skillcrew propose commit-message --title "Allow emojis in commit messages"
Pull request opened: https://github.com/votre-compte-github/acme-skills/pull/1

Skillcrew a poussé une branche avec la modification (prise dans la sauvegarde, puisque la synchronisation était passée avant) et ouvert la pull request avec gh. Elle suit ensuite le chemin habituel : revue, CI, fusion, puis diffusion automatique. Il faut pour cela un droit de push sur le registre.

skillcrew propose ma-skill --plugin git fonctionne aussi pour proposer l’une de vos skills personnelles à l’équipe.

Étape 10 : bloquer une skill

Imaginons que hello-world se mette à produire n’importe quoi. Côté administration, on la bloque :

cd ~/acme-skills
sed -i.bak 's/example:hello-world: available/example:hello-world: blocked/' skillcrew.yaml && rm skillcrew.yaml.bak
skillcrew validate
git commit -am "Block hello-world" && git push

À la synchronisation suivante, elle disparaît de toutes les machines :

$ skillcrew sync
Synced registry 32b6eb22a151:
  - hello-world (removed: blocked by your organization)
$ skillcrew install hello-world
Error: example:hello-world is blocked by your organization; it is never installed

validate ne fait qu’avertir sur le contenu d’une skill bloquée : on peut couper une skill cassée sans avoir à la corriger d’abord.

Étape 11 : diagnostiquer et désinstaller

skillcrew doctor vérifie git, le registre, la dernière synchronisation, les hooks de chaque agent, le timer et les skills installées :

$ skillcrew doctor
✓ git          git found
✓ registry     git@github.com:votre-compte-github/acme-skills.git (main @ 32b6eb22a151)
✓ sync         last sync on 2026-10-11 15:05
✓ claude-code  session-start hook installed
✓ codex        session-start hook installed
✓ timer        fallback timer installed
✓ skills       2 team skills installed
✓ symlinks     team skills linked from /Users/vous/.claude/skills

Pour remettre votre machine dans son état initial :

$ skillcrew uninstall --yes
Skillcrew is uninstalled. Backups of your local changes are kept in /Users/vous/.skillcrew/backups.

Les hooks, le timer, les skills d’équipe et ~/.skillcrew disparaissent ; vos skills personnelles restent en place, et celles qu’une skill d’équipe avait remplacées sont restaurées. Il ne reste qu’à supprimer le registre de démo et le binaire :

gh repo delete $GH_USER/acme-skills   # demande le scope delete_repo : gh auth refresh -s delete_repo
rm -rf ~/acme-skills ~/.skillcrew
brew uninstall skillcrew

---

Ce qu’il faut retenir

Côté administration, un dépôt Git et un fichier YAML. Côté développeurs, une commande, puis plus rien : les skills arrivent, se mettent à jour et disparaissent toutes seules, dans tous les agents. Entre les deux, le circuit habituel d’une équipe de développement : pull request, revue, CI.

Ce que Skillcrew ne fait pas, volontairement : les skills propres à un projet. Celles-là se commitent dans le projet (.agents/skills/, .claude/skills/), et Git les distribue déjà très bien. Skillcrew s’occupe des skills de niveau utilisateur, celles qui suivent une personne d’un projet à l’autre.

Le projet est jeune, et les agents changent vite : leurs dossiers de skills et leurs formats de hooks bougent souvent. Claude Code et OpenCode sont testés en conditions réelles, les autres agents à des degrés divers (le tableau à jour est dans la documentation). Si vous essayez Skillcrew avec votre équipe, vos retours m’intéressent : les issues et les pull requests sont ouvertes.

Et si vous en êtes plutôt à vous demander quelles skills écrire, ou comment faire travailler une équipe avec des agents, on peut en parler.