OpenCode-Fähigkeiten

In OpenCode istAgent Skillsein Mechanismus zum Kapseln wiederverwendbarer Verhaltensweisen, durchSKILL.mdin Dateien definiert, wodurch LLMs in die Lage versetzt werden,bei Bedarf zu laden und bei Bedarf auszuführenspezifische Fähigkeiten.

Im Vergleich zu gewöhnlichen Prompts sind Skills eher modulare Fähigkeitseinheiten und können über mehrere Projekte oder Teams hinweg wiederverwendet werden.

Skills sind OpenCodesFähigkeits-Plugin-System, das das Verhalten der KI von einmaligen Prompts zu wiederverwendbaren Fähigkeitsmodulen aufwertet und Entwicklungs-Workflows standardisierter, komponierbarer und auf komplexe Engineering-Systeme anwendbar macht.

Skills existieren als Markdown-Dateien. Sie führen keine Funktionalität aus; stattdessen erreichen sie durch bedarfsgesteuertes, progressives Laden eine effiziente und wiederverwendbare Wissensvermittlung.

Der größte Unterschied zwischen Skills und traditionellen Prompts ist: bedarfsgesteuertes Laden + progressive Offenlegung (nur bei Bedarf wird das dicke SOP in den Kontext gestopft, was Tokens stark spart).

Kernmechanismus

Skills nutzen das integrierteskillTool zur Verwaltung; der Workflow ist wie folgt:

1. Lokale und globale Skill-Verzeichnisse scannen
2. Die Liste der verfügbaren Skills im Kontext bereitstellen
3. Der Agent wählt Skills automatisch basierend auf der Aufgabe aus.
4. SKILL.md-Inhalt bei Bedarf laden

Dieser Mechanismus vermeidet das Laden aller Regeln auf einmal und verbessert die Leistung und Kontextnutzung.

Kernstruktur eines Skills

Der Kern von Skills ist:Ein Ordner + eine SKILL.md-Datei。

Die SKILL.md-Datei enthält:

• Metadaten (mindestens einen Namen und eine Beschreibung)
• Anweisungen, die der KI mitteilen, wie eine bestimmte Aufgabe zu erledigen ist

Ein Skill ist im Wesentlichen eine Markdown-Datei (der Dateiname ist auf SKILL.md festgelegt)

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

SKILL.md-Basisvorlage:

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

# PDF 处理

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

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

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

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

Minimal erforderliches Beispiel:

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

Beispiel mit optionalen Feldern:

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

Wenn Sie Referenzmaterialien, Referenzbeispiele oder Ausführungsskripte benötigen, können Sie eine komplexere Skill-Verzeichnisstruktur verwenden:

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

So funktionieren Skills

Skills verwenden progressives Laden, um den Kontext effizient zu verwalten:

• Erkennung:Beim Start lädt die KI nur den Namen und die Beschreibung jedes Skills und behält nur die grundlegendsten Identifikationsinformationen bei.
• Aktivierung:Wenn eine Aufgabe mit der Beschreibung eines Skills übereinstimmt, liest die KI die vollständigen Anweisungen aus SKILL.md in den Kontext.
• Ausführung:Die KI führt die Anweisungen aus, wobei sie bei Bedarf Referenzdateien lädt oder Code ausführt.

Dieses Design hält die KI schnell und ermöglicht es ihr, bei Bedarf weitere Informationen zu erhalten.

Speicherorte für Dateien

Jeder Skill benötigt einen eigenen Ordner, und in diesem Ordner platzieren Sie dieSKILL.mdDatei (Hinweis: Der Dateiname muss vollständig in Großbuchstaben geschrieben sein). OpenCode durchsucht automatisch die folgenden sechs Speicherorte:

Eine typische Projektverzeichnisstruktur sieht wie folgt aus:

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

Erkennungsmechanismus

Die Skill-Erkennung von OpenCode ist in zwei Ebenen unterteilt:

• Projektlokale Skills:OpenCode beginnt im aktuellen Arbeitsverzeichnis,durchläuft den Verzeichnisbaum Ebene für Ebene nach oben, bis es das Stammverzeichnis des Git-Arbeitsbaums erreicht. Dabei sammelt es von jeder Verzeichnisebene auf dem Weg.opencode/skills/*/SKILL.md、.claude/skills/*/SKILL.md、.agents/skills/*/SKILL.mdalle passenden Skill-Dateien.

• Globale Skills:Gleichzeitig werden dabei von dort~/.config/opencode/skills/*/SKILL.md、~/.claude/skills/*/SKILL.md、~/.agents/skills/*/SKILL.mdalle definierten globalen Skills geladen.

Skills aus beiden Ebenen werden zusammengeführt und dem Agenten bereitgestellt. Wenn ein projektlokaler Skill denselben Namen wie ein globaler Skill hat,haben projektlokale Skills Vorrang。

SKILL.md schreiben

1. Frontmatter-Felder

JedesSKILL.mdDatei muss mit YAML-Frontmatter beginnen (d. h.,---der umschlossene Teil). OpenCode erkennt nur die folgenden Felder; unbekannte Felder werden automatisch ignoriert:

2. Namensregeln

nameDer Wert des Feldes muss alle folgenden Bedingungen gleichzeitig erfüllen; andernfalls kann der Skill nicht geladen werden:

• Die Länge beträgt1–64 Zeichen
• Darf nurKleinbuchstabenundZahlenenthalten, Wörter können einen einzelnen Bindestrich (-) als Trennzeichen.
• Darf nicht-beginnen oder enden mit
• Darf keine aufeinanderfolgenden enthalten--
• Muss mit dem enthaltenden übereinstimmenSKILL.mddesOrdnernamens exakt.

Äquivalenter regulärer Ausdruck:

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

Gültige Benennungsbeispiele:git-release、api-doc、code-review、deploy2prod

Ungültige Benennungsbeispiele:Git-Release(enthält Großbuchstaben),-release(mit-am Anfang),git--release(Fortlaufend--）

3. Die Beschreibung schreiben

descriptionDer Inhalt des Feldes wirkt sich direkt darauf aus, ob der Agent den Skill korrekt auswählen und aufrufen kann.Es wird empfohlen, dass die Beschreibung spezifisch und klar istund erklärt, was der Skill tut und in welchen Szenarien er verwendet wird, wobei übermäßig allgemeine Beschreibungen vermieden werden:

• ❌ Zu allgemein:Help complete the release task.
• ✅ Spezifisch und klar:从合并的 PR 中起草发版说明、提出版本号建议，并生成可直接使用的 gh release create 命令

4. Vollständiges Beispiel

Im Projekt erstellen.opencode/skills/git-release/SKILL.md, mit folgendem Inhalt:

Im Frontmatter, dernameWert muss mit dem Ordnernamen übereinstimmen. In diesem Beispiel ist der Ordnernamegit-release, alsonameer muss auch geschrieben werden alsgit-release, andernfalls kann der Skill nicht erkannt werden.

Wie Agenten Skills entdecken und laden

Nachdem OpenCode gestartet ist, injiziert es alle derzeit verfügbaren Skills im XML-Format in dieskillToolbeschreibung. Agenten können erfahren, welche Skills verfügbar sind, indem sie die Toolbeschreibung einsehen:

<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>

Wenn der Agent feststellt, dass ein Skill für die aktuelle Aufgabe relevant ist, ruft er proaktiv dasskillTool auf, um den vollständigen Skill zu ladenSKILL.mdcontent:

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

Nach dem Laden gelangen die im Skill definierten Anweisungen und Kontextinformationen in das Arbeitsgedächtnis des Agenten und beeinflussen dadurch das nachfolgende Verhalten und die Ausgabe. Der Skill selbst führt keine Operationen automatisch aus; er stellt dem Agenten nur zusätzlichen Kontext und Verhaltensregeln bereit.

Konfigurieren von Skill-Berechtigungen

Inopencode.jsonIn, verwenden Siepermission.skillDas Feld steuert, auf welche Skills der Agent zugreifen kann, und unterstützt zwei Übereinstimmungsmethoden: exakte Namen und Glob-Wildcards:

Die konkreten Auswirkungen der drei Berechtigungsaktionen auf Skills sind wie folgt:

Berechtigungen pro Agent überschreiben

Verschiedene Agenten benötigen möglicherweise Zugriff auf unterschiedliche Skill-Sets. Sie können Berechtigungen für jeden Agenten separat konfigurieren und dabei die globalen Standardeinstellungen überschreiben.

1. Im Frontmatter des benutzerdefinierten Agenten konfigurieren

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

2. Für integrierte Agenten in opencode.json konfigurieren

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

Deaktivieren des Skill-Tools

Für Agenten, die überhaupt keine Skills verwenden müssen, kannst du direkt dasskillTool deaktivieren. Nach dem Deaktivieren<available_skills>wird die Liste vollständig aus dem Kontext des Agenten entfernt, was Token-Verbrauch spart und verhindert, dass der Agent versucht, Skills zu laden.

1. Im Frontmatter des benutzerdefinierten Agenten deaktivieren

2. Für integrierte Agenten in opencode.json deaktivieren

Fehlerbehebung bei Problemen beim Laden von Skills

Wenn ein Skill nicht in der verfügbaren Liste erscheint, prüfe die folgenden Punkte der Reihe nach:

1. Überprüfe die Groß-/Kleinschreibung des Dateinamens

   SKILL.mdDer Dateiname muss vollständig in Großbuchstaben geschrieben sein; wenn er alsskill.mdoderSkill.mdwird er nicht erkannt.

2. Frontmatter-Vollständigkeit prüfen

   Stellen Sie sicherSKILL.mdes beginnt mit korrektem YAML-Frontmatter und enthält dienameunddescriptionzwei erforderlichen Felder. Wenn eines davon fehlt, wird der Skill nicht geladen.

3. Bestätige, dass der Skill-Name eindeutig und korrekt formatiert ist

   Wenn Skills mit demselben Namen in verschiedenen Pfaden existieren, kann es zu Konflikten kommen. Prüfe außerdemnameob das Feld den Namensregeln entspricht (nur Kleinbuchstaben und Zahlen, durch Bindestriche getrennt) und exakt mit dem Ordnernamen übereinstimmt.

4. Berechtigungskonfiguration prüfen

   Inopencode.jsonvonpermission.skillIn, wenn die Berechtigung"deny"Der Skill wird vor dem Agenten vollständig verborgen und erscheint nicht in der<available_skills>Liste. Prüfe, ob Platzhalterregeln (wie z. B."*": "deny") versehentlich mit diesem Skill übereinstimmen.

Weitere Skills findest du unter:

• Skills-Tutorial:https://www.example.com/ai-agent/skills-agent.html