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
|
---
title: Agenten-Skills
description: "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.
---
## Dateien platzieren
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`
---
## Discovery verstehen
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`.
---
## Frontmatter schreiben
Jede `SKILL.md` muss mit YAML-Frontmatter beginnen.
Nur diese Felder werden ausgewertet:
- `name` (erforderlich)
- `description` (erforderlich)
- `license` (optional)
- `compatibility` (optional)
- `metadata` (optional, String-zu-String-Map)
Unbekannte Frontmatter-Felder werden ignoriert.
---
## Namen validieren
`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:
```text
^[a-z0-9]+(-[a-z0-9]+)*$
```
---
## Längenregeln beachten
`description` muss 1-1024 Zeichen lang sein.
Formuliere sie so konkret, dass Agenten den Skill eindeutig auswaehlen koennen.
---
## Beispiel verwenden
Erstelle `.opencode/skills/git-release/SKILL.md` zum Beispiel so:
```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.
```
---
## Tool-Beschreibung erkennen
OpenCode listet verfuegbare Skills in der Beschreibung des `skill`-Tools.
Jeder Eintrag enthaelt Namen und Beschreibung:
```xml
<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" })
```
---
## Berechtigungen konfigurieren
Steuere in `opencode.json` per Muster, auf welche Skills Agenten zugreifen duerfen:
```json
{
"permission": {
"skill": {
"*": "allow",
"pr-review": "allow",
"internal-*": "deny",
"experimental-*": "ask"
}
}
}
```
| Berechtigung | Verhalten |
| ------------ | ---------------------------------------- |
| `allow` | Skill wird sofort geladen |
| `deny` | Skill ist fuer Agenten versteckt |
| `ask` | Vor dem Laden wird nach Freigabe gefragt |
Muster unterstuetzen Wildcards: `internal-*` passt z. B. auf `internal-docs` oder `internal-tools`.
---
## Pro Agent überschreiben
Du kannst einzelnen Agenten andere Berechtigungen als die globalen Defaults geben.
**Fuer benutzerdefinierte Agenten** (im Frontmatter):
```yaml
---
permission:
skill:
"documents-*": "allow"
---
```
**Fuer eingebaute Agenten** (in `opencode.json`):
```json
{
"agent": {
"plan": {
"permission": {
"skill": {
"internal-*": "allow"
}
}
}
}
}
```
---
## Skill-Tool deaktivieren
Deaktiviere Skills komplett fuer Agenten, die sie nicht nutzen sollen:
**Fuer benutzerdefinierte Agenten**:
```yaml
---
tools:
skill: false
---
```
**Fuer eingebaute Agenten**:
```json
{
"agent": {
"plan": {
"tools": {
"skill": false
}
}
}
}
```
Wenn deaktiviert, wird der Abschnitt `<available_skills>` komplett weggelassen.
---
## Fehlerbehebung beim Laden
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
|
