Une skill, c'est un dossier. skills.sh ne fait que le poser.

Je colle la même checklist dans chaque fenêtre de chat. À quoi doit ressembler une pull request ici. Quand l'agent doit s'arrêter au lieu de dire « terminé ». Comment un article se construit sur ce site. AGENTS.md est déjà long — et il grossit à chaque exception.

C'est à ça que servent les skills. Et skills.sh est la partie qui les trouve et les pose.

La réponse courte

Une skill est un dossier avec un fichier nommé SKILL.md. Il dit ce que l'agent doit faire et quand. Des scripts, des textes de référence et des modèles peuvent rester à côté. L'agent ne voit d'abord que le nom et la description. Il charge le reste quand la tâche correspond.

skills.sh est l'annuaire public et la CLI qui va avec, opéré par Vercel. Le format vient d'Anthropic et vit à l'air libre sur agentskills.io. Le site n'est pas la spécification. La CLI n'est pas l'agent.

Installer :

npx skills add vercel-labs/agent-skills

La CLI détecte quels agents vous avez en local et dépose les dossiers là où ils les cherchent : .claude/skills/ pour Claude Code, .agents/skills/ pour Cursor, et ainsi de suite. Par défaut, c'est le projet courant. Avec -g la skill atterrit dans votre répertoire home et s'applique partout.

La doc officielle est skills.sh/docs, la CLI est sur GitHub. Ce qui suit est la version que j'aurais voulu avoir : en quoi une skill diffère de MCP et de AGENTS.md, comment en trouver une sans croire le classement — et les endroits où elle échoue sans bruit.

Trois noms, une confusion

Agent Skills est le dossier. Du frontmatter YAML avec name et description, du Markdown en dessous. C'est la spécification. Un agent qui la parle peut lire le même dossier — Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI et des dizaines d'autres. La liste à jour est dans le README de la CLI.

skills.sh est npm pour ces dossiers. Le site montre ce que les gens installent. La CLI (npx skills) copie ou lie vers le chemin que votre agent connaît. Vous pouvez poser le même dossier à la main, sans CLI. Vous pouvez utiliser la CLI sans le site. Ni l'un ni l'autre n'est le format.

Le chemin local est l'endroit où votre agent cherche. Une skill dans ~/.claude/skills/ est invisible pour Cursor. Une qui ne vit que dans .agents/skills/ est invisible pour Claude Code. La CLI fait le câblage — si vous lui dites pour quel agent.

Cherchez « skills » et vous tombez sur Anthropic, ou Vercel, ou un classement de comptes d'installations. Trois couches. Seule la première est la capacité. Les deux autres la transportent.

Skill, MCP ou AGENTS.md

Trois mécanismes que les gens jettent dans le même seau :

AGENTS.md et CLAUDE.md sont toujours allumés. Des faits sur le dépôt, des conventions, des choses qui doivent être vraies à chaque session. Quand le fichier devient une procédure — une checklist, un flux en plusieurs étapes, « lis X d'abord, puis Y » — ça va dans une skill. La description coûte quelques tokens. Le reste ne charge que si la tâche correspond.

Une skill est du savoir procédural. Quand agir, dans quel ordre, comment vous savez que c'est fini, quels pièges existent. Elle peut apporter des scripts que l'agent exécute au lieu de les réécrire à chaque fois.

MCP accroche des outils : APIs, bases de données, le navigateur. L'agent peut alors appeler quelque chose. Une skill lui dit quand et comment. Les deux se complètent. Un MCP navigateur sans skill clique quelque part. Une skill sans outil décrit des étapes que l'agent ne peut pas faire.

Règle : si ça appartient à chaque session, ça va dans AGENTS.md. Si vous répétez la même procédure, ça devient une skill. Si l'agent a besoin d'une interface externe, c'est MCP.

Installer une skill

Il vous faut Node pour que npx existe, et au moins un agent que la CLI connaît. Ensuite la forme courte owner/repo suffit :

npx skills add vercel-labs/agent-skills

C'est l'exemple de la doc officielle. Ça clone le dépôt, cherche les SKILL.md et demande quelles skills et quels agents. Pour le CI, ou si vous ne voulez pas les questions :

npx skills add vercel-labs/agent-skills --skill frontend-design -a claude-code -y

--skill prend un nom, ou '*' pour toutes. -a vise un agent (claude-code, cursor, codex, …). -g écrit dans ~/ plutôt que dans le projet. --copy copie au lieu de lier ; les symlinks sont la recommandation, parce qu'une mise à jour n'a alors qu'une source.

Ça n'a pas besoin d'être le raccourci GitHub. URL GitHub complète, GitLab, n'importe quelle URL git, un chemin local, même un SKILL.md direct ou une archive. Les dépôts privés utilisent l'auth que Git a déjà — pas de jeton en plus, sauf si vous posez GITHUB_TOKEN exprès.

Après l'exécution :

npx skills list

Dans Claude Code le dossier devrait être sous .claude/skills/<name>/, dans Cursor sous .agents/skills/. Tapez / et cherchez le nom, ou posez une question qui colle à la description. Si rien ne se passe : vérifier le YAML, vérifier le chemin, relancer l'agent. La CLI journalise le chemin cible ; ne devinez pas.

Utiliser une skill sans l'installer :

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

