a dotfile but it's really big
skill: don't point agents towards simlinks
+34
-30
+34
-30
modules/opencode/skills/skill-builder/SKILL.md
+34
-30
modules/opencode/skills/skill-builder/SKILL.md
···
20
20
- File MUST be named exactly `SKILL.md` (case-sensitive)
21
21
- Folder MUST use kebab-case: lowercase, hyphens only, no spaces/capitals/underscores
22
22
- MUST NOT include a README.md inside skill folders, because SKILL.md is the single entrypoint and a README creates ambiguity about which file is authoritative
23
-
- Skills live at `~/.config/opencode/skills/<name>/` (global) or `.opencode/skills/<name>/` (project-local)
24
23
25
24
## 2. Frontmatter Reference
26
25
27
26
```yaml
28
27
---
29
-
name: my-skill # required
30
-
description: ... # required
31
-
license: MIT # optional
32
-
compatibility: ... # optional
33
-
metadata: # optional
28
+
name: my-skill # required
29
+
description: ... # required
30
+
license: MIT # optional
31
+
compatibility: ... # optional
32
+
metadata: # optional
34
33
author: jane
35
34
version: "1.0"
36
-
allowed-tools: Bash Read # optional, space-delimited
35
+
allowed-tools: Bash Read # optional, space-delimited
37
36
---
38
37
```
39
38
40
-
| Field | Constraints |
41
-
|---|---|
42
-
| `name` | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. MUST match folder name. |
43
-
| `description` | 1-1024 chars. No XML angle brackets. See §3. |
44
-
| `license` | Short license identifier (e.g., MIT, Apache-2.0). |
45
-
| `compatibility` | 1-500 chars. Environment requirements (OS, runtime, tools). |
46
-
| `metadata` | Key-value string map. |
47
-
| `allowed-tools` | Space-delimited tool names pre-approved for this skill. |
39
+
| Field | Constraints |
40
+
| --------------- | -------------------------------------------------------------------------------------------------------------- |
41
+
| `name` | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. MUST match folder name. |
42
+
| `description` | 1-1024 chars. No XML angle brackets. See §3. |
43
+
| `license` | Short license identifier (e.g., MIT, Apache-2.0). |
44
+
| `compatibility` | 1-500 chars. Environment requirements (OS, runtime, tools). |
45
+
| `metadata` | Key-value string map. |
46
+
| `allowed-tools` | Space-delimited tool names pre-approved for this skill. |
48
47
49
48
Security constraints:
49
+
50
50
- MUST NOT use XML angle brackets (`<` `>`) in any frontmatter value, because frontmatter is injected into XML-structured system prompts and unescaped brackets break parsing
51
51
- `name` MUST NOT contain "claude" or "anthropic" (reserved)
52
52
···
107
107
108
108
Skills load in three levels to minimize context cost:
109
109
110
-
| Level | What loads | When | Budget |
111
-
|---|---|---|---|
112
-
| 1. Frontmatter | `name` + `description` | Always (system prompt) | ~100 tokens per skill |
113
-
| 2. SKILL.md body | Core instructions | Agent triggers the skill | Keep under 500 lines |
114
-
| 3. Linked files | references/, scripts/, assets/ | Agent reads explicitly | No cost until accessed |
110
+
| Level | What loads | When | Budget |
111
+
| ---------------- | ------------------------------ | ------------------------ | ---------------------- |
112
+
| 1. Frontmatter | `name` + `description` | Always (system prompt) | ~100 tokens per skill |
113
+
| 2. SKILL.md body | Core instructions | Agent triggers the skill | Keep under 500 lines |
114
+
| 3. Linked files | references/, scripts/, assets/ | Agent reads explicitly | No cost until accessed |
115
115
116
116
Practical guidance:
117
117
···
148
148
149
149
```markdown
150
150
## Summary
151
+
151
152
[required — 1-2 sentences]
152
153
153
154
## Details
155
+
154
156
[optional — supporting context]
155
157
```
156
158
···
197
199
198
200
### Location
199
201
200
-
- Global: `~/.config/opencode/agents/<name>.md`
202
+
- Global: `~/dotfiles/modules/opencode/agents/<name>.md`
201
203
- Project: `.opencode/agents/<name>.md`
202
204
203
205
### Frontmatter
···
219
221
---
220
222
```
221
223
222
-
| Field | Required | Notes |
223
-
|---|---|---|
224
-
| `description` | Yes | Same rules as skill descriptions (§3). |
225
-
| `mode` | No | `primary` (top-level) or `subagent` (delegated to). |
226
-
| `permission` | No | Tool permission overrides. Pattern-matched, most specific wins. |
224
+
| Field | Required | Notes |
225
+
| ------------- | -------- | --------------------------------------------------------------- |
226
+
| `description` | Yes | Same rules as skill descriptions (§3). |
227
+
| `mode` | No | `primary` (top-level) or `subagent` (delegated to). |
228
+
| `permission` | No | Tool permission overrides. Pattern-matched, most specific wins. |
227
229
228
230
### Content
229
231
···
233
235
You are the **Code Reviewer**. You review pull requests for correctness and style.
234
236
235
237
## Protocol
238
+
236
239
1. Read the diff
237
240
2. Check against project conventions
238
241
3. Report issues with file:line references
239
242
240
243
## Constraints
244
+
241
245
- MUST NOT suggest style changes that contradict existing patterns
242
246
- MUST NOT approve without reading every changed file
243
247
```
···
258
262
259
263
### Iteration
260
264
261
-
| Problem | Fix |
262
-
|---|---|
265
+
| Problem | Fix |
266
+
| ---------------- | ---------------------------------------------------- |
263
267
| Under-triggering | Add more keywords and trigger phrases to description |
264
-
| Over-triggering | Be more specific, add negative triggers |
265
-
| Wrong output | Add examples, tighten constraints |
268
+
| Over-triggering | Be more specific, add negative triggers |
269
+
| Wrong output | Add examples, tighten constraints |
266
270
267
271
Debug with: _"When would you use the [skill name] skill?"_
268
272