Aller directement au contenu
LUNDI, NOVEMBRE 16, 2026ACTUALITÉS TECHNIQUES INDÉPENDANTES, TESTS ET GUIDES PRATIQUES
À PROPOS
DERNIÈRES NOUVELLES /

Agent Skills et serveurs MCP expliqués : comment les installer, les mettre à jour et les réparer dans OpenCode, Claude Code, Codex et autres agents IA

LIRE LE GUIDE
Agents IAGM / 997

Agent Skills et serveurs MCP expliqués : comment les installer, les mettre à jour et les réparer dans OpenCode, Claude Code, Codex et autres agents IA

Agent Skills et serveurs MCP expliqués simplement : installer, mettre à jour et corriger dans OpenCode, Claude Code, Codex et plus, avec la CLI npx skills.

Agent skills and MCP servers explained: a tech.grahammiranda.com title card with SKILL.md, npx skills, MCP servers and .agents/skills, and a terminal running npx skills check and opencode mcp add

Un agent de codage IA qui vient d’être installé, c’est comme une nouvelle recrue brillante à son premier matin. Il sait raisonner, écrire du code et lancer des commandes, mais il ne sait pas comment ton équipe travaille, et il n’a aucune clé pour accéder à tes systèmes. Les agent skills et les serveurs MCP comblent exactement ces deux lacunes. Un skill est un guide de procédure écrit que l’agent sort de l’étagère quand une tâche en a besoin. Un serveur MCP est un trousseau de clés : un petit programme qui permet à l’agent d’utiliser quelque chose qu’il ne pouvait pas atteindre auparavant, comme tes tickets GitHub, un vrai navigateur ou une documentation à jour.

Ce guide explique les deux en langage clair, puis te montre comment les installer, les mettre à jour, les supprimer et les dépanner dans OpenCode, Claude Code, Codex, Gemini CLI, Cursor, GitHub Copilot et Hermes Agent. L'essentiel fonctionne de la même manière partout, parce que les deux sont désormais des standards ouverts. Côté skills, un petit outil en ligne de commande relie le tout, npx skills, et je vais le détailler commande par commande.

Je ne suis pas développeur de formation. Je dirige une petite entreprise informatique en Allemagne et je construis des logiciels avec des agents IA, donc j’ai appris l’essentiel de ce contenu comme tu vas probablement le faire : en cassant des choses. La partie 6 est tirée de mes propres sessions de terminal sur un Mac et un Raspberry Pi, y compris le jour où l’outil m’a annoncé que tous mes skills étaient à jour alors qu’il n’avait pas réussi à en vérifier un seul.

Tout ce qui suit a été vérifié par rapport à la documentation officielle de chaque agent et, pour la compétences CLI, par rapport au code source publié des versions 1.5.18 à 1.8.1, le 15 novembre 2026. Ces outils changent chaque semaine : la CLI a publié deux versions rien que cette semaine, et OpenCode est passé en 2.3.0 le 13 novembre. Les numéros de version et les comportements sont signalés là où ils risquent de bouger. Vérifie-les avant de t’y fier.

Mention légale : Aucune entreprise mentionnée dans cet article ne l'a sponsorisé, relu ou approuvé, et il ne contient aucun lien d'affiliation. Les produits sont simplement nommés dans le texte ; les images utilisent mes propres logos.


TL;DR — Agent Skills et serveurs MCP en dix points

  • Un skill est un dossier avec un SKILL.md fichier: un nom et une description en haut, les instructions en dessous, et éventuellement des scripts ou des fichiers de référence. Les agents ne lisent que la description tant qu’une tâche n’a pas besoin du skill, donc un skill inutilisé coûte environ 100 tokens de l’attention de l’agent.
  • Un serveur MCP donne à l'agent de nouveaux outils, comme GitHub, un navigateur ou une documentation en direct. Les descriptions d'outils peuvent être envoyées avec chaque requête, alors ne connecte que les serveurs que tu utilises. Claude Code les reporte désormais jusqu'au moment où ils sont nécessaires, et OpenCode les regroupe par serveur.
  • La règle empirique : les règles maison valables pour chaque tâche vont dans AGENTS.md; le savoir-faire nécessaire à certaines tâches devient un skill ; l'accès en direct à un système demande un serveur MCP ; et si un bon outil en ligne de commande existe déjà, un skill qui apprend à l'agent à s'en servir est souvent moins coûteux qu'un serveur.
  • Les deux sont des standards ouverts au sein de l’Agentic AI Foundation de la Linux Foundation : MCP depuis décembre 2025, Agent Skills depuis le 22 octobre 2026. Un skill écrit pour un agent fonctionne généralement dans les autres.
  • .agents/skills est le dossier partagé. Codex, OpenCode, Cursor, Gemini CLI et GitHub Copilot lisent tous .agents/skills dans un projet et ~/.agents/skills dans ton dossier personnel. Claude Code ne lit que .claude/skills, et Hermes Agent lit ~/.hermes/skills ainsi que tous les dossiers que tu ajoutes.
  • npx skills est le npm des skills. La CLI open source de Vercel (version 1.8.1) installe les skills dans 79 agents : npx skills add owner/repo, -g pour chaque projet, -a opencode -a claude-code pour choisir les agents, npx skills ls pour lister et npx skills remove pour désinstaller.
  • Pour voir si tes skills sont à jour, lance npx skills@latest check. Depuis la version 1.7.5 (2 novembre 2026), il ne fait que signaler ; npx skills update installe. Dans les versions antérieures, check lançait discrètement la mise à jour.
  • Ne te fie jamais à la coche verte toute seule. Quand la limite de 60 requêtes anonymes par heure de GitHub bloquait chaque vérification sur mon Mac, la CLI affichait quand même “Tous les skills globaux sont à jour”. Lance gh auth login ou définis GITHUB_TOKEN, et lis les lignes ✗.
  • N'utilise jamais sudo avec les skills ou les agents, et ne lance pas la CLI depuis ton dossier personnel. Root possède un dossier personnel séparé, donc sudo crée un deuxième magasin de skills, invisible ; et depuis ~ la CLI prend ton dossier personnel pour un projet.
  • Traite les skills et les serveurs MCP comme des logiciels que tu installes. Un audit de février 2026 portant sur 3 984 skills publics a trouvé des failles de sécurité dans 36,82 % d'entre eux et confirmé des charges malveillantes dans 76. Lis avant d'installer, privilégie les skills des créateurs de l'outil lui-même, verrouille les versions et garde les outils risqués en mode “ask”.

Les quatre briques de base en un coup d'œil

Brique de base Ce que c'est, en une ligne Vois-le comme Quand l'agent le lit Combien ça coûte Exemple
AGENTS.md (CLAUDE.md dans Claude Code) Un fichier Markdown avec les règles internes d'un projet Le manuel de l'équipe Au début de chaque session, en entier Toute sa longueur, à chaque requête “Utilise l'orthographe britannique. Lance les tests avant de dire que tu as fini.”
Compétence Un dossier avec une SKILL.md recette, plus des scripts et des références facultatifs Une fiche recette dans un classeur Le nom et la description au début ; la recette complète seulement quand une tâche en a besoin Environ 100 tokens par compétence tant qu’elle n’est pas utilisée “Comment nous rédigeons les notes de version”
Serveur MCP Un petit programme qui donne de nouveaux outils à l’agent Un jeu de clés et d’adaptateurs La liste des outils au début (sauf si ton agent la diffère) ; chaque outil au moment où il est appelé Les descriptions des outils, souvent à chaque requête Les issues GitHub, un vrai navigateur, la documentation à jour des bibliothèques
Plugin ou extension Un ensemble de compétences, de serveurs MCP et parfois de hooks Un kit de bienvenue Dépend de ce qu’il y a dedans La somme de ses parties Superpowers, un kit de démarrage d’un éditeur
Les compétences d'agents et les serveurs MCP expliqués : AGENTS.md comme manuel toujours chargé, les compétences comme des fiches recettes chargées à la demande, les serveurs MCP comme des outils pour GitHub, un navigateur et la documentation en direct, et les plugins comme des ensembles
Quatre briques, un agent. Le manuel est toujours ouvert, les fiches recettes sortent quand il le faut, et les serveurs MCP sont les clés de tout ce qui se trouve hors du terminal.

Table des matières


Partie 1 — Agent Skills et serveurs MCP en langage clair

L’image de la nouvelle recrue

Imagine que tu embauches quelqu’un de brillant. Le premier jour, tu lui donnerais trois choses : un petit manuel avec les règles que tout le monde suit, un classeur de recettes pour les tâches que ton équipe fait à sa façon, et un jeu de clés et de badges pour accéder aux systèmes dont il a besoin. Tu remettrais aussi à certaines personnes un kit de bienvenue qui regroupe quelques recettes et quelques clés.

Les agents IA ont besoin exactement de la même chose, et chaque brique a désormais un nom standard :

  • Le manuel est AGENTS.md (Claude Code appelle sa version CLAUDE.md).
  • Les recettes sont des compétences.
  • Les clés sont des serveurs MCP.
  • Les kits de bienvenue sont des plugins, appelés extensions dans certains agents.

Le reste de ce guide porte sur les recettes et les clés, car c’est là que se concentre l’essentiel de la confusion.

Ce qu’est une compétence

Une compétence est un dossier. À l’intérieur se trouve un fichier obligatoire, SKILL.md, et éventuellement tout ce dont la tâche a besoin :

release-notes/
├── SKILL.md          ← requis : nom, description, instructions
├── references/       ← facultatif : documents plus longs, lus seulement si nécessaire
├── scripts/          ← facultatif : code que l’agent peut exécuter
└── assets/           ← facultatif : modèles, images, fichiers de données

Le SKILL.md fichier comporte un court en-tête entre deux --- lignes (cet en-tête s’appelle front matter), suivi d’instructions simples :

---
name: release-notes
description: Rédige les notes "Nouveautés" de l’App Store à partir des commits récents. À utiliser quand on demande des notes de version, un journal des modifications ou un texte "quoi de neuf".
---

# Notes de version

1. Lis les commits depuis le dernier tag git.
2. Ne garde que les changements qu’un utilisateur remarquerait.
3. Rédige trois à cinq puces courtes en anglais simple, sous 400 caractères au total.

La norme ouverte exige deux champs. Le nom ne peut contenir que des lettres minuscules, des chiffres et des traits d’union, doit faire au plus 64 caractères et correspondre au nom du dossier. La description peut faire jusqu’à 1 024 caractères et doit indiquer ce que fait la compétence et quand l’utiliser, car c’est la description qui permet à l’agent de décider s’il ouvre la compétence ou non.

Pourquoi tu peux installer des dizaines de compétences : l’astuce des trois couches

Les compétences se chargent par couches, ce que la norme appelle la divulgation progressive. Pense à une étagère :

  1. Les quatrièmes de couverture. Au début d’une session, l’agent ne lit que le nom et la description de chaque compétence. La spécification prévoit environ 100 tokens par compétence. (Un token correspond à peu près à un mot court ou à une partie de mot ; c’est l’unité dans laquelle les modèles comptent leur mémoire de travail.)
  2. Le chapitre. Quand une tâche correspond à une description, l’agent lit l’intégralité du SKILL.md. La norme recommande de le garder sous 5 000 tokens et 500 lignes.
  3. L’annexe. Les fichiers de référence et les scripts ne se chargent que si les instructions y renvoient.

