make-skill — Créer, Auditer et Livrer des Skills

make-skill — Créer, Adapter et Livrer des Skills de Manière Éprouvée

Copie depuis un dépôt de travail (généralement ~/DATA/<nom>) : ssheleg/super-ux (suite multi-skills, règles Cursor) ou ssheleg/task-pipeline (orchestrateur mono-skill, automatisation de version). make-skill lui-même est construit selon ce canon.

Références — charger à la demande

Lecture	Quand
references/agent-skills-spec.md	rédiger ou auditer TOUT SKILL.md — limites strictes des deux autorités, champs optionnels, budgets, qui rejette quoi
references/authoring.md	rédiger ou ajuster un corps/description — nommage, troisième personne, degrés de liberté, règles de script, boucles d'évaluation
references/surfaces.md	livrer ailleurs que sur Claude Code — upload Skills API/versions/8-par-requête, claude.ai zip, limites sans réseau
references/enterprise.md	installer le skill d'autrui, ou gérer une flotte — niveaux de risque, checklist de révision, portes d'approbation, cycle de vie
references/retrofit.md	auditer un skill/dépôt existant — la checklist en 14 points, les règles de preuve, le formulaire court pour skill personnel
references/host-capabilities.md	livrer un hook, sous-agent, commande, script ou dépendance MCP — ce que chacun apporte et coûte, événements de hook et codes de sortie, clauses de dégradation
references/claude-code-plugin.md	tout ce qui est livré comme plugin/marketplace Claude Code — schémas de manifeste, disposition des composants, variables de chemin, échecs de validate
references/distribution.md	la structure du dépôt, les versions, et les cinq canaux — plugin, CLI skills, npx, Cursor, dépôt famille parapluie
references/mcp.md, references/mcp-ship.md	skill vs serveur MCP, en envelopper un — puis le livrer : montage, son 404, server.json, le registre
references/a2a.md	le skill couvre deux agents autonomes (A2A) : Cartes Agent, cycle de vie des tâches, délégation

Manquant dans cette copie ? Repli brut : raw.githubusercontent.com/ssheleg/make-skill/main/plugins/make-skill/skills/make-skill/references/<fichier>

Choisir un workflow

Détecter depuis la requête et tout chemin dans $ARGUMENTS ; annoncer le choix.

Situation	Workflow
Nouveau skill, uniquement pour les agents de cet utilisateur	Créer (personnel)
Nouveau skill, installable par d'autres/autres agents	Créer (distribuable)
Skill ou dépôt existant en dessous de ce standard, « correspond-il à la spec ? »	Retrofit
Skill personnel doit devenir installable	Promouvoir

Sans argument, détecter au lieu de demander : un SKILL.md, .claude-plugin/ ou plugins/*/skills/*/ dans le répertoire courant → exécuter l'audit Retrofit et signaler le tableau des écarts PLUS UNE prochaine action. Rien à détecter → demander en une ligne quoi créer.

Un travail distribuable est un vrai projet : spec (docs/superpowers/specs/) avant le code, et la spec verrouille les contrats des fichiers du projet cible EN PREMIER — les skills sont écrits contre ce contrat, jamais ad hoc.

Règles de rédaction (chaque workflow)

La spec d'abord — la norme ouverte et les règles de plateforme d'Anthropic sont toutes deux non négociables ; ce canon ne fait qu'ajouter par-dessus. Tableaux de champs, leurs différences et la checklist : references/agent-skills-spec.md.

