ahundt/ai-skill-builder

AI Skill Builder

Construisez des Skills Agent en utilisant le format partagé SKILL.md et la méthodologie Anthropic : le noyau portable le plus petit qui fonctionne dans chaque environnement cible nommé, plus des adaptateurs d'exécution explicites. La portabilité est une revendication de compatibilité testée, pas un style de formatage. references/sources.md cite la documentation hôte pour Claude Code, Codex, et Qwen Code ; tout autre hôte n'est pas testé ici, donc vérifiez celui que vous ciblez (Étape 1).

Cette méthodologie exige délibérément des régions XML sémantiques cohérentes à l'intérieur du corps Markdown. Il s'agit d'une règle de qualité pour réduire l'ambiguïté dans les instructions opérationnelles complexes, soutenue par les directives actuelles d'Anthropic sur les invites et vérifiée par les tests avancés de l'Étape 4. Ce n'est pas une exigence de l'analyseur de la spécification des Skills Agent portables, ni une frontière d'autorisation, ni une affirmation que le XML seul empêche l'injection d'invites.

Source méthodologique principale : "The Complete Guide to Building Skills for Claude" (Anthropic, January 2026)

• PDF : https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
• Texte extrait : references/ai-skill-builder-guide.md

Source du format portable : https://agentskills.io/specification

---

Démarrage rapide

Pour créer un skill à partir de zéro, suivez le processus en 4 phases ci-dessous. Pour améliorer un skill existant, lisez references/refining-skills.md. Pour valider la structure, exécutez scripts/audit-skill.sh.

Invoquez avec : demandez ai-skill-builder ; les hôtes peuvent l'exposer comme /ai-skill-builder, $ai-skill-builder, ou via leur sélecteur de skills.

Exigences P0

Chaque skill produit par cette méthodologie satisfait aux treize exigences. Citez-les par leur ID dans les audits et les revues.

1. SKILL-REQ001-découvrir-les-environnements-cibles. Identifiez les produits exacts, versions, modes d'invocation, racines d'installation, limites de confiance et sémantique des systèmes de fichiers avant la rédaction.
2. SKILL-REQ002-séparer-standard-et-extensions. Conservez la spécification des Skills Agent, les extensions d'exécution et les conventions de projet dans des colonnes séparées. Ne présentez jamais un champ spécifique à Claude, Codex, Copilot, Gemini ou un framework comme universel.
3. SKILL-REQ003-utiliser-un-noyau-portable-valide. Placez un fichier SKILL.md requis dans un répertoire dont le nom correspond à son name portable ; incluez une description spécifique qui dit ce que le skill fait et quand l'utiliser. N'utilisez les champs optionnels standard que si nécessaire.
4. SKILL-REQ004-utiliser-des-régions-xml-sémantiques. Entourez chaque région opérationnelle majeure de balises XML cohérentes et descriptives à l'intérieur du corps Markdown, comme <purpose>, <requirements>, <workflow>, <examples> et <output_contract>. Conservez le Markdown à l'intérieur de ces régions et le code source littéral dans des blocs de code délimités. Cette règle méthodologique obligatoire vise la meilleure qualité de séparation des instructions ; ce n'est pas une exigence de l'analyseur des Skills Agent ou une frontière de sécurité. scripts/audit-skill.sh échoue si le corps n'a pas de région, une balise déséquilibrée ou mal imbriquée, ou un titre ## en dehors de chaque région.
5. SKILL-REQ005-concevoir-une-divulgation-progressive. Gardez la description d'activation précise et le flux de travail principal concis. Déplacez les détails réellement conditionnels dans des références ciblées et directement liées ; conservez l'automatisation réutilisable dans des scripts et les supports de sortie dans assets.
6. SKILL-REQ006-préserver-le-contexte-opérationnel. Chaque référence ou script doit dire quand l'utiliser, quelles entrées il accepte, ce qu'il retourne ou change, et comment l'échec est signalé. Évitez les chaînes de références profondes.
7. SKILL-REQ007-rendre-l-invocation-correcte. Testez l'activation automatique et l'invocation explicite. Lorsqu'un environnement d'exécution prend en charge les paramètres, testez les entrées vides, positionnelles, nommées, entre guillemets, Unicode, invalides et volumineuses. Ne supposez pas qu'un autre environnement d'exécution implémente la même syntaxe de substitution.
8. SKILL-REQ008-minimiser-l-autorité-des-outils. Traitez les skills et les scripts inclus comme des dépendances exécutables. Demandez la moindre autorité nécessaire, validez les entrées, conservez les invites d'approbation lorsque c'est pratique, et ne décrivez jamais les délimiteurs d'invite comme une prévention d'injection d'invite.
9. SKILL-REQ009-valider-chaque-harnais. Validez la découverte, le chargement, les références, les scripts, les arguments, les liens symboliques, la résolution des doublons, les mises à jour et la suppression dans chaque harnais pris en charge. Le fait de passer un analyseur ne prouve pas la compatibilité entre environnements d'exécution.
10. SKILL-REQ010-préserver-l-état-utilisateur. L'installation et la désinstallation doivent posséder des chemins générés exacts, préserver les modifications manuelles, prendre en charge plusieurs racines de skills configurées, et supprimer uniquement les liens ou fichiers appartenant à l'installateur.
11. SKILL-REQ011-mesurer-le-contexte-et-le-coût-d-exécution. Enregistrez la taille des métadonnées de découverte, la taille des instructions chargées, le coût des références conditionnelles, le temps/mémoire/E/S des scripts, et le chargement en double. Traitez les cibles de lignes et de tokens comme des heuristiques, sauf si un environnement d'exécution cible les rend normatives.
12. SKILL-REQ012-tester-vers-l-avant-avec-des-tâches-réelles. Utilisez des invites réalistes positives, négatives, ambiguës et adversariales. Vérifiez le résultat de la tâche, pas seulement si le skill est apparu dans une liste.
13. SKILL-REQ013-séparer-la-création-de-l-exécution. Classez si la tâche consiste à modifier le skill, utiliser le skill pour produire un artefact ou un résultat, ou évaluer le skill à partir de preuves. Les entrées d'exécution, les sorties générées, les exemples et les observations de dogfood ne deviennent pas des instructions de skill à moins qu'une décision explicite de création ne les accepte et ne les généralise.

