zhangliang0115/ai-plugin

Rédaction d'une compétence SKILL.md multi-agents

Une compétence est un dossier contenant un fichier SKILL.md. Celui-ci commence par un bloc YAML de métadonnées (nom + description) suivi d'instructions Markdown que l'agent charge à la demande. Étant donné que Claude Code, DeepSeek Harness (dsh), Codex CLI, Gemini CLI, Copilot et Cursor lisent tous ce même format, une compétence bien rédigée est utilisable par chaque agent.

Anatomie

ma-competence/
├── SKILL.md            # obligatoire : métadonnées + instructions
├── references/         # facultatif : documentation longue que le modèle lit à la demande
└── scripts/            # facultatif : scripts d'aide que la compétence peut exécuter

---
name: ma-competence
description: >-
  Une ou deux phrases : ce qu'elle fait ET quand l'utiliser. C'est le déclencheur
  que l'agent fait correspondre à la demande de l'utilisateur — rédigez-le comme une règle de routage.
---

# Ma compétence

Instructions étape par étape. Supposez un ingénieur compétent ; soyez concret, pas vague.

Règles qui déterminent si une compétence fonctionne

1. name doit être en kebab-case — lettres minuscules, chiffres, traits d'union ; 64 caractères max. Les agents rejettent ou déforment les autres noms. aipx normalise pour vous, mais fournissez-le correctement.
2. description est le déclencheur, pas la documentation. Mauvais : « Utilitaires pour travailler avec des choses. » Bon : « Résumer des vidéos YouTube/Bilibili et des podcasts à partir d'une URL. À utiliser lorsque l'utilisateur colle un lien vidéo ou audio. »
3. Gardez SKILL.md sous ~500 lignes. Mettez la profondeur dans references/*.md et faites-y référence (« voir references/schema.md »). Les agents ne chargent le corps que lorsque la compétence se déclenche ; les corps volumineux gaspillent du contexte et diluent le comportement.
4. Pas de compétences imbriquées. La découverte ne scanne que les enfants directs d'une racine de compétence — competences/a/SKILL.md est trouvé, competences/a/b/SKILL.md ne l'est pas.
5. Les liens relatifs doivent rester relatifs. Si SKILL.md référence scripts/x.py, tout le dossier voyage ensemble — ne liez jamais en dehors du répertoire de la compétence.

Où vivent les compétences (racines utilisateur)

Racine	Lu par
~/.agents/skills/<nom>/SKILL.md	DeepSeek Harness (dsh), Codex CLI
~/.claude/skills/<nom>/SKILL.md	Claude Code
~/.gemini/skills/<nom>/SKILL.md	Gemini CLI
~/.copilot/skills/<nom>/SKILL.md	GitHub Copilot CLI

Il existe aussi des équivalents à portée de projet (par exemple .claude/skills/, .agents/skills/ dans le dépôt). Ne copiez pas à la main — utilisez aipx sync pour lier une copie dans chaque racine d'agent.

Tester avant de publier

# Est-ce que ça s'analyse et se découvre ?
aipx install ./ma-competence --dry-run
aipx install ./ma-competence
aipx list

Ensuite, ouvrez votre agent et confirmez que la compétence apparaît (Claude Code : elle s'affiche dans la liste des compétences ; dsh : palette de commandes / → groupe Skills).

Liste de vérification pour la publication

• Le dépôt contient le dossier de la compétence à un chemin stable, par ex. skills/ma-competence/
• description indique les conditions de déclenchement, pas seulement les fonctionnalités
• Fonctionne à partir d'une installation propre (aipx install proprietaire/depot#chemin:/skills/ma-competence)
• Ajoutez des sujets GitHub pour que la découverte fonctionne : agent-skills, claude-code, dsh-plugin (s'il fournit aussi un bundle dsh), deepseek (si lié à DS)
• Facultatif : emballage double-cible — voir les compétences dsh-plugin-dev et claude-plugin-dev