Compétences des agents

Les compétences d’agent permettent à OpenCode de découvrir des instructions réutilisables à partir de votre dépôt ou de votre répertoire personnel. Les compétences sont chargées à la demande via l’outil natif skill : les agents voient les compétences disponibles et peuvent charger le contenu complet en cas de besoin.

---

Placer des fichiers

Créez un dossier par nom de compétence et insérez-y un SKILL.md. OpenCode recherche ces emplacements :

• Configuration du projet : .opencode/skills/<name>/SKILL.md
• Configuration globale : ~/.config/opencode/skills/<name>/SKILL.md
• Compatible Projet Claude : .claude/skills/<name>/SKILL.md
• Compatible Global Claude : ~/.claude/skills/<name>/SKILL.md
• Compatible avec l’agent de projet : .agents/skills/<name>/SKILL.md
• Compatible avec les agents globaux : ~/.agents/skills/<name>/SKILL.md

---

Comprendre la découverte

Pour les chemins locaux du projet, OpenCode remonte de votre répertoire de travail actuel jusqu’à ce qu’il atteigne l’arbre de travail git. Il charge tout skills/*/SKILL.md correspondant dans .opencode/ et tout .claude/skills/*/SKILL.md ou .agents/skills/*/SKILL.md correspondant en cours de route.

Les définitions globales sont également chargées à partir de ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md et ~/.agents/skills/*/SKILL.md.

---

Écrire un texte de présentation

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

• name (obligatoire)
• description (obligatoire)
• license (facultatif)
• compatibility (facultatif)
• metadata (facultatif, mappage chaîne à chaîne)

Les champs de contenu inconnus sont ignorés.

---

Valider les noms

name doit :

• Comprenant entre 1 et 64 caractères
• Être alphanumérique en minuscules avec des séparateurs à tiret unique
• Ne commence ni ne termine par -
• Ne contient pas de -- consécutifs
• Faites correspondre le nom du répertoire qui contient SKILL.md

Expression régulière équivalente :

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

---

Suivez les règles de longueur

description doit comporter entre 1 et 1 024 caractères. Gardez-le suffisamment précis pour que l’agent puisse choisir correctement.

---

Utiliser un exemple

Créez .opencode/skills/git-release/SKILL.md comme ceci :

---
name: git-release
description: Create consistent releases and changelogs
license: MIT
compatibility: opencode
metadata:
  audience: maintainers
  workflow: github
---

## What I do

- Draft release notes from merged PRs
- Propose a version bump
- Provide a copy-pasteable `gh release create` command

## When to use me

Use this when you are preparing a tagged release.
Ask clarifying questions if the target versioning scheme is unclear.

---

Reconnaître la description de l’outil

OpenCode répertorie les compétences disponibles dans la description de l’outil skill. Chaque entrée comprend le nom et la description de la compétence :

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
</available_skills>

L’agent charge une compétence en appelant l’outil :

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

---

Configurer les autorisations

Contrôlez les compétences auxquelles les agents peuvent accéder à l’aide d’autorisations basées sur des modèles dans opencode.json :

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

Autorisation	Comportement
allow	Les compétences se chargent immédiatement
deny	Compétence masquée à l’agent, accès refusé
ask	L’utilisateur est invité à donner son approbation avant le chargement

Les modèles prennent en charge les caractères génériques : internal-* correspond à internal-docs, internal-tools, etc.

---

Remplacement par agent

Accordez à des agents spécifiques des autorisations différentes de celles par défaut globales.

Pour les agents personnalisés (dans la rubrique Agent) :

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

Pour les agents intégrés (dans opencode.json) :

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

---

Désactiver l’outil de compétences

Désactivez complètement les compétences pour les agents qui ne devraient pas les utiliser :

Pour les agents personnalisés :

---
tools:
  skill: false
---

Pour les agents intégrés :

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

Lorsqu’elle est désactivée, la section <available_skills> est entièrement omise.

---

Dépanner le chargement

Si une compétence n’apparaît pas :

1. Vérifiez que SKILL.md est écrit en majuscules
2. Vérifiez que le frontmatter inclut name et description
3. Assurez-vous que les noms des compétences sont uniques sur tous les sites
4. Vérifiez les autorisations : les compétences avec deny sont masquées aux agents