C’est pourquoi cent compétences inutilisées coûtent bien moins qu’un long règlement. Ce n’est pas gratuit pour autant : les descriptions s’additionnent, et les agents imposent des limites. Codex limite sa liste initiale de compétences à 2 % de la mémoire de travail du modèle (8 000 caractères s’il ne peut pas en déterminer la taille), et Claude Code tronque le texte de présentation de chaque compétence à 1 536 caractères. Installe ce que tu utiliseras.

Ce qu’est un serveur MCP

MCP, le Model Context Protocol, est une norme ouverte pour connecter les agents IA aux outils et aux données. Anthropic l’a présenté en novembre 2024 et l’a confié à la nouvelle Agentic AI Foundation de la Linux Foundation en décembre 2025, aux côtés d’AGENTS.md d’OpenAI et de goose de Block.

Un Serveur MCP est un petit programme qui dit à ton agent : “voici les outils que je propose”. Un serveur GitHub peut proposer create_issue et search_code; un serveur de navigateur propose navigate et take_screenshot; un serveur de documentation propose query_docs. Ton agent est le client MCP: il montre la liste au modèle, et quand le modèle veut utiliser un outil, l'agent vérifie tes permissions, demande au serveur de l'exécuter et renvoie le résultat.

Les serveurs sont de deux types :

  • Serveurs locaux tournent sur ton propre ordinateur. L'agent les démarre avec une commande comme npx @playwright/mcp@latest et communique avec eux via l’entrée et la sortie du programme (le nom technique est stdio).
  • Serveurs distants tournent sur les ordinateurs du fournisseur. Tu te connectes avec une adresse web, du type https://mcp.context7.com/mcp, et tu te connectes en général via ton navigateur ou en collant une clé API. Le nom technique de la connexion est Streamable HTTP.

Voici le piège. Chaque outil arrive avec un nom, une description et une liste de paramètres, écrits pour que le modèle les lise. À moins que ton agent ne les diffère, ces descriptions voyagent avec chaque requête, et vingt serveurs de dix outils chacun rendent chaque réponse plus lente, plus chère et moins ciblée. La partie 7 montre ce que fait chaque agent à ce sujet.

AGENTS.md et les plugins, en bref

AGENTS.md est un simple fichier Markdown à la racine de ton projet que l’agent lit au début de chaque session : le but du projet, ses commandes, ses règles non négociables. OpenCode, Codex, Cursor et GitHub Copilot le lisent directement. Claude Code lit CLAUDE.md à la place, et sa documentation suggère un CLAUDE.md qui importe simplement l'autre fichier avec une ligne du genre @AGENTS.md. Comme il est chargé à chaque fois, garde-le court et déplace tout ce qui est spécifique à une tâche dans des skills.

