Better Skill Generator – Générateur de Compétences Amélioré

Better Skill Generator (better-skill-gen)

Ce skill agit comme un Meta-Skill : il reçoit une idée, un problème ou un processus métier de l'utilisateur, finalise la conception avec lui, puis génère un dossier de skill complet pour chaque fournisseur sélectionné :

Fournisseur	Dossier (scope du projet)	Particularités
Codex et Antigravity	.agents/skills/<skill-name>/ (une version partagée)	Uniquement name, description ; Codex ajoute agents/openai.yaml pour la politique d'appel du skill
Claude Code	.claude/skills/<skill-name>/	Dispose de champs frontmatter supplémentaires, voir references/frontmatter-spec.md

Ce fichier est commun à Codex et Antigravity. Tous les chemins scripts/..., references/... dans ce fichier sont relatifs au dossier contenant ce SKILL.md. « Exécuter une commande » signifie utiliser l'outil d'exécution shell du fournisseur utilisé (par exemple run_command dans Antigravity).

---

1. Principes de conception fondamentaux

1. Architecture Progressive Disclosure à 3 niveaux :
   • Niveau 1 : Métadonnées (toujours chargées au démarrage) : name, description dans le YAML Frontmatter. Consomme très peu de tokens ; gardez description sous 1 536 caractères.
   • Niveau 2 : Instructions (chargées uniquement lorsque le skill est activé) : Le corps du fichier SKILL.md, obligatoirement moins de 500 lignes. Ne contient que le workflow, les principes fondamentaux et les contraintes.
   • Niveau 3 : Ressources (chargées uniquement en cas de besoin réel) : templates/ (modèles de résultat), examples/ (textes exemples Gold Standard), references/ (spécifications techniques), scripts/ (code bash/python pour les tâches lourdes sans consommer de contexte).
2. Classification des objectifs du skill :
   • Reference Skills : Conventions de code, connaissances système, patterns de conception, que l'agent applique comme connaissance de base.
   • Task Skills : Processus étape par étape pour exécuter des actions. Les tâches ayant des effets secondaires (déploiement, commit, suppression de données) ne doivent être exécutées que lorsque l'utilisateur les appelle directement. La version .agents/skills/ fait les deux : crée agents/openai.yaml avec policy.allow_implicit_invocation: false (pour Codex) et inscrit la phrase « À utiliser uniquement sur demande directe de l'utilisateur » dans description (pour Antigravity, qui n'a pas de champ équivalent). Détails dans references/providers.md section 3.
3. Fonctionnalités propres à chaque fournisseur : Claude Code dispose de sous-agents, de variables de paramètres et d'injections de commandes shell dans SKILL.md (voir references/frontmatter-spec.md). Utilisez-les uniquement dans la version Claude Code ; pour les autres fournisseurs, convertissez selon references/providers.md section 3.
4. Vérifier, ne pas faire confiance (Auto-vérification) :
   • Chaque skill généré doit être accompagné d'un scripts/validate.sh avec des codes de sortie standard (0 = succès, 1 = échec).
   • Respect à 100 % des règles de linting selon markdownlint.
5. Zero Workspace Pollution :
   • Tous les fichiers de configuration, ressources et scripts se trouvent uniquement dans le dossier du skill chez chaque fournisseur.
   • Tous les documents d'exemple se trouvent uniquement dans examples/ du skill. Ne générez et ne copiez aucun fichier exemple vers d'autres dossiers métier du projet (comme src/, la racine du projet).
   • Les fichiers temporaires lors des tests sont écrits dans le dossier temporaire du système d'exploitation (ou le dossier temporaire spécifié par les instructions de l'utilisateur) et sont nettoyés immédiatement après.
