Compétences OpenCode

Dans OpenCode,Agent Skillsest un mécanisme d'encapsulation de comportements réutilisables, viaSKILL.mddéfinis dans des fichiers, permettant aux LLM decharger à la demande et exécuter à la demandedes capacités spécifiques.

Par rapport aux prompts ordinaires, les Skills sont plus proches d'unités de capacités modulaires et peuvent être réutilisés dans plusieurs projets ou équipes.

Les Skills sont lesystème de plugins de capacitésd'OpenCode, qui fait passer le comportement de l'IA de prompts ponctuels à des modules de capacités réutilisables, rendant les workflows de développement plus standardisés, composables et applicables à des systèmes d'ingénierie complexes.

Les Skills existent sous forme de fichiers Markdown. Ils n'exécutent pas de fonctionnalité ; au contraire, grâce à un chargement à la demande et progressif, ils réalisent un transfert de connaissances efficace et réutilisable.

La plus grande différence entre les Skills et les prompts traditionnels est : le chargement à la demande + la divulgation progressive (ce n'est que lorsque c'est nécessaire que le gros SOP est fourré dans le contexte, ce qui économise grandement les tokens).

Mécanisme central

Les Skills utilisent l'outil intégréskillde gestion ; le workflow est le suivant :

1. Analyser les répertoires de compétences locaux et globaux
2. Exposer la liste des compétences disponibles dans le contexte
3. L'agent sélectionne automatiquement les compétences en fonction de la tâche
4. Charger le contenu de SKILL.md à la demande

Ce mécanisme évite de charger toutes les règles d'un coup, ce qui améliore les performances et l'utilisation du contexte.

Structure de base d'une compétence

Le cœur des compétences est :Un dossier + un fichier SKILL.md。

Le fichier SKILL.md contient :

• Métadonnées (au moins un nom et une description)
• Des instructions qui indiquent à l'IA comment accomplir une tâche spécifique

Une compétence est essentiellement un fichier Markdown (le nom de fichier est fixé à SKILL.md)

my-skill/
└── SKILL.md   （唯一必需）

Modèle de base de SKILL.md :

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
---

# PDF 处理

## 使用场景
当需要对 PDF 文件进行操作时使用，例如：

- 提取 PDF 文本或表格数据
- 填写 PDF 表单
- 合并多个 PDF 文件

## 提取文本
- 使用 `pdfplumber` 提取文本型 PDF 内容  
- 扫描版 PDF 需配合 OCR 工具  

## 填写表单
- 读取 PDF 表单字段  
- 按输入数据填充并生成新文件  

Exemple minimal requis :

---
name: skill-name
description: 说明该 Skill 的功能以及适用场景
---

Exemple avec champs optionnels :

---
name: pdf-processing
description: 从 PDF 中提取文本和表格，填写表单，并合并文档
license: Apache-2.0
metadata:
  author: example-org
  version: "1.0"
---

Si vous avez besoin de documents de référence, d'exemples de référence ou de scripts d'exécution, vous pouvez utiliser une structure de répertoire de Skill plus complexe :

my-skill/
├── SKILL.md      # 必需：指令 + 元数据
├── scripts/      # 可选：可执行代码
├── references/   # 可选：文档资料
└── assets/       # 可选：模板、资源

Fonctionnement des compétences

Les compétences utilisent le chargement progressif pour gérer efficacement le contexte :

• Découverte :Au démarrage, l'IA ne charge que le nom et la description de chaque compétence, en ne conservant que les informations d'identification les plus élémentaires.
• Activation :Lorsqu'une tâche correspond à la description d'une compétence, l'IA lit les instructions complètes de SKILL.md dans le contexte.
• Exécution :L'IA exécute selon les instructions, en chargeant les fichiers de référence ou en exécutant du code selon les besoins.

Cette conception garde l'IA rapide tout en lui permettant d'obtenir plus d'informations à la demande.

Emplacements des fichiers

Chaque compétence nécessite son propre dossier, et dans ce dossier vous placez leSKILL.mdfichier (remarque : le nom du fichier doit être entièrement en majuscules). OpenCode recherche automatiquement les six emplacements suivants :

Une structure de répertoire de projet typique est la suivante :

your-repo/
├── .opencode/
│   └── skills/
│       ├── git-release/
│       │   └── SKILL.md      ← 发版流程技能
│       ├── code-review/
│       │   └── SKILL.md      ← 代码审查技能
│       └── api-doc/
│           └── SKILL.md      ← API 文档编写技能
├── src/
└── package.json

Mécanisme de découverte

La découverte des compétences d'OpenCode est divisée en deux niveaux :

• Compétences locales au projet :OpenCode part du répertoire de travail actuel,remonte l'arborescence des répertoires niveau par niveau, jusqu'à atteindre la racine de l'arbre de travail Git. Dans ce processus, il collecte à chaque niveau de répertoire rencontré.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.mdtous les fichiers de compétences correspondants.

• Compétences globales :En même temps, à partir de~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.mdcharge toutes les compétences globales définies.

Les compétences des deux niveaux sont fusionnées et fournies à l'agent. Si une compétence locale au projet porte le même nom qu'une compétence globale,les compétences locales au projet sont prioritaires。

Écriture de SKILL.md

1. Champs du frontmatter

