Elites Skills Architect

Transforme une idée brute en une compétence qui fonctionne : découverte, spécification, validation, tests, relecture humaine, ajustement de la description et empaquetage. Chaque affirmation concernant une compétence est étayée par un script ou une exécution notée, et non par une simple lecture rassurante.

Par où commencer

Huit étapes. Identifiez où se trouve l'utilisateur et commencez-y :

Découverte : obtenir un problème concret et les faits nécessaires pour rédiger le cahier des charges
Signaler les problèmes : trop simple, trop large, chevauchements, contradictions
Catégoriser : création de documents, automatisation de workflow ou amélioration MCP
Construire et valider : en-tête, corps, dossier, évaluations, scripts/validate_spec.py
Tester et réviser : exécuter les évaluations, montrer les résultats, les noter, mettre à l'épreuve toute règle imposée par la compétence
Améliorer : corriger le modèle sous-jacent au retour, pas le cas isolé
Ajustement de la description : tests de déclenchement et scripts/optimize_description.py
Empaqueter : scripts/package_skill.py

Adaptez votre rythme à l'utilisateur. Quelqu'un qui dit « serveur MCP » et « en-tête » sans y être invité veut de la rapidité. Quelqu'un qui dit « Je veux que Claude fasse mes factures » a besoin d'être guidé question par question. Utilisez un français simple, sans jargon qu'il n'a pas utilisé en premier.

Tous les scripts sont en Python 3.9 ou ultérieur de la bibliothèque standard, exécutés depuis la racine de la compétence :

cd <chemin-vers-elites-skills-architect>
python3 scripts/validate_spec.py <dossier-compétence>

Étape 1 : Découverte

Lisez references/discovery-questions.md pour la banque de questions et les relances pour les réponses faibles. Posez les questions par lots de deux ou trois, construisez sur les réponses, ne déversez jamais la liste.

Lot 1, problème : le seul résultat que la compétence doit produire ; 5 à 10 phrases que les utilisateurs diraient vraiment ; ce que la compétence ne doit PAS gérer. Lot 2, données : entrées et leur format ; ce que l'utilisateur a en main quand ça a fonctionné ; ce qui se passe généralement mal avec l'entrée. Lot 3, workflow : ordre des étapes ; dépendances ; chemins si/alors ; ce qui arrive aux étapes 1 et 2 lorsque l'étape 3 échoue. Lot 4, intégrations : serveurs MCP, API, fonctions intégrées Claude, authentification et limites de débit. Lot 5, résilience : les trois défaillances d'exécution les plus probables ; le message en cas d'échec total.

Arrêtez de poser des questions lorsque vous pouvez faire les quatre choses suivantes sans deviner : rédiger la description avec de vraies phrases de déclenchement, lister chaque étape dans l'ordre, nommer trois modes de défaillance avec leur traitement, et expliquer la compétence suffisamment bien pour qu'un autre développeur la construise.

Si l'utilisateur a déjà les connaissances écrites (un manuel, une documentation API, un guide de style, des pages web sauvegardées), importez-les au lieu de les retaper :

python3 scripts/import_sources.py <fichiers-ou-dossiers> --skill <dossier-compétence> --dry-run

Cela transforme le Markdown, le texte et le HTML sauvegardé en fichiers de référence, divise les longs fichiers aux titres, écrit un sources-index.md à côté d'eux, et imprime les lignes « lire X quand Y » pour le corps. Cela ne télécharge jamais rien ; sauvegardez d'abord les pages.

Étape 2 : Signaler les problèmes avant de construire

Trop simple : Claude le fait déjà. Une compétence gagne sa place quand il y a une logique métier ou un format à imposer à chaque fois. Demandez si c'est le cas.
Trop large : plusieurs workflows sans rapport. Suggérez une scission ; les petites compétences se déclenchent plus fi ablement. Demandez laquelle vient en premier.
Chevauchement : proche de docx, pptx, xlsx, pdf ou conception front-end. Dites-le et demandez s'il faut étendre ou construire quelque chose de différent.
Impossible ou dangereux : dites-le clairement et proposez la version réalisable la plus proche.
Contradiction : « entièrement automatique » plus tôt, « demandez-moi d'abord » maintenant. Résolvez-la avant d'écrire une ligne.

Étape 3 : Catégoriser

Lisez references/categories-and-patterns.md. Choisissez-en une :