Les noms de régions suivent la tâche plutôt qu'une taxonomie universelle : les workflows utilisent <workflow>, les skills de référence peuvent utiliser <decision_guide>, les skills multi-modes <routing>, les contrats de résultats stricts <output_contract>, le matériel de référence en ligne <reference>, et les pointeurs vers des fichiers et sources inclus <resources>. Les balises doivent être cohérentes, descriptives, équilibrées et pas plus profondément imbriquées que la tâche ne l'exige. La matrice standard-extension, l'audit de revendication et le reçu de validation par hôte se trouvent dans references/portability-and-claim-audit.md.

Comment ça fonctionne

Méthodologie en quatre phases du guide Anthropic. Chaque phase comporte une Définition de Terminé : la condition qui doit être remplie avant que la phase suivante ne commence.

Phase	Activité	Définition de Terminé
1 : Planification & Conception	Définir les hôtes cibles, les cas d'utilisation, la catégorie, les critères de succès	Les critères sont mesurables et la catégorie est choisie
2 : Implémentation	Créer le dossier, écrire SKILL.md, ajouter les ressources	audit-skill.sh ne signale aucune erreur
3 : Test	Tests de déclenchement, fonctionnels, de performance, de compatibilité, tests avancés	Chaque hôte nommé réussit avec un reçu de validation ; référence enregistrée
4 : Distribution	Empaqueter, documenter, publier	Installation vérifiée à partir d'une racine propre

La phase 1 couvre les Étapes 1–2 ci-dessous ; les Phases 2–4 correspondent aux Étapes 3–5.

La durée d'une phase dépend de qui ou quoi l'exécute, donc ce skill ne fournit aucune estimation en temps réel et les skills que vous construisez ne devraient pas non plus.

---

Flux de travail de création de skill

Étape 1 : Découvrir les exigences

