Competences d'agent

Les competences d’agent permettent a OpenCode de decouvrir des instructions reutilisables a partir de votre depot ou de votre repertoire personnel. Les competences sont chargees a la demande via l’outil natif skill — les agents voient les competences disponibles et peuvent charger le contenu complet lorsque necessaire.

---

Placer les fichiers

Crez un dossier par nom de competence et placez un SKILL.md a l’interieur. OpenCode recherche ces emplacements :

• Configuration du projet : .opencode/skill/<name>/SKILL.md
• Configuration globale : ~/.config/opencode/skill/<name>/SKILL.md
• Compatible Claude du projet : .claude/skills/<name>/SKILL.md
• Compatible Claude global : ~/.claude/skills/<name>/SKILL.md

---

Comprendre la decouverte

Pour les chemins locaux du projet, OpenCode remonte a partir de votre repertoire de travail actuel jusqu’a ce qu’il atteigne l’arborescence de travail git. Il charge tous les skill/*/SKILL.md correspondants dans .opencode/ et tous les .claude/skills/*/SKILL.md correspondants en chemin.

Les definitions globales sont egalement chargees a partir de ~/.config/opencode/skill/*/SKILL.md et ~/.claude/skills/*/SKILL.md.

---

Ecrire le frontmatter

Chaque SKILL.md doit commencer par un frontmatter YAML. Seuls ces champs sont reconnus :

• name (obligatoire)
• description (obligatoire)
• license (facultatif)
• compatibility (facultatif)
• metadata (facultatif, carte de chaine a chaine)

Les champs de frontmatter inconnus sont ignores.

---

Valider les noms

name doit :

• Avoir 1 a 64 caracteres
• Etre alphanumerique en minuscules avec des separateurs de tiret unique
• Ne pas commencer ou finir par -
• Ne pas contenir de -- consecutifs
• Correspondre au nom du repertoire contenant SKILL.md

Expression regex equivalente :

^[a-z0-9]+(-[a-z0-9]+)*$

---

Suivre les regles de longueur

description doit avoir 1 a 1024 caracteres. Gardez-la suffisamment specifique pour que l’agent puisse choisir correctement.

---

Utiliser un exemple

Creez .opencode/skill/git-release/SKILL.md comme ceci :

---
name: git-release
description: Creer des versions et des journaux des modifications coherents
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## Ce que je fais

- Rediger des notes de version a partir des PR fusionnes
- Proposer une incrementation de version
- Fournir une commande `gh release create` copiable

## Quand m'utiliser

Utilisez ceci lorsque vous preparez une version etiquetee.
Posez des questions de clarification si le schema de versionnement cible n'est pas clair.

---

Reconnaitre la description de l’outil

OpenCode liste les competences disponibles dans la description de l’outil skill. Chaque entree comprend le nom et la description de la competence :

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Creer des versions et des journaux des modifications coherents</description>
  </skill>
</available_skills>

L’agent charge une competence en appelant l’outil :

skill({ name: "git-release" })

---

Configurer les autorisations

Controlez les competences auxquelles les agents peuvent acceder en utilisant des autorisations basees sur des modeles dans opencode.json :

{
  "permission": {
    "skill": {
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask",
      "*": "allow"
    }
  }
}

Permission	Comportement
allow	La competence se charge immediatement
deny	Competence masquee a l’agent, acces refuse
ask	Utilisateur invite a approuver avant le chargement

Les modeles prennent en charge les caracteres generiques : internal-* correspond a internal-docs, internal-tools, etc.

---

Remplacer par agent

Donnez a des agents specifiques des autorisations differentes des valeurs globales par defaut.

Pour les agents personnalises (dans le frontmatter de l’agent) :

---
permission:
  skill:
    "documents-*": "allow"
---

Pour les agents integres (dans opencode.json) :

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

---

Desactiver l’outil skill

Desactivez completement les competences pour les agents qui ne devraient pas les utiliser :

Pour les agents personnalises :

---
tools:
  skill: false
---

Pour les agents integres :

{
  "agent": {
    "plan": {
      "tools": {
        "skill": false
      }
    }
  }
}

Lorsqu’il est desactive, la section <available_skills> est entierement omise.

---

Resoudre les problemes de chargement

Si une competence n’apparait pas :

1. Verifiez que SKILL.md est ecrit en majuscules
2. Verifiez que le frontmatter inclut name et description
3. Assurez-vous que les noms de competences sont uniques dans tous les emplacements
4. Verifiez les autorisations — les competences avec deny sont masquees aux agents