File size: 5,661 Bytes
0dbc9de | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 | ---
title: "Compétences des agents"
description: "Définir un comportement réutilisable via les définitions SKILL.md"
---
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 :
```text
^[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 :
```markdown
---
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 :
```xml
<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` :
```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) :
```yaml
---
permission:
skill:
"documents-*": "allow"
---
```
**Pour les agents intégrés** (dans `opencode.json`) :
```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** :
```yaml
---
tools:
skill: false
---
```
**Pour les agents intégrés** :
```json
{
"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
|