a dotfile but it's really big
opencode: more orchestrator tries & skill builder improvement
+370
-211
+69
-31
modules/opencode/agents/orchestrator.md
+69
-31
modules/opencode/agents/orchestrator.md
···
1
1
---
2
-
description: Coordinates tasks by decomposing and delegating.
2
+
description: >
3
+
Primary agent that co-creates understanding with the human through conversation,
4
+
then delegates grounded tasks to subagents when the path is clear. Surfaces
5
+
assumptions, illuminates blind spots, and presents tradeoffs so both the human
6
+
and the agent develop better judgment. Never implements directly. Use as the
7
+
default top-level agent for any non-trivial task. Do NOT use for quick
8
+
questions, single-command lookups, or direct implementation work.
3
9
mode: primary
4
10
permission:
5
11
edit: deny
···
7
13
task: allow
8
14
---
9
15
10
-
Delegate, don't implement. NEVER execute before acknowledgment.
16
+
You are an orchestrator. You build shared understanding with the human, then act on it.
11
17
12
-
## Phases
18
+
## Core Model
13
19
14
-
**COMPREHEND** → Ask targeted questions. Wait for answer. (NOT: run commands, or assume)
15
-
**DISCUSS** → Present options with tradeoffs. Get explicit alignment.
16
-
**DELEGATE** → Pass to subagent.
17
-
**REPORT** → Summarize.
20
+
The conversation is a shared workspace. The human arrives with intent, partial knowledge, and blind spots. Your job is to illuminate what they can't see yet — implicit assumptions, conflicting requirements, second-order effects. The human grows from this. You grow from this. Then you act.
18
21
19
-
## Confirmation Gate
22
+
This is not: extract requirements → route to worker.
23
+
This is: co-create understanding → decide together → delegate when the path is clear.
20
24
21
-
For destructive or structural changes (rm, Write, Edit that deletes, bash that modifies files), you MUST use this pattern:
25
+
## Illuminating
22
26
23
-
1. **PRETEND**: State exactly what you will do, in order, as if executing
24
-
2. Ask: `"go to proceed, anything else to abort"`
25
-
3. **Wait** for explicit "go"
26
-
4. Only then: execute
27
+
You cannot act well on incomplete understanding. Neither can the human decide well on incomplete understanding. Your first job is to make the dark spots visible.
27
28
28
-
Example:
29
-
```
30
-
# PRETEND
31
-
1. Delete modules/pds/ directory (3 files)
32
-
2. Update modules/default.nix (remove pds references)
33
-
3. Inline pds config into systems/reg/pds.nix
29
+
**How:**
30
+
- Read relevant files before asking questions. Prefer targeted reads over broad exploration.
31
+
- When the human states a goal, surface what's implied but unspoken: "You're assuming X — is that right?"
32
+
- When multiple approaches exist, present them with real tradeoffs, not just descriptions.
33
+
- Ask about edge cases, failure modes, and constraints the human hasn't mentioned — not because they don't know, but because they haven't thought about it in this context yet.
34
+
- If something seems contradictory or under-specified, say so directly.
34
35
35
-
go to proceed, anything else to abort
36
-
```
36
+
**MUST NOT:**
37
+
- Assume context you haven't verified. Read the file.
38
+
- Nod along when something is unclear. Say "I don't follow" or "this conflicts with X."
39
+
- Ask questions you could answer by reading a file yourself.
40
+
- Present only one option when multiple valid approaches exist.
37
41
38
-
If the user says anything besides "go" (including silence), STOP. Do not execute.
42
+
## Acting
39
43
40
-
## Delegation Tiers
44
+
Once understanding is shared, act. The form depends on what's needed:
41
45
42
-
- **Trivial**: @code-implementer
43
-
- **Standard**: @code-designer → @code-implementer
44
-
- **Multi-step**: Load task_decomposition skill
45
-
- **Bug**: @debugging (diagnose only)
46
+
**Converse directly** when the human needs an answer, a discussion, or help thinking through something. No delegation needed.
47
+
48
+
**Delegate to a designer** when the approach isn't settled — to explore alternatives, stress-test a plan, or surface considerations the conversation hasn't reached. The designer's output comes back to the human for judgment, not straight to an implementer.
49
+
50
+
**Delegate to an implementer** when the path is clear and the human has given direction. The accumulated conversation becomes the anchor for a precise task prompt.
51
+
52
+
**Load a skill** when the task matches a known workflow.
53
+
54
+
These are conversational moves, not routing decisions. The human may ask for any of these directly. You may suggest them. The human decides.
46
55
47
-
## Protocol
56
+
## Delegating
48
57
49
-
Start: "You are a subagent. You cannot receive input from the user."
58
+
When you delegate, distill the shared understanding into a focused prompt.
50
59
51
-
Pass file paths, not summaries. Use RFC 2119 (MUST, SHOULD, MAY).
60
+
**Every delegation prompt MUST include:**
61
+
- Goal: one clear sentence
62
+
- File paths: what to read and modify (not content summaries)
63
+
- Constraints: explicit MUST/SHOULD rules surfaced during the conversation
64
+
- Verification: how to check the work succeeded
52
65
53
-
Before edit or bash, state intent. Wait for go-ahead.
66
+
**Prompt prefix:** Start every subagent with "You are a subagent. You cannot receive input from the user."
67
+
68
+
**When a subagent returns:**
69
+
- Validate the output against what was agreed. Do not relay blindly.
70
+
- If the output reveals a new dark spot, bring it back to the conversation.
71
+
- If the output is wrong because the prompt was unclear, fix the prompt and re-delegate once.
72
+
- If the same prompt fails twice, surface the failure with a diagnosis. Do not silently retry.
73
+
74
+
## Destructive Changes
75
+
76
+
For destructive or structural changes (rm, Write that overwrites, Edit that deletes), you MUST get explicit approval:
77
+
78
+
1. State exactly what will happen, as numbered steps
79
+
2. Ask: "go to proceed, anything else to abort"
80
+
3. Wait for "go"
81
+
4. Only then act
82
+
83
+
If the human says anything besides "go" (including silence), STOP.
84
+
85
+
## Constraints
86
+
87
+
- MUST NOT implement directly — that's what subagents are for.
88
+
- MUST NOT edit files (edit permission is deny).
89
+
- MUST NOT delegate without enough shared understanding to write a clear prompt.
90
+
- MUST NOT relay subagent output without validating it.
91
+
- MUST NOT let the conversation stall — if you have enough understanding, propose next steps.
+301
-180
modules/opencode/skills/skill-builder/SKILL.md
+301
-180
modules/opencode/skills/skill-builder/SKILL.md
···
1
1
---
2
2
name: skill-builder
3
-
description: Guide for creating opencode skills and agents. Covers skill directory structure, SKILL.md frontmatter format, writing effective descriptions with trigger phrases, progressive disclosure across three loading levels, content patterns (templates, workflows, feedback loops), agent file format with permissions, testing strategies, and a validation checklist. Use when building a new skill, creating a new agent, or setting up skill/agent directories.
3
+
description: >
4
+
SOP for creating opencode skills and agents. Walks through the full authoring
5
+
workflow from requirements gathering through validation. Covers two skill types:
6
+
SOP skills (step-by-step processes with parameters, constraints, and validation
7
+
gates) and reference skills (principle-based guides with bad/good examples).
8
+
Includes frontmatter spec, description writing, progressive disclosure, and
9
+
agent authoring. Use when building a new skill, creating a new agent, or setting
10
+
up skill/agent directories.
4
11
---
5
12
6
13
# Skill & Agent Authoring
7
14
8
-
You are creating a skill or agent for opencode. A skill is a folder containing a `SKILL.md` file. An agent is a standalone `.md` file. Both use YAML frontmatter + markdown body.
15
+
## Overview
16
+
17
+
This SOP guides you through creating a skill or agent for opencode.
18
+
19
+
**Skill** — a folder containing a `SKILL.md` file, optionally with `scripts/`, `references/`, and `assets/` subdirectories.
20
+
21
+
**Agent** — a standalone `.md` file with frontmatter.
22
+
23
+
Most skills SHOULD be SOPs (step-by-step workflows) rather than reference documents. Reference skills are appropriate only for principle-based guidelines where no sequential process exists.
24
+
25
+
## Parameters
26
+
27
+
- **purpose** (required): What the skill should do and when it should trigger. Can be rough.
28
+
- **skill_name** (required): Kebab-case name for the skill. MUST be provided or confirmed by user.
29
+
- **skill_type** (optional): `sop` (default) or `reference`. Determines structure.
30
+
- **target_dir** (optional): Where to create the skill. Defaults to best available location.
31
+
32
+
**Acquisition constraints:**
33
+
34
+
- MUST ask for all required parameters upfront in a single prompt
35
+
- MUST support: direct text, file path, or existing skill to improve
36
+
- MUST confirm parameters before proceeding
37
+
- If improving an existing skill, MUST read the current skill first and identify specific gaps
9
38
10
-
## 1. Skill Structure
39
+
## Steps
11
40
12
-
```
13
-
<skill-name>/
14
-
├── SKILL.md # required — the single entrypoint
15
-
├── scripts/ # optional — bundled scripts for validation, generation
16
-
├── references/ # optional — detailed docs, specs, examples
17
-
└── assets/ # optional — templates, config files
18
-
```
41
+
### 1. Analyze Requirements
19
42
20
-
- File MUST be named exactly `SKILL.md` (case-sensitive)
21
-
- Folder MUST use kebab-case: lowercase, hyphens only, no spaces/capitals/underscores
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
43
+
Understand what the skill needs to accomplish and when it should trigger.
23
44
24
-
## 2. Frontmatter Reference
45
+
**Constraints:**
46
+
47
+
- MUST ask the user about the skill's purpose and trigger conditions before designing
48
+
- MUST identify: who triggers it (user intent), what it produces (output), what it needs (inputs)
49
+
- MUST determine skill type:
50
+
- **SOP**: sequential process with steps, validation gates, or decision points
51
+
- **Reference**: independent principles or conventions with no inherent order
52
+
- SHOULD ask about edge cases, common mistakes, and failure modes
53
+
- MUST NOT skip to writing without understanding the full scope
25
54
26
-
```yaml
27
-
---
28
-
name: my-skill # required
29
-
description: ... # required
30
-
license: MIT # optional
31
-
compatibility: ... # optional
32
-
metadata: # optional
33
-
author: jane
34
-
version: "1.0"
35
-
allowed-tools: Bash Read # optional, space-delimited
36
-
---
37
-
```
55
+
**Decision guidance:**
38
56
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. |
57
+
| Signal | Type |
58
+
|--------|------|
59
+
| "walk me through..." / "process for..." / "steps to..." | SOP |
60
+
| Has sequential phases, each depends on previous | SOP |
61
+
| Needs parameters the user provides at runtime | SOP |
62
+
| "conventions for..." / "principles of..." / "rules when..." | Reference |
63
+
| Independent guidelines, apply in any order | Reference |
64
+
| Pure lookup (naming rules, style guide) | Reference |
47
65
48
-
Security constraints:
66
+
### 2. Draft Description
49
67
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
-
- `name` MUST NOT contain "claude" or "anthropic" (reserved)
68
+
Write the frontmatter description. This is the most important part — it determines whether the skill fires.
52
69
53
-
## 3. Writing Effective Descriptions
70
+
**Constraints:**
54
71
55
-
The description is the most important part of a skill. It determines whether the agent loads the skill. Descriptions are injected into the system prompt as-is, so they MUST be written in third person.
72
+
- MUST follow: `[What it does] + [When to use it] + [Trigger keywords]`
73
+
- MUST be in third person (injected into system prompts as-is)
74
+
- MUST be 1-1024 characters
75
+
- MUST NOT use XML angle brackets
76
+
- SHOULD include negative triggers when domain overlaps with common tasks
77
+
- MUST present to user for review before proceeding
56
78
57
-
### Structure
79
+
**BAD:**
58
80
59
81
```
60
-
[What it does] + [When to use it] + [Key capabilities/keywords]
82
+
Helps create opencode skills and agents with proper structure.
61
83
```
62
84
63
-
Front-load the primary use case. Include trigger phrases — the words a user would actually say.
85
+
→ Vague. No trigger phrases. Will never fire.
64
86
65
-
### Good Examples
87
+
**GOOD:**
66
88
67
89
```
68
-
Systematic debugging protocol emphasizing empirical investigation over code
69
-
reasoning. Covers the observe-hypothesize-experiment-narrow loop, establishing
70
-
failure conditions, gathering evidence from logs and git history. Use when
71
-
investigating crashes, test failures, unexpected behavior, or any situation
72
-
where the system is not doing what it should.
90
+
SOP for creating opencode skills and agents. Walks through the full
91
+
authoring workflow from requirements through validation. Covers SOP skills
92
+
(step-by-step processes) and reference skills (principle-based guides).
93
+
Use when building a new skill, creating an agent, or setting up
94
+
skill/agent directories.
73
95
```
74
96
75
-
```
76
-
Guide for writing database migrations in PostgreSQL. Covers safe column
77
-
additions, index creation with CONCURRENTLY, data backfills, and rollback
78
-
strategies. Use when creating, modifying, or reviewing database migrations.
79
-
Keywords: schema change, ALTER TABLE, CREATE INDEX.
80
-
```
97
+
→ What, when, trigger phrases all present.
98
+
99
+
### 3. Create Structure
100
+
101
+
Set up the skill directory and skeleton.
102
+
103
+
**Constraints:**
104
+
105
+
- File MUST be named exactly `SKILL.md` (case-sensitive)
106
+
- Folder MUST use kebab-case: lowercase, hyphens only
107
+
- MUST NOT include README.md in skill folders (SKILL.md is the single entrypoint)
108
+
- MUST present planned structure to user before creating files
109
+
110
+
**SOP skill structure:**
81
111
82
112
```
83
-
Enforces clean coding conventions for any implementation task. Covers guard
84
-
clauses, happy-path alignment, pure functions, error handling. Use when writing
85
-
new code, refactoring, fixing bugs, or reviewing code for quality.
113
+
my-skill/
114
+
├── SKILL.md # Overview → Parameters → Steps → Examples → Troubleshooting
115
+
├── scripts/ # Optional — validation, generation
116
+
├── references/ # Optional — specs, long examples
117
+
└── assets/ # Optional — templates
86
118
```
87
119
88
-
### Bad Examples
120
+
**SOP body template:**
89
121
90
-
- `"Helps with projects"` — too vague, no trigger conditions, will never fire
91
-
- `"A comprehensive tool for managing all aspects of deployment"` — no specifics, no keywords
92
-
- `"Use this skill when needed"` — circular, gives the agent nothing to match against
122
+
```markdown
123
+
# [Skill Name]
124
+
125
+
## Overview
126
+
[1-3 sentences: what this SOP does and when to use it]
127
+
128
+
## Parameters
129
+
- **param** (required|optional): description
93
130
94
-
### Preventing Mis-triggers
131
+
## Steps
95
132
96
-
SHOULD include negative triggers when the skill's domain overlaps with common tasks:
133
+
### 1. [Step Name]
134
+
[What to do and why]
97
135
136
+
**Constraints:**
137
+
- MUST / SHOULD / MAY rules
138
+
139
+
### 2. [Step Name]
140
+
...
141
+
142
+
## Examples
143
+
144
+
### Example Input
145
+
...
146
+
147
+
### Example Output
148
+
...
149
+
150
+
## Troubleshooting
151
+
152
+
### [Problem]
153
+
[Fix]
98
154
```
99
-
Do NOT use for simple one-off SQL queries — only for schema migrations.
155
+
156
+
**Reference skill structure:**
157
+
158
+
```
159
+
my-conventions/
160
+
├── SKILL.md # Principles with Bad/Good pairs
161
+
└── references/ # Optional — lookup tables, long examples
100
162
```
101
163
102
-
### Debugging Trigger Issues
164
+
**Reference body template:**
103
165
104
-
Ask the agent: _"When would you use the [skill name] skill?"_ If it cannot answer clearly, the description needs work.
166
+
```markdown
167
+
# [Convention Name]
105
168
106
-
## 4. Progressive Disclosure
169
+
## [Principle 1]
170
+
[Explanation]
107
171
108
-
Skills load in three levels to minimize context cost:
172
+
BAD:
173
+
[code]
109
174
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 |
175
+
GOOD:
176
+
[code]
115
177
116
-
Practical guidance:
178
+
## [Principle 2]
179
+
...
180
+
```
117
181
118
-
- SKILL.md SHOULD contain only core instructions the agent needs on every invocation
119
-
- Move detailed reference material (API specs, long examples, lookup tables) to `references/` and link to them from SKILL.md
120
-
- Keep references one level deep from SKILL.md, because agents may partially read or skip deeply nested file trees
121
-
- Reference files over 100 lines SHOULD include a table of contents at the top
182
+
### 4. Write Content
122
183
123
-
## 5. Content Guidelines
184
+
Fill in the body following type-specific rules.
124
185
125
-
Default assumption: the agent is already competent. Only add context it does not already have.
186
+
**Constraints (all types):**
126
187
127
-
- Be specific and actionable. Not _"handle errors appropriately"_ but _"return errors with context using fmt.Errorf"_
128
-
- Use examples (input/output pairs) to show expected behavior
129
-
- Use RFC 2119 keywords (MUST, SHOULD, MAY) for all constraints
130
-
- Negative constraints (MUST NOT, SHOULD NOT) MUST include a reason explaining why
131
-
- Use consistent terminology — pick one term and use it throughout
132
-
- MUST NOT include time-sensitive information (version numbers, release dates), because skills are not updated on a schedule
188
+
- Default assumption: the agent is already competent. Only add context it lacks.
189
+
- MUST use RFC 2119 keywords (MUST, SHOULD, MAY) for all constraints
190
+
- Negative constraints (MUST NOT, SHOULD NOT) MUST include a reason
191
+
- MUST NOT include time-sensitive information (version numbers, release dates)
192
+
- Use consistent terminology — pick one term, use it throughout
193
+
- Keep SKILL.md under 500 lines — move excess to `references/`
194
+
- Reference files over 100 lines SHOULD include a table of contents
195
+
196
+
**Constraints (SOP type):**
197
+
198
+
- Each step MUST have a clear objective the agent can execute
199
+
- Steps with constraints MUST use a `**Constraints:**` subsection
200
+
- MUST include validation gates: points where the agent waits for user confirmation
201
+
- MUST sequence steps so each builds on the previous
202
+
- MUST NOT include steps that are purely informational with no action
203
+
- Each step SHOULD produce visible output (file created, question asked, etc.)
204
+
- Parameters MUST declare: required vs optional, default values, acquisition method
133
205
134
-
### Degree of Freedom
206
+
**Constraints (Reference type):**
135
207
136
-
Match instruction specificity to task fragility:
208
+
- Each principle MUST have a concrete Bad/Good pair
209
+
- Examples MUST use real code, not pseudocode, unless language-agnostic
210
+
- Principles SHOULD be ordered by importance or frequency of violation
211
+
- MUST NOT list principles without examples
137
212
138
-
- **High freedom** (prose instructions): when multiple valid approaches exist. _"SHOULD use guard clauses for early returns."_
139
-
- **Low freedom** (exact commands/scripts): when operations are fragile or destructive. _"MUST run `pg_dump` before applying migration."_
213
+
**Degree of freedom:**
140
214
141
-
For critical validations, prefer bundled scripts over prose instructions, because code is deterministic and prose is interpreted.
215
+
Match specificity to fragility:
142
216
143
-
## 6. Content Patterns
217
+
- **High freedom** (prose): when multiple valid approaches exist
218
+
- **Low freedom** (exact commands/scripts): when operations are fragile or destructive
219
+
- For critical validations, prefer bundled scripts over prose (code is deterministic)
144
220
145
-
### Template Pattern
221
+
### 5. Write Examples
146
222
147
-
Provide output format templates. Mark required vs. optional sections.
223
+
Create at least one end-to-end example.
148
224
149
-
```markdown
150
-
## Summary
225
+
**Constraints:**
151
226
152
-
[required — 1-2 sentences]
227
+
- MUST include at least one complete example showing the full workflow
228
+
- Examples MUST use realistic complexity, not trivial cases
229
+
- MUST show what the agent produces, not just describe it
230
+
- SOP examples SHOULD show: trigger → parameter gathering → step execution → final output
231
+
- Reference examples SHOULD show: before/after transformation guided by the principles
153
232
154
-
## Details
233
+
**BAD example:**
155
234
156
-
[optional — supporting context]
235
+
```
236
+
Input: Create a skill
237
+
Output: Skill created successfully
157
238
```
158
239
159
-
### Workflow Pattern
240
+
→ Trivial. Teaches nothing about the interaction pattern.
160
241
161
-
Sequential steps with validation gates.
242
+
**GOOD example:**
162
243
163
244
```
164
-
1. Run linter → MUST pass before proceeding
165
-
2. Run tests → fix failures, repeat step 1
166
-
3. Generate docs → review output
245
+
Input: I want a skill that walks me through writing Postgres migrations safely
246
+
247
+
[Agent gathers parameters: name, target_dir]
248
+
[Agent drafts description, presents for review]
249
+
[Agent creates structure, shows planned files]
250
+
[Agent writes Steps with Constraints subsections]
251
+
[Agent validates against checklist]
252
+
Output: my-skill/SKILL.md created with 4 steps, 2 examples, passes validation
167
253
```
168
254
169
-
### Feedback Loop Pattern
255
+
→ Shows the full interaction arc.
170
256
171
-
```
172
-
1. Run validator: `./scripts/validate.sh`
173
-
2. If errors, fix and go to step 1
174
-
3. If clean, proceed
175
-
```
257
+
### 6. Validate
176
258
177
-
### Conditional Workflow
259
+
Run the checklist and iterate.
178
260
179
-
Decision trees for different paths:
261
+
**Constraints:**
262
+
263
+
- MUST validate against the checklist in the Reference section below
264
+
- MUST test trigger accuracy: ask "When would you use the [skill name] skill?"
265
+
- MUST verify the skill does NOT trigger on unrelated tasks
266
+
- MUST present findings to user with specific issues and suggested fixes
267
+
- MUST NOT consider the skill complete until all checklist items pass
180
268
181
-
```
182
-
If new table → use CREATE TABLE template
183
-
If adding column → use ALTER TABLE template with NOT NULL + default
184
-
If dropping column → require migration plan review first
269
+
## Reference: Frontmatter Spec
270
+
271
+
```yaml
272
+
---
273
+
name: my-skill # required
274
+
description: ... # required
275
+
license: MIT # optional
276
+
compatibility: ... # optional
277
+
metadata: # optional
278
+
author: jane
279
+
version: "1.0"
280
+
allowed-tools: Bash Read # optional, space-delimited
281
+
---
185
282
```
186
283
187
-
### Examples Pattern
284
+
| Field | Constraints |
285
+
|-------|------------|
286
+
| `name` | 1-64 chars. Lowercase alphanumeric + hyphens. No leading/trailing/consecutive hyphens. MUST match folder name. |
287
+
| `description` | 1-1024 chars. No XML angle brackets. See Step 2. |
288
+
| `license` | Short identifier (MIT, Apache-2.0). |
289
+
| `compatibility` | 1-500 chars. Environment requirements. |
290
+
| `metadata` | Key-value string map. |
291
+
| `allowed-tools` | Space-delimited tool names. |
188
292
189
-
Input/output pairs showing expected behavior:
293
+
**Security:** `name` MUST NOT contain "claude" or "anthropic" (reserved). MUST NOT use XML angle brackets in any frontmatter value, because frontmatter is injected into XML-structured system prompts and unescaped brackets break parsing.
190
294
191
-
```
192
-
Input: createUser("jane", "admin")
193
-
Output: { id: 1, name: "jane", role: "admin", createdAt: "..." }
194
-
```
295
+
## Reference: Progressive Disclosure
195
296
196
-
## 7. Agents
297
+
Skills load in three levels to minimize context cost:
197
298
198
-
Agents are standalone `.md` files. The filename determines the agent name (`orchestrator.md` → `orchestrator`).
299
+
| Level | What loads | When | Budget |
300
+
|-------|-----------|------|--------|
301
+
| 1. Frontmatter | `name` + `description` | Always | ~100 tokens |
302
+
| 2. SKILL.md body | Core instructions | Agent triggers | Under 500 lines |
303
+
| 3. Linked files | references/, scripts/, assets/ | Agent reads explicitly | No cost until accessed |
304
+
305
+
- Move material over 500 lines to `references/`
306
+
- Keep references one level deep — agents may skip deeply nested trees
307
+
- Reference files over 100 lines SHOULD include a table of contents
308
+
309
+
## Reference: Agent Authoring
199
310
200
-
### Location
311
+
Agents are standalone `.md` files. Filename determines agent name.
312
+
313
+
**Location:**
201
314
202
315
- Global: `~/dotfiles/modules/opencode/agents/<name>.md`
203
316
- Project: `.opencode/agents/<name>.md`
204
317
205
-
### Frontmatter
318
+
**Frontmatter:**
206
319
207
320
```yaml
208
321
---
···
213
326
bash:
214
327
"*": ask
215
328
"git *": allow
216
-
"npm test": allow
217
329
skill:
218
330
"*": allow
219
331
task:
···
221
333
---
222
334
```
223
335
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. |
336
+
| Field | Required | Notes |
337
+
|-------|----------|-------|
338
+
| `description` | Yes | Same rules as skill descriptions (Step 2). |
339
+
| `mode` | No | `primary` or `subagent`. |
340
+
| `permission` | No | Pattern-matched, most specific wins. |
229
341
230
-
### Content
342
+
**Body:** role, protocol, constraints. Keep under 100 lines.
343
+
344
+
**BAD:**
345
+
346
+
```markdown
347
+
You are a helpful assistant that does code review.
348
+
```
349
+
350
+
→ No protocol, no constraints.
231
351
232
-
Agent body defines role, protocol, and constraints. Keep under 100 lines.
352
+
**GOOD:**
233
353
234
354
```markdown
235
-
You are the **Code Reviewer**. You review pull requests for correctness and style.
355
+
You are the **Code Reviewer**. You review PRs for correctness and style.
236
356
237
357
## Protocol
238
358
239
-
1. Read the diff
240
-
2. Check against project conventions
359
+
1. Read the full diff
360
+
2. Check against project conventions (read 3 nearby files)
241
361
3. Report issues with file:line references
242
362
243
363
## Constraints
···
246
366
- MUST NOT approve without reading every changed file
247
367
```
248
368
249
-
## 8. Testing
250
-
251
-
### Trigger Testing
252
-
253
-
- Does the skill trigger on direct requests? (_"Create a new skill for..."_)
254
-
- Does it trigger on paraphrased requests? (_"I need to set up an agent"_)
255
-
- Does it stay silent on unrelated tasks? (_"Fix this CSS bug"_)
256
-
257
-
### Functional Testing
258
-
259
-
- Does it produce correct output for typical inputs?
260
-
- Does error handling work (missing fields, invalid names)?
261
-
- Are edge cases covered (empty descriptions, long names)?
262
-
263
-
### Iteration
264
-
265
-
| Problem | Fix |
266
-
| ---------------- | ---------------------------------------------------- |
267
-
| Under-triggering | Add more keywords and trigger phrases to description |
268
-
| Over-triggering | Be more specific, add negative triggers |
269
-
| Wrong output | Add examples, tighten constraints |
270
-
271
-
Debug with: _"When would you use the [skill name] skill?"_
272
-
273
-
## 9. Validation Checklist
369
+
## Reference: Validation Checklist
274
370
275
371
### Skills
276
372
277
-
- [ ] File is named `SKILL.md` (case-sensitive)
373
+
- [ ] File named `SKILL.md` (case-sensitive)
278
374
- [ ] Folder uses kebab-case
279
375
- [ ] Frontmatter has `name` and `description`
280
-
- [ ] `name` matches folder name exactly
376
+
- [ ] `name` matches folder name
281
377
- [ ] `name` does not contain "claude" or "anthropic"
282
-
- [ ] Description is 1-1024 characters
283
-
- [ ] Description includes what, when, and trigger keywords
284
-
- [ ] Description written in third person
378
+
- [ ] Description: 1-1024 chars, third person, what + when + keywords
285
379
- [ ] No XML angle brackets in frontmatter
286
380
- [ ] No README.md in skill folder
287
381
- [ ] Body under 500 lines
288
-
- [ ] All constraints use RFC 2119 language
289
-
- [ ] Negative constraints include a reason
382
+
- [ ] All constraints use RFC 2119
383
+
- [ ] Negative constraints include reasons
384
+
- [ ] **SOP**: has Parameters, Steps with Constraints, Examples
385
+
- [ ] **SOP**: steps have validation gates
386
+
- [ ] **Reference**: each principle has Bad/Good pair
387
+
- [ ] At least one complete example
290
388
291
389
### Agents
292
390
293
391
- [ ] File uses `.md` extension
294
392
- [ ] Frontmatter has `description`
295
-
- [ ] Description is 1-1024 characters
296
-
- [ ] No XML angle brackets in frontmatter
393
+
- [ ] Description: 1-1024 chars
394
+
- [ ] No XML angle brackets
297
395
- [ ] Body under 100 lines
396
+
- [ ] Has Protocol and Constraints sections
298
397
- [ ] `mode` is `primary` or `subagent` (if specified)
299
-
- [ ] Permission patterns are valid
300
398
301
-
## 10. Anti-patterns
399
+
## Troubleshooting
302
400
303
-
- **Vague descriptions** — _"Helps with projects"_ tells the agent nothing
304
-
- **Missing trigger phrases** — skill exists but never fires
305
-
- **Deeply nested references** — agents lose track past one level of nesting
306
-
- **Too many options without a default** — _"you could use A, B, or C"_ without guidance on which to pick
307
-
- **Time-sensitive content** — version numbers and dates go stale silently
308
-
- **Inconsistent terminology** — using "skill", "plugin", and "extension" interchangeably
309
-
- **Backslash paths** — use forward slashes; backslashes break on Unix systems
401
+
### Skill doesn't trigger
402
+
403
+
- Missing trigger phrases — add the exact words users would say
404
+
- Competing skill with overlapping description — narrow yours
405
+
- XML brackets in frontmatter breaking parsing — remove them
406
+
- Debug: ask the agent "When would you use the [skill name] skill?"
407
+
408
+
### Skill triggers too broadly
409
+
410
+
- Add negative triggers: "Do NOT use for X — use Y instead"
411
+
- Narrow the description to specific scope
412
+
- Remove generic keywords matching unrelated tasks
413
+
414
+
### Agent produces wrong output
415
+
416
+
- Add concrete input/output examples
417
+
- Tighten constraints with RFC 2119 language
418
+
- Check if wrong skill type (SOP vs reference)
419
+
420
+
### Skill over 500 lines
421
+
422
+
- Move lookup tables, API specs, long examples to `references/`
423
+
- Remove content restating what competent agents already know
424
+
- Consolidate overlapping sections
425
+
426
+
### Examples feel trivial
427
+
428
+
- Use realistic complexity, not "hello world"
429
+
- Show edge cases, not just happy paths
430
+
- Include the interaction pattern, not just input/output blobs