6. Interroger l'utilisateur avec des choix structurés :
   • Tous les choix proposés à l'utilisateur (scope, fournisseur, points flous dans l'idée, directions de conception) sont présentés sous forme d'options. Si la session dispose d'un outil de sélection de réponses, utilisez-le. Sinon, listez les options numérotées, puis arrêtez-vous et attendez la réponse de l'utilisateur.
   • Ordre de présentation : (1) ce que le skill à créer fait, (2) ce que la question demande et pourquoi elle est posée, (3) les options, chacune décrivant ses avantages et inconvénients, (4) l'option recommandée, placée en tête de liste et marquée (recommandé).
   • Posez au maximum 4 questions par tour, les questions importantes en premier. Autorisez toujours l'utilisateur à répondre autre chose que les options proposées.
   • Ne choisissez pas à la place de l'utilisateur sans sa réponse.
7. Une version par fournisseur, conforme à ses spécifications :
   • Les ressources partagées (template.md, examples/, references/, scripts/) sont copiées à l'identique. Seuls SKILL.md (et agents/openai.yaml de Codex) sont rédigés individuellement : une version pour Claude Code, une version commune pour Codex et Antigravity.
   • La version Codex/Antigravity doit fonctionner correctement sur les deux fournisseurs : utilisez uniquement les champs frontmatter de la norme ouverte, n'utilisez ni variables ni outils compris uniquement par Claude Code, et n'appelez pas l'agent en cours d'exécution « Claude ». Claude n'est mentionné que s'il est le sujet du skill.

---

2. Entrées requises (Inputs)

• Obligatoire : Description de l'idée ou de l'objectif métier du skill à créer.
• Optionnel : Contraintes spécifiques, outils à utiliser, type de tâche ou de référence.
• Obligation de demander (à chaque création de nouveau skill) : Scope et fournisseur (section 2.1), ainsi que tous les points flous dans l'idée (section 2.2). Ne passez une question que si l'utilisateur y a déjà répondu clairement dans sa demande.
• Ne décidez pas vous-même des points flous : Si l'idée est vague, analysez et proposez (section 2.2), ne remplissez pas puis générez les fichiers. Seuls les points évidents par convention (par exemple le nom kebab-case déduit de l'idée) peuvent être définis automatiquement, et doivent être mentionnés dans le résumé de conception.

2.1. Demander le périmètre (Scope) et le Fournisseur

Avant de générer un fichier, posez 2 questions dans le même tour selon le principe 6 :

1. Scope (choix multiple) : les trois options du tableau ci-dessous, project-shared est recommandé.
2. Fournisseur (choix multiple) : Codex, Claude Code, Antigravity. Si le skill peut être utilisé avec tous les fournisseurs, recommandez les trois. Si le skill n'a de sens qu'avec un seul fournisseur (par exemple, vérifier un fichier de configuration de Claude Code), recommandez uniquement ce fournisseur et expliquez pourquoi.

Scope	Signification	Racine cible	Variable lors de l'exécution du script
project-shared	Propre au projet actuel, partagé par toute l'équipe (commit dans git)	Racine du projet	SCOPE=project (par défaut)
project-personal	Propre au projet actuel, uniquement pour cet utilisateur (pas de commit)	Racine du projet	SCOPE=project, puis ajoute les dossiers créés dans .git/info/exclude
user-global	Tous les projets de cet utilisateur	$HOME	SCOPE=user

Règles :

• Si l'utilisateur choisit plusieurs scopes, déployez-les un par un.
• Si le dossier du projet n'est pas un dépôt git, supprimez l'option project-personal.
• Inscrivez le scope et le fournisseur choisis dans le rapport de livraison ainsi que la liste des chemins créés.
• Si un skill a un contenu spécifique au projet et que l'utilisateur choisit user-global, avertissez d'une ligne avant la création.

2.2. Analyse de l'idée et proposition

Après avoir obtenu le scope et le fournisseur, analysez l'idée avant d'écrire un fichier :