Recherchez d'abord le domaine — utilisez les outils web de l'hôte pour vérifier les meilleures pratiques actuelles avant d'écrire des instructions. Des conseils obsolètes sont pires que rien : un agent les suit avec confiance.

Conservez toutes les sources : enregistrez chaque URL consultée avec une note de ce qu'elle a confirmé. Les conseils sans source ne peuvent pas être vérifiés ou mis à jour.

Pour les stratégies de recherche, les normes de qualité des sources et le format requis de la section Sources : references/research.md

1. Classez la demande : création (modifier le skill), exécution (utiliser le skill pour produire un résultat), ou évaluation (juger le skill à partir de preuves). Nommez l'artefact et la frontière de mutation avant d'utiliser le contenu de la tâche comme entrée de conception (SKILL-REQ013).
2. Identifiez le problème et les utilisateurs cibles
3. Identifiez chaque hôte cible et sa version, sa racine de découverte, sa forme d'invocation et son comportement de rechargement. Marquez les inconnus comme inconnus plutôt que de deviner. Inspectez les racines de skills existantes et les directives du projet avant de créer un package parallèle.
4. Définissez 2 à 3 cas d'utilisation concrets
5. Fixez des critères de succès mesurables (temps économisé, erreurs réduites, qualité améliorée)
6. Choisissez une catégorie de skill :

Catégorie	ENTRÉE → SORTIE	Exemples
1 : Création de documents et d'actifs	Données/spécifications → document, code, rapport	Générateur de tests d'API, résumeur de notes de réunion
2 : Automatisation de flux de travail	Paramètres de tâche → processus multi-étapes terminé	Pipeline de déploiement, flux de travail de révision de code
3 : Amélioration MCP	Sorties d'outils MCP → orchestration plus intelligente	Recherche intelligente de fichiers, assistant BigQuery

Pour des conseils approfondis sur les catégories : references/categories.md Pour des questions de découverte interactives : references/discovery.md

Étape 2 : Concevoir la structure

Concevez en utilisant la divulgation progressive — 3 niveaux de chargement :

Niveau	Quand il est chargé	Longueur cible	Contenu
1 : Métadonnées	Toujours (~100 mots)	name + description	Conditions de déclenchement
2 : Corps SKILL.md	Quand le skill se déclenche	Moins de 5 000 mots (idéalement moins de 2 000)	Flux de travail principal + pointeurs
3 : Fichiers references/	Au besoin	Illimité	Détails approfondis, schémas, exemples

Pour des conseils d'écriture sur la divulgation progressive et des métriques de succès : references/best-practices.md

Étape 3 : Implémenter

Règles critiques :

• ✅ Le fichier DOIT être nommé SKILL.md (pas README.md)
• ✅ Le nom du dossier DOIT être en kebab-case — pas d'espaces, pas de majuscules (my-skill pas My Skill)
• ✅ Le frontmatter YAML DOIT inclure name et description ; mettez une version sous metadata
• ✅ La description DOIT inclure des phrases de déclenchement spécifiques — ce que les utilisateurs DISENT pour activer le skill
• ✅ La description doit faire moins de 1024 caractères (limite stricte — les descriptions plus longues sont tronquées)
• ✅ Pas de chevrons XML (< ou >) dans aucun champ du frontmatter — une restriction d'hôte provenant du guide des skills Anthropic, pas une règle YAML ; le corps n'est pas affecté
• ✅ Corps : chaque section majeure se trouve à l'intérieur d'une région XML équilibrée et descriptive sur sa propre ligne (<purpose>, <requirements>, <workflow>, <examples>, <output_contract>), Markdown à l'intérieur, code source littéral dans des blocs de code délimités (SKILL-REQ004). Le titre H1 peut rester à l'extérieur.
• ❌ PAS de README.md dans le dossier du skill — toute documentation va dans SKILL.md ou references/ (Exception : un README.md à la RACINE du dépôt GitHub, en dehors du dossier du skill, est acceptable pour GitHub.)
• ❌ PAS d'espaces ni de tirets bas dans les noms de dossiers (mon_skill → mon-skill)

Frontmatter : champs obligatoires :