Catégorie 1, création de documents et d'actifs : crée des fichiers avec les fonctions intégrées de Claude. Les lots de découverte 1 et 2 suffisent.
Catégorie 2, automatisation de workflow : étapes ordonnées entre outils, portes de validation, échec partiel ou rollback. Les cinq lots.
Catégorie 3, amélioration MCP : enveloppe un serveur MCP existant avec jugement et valeurs par défaut. Lots 1, 2 et 4.

Dites à l'utilisateur la catégorie et pourquoi. Les mélanges sont acceptables ; choisissez la catégorie principale pour la description et la structure de dossier.

Étape 4 : Construire et valider

Lisez references/worked-example.md une fois avant de générer quoi que ce soit, afin que votre résultat corresponde à ce niveau de détail. Utilisez references/spec-output-template.md comme squelette.

4a : En-tête

Lisez references/yaml-rules.md. Ce que le validateur vérifie (erreurs sauf indication contraire) :

name : kebab-case, sans « claude » ou « anthropic » ; correspond au nom du dossier (avertissement, erreur avec --portable)
description : 1 à 1024 caractères ; verbe d'action, ce qu'elle fait, quand l'utiliser, 3 à 8 phrases de déclenchement entre guillemets, un périmètre négatif (la longueur est une erreur ; verbe, phrases et périmètre négatif sont des avertissements)
pas de chevrons, tabulations, guillemets courbes ou tirets autres que le trait d'union
pas d'apostrophes dans la description (avertissement ; certains analyseurs de téléchargement les ont rejetées)
balises comme une seule chaîne, tags: "a, b, c", jamais [a, b, c] (avertissement) ; mettez les valeurs de métadonnées qui ressemblent à des nombres entre guillemets, version: "1.0"

Rendez la description percutante. Dans nos tests, Claude laisse une compétence inutilisée plus souvent qu'il ne la choisit à tort, alors ajoutez « se déclenche aussi quand quelqu'un mentionne ... » pour les demandes indirectes.

4b : Corps

Au maximum 500 lignes, impératif, et il explique pourquoi, pas seulement quoi. Ordre : objectif en une ligne ; quand utiliser et quand ne pas utiliser ; étapes numérotées avec une vérification après chacune ; deux ou trois exemples (phrase, actions, résultat) ; gestion des erreurs avec cause et réponse ; bonnes pratiques courtes. Déplacez tout ce qui est plus volumineux dans references/ et faites-y référence avec « lire X quand Y ».

4c : Dossier

nom-compétence/
  SKILL.md
  evals/evals.json        cas de test, voir references/schemas.md
  scripts/                logique déterministe que le modèle ne doit pas redériver
  references/             contenu approfondi chargé à la demande
  assets/                 modèles et échantillons

Pas de README.md dans le dossier de la compétence ; la documentation se trouve dans SKILL.md et references/.

4d : Plan de test et évaluations

Rédigez 5 requêtes ou plus qui DEVRAIENT déclencher et 5 requêtes ou plus qui NE DEVRAIENT PAS déclencher. Les bonnes requêtes sont spécifiques et ressemblent à une personne : « ok je lance la refonte du checkout lundi, configure le sprint dans Linear, 2 semaines, équipe frontend ». Les meilleures négatives partagent des mots avec les positives mais veulent autre chose : des conseils au lieu d'une action, des rapports au lieu de la création.

Rédigez 2 ou 3 évaluations dans evals/evals.json (format dans references/schemas.md). Chaque attente est une phrase vérifiable. Montrez-les à l'utilisateur avant d'exécuter quoi que ce soit.

4e : Valider

python3 scripts/validate_spec.py <dossier-compétence>
python3 scripts/validate_spec.py <dossier-compétence> --json     # pour les outils
python3 scripts/validate_spec.py <dossier-compétence> --strict   # les avertissements échouent aussi
python3 scripts/validate_spec.py <dossier-compétence> --portable # pour d'autres agents que Claude

Il vérifie les règles d'en-tête, la longueur du corps, les sections ci-dessus, les espaces résiduels, evals.json, pressure-evals.json lorsqu'il est présent, et que chaque chemin scripts/... ou references/... mentionné dans le corps existe. Corrigez chaque erreur. Ne montrez jamais un cahier des charges qui échoue. --portable ajoute les règles de la spécification open Agent Skills (le nom du dossier doit correspondre, les valeurs de métadonnées doivent être du texte) pour les compétences qui seront également exécutées dans d'autres agents.