1. Résumé de ce qui est compris : ce que le skill résout, qui l'utilise, quand il est activé, quel est le résultat.
2. Identification des points de conception, en précisant pour chacun si l'utilisateur l'a dit ou si l'agent le déduit :
   • Type de skill : Task ou Reference ; a-t-il des effets secondaires ?
   • Mode d'activation : automatique selon description, uniquement sur appel direct de l'utilisateur, ou les deux ; phrase d'activation et cas de non-utilisation.
   • Entrées, paramètres et gestion des absences.
   • Sorties : format, emplacement de stockage, nécessité d'un template.md et critères de vérification dans scripts/validate.sh.
   • Mode d'exécution : simple guide ou nécessité d'un script ; outils requis.
   • Parties à déporter vers references/ pour que SKILL.md reste sous 500 lignes.
3. Proposition d'orientation optimale : pour chaque point offrant plusieurs approches, présentez 2 à 3 directions avec leurs avantages et inconvénients, et choisissez-en une recommandée. Exemple : « vérification via le script scripts/check.sh (rapide, précis, mais nécessite bash) » par rapport à « l'agent lit et évalue lui-même (flexible, mais coûteux en tokens et sujet à erreurs) ».
4. Interrogation de l'utilisateur : regroupez tous les points flous et tous les points avec plusieurs directions en questions selon le principe 6.
5. Finalisation de la conception : après avoir reçu les réponses, rédigez un résumé de conception (nom du skill, type, mode d'activation, liste des fichiers à créer, fournisseur, scope, valeurs définies automatiquement par l'agent). Si une réponse soulève un nouveau point flou, demandez à nouveau, ne générez pas de fichier.

2.3. Étude du fournisseur

Avant d'écrire la version pour un fournisseur, lisez references/providers.md :

• Si la Date de vérification date de plus de 30 jours, que le skill nécessite une fonctionnalité absente du fichier, ou que les informations du fichier contredisent la réalité : consultez la documentation officielle à la section 6 de ce fichier, mettez à jour le fichier, corrigez la date de vérification, puis recopiez le fichier vers les autres fournisseurs via scripts/sync-skill.sh better-skill-gen.
• Antigravity au scope projet partage .agents/skills/ avec Codex (section 5). Ne créez pas .agent/skills/.
• Ne devinez pas les spécifications du fournisseur. Tout point introuvable doit être signalé clairement à l'utilisateur et demandé.

---

3. Processus d'exécution (Workflow)

flowchart TD
    A["Idée métier de l'Utilisateur"] --> A2["0. Demander Scope et Fournisseur"]
    A2 --> B["1. Analyser l'idée, proposer, demander les points flous"]
    B --> B2["2. Étudier le fournisseur"]
    B2 --> C["3. Consulter template.md & references/"]
    C --> D["4. Générer la version originale"]
    D --> E["5. Synchroniser les ressources & écrire SKILL.md propre à chaque fournisseur"]
    E --> F["6. Auto-vérification via scripts/validate.sh"]
    F -->|Succès| G["Terminé & Livraison"]
    F -->|Échec| D

