Workflow-to-Skill Distiller

Transforme un workflow complété en skill agent réutilisable. Spécifiquement, ce skill extrait des motifs d'une interaction ou d'un workflow qui a déjà eu lieu et les package.

[!CAUTION] Vous DEVEZ compléter la Phase 1 (Brainstorming) avant d'écrire du code ou du contenu SKILL.md. Sauter le brainstorming produit des skills soit trop rigides soit trop vagues. La conversation de brainstorming est la partie la plus importante de ce processus.

Phase 1 : Brainstorming (OBLIGATOIRE)

Menez une conversation itérative d'allers-retours avec l'utilisateur. Ne posez PAS toutes les questions d'un coup. Sélectionnez 2-3 questions pertinentes par round depuis la banque ci-dessous, affinez votre compréhension, et posez des questions de suivi.

Round 1 : Comprendre le Workflow

Commencez par résumer ce que vous avez observé du workflow, puis posez :

« Voici ma compréhension du workflow : [résumé]. Est-ce exact ? Que changeriez-vous ? »
« Quelles sont les entrées et sorties attendues pour ce workflow ? »
« À quelle fréquence pensez-vous exécuter ce workflow ? Est-ce récurrent ou ponctuel ? »

Round 2 : Flexibilité et Gestion des Erreurs

Pour chaque étape identifiée dans le workflow, déterminez sa rigidité :

