Skill Miner

Que fait Skill Miner ?

Transformez les signaux enfouis dans les sessions passées de vos agents de codage en nouvelles et existantes « Agent Skills ». Une session ne devient une compétence que lorsqu'elle franchit cette porte — reproductible ET (marge d'amélioration OU demande répétée) :

1. Reproductible — la tâche ou la connaissance se répète, ou pourrait clairement se répéter. Une répétition passée est la preuve la plus solide, mais une tâche plausiblement récurrente compte ; un véritable cas unique ne compte jamais. (Obligatoire.)
2. Marge d'amélioration — il y a un feedback significatif, de sorte que la prochaine fois surpasse la première :
   • Feedback environnemental — ce que l'exécution du travail a révélé : échecs, bizarreries récurrentes de cet environnement, chemins détournés et leurs raccourcis, heuristiques durement acquises. Ce sont littéralement des compétences.
   • Feedback utilisateur — l'utilisateur est l'expert et son feedback est rare ; exploitez-le pour comprendre son raisonnement (une correction, une meilleure méthode qu'il connaissait, un fait que nous avons mal compris).
3. Une demande répétée — l'utilisateur demande continuellement la même chose ; extrayez-la une fois pour qu'il n'ait pas à redemander.

Pipeline : découvrir → distiller (LLM peu coûteux, par conversation) → regrouper, évaluer & générer.

0. Prérequis

Un petit LLM doit être accessible. Vérifiez-le d'abord :

python3 scripts/llm.py --check   # affiche le backend qu'il utilisera, ou comment en activer un

Définissez OPENAI_API_KEY / GEMINI_API_KEY / OPENROUTER_API_KEY, ou ayez une CLI claude / codex / gemini dans le PATH. Remplacez le modèle par SKILL_MINER_MODEL, forcez un backend avec SKILL_MINER_LLM.

1–2. Exécutez le pipeline (les scripts font le travail lourd avec un LLM peu coûteux)

Gardez votre répertoire de travail au répertoire de lancement : tous les artefacts vont dans ./out.

OUT=./out
python3 scripts/discover.py  --since 35 --out $OUT/inventory.jsonl       # trouve les transcriptions entre agents
python3 scripts/extract.py   --inventory $OUT/inventory.jsonl --out $OUT/conversations.jsonl --workers 10

• discover.py parcourt chaque adaptateur dans common.py:ADAPTERS (Claude Code, Codex, opencode ; ajoutez-en d'autres ici) et conserve les sessions des derniers --since jours. Commencez avec au maximum 100 conversations, sauf si l'utilisateur en demande plus. Ajoutez --limit 15 à extract.py pour un échantillonnage rapide.
• extract.py analyse chaque conversation et émet une ligne JSONL : agent, session_id, path, main_dir, datetime, n_user_turns, topics[], tasks[], skills_used[], env_feedback[], user_feedback[]. main_dir = le dossier le plus profond où la plupart du travail a eu lieu (d'après les fichiers édités / lus / mentionnés), pas le cwd de lancement. topics est la portée (généralement une — faisant aussi office de titre — pour le regroupement). tasks, env_feedback et user_feedback sont de courts tableaux que le LLM peu coûteux copie à partir des propres mots de l'utilisateur (chaque [] pour la session typique) — ils correspondent aux trois dimensions de la porte. L'appel peu coûteux ne voit que les tours de l'utilisateur, donc env_feedback est ce que l'utilisateur a dit à propos de ce qui a été exécuté, pas le résultat brut de l'outil — vérifiez-le à l'étape 4.

3. Regroupez les conversations

Lisez conversations.jsonl — une ligne par session. Avec ≤100 lignes, le fichier entier tient dans le contexte, alors lisez-le. (Si vous en avez extrait beaucoup plus, parcourez avec jq/grep pour les lignes avec env_feedback / user_feedback non vides d'abord, puis lisez les sections intéressantes.) Ignorez les lignes dont topics est <error> ou trivial/vide.

Regroupez par archétype de tâche — le TYPE de travail, pas seulement le répertoire (par exemple « débogage de déploiement CI », « itération d'interface utilisateur des paramètres », « migration de dépendances ») — pour évaluer la dimension 1 (reproductible) : quelles tâches se répètent ou pourraient clairement se répéter. Ensuite, à travers les lignes, rassemblez les deux autres dimensions :

• dimension 2 — les env_feedback et user_feedback qui pointent vers une manière de mieux faire une tâche la prochaine fois (commencez par le feedback environnemental). Une leçon durement acquise unique est une piste même sans groupe autour d'elle.
• dimension 3 — un détail qui revient dans les tasks de nombreuses sessions (l'utilisateur demande continuellement la même chose).

Mettez de côté les étapes de configuration uniques et les remarques isolées. Gardez des notes courtes : groupes nommés, chacun avec son nombre de conversations, les main_dir dominants, le feedback / les demandes répétées qu'il porte, et quelques exemples de paths à ouvrir comme preuve plus tard.

4. Évaluez et générez

Lisez references/quality-bar.md et appliquez sa porte : reproductible ET (feedback OU demande répétée).

1. Connaissez le paysage. Vérifiez vos compétences existantes pour voir ce qui peut être étendu — en particulier celles dont le feedback indique qu'elles ont échoué ; si un candidat chevauche une compétence, ouvrez ce SKILL.md et modifiez-le sur place. Pour trouver les chemins des fichiers de compétences :

   python3 scripts/skills_inventory.py
   

   Utilisez-le uniquement pour trouver les fichiers à modifier ; votre contexte reste la source de vérité pour le paysage. Si un candidat se concentre sur un dépôt spécifique, vérifiez quels documents Markdown existent déjà (README.md, documents de conception, plans) ; si la connaissance récurrente appartient à ces documents plutôt qu'à une compétence, recommandez cela à l'utilisateur dans votre rapport.
2. Confirmez via les transcriptions. Pour chaque piste, ouvrez 1 à 3 exemples de transcriptions (le champ path) pour confirmer que le signal est réel et pour capturer les spécificités — la règle exacte, l'erreur exacte et la solution de contournement, le meilleur chemin indiqué par l'utilisateur, la demande répétée. Lisez les mots de l'utilisateur autour de toute correction et autour des marqueurs [skill used: X]. Les lignes condensées ne montrent que les tours de l'utilisateur, donc la transcription est l'endroit où vous vérifiez ce que l'environnement a réellement fait. Séparez une bizarrerie récurrente (notez-la) d'une configuration unique (un piège d'une ligne au maximum).
3. Décidez, face à la porte. Une piste devient une compétence uniquement si elle est reproductible ET a soit une marge d'amélioration (feedback), soit une demande répétée. Les trois dimensions ont un poids égal — ne laissez pas tomber une leçon durement acquise parce que la tâche n'est apparue qu'une fois si elle se répète clairement, et ne publiez pas une tâche reproductible qui n'a rien à améliorer et aucune demande répétée.
4. Générez / modifiez ≤ 5 compétences. Écrivez chacune comme un contenu concret : la règle, le déclencheur, les étapes/commandes, la bizarrerie + la solution de contournement — avec des chemins de fichiers relatifs à la racine du dépôt (src/pages/Run.tsx), jamais d'absolus spécifiques à la machine (/home/<user>/…) copiés d'une transcription. Où cela atterrit :
   • Extension d'une compétence existante → modifiez-la sur place au chemin de la compétence. Ne la bifurquez pas et ne la copiez pas.
   • Une toute nouvelle compétence → écrivez-la sous ~/.agents/skills/generated-skills/<name>/, mise en attente pour que l'utilisateur la révise et la promouvoie — ne déposez pas de nouvelles compétences directement dans un répertoire actif.
5. Rapportez. Listez ce que vous avez créé/modifié et, pour chaque, de quelle(s) dimension(s) cela provient. Pour chaque candidat notable rejeté, dites en une ligne quelle dimension il a manquée. Incluez tous les documents de dépôt que vous pensez devoir être mis à jour à la place, ou en plus, des modifications de compétences.

Extension à d'autres agents

Chaque agent stocke les transcriptions différemment. Pour en supporter un nouveau (Gemini CLI, Cursor, …) ajoutez une paire (discover_fn, parse_fn) à common.py:ADAPTERS qui renvoie l'enregistrement normalisé (_norm(...)). Le reste du pipeline est inchangé. Cursor (sqlite state.vscdb) n'est pas encore câblé — l'adaptateur d'opencode est un modèle basé sur une base de données (SQLite) à suivre.

Remarques

• Lecture seule de vos transcriptions ; les seules écritures sont les artefacts --out et les compétences que vous choisissez de générer ou d'améliorer — les nouvelles compétences atterrissent mises en attente sous ~/.agents/skills/generated-skills/, les modifications se font sur place dans la compétence existante.
• Les fils de discussion de sous-agent / révision (chaînes latérales Claude Code, thread_source: subagent de Codex) sont filtrés — seules les vraies conversations utilisateur sont exploitées.

Visualisation des résultats

Exécuté de manière autonome, les résultats sont des fichiers simples : les artefacts sous ./out, et les compétences que vous avez modifiées (modifiées sur place, ou mises en attente sous generated-skills/). Cette compétence est également fournie avec Skill Studio, une application de bureau où l'utilisateur regarde l'exécution en direct, examine chaque nouvelle compétence mise en attente sous generated-skills/ comme une carte Proposée à Accepter ou Rejeter, et voit les modifications sur place comme des changements suivis par git pour enregistrer une version ou revenir en arrière.