Plugins regroupent les autres éléments. Un plugin Claude Code peut contenir des skills, des sous-agents, des hooks (des scripts qui s'exécutent sur des événements) et des serveurs MCP et LSP. Codex, Cursor, GitHub Copilot CLI et Hermes Agent ont aussi des plugins, et Gemini CLI les appelle des extensions. La partie 9 les couvre.

Un lexique de poche

Terme Ce que cela signifie ici
Agent (ou harnais) Le programme auquel tu parles : OpenCode, Claude Code, Codex, etc. Il exécute le modèle, lit les fichiers et appelle des outils
Modèle L'IA qui réfléchit, comme GLM, Claude ou GPT
Fenêtre de contexte La mémoire de travail du modèle pour une requête. Tout ce que tu charges s'y dispute la place
Jeton L'unité dans laquelle les modèles comptent le texte ; environ un mot court ou une partie de mot
Compétence Un dossier avec une SKILL.md fichier qui apprend une tâche à l'agent
Front matter L'en-tête en haut de SKILL.md, entre deux --- lignes
Serveur MCP Un programme qui offre des outils à l'agent via le Model Context Protocol
Outil Une action qu'offre un serveur MCP, comme create_issue
stdio / Streamable HTTP Comment l'agent parle à un serveur local et à un serveur distant
OAuth Le flux “Se connecter avec…” dans ton navigateur, qui donne un jeton à l'agent sans que tu colles un mot de passe
Portée du projet / portée globale Installé pour un seul projet, ou pour tous les projets de ton ordinateur
Fichier de verrouillage Un reçu listant ce que tu as installé, depuis quelle source, et une empreinte de chaque skill
Lien symbolique Un raccourci vers un dossier. La CLI skills garde une seule copie réelle et y relie les agents

Partie 2 — Compétence, serveur MCP ou AGENTS.md ? Le test des cinq questions

Quand tu veux qu'un agent fasse quelque chose de mieux, pose ces questions dans l'ordre et arrête-toi au premier “oui”. La question 4 est la seule à avoir une relance :

  1. Cela doit-il valoir pour chaque tâche de ce projet ? Mets-le dans AGENTS.md. “Utilise l'orthographe britannique” et “lance les tests avant de dire que c'est fini” ont leur place ici.
  2. Cela doit-il être imposé, et pas seulement suggéré ? Utilise une règle de permission ou un hook. Les skills et AGENTS.md sont des instructions, et un modèle peut ignorer les instructions. “Ne jamais pousser sur main” a besoin d'une deny règle.
  3. Est-ce un savoir-faire qui ne compte que pour certaines tâches ? Écris ou installe un skill. Les routines de publication, les checklists de revue, ta voix de marque et ton flux de travail test-first sont tous des skills.
  4. L'agent a-t-il besoin d'un accès en direct à un système extérieur à ses fichiers ? Tes rapports de plantage derrière un identifiant, un navigateur qu'il peut piloter, une appli de gestion de projet. Si oui, pose la question 5 avant de sortir un serveur.
  5. Existe-t-il déjà un bon outil en ligne de commande pour ce système ? Si oui, un skill qui apprend cet outil à l'agent bat généralement un serveur : l'agent sait déjà exécuter des commandes, une CLI ne coûte rien tant qu'elle n'est pas utilisée, et sa sortie peut être filtrée avant d'atteindre le modèle. S'il n'existe pas de bonne CLI, si ton agent ne peut pas exécuter de commandes, ou si la tâche est interactive (comme piloter un navigateur), ajoute un serveur MCP.

Voici le test appliqué à dix envies du quotidien :

Tu veux que l'agent… Utilisation Pourquoi
Toujours utiliser l'orthographe britannique AGENTS.md Vaut pour toutes les tâches
Ne jamais pousser sur la branche main Une règle de permission Il faut l'imposer, pas le suggérer
Rédiger les notes de version comme tu les aimes Un skill Savoir-faire, nécessaire occasionnellement
Suivre un flux de travail test-first strict Un skill (Superpowers en propose un) Une procédure pour certaines tâches
Lire et classer les issues GitHub Un skill qui apprend gh, ou le serveur MCP de GitHub gh revient moins cher ; le serveur convient aux agents qui ne peuvent pas exécuter de commandes
Consulter la documentation actuelle d'une bibliothèque Un serveur MCP (Context7) ou sa CLI avec un skill (ctx7) Des données en direct dans les deux cas
Parcours ton application web et prends des captures d'écran Un serveur MCP (Playwright) Il a besoin d'un navigateur en cours d'exécution que l'agent peut piloter
Vérifie les plantages de la nuit dernière Un serveur MCP (Sentry) Des données en direct derrière un identifiant
Génère un rapport PDF à partir de ton modèle Une compétence avec un script et le modèle à l'intérieur assets/ Une procédure plus un outil intégré
Tiens à l'écart de tes .env fichiers Une règle de permission Il faut l'imposer

Les compétences et les serveurs MCP ne sont pas rivaux. Certaines des meilleures configurations les associent : une compétence explique quand et comment comment utiliser les outils d'un serveur, et le serveur fait le travail. Codex permet même à une compétence de déclarer les serveurs MCP dont elle dépend, dans un champ facultatif agents/openai.yaml fichier.

Compétence, serveur MCP ou AGENTS.md : un parcours en cinq questions qui envoie les règles valables pour toutes les tâches vers AGENTS.md, les règles imposées vers les permissions, le savoir-faire vers les compétences, et l'accès au système en direct vers une compétence CLI ou un serveur MCP
Cinq questions, posées dans l'ordre. La plupart des souhaits se révèlent être des compétences ; un serveur gagne sa place quand l'agent a besoin d'un accès en direct et qu'aucun bon outil en ligne de commande n'existe.

Partie 3 — Où chaque agent cherche ses compétences

Chaque agent regarde à deux types d'endroits. Dossiers de projet vivent dans ton dépôt, si bien que les compétences voyagent avec le code et que tes collègues en profitent aussi. Dossiers personnels vivent dans ton dossier personnel et s'appliquent à tous les projets de ton ordinateur. La plupart des outils appellent les installations personnelles globales.

En 2026, les agents se sont rejoints sur un emplacement partagé : .agents/skills dans un projet et ~/.agents/skills dans ton dossier personnel. Place une compétence là et la plupart des agents la trouvent sans travail supplémentaire.

Agent Dossiers de projet Dossiers personnels Appelle une compétence toi-même À savoir
OpenCode .opencode/skills, .agents/skills, .claude/skills ~/.config/opencode/skills, ~/.agents/skills, ~/.claude/skills Mentionne @skill-id dans ton prompt L'ID est le nom du dossier. Restreins les compétences avec la skill permission
Claude Code .claude/skills ~/.claude/skills /skill-name Ne lit pas .agents/skills. Les compétences des plugins apparaissent comme /plugin-name:skill-name
Codex .agents/skills, dans chaque dossier depuis ton point de départ jusqu'à la racine du dépôt ~/.agents/skills, plus /etc/codex/skills pour les administrateurs $skill-nameou /skills Est livré avec un $skill-installer
Gemini CLI .agents/skills, .gemini/skills ~/.agents/skills, ~/.gemini/skills /skills list; le modèle te demande la permission avant d'en activer un .agents/skills l'emporte quand deux skills portent le même nom
Cursor .agents/skills, .cursor/skills (et lit .claude/skills et .codex/skills) ~/.agents/skills, ~/.cursor/skills /skill-name A chemins le champ limite un skill aux fichiers correspondants
GitHub Copilot .github/skills, .agents/skills, .claude/skills ~/.copilot/skills, ~/.agents/skills Charge les skills quand c'est pertinent Fonctionne dans Copilot CLI, l'agent cloud et le mode agent de VS Code et JetBrains
Hermes Agent .hermes/skills, .agents/skills, après avoir lancé hermes skills trust ~/.hermes/skills, plus tous les dossiers listés dans skills.external_dirs /skill-name, et jusqu'à cinq d'affilée Analyse chaque installation depuis le hub à la recherche de contenu malveillant

Chemins tirés de la documentation de chaque agent au 15 novembre 2026. Les agents ajoutent régulièrement des emplacements ; vérifie la page skills de ton agent si quelque chose n’apparaît pas.

Trois détails qui évitent bien des confusions

  • Claude Code est l'exception. Il ne lit que .claude/skills et ~/.claude/skills. La CLI skills s'en charge pour toi en créant un lien depuis le dossier de Claude Code vers la copie partagée. Si tu copies les skills à la main, tu devras les placer toi-même (ou un lien symbolique) dans le dossier de Claude Code.
  • Hermes Agent garde sa propre bibliothèque. Son dossier principal est ~/.hermes/skills. Pour qu'il lise aussi le dossier partagé, ajoute-le dans ~/.hermes/config.yaml:

yaml skills: external_dirs: - ~/.agents/skills

Ou installe avec la CLI skills en incluant -a hermes-agent. Choisis une seule approche, pas les deux, sinon tu auras chaque skill en double. – Les noms en double provoquent des surprises discrètes. Chaque agent a sa propre règle pour savoir quelle copie l'emporte. OpenCode enregistre ses dossiers dans un ordre fixe et le dernier l'emporte, celui de ton projet .opencode/skills en tout dernier. Claude Code fait l'inverse : un skill personnel bat un skill de projet portant le même nom. Gemini CLI préfère l'espace de travail à l'utilisateur et .agents plutôt que .gemini, et Codex affiche simplement les deux. La solution est ennuyeuse mais fiable : ne garde pas deux skills du même nom.

OpenCode a deux extras qui valent la peine d'être connus. Un simple fichier Markdown à la racine d'un dossier de skills (comme skills/review.md) compte aussi comme un skill, et un compétences tableau dans opencode.jsonc peut ajouter des dossiers supplémentaires ou même un catalogue web de skills. Mon guide OpenCode traite de ses permissions de skills plus en détail.

Où les agents IA cherchent leurs compétences : le dossier partagé .agents/skills lu par Codex, OpenCode, Cursor, Gemini CLI et GitHub Copilot, avec des liens vers .claude/skills de Claude Code et ~/.hermes/skills de Hermes Agent
Un seul dossier partagé couvre la plupart des agents. Claude Code a toujours besoin d’un lien, et Hermes Agent en a besoin pour les compétences globales ; le CLI skills crée les deux.

Partie 4 — La compétences CLI : npm pour les Agent Skills, étape par étape

Tu peux installer des compétences en copiant des dossiers, et pour une ou deux ça va. Au-delà, il te faut un gestionnaire de paquets : quelque chose qui sait où chaque agent regarde, qui garde une seule copie au lieu de cinq, qui se souvient d’où vient chaque compétence et qui peut te dire quand il existe une version plus récente. C’est ce que compétences fait. C’est un outil en ligne de commande open source (MIT) de Vercel Labs, tu le lances avec npx skills, et son répertoire de compétences publiques se trouve sur skills.sh.

Les faits qui comptent au 15 novembre 2026 :

  • Version 1.8.1, publiée le 11 novembre. Ça bouge vite : de la 1.7.5 à la 1.8.1 en neuf jours.
  • Il nécessite Node.js 22.20 ou une version ultérieure.
  • Il prend en charge 79 agents, dont OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot et Hermes Agent.
  • Il s’installe depuis GitHub (owner/repo), GitLab, Azure Repos, n’importe quelle adresse Git, un dossier local, ou un lien de téléchargement direct vers un SKILL.md ou une archive.

Étape 0 — Vérifie Node.js et demande toujours la dernière version

node --version      # nécessite la v22.20.0 ou une version ultérieure

Si ça affiche une version plus ancienne ou “command not found” (commande introuvable), installe la version LTS actuelle depuis nodejs.org. Sur un Mac avec Homebrew, brew install node fonctionne aussi. Sur un Raspberry Pi, la version présente dans la liste de paquets du système d’exploitation est souvent trop ancienne, alors utilise les installateurs liés depuis cette même page.

Ensuite, rends une habitude automatique : tape npx skills@latest plutôt que npx skills pour tout ce qui vérifie ou met à jour. Un simple npx peut réutiliser une copie téléchargée il y a des semaines, et avec cet outil, la version que tu lances change ce que font les commandes (la partie 5 explique le plus gros exemple).

Étape 1 — Regarde avant d’installer

npx skills@latest add vercel-labs/agent-skills --list

--list affiche chaque compétence du dépôt avec sa description et n’installe rien. Ensuite, ouvre le dépôt dans ton navigateur et lis le SKILL.md de tout ce que tu es sur le point d’installer, ainsi que des éventuels scripts à côté. Sur skills.sh, la page de chaque compétence affiche aussi les résultats de l’audit de sécurité (partie 11).

Étape 2 — Installe une compétence pour les agents que tu utilises

# Une compétence, pour OpenCode et Claude Code, dans le projet actuel
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -a opencode -a claude-code

# La même compétence pour tous les projets de cet ordinateur
npx skills add vercel-labs/agent-skills --skill web-design-guidelines -g -a opencode -a claude-code

# Épingle un tag de version ou un commit complet, pour que les mises à jour soient délibérées
npx skills add owner/[email protected] --skill my-skill

Omets --skill et -a et le CLI te pose les questions de manière interactive : quelles compétences, quels agents, et s’il faut lier ou copier. Voici où tout atterrit :

Champ d'application La seule vraie copie Des liens pour les agents qui ont leur propre dossier Le registre de ce que tu as installé
Projet (par défaut) ./.agents/skills/<name> p. ex. ./.claude/skills/<name> pour Claude Code ./skills-lock.json
Global (-g) ~/.agents/skills/<name> p. ex. ~/.claude/skills/<name>, ~/.hermes/skills/<name> ~/.agents/.skill-lock.json

La CLI conserve une seule copie réelle en .agents/skills, que la plupart des agents lisent directement, et crée des liens (des liens symboliques, en gros des raccourcis) pour les agents qui regardent ailleurs. Une seule copie, c’est une seule mise à jour. Si ton système ne gère pas bien les liens symboliques, ce qui peut arriver sous Windows, ajoute --copy pour obtenir des copies indépendantes à la place.

Étape 3 — Voir ce qui est installé

npx skills ls              # les compétences de ce projet
npx skills ls -g           # tes compétences globales
npx skills ls -a opencode  # uniquement ce qu'OpenCode reçoit
npx skills ls --json       # lisible par une machine, pour les scripts

Pour les skills de projet, les versions actuelles affichent aussi un statut : suivi (correspond au fichier de verrouillage), modifié (toi ou l'agent l'avez modifié), non suivi (aucune entrée de verrouillage, comme un skill que tu as écrit à la main) ou manquant (dans le fichier de verrouillage mais pas sur le disque).

Étape 4 — Trouver des skills

npx skills find                    # recherche interactive
npx skills find seo                # recherche par mot-clé
npx skills find react --owner vercel   # uniquement les dépôts d'une organisation

Ou parcours skills.sh, qui classe les skills par nombre d'installations et les regroupe par thème. Le skill le plus installé aujourd'hui est find-skills du dépôt de Vercel lui-même, qui apprend à ton agent à chercher des skills par lui-même. Les nombres d’installations changent chaque jour, alors prends le classement comme une indication, pas comme une évaluation.

Étape 5 — Essayer un skill sans l'installer

npx skills use vercel-labs/agent-skills@web-design-guidelines

Cela affiche un prompt prêt à l'emploi pour ce skill, que tu peux envoyer via un pipe ou coller dans un agent sur le même ordinateur. Ajoute --agent claude-code et la CLI lance Claude Code avec le skill chargé. C’est un bon moyen de tester un skill avant qu'il fasse partie de ta configuration.

Étape 6 — Supprimer des skills

npx skills remove web-design-guidelines            # de ce projet
npx skills rm --global web-design-guidelines       # de tes compétences globales
npx skills remove --agent claude-code my-skill     # d'un seul agent
npx skills remove vercel-labs/agent-skills         # tout ce qui vient de cette source
npx skills remove                                  # choisir dans une liste

npx skills remove --all supprime tous les skills enregistrés dans le fichier de verrouillage et ignore les dossiers qu’il n’a pas installés, comme les skills que tu as écrits toi-même, donc il ne supprimera pas ton propre travail.

Étape 7 — Créer le tien

npx skills init my-skill crée my-skill/SKILL.md à partir d'un modèle. La partie 10 déroule un exemple complet.

Tout l'outil sur une seule carte

Je veux… Commandement
Voir ce qu'un dépôt propose npx skills@latest add owner/repo --list
Installer une compétence dans ce projet npx skills add owner/repo --skill name
Installer pour tous les projets add -g
Choisir les agents add -a opencode -a claude-code (ou --agent '*' pour tous)
Installer sans aucune question add -y
Épingler une version npx skills add owner/[email protected] --skill name
Lister les compétences installées npx skills ls · npx skills ls -g
Recherche npx skills find keyword
Vérifier les mises à jour (lecture seule) npx skills@latest check · add -g ou -p
Installer les mises à jour npx skills update · -g · -p · -y · ou nommer les compétences
Supprimer npx skills remove name · add -g pour le mode global
Restaurer les compétences d’un projet depuis son fichier de verrouillage npx skills install
Créer une nouvelle compétence npx skills init name

Commandes de skills 1.8.1. npx skills install (un alias de experimental_install) et la experimental_sync commande pour les compétences intégrées aux paquets npm sont marquées comme expérimentales et peuvent changer.

Aide-mémoire de la CLI npx skills : les commandes add, list, find, use, check, update, remove et init avec leurs options les plus utiles, les emplacements d'installation par projet et global, et les deux fichiers de verrouillage
L’interface CLI skills sur une seule fiche. Deux habitudes font l’essentiel du travail : --list avant d’installer, et @latest à chaque vérification ou mise à jour.

Qu’est-ce qu’un fichier de verrouillage, et faut-il le committer ?

Un fichier de verrouillage est un reçu. Pour chaque compétence, il enregistre d’où elle vient et une empreinte empreinte de son dossier (techniquement un hash : un court code qui change dès que n’importe quel fichier du dossier change). L’interface CLI en tient deux sortes :

  • skills-lock.json dans un projet. Fais-en un commit dans Git. Sur un autre ordinateur, ou pour un collègue, npx skills install restaure exactement les mêmes compétences, et --frozen-lockfile (la valeur par défaut en CI) refuse de continuer si quoi que ce soit diffère. Cela rend les compétences d’un projet reproductibles, comme package-lock.json le fait pour le code.
  • ~/.agents/.skill-lock.json pour tes compétences globales. Il appartient à ton compte utilisateur (ou se trouve dans $XDG_STATE_HOME/skills/.skill-lock.json si tu as défini cette variable). Ne le modifie pas à la main, et note que chaque utilisateur d'un ordinateur a le sien, ce qui compte dans la partie 6.

La télémétrie, en bref

Le CLI envoie des données d'usage anonymes. D'après sa documentation, les noms de dépôts GitHub et de skills ne sont inclus que lorsque GitHub confirme que le dépôt est public ; d'autres types de source peuvent aussi être nommés. Pour le désactiver, ajoute export DISABLE_TELEMETRY=1 (ou DO_NOT_TRACK=1) à ton profil de shell. Cela désactive aussi les recherches d'audit de sécurité que le CLI effectue pour les skills publics, alors décide ce qui compte le plus pour toi.

D'autres installateurs que tu rencontreras

Le CLI skills n'est pas la seule voie d'entrée. Plusieurs agents et outils ont leurs propres installateurs, et ils suivent tous le même standard ouvert :

Outil Exemple Bon à savoir
GitHub CLI (gh skill, version 2.90 ou ultérieure, en aperçu) gh skill install owner/repo skill-name --agent claude-code gh skill preview montre un skill avant que tu ne l'installes ; --pin verrouille une version
Hermes Agent hermes skills install <identifier> Son hub inclut skills.sh, et chaque installation fait l'objet d'une analyse de sécurité
Gemini CLI gemini skills install <git-url> --scope workspace pour un seul projet ; demande ton consentement sauf si tu passes --consent
Codex $skill-installer <name> Un skill système intégré
Claude Code /plugin install name@marketplace Les plugins regroupent des skills avec des serveurs MCP et des hooks (partie 9)

Une seule règle évite la plupart des maux de tête : mets à jour un skill avec le même outil que celui avec lequel tu l'as installé. Chaque installateur tient ses propres registres, et aucun ne sait ce que les autres ont fait.


Partie 5 — “Mon pack de compétences a été mis à jour il y a deux jours. Comment savoir si je l’ai ?”

C'était exactement ma question quand Superpowers, la populaire bibliothèque de skills de Jesse Vincent, a annoncé une mise à jour. npx skills ls liste des noms, pas des versions, donc il ne peut pas te le dire. Voici comment le CLI le sait réellement.

Comment fonctionne la vérification

Quand tu installes un skill, le CLI stocke l'empreinte de son dossier dans le fichier de verrouillage. Quand tu vérifies, il demande à la source (généralement GitHub) l'empreinte du même dossier aujourd'hui. Même empreinte : à jour. Différente : il y a une mise à jour. Il ne compare ni numéros de version ni dates, c'est pourquoi ça fonctionne même pour les skills qui n'ont ni l'un ni l'autre.

cd /tmp                        # ou un dossier de projet, mais jamais ton dossier personnel
npx skills@latest check -g     # tes skills globaux

cd ~/code/my-app
npx skills@latest check -p     # les skills de ce projet

Un résultat typique en 1.8.1 ressemble à ceci :

↑ brainstorming a une mise à jour
↑ writing-plans a une mise à jour
2 skill(s) peuvent être mises à jour ; exécute npx skills update pour les installer

check signale aussi les skills de projet dont les fichiers ne correspondent plus au fichier de verrouillage (a des modifications locales), et il se termine par un code d’erreur dès que quelque chose est obsolète ou modifié, tu peux donc t’en servir pour arrêter un build CI qui a divergé.

check a changé en novembre, alors exécute la dernière version

Depuis la version 1.7.5 (2 novembre 2026), check ne fait que signaler. Dans les versions antérieures, d’au moins 1.5.18 jusqu’à 1.7.4, check n’était qu’un autre nom pour update: il demandait “Portée de la mise à jour ?” et installait les mises à jour au passage. Si tu as utilisé npx skills check avant novembre et que tu t’es demandé pourquoi il “mettait à jour” des choses, c’est pour ça. Utilise npx skills@latest check et tu obtiendras le comportement en lecture seule.

Deux autres détails qui piègent les gens :

  • check choisit tout seul une portée. Si le dossier où tu te trouves contient un skills-lock.json fichier, ou un .agents/skills dossier contenant une skill, il vérifie les projet skills du projet ; sinon il vérifie les globales globales. Ajoute -g ou -p pour préciser laquelle tu veux.
  • Il n’y a pas d’option “tout mettre à jour depuis un seul dépôt”. Soit tu mets à jour tout dans une portée, soit tu nommes les skills.

Puis mets à jour

npx skills update                      # demande : projet, global ou les deux
npx skills update -g                   # toutes les compétences globales
npx skills update -p                   # toutes les compétences du projet
npx skills update brainstorming writing-plans -g   # seulement celles-ci
npx skills update -y                   # sans question : projet si tu en as un, sinon global

Lis les changements avant de mettre à jour quoi que ce soit d’important. Ouvre l’historique des commits du dépôt sur GitHub et regarde ce qui a changé dans les dossiers de skills : une mise à jour, ce sont de nouvelles instructions que ton agent suivra avec tes permissions.

Si tu l’as installé comme plugin, mets-le à jour comme un plugin

Beaucoup de packs de skills sont désormais distribués comme plugins, et Superpowers en est un bon exemple. Son README indique une méthode d’installation différente pour presque chaque agent :

Agent Installation de Superpowers, d’après son README Comment il se met à jour
Claude Code /plugin install superpowers@claude-plugins-official Automatiquement, depuis la marketplace officielle d’Anthropic
Codex CLI /plugins, cherche “superpowers”, Installer le plugin Via le gestionnaire de plugins
Cursor /add-plugin superpowers dans le chat Agent Via le gestionnaire de plugins
Gemini CLI gemini extensions install https://github.com/obra/superpowers gemini extensions update superpowers
GitHub Copilot CLI copilot plugin marketplace add obra/superpowers-marketplace, alors copilot plugin install superpowers@superpowers-marketplace Via le gestionnaire de plugins
Hermes Agent hermes plugins install obra/superpowers --enable Via le gestionnaire de plugins
OpenCode Ajouter "superpowers@git+https://github.com/obra/superpowers.git" à la liste de plugins dans opencode.json, comme le décrit son guide d'installation OpenCode Au redémarrage ; vide le cache de paquets d’OpenCode si une nouvelle version n’apparaît pas, ou ajoute #v5.0.3pour épingler une version avec des balises de ce style

D'après le README de Superpowers et son guide d'installation OpenCode, vérifié le 15 novembre 2026.

J'ai installé Superpowers sur mon Mac avec npx skills -g, donc le mien se met à jour via la CLI skills. Ça va. Ce qui ne va pas, c'est d'installer le même pack par deux canaux : tu te retrouves avec deux copies de chaque skill sous des noms identiques, et aucun moyen de savoir laquelle l'agent choisira.

Comment fonctionne npx skills check : le fichier de verrouillage stocke une empreinte de chaque dossier de compétence, check la compare avec le même dossier en amont et signale les mises à jour, et update les installe
check compare les empreintes, pas les numéros de version. Depuis la 1.7.5, il se contente de signaler ; update est la commande qui change vraiment les choses.

Partie 6 — Cinq vrais problèmes rencontrés sur mon Mac et mon Raspberry Pi, et comment les résoudre

Tout ce qui suit dans cette partie m'est arrivé à l'été 2026, avec la version 1.5 de la CLI. Chaque problème a depuis été vérifié dans le code source de la version actuelle, la 1.8.1, pour que tu saches lesquels sont corrigés et lesquels mordent encore. La sortie du terminal est réelle ; je l'ai raccourcie et j'ai retiré les noms de machines.

Problème 1 : “Tous les skills globaux sont à jour”, alors que rien n'a été vérifié

Sur mon Mac, npx skills check a produit ceci :

graham@mac my-app % npx skills check
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
Checking skills from source: anthropics/skills
│  GitHub API request limit reached; checking existing gh authentication…
  ✗ Failed to fetch tree for anthropics/skills
Checking skills from source: vercel-labs/skills
  ✗ Failed to fetch tree for vercel-labs/skills
…                                  (six more sources, every one ✗)
Checking skills from source: obra/superpowers
  ✗ Failed to fetch tree for obra/superpowers
✓ All global skills are up to date

Ce qui s'est passé. Pour vérifier un dépôt, la CLI demande à l’API de GitHub la liste des fichiers du dépôt. GitHub autorise 60 requêtes anonymes par heure par adresse internet, et mon quota de l'heure était déjà épuisé (l'outil le dit dès la première ligne), donc chaque recherche a échoué. La dernière ligne ne compte que les mises à jour que l'outil a trouvées, et il n'en avait trouvé aucune, alors il a affiché une coche verte. L'ancienne version essayait aussi d'emprunter une connexion à la CLI GitHub en coulisses (c'est la ligne “checking existing gh authentication”) ; comme chaque requête échouait quand même, il n'y avait manifestement aucune connexion à emprunter.

Est-ce corrigé ? En partie. La version 1.8.1 insiste davantage avant d'abandonner : d'abord en anonyme, puis avec un jeton issu de ton environnement, puis avec la connexion propre à la CLI GitHub via gh api, et, pour les vérifications de mise à jour, un simple téléchargement Git en dernier recours. Mais le code source de la 1.8.1 montre que lorsqu'une source ne peut toujours pas être vérifiée, la ligne de résumé ne compte encore que les mises à jour qu'il a trouvées. Une coche verte sous des croix rouges reste possible, alors lis les lignes ✗.

La solution. Donne une connexion à la CLI, ce qui relève la limite à 5 000 requêtes par heure :

  1. Le plus simple : installe la GitHub CLI et lance gh auth login. Les versions actuelles de la CLI skills demandent gh de faire l'appel API et ne voient jamais tes identifiants.
  2. Ou utilise un jeton : crée un jeton d’accès personnel à granularité fine avec un accès en lecture seule aux dépôts publics, puis ajoute-le à ton profil de shell (~/.zshrc sur un Mac, ~/.bashrc sur un Raspberry Pi) :

bash export GITHUB_TOKEN="github_pat_…" # read-only, public repositories

Ouvre ensuite un nouveau terminal. Traite le jeton comme un mot de passe : ne le colle jamais dans un chat, dans un skill ou dans un fichier que tu commites. 3. Mets à jour et revérifie : npx skills@latest check -g.

Problème 2 : sudo m’a donné deux stocks de skills et une erreur npm

Sur mon Raspberry Pi, j’avais pris l’habitude de taper sudo su en premier. Voici ce que ça a produit :

graham@pi:~ $ sudo su
root@pi:/home/graham# npx skills update
npm error config prefix cannot be changed from project config: /home/graham/.npmrc.
◇  Update scope
│  Both
Checking for skill updates…
Global Skills
…
Found 6 global update(s)
…
Project Skills
Updating for: Universal, Claude Code, Hermes Agent
Refreshing 7 skill(s)…

Et un instant plus tard, de retour avec mon utilisateur normal :

graham@pi:~ $ ls ~/.agents/skills | wc -l
7
graham@pi:~ $ sudo ls /root/.agents/skills | wc -l
37

Ce qui s'est passé. sudo su te transforme en root, et root a son propre dossier personnel, /root. Les skills sont stockés par utilisateur, donc les skills globaux de root vivent dans /root/.agents/skills et les miens dans /home/graham/.agents/skills. Toutes les installations globales que j’avais faites en root avaient atterri dans le stock de root : 37 skills là-bas, 7 chez moi. Si tes agents tournent sous ton utilisateur normal, ce qui est la configuration habituelle, tout ce qui se trouve dans le stock de root leur est invisible.

L’erreur npm a la même cause. En root, le fichier de réglages personnels de npm est /root/.npmrc, donc le /home/graham/.npmrc présent dans le dossier où je me trouvais est lu comme un projet fichier de réglages à la place. Le code de npm lui-même refuse qu’un fichier de projet change le prefix réglage, et journalise exactement cette erreur. Il y a un troisième risque que tu ne verras pas tout de suite : tout ce que root écrit dans ton dossier personnel finit par appartenir à root, et ton utilisateur normal ne peut plus le mettre à jour ensuite.

La solution.

  1. Quitte root : type exit. Désormais, lance le CLI et tes agents avec ton propre compte.
  2. Découvre sous quel utilisateur tournent tes agents. Le dossier personnel qui contient leurs réglages est celui qui compte :

bash ls -d ~/.claude ~/.config/opencode ~/.hermes 2>/dev/null sudo ls -d /root/.claude /root/.config/opencode /root/.hermes 2>/dev/null

  1. Réinstalle les skills de root en ton propre nom, depuis leurs sources d’origine. Copier les fichiers tels quels transporterait la propriété de root et des enregistrements périmés. Une réinstallation écrit un fichier de verrouillage propre. Commence par lister les sources que root a utilisées :

bash sudo grep '"source"' /root/.agents/.skill-lock.json | sort -u

Ensuite, depuis un dossier de projet ou /tmp, lance npx skills add <owner/repo> -g -a <your agents> pour chacun de ceux que tu veux encore garder. 4. Récupère la propriété de tes propres dossiers, au cas où root y aurait écrit :

bash sudo chown -R "$(id -un)":"$(id -gn)" ~/.agents ~/.claude ~/.hermes ~/.config/opencode 2>/dev/null

  1. Seulement quand tout fonctionne avec ton propre compte, supprime la copie de root avec sudo rm -rf /root/.agents.

Si tu utilises sudo car les installations npm globales échouent sans ça, corrige plutôt ça : pointe le préfixe de npm vers un dossier qui t'appartient (npm config set prefix ~/.npm-global, puis ajoute ~/.npm-global/bin à ton PATH). C'est presque sûrement ce que la prefix ligne dans mon propre .npmrc faisait.

Problème 3 : lancé depuis ton dossier personnel, il devient un “projet”

De retour sous mon propre compte, dans mon dossier personnel :

graham@pi:~ $ npx skills check
Les paquets suivants doivent être installés :
[email protected]
On continue ? (y) y
…
Skills globaux
Aucun skill global suivi dans le fichier de verrouillage.
Installe des skills avec npx skills add <package> -g
Skills du projet
Mise à jour pour : Universal, Claude Code, Hermes Agent
Actualisation de 7 skill(s)…

Ce qui s'est passé. Le CLI décide qu'un dossier est un projet s'il contient un skills-lock.json fichier ou un .agents/skills dossier contenant un skill. Ton dossier personnel contient ~/.agents/skills, car c'est là que vivent les skills globaux, donc depuis ~ le CLI voit un projet. Et si tu as déjà lancé npx skills add dans ton dossier personnel sans -g, tu y as créé une véritable installation de projet, avec son propre ~/skills-lock.json, dont le dossier de skills est exactement le même que celui utilisé par l'installation globale. C'est ce qui s'était passé sur mon Pi : sept skills suivis comme un “projet” dans mon dossier personnel, et rien du tout dans mon propre fichier de verrouillage global.

“Aucun skill global suivi dans le fichier de verrouillage” a trois causes courantes : tu n'as jamais installé avec -g, tu as installé avec -g en tant qu'autre utilisateur (root, via sudo), ou le fichier de verrouillage a été supprimé. Si tu as lu ailleurs qu'une generate-lock commande le reconstruit, elle n'existe pas : il n'y a aucune commande de ce genre en version 1.5 ou 1.8.

La solution.

  • Lance le CLI depuis un dossier de projet ou /tmp, jamais depuis ~, et passe -g ou -p pour qu'il ne puisse pas deviner.
  • Pour démêler un “projet” de dossier personnel, réinstalle les skills que tu veux avec -g depuis un autre dossier (ils atterrissent au même endroit, désormais enregistrés dans ton fichier de verrouillage global), puis supprime ~/skills-lock.json. Ne lance pas npx skills remove de ~ pour ça : dans ton dossier personnel, le dossier de projet et le dossier global sont le même dossier.

Problème 4 : “No matching skills found” à cause d’un deux-points

graham@pi:~ $ npx skills remove ckm:banner-design ckm:brand ckm:design \
  ckm:design-system ckm:slides ckm:ui-styling
◇  Found 7 unique installed skill(s)
■  No matching skills found for: ckm:banner-design, ckm:brand, ckm:design, ckm:design-system, ckm:slides, ckm:ui-styling

Ce qui s'est passé. Ces compétences apparaissent comme ckm:banner-design, mais un deux-points est un caractère risqué dans un nom de dossier, donc le CLI les a enregistrées sous ckm-banner-design: il met le nom en minuscules et transforme tout ce qui n’est pas lettre, chiffre, point ou tiret bas en trait d’union. La version 1.5.18 comparait exactement ce que je tapais aux noms de dossiers, donc rien ne correspondait.

Est-ce corrigé ? Oui. Les versions actuelles convertissent ta saisie de la même façon avant de comparer, donc ckm:brand et ckm-brand les deux fonctionnent, et quand rien ne correspond, la 1.8.1 affiche les noms qui sont sont installés.

La solution. Courir npx skills ls (ou ls ~/.agents/skills) pour voir les vrais noms, ou lance npx skills remove sans argument et choisis dans la liste. Vérifie aussi la portée : depuis un dossier de projet, retirer une compétence enregistrée dans ton fichier de verrouillage global te dit désormais d’ajouter -g.

Problème 5 : six compétences échouent, une du même dépôt fonctionne

Refreshing 7 skill(s)…
✗ Failed to check for deleted skills from nextlevelbuilder/ui-ux-pro-max-skill
Updating ckm:banner-design…
  ✗ Failed to update ckm:banner-design
…                                  (five more ✗)
Updating ui-ux-pro-max…
  ✓ Updated ui-ux-pro-max

Ce qui s'est passé. Pour mettre à jour une compétence, le CLI la recherche à nouveau dans son dépôt source. Six de mes sept compétences de ce dépôt étaient introuvables, alors que la septième s’est mise à jour sans problème. Quand la plupart des compétences d’une même source échouent et qu’une seule réussit, les manquantes ont en général été renommées, déplacées ou supprimées en amont. Le README de ce dépôt ne décrit plus aujourd’hui qu’une seule compétence, ui-ux-pro-max, et ne mentionne les bannières, l’identité de marque et les diapositives que comme des fonctionnalités d’une offre payante, ce qui cadre avec le départ des six du dépôt gratuit.

La solution. Regarde ce que la source propose maintenant, puis retire ce qui a disparu :

npx skills add nextlevelbuilder/ui-ux-pro-max-skill --list
npx skills remove ckm-banner-design ckm-brand ckm-design ckm-design-system ckm-slides ckm-ui-styling

Les versions actuelles du CLI repèrent les compétences supprimées en amont et proposent de les nettoyer pendant une mise à jour, et elles retirent les compétences manquantes du fichier de verrouillage quand tu désinstalles. Pendant que tu y es, cherche les doublons : si tu as aussi une brand compétence à côté de ckm-brand, gardes-en une. Deux compétences aux descriptions presque identiques brouillent le choix de l’agent et gaspillent son budget de listing.

Bonus : Claude Code ne voit pas une compétence installée par le CLI

  • Vérifie le lien. Claude Code ne lit que ses propres dossiers, donc ls -la ~/.claude/skills (ou .claude/skills dans le projet) devrait afficher la compétence, généralement sous la forme d’un lien vers .agents/skills. Plusieurs versions 1.5 ont corrigé des bugs autour des liens de Claude Code (1.5.16 et 1.5.20), donc s’il manque, réinstalle avec npx skills@latest add … -a claude-code.
  • Vérifie que le fichier commence correctement. L’ouverture --- du front matter doit être la toute première ligne de SKILL.md, sinon Claude Code traite tout le fichier comme du texte brut.
  • Recharge. Claude Code prend en compte les compétences modifiées à chaud, mais un dossier de compétences créé après le début de la session a besoin d’un /reload-skills. Ensuite /skills liste ce qui est chargé.
Dépannage de npx skills : cinq erreurs réelles et leurs correctifs, d'un faux « tout est à jour » après une limite de débit GitHub à sudo qui crée un second magasin de compétences, en passant par un dossier personnel traité comme un projet et des compétences supprimées en amont
Cinq erreurs, cinq solutions. La plupart se ramènent aux deux mêmes règles : lis les lignes ✗, et ne lance jamais l'interface CLI en root ni depuis ton dossier personnel.

Partie 7 — Les serveurs MCP sans le jargon

Ce qui se passe quand tu connectes un serveur

  1. Tu ajoutes le serveur dans les réglages de ton agent : une commande pour un serveur local, une adresse web pour un serveur distant.
  2. Au démarrage d'une session, l'agent lance le serveur local ou se connecte au serveur distant, et s'authentifie si le serveur l'exige.
  3. Le serveur liste ses outils, et l'agent transmet leurs descriptions au modèle.
  4. Quand une tâche a besoin d'un outil, le modèle le demande, ton agent vérifie tes règles d'autorisation (et peut te poser la question), le serveur fait le travail, et le résultat revient dans la conversation.

Local ou distant ?

Serveur local (stdio) Serveur distant (Streamable HTTP)
S'exécute Sur ton ordinateur, lancé par l'agent Sur les ordinateurs du fournisseur
Tu ajoutes Une commande, comme npx @playwright/mcp@latest Une adresse, comme https://mcp.context7.com/mcp
Authentification Généralement une clé API dans une variable d'environnement Généralement OAuth dans ton navigateur, ou une clé dans un en-tête
Nécessite Node.js, Python ou Docker, selon le serveur Une connexion internet
Meilleur pour Des choses sur ta machine : un navigateur, des fichiers, une base de données locale Des services cloud : GitHub, Sentry, de la documentation, des outils de projet
Attention à Il s'exécute avec toutes les permissions de ton utilisateur Tes données partent chez ce fournisseur

Tu peux encore voir un troisième type, SSE, dans des guides plus anciens. La documentation de Claude Code le marque comme obsolète ; utilise l'adresse HTTP quand un serveur propose les deux.

Un mot sur les versions

La spécification MCP actuelle, publiée le 28 juillet 2026, est la plus grande révision depuis le lancement du protocole : son cœur est désormais sans état, ce qui permet aux serveurs distants de tourner derrière des équilibreurs de charge ordinaires. Tu as rarement besoin de t'en soucier, car clients et serveurs s'accordent sur la révision à utiliser et les anciens serveurs continuent de fonctionner. OpenCode est le seul endroit où tu pourrais le voir : chaque serveur a un protocole réglage (legacy par défaut, autoou 2026-07-28), et la mise en commun des connexions ne fonctionne qu’avec la révision la plus récente.

La facture du contexte, et comment la garder légère

Chaque outil qu’un serveur propose arrive avec une description écrite pour le modèle. Dans les mots propres d’OpenCode, “Les outils MCP consomment le contexte du modèle, donc n'ajoute que les serveurs dont tu as besoin.” Deux agents adoucissent désormais ce coût par défaut :

  • Claude Code utilise la recherche d’outils. Au début d’une session, il ne charge que les noms des outils et les instructions de chaque serveur, et récupère la définition complète d’un outil quand Claude la cherche vraiment.
  • OpenCode utilise Code Mode, qui regroupe les outils de chaque serveur derrière une seule entrée au lieu de lister chaque outil séparément. C’est activé sauf si tu définis "codemode": false pour un serveur.

Partout ailleurs, et en plus de ces valeurs par défaut, voici tes leviers :

Agent Désactiver un serveur Masquer les outils que tu ne veux pas
OpenCode "disabled": trueou /mcps pour une session A deny règle sur <server>_<tool> dans les autorisations
Claude Code claude mcp remove <name> (/mcp affiche l’état) A deny règle d’autorisation sur mcp__<server>__<tool>; ENABLE_TOOL_SEARCH décide de la quantité chargée au départ
Codex enabled = false enabled_tools et disabled_tools
Gemini CLI gemini mcp disable <name> (ajoute --session pour une session) includeTools et excludeTools
Cursor L’interrupteur du serveur sous Personnaliser (Les admins peuvent définir des listes d’outils autorisés)
Hermes Agent enabled: false tools.include et tools.exclude

Ma règle : deux à cinq serveurs que tu utilises chaque semaine valent mieux que vingt que tu pourrais utiliser un jour. Supprime le reste ; tu peux les rajouter en une minute.

Quatre serveurs à essayer en premier

Serveur Ce que ça apporte à ton agent Type Adresse ou commande Authentification
Context7 Documentation à jour et propre à chaque version pour les bibliothèques et frameworks populaires Distant https://mcp.context7.com/mcp Aucune clé nécessaire ; une clé API gratuite relève les limites
GitHub (officielles) Issues, pull requests, recherche de code, Actions Distant https://api.githubcopilot.com/mcp/ OAuth quand ton agent le prend en charge, ou un jeton d'accès personnel
Playwright Un vrai navigateur que l'agent peut ouvrir, parcourir et capturer en capture d'écran Local npx @playwright/mcp@latest Aucun
Sentry Tes vraies erreurs et tes vrais plantages Distant https://mcp.sentry.dev/mcp OAuth

Où en trouver d'autres :

  • Le registre MCP officiel, maintenu par les contributeurs du protocole, répertorie les serveurs publiés.
  • La documentation propre à tes outils. La plupart des services publient désormais un serveur officiel ; cherche “MCP” dans leur documentation.
  • Le catalogue de ton agent. Hermes Agent a hermes mcp catalog, et beaucoup de plugins Claude Code apportent leurs propres serveurs.

Préfère les serveurs publiés par l'entreprise qui exploite le service. Un serveur au hasard nommé “github-mcp-pro” mérite la même méfiance qu'une extension de navigateur au hasard.

L'option plus légère : un outil en ligne de commande et une skill

Avant d'ajouter un serveur, vérifie si un outil en ligne de commande ne fait pas le travail. Context7 propose lui-même les deux voies : le serveur MCP ci-dessus, ou une petite CLI avec une skill (npx ctx7 setup --opencode, qui nécessite Node.js 22.13 ou version ultérieure). L’outil propre à GitHub gh associé à une courte skill couvre l'essentiel de ce que fait son serveur.

Un serveur se justifie quand ton agent ne peut pas exécuter de commandes (une appli de chat de bureau, par exemple), le service n’a pas de bonne CLI, ou la tâche est interactive, comme piloter un navigateur. Une CLI et une skill se justifient quand l'outil existe déjà : il ne coûte rien tant qu’il n'est pas utilisé, et sa sortie peut être réduite avant d'atteindre le modèle. Mon guide OpenCode défend le même argument pour le développement d'applications.


Partie 8 — Ajouter un serveur MCP dans six agents : des recettes à copier-coller

Chaque recette ajoute les deux mêmes serveurs : Context7 (distant) et Playwright (local). Remplace par n'importe quel autre serveur de la même façon. Quand un agent propose à la fois une commande et un fichier de réglages, la commande écrit simplement le fichier pour toi.

OpenCode

opencode mcp add context7 --url https://mcp.context7.com/mcp
opencode mcp add playwright -- npx @playwright/mcp@latest
opencode mcp list

Ajouter --global pour rendre un serveur disponible dans tous les projets. Dans opencode.jsonc la même configuration ressemble à ceci :

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "context7": {
        "type": "remote",
        "url": "https://mcp.context7.com/mcp",
        "oauth": false
        // With a free API key, add:
        // "headers": { "Authorization": "Bearer {env:CONTEXT7_API_KEY}" }
      },
      "playwright": {
        "type": "local",
        "command": ["npx", "@playwright/mcp@latest"]
      }
    }
  }
}
  • Les secrets s'écrivent sous la forme {env:NAME}; OpenCode n’étend pas une simple $NAME.
  • Les serveurs distants tentent OAuth automatiquement ; oauth: false est destiné aux serveurs qui utilisent une clé ou aucun. Connecte-toi avec opencode mcp auth <name>, et en SSH, colle l'URL de rappel depuis la page du navigateur qui a échoué dans l'invite.
  • Dans une session, /mcps connecte, déconnecte ou authentifie les serveurs.
  • Chaque outil devient une action de permission nommée <server>_<tool>, donc { "action": "playwright_*", "resource": "*", "effect": "ask" } fait que chaque action du navigateur demande d'abord.