« Pour [l'étape X], si l'approche principale échoue (p. ex., API indisponible, aucun résultat), l'agent devrait-il : (a) vous demander des conseils, (b) essayer automatiquement des approches alternatives, ou (c) échouer bruyamment avec une erreur ? »
« Y a-t-il des étapes où la méthode exacte compte (p. ex., doit utiliser une base de données spécifique), par rapport à des étapes où n'importe quelle approche raisonnable convient ? »
« Le skill doit-il gérer les cas limites silencieusement ou les signaler à l'utilisateur ? »

Round 3 : Dépendances et Ressources

Avant de poser ces questions, vérifiez quels de vos skills installés chevauchent le workflow. Si un skill existant du bundle science couvre une étape, le nouveau skill DOIT le référencer — n'offrez pas d'option autonome.

« J'ai remarqué que le workflow utilise des fonctionnalités couvertes par [skill existant X, skill Y]. Le nouveau skill les référencera plutôt que de les réimplémente. Y a-t-il d'autres outils ou skills que vous aimeriez que j'incorpore ? »
« Y a-t-il des limites de débit API dont je devrais être conscient pour les services utilisés dans ce workflow qui ne sont pas déjà couverts par un skill existant ? »
« Y a-t-il des fichiers spécifiques qui fournissent un contexte scientifique important pour créer ce skill ? Par exemple : documentation API, articles de référence, exemples de jeux de données, ou notes spécifiques au domaine. Si oui, veuillez les partager et j'incorporerai leur contenu dans les matériaux de référence du skill. »

Round 4 : Portée et Forme

« Notre workflow a couvert [X, Y, Z]. Dois-je distiller tout cela dans le skill, ou y a-t-il une fonctionnalité supplémentaire qui est importante à inclure ? Inversement, certaines de ces étapes devraient-elles être omises ? »
Déterminez si le skill a besoin de code. Si une étape implique d'appeler une API, de traiter des données, de lire/écrire des fichiers, ou de calculer des résultats, le skill a besoin de code et vous devriez utiliser par défaut le pattern CLI. Utilisez uniquement un skill d'instructions texte uniquement quand chaque étape est purement une question de raisonnement, de coordination de skills existants, ou de suivi d'un protocole écrit sans aucun travail programmatique. Confirmez votre évaluation avec l'utilisateur en langage clair :
- Si du code est nécessaire : « Certaines de ces étapes impliquent [récupérer des données depuis une API / traiter des fichiers / calculer des résultats], donc je vais créer un script d'aide que l'agent peut exécuter pour vous. Le script aura des commandes simples comme search, fetch, analyze, etc. — vous n'aurez pas besoin d'écrire du code vous-même. Cela vous convient-il ? »
- Si aucun code n'est nécessaire : « Ce workflow concerne entièrement le suivi d'une série d'étapes et l'utilisation de skills existants — aucun nouveau code n'est nécessaire. Je l'écrirai comme une série d'instructions claires que l'agent suit. Cela vous convient-il ? »
Si un script d'aide sera créé : « Je pense que le script devrait avoir ces commandes : [commandes proposées en anglais clair, p. ex. 'search for proteins', 'fetch results', 'compare sequences']. Qu'ajouteriez-vous ou changeriez-vous ? »
« Comment devrait s'appeler le skill ? Nom proposé : [suggestion]. »

Round 5 : Tests (Optionnel)

« Pouvez-vous fournir une requête exemple et une réponse attendue que je peux utiliser pour vérifier que le skill fonctionne comme prévu ? Par exemple : 'Si je demande [question], le skill devrait produire [réponse].' C'est optionnel mais m'aide à valider le skill pendant le développement. »

Critères de Complétude du Brainstorming

Vous êtes prêt à passer à la Phase 2 quand vous pouvez répondre en confiance à TOUS les points :

[ ] Quel est le but et la portée du workflow ?
[ ] Quelles sont les entrées et sorties ?
[ ] Quelles étapes sont strictes par rapport flexibles ?
[ ] Quels skills existants doivent être référencés ?
[ ] Quels nouveaux scripts (le cas échéant) sont nécessaires ?
[ ] Quelles limites de débit s'appliquent ?
[ ] Comment les erreurs doivent-elles être gérées ?
[ ] Le workflow a-t-il besoin de code ? (Si oui → pattern CLI ; si non → instructions uniquement)
[ ] Y a-t-il une requête/réponse exemple pour la validation ?

Phase 2 : Conception du Skill

Produisez un document de conception (comme artefact / plan de mise en œuvre) et présentez-le à l'utilisateur pour approbation. Le document doit inclure :

Nom et description du skill (suivant les règles du frontmatter YAML : nom ≤64 caractères, minuscules + tirets ; description ≤1024 caractères).
Structure de répertoire montrant tous les fichiers prévus.
Skills existants référencés avec justification pour chacun.
Nouveaux scripts (le cas échéant) avec sous-commandes proposées et arguments.
Stratégie de limitation de débit pour toute API non couverte par un skill existant.
Stratégie de gestion des erreurs par étape.

Attendez l'approbation explicite de l'utilisateur avant de procéder à la Phase 3.

Phase 3 : Implémentation

Principes Directeurs

Directives générales pour l'implémentation du skill :

Utilisez uv run, jamais python ou python3.
Préférez les bibliothèques stdlib qui viennent avec une installation Python 3 par défaut (urllib préféré) ; Évitez les bibliothèques qui nécessitent une installation supplémentaire si possible.
Les limites de débit doivent être documentées et respectées dans le code. Préférez la limitation de débit basée sur les verrous de fichiers pour que les sous-agents concurrents partageant la même machine respectent collectivement la limite. Consultez les autres skills du bundle Science Skills pour l'implémentation canonique sécurisée inter-processus.
La sortie du skill doit être <500 lignes ou redirigée vers un fichier. Les fichiers de sortie longs doivent être traités programmatiquement pour extraire les champs pertinents.
Les tirets sont recommandés pour le nom du skill et le champ YAML name:.

Règle 1 : Réutiliser les Skills Existants

Quand le workflow utilise une fonctionnalité couverte par un skill installé existant, le nouveau SKILL.md DOIT le référencer par nom plutôt que de le réimplémente. Incluez une section Dependencies dans le SKILL.md listant les skills requis avec une brève justification pour chacun.

Règle 2 : Limitation de Débit pour les Nouvelles APIs

Pour toute interaction API non couverte par un skill existant, le script CLI généré DOIT implémenter une limitation de débit. Avant d'écrire du code de limitation de débit, recherchez les directives de limite de débit officielles de l'API : consultez toute documentation que l'utilisateur a fournie pendant le brainstorming, puis recherchez la documentation publique de l'API en ligne. Si aucune limite de débit documentée ne peut être trouvée, utilisez par défaut 1 requête par seconde. Le pattern de limitation de débit est intégré directement au template CLI à references/cli_script_template.py — voir la classe RateLimitError et la méthode _request du client API.

Exigences clés :

Utilisez time.monotonic() pour le chronométrage (pas time.time()).
Calculez le délai à partir des limites de débit documentées.
Implémentez la réessai avec backoff exponentiel pour les erreurs transitoires (5xx).
Levez une RateLimitError dédiée quand HTTP 429 est reçu.
Enregistrez les tentatives de réessai sur stderr afin que l'agent puisse observer la progression.
Incluez l'URL et la valeur de limite de débit dans les messages d'erreur.
Sur les erreurs HTTP non-réessayables (p. ex. 400, 403, 404), lisez et incluez le corps de la réponse dans le message d'erreur — pas seulement le code d'état. Les corps de réponse API contiennent des détails exploitables (p. ex., « Invalid parameter ») qui permettent à l'agent de s'auto-corriger.

Règle 3 : Pattern de Script CLI (Par Défaut Quand du Code Est Nécessaire)

C'est le choix par défaut. Si une étape du workflow implique des appels API, du traitement de données, du I/O fichier, du calcul, ou tout autre travail programmatique, produisez un script CLI multi-commandes utilisant argparse avec sous-commandes. Suivez le template dans references/cli_script_template.py.

Exigences clés :

Chaque étape majeure du workflow devient une sous-commande.
Tous les sous-commandes acceptent --output pour écrire les résultats dans un fichier.
Utilisez json.dump avec indent=2 pour la sortie JSON.
Imprimez un message de succès avec le chemin du fichier de sortie.
Quittez avec le code 1 sur erreurs.
Rendez les arguments comme --limit requis (pas de defaults silencieux). Cela force l'agent à spécifier la valeur explicitement, l'empêchant d'supposer qu'il a récupéré « tous » les résultats quand il était silencieusement plafonné.

Règle 4 : Par Défaut la Sortie Fichier

Tous les scripts et workflows DOIVENT écrire la sortie dans des fichiers, pas stdout. Stdout devrait uniquement contenir de courts messages d'état (p. ex., « Success! Data written to: results.json »). C'est critique parce que :

Les réponses API peuvent être très grandes et seront tronquées dans la sortie terminal.
La sortie fichier est efficace en tokens — l'agent lit uniquement les champs dont il a besoin en utilisant jp ou des one-liners Python.
La grande sortie stdout gaspille l'espace de la fenêtre de contexte.

Règle 5 : Pattern Instructions Uniquement (Uniquement Quand Aucun Code N'Est Nécessaire)

Utilisez ce pattern uniquement quand le workflow nécessite zéro travail programmatique — c.-à-d., chaque étape concerne purement l'orchestration, le raisonnement, la coordination de plusieurs skills, ou le suivi d'un protocole écrit. Si une étape nécessite du code (appels API, traitement de données, I/O fichier, etc.), utilisez à la place le pattern CLI de la Règle 3. Produisez un SKILL.md avec une section workflow structurée :

## Workflow

### 1. Nom de l'Étape
- Description de ce qu'il faut faire
- Quel skill utiliser et comment

### 2. Étape Suivante
...

Règle 6 : Structure SKILL.md

Chaque SKILL.md généré doit suivre cette structure :

---
name: {skill-name}
description: >-
  {description}
---

# {Skill Title}

## Overview
{Brève description de ce que fait le skill.}

## Dependencies
{Liste des skills requis, le cas échéant.}

## Quick Start
{Exemple minimal pour démarrer.}

## Utility Scripts (si basé sur CLI)
{Documenter chaque sous-commande avec des exemples.}

## Workflow (si instructions uniquement)
{Étapes numérotées avec des instructions claires.}

## Rate Limiting (si applicable)
{Documenter les limites de débit et comment elles sont appliquées.}

## Common Mistakes
{Lister 2-3 pièges courants.}

Phase 4 : Validation

Après que l'implémentation soit complète :

Testez le skill manuellement en invoquant l'agent avec une invite en langage naturel qui devrait déclencher le nouveau skill.
Si une requête/réponse exemple a été fournie pendant le brainstorming, exécutez-la à travers le skill et vérifiez que la sortie correspond aux attentes.

workflow-skill-creator