BuilderIO/adding-a-skill

Ajouter une compétence

Utilisez ceci pour le travail sur les compétences publiques dans ce dépôt. Conservez les modifications de compétences ordinaires dans skills/<nom-de-la-compétence>/ ; conservez les instructions propres au dépôt sous .agents/skills/.

Déterminez d'abord le type de compétence

• Compétence publique simple : un dossier normal sous skills/<nom>/ avec SKILL.md. C'est le cas courant. @agent-native/skills les découvre dynamiquement à partir de BuilderIO/skills@main, donc il n'y a pas de registre de framework à modifier juste pour que npx @agent-native/skills@latest add --skill <nom> fonctionne.
• Compétence de type instruction : une compétence simple qui doit éventuellement écrire une ligne AGENTS.md / CLAUDE.md gérée et toujours active lorsque les utilisateurs passent --update-instructions. Ces compétences nécessitent une modification supplémentaire du framework ; voir « Blocs d'instructions gérés » ci-dessous.
• Compétence avec application ou MCP : une compétence qui enregistre un serveur MCP hébergé ou local ou utilise un comportement d'installation appartenant au framework. Ce ne sont pas des compétences publiques simples ; examinez ../agent-native/framework/packages/core/src/cli/skills.ts et ../agent-native/framework/packages/skills/src/built-in-apps.ts.
• Compétences Plan : visual-plan et visual-recap ont des copies générées/synchronisées entre ce dépôt et ../agent-native/framework. Ne les traitez pas comme un dossier de prose autonome.

Liste de contrôle pour les compétences publiques simples

1. Créez ou mettez à jour skills/<nom-de-la-compétence>/SKILL.md.

2. Ajoutez skills/<nom-de-la-compétence>/README.md lorsque la compétence doit apparaître dans le catalogue public. Ce dépôt utilise intentionnellement les README pour les pages de compétences publiques.

3. Si le positionnement dans la collection change, mettez à jour le README.md racine, .codex-plugin/plugin.json, .claude-plugin/plugin.json et les descriptions dans package.json.

4. Gardez la compétence concise. Placez uniquement les instructions essentielles pour l'agent dans SKILL.md ; évitez les documents supplémentaires sauf s'ils soutiennent directement la compétence.

5. Validez avec :

   python3 /Users/steve/.codex/skills/.system/skill-creator/scripts/quick_validate.py skills/<nom-de-la-compétence>
   

6. Testez la découverte d'installation localement avant d'affirmer que le chemin CLI fonctionne :

   node ../agent-native/framework/packages/skills/dist/cli.js add --copy . --skill <nom-de-la-compétence> --client codex --scope project --dry-run --json
   

7. Exécutez npm run check. Si cela échoue sur la synchronisation visual-plan / visual-recap alors que la modification n'est pas liée, signalez-le spécifiquement au lieu de réécrire ces compétences à la légère.

Chemin d'installation de @agent-native/skills

Pour une compétence publique simple, le chemin d'installation est dynamique :

• ../agent-native/framework/packages/skills/src/index.ts définit DEFAULT_SKILLS_SOURCE = "BuilderIO/skills".

• Il matérialise ce dépôt, lit les manifestes des plugins via resolveSkillsRoot, et découvre chaque skills/*/SKILL.md via discoverSkills.

• Par conséquent, un nouveau dossier sous skills/<nom>/ est suffisant pour :

  npx @agent-native/skills@latest add --skill <nom>
  

Aucune modification du registre intégré de @agent-native/core n'est nécessaire, sauf si la compétence est adossée à une application ou nécessite un comportement d'installation personnalisé.

Blocs d'instructions gérés

Si la compétence doit affecter AGENTS.md / CLAUDE.md via --update-instructions, mettez à jour le wrapper du framework :

• Ajoutez une ligne concise dans ../agent-native/framework/packages/skills/src/index.ts à l'intérieur de instructionContentForSkill(skillName).

• Ajoutez ou mettez à jour les tests dans ../agent-native/framework/packages/skills/src/index.spec.ts.

• Exécutez :

  pnpm --filter @agent-native/skills test -- src/index.spec.ts --runInBand
  

Utilisez ceci pour les règles de comportement durables comme quick-recap, efficient-fable, stay-within-limits, et probablement les comportements axés sur la documentation comme read-the-damn-docs.

Compétences avec application ou MCP

Si une compétence nécessite des outils hébergés, une authentification, un enregistrement MCP, un mode de fichiers locaux ou des indicateurs d'installation spéciaux, examinez le framework avant de modifier :

• ../agent-native/framework/packages/core/src/cli/skills.ts
• ../agent-native/framework/packages/skills/src/built-in-apps.ts
• ../agent-native/framework/packages/skills/src/sync-with-core.spec.ts

Gardez les descripteurs MCP du framework et de @agent-native/skills autonome synchronisés.

Pièges de synchronisation des compétences Plan

visual-plan et visual-recap sont spéciaux :

• Le framework contient des copies canoniques/générées et des bundles du marketplace Plan.
• La commande npm run check de ce dépôt compare ces copies et peut échouer en cas de dérive non liée à une nouvelle compétence simple.
• Lorsque vous modifiez intentionnellement les compétences Plan, utilisez les chemins de synchronisation du framework au lieu de modifier manuellement les copies générées. Recherchez dans le framework sync-plan-marketplace, sync-workspace-skills et skills.sync.spec.ts.

Rapport final

En terminant une modification de compétence, informez l'utilisateur :

• Quels fichiers de compétence ont été modifiés.
• Si la découverte d'installation dynamique de @agent-native/skills est suffisante.
• Si une modification d'instruction gérée du framework a été ajoutée ou intentionnellement laissée comme suivi.
• Quelles commandes de validation ont réussi ou échoué, y compris les échecs de synchronisation Plan non liés.