Création de compétences

Cette compétence vous aide à créer de nouvelles compétences et à en améliorer les existantes. Pensez-y comme la compétence qui vous enseigne comment apprendre.

Pourquoi se donner la peine d'utiliser des compétences ?

Chaque fois que vous résolvez un problème, cette connaissance meurt généralement avec la session. Les compétences règlent ça. C'est comment vous transformez « j'ai trouvé la solution une fois » en « je sais faire ça ».

Quelques raisons d'extraire des compétences :

• Vous n'aurez pas à redécouvrir la même solution le mois prochain
• Les autres sessions (et les autres utilisateurs) bénéficient de ce que vous avez appris
• Les workflows complexes deviennent répétables au lieu d'être fragiles

Le format de base

Les compétences vivent dans un dossier avec un fichier SKILL.md :

.factory/skills/my-skill/
└── SKILL.md

Le fichier a du frontmatter YAML et du contenu markdown :

---
name: my-skill
version: 1.0.0
description: |
  What this skill does.
  When to use it.
---

# My skill

Instructions go here.

La description a une grande importance. C'est comment l'agent décide de charger votre compétence pour une tâche donnée. Soyez spécifique sur les problèmes qu'elle résout.

Quand créer une compétence

Tout ne mérite pas d'être une compétence. Les compétences sont faites pour les workflows complexes ou longs que quelqu'un pourrait avoir besoin de répéter ou de partager. Si c'est une simple tâche ponctuelle, une compétence est exagéré.

Le bon niveau de spécificité compte. Une compétence pour « déboguer dans une base de code » est utile s'il y a beaucoup de modes de défaillance courants que les agents pourraient rencontrer. Une compétence pour « déboguer le flux de connexion » est probablement trop étroite. Trouvez l'équilibre entre assez générale pour être réutilisée et assez spécifique pour être utile.

Posez-vous la question :

• Ai-je dû chercher dur pour comprendre ça ?
• Serais-je agacé si je devais résoudre ça à nouveau de zéro ?
• Y a-t-il quelque chose ici qui n'est pas évident à partir de la doc ?

Si oui à l'une de ces questions, ça vaut probablement la peine d'extraire. Si c'était simple ou vous avez juste suivi un tutoriel, passez.

Les compétences peuvent aussi encoder des préférences et des bonnes pratiques. Peut-être qu'un utilisateur se connecte toujours à une plateforme spécifique quand il fait de l'analyse de données. Peut-être qu'il y a un piège que l'équipe continue de rencontrer. Si vous remarquez que vous faites systématiquement quelque chose que l'utilisateur doit corriger ou ajuster, ça vaut la peine d'inclure.

Extraire des compétences à partir de sessions

Utilisez la compétence session-navigation pour explorer les sessions passées et trouver des motifs qui méritent d'être extraits. Cherchez des choses qui sont revenues plusieurs fois, des solutions qui ont demandé un vrai effort pour être trouvées, ou des workflows que vous répétez.

Une fois que vous avez trouvé quelque chose, généralisez-le. Remplacez les chemins spécifiques par des motifs, notez les conditions préalables, appelez l'attention sur les suppositions. La compétence devrait fonctionner pour des situations similaires, pas juste le cas exact que vous avez trouvé.

Conseils de conception de compétences

Quand vous écrivez la compétence, utilisez la compétence human-writing. Les docs de compétences qui lisent comme du discours marketing sont plus difficiles à suivre.

Commencez petit. Une compétence qui fait bien une chose bat une compétence qui essaie de couvrir tout. Vous pouvez toujours composer plusieurs compétences ensemble.

Incluez la vérification. Comment saurez-vous que la compétence a fonctionné ? Ajoutez une vérification à la fin :

## Verify it worked

Run `npm test` and make sure nothing broke.
Check that the new file exists at `src/config.ts`.

Documentez aussi les défaillances. Qu'est-ce qui ne marche pas ? Qu'est-ce que vous devriez éviter ? Cela économise des problèmes futurs :

## What not to do

Don't run this on a dirty git working directory.
The `--force` flag will overwrite without asking.

Gardez-le frais. Les compétences vieillissent. Les dépendances changent, les API se mettent à jour, de meilleures approches émergent. Si une compétence cesse de fonctionner ou semble obsolète, mettez-la à jour ou supprimez-la.

Où vivent les compétences

Les compétences du projet sont bonnes pour les conventions d'équipe. Les compétences personnelles sont bonnes pour vos propres workflows.

Améliorer les compétences existantes

Signes qu'une compétence a besoin de travail :

• Les utilisateurs posent des questions de suivi après qu'elle s'exécute
• Elle échoue sur les cas limites qui reviennent constamment
• Il y a une meilleure approche maintenant que quand elle a été écrite

Pour trouver des motifs :

# Which sessions used this skill?
rg -l "skill-name" ~/.factory/sessions/*.jsonl

# Where did things go wrong?
rg "error|failed|retry" ~/.factory/sessions/*.jsonl -C 3

Quand vous mettez à jour une compétence, incrémentez la version. Si c'est un changement cassant (sortie différente, entrées différentes), incrémentez la version majeure.

Notes de recherche

Une partie de ceci provient de travaux académiques sur les agents qui apprennent :

Voyager a montré que les agents peuvent construire des bibliothèques de compétences au fil du temps, chaque compétence composée de compétences plus simples.

CASCADE a démontré que les compétences peuvent être partagées entre agents, pas seulement stockées pour l'utilisation d'un seul agent.

SEAgent a trouvé que l'apprentissage à partir des défaillances est aussi précieux que l'apprentissage à partir des succès.

Reflexion a montré que le feedback verbal (expliquer ce qui s'est mal passé en langage naturel) surpasse les scores numériques pour améliorer le comportement des agents.

La boucle

1. Travaillez sur quelque chose
2. Remarquez quand vous apprenez quelque chose de non-évident
3. Extrayez-le comme une compétence
4. Utilisez la compétence la prochaine fois
5. Améliorez la compétence en fonction de comment ça se passe
6. Répétez