Ça écrit les fichiers dans un répertoire temporaire et imprime un prompt. Avec --agent la CLI lance l'agent. Utile pour tester. Pour quelque chose que vous voulez garder, préférez add.

Les équipes peuvent assembler un pack sur skills.sh : plusieurs skills, y compris privées, une URL d'install de la forme npx skills add https://skills.sh/p/<id>. Les packs sont unlisted, pas contrôlés à l'accès. Quiconque a l'URL peut installer. N'y mettez pas de secrets.

Chercher sans croire le classement

Le site a All Time, Trending (24h) et Hot. Les chiffres viennent de la télémétrie anonyme de la CLI — allumée par défaut, dédupliquée toutes les heures : quelle skill, sur quel agent. Pas de contenu, pas de personnes. On coupe avec DISABLE_TELEMETRY=1 ou DO_NOT_TRACK=1.

Le classement compte des installations, pas de la qualité. Une méta-skill qui aide à chercher collectionne des installs parce que la CLI la propose — pas parce qu'elle résout votre vrai problème. Packs Azure, kits de design, pipelines vidéo : un gros chiffre veut dire « beaucoup de gens ont lancé npx skills add », souvent pour un dépôt entier d'un coup.

Mieux :

npx skills find

Sans argument, une recherche interactive ; avec un argument, un mot-clé (npx skills find typescript). --owner vercel limite aux dépôts de cette org. Puis lire le SKILL.md avant d'installer. skills.sh montre pour chaque entrée la source, les audits de sécurité des partenaires et sur quels agents elle atterrit. Les skills qui échouent chez tous les partenaires sortent de l'annuaire. Ce n'est pas un chèque en blanc. Anthropic dit la même chose dans sa propre doc : une skill peut apporter des instructions et du code. Traitez-la comme un logiciel que vous installez.

Être au classement veut dire que des gens ont lancé npx skills add owner/repo. Il n'y a pas de revue qui vous admet. Il n'y en a pas non plus qui retire une mauvaise skill, tant que les audits ne tombent pas.

En écrire une

La troisième fois que vous versez les mêmes consignes dans une fenêtre de chat, c'est le moment.

npx skills init my-skill

crée un SKILL.md. Les deux champs obligatoires :

---
name: my-skill
description: What this skill does and when to use it
---

name est en minuscules, tirets, 64 caractères max, identique au nom du dossier. description dit les deux : ce qu'elle fait et quand l'agent doit la charger. « Helps with PDFs » est trop mince. « Extracts text and tables from PDF files, fills forms, merges files. Use when handling PDFs. » vise juste, parce que l'agent tient la description contre votre message.

Le reste est du Markdown. Étapes, exemples, bords. La spécification recommande de garder SKILL.md sous 500 lignes et de pousser le détail dans references/. Les scripts dans scripts/. Les modèles dans assets/. L'agent ne charge ces extras que si les consignes pointent dessus.

Une bonne skill est ennuyeuse à lire. Elle dit quoi faire, à quoi on voit que c'est en place, et quand s'arrêter. Elle n'explique pas pourquoi les skills sont l'avenir. L'agent ne le remarque pas, et vous ne voulez pas dépenser les tokens là-dessus.

Pour distribuer, un dépôt GitHub public suffit, du moment que la CLI trouve un SKILL.md — à la racine, sous skills/, ou dans les chemins que l'agent utilise lui-même (.claude/skills/, .agents/skills/, …). Dès que quelqu'un lance npx skills add dessus, elle apparaît dans la télémétrie.

Quand elle ne part pas

La liste habituelle, dans l'ordre où je vérifie :

1. Le dossier est-il là où cet agent cherche ? Claude Code ne regarde pas dans ~/.cursor/skills/.
2. name et description sont-ils du YAML valide ? Sans les deux champs, la CLI ne trouve pas la skill.
3. La description colle-t-elle à la tâche ? Si elle dit seulement « utility for developers », l'agent ne la charge jamais. La description est l'index.
4. Avez-vous installé en global et l'attendez-vous dans le projet — ou l'inverse ?
5. Quelqu'un a-t-il posé disable-model-invocation ? Alors vous devez l'invoquer vous-même avec /name. C'est un champ Claude Code, pas une partie de la spécification ouverte.

npx skills list montre ce que la CLI croit installé. L'agent a sa propre vue. Tenez les deux contre le chemin, pas l'un contre l'autre.

Et : une skill qui lance un script tourne avec les mêmes droits que l'agent. Lisez SKILL.md et tout ce qu'il y a sous scripts/ avant d'appuyer sur -y.

Ce que je fais vraiment tourner

Sur ce site il y a des skills pour la couverture d'un article, pour les infographies et pour le texte qui sonne chatbot. Ce sont des dossiers. Je ne les ai pas prises sur le classement. Je les ai écrites parce que j'expliquais le même flux à chaque fois.

Je n'installe pas quarante pièces « au cas où ». Chaque description siège dans le contexte dès le départ. Vingt skills vagues coûtent plus cher et ratent plus que trois précises. Celles que je garde ont un bord net : cette procédure que je retaperais sinon.

Si une skill ne part pas chez vous et que vous préférez ne pas passer la soirée dans du YAML, écrivez-moi. Parfois il manque juste la phrase « Use when… » dans la description.