Étape 5 : Tester et réviser

Une seule séquence ; ne vous arrêtez pas à mi-chemin.

5a : Exécuter les évaluations

Structure de l'espace de travail (arbre complet dans references/schemas.md) :

<nom-compétence>-workspace/iteration-1/eval-<id>/<configuration>/run-<k>/outputs/

Écrivez eval_metadata.json dans chaque dossier eval-<id>/. Puis exécutez chaque évaluation :

Avec sous-agents (Claude Code, Cowork) : lancez les exécutions avec compétence et sans compétence pour chaque évaluation dans le même tour. Chaque exécuteur lit la compétence, effectue la tâche, enregistre les fichiers dans outputs/, écrit outputs/user_notes.md pour tout ce dont il n'était pas sûr, et outputs/metrics.json. Enregistrez immédiatement timing.json à partir de la notification de tâche ; les chiffres ne sont conservés nulle part ailleurs.
Sans sous-agents (claude.ai) : lisez SKILL.md et effectuez chaque tâche vous-même, une par une, dans les mêmes dossiers.

5b : Rédiger des assertions pendant que les exécutions sont en cours

Ajoutez des attentes mesurables à eval_metadata.json et evals/evals.json. Expliquez chacune à l'utilisateur en une phrase. Sautez les assertions de goût ; une personne les juge.

5c : Montrer les résultats avant de les juger

python3 eval-viewer/review.py <nom-compétence>-workspace/iteration-1 --skill-name <nom>

La page s'ouvre dans le navigateur, fonctionne hors ligne et enregistre les retours dans feedback.json dans l'espace de travail au fur et à mesure que l'utilisateur tape. Dans Cowork, ou lorsqu'un serveur n'est pas possible, ajoutez --static review.html ; les retours sont alors téléchargés sous forme de fichier. Ouvrez d'abord la visionneuse et regardez les résultats vous-même en second. Ne modifiez pas la compétence avant que l'utilisateur n'ait réagi.

5d : Noter et évaluer (sous-agents)

Notez chaque exécution avec agents/grader.md. Utilisez un modèle différent de celui qui a exécuté l'évaluation lorsque c'est possible ; un modèle est un mauvais juge de son propre travail.

Agrégez :

python3 scripts/aggregate_benchmark.py <nom-compétence>-workspace/iteration-1 --skill-name <nom>

Rouvrez la visionneuse avec --benchmark <iteration>/benchmark.json pour l'onglet Benchmark. Pour les modèles que les moyennes cachent, exécutez la tâche 2 de agents/analyzer.md.

5e : Test de résistance (compétences qui imposent une règle)