Claude Code

claude mcp add --transport http context7 https://mcp.context7.com/mcp
claude mcp add playwright -- npx @playwright/mcp@latest
claude mcp list

Le -- sépare les options de Claude Code de la commande propre au serveur. Par défaut, les serveurs sont en portée locale (toi, dans ce projet). Ajoute --scope user pour tous tes projets, ou --scope project pour écrire un .mcp.json fichier que tu peux committer pour ton équipe :

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    },
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • .mcp.json développe ${VAR} et ${VAR:-default}, afin que les clés restent dans ton environnement, pas dans Git.
  • /mcp dans une session affiche l'état de chaque serveur et gère la connexion OAuth.
  • Claude Code demande avant d'utiliser les serveurs d'un .mcp.json, ainsi un dépôt cloné ne peut pas ajouter les siens en douce.

Codex

Codex conserve les serveurs dans ~/.codex/config.toml, ou dans .codex/config.toml dans un projet que tu as marqué comme fiable :

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
  • Les serveurs distants peuvent aussi être ajoutés avec codex mcp add context7 --url https://mcp.context7.com/mcpet codex mcp login <name> lance une connexion OAuth.
  • Pour une clé, bearer_token_env_var = "CONTEXT7_API_KEY" la lit depuis ton environnement.
  • Ajuste un serveur avec enabled_tools et disabled_tools; startup_timeout_sec (10 secondes par défaut) aide les serveurs lents à démarrer.