0. Demander Scope et Fournisseur : Appliquez la section 2.1 et attendez la réponse avant de continuer.
1. Analyser l'idée : Appliquez la section 2.2 jusqu'à ce que la conception soit finalisée. Nommez le skill en kebab-case ($\le 64$ caractères, interdiction des termes anthropic-skills, synced, claude, anthropic).
2. Étudier le fournisseur : Appliquez la section 2.3 pour tous les fournisseurs sélectionnés.
3. Consulter les documents de référence : Lisez template.md (structure cadre), references/providers.md (différences entre fournisseurs), references/frontmatter-spec.md (champs de Claude Code) et examples/sample.md (style d'écriture et logique des scripts).
4. Générer la version originale : Écrivez tous les composants dans le dossier du premier fournisseur sélectionné :
   • SKILL.md : Frontmatter sécurisé (scalar >-), moins de 500 lignes.
   • template.md (ou templates/) : Modèle de sortie avec variables d'exemple ${VARIABLE}.
   • examples/sample.md : Texte exemple réel sans placeholder.
   • references/ (si documents de spécification ou connaissances complexes à déporter).
   • scripts/validate.sh : Script de vérification de l'intégrité du résultat.
   • Ressources partagées rédigées de manière neutre vis-à-vis du fournisseur : scripts appelés par chemin relatif depuis le dossier du skill.
5. Déploiement par fournisseur :
   • Copie des ressources partagées : exécutez PROVIDERS="<fournisseurs sélectionnés>" bash scripts/sync-skill.sh <skill-name>. Le script copie tous les fichiers sauf SKILL.md et agents/, et signale [TODO] pour tout fournisseur manquant de SKILL.md.
   • Pour le dossier restant, écrivez un SKILL.md propre selon le tableau de conversion de references/providers.md section 3. Réécrivez le texte du corps, ne vous contentez pas de supprimer des champs frontmatter. Si Codex et Antigravity sont tous deux sélectionnés, un seul dossier .agents/skills/ est créé, le script fusionne automatiquement.
   • Skill avec effets secondaires : la version .agents/skills/ crée en plus agents/openai.yaml avec policy.allow_implicit_invocation: false et inscrit la phrase « À utiliser uniquement sur demande directe de l'utilisateur » dans description.
   • Scope user-global : ajoutez SCOPE=user lors de l'exécution du script.
   • Scope project-personal : ajoutez les dossiers de skill créés dans .git/info/exclude (ne modifiez pas .gitignore, ne commitez pas).
6. Auto-vérification :
   • Exécutez PROVIDERS="<fournisseurs sélectionnés>" bash scripts/validate.sh <skill-name> (ajoutez SCOPE=user si user-global).
   • Le script vérifie : YAML frontmatter valide, markdownlint, SKILL.md $\le 500$ lignes, présence des fichiers obligatoires chez chaque fournisseur sélectionné, et absence de champs ou tokens propres à Claude Code dans la version Codex/Antigravity.
   • Lisez chaque ligne [WARN] : si elle mentionne Claude parce que Claude est le sujet, conservez-la ; sinon corrigez.
   • En cas d'erreur, corrigez jusqu'à obtenir [PASS].

---

4. Contraintes & Standards (Guardrails)

• RÈGLES OBLIGATOIRES (CRITICAL) :
  • Toutes les options sont demandées selon le principe 6 et attendez la réponse avant de continuer.
  • Demandez toujours le scope et le fournisseur avant de créer un nouveau skill (section 2.1).
  • Ne décidez pas vous-même des points flous : analysez, proposez et demandez (section 2.2) avant de générer des fichiers.
  • Étudiez le fournisseur avant d'écrire sa version (section 2.3) ; ne devinez pas les spécifications.
  • Ne copiez pas à l'identique SKILL.md entre fournisseurs : chaque fournisseur a sa propre version conforme ; validate.sh doit être [PASS] pour tous les fournisseurs sélectionnés.
  • Zero Workspace Pollution : les documents d'exemple se trouvent uniquement dans examples/ ; ne créez pas de fichiers en dehors du dossier du skill.
  • Gardez SKILL.md sous 500 lignes : déportez le contenu détaillé vers references/ ou templates/.
  • Normalisation du Frontmatter : description contenant des deux-points : doit utiliser le scalar >- ou des guillemets "...".
  • Respectez Markdownlint (MD001 - MD047) pour tous les fichiers Markdown créés.
• À FAIRE (DOs) :
  • Déclarez le mécanisme « exécuté uniquement sur appel utilisateur » pour tout skill ayant des effets secondaires, selon la méthode propre à chaque fournisseur (Codex : agents/openai.yaml ; Antigravity : phrase dans description).
  • Utilisez des noms de variables de template ${NOM_VARIABLE} évocateurs dans le template.
  • Nettoyez immédiatement les fichiers temporaires générés lors des tests automatiques.
• À NE PAS FAIRE (DON'Ts) :
  • Ne mettez pas l'intégralité des documents de référence longs directement dans SKILL.md.
  • Ne laissez pas d'URL brute dans les fichiers markdown sans les encadrer de <> ou de lien markdown.
  • N'utilisez pas un nom de skill de plus de 64 caractères ou contenant des majuscules ou caractères spéciaux.
  • N'appelez pas l'agent « Claude » dans la version destinée à un autre fournisseur que Claude Code.