ChaqueSKILL.mdle fichier doit commencer par un frontmatter YAML (c'est-à-dire,---la partie encapsulée). OpenCode ne reconnaît que les champs suivants ; les champs inconnus sont automatiquement ignorés :

2. Règles de nommage

nameLa valeur du champ doit satisfaire simultanément toutes les conditions suivantes ; sinon, la compétence ne peut pas être chargée :

• La longueur est de1–64 caractères
• Ne peut contenir quedes lettres minusculesetdes chiffres, les mots peuvent utiliser un seul trait d'union (-) comme séparateur.
• Ne doit pas-commencer ou se terminer par
• Ne doit pas contenir de consécutifs--
• Doit correspondre au dossier conteneurSKILL.mddunom du dossier exactement.

Expression régulière équivalente :

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

Exemples de noms valides :git-release、api-doc、code-review、deploy2prod

Exemples de noms invalides :Git-Release(contient des majuscules),-releaseavec-au début),git--release(Continu--）

3. Rédaction de la description

descriptionLe contenu du champ affecte directement la capacité de l'agent à sélectionner et appeler correctement la compétence.Il est recommandé que la description soit précise et claire, en expliquant ce que fait la compétence et dans quels scénarios elle est utilisée, en évitant les descriptions trop générales :

• ❌ Trop général :Help complete the release task.
• ✅ Spécifique et clair :从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4. Exemple complet

Créer dans le projet.opencode/skills/git-release/SKILL.md, avec le contenu suivant :

Dans le Frontmatter, lanamevaleur doit être cohérente avec le nom du dossier. Dans cet exemple, le nom du dossier estgit-release, doncnameil doit aussi être écrit commegit-release, sinon la compétence ne peut pas être reconnue.

Comment les agents découvrent et chargent les compétences

Après le démarrage d’OpenCode, il injecte toutes les compétences actuellement disponibles au format XML dans laskilldescription de l’outil. Les agents peuvent savoir quelles compétences sont disponibles en consultant la description de l’outil :

<available_skills>
  <skill>
    <name>git-release</name>
    <description>Create consistent releases and changelogs</description>
  </skill>
  <skill>
    <name>code-review</name>
    <description>Perform structured code reviews with consistent criteria</description>
  </skill>
</available_skills>

Lorsque l’agent détermine qu’une compétence est pertinente pour la tâche en cours, il appelle proactivement l’skilloutil pour charger la compétence complèteSKILL.mdcontent:

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

Après le chargement, les instructions et les informations contextuelles définies dans la compétence entrent dans la mémoire de travail de l’agent, affectant ainsi son comportement et sa sortie ultérieurs. La compétence elle-même n’exécute automatiquement aucune opération ; elle fournit uniquement un contexte supplémentaire et des règles de comportement à l’agent.

Configuration des autorisations de compétences

Dansopencode.jsonDans, utilisezpermission.skillLe champ contrôle les compétences auxquelles l’agent peut accéder et prend en charge deux méthodes de correspondance : les noms exacts et les caractères génériques Glob :

Les effets spécifiques des trois actions d'autorisation sur les compétences sont les suivants :

Surcharge des autorisations par agent

Différents agents peuvent avoir besoin d'accéder à différents ensembles de compétences. Vous pouvez configurer les autorisations séparément pour chaque agent, en surchargeant les valeurs par défaut globales.

1. Configurer dans le Frontmatter de l'agent personnalisé

# 文件路径：~/.config/opencode/agents/my-agent.md
---
permission:
  skill:
    "documents-*": "allow"    # 该代理可以加载所有 documents- 开头的技能
                               # 其他技能遵循全局权限配置
---
 
You are a documentation assistant.

2. Configurer pour les agents intégrés dans opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "agent": {
    "plan": {                          // 内置代理名称
      "permission": {
        "skill": {
          "internal-*": "allow"        // plan 代理可以加载 internal- 开头的技能，
                                       // 即使全局配置中对其设置了 deny
        }
      }
    }
  }
}

Désactivation de l'outil Skill

Pour les agents qui n'ont pas du tout besoin d'utiliser des compétences, vous pouvez directement désactiver l'skilloutil. Après l'avoir désactivé,<available_skills>la liste sera complètement supprimée du contexte de l'agent, ce qui économise la consommation de tokens et empêche l'agent de tenter de charger la moindre compétence.

1. Désactiver dans le Frontmatter de l'agent personnalisé

2. Désactiver pour les agents intégrés dans opencode.json

Dépannage des problèmes de chargement des compétences

Si une compétence n'apparaît pas dans la liste disponible, vérifiez les éléments suivants dans l'ordre :

1. Confirmez la casse du nom de fichier

   SKILL.mdLe nom de fichier doit être en majuscules ; s’il est écrit commeskill.mdouSkill.mdil ne sera pas reconnu.

2. Vérifier la complétude du frontmatter

   Assurez-vousSKILL.mdil commence par un frontmatter YAML correct et contient lesnameetdescriptiondeux champs obligatoires. Si l’un des deux est manquant, la compétence ne sera pas chargée.

3. Confirmez que le nom de la compétence est unique et correctement formaté

   Si des compétences portant le même nom existent dans des chemins différents, des conflits peuvent survenir. Vérifiez égalementnamesi le champ respecte les règles de nommage (uniquement des lettres minuscules et des chiffres, séparés par des traits d’union) et correspond exactement au nom du dossier.

4. Vérifier la configuration des autorisations

   Dansopencode.jsondepermission.skillDans, si l’autorisation est"deny"La compétence sera complètement masquée à l’agent et n’apparaîtra pas dans la<available_skills>liste. Vérifiez si des règles avec caractères génériques (telles que"*": "deny") correspondre accidentellement à cette compétence.

Pour plus de compétences, vous pouvez consulter :

• Tutoriel sur les compétences :https://www.example.com/ai-agent/skills-agent.html