Gemini CLI

gemini mcp add -t http context7 https://mcp.context7.com/mcp
gemini mcp add playwright npx @playwright/mcp@latest
gemini mcp list

gemini mcp add écrit dans les paramètres du projet par défaut ; ajoute -s user pour chaque projet. Dans settings.json:

{
  "mcpServers": {
    "context7": { "httpUrl": "https://mcp.context7.com/mcp" },
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] }
  }
}
  • httpUrl sert au Streamable HTTP ; url désigne l'ancien type SSE.
  • Laisse trust désactivé. Mis à vrai, il saute toutes les confirmations pour ce serveur.
  • Gemini CLI retire les variables qui ressemblent à des secrets (noms contenant TOKEN, SECRET, PASSWORD ou KEY) de l'environnement d'un serveur, sauf si tu les listes dans son env bloc.
  • OAuth a besoin d'un navigateur sur la même machine. Dans un dossier non approuvé, les serveurs locaux restent déconnectés jusqu'à ce que tu lances gemini trust.

Cursor

Cursor lit .cursor/mcp.json dans un projet et ~/.cursor/mcp.json pour tout :

{
  "mcpServers": {
    "context7": { "url": "https://mcp.context7.com/mcp" },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
  • Les serveurs locaux ont besoin de "type": "stdio".
  • Les secrets s'écrivent sous la forme ${env:NAME}.
  • Active et désactive les serveurs avec leurs interrupteurs sous Personnaliser.

Hermes Agent

Hermes lit mcp_servers en ~/.hermes/config.yaml:

mcp_servers:
  context7:
    url: "https://mcp.context7.com/mcp"
  playwright:
    command: "npx"
    args: ["@playwright/mcp@latest"]
  • Courir /reload-mcp après modification, et hermes mcp test context7 pour voir exactement ce qu'un serveur a répondu.
  • Pour les services OAuth, ajoute auth: oauth à une entrée HTTP. Sur une machine sans écran, Hermes propose le retour par collage, le transfert de port SSH ou un flux de connexion par appareil.
  • Hermes ne transmet aux serveurs locaux que les variables que tu listes dans env plus une base minimale sûre, pas tout l'environnement de ton shell.
  • Les outils apparaissent sous la forme mcp_<server>_<tool>; filtre-les avec tools.include ou tools.exclude.

Vérifie que ça marche, dans n'importe quel agent

Pose une question à laquelle seul le serveur peut répondre : “Utilise Context7 pour chercher comment définir une route dans la version actuelle de Next.js, et dis-moi quel outil tu as appelé.” Demande ensuite quelque chose de visible : “Ouvre example.com avec Playwright et décris la page.” Si l'agent dit qu'il n'a pas ces outils, liste les serveurs (Liste des MCP OpenCode, claude mcp list, gemini mcp list, hermes mcp test) et cherche une connexion en échec ou une authentification qui ne s'est jamais terminée.

Comment ajouter un serveur MCP dans OpenCode, Claude Code, Codex, Gemini CLI, Cursor et Hermes Agent : le même serveur Context7 dans la commande ou le format de configuration de chaque agent, plus une commande de serveur local
Un serveur, six dialectes. Les idées sont identiques ; seuls les noms de fichiers et les crochets changent.

Partie 9 — Plugins : compétences et serveurs MCP dans un seul paquet

Installer dix skills et trois serveurs un par un finit par lasser. Les plugins les regroupent, et la plupart des agents disposent désormais d'un système de plugins, d'une forme ou d'une autre.

Plugins Claude Code

Un plugin Claude Code peut contenir des skills, des sous-agents, des hooks, des serveurs MCP et des serveurs de langage. Les plugins viennent de marketplaces, qui ne sont rien d'autre que des catalogues hébergés dans un dépôt Git :

/plugin marketplace add anthropics/skills
/plugin install document-skills@anthropic-agent-skills

Dans une session, /plugin install ouvre d'abord les détails du plugin pour que tu voies exactement ce qu'il ajoute avant de choisir une portée : toi (tous les projets), ce dépôt pour tout le monde, ou ce dépôt rien que pour toi. Depuis ton shell, claude plugin install <name>@<marketplace> fait la même chose sans session.

Trois fonctions à connaître :

  • Le coût en contexte est visible. Pour les plugins de la marketplace officielle d’Anthropic, le panneau de détails estime ce que le plugin ajoute à chaque message et ce qu'il ajoute quand il est utilisé. claude plugin details <name> affiche la valeur par session pour tout ce qui est installé.
  • Mises à jour. La marketplace officielle d'Anthropic met à jour les plugins automatiquement ; les marketplaces tierces ne le font pas, sauf si tu l'actives. claude plugin update <name>@<marketplace> met à jour un plugin à la main.
  • Les plugins inutilisés sont signalés. L'onglet Installés regroupe les plugins que tu n'as pas utilisés récemment, ce qui facilite le grand ménage.

Plugins ailleurs

  • Codex distribue des skills réutilisables via des plugins (/plugins dans la CLI), et un plugin peut aussi porter des connexions à des serveurs MCP.
  • Gemini CLI les appelle des extensions : gemini extensions install <git-url> et gemini extensions update <name>.
  • GitHub Copilot CLI (copilot plugin install) et Hermes Agent (hermes plugins install) ont des commandes de plugin, et Cursor a /add-plugin dans le chat Agent.
  • OpenCode les plugins sont des paquets JavaScript ou TypeScript listés dans le liste de plugins réglage de sa configuration, qui peut enregistrer des skills et des outils. Superpowers s'installe de cette façon.

Les deux règles pour garder une installation de plugins saine

  1. Un canal par pack. Si un pack de skills existe à la fois comme plugin et comme skills simples, choisis-en un. Deux copies, cela veut dire des noms en double et un agent qui prend celle qu'il voit en premier.
  2. Mets à jour là où tu as installé. Le CLI skills ne connaît rien aux plugins, et les gestionnaires de plugins ne connaissent rien aux ~/.agents/skills.

Partie 10 — Écris ta première compétence en dix minutes

La meilleure première skill résout une tâche que tu répètes. En voici une, construite à partir de la partie 6 : une skill qui permet à n'importe quel agent de vérifier les mises à jour de tes skills en toute sécurité, sans jamais utiliser sudo ni faire aveuglément confiance à une coche verte.

Étape 1 — Créer le dossier

mkdir -p ~/skills-drafts && cd ~/skills-drafts
npx skills init skills-housekeeping

Cela crée skills-housekeeping/SKILL.md à partir d'un modèle. Remplace son contenu par ceci :

---
name: skills-housekeeping
description: Vérifie les mises à jour et les problèmes des skills d'agent installées avec le CLI npx skills, et explique les résultats en langage clair. À utiliser quand on demande si les skills sont à jour, pour mettre à jour des skills, ou quand une skill installée semble manquer.
metadata:
  author: graham-miranda
  version: "1.0"
---

# Entretien des skills

## Règles
- Ne jamais lancer de commande avec sudo.
- Ne jamais lancer `npx skills update` ou `npx skills remove` sans demander d'abord.
- Lancer les commandes depuis /tmp ou un dossier de projet, jamais depuis le dossier personnel.

## Vérification
1. Lance `cd /tmp && npx skills@latest check -g` pour les skills globales.
2. Si le projet en cours a un fichier skills-lock.json, lance aussi `npx skills@latest check -p` dans le dossier du projet.
3. Considère chaque ligne qui commence par ✗ comme "non vérifiée", même si une ligne suivante dit que tout est à jour.

## Rapport
- Liste les skills qui ont des mises à jour, les skills avec des modifications locales et tout ce qui n'a pas pu être vérifié.
- Si une vérification a échoué, suggère `gh auth login`, ou un GITHUB_TOKEN avec un accès en lecture seule aux dépôts publics.
- Demande avant de mettre à jour. Lance ensuite `npx skills update -g` (ou `-p`) et indique ce qui a changé.

Étape 2 — La vérifier par rapport à la norme

  • Nom : skills-housekeeping n'utilise que des minuscules et des traits d'union, fait moins de 64 caractères et correspond au nom du dossier. Les trois sont obligatoires.
  • Description : elle dit quoi ce que fait la skill et quand quand l'utiliser, et elle contient les mots que les gens tapent vraiment (“up to date”, “update skills”, “missing”). La description est la seule partie que l'agent voit avant de décider, c'est donc elle qui fait l'essentiel du travail. La norme autorise jusqu'à 1 024 caractères ; vise une ou deux phrases.
  • Longueur : bien en dessous des 500 lignes recommandées. Quand une skill grossit, déplace les détails dans references/ et pointe vers lui depuis les instructions.

Le projet Agent Skills publie un validateur de référence, skills-ref, qui vérifie le front matter et les règles de nommage : skills-ref validate ./skills-housekeeping.

Étape 3 — L'installer pour tous les agents d'un coup

Le CLI skills installe aussi depuis un dossier local :

npx skills add ./skills-housekeeping -g -a opencode -a claude-code -a codex

Cela place la vraie copie dans ~/.agents/skills/skills-housekeeping (lu directement par OpenCode et Codex) et ajoute un lien dans ~/.claude/skills pour Claude Code.

Étape 4 — Teste-le

Demande en termes simples : “Mes skills sont-ils à jour ?” Un skill bien décrit est repris automatiquement. S’il ne l’est pas, appelle-le par son nom pour écarter un problème de chargement : @skills-housekeeping dans OpenCode, /skills-housekeeping dans Claude Code, $skills-housekeeping dans Codex. S'il se charge par son nom mais jamais tout seul, le problème vient de la description : ajoute les formulations que tu utilises vraiment.

Étape 5 — Partage-le

Pousse le dossier vers un dépôt GitHub, idéalement dans un skills/ dossier (skills/skills-housekeeping/SKILL.md). N'importe qui peut ensuite l'installer avec npx skills add your-name/your-repo. Le CLI cherche les skills dans skills/ et dans les dossiers d'agents habituels, jusqu'à trois niveaux de profondeur.

Les extras propres à chaque agent, et quand les éviter

Plusieurs agents comprennent des champs front matter supplémentaires. Claude Code a disable-model-invocation (toi seul peux déclencher le skill) et context: fork (l'exécuter dans un sous-agent) ; Cursor a chemins (uniquement pour les fichiers correspondants) ; OpenCode peut cacher un skill au modèle avec metadata fixé à opencode/autoinvoke: false. Ils sont utiles, mais ce sont les champs standard qui voyagent. La documentation de Claude Code note elle-même qu’en dehors de Claude Code, dans les imports claude.ai ou l’API Skills, seuls les champs standard sont acceptés et tout le reste provoque une erreur. Pour les skills que tu partages, tiens-toi à nom, description, licence, compatibilité, metadata et le champ expérimental allowed-tools.

Anatomie d'une compétence d'agent : le front matter de SKILL.md lu au démarrage pour environ 100 tokens, les instructions lues quand une tâche correspond, et les références, scripts et ressources lus seulement au besoin
Trois couches : l'étiquette, la recette et l'annexe. Seule la première est toujours chargée, c'est pourquoi une bonne description compte plus que de longues instructions.

Partie 11 — Rester en sécurité : les compétences et les serveurs sont des logiciels

Il est facile de voir un skill comme “un simple fichier Markdown”. Ce n’est pas vraiment le cas. Ce sont des instructions que ton agent suivra avec tes permissions, souvent avec des scripts qu'il exécutera sur ta machine. Et un serveur MCP local est un programme qui tourne avec tes droits.

Les chiffres de cette année donnent à réfléchir. L’étude ToxicSkills de Snyk, publiée en février 2026, a passé au crible 3 984 skills publics d’agents : 36,82 % avaient au moins une faille de sécurité, 13,4 % en avaient une critique, et 76 contenaient des charges malveillantes confirmées. Le problème se concentrait sur ClawHub, la place de marché communautaire d’OpenClaw, où un audit antérieur de 2 857 skills, également rapporté par Snyk, avait trouvé 341 skills malveillants, soit environ 12 % du registre à l’époque. À l’inverse, les 100 skills les plus populaires sur skills.sh n’ont déclenché aucun des contrôles d’injection de prompt ou de code malveillant de Snyk. La popularité n’est pas une preuve, mais elle aide.

MCP a sa propre version du risque. La documentation de Claude Code avertit que les serveurs qui vont chercher du contenu externe peuvent t’exposer à l’injection de prompt: une page web, un commentaire de ticket ou un rapport de plantage contenant du texte destiné à ton agent plutôt qu'à toi.

Dix habitudes pour rester en sécurité

  1. À lire avant d'installer. Utilisation npx skills add owner/repo --list, gh skill preview, ou ouvre simplement le SKILL.md et ses scripts sur GitHub.
  2. Privilégie les créateurs et les auteurs connus. Les skills d’Expo pour Expo, celles de Vercel pour Next.js, le serveur MCP officiel d’un éditeur pour son propre service.
  3. Vérifie les audits. Chaque skill sur skills.sh affiche les résultats de trois analyseurs : Gen Agent Trust Hub, Socket et Snyk. “En attente” signifie que personne n'a encore regardé.
  4. Fige tout ce qui est important. npx skills add owner/[email protected]ou gh skill install … --pin v1.2.3, pour que les mises à jour arrivent quand tu le décides.
  5. Relis les mises à jour comme du code. npx skills check, puis lis les changements sur GitHub, puis npx skills update.
  6. Contrôle les skills de tiers. Dans OpenCode, les règles utilisent le skill action et la dernière correspondance l'emporte :

jsonc "permissions": [ { "action": "skill", "resource": "*", "effect": "ask" }, { "action": "skill", "resource": "skills-housekeeping", "effect": "allow" }, { "action": "playwright_*", "resource": "*", "effect": "ask" } ]

Hermes Agent analyse chaque installation depuis un hub, et --force ne peut pas passer outre un verdict “dangereux”. Gemini CLI te demande ton accord avant d'activer un skill. 7. Donne aux serveurs le minimum d'accès qui fonctionne. Des jetons en lecture seule et à granularité fine ; des jetons séparés par serveur ; les outils d'écriture et de suppression sur “demander” ou filtrés. 8. Garde les secrets hors des skills et de la configuration commitée. Utilise des variables d'environnement ({env:NAME} dans OpenCode, ${VAR} dans la configuration de Claude Code .mcp.json, ${env:NAME} dans Cursor), jamais de clés collées. 9. Fais attention aux réglages de projet des autres. Un dépôt cloné peut apporter ses propres .mcp.json ou skills. Claude Code demande confirmation avant d'utiliser les serveurs du projet, Gemini CLI garde les serveurs locaux déconnectés dans les dossiers non fiables, et Hermes Agent ne charge les skills du projet qu'après hermes skills trust. Ne valide pas ces invites en pilote automatique. 10. Désinstalle ce que tu n’utilises pas. Chaque skill et chaque serveur inutilisé est une surface d'attaque que tu paies en contexte.

Liste de contrôle sécurité pour les compétences d'agents et MCP : les chiffres de ToxicSkills de Snyk pour 3 984 compétences publiques et dix bonnes habitudes, de la lecture avant l'installation et l'épinglage des versions aux jetons à privilèges minimaux
Un skill, ce sont des instructions que ton agent suit avec tes permissions. Installe-le avec le soin que tu accorderais à n'importe quel autre logiciel.

Partie 12 — Une routine hebdomadaire de deux minutes

Les skills et les serveurs dérivent. Une petite routine les garde honnêtes :

# Skills globales, depuis un dossier neutre
cd /tmp && npx skills@latest check -g

# Chaque projet sur lequel tu travailles activement
cd ~/code/my-app && npx skills@latest check -p

# Après avoir lu ce qui a changé en amont :
npx skills update -g

Une fois par mois, prends cinq minutes de plus :

  • Élague. npx skills ls -g et retire ce que tu n’as pas utilisé. Dans Claude Code, le panneau des extensions liste les extensions que tu n’as pas utilisées récemment.
  • Liste tes serveurs. Liste des MCP OpenCode, claude mcp list, gemini mcp list ou hermes mcp test pour chacun. Supprime ce que tu as oublié d'ajouter.
  • Renouvelle les jetons que tu as donnés aux serveurs, surtout ceux capables d'écrire.

Deux machines, une seule configuration

Je fais tourner des agents sur un Mac et sur un Raspberry Pi, et trois habitudes les gardent synchronisés :

  1. Même approche sur les deux : ton utilisateur normal, jamais sudo, et la CLI lancée depuis un dossier de projet ou /tmp.
  2. Les skills de projet voyagent avec Git. Valider .agents/skills et skills-lock.json; sur l'autre machine, npx skills install restaure exactement les mêmes versions.
  3. Les skills globales viennent d'un script. Garde ton npx skills add … -g les commandes dans un petit fichier shell et l'exécute sur chaque machine. Il sert aussi de documentation de ce sur quoi tu t'appuies.

Sur une machine sans écran comme un Pi, définis GITHUB_TOKEN en ~/.bashrc pour que les vérifications de mise à jour ne tombent pas dans la limite anonyme. Les connexions via navigateur demandent de l'attention : OpenCode te laisse coller l'URL de callback dans son prompt, Hermes Agent propose le collage en retour, la redirection de port SSH ou un device flow, tandis que le flux OAuth de Gemini CLI a besoin d'un navigateur sur la même machine.


Partie 13 — Quelle configuration choisir ? Cinq scénarios

1. “Je débute avec OpenCode.”

Installer trois skills au maximum et un serveur MCP. Context7 est un bon premier serveur, et une skill de release ou de revue qui correspond à ta façon de travailler est une bonne première skill. Garde les skills tierces sur demander dans les permissions d'OpenCode jusqu'à ce que tu leur fasses confiance. Mon guide OpenCode couvre le reste de la configuration.

2. “J'utilise OpenCode et Claude Code côte à côte, peut-être Hermes Agent aussi.”

Installe les skills globalement avec la CLI et nomme chaque agent: npx skills add owner/repo -g -a opencode -a claude-code -a hermes-agent. Une copie, trois agents. Les serveurs MCP ne partagent pas de fichier de configuration commun, alors ajoute chacun à chaque agent et garde la liste quelque part où tu la retrouveras. Mon comparaison d'OpenCode, Hermes Agent et OpenClaw explique où chaque agent brille, et mon comparatif des harnais de codage IA en couvre 28 côte à côte.

3. “Mon équipe partage un dépôt.”

Utilisation portée du projet: commit .agents/skills, skills-lock.json, et les réglages MCP (opencode.jsonc, .mcp.json ou .cursor/mcp.json) sans aucun secret dedans. Chacun garde ses clés dans son propre environnement. Dans la CI, npx skills install --frozen-lockfile échoue si les skills de quelqu'un divergent, et npx skills check -p échoue quand des mises à jour attendent.

4. “Mes agents tournent sur un Raspberry Pi ou un serveur.”

Un utilisateur normal, pas de sudo, jamais. Ensemble GITHUB_TOKEN, privilégie les serveurs distants qui acceptent un jeton dans un en-tête (ou qui proposent une connexion par appareil), et lance la vérification hebdomadaire depuis /tmp. La partie 6 est ta liste de contrôle.

5. “Mon code ne doit pas quitter ma machine.”

Utilisation serveurs MCP locaux uniquement, et évite les serveurs distants de documentation et de recherche de code. Désactive la télémétrie du CLI (DISABLE_TELEMETRY=1), lis chaque skill que tu installes, et rappelle-toi que le modèle lui-même peut rester un modèle cloud : la confidentialité dépend de l'endroit où le modèle tourne aussi. Mon guide pour faire tourner des LLM sur un MacBook explique ce que coûte vraiment la solution entièrement locale.


Foire aux questions

Que sont les agent skills ?

Les skills d'agent sont des dossiers qui apprennent à un agent IA à faire un travail précis. Chacun contient un SKILL.md fichier avec un nom, une description et des instructions étape par étape, plus des scripts et des fichiers de référence facultatifs. L'agent ne lit que les descriptions au début d'une session et charge les instructions complètes d'un skill quand une tâche correspond. Les skills suivent un standard ouvert, donc la plupart fonctionnent aussi bien dans OpenCode, Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot que dans Hermes Agent.

Qu'est-ce qu'un serveur MCP ?

Un serveur MCP est un petit programme qui donne à un agent IA de nouveaux outils via le Model Context Protocol, un standard ouvert désormais hébergé par l'Agentic AI Foundation de la Linux Foundation. Les serveurs locaux tournent sur ton ordinateur et sont démarrés par l'agent ; les serveurs distants tournent sur les ordinateurs d'un fournisseur et sont joints par une adresse web, généralement avec une connexion dans le navigateur. Citons par exemple le serveur officiel de GitHub, Context7 pour une documentation à jour et Playwright pour piloter un navigateur.

Quelle est la différence entre les skills d'agent et les serveurs MCP ?

Un skill donne à l'agent du savoir-faire : des instructions écrites pour faire un travail, chargées seulement au besoin. Un serveur MCP donne à l'agent des capacités : des outils qui atteignent des systèmes en dehors du terminal, comme GitHub, un navigateur ou un outil de suivi des plantages. Utilise un skill pour les procédures et les conventions, un serveur MCP pour l'accès en direct à un système, et AGENTS.md pour les règles qui valent pour chaque tâche. Si un bon outil en ligne de commande existe, un skill qui le présente coûte souvent moins cher qu'un serveur.

Les skills fonctionnent-ils de la même manière dans OpenCode, Claude Code et Codex ?

En grande partie, parce que tous les trois suivent le standard Agent Skills. La différence tient à l'endroit où ils regardent. Codex et OpenCode lisent les .agents/skills et ~/.agents/skills dossiers partagés ; OpenCode lit aussi .opencode/skills et les dossiers de Claude Code. Claude Code ne lit que .claude/skills et ~/.claude/skills. Certains champs supplémentaires du front matter, comme ceux de Claude Code context: fork, ne fonctionnent que dans un seul agent, donc les skills partagés devraient s'en tenir aux champs standard.

Comment installer un skill avec npx skills ?

Courir npx skills add owner/repo --list pour voir les skills proposés par un dépôt, puis npx skills add owner/repo --skill skill-name -a opencode -a claude-code pour en installer un pour les agents que tu utilises. Ajoute -g pour le rendre disponible dans chaque projet. Il te faut Node.js 22.20 ou plus récent. Sans options, le CLI te demande quels skills et quels agents tu veux, et s'il faut lier ou copier les fichiers.

Où npx skills installe-t-il les skills ?

Les installations par projet placent la vraie copie dans .agents/skills/<name> dans ton projet et l'inscrivent dans skills-lock.json. Les installations globales (-g) la placent dans ~/.agents/skills/<name> et l'inscrivent dans ~/.agents/.skill-lock.json. Les agents qui lisent .agents/skills utilisent directement cette copie ; pour les agents qui ont leur propre dossier, comme Claude Code (.claude/skills) ou Hermes Agent (~/.hermes/skills), le CLI crée un lien vers elle.

Comment savoir si mes skills sont à jour ?

Courir npx skills@latest check -g pour les skills globaux, ou npx skills@latest check -p dans un projet. Le CLI compare l'empreinte de chaque dossier de skill dans ton fichier lock avec celle du même dossier en amont et liste tout skill qui a une mise à jour, sans rien installer. Depuis la version 1.7.5 (2 novembre 2026), check se contente de signaler ; npx skills update installe. Lance-le depuis un dossier de projet ou /tmp, pas depuis ton dossier personnel.

Pourquoi npx skills affiche-t-il que tous les skills sont à jour alors que la vérification a échoué ?

Parce que le récapitulatif ne compte que les mises à jour qu'il a trouvées. Si la limite de 60 requêtes API anonymes par heure de GitHub bloque chaque recherche, le CLI affiche une ligne ✗ pour chaque source et peut quand même finir sur “Tous les skills globaux sont à jour”. Connecte-toi avec gh auth login ou définis un jeton en lecture seule GITHUB_TOKEN pour porter la limite à 5 000 requêtes par heure, passe à npx skills@latest, et lis toujours les lignes ✗.

Faut-il utiliser sudo avec npx skills ?

Non. Les skills sont stockés par utilisateur, et root a son propre dossier personnel, donc sudo installe les skills dans /root/.agents/skills, où les agents lancés sous ton utilisateur normal ne les voient jamais. Il peut aussi laisser des fichiers appartenant à root dans tes propres dossiers et déclencher des erreurs npm comme “prefix ne peut pas être modifié depuis la configuration du projet”. Lance la CLI et tes agents sous ton utilisateur normal.

Comment ajouter un serveur MCP à OpenCode ?

Courir opencode mcp add <name> --url <address> pour un serveur distant, ou opencode mcp add <name> -- <command> pour un serveur local, puis vérifie-le avec Liste des MCP OpenCode. Ajoute --global pour l'utiliser dans chaque projet. Les mêmes réglages peuvent se trouver sous mcp.servers en opencode.jsonc, avec les secrets écrits sous la forme {env:NAME}. Utilise opencode mcp auth <name> pour te connecter, et /mcps dans une session pour connecter ou déconnecter des serveurs.

Combien de serveurs MCP faut-il installer ?

Le moins possible, ceux que tu utilises vraiment, généralement deux à cinq. Les outils de chaque serveur viennent avec des descriptions que le modèle doit lire, ce qui consomme du contexte et peut rendre les réponses plus lentes et moins ciblées. Claude Code reporte les définitions d'outils jusqu'au moment où elles sont nécessaires et OpenCode les regroupe par serveur, ce qui aide, mais les serveurs inutilisés ajoutent quand même du risque et de l'encombrement. Supprime tout ce que tu n'as pas utilisé depuis un mois.

Les agent skills sont-ils sûrs à installer ?

Seulement aussi sûrs que leur source. Un skill est un ensemble d'instructions que ton agent suit avec tes permissions, souvent avec des scripts qu'il exécute. L'étude de Snyk de février 2026 sur 3 984 skills publics a trouvé des failles de sécurité dans 36,82 % d'entre eux et confirmé des charges malveillantes dans 76. Lis un skill et ses scripts avant de l'installer, privilégie les skills des créateurs de l'outil, consulte les résultats d'audit sur skills.sh, épingle les versions et garde les skills tiers sur “ask” dans les permissions de ton agent.

Qu'est-ce que skills-lock.json ?

C'est le fichier de verrouillage du projet que la CLI skills écrit quand tu installes des skills dans un projet. Il enregistre l'origine de chaque skill et une empreinte de ses fichiers. Commite-le dans Git : sur un autre ordinateur, npx skills install restaure exactement les mêmes compétences, et --frozen-lockfile échoue si quoi que ce soit diffère. Les skills globaux ont un fichier de verrouillage séparé dans ~/.agents/.skill-lock.json, un par compte utilisateur.

Qu'est-ce que skills.sh ?

skills.sh est l'annuaire public de skills pour agents de Vercel. Il classe les skills par nombre d'installations, les regroupe par thème et affiche pour chacun les résultats d'audit de sécurité de Gen Agent Trust Hub, Socket et Snyk. Tu y installes des skills avec la npx skills add owner/repo commande qu'il affiche. La commande npx skills find de la même CLI parcourt l'annuaire depuis ton terminal.

En résumé

Les agent skills et les serveurs MCP répondent à deux questions différentes. Les skills répondent à “comment fait-on ici ?”: ce sont des fiches recettes peu coûteuses et transportables qui ne se chargent qu'en cas de besoin. Les serveurs MCP répondent à “peux-tu atteindre ce système ?”: ce sont des clés puissantes qui coûtent du contexte et méritent le même soin que n'importe quel logiciel que tu installes. AGENTS.md contient les quelques règles qui s'appliquent à tout, et les permissions font respecter ce qui ne doit jamais arriver.

Si tu ne retiens que cinq choses de ce guide, retiens celles-ci :

  1. Mets les skills partagés dans .agents/skills et laisse npx skills créer des liens vers eux pour les agents qui regardent ailleurs.
  2. Courir npx skills@latest check depuis un dossier de projet ou /tmp, lis les lignes ✗ et mets à jour délibérément.
  3. Connecte-toi à GitHub (gh auth login) sur chaque machine qui vérifie les mises à jour.
  4. N'utilise jamais sudo avec les skills ou les agents.
  5. Commence avec trois skills et un serveur, et n'en ajoutes d'autres que lorsqu'une vraie tâche le demande.

Les skills et les serveurs transforment un brillant généraliste en un collègue qui connaît ta façon de travailler et peut accéder à tes outils. L'astuce consiste à lui donner exactement ce dont il a besoin, et rien de superflu.


Tu utilises des skills ou des serveurs MCP dont je n'ai pas parlé ? J'aimerais savoir lesquels ont trouvé une place permanente dans ta configuration, et quels messages d'erreur t'ont envoyé chercher. Les corrections sont les bienvenues : cet article est mis à jour quand les outils changent, ce qui, à en juger par cette année, arrivera souvent.

Mention légale : Aucune entreprise mentionnée dans cet article ne l'a sponsorisé, relu ou approuvé, et il ne contient aucun lien d'affiliation. Les produits sont simplement nommés dans le texte ; les images utilisent mes propres logos.

Dernière mise à jour : 15 novembre 2026.

Ajoute ton signal.

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

fr_FRFrançais