• name : règles de caractères dans references/agent-skills-spec.md ; égal au nom du répertoire. Le piège : ne contient jamais anthropic ou claude — sous-chaînes réservées que Claude Code charge volontiers et que l'API Skills rejette au téléversement, donc l'échec apparaît sur la machine de quelqu'un d'autre.
• description : ≤1024 caractères (la limite porte sur ce champ uniquement, pas tout le bloc de front-matter), pas de chevrons, troisième personne — elle est injectée dans le prompt système, où « Je peux vous aider… » dégrade la sélection. Indique CE qu'il fait et QUAND l'utiliser.
• L'ensemble optionnel portable est license, compatibility, metadata et allowed-tools — limites et types dans references/agent-skills-spec.md.
• license est optionnel — déclarez-le quand même, dans le front-matter ET l'entrée plugin marketplace.json : un fichier LICENSE racine n'atteint ni la liste du plugin ni un skill installé, et rien ne génère d'erreur, donc l'écart reste ouvert (les six dépôts ici, 2026-07-30).
• Les extensions hôte sont légales, jamais essentielles. Claude Code lit un ensemble supplémentaire réservé à l'hôte (references/claude-code-plugin.md) ; les autres agents l'ignorent, donc un skill qui EN DÉPEND est cassé partout ailleurs. Hors spec ∪ hôte = faute de frappe.
• Corps < 500 lignes et < 5000 tokens, et gardez 5% de marge — un corps à 99% du budget transforme la prochaine correction en combat avec le validateur. Le matériel plus lourd va dans references/, scripts/, assets/ À L'INTÉRIEUR du répertoire du skill, à un niveau de profondeur, chacun lié depuis le corps avec un déclencheur de chargement énoncé (« lire X quand Y ») — jamais un simple « voir references/ ». Les fichiers de référence de >100 lignes commencent par une liste ## Contenu : une lecture partielle de head est ce que les agents obtiennent.
• Les pièges restent dans SKILL.md : l'agent ne peut pas savoir qu'il doit ouvrir un fichier sur un piège dont il ignore l'existence.
• Écrivez pour la surface la plus faible que vous revendiquez (references/surfaces.md) : le conteneur de l'API Claude n'a PAS de réseau et PAS d'installation de paquets, claude.ai varie, seul Claude Code a les deux. Un script qui pip install ou curl est un skill Claude Code — dites-le dans compatibility ou abandonnez-le. Rien ne se synchronise entre les surfaces ; git est la source de vérité.

Ajouts maison par-dessus la spec :

• La prose est en anglais ; un littéral reste dans la langue où il est saisi. Le cyrillique ne survit qu'à quatre endroits, où la chaîne elle-même est le point important : une phrase déclencheur, une phrase de refus (l'opérateur tape les deux — traduites, elles ne correspondent plus à ce qui a été dit), un nom propre, un exemple de langue («вы»/«ты»). Une règle de budget avant une règle de style : le russe s'encode à 1,9–2,3 caractères/token contre 5,0 pour l'anglais (cl100k), et la réécriture en anglais des huit routeurs ssheleg les a réduits de 3408 à 1885 tokens sans perte de sens.
• description commence par « Utiliser quand … » et liste des phrases déclencheur concrètes — anglais ET russe (l'utilisateur travaille dans les deux). Un skill que personne ne déclenche est un poids mort. Gardez 5% de marge ici aussi (≤970 sur 1024) : un voisin très proche force une clause « PAS pour … », et une description à 98% de la capacité n'a nulle part où la mettre.
• Un seul schéma de nommage, de préférence un gérondif (processing-pdfs) ; jamais helper, utils, tools, data — les noms vagues perdent toute sélection.
• Un skill = un travail. Plusieurs préoccupations → plusieurs skills + un fichier de contrat partagé. Mettez les contrats À L'INTÉRIEUR du répertoire du skill (references/…) : le CLI skills ne livre que le propre répertoire du skill, donc un répertoire skills/references/ FRÈRE fonctionne comme plugin Claude Code et arrive cassé sur tout autre agent. Partagé entre skills → dupliquez par répertoire de skill, vérifié identique par le validateur.
• Corps : impératif, procédural, listes de contrôle plutôt que prose ; les non-négociables sont énoncés comme tels. Faites correspondre la directivité à la fragilité — commandes exactes pour le travail destructeur ou dépendant de l'ordre, orientation uniquement là où le contexte décide (references/authoring.md).
• Évaluations avant la prose : exécutez la tâche cible SANS skill, enregistrez les échecs, écrivez ≥3 évaluations contre eux, puis écrivez le minimum qui réussit ; un skill construit sans base de référence documente des problèmes imaginés. Ajouter à une famille existante → mesurez la coexistence par rapport à l'ensemble INSTALLÉ, ne le devinez pas : le voisin que vous nommeriez n'est généralement pas le plus proche.
• Livrez un point d'entrée en une commande : idempotent — inspecter l'état → réparer les pièces manquantes → rapport d'état → EXACTEMENT UNE action suivante suggérée. Détectez le mode, ne demandez jamais. Le skill EST cette commande ; l'invocation diffère par canal (/<skill> depuis un répertoire de skills, /<plugin>:<skill> comme plugin) — écrivez les deux dans le README plutôt que d'en promettre un.
• Ne jamais écraser les données utilisateur : ne créez que lorsqu'absent ; n'écrasez que derrière --force.

Contrat de dégradation (chaque skill qui touche une capacité hôte)

Les hooks, sous-agents, /commands, variables de chemin de plugin et serveurs MCP n'existent qu'à l'intérieur de Claude Code — une minorité des endroits où les skills s'exécutent. Chacun est un accélérateur avec une solution de repli écrite ; le skill termine quand même son travail sans lui, mais plus lentement. Écrivez les trois cas dans le corps, avec les mots de l'agent, au point où il en aura besoin (formes : references/host-capabilities.md) :

• Pas Claude Code (Cursor, Codex, CLI skills, API) : pas de hooks, pas de sous-agents, pas de /command. Nommez la procédure en ligne ; les scripts/ groupés voyagent toujours, donc donnez le chemin par canal.
• Plugin/skill recommandé absent : dites une fois ce qui est dégradé, continuez sur la voie manuelle. Une étape qui refuse de démarrer parce qu'un compagnon optionnel est manquant est cassée, pas stricte.
• Outil, interpréteur ou serveur MCP absent : dites-le une fois, retombez sur la procédure manuelle, ne réessayez jamais en boucle. L'authentification interactive est une étape humaine.

Un repli que vous connaissez mais n'avez pas écrit n'est pas un repli.

Exemples de travail fournis avec ce skill — copiez-les, pas votre mémoire

scripts/audit_skill.py audite TOUT répertoire de skill (stdlib ; la moitié mécanique d'un Retrofit), enveloppé comme bin/make-skill-audit pour Claude Code. À côté : hooks/ (PostToolUse, silencieux sauf si un SKILL.md a été écrit), commands/skill-audit.md (délibérément PAS le nom du skill), agents/skill-auditor.md, et six squelettes : assets/SKILL.template.md, assets/plugin.template.json, assets/marketplace.template.json, assets/hooks.template.json, assets/agent.template.md, assets/command.template.md.

Créer (personnel)

~/.claude/skills/<nom>/SKILL.md selon les règles de rédaction — c'est fait. Pas de dépôt, pas de versionnage ; chargé à la session suivante. Mentionnez Promouvoir comme voie de mise à niveau.

Besoin de hooks, d'un agent ou d'un serveur MCP, toujours sans dépôt ? Ajoutez .claude-plugin/plugin.json dans ce même dossier — Claude Code le charge comme <nom>@skills-dir à la session suivante.

Créer (distribuable)

L'arborescence du dépôt, le plancher du dépôt public, les deux exécutions de claude plugin validate … --strict et la spec du validateur maison sont dans references/distribution.md → La structure du dépôt distribuable. Ouvrez-le avant le premier fichier. Ce qui tient quoi qu'il arrive :

• .claude-plugin/marketplace.json à la racine du dépôt ; le plugin sous plugins/<nom>/ avec son propre .claude-plugin/plugin.json ; le skill à plugins/<nom>/skills/<skill>/ avec references/, scripts/, assets/ À L'INTÉRIEUR. Seuls les manifestes vivent dans .claude-plugin/ — les composants enterrés là se chargent comme rien alors que le plugin semble toujours fonctionner.
• Synchronisation des versions (règle stricte) : marketplace.json, plugin.json, package.json et l'entrée CHANGELOG la plus haute portent la MÊME version sémantique, incrémentée ensemble (+ un 5ème point si SKILL.md porte metadata.version).
• Les deux exécutions --strict sont vertes, en CI, comme leur propre job — elles ne lisent que les MANIFESTES, donc les règles de front-matter vivent dans votre propre test/validate.py, qui a besoin d'un auto-test négatif : un validateur qui ne peut pas échouer est une décoration. Livrez $schema et displayName dans plugin.json ET l'entrée du marketplace (la racine du marketplace n'en prend aucun).
• Un dépôt public doit au lecteur un README priorité anglais, CONTRIBUTING.md avec les commandes hors ligne qui vérifient un changement, et SECURITY.md nommant un canal privé et ce que les installateurs touchent.

Première publication — de bout en bout, même session

Allez JUSQU'AU BOUT, pas de relais à moitié fait. Seule la première publication nécessite un humain (npm 2FA) ; armer la publication CI fait partie de la livraison, donc la seconde non. La séquence en 11 étapes est dans references/distribution.md → Première publication. Fait = cinq faits VÉRIFIÉS : dépôt + CI verts, npm résoluble via npx, plugin installé, découverte skills-CLI fonctionnelle, prochaine publication de tag sans humain.

Retrofit (mettre un skill/dépôt existant à niveau)

Auditez d'abord, corrigez ensuite, dans la même session. Verdict par élément : PASS / GAP / NOT-RUN avec preuve — un fichier:ligne ou la sortie de la commande que vous avez réellement exécutée. « Ça a l'air bien » n'est pas un verdict, et ce n'en est pas un non plus sur un élément qui a été raisonné au lieu d'être exécuté ; un élément dont l'outil est absent est NOT-RUN avec la raison, jamais un PASS.

Exécutez d'abord l'auditeur fourni — il fait la moitié mécanique de manière déterministe, et il ne dépend jamais d'une variable non définie :

make-skill-audit <skill-dir> --house    # Claude Code : le bin/ du plugin est dans le PATH

Ailleurs, exécutez scripts/audit_skill.py depuis le répertoire make-skill que vous venez de lire. Ensuite, travaillez la checklist en 14 points dans references/retrofit.md — plancher spec, plancher plugin, surfaces, mono-travail, point d'entrée, structure et synchronisation de version, validateur et CI, évaluations, README, distribution, métadonnées du dépôt, pièges, protocoles, capacités hôte. Pour un skill PERSONNEL, seuls trois éléments s'appliquent ; ce fichier dit lesquels.

Ensuite : rapportez le tableau des écarts, corrigez tout ce qui peut être corrigé maintenant, incrémentez une version mineure/corrective, exécutez la checklist de publication.

Promouvoir (personnel → distribuable)

Créez le dépôt selon la structure, déplacez le skill dans plugins/<nom>/skills/<skill>/, extrayez les contrats vers references/, puis exécutez la Première publication de bout en bout. Supprimez l'ancienne copie ~/.claude/skills/<skill> UNIQUEMENT APRÈS que l'installation du plugin a été vérifiée.

Installer le skill de quelqu'un d'autre

Un skill est des instructions qu'un agent exécute plus du code qu'il exécute sans le lire — en installer un, c'est installer un logiciel. Tout ce que vous n'avez pas écrit passe par la checklist de révision dans references/enterprise.md EN PREMIER. La forme au plus haut risque : un skill qui récupère ses instructions depuis une URL — ce contenu change après la révision qui l'a approuvé.

Skills connectés par protocole (MCP / A2A)

Un skill est des instructions ; il ne peut pas octroyer de capacité. Enseigner le COMMENT à l'agent est un skill. Une nouvelle capacité contre un système en direct est un serveur MCP (mcp.md, puis mcp-ship.md pour le monter et le publier). Déléguer un résultat à un autre agent autonome est A2A (a2a.md). Les deux références portent les règles au niveau du fil — découverte du nom d'outil par hôte, Cartes Agent, et l'authentification interactive comme étape humaine plutôt que...