Lorsque la valeur de la compétence est une règle qui doit être respectée (un format, une vérification, une étape d'approbation), lisez references/pressure-tests.md et écrivez 3 à 5 scénarios dans evals/pressure-evals.json : une situation concrète, deux pressions ou plus (délai, un patron, le client a demandé, des heures déjà passées), et un choix forcé qui inclut un compromis tentant.

python3 scripts/pressure_eval.py --skill-path <dossier-compétence> \
  --scenarios <dossier-compétence>/evals/pressure-evals.json --runs 3 --model <id-modèle> \
  --output <nom-compétence>-workspace/pressure-results.json \
  --report <nom-compétence>-workspace/pressure-report.md --dry-run

Supprimez --dry-run après que l'utilisateur a approuvé le nombre d'appels. Chaque scénario s'exécute sans et avec la compétence. « la compétence ne tient pas » signifie que le rapport contient les excuses que Claude a données : contrez chacune dans la compétence (nommez-la, dites pourquoi elle a tort, dites quoi faire), puis réexécutez. « passe, mais la référence passe aussi » signifie que le scénario est trop facile pour prouver quoi que ce soit.

Étape 6 : Améliorer

Trouvez le modèle derrière le retour et corrigez-le ; trois tâches de test ne représentent pas le monde réel. Lisez les transcriptions, pas seulement les résultats, et supprimez les instructions qui ont fait perdre des étapes au modèle. Si vous écrivez TOUJOURS ou JAMAIS en majuscules, arrêtez et expliquez la raison à la place ; un modèle avec la raison va plus loin qu'un modèle avec la règle. Lorsque chaque exécution a écrit la même aide, placez-la dans scripts/ et dites-le. Méfiez-vous d'une compétence qui réussit ses trois évaluations et rien d'autre.

Ensuite : appliquez les modifications, réexécutez toutes les évaluations dans iteration-2/, ouvrez la visionneuse avec --previous-workspace iteration-1 pour que l'utilisateur voie l'ancien et le nouveau côte à côte, lisez les retours, répétez. Arrêtez-vous lorsque l'utilisateur est satisfait, que les retours sont vides ou que les progrès stagnent.

Pour un appel rigoureux ancien contre nouveau, utilisez agents/comparator.md (un juge A/B en aveugle avec une vérification d'échange), puis la tâche 1 de agents/analyzer.md pour expliquer le résultat. Facultatif ; la boucle de révision est généralement suffisante.

Étape 7 : Ajustement de la description

La description est ce qui fait que Claude choisit la compétence. Ajustez-la une fois que la compétence elle-même fonctionne.

7a : Requêtes de déclenchement

Écrivez 20 requêtes dans evals/trigger-evals.json : environ la moitié devrait déclencher, l'autre moitié non. Incluez le langage courant, les noms de fichiers, le contexte personnel. Les négatives précieuses sont les quasi-échecs. Montrez la liste à l'utilisateur et modifiez ce qu'il demande de modifier ; de mauvaises requêtes produisent une mauvaise description.

7b : Compter avant de dépenser

python3 scripts/trigger_eval.py --skill-path <dossier-compétence> --eval-set <dossier-compétence>/evals/trigger-evals.json --dry-run

Chaque exécution est un appel claude -p. Dites le nombre à l'utilisateur et obtenez un accord.

7c : Mesurer

python3 scripts/trigger_eval.py --skill-path <dossier-compétence> \
  --eval-set <dossier-compétence>/evals/trigger-evals.json \
  --runs-per-query 3 --workers 4 --model <id-modèle> \
  --output <nom-compétence>-workspace/trigger-results.json --verbose

Le script installe la compétence dans un projet jetable et exécute Claude avec uniquement les paramètres de ce projet, de sorte que rien ne touche le vrai projet de l'utilisateur et que ses autres compétences ne peuvent pas interférer. Lisez le résumé : les requêtes manquées (faux négatifs) signifient que la description est trop étroite ; les déclenchements erronés signifient qu'elle est trop large. Une requête dont toutes les exécutions ont échoué est signalée comme inconnue, jamais comme réussite.

7d : Optimiser (Claude Code uniquement)

python3 scripts/optimize_description.py --skill-path <dossier-compétence> \
  --eval-set <dossier-compétence>/evals/trigger-evals.json --model <id-modèle> \
  --max-iterations 4 --results-dir <nom-compétence>-workspace/description-runs --verbose

Il divise les requêtes une fois en ensembles d'entraînement et de test, évalue, demande à Claude une meilleure description en utilisant uniquement les échecs d'entraînement, valide le candidat avec les mêmes règles que validate_spec.py, et répète. Le gagnant est l'itération avec le meilleur score d'entraînement ; les égalités vont au texte le plus court. Le score de l'ensemble de test est rapporté mais jamais utilisé pour choisir, il reste donc une vérification honnête : s'il est bien inférieur au score d'entraînement, la description est ajustée aux requêtes d'entraînement. Il écrit results.json, report.md et best-description.txt, et se termine avec le code 0 uniquement lorsque le gagnant réussit chaque requête d'entraînement. Sur claude.ai, lisez les échecs et réécrivez à la main à la place.

7e : Appliquer

Collez le gagnant dans SKILL.md, montrez à l'utilisateur l'avant et l'après avec les scores, et exécutez à nouveau scripts/validate_spec.py.

Étape 8 : Empaqueter

python3 scripts/package_skill.py <dossier-compétence> --output dist/
python3 scripts/package_skill.py --inspect dist/<nom-compétence>.skill

L'empaquetage valide d'abord et refuse en cas d'erreur (et en cas d'avertissement sauf si --allow-warnings est spécifié). L'archive est reproductible et imprime un SHA-256. Donnez le chemin à l'utilisateur, ou le fichier lui-même.

elitesalgorithm/elites-skills-architect

Qu'est-ce que elites-skills-architect ?

Demander à votre IA préférée

Documentation