Zum Inhalt springen
OpenCode
app.header.homeapp.header.docs

Agent Skills

Definiere wiederverwendbares Verhalten ueber SKILL.md

Agent Skills erlauben OpenCode, wiederverwendbare Anweisungen aus deinem Repo oder Home-Verzeichnis zu finden. Sie werden bei Bedarf ueber das native skill-Tool geladen, wenn ein Agent sie wirklich braucht.

Place files

Erstelle pro Skill-Namen einen Ordner und lege dort eine SKILL.md ab. OpenCode sucht in folgenden Pfaden:

  • Project config: .opencode/skills/<name>/SKILL.md
  • Global config: ~/.config/opencode/skills/<name>/SKILL.md
  • Project Claude-compatible: .claude/skills/<name>/SKILL.md
  • Global Claude-compatible: ~/.claude/skills/<name>/SKILL.md
  • Project agent-compatible: .agents/skills/<name>/SKILL.md
  • Global agent-compatible: ~/.agents/skills/<name>/SKILL.md

Understand discovery

Bei projektlokalen Pfaden laeuft OpenCode vom aktuellen Verzeichnis nach oben bis zum Git-Worktree. Dabei werden passende skills/*/SKILL.md in .opencode/ sowie passende Dateien unter .claude/skills/*/SKILL.md und .agents/skills/*/SKILL.md geladen.

Globale Definitionen kommen zusaetzlich aus ~/.config/opencode/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md und ~/.agents/skills/*/SKILL.md.

Write frontmatter

Jede SKILL.md muss mit YAML-Frontmatter beginnen. Nur diese Felder werden ausgewertet:

  • name (required)
  • description (required)
  • license (optional)
  • compatibility (optional)
  • metadata (optional, string-to-string map)

Unbekannte Frontmatter-Felder werden ignoriert.

Validate names

name muss:

  • 1-64 Zeichen lang sein
  • nur Kleinbuchstaben und Ziffern mit einzelnen Bindestrichen enthalten
  • nicht mit - beginnen oder enden
  • kein -- enthalten
  • zum Verzeichnisnamen passen, in dem SKILL.md liegt

Entsprechender Regex:

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

Follow length rules

description muss 1-1024 Zeichen lang sein. Formuliere sie so konkret, dass Agenten den Skill eindeutig auswaehlen koennen.

Use an example

Erstelle .opencode/skills/git-release/SKILL.md zum Beispiel so:

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

Recognize tool description

OpenCode listet verfuegbare Skills in der Beschreibung des skill-Tools. Jeder Eintrag enthaelt Namen und Beschreibung:

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

Der Agent laedt einen Skill per Tool-Aufruf:

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

Configure permissions

Steuere in opencode.json per Muster, auf welche Skills Agenten zugreifen duerfen:

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}
BerechtigungVerhalten
allowSkill wird sofort geladen
denySkill ist fuer Agenten versteckt
askVor dem Laden wird nach Freigabe gefragt

Muster unterstuetzen Wildcards: internal-* passt z. B. auf internal-docs oder internal-tools.

Override per agent

Du kannst einzelnen Agenten andere Berechtigungen als die globalen Defaults geben.

Fuer benutzerdefinierte Agenten (im Frontmatter):

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

Fuer eingebaute Agenten (in opencode.json):

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

Disable the skill tool

Deaktiviere Skills komplett fuer Agenten, die sie nicht nutzen sollen:

Fuer benutzerdefinierte Agenten:

---
tools:
  skill: false
---

Fuer eingebaute Agenten:

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

Wenn deaktiviert, wird der Abschnitt <available_skills> komplett weggelassen.

Troubleshoot loading

Wenn ein Skill nicht auftaucht:

  1. Pruefe, ob SKILL.md exakt in Grossbuchstaben geschrieben ist
  2. Pruefe, ob Frontmatter name und description enthaelt
  3. Stelle sicher, dass Skill-Namen ueber alle Orte hinweg eindeutig sind
  4. Pruefe Berechtigungen - Skills mit deny sind fuer Agenten unsichtbar