Skip to content

Commit 5f66d93

Browse files
committed
feat(skill): externalize customize-opencode as .claude/skills skill anomalyco#212
Task 1: 将内置 customize-opencode 技能内容(377 行)迁移至外部技能目录 .claude/skills/customize-opencode/SKILL.md,前置 YAML frontmatter(name+description),正文完整保全。技能系统据此目录发现外部技能。
1 parent 8e221d8 commit 5f66d93

1 file changed

Lines changed: 382 additions & 0 deletions

File tree

  • .claude/skills/customize-opencode
Lines changed: 382 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,382 @@
1+
---
2+
name: customize-opencode
3+
description: Use ONLY when the user is editing or creating opencode's own configuration: opencode.json, opencode.jsonc, files under .opencode/, or files under ~/.config/opencode/. Also use when creating or fixing opencode agents, subagents, skills, plugins, MCP servers, or permission rules. Do not use for the user's own application code, or for any project that is not configuring opencode itself.
4+
---
5+
6+
<!--
7+
Built-in skill. Name and description are registered in code at
8+
packages/opencode/src/skill/index.ts (see CUSTOMIZE_OPENCODE_SKILL_NAME
9+
and CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION). The body below becomes the
10+
skill's content.
11+
-->
12+
13+
# Customizing opencode
14+
15+
opencode validates its own config strictly and refuses to start when a field
16+
is wrong. The shapes below cover the common surface area, but they are a
17+
**summary, not the source of truth**.
18+
19+
## Full schema reference
20+
21+
The authoritative list of every config option — with field types, enums,
22+
defaults, and descriptions — lives in the published JSON Schema:
23+
24+
**<https://opencode.ai/config.json>**
25+
26+
If a field is not documented in this skill, or you need to confirm an exact
27+
shape before writing config, **fetch that URL and read the schema directly**
28+
rather than guessing. opencode hard-fails on invalid config, so the cost of a
29+
wrong shape is a broken startup.
30+
31+
Independently, every `opencode.json` should declare
32+
`"$schema": "https://opencode.ai/config.json"` so the user's editor catches
33+
mistakes as they type.
34+
35+
## Applying changes
36+
37+
Config is loaded once when opencode starts and is not hot-reloaded. After
38+
saving changes to `opencode.json`, an agent file, a skill, a plugin, or any
39+
other config-time file, **tell the user to quit and restart opencode** for
40+
the changes to take effect. The running session will keep using the
41+
already-loaded config until then.
42+
43+
## Where files live
44+
45+
| Scope | Path |
46+
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
47+
| Project config | `./opencode.json`, `./opencode.jsonc`, or `.opencode/opencode.json` (opencode walks up from the cwd to the worktree root) |
48+
| Global config | `~/.config/opencode/opencode.json` (NOT `~/.opencode/`) |
49+
| Project agents | `.opencode/agent/<name>.md` or `.opencode/agents/<name>.md` |
50+
| Global agents | `~/.config/opencode/agent(s)/<name>.md` |
51+
| Project skills | `.opencode/skill(s)/<name>/SKILL.md` |
52+
| Global skills | `~/.config/opencode/skill(s)/<name>/SKILL.md` |
53+
| External skills (auto-loaded) | `~/.claude/skills/<name>/SKILL.md`, `~/.agents/skills/<name>/SKILL.md` |
54+
55+
Configs from each scope are deep-merged. Project overrides global. Unknown
56+
top-level keys in `opencode.json` are rejected with `ConfigInvalidError`.
57+
58+
## opencode.json
59+
60+
Every field is optional.
61+
62+
```json
63+
{
64+
"$schema": "https://opencode.ai/config.json",
65+
"username": "string",
66+
"model": "provider/model-id",
67+
"small_model": "provider/model-id",
68+
"default_agent": "agent-name",
69+
"shell": "/bin/zsh",
70+
"logLevel": "DEBUG" | "INFO" | "WARN" | "ERROR",
71+
"share": "manual" | "auto" | "disabled",
72+
"autoupdate": true | false | "notify",
73+
"snapshot": true,
74+
"instructions": ["AGENTS.md", "docs/style.md"],
75+
76+
"skills": {
77+
"paths": [".opencode/skills", "/abs/path/to/skills"],
78+
"urls": ["https://example.com/.well-known/skills/"]
79+
},
80+
81+
"agent": {
82+
"my-agent": {
83+
"model": "anthropic/claude-sonnet-4-6",
84+
"mode": "subagent",
85+
"description": "...",
86+
"permission": { "edit": "deny" }
87+
}
88+
},
89+
90+
"command": {
91+
"deploy": { "description": "...", "prompt": "..." }
92+
},
93+
94+
"provider": {
95+
"anthropic": { "options": { "apiKey": "..." } }
96+
},
97+
"disabled_providers": ["openai"],
98+
"enabled_providers": ["anthropic"],
99+
100+
"mcp": {
101+
"playwright": {
102+
"type": "local",
103+
"command": ["npx", "-y", "@playwright/mcp"],
104+
"enabled": true,
105+
"env": {}
106+
},
107+
"remote-thing": {
108+
"type": "remote",
109+
"url": "https://...",
110+
"headers": { "Authorization": "Bearer ..." }
111+
}
112+
},
113+
114+
"plugin": [
115+
"opencode-gemini-auth",
116+
117+
"./local-plugin.ts",
118+
["opencode-bar", { "option": "value" }]
119+
],
120+
121+
"permission": {
122+
"edit": "deny",
123+
"bash": { "git *": "allow", "*": "ask" }
124+
},
125+
126+
"formatter": false,
127+
"lsp": false,
128+
129+
"experimental": {
130+
"primary_tools": ["edit"],
131+
"mcp_timeout": 30000
132+
},
133+
134+
"tool_output": { "max_lines": 200, "max_bytes": 8192 },
135+
136+
"compaction": { "auto": true, "tail_turns": 15 }
137+
}
138+
```
139+
140+
Shape notes worth being explicit about:
141+
142+
- `model` always carries a provider prefix: `"anthropic/claude-sonnet-4-6"`.
143+
- `skills` is an object with `paths` and/or `urls`, not an array.
144+
- `agent` is an object keyed by agent name, not an array.
145+
- `plugin` is an array of strings or `[name, options]` tuples, not an object.
146+
- `mcp[name].command` is an array of strings, never a single string. `type` is required.
147+
- `permission` is either a string action or an object keyed by tool name.
148+
149+
## Skills
150+
151+
opencode's skill loader scans for `**/SKILL.md` inside skill directories. The
152+
file is named `SKILL.md` exactly, and lives in its own folder named after the
153+
skill:
154+
155+
```
156+
.opencode/skills/my-skill/SKILL.md
157+
```
158+
159+
Frontmatter:
160+
161+
```markdown
162+
---
163+
name: my-skill
164+
description: One sentence covering what this skill does AND when to trigger it. Front-load the literal keywords or filenames the user is likely to say.
165+
---
166+
167+
# My Skill
168+
169+
(skill body in markdown: instructions, examples, references)
170+
```
171+
172+
- `name` is required, lowercase hyphen-separated, up to 64 chars, and matches the folder name.
173+
- `description` is effectively required: skills without one are filtered out and never surfaced to the model. Cover both _what_ the skill does and _when_ to use it. Write in third person ("Use when...", not "I help with..."). Front-load concrete trigger keywords and filenames; gate with "Use ONLY when..." if the skill should stay quiet on adjacent topics.
174+
- Optional: `license`, `compatibility`, `metadata` (string-string map).
175+
176+
Register skills from non-default locations via `skills.paths` (scanned
177+
recursively for `**/SKILL.md`) and `skills.urls` (each URL serves a list of
178+
skills).
179+
180+
## Agents
181+
182+
Two ways to define an agent. Use the file form for anything non-trivial.
183+
184+
### Inline (in `opencode.json`)
185+
186+
```json
187+
{
188+
"agent": {
189+
"my-reviewer": {
190+
"description": "Reviews PRs for style violations.",
191+
"mode": "subagent",
192+
"model": "anthropic/claude-sonnet-4-6",
193+
"permission": { "edit": "deny", "bash": "ask" },
194+
"prompt": "You are a strict PR reviewer..."
195+
}
196+
}
197+
}
198+
```
199+
200+
### File
201+
202+
```
203+
.opencode/agent/my-reviewer.md OR .opencode/agents/my-reviewer.md
204+
```
205+
206+
```markdown
207+
---
208+
description: Reviews PRs for style violations.
209+
mode: subagent
210+
model: anthropic/claude-sonnet-4-6
211+
permission:
212+
edit: deny
213+
bash: ask
214+
---
215+
216+
You are a strict PR reviewer. Focus on...
217+
```
218+
219+
The file body becomes the agent's `prompt`. Do not also put `prompt:` in the
220+
frontmatter.
221+
222+
`mode` is one of `"primary"`, `"subagent"`, `"all"`.
223+
224+
Allowed top-level frontmatter fields: `name, model, variant, description, mode,
225+
hidden, color, steps, options, permission, disable, temperature, top_p`. Any
226+
unknown field is silently routed into `options`.
227+
228+
To disable a built-in agent: `agent: { build: { disable: true } }`, or in a
229+
file, `disable: true` in frontmatter.
230+
231+
`default_agent` must point to a non-hidden, primary-mode agent.
232+
233+
### Built-in agents
234+
235+
opencode ships with `build`, `plan`, `general`, `explore`, plus optionally
236+
`scout` (gated on `OPENCODE_EXPERIMENTAL_SCOUT`). Hidden internal agents:
237+
`compaction`, `title`, `summary`. To override a built-in's fields, define the
238+
same key in `agent: { <name>: { ... } }`.
239+
240+
## Plugins
241+
242+
`plugin:` is an array. Each entry is one of:
243+
244+
```json
245+
"plugin": [
246+
"opencode-gemini-auth", // npm spec, latest
247+
"[email protected]", // npm spec, pinned
248+
"./local-plugin.ts", // file path, relative to the declaring config
249+
"file:///abs/path/plugin.js", // file URL
250+
["opencode-bar", { "key": "val" }] // tuple form with options
251+
]
252+
```
253+
254+
Auto-discovered plugins (no config entry needed): any `*.ts` or `*.js` file in
255+
`.opencode/plugin/` or `.opencode/plugins/`.
256+
257+
A plugin module exports `default` (or any named export) of type
258+
`Plugin = (input: PluginInput, options?) => Promise<Hooks>`. The export is a
259+
function, not a plain object literal, and the function returns an object
260+
(return `{}` if there is nothing to register).
261+
262+
```ts
263+
import type { Plugin } from "@opencode-ai/plugin"
264+
265+
export default (async ({ client, project, directory, $ }) => {
266+
return {
267+
config: (cfg) => {
268+
// cfg is the live merged config; mutate fields here.
269+
},
270+
"tool.execute.before": async (input, output) => {
271+
// mutate output.args before the tool runs
272+
},
273+
}
274+
}) satisfies Plugin
275+
```
276+
277+
Hook surface (mutate `output` in place; return `void`):
278+
279+
- `event(input)`: every bus event
280+
- `config(cfg)`: once on init with the merged config
281+
- `chat.message`, `chat.params`, `chat.headers`
282+
- `tool.execute.before`, `tool.execute.after`
283+
- `tool.definition`
284+
- `command.execute.before`
285+
- `shell.env`
286+
- `permission.ask`
287+
- `experimental.chat.messages.transform`, `experimental.chat.system.transform`,
288+
`experimental.session.compacting`, `experimental.compaction.autocontinue`,
289+
`experimental.text.complete`
290+
291+
Special object-shaped (not callbacks): `tool: { my_tool: { ... } }`,
292+
`auth: { ... }`, `provider: { ... }`.
293+
294+
## MCP servers
295+
296+
`mcp:` is an object keyed by server name. Each server is discriminated by
297+
`type`:
298+
299+
```json
300+
{
301+
"mcp": {
302+
"playwright": {
303+
"type": "local",
304+
"command": ["npx", "-y", "@playwright/mcp"],
305+
"enabled": true,
306+
"env": { "BROWSER": "chromium" }
307+
},
308+
"github": {
309+
"type": "remote",
310+
"url": "https://...",
311+
"enabled": true,
312+
"headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
313+
},
314+
"old-server": { "enabled": false }
315+
}
316+
}
317+
```
318+
319+
`command` is an array of strings. `type` is required. Use `enabled: false` to
320+
disable a server inherited from a parent config.
321+
322+
## Permissions
323+
324+
```json
325+
"permission": {
326+
"edit": "deny",
327+
"bash": { "git *": "allow", "rm *": "deny", "*": "ask" },
328+
"external_directory": { "~/secrets/**": "deny", "*": "allow" }
329+
}
330+
```
331+
332+
Actions: `"allow"`, `"ask"`, `"deny"`.
333+
334+
Per-tool value forms: `"allow"` shorthand (treated as `{"*": "allow"}`), or an
335+
object `{ pattern: action }`. Within an object, **insertion order matters**.
336+
opencode evaluates the LAST matching rule, so put broad rules first and narrow
337+
rules last.
338+
339+
`permission: "allow"` (a string at the top level) is shorthand for "allow
340+
everything" and is rarely what the user wants.
341+
342+
Known permission keys: `read, edit, glob, grep, list, bash, task,
343+
external_directory, todowrite, question, webfetch, websearch, repo_clone,
344+
repo_overview, lsp, doom_loop, skill`. Some of these (`todowrite,
345+
question, webfetch, websearch, doom_loop`) only accept a flat
346+
action, not a per-pattern object.
347+
348+
`external_directory` patterns are filesystem paths (use `~/`, absolute paths,
349+
or globs like `~/projects/**`).
350+
351+
Per-agent `permission:` overrides top-level `permission:`. Plan Mode lives on
352+
the `plan` agent's permission ruleset (`edit: deny *`).
353+
354+
## Escape hatches
355+
356+
When a user's config is broken and opencode won't start, these env vars help:
357+
358+
- `OPENCODE_DISABLE_PROJECT_CONFIG=1`: skip the project's local `opencode.json`
359+
and start from globals only. Run from the project directory, opencode loads,
360+
the user edits the broken file, then they restart without the flag.
361+
- `OPENCODE_CONFIG=/path/to/file.json`: load an additional explicit config.
362+
- `OPENCODE_CONFIG_CONTENT='{"$schema":"https://opencode.ai/config.json"}'`:
363+
inject inline JSON as a final local-scope merge.
364+
- `OPENCODE_DISABLE_DEFAULT_PLUGINS=1`: skip default plugins.
365+
- `OPENCODE_PURE=1`: skip external plugins entirely.
366+
- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`,
367+
`OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip the external skill scans under
368+
`~/.claude/` and `~/.agents/`.
369+
370+
## When proposing edits
371+
372+
- Validate against the schema before writing. If you are unsure of a field's
373+
exact shape, or the field is not covered in this skill, fetch
374+
`https://opencode.ai/config.json` and read the schema rather than guessing.
375+
- Preserve `$schema` and any existing fields the user did not ask to change.
376+
- For agent, skill, and plugin definitions, prefer creating new files in the
377+
correct location over inlining everything in `opencode.json`.
378+
- If the user's existing config is malformed, point them at the env-var escape
379+
hatches above so they can edit from inside opencode without breaking their
380+
session.
381+
- After saving any config change, remind the user to quit and restart opencode
382+
— running sessions keep using the already-loaded config.

0 commit comments

Comments
 (0)