---
name: votre-nom-de-skill          # kebab-case uniquement ; pas d'espaces, de majuscules ou de tirets bas
description: Ce qu'il fait. À utiliser lorsque l'utilisateur demande "phrase spécifique", "une autre phrase".
             # DOIT inclure : ce qu'il fait + quand l'utiliser (conditions de déclenchement)
             # Moins de 1024 caractères. Pas de chevrons XML.
             # Ne commencez PAS par "claude" ou "anthropic" (espaces de noms réservés).
---

Pour chaque champ optionnel (license, compatibility, allowed-tools, metadata) avec des notes de portabilité entre hôtes : references/best-practices.md

Le langage de positionnement ("génère les tests 87 % plus rapidement") appartient au README du dépôt, jamais dans description. Voir references/best-practices.md.

Structure de dossiers (exemple autonome Claude Code annoté : references/best-practices.md, section "Patrons de structure de dossiers") :

Répertoire	Charger dans le contexte ?	Utilisation pour
references/	Oui, selon les besoins	Schémas, documentation API, politiques, guides de flux de travail
references/examples/	Selon les besoins	Code fonctionnel que les utilisateurs copient et adaptent
scripts/	Non (exécuté directement)	Validateurs, générateurs de structure, utilitaires
assets/	Non (utilisé dans la sortie)	Images, polices, modèles HTML que le skill colle dans la sortie

Remarque : Les skills de plugin (dans plugin-name/skills/) peuvent placer examples/ au niveau supérieur — c'est une convention de développement de plugin. Pour les skills autonomes ~/.claude/skills/, placez les exemples dans references/.

Pour générer la structure d'un nouveau skill : bash scripts/scaffold-skill.sh mon-nom-de-skill (définissez SKILLS_DIR pour cibler la racine d'un autre hôte) Pour partir d'un modèle : copiez references/examples/SKILL-template.md

Étape 4 : Tester

Cinq approches de test (à exécuter dans l'ordre) :

1. Tests de déclenchement — vérifiez que l'agent s'active sur les phrases attendues et pas sur des demandes non liées
2. Tests fonctionnels — validez que le flux de travail principal du skill produit une sortie correcte pour des entrées connues
3. Tests de performance — mesurez l'amélioration par rapport à la référence (temps économisé, réduction d'erreurs, cohérence)
4. Tests de compatibilité — vérifiez la découverte, l'invocation explicite, le chargement des références, l'exécution des scripts, et la résolution des doublons/noms sur chaque hôte et version nommés. Commencez une session propre pour chaque hôte, exécutez le validateur de l'hôte s'il existe (Codex fournit skill-creator/scripts/quick_validate.py), testez les réexécutions de l'installateur, les racines multiples, les cibles de liens symboliques, les fichiers utilisateur modifiés, et la désinstallation, et enregistrez un reçu de validation par hôte (references/portability-and-claim-audit.md).
5. Tests avancés — invites réalistes positives, négatives, ambiguës et adversariales ; jugez le résultat de la tâche, pas si le skill est apparu dans une liste, et vérifiez qu'il ne se déclenche pas par erreur sur des tâches voisines (SKILL-REQ012)

Débogage des problèmes de déclenchement :

Demandez à l'agent : "Quand utiliseriez-vous le skill [nom du skill] ?"

L'agent devrait citer sa description. Ajustez en fonction de ce qui manque ou est trop vague.

Correction du sous-déclenchement : Ajoutez des phrases de déclenchement plus spécifiques et des termes techniques pertinents.

Correction du sur-déclenchement : Ajoutez des déclencheurs négatifs à la description :

description : Traite les documents juridiques PDF pour la révision de contrats. À utiliser pour "réviser ce contrat",
  "analyser un document juridique", "extraire les clauses du contrat". Ne PAS utiliser pour la visualisation générale de PDF,
  l'extraction d'images ou les documents non juridiques (utilisez plutôt le skill doc-converter).

Pour le guide complet de diagnostic et de correction couvrant les quatre modes d'échec : references/troubleshooting.md

Pour valider la structure :

bash scripts/audit-skill.sh /chemin/vers/VOTRE-SKILL

…

[la suite a été tronquée pour la traduction]