From 6a6eb9fb9437c605ba6cbe76a057c51d0663141c Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Sat, 9 May 2026 21:39:45 -0400 Subject: [PATCH 1/4] feat(skill): ship built-in opencode-meta skill Loads automatically and gives the model the actual shape of opencode.json, agent/skill/plugin/MCP/permission definitions when it's asked to edit opencode's own config. Avoids the recurring failure mode where the model hallucinates a config shape and opencode hard-fails on startup. Override via shadowing on disk (drop a same-named SKILL.md). No env flag because skills as a category have no config-level disable today, so adding one only here would be inconsistent. --- packages/opencode/src/markdown.d.ts | 4 + packages/opencode/src/skill/index.ts | 18 + .../src/skill/prompt/opencode-meta.md | 364 ++++++++++++++++++ 3 files changed, 386 insertions(+) create mode 100644 packages/opencode/src/markdown.d.ts create mode 100644 packages/opencode/src/skill/prompt/opencode-meta.md diff --git a/packages/opencode/src/markdown.d.ts b/packages/opencode/src/markdown.d.ts new file mode 100644 index 000000000000..eb3e3b92d663 --- /dev/null +++ b/packages/opencode/src/markdown.d.ts @@ -0,0 +1,4 @@ +declare module "*.md" { + const content: string + export default content +} diff --git a/packages/opencode/src/skill/index.ts b/packages/opencode/src/skill/index.ts index 3000406ebc51..850e1965c2e7 100644 --- a/packages/opencode/src/skill/index.ts +++ b/packages/opencode/src/skill/index.ts @@ -17,6 +17,7 @@ import { ConfigMarkdown } from "@/config/markdown" import { Glob } from "@opencode-ai/core/util/glob" import * as Log from "@opencode-ai/core/util/log" import { Discovery } from "./discovery" +import OPENCODE_META_SKILL_BODY from "./prompt/opencode-meta.md" with { type: "text" } const log = Log.create({ service: "skill" }) const CLAUDE_EXTERNAL_DIR = ".claude" @@ -25,6 +26,15 @@ const EXTERNAL_SKILL_PATTERN = "skills/**/SKILL.md" const OPENCODE_SKILL_PATTERN = "{skill,skills}/**/SKILL.md" const SKILL_PATTERN = "**/SKILL.md" +// Built-in skill that ships with opencode. The model's intuition for what an +// opencode.json should look like is often wrong, and opencode hard-fails on +// invalid config, so users hit cryptic startup errors. Loading this skill +// when the model is asked to touch opencode's own config files gives it the +// actual schemas instead of guesses. +const META_SKILL_NAME = "opencode-meta" +const META_SKILL_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." + export const Info = Schema.Struct({ name: Schema.String, description: Schema.optional(Schema.String), @@ -230,6 +240,14 @@ export const layer = Layer.effect( const state = yield* InstanceState.make( Effect.fn("Skill.state")(function* () { const s: State = { skills: {}, dirs: new Set() } + // Register the built-in meta-skill BEFORE disk discovery so a + // user-disk skill with the same name can override it. + s.skills[META_SKILL_NAME] = { + name: META_SKILL_NAME, + description: META_SKILL_DESCRIPTION, + location: "", + content: OPENCODE_META_SKILL_BODY, + } yield* loadSkills(s, yield* InstanceState.get(discovered), bus) return s }), diff --git a/packages/opencode/src/skill/prompt/opencode-meta.md b/packages/opencode/src/skill/prompt/opencode-meta.md new file mode 100644 index 000000000000..4b736256cb66 --- /dev/null +++ b/packages/opencode/src/skill/prompt/opencode-meta.md @@ -0,0 +1,364 @@ + + +# Editing opencode itself + +opencode validates its own config strictly. There is no graceful degradation: a +wrong field name or shape and opencode refuses to start. Use the shapes +documented here as written. If you are not sure about a field, fetch +`https://opencode.ai/config.json` instead of guessing. + +The JSON Schema URL is `https://opencode.ai/config.json`. Every `opencode.json` +should declare `"$schema": "https://opencode.ai/config.json"` so the user's +editor catches mistakes as they type. + +## Where things live + +- **Project config**: `./opencode.json` or `./opencode.jsonc` at the project + root, or inside `.opencode/opencode.json`. opencode walks up from the current + directory to the worktree root looking for these. +- **Global config**: `~/.config/opencode/opencode.json` (NOT `~/.opencode/`). +- **Project agents**: `.opencode/agent/.md` or `.opencode/agents/.md`. +- **Global agents**: `~/.config/opencode/agent(s)/.md`. +- **Project skills**: `.opencode/skill//SKILL.md` or `.opencode/skills//SKILL.md`. +- **Global skills**: `~/.config/opencode/skill(s)//SKILL.md`. +- **External skills** (auto-loaded): `~/.claude/skills//SKILL.md` and `~/.agents/skills//SKILL.md`. + +Configs from each scope are deep-merged. Project overrides global. Unknown +top-level keys in `opencode.json` are rejected with `ConfigInvalidError`. + +## opencode.json: top-level shape + +Every field is optional. The shapes below are the only accepted shapes: + +```json +{ + "$schema": "https://opencode.ai/config.json", + "username": "string", + "model": "provider/model-id", + "small_model": "provider/model-id", + "default_agent": "agent-name", + "shell": "/bin/zsh", + "logLevel": "DEBUG" | "INFO" | "WARN" | "ERROR", + "share": "manual" | "auto" | "disabled", + "autoupdate": true | false | "notify", + "snapshot": true, + "instructions": ["AGENTS.md", "docs/style.md"], + + "skills": { + "paths": [".opencode/skills", "/abs/path/to/skills"], + "urls": ["https://example.com/.well-known/skills/"] + }, + + "agent": { + "my-agent": { "model": "anthropic/claude-sonnet-4-6", "mode": "subagent", "description": "...", "permission": { "edit": "deny" } } + }, + + "mode": { /* deprecated alias for `agent`; prefer `agent` */ }, + + "command": { + "deploy": { "description": "...", "prompt": "..." } + }, + + "provider": { + "anthropic": { "options": { "apiKey": "..." } } + }, + "disabled_providers": ["openai"], + "enabled_providers": ["anthropic"], + + "mcp": { + "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp"], "enabled": true, "env": {} }, + "remote-thing": { "type": "remote", "url": "https://...", "headers": { "Authorization": "Bearer ..." } } + }, + + "plugin": [ + "opencode-gemini-auth", + "opencode-foo@1.2.3", + "./local-plugin.ts", + ["opencode-bar", { "option": "value" }] + ], + + "permission": { + "edit": "deny", + "bash": { "git *": "allow", "*": "ask" } + }, + + "formatter": false, + "lsp": false, + + "experimental": { + "primary_tools": ["edit"], + "mcp_timeout": 30000 + }, + + "tool_output": { "max_lines": 200, "max_bytes": 8192 }, + + "compaction": { "auto": true, "tail_turns": 15 } +} +``` + +### Common shape mistakes (these all reject hard) + +| Wrong | Right | +|---|---| +| `"skills": [{ "name": "...", "path": "..." }]` | `"skills": { "paths": ["..."] }` | +| `"plugin": { "foo": "bar" }` | `"plugin": ["foo"]` | +| `"agent": [ { "name": "x", ... } ]` | `"agent": { "x": { ... } }` | +| `"mcp": { "x": { "command": "npx ..." } }` (missing type, command as string) | `"mcp": { "x": { "type": "local", "command": ["npx", "..."] } }` | +| `"permission": ["edit", "bash"]` | `"permission": { "edit": "allow", "bash": "ask" }` or `"permission": "allow"` | +| `"model": "claude-sonnet-4-6"` (missing provider prefix) | `"model": "anthropic/claude-sonnet-4-6"` | + +## Skills (`SKILL.md`) + +opencode's skill loader scans for `**/SKILL.md` in skill directories. The file +must be named `SKILL.md` exactly, and live in its own folder named after the +skill. + +``` +.opencode/skills/my-skill/SKILL.md loads +.opencode/skills/my-skill.md ignored (flat file, not a folder) +.opencode/skills/my-skill/skill.md ignored (wrong case) +``` + +`SKILL.md` must start with YAML frontmatter: + +```markdown +--- +name: my-skill +description: One sentence describing what this skill does AND when to trigger it. Front-load the literal keywords or filenames the user will say. +--- + +# My Skill + +(skill body in markdown: instructions, examples, references) +``` + +Frontmatter rules: +- `name` (required): lowercase, hyphen-separated, up to 64 chars, must match the folder name. +- `description` (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 not fire on adjacent topics. +- Optional: `license`, `compatibility`, `metadata` (string-string map). + +### Registering skills from a non-default location + +```json +{ + "skills": { + "paths": [".opencode/skills", "shared-skills"], + "urls": ["https://example.com/.well-known/skills/"] + } +} +``` + +Each path is scanned recursively for `**/SKILL.md`. Each URL must serve a list +of skills. + +## Agents + +Two ways to define an agent. Use the file form for anything non-trivial. + +### Inline (in `opencode.json`) + +```json +{ + "agent": { + "my-reviewer": { + "description": "Reviews PRs for style violations.", + "mode": "subagent", + "model": "anthropic/claude-sonnet-4-6", + "permission": { "edit": "deny", "bash": "ask" }, + "prompt": "You are a strict PR reviewer..." + } + } +} +``` + +### File (preferred) + +``` +.opencode/agent/my-reviewer.md OR .opencode/agents/my-reviewer.md +``` + +```markdown +--- +description: Reviews PRs for style violations. +mode: subagent +model: anthropic/claude-sonnet-4-6 +permission: + edit: deny + bash: ask +--- + +You are a strict PR reviewer. Focus on... +(file body becomes the agent's `prompt`. Do NOT also put `prompt:` in frontmatter.) +``` + +Allowed `mode` values: `"primary"` | `"subagent"` | `"all"`. + +Allowed top-level frontmatter fields: `name, model, variant, description, mode, +hidden, color, steps, options, permission, disable, tools, temperature, top_p`. +Any unknown field is silently routed into `options`. + +`tools: { read: true, edit: false }` is deprecated. Use `permission` instead. + +To disable a built-in agent: `agent: { build: { disable: true } }` (or in a +file, `disable: true` in frontmatter). + +`default_agent` must point to a non-hidden, primary-mode agent. + +### Built-in agents + +opencode ships with: `build`, `plan`, `general`, `explore`, plus optionally +`scout` (gated on `OPENCODE_EXPERIMENTAL_SCOUT`). Hidden internal agents: +`compaction`, `title`, `summary`. To override a built-in's fields, define the +same key in `agent: { build: { ... } }`. + +## Plugins + +`plugin:` is an array. Each entry is one of: + +```json +"plugin": [ + "opencode-gemini-auth", // npm spec, latest + "opencode-foo@1.2.3", // npm spec, pinned + "./local-plugin.ts", // file path, relative to the declaring config + "file:///abs/path/plugin.js", // file URL + ["opencode-bar", { "key": "val" }] // tuple form with options +] +``` + +Auto-discovered plugins (no config entry needed): any `*.ts` or `*.js` file +inside `.opencode/plugin/` or `.opencode/plugins/`. + +### Authoring a plugin + +A plugin module exports `default` (or any named export) of type +`Plugin = (input: PluginInput, options?) => Promise`. + +```ts +import type { Plugin } from "@opencode-ai/plugin" + +export default (async ({ client, project, directory, $ }) => { + return { + config: (cfg) => { + // cfg is the live merged config; mutate fields here. + }, + "tool.execute.before": async (input, output) => { + // mutate output.args before the tool runs + }, + } +}) satisfies Plugin +``` + +Hook surface (mutate `output` in place; return `void`): +- `event(input)`: fires for every bus event +- `config(cfg)`: once on init with the merged config +- `chat.message`, `chat.params`, `chat.headers` +- `tool.execute.before`, `tool.execute.after` +- `tool.definition` +- `command.execute.before` +- `shell.env` +- `permission.ask` +- `experimental.chat.messages.transform`, `experimental.chat.system.transform`, + `experimental.session.compacting`, `experimental.compaction.autocontinue`, + `experimental.text.complete` + +Special hook objects: `tool: { my_tool: { ... } }`, `auth: { ... }`, +`provider: { ... }` are object-shaped, not callbacks. + +A plugin must return an object. Return `{}` if there is nothing to register. Do +not export a plain object literal: the loader requires a function. + +## MCP servers + +`mcp:` is an object keyed by server name. Each server is discriminated by +`type`: + +```json +{ + "mcp": { + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp"], + "enabled": true, + "env": { "BROWSER": "chromium" } + }, + "github": { + "type": "remote", + "url": "https://...", + "enabled": true, + "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" } + }, + "old-server": { "enabled": false } + } +} +``` + +`command` MUST be an array of strings, never a single string. Missing `type` +silently fails to load. Use `enabled: false` to disable a server inherited from +a parent config. + +## Permissions + +```json +"permission": { + "edit": "deny", + "bash": { "git *": "allow", "rm *": "deny", "*": "ask" }, + "external_directory": { "~/secrets/**": "deny", "*": "allow" } +} +``` + +Actions: `"allow"`, `"ask"`, `"deny"`. + +Per-tool value forms: `"allow"` shorthand (treated as `{"*": "allow"}`), or an +object `{ pattern: action }`. Within an object, **insertion order matters**. +opencode evaluates the LAST matching rule, so put broad rules first and narrow +rules last. + +`permission: "allow"` (a string at the top level) is shorthand for "allow +everything" and is rarely what the user actually wants. + +Known permission keys: `read, edit, glob, grep, list, bash, task, +external_directory, todowrite, question, webfetch, websearch, codesearch, +repo_clone, repo_overview, lsp, doom_loop, skill`. Some of these (`todowrite, +question, webfetch, websearch, codesearch, doom_loop`) only accept a flat +action, not a per-pattern object. + +`external_directory` patterns are filesystem paths (use `~/`, absolute paths, +or globs like `~/projects/**`). + +Per-agent `permission:` overrides top-level `permission:`. Plan Mode lives on +the `plan` agent's permission ruleset (`edit: deny *`). + +## Useful escape hatches + +When a user's config is broken and opencode won't start, these env vars help: + +- `OPENCODE_DISABLE_PROJECT_CONFIG=1`: skips the project's local `opencode.json` + so opencode starts from globals only. Run from the project directory, + opencode loads, the user can edit the broken file, then they restart without + the flag. +- `OPENCODE_CONFIG=/path/to/file.json`: load an additional explicit config. +- `OPENCODE_CONFIG_CONTENT='{"$schema":"https://opencode.ai/config.json"}'`: + inject inline JSON as a final local-scope merge. +- `OPENCODE_DISABLE_DEFAULT_PLUGINS=1`: skip default plugins. +- `OPENCODE_PURE=1`: skip external plugins entirely. +- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1` and + `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip the external skill scans under + `~/.claude/` and `~/.agents/`. + +## When proposing edits to the user + +- Validate against the schema before writing. If you are unsure of a field's + exact shape, fetch `https://opencode.ai/config.json` rather than guessing. +- Preserve `$schema` and any existing fields the user did not ask to change. +- For agent, skill, and plugin definitions, prefer creating new files in the + correct location over inlining everything in `opencode.json`. +- If the user's existing config is malformed, point them at the env-var escape + hatch above so they can edit from inside opencode without breaking their + session. +- opencode hard-fails on invalid config by design. There is no graceful + degradation. A wrong shape means a startup error, so get it right the first + time. From a89867d2787888e3c5100c9962322ad6e91d2ee0 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Sat, 9 May 2026 21:45:46 -0400 Subject: [PATCH 2/4] rename to customize-opencode; positive technical writing; drop deprecated fields - Rename skill from opencode-meta to customize-opencode (better matches user intent, 'customize' is the verb users actually type). - Rewrite the body in positive form: drop the wrong/right 'common shape mistakes' table, fold the disambiguation into a short list of positive shape statements per top-level field. - Drop deprecated surfaces from the documented shapes: the deprecated 'mode' alias for 'agent', and the deprecated per-agent 'tools' field. - Tighten prose throughout. --- packages/opencode/src/skill/index.ts | 18 +- ...opencode-meta.md => customize-opencode.md} | 183 ++++++++---------- 2 files changed, 95 insertions(+), 106 deletions(-) rename packages/opencode/src/skill/prompt/{opencode-meta.md => customize-opencode.md} (55%) diff --git a/packages/opencode/src/skill/index.ts b/packages/opencode/src/skill/index.ts index 850e1965c2e7..e532efa3d823 100644 --- a/packages/opencode/src/skill/index.ts +++ b/packages/opencode/src/skill/index.ts @@ -17,7 +17,7 @@ import { ConfigMarkdown } from "@/config/markdown" import { Glob } from "@opencode-ai/core/util/glob" import * as Log from "@opencode-ai/core/util/log" import { Discovery } from "./discovery" -import OPENCODE_META_SKILL_BODY from "./prompt/opencode-meta.md" with { type: "text" } +import CUSTOMIZE_OPENCODE_SKILL_BODY from "./prompt/customize-opencode.md" with { type: "text" } const log = Log.create({ service: "skill" }) const CLAUDE_EXTERNAL_DIR = ".claude" @@ -31,8 +31,8 @@ const SKILL_PATTERN = "**/SKILL.md" // invalid config, so users hit cryptic startup errors. Loading this skill // when the model is asked to touch opencode's own config files gives it the // actual schemas instead of guesses. -const META_SKILL_NAME = "opencode-meta" -const META_SKILL_DESCRIPTION = +const CUSTOMIZE_OPENCODE_SKILL_NAME = "customize-opencode" +const CUSTOMIZE_OPENCODE_SKILL_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." export const Info = Schema.Struct({ @@ -240,13 +240,13 @@ export const layer = Layer.effect( const state = yield* InstanceState.make( Effect.fn("Skill.state")(function* () { const s: State = { skills: {}, dirs: new Set() } - // Register the built-in meta-skill BEFORE disk discovery so a - // user-disk skill with the same name can override it. - s.skills[META_SKILL_NAME] = { - name: META_SKILL_NAME, - description: META_SKILL_DESCRIPTION, + // Register the built-in skill BEFORE disk discovery so a user-disk + // skill with the same name can override it. + s.skills[CUSTOMIZE_OPENCODE_SKILL_NAME] = { + name: CUSTOMIZE_OPENCODE_SKILL_NAME, + description: CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION, location: "", - content: OPENCODE_META_SKILL_BODY, + content: CUSTOMIZE_OPENCODE_SKILL_BODY, } yield* loadSkills(s, yield* InstanceState.get(discovered), bus) return s diff --git a/packages/opencode/src/skill/prompt/opencode-meta.md b/packages/opencode/src/skill/prompt/customize-opencode.md similarity index 55% rename from packages/opencode/src/skill/prompt/opencode-meta.md rename to packages/opencode/src/skill/prompt/customize-opencode.md index 4b736256cb66..b7b4be1b9fb4 100644 --- a/packages/opencode/src/skill/prompt/opencode-meta.md +++ b/packages/opencode/src/skill/prompt/customize-opencode.md @@ -1,38 +1,36 @@ -# Editing opencode itself +# Customizing opencode -opencode validates its own config strictly. There is no graceful degradation: a -wrong field name or shape and opencode refuses to start. Use the shapes -documented here as written. If you are not sure about a field, fetch -`https://opencode.ai/config.json` instead of guessing. +opencode validates its own config strictly and refuses to start when a field +is wrong. The shapes below are the accepted shapes. When in doubt, fetch +`https://opencode.ai/config.json` (the JSON Schema) and validate against it. -The JSON Schema URL is `https://opencode.ai/config.json`. Every `opencode.json` -should declare `"$schema": "https://opencode.ai/config.json"` so the user's -editor catches mistakes as they type. +Every `opencode.json` should declare `"$schema": "https://opencode.ai/config.json"` +so the user's editor catches mistakes as they type. -## Where things live +## Where files live -- **Project config**: `./opencode.json` or `./opencode.jsonc` at the project - root, or inside `.opencode/opencode.json`. opencode walks up from the current - directory to the worktree root looking for these. -- **Global config**: `~/.config/opencode/opencode.json` (NOT `~/.opencode/`). -- **Project agents**: `.opencode/agent/.md` or `.opencode/agents/.md`. -- **Global agents**: `~/.config/opencode/agent(s)/.md`. -- **Project skills**: `.opencode/skill//SKILL.md` or `.opencode/skills//SKILL.md`. -- **Global skills**: `~/.config/opencode/skill(s)//SKILL.md`. -- **External skills** (auto-loaded): `~/.claude/skills//SKILL.md` and `~/.agents/skills//SKILL.md`. +| Scope | Path | +|---|---| +| Project config | `./opencode.json`, `./opencode.jsonc`, or `.opencode/opencode.json` (opencode walks up from the cwd to the worktree root) | +| Global config | `~/.config/opencode/opencode.json` (NOT `~/.opencode/`) | +| Project agents | `.opencode/agent/.md` or `.opencode/agents/.md` | +| Global agents | `~/.config/opencode/agent(s)/.md` | +| Project skills | `.opencode/skill(s)//SKILL.md` | +| Global skills | `~/.config/opencode/skill(s)//SKILL.md` | +| External skills (auto-loaded) | `~/.claude/skills//SKILL.md`, `~/.agents/skills//SKILL.md` | Configs from each scope are deep-merged. Project overrides global. Unknown top-level keys in `opencode.json` are rejected with `ConfigInvalidError`. -## opencode.json: top-level shape +## opencode.json -Every field is optional. The shapes below are the only accepted shapes: +Every field is optional. ```json { @@ -54,11 +52,14 @@ Every field is optional. The shapes below are the only accepted shapes: }, "agent": { - "my-agent": { "model": "anthropic/claude-sonnet-4-6", "mode": "subagent", "description": "...", "permission": { "edit": "deny" } } + "my-agent": { + "model": "anthropic/claude-sonnet-4-6", + "mode": "subagent", + "description": "...", + "permission": { "edit": "deny" } + } }, - "mode": { /* deprecated alias for `agent`; prefer `agent` */ }, - "command": { "deploy": { "description": "...", "prompt": "..." } }, @@ -70,8 +71,17 @@ Every field is optional. The shapes below are the only accepted shapes: "enabled_providers": ["anthropic"], "mcp": { - "playwright": { "type": "local", "command": ["npx", "-y", "@playwright/mcp"], "enabled": true, "env": {} }, - "remote-thing": { "type": "remote", "url": "https://...", "headers": { "Authorization": "Bearer ..." } } + "playwright": { + "type": "local", + "command": ["npx", "-y", "@playwright/mcp"], + "enabled": true, + "env": {} + }, + "remote-thing": { + "type": "remote", + "url": "https://...", + "headers": { "Authorization": "Bearer ..." } + } }, "plugin": [ @@ -100,35 +110,31 @@ Every field is optional. The shapes below are the only accepted shapes: } ``` -### Common shape mistakes (these all reject hard) +Shape notes worth being explicit about: -| Wrong | Right | -|---|---| -| `"skills": [{ "name": "...", "path": "..." }]` | `"skills": { "paths": ["..."] }` | -| `"plugin": { "foo": "bar" }` | `"plugin": ["foo"]` | -| `"agent": [ { "name": "x", ... } ]` | `"agent": { "x": { ... } }` | -| `"mcp": { "x": { "command": "npx ..." } }` (missing type, command as string) | `"mcp": { "x": { "type": "local", "command": ["npx", "..."] } }` | -| `"permission": ["edit", "bash"]` | `"permission": { "edit": "allow", "bash": "ask" }` or `"permission": "allow"` | -| `"model": "claude-sonnet-4-6"` (missing provider prefix) | `"model": "anthropic/claude-sonnet-4-6"` | +- `model` always carries a provider prefix: `"anthropic/claude-sonnet-4-6"`. +- `skills` is an object with `paths` and/or `urls`, not an array. +- `agent` is an object keyed by agent name, not an array. +- `plugin` is an array of strings or `[name, options]` tuples, not an object. +- `mcp[name].command` is an array of strings, never a single string. `type` is required. +- `permission` is either a string action or an object keyed by tool name. -## Skills (`SKILL.md`) +## Skills -opencode's skill loader scans for `**/SKILL.md` in skill directories. The file -must be named `SKILL.md` exactly, and live in its own folder named after the -skill. +opencode's skill loader scans for `**/SKILL.md` inside skill directories. The +file is named `SKILL.md` exactly, and lives in its own folder named after the +skill: ``` -.opencode/skills/my-skill/SKILL.md loads -.opencode/skills/my-skill.md ignored (flat file, not a folder) -.opencode/skills/my-skill/skill.md ignored (wrong case) +.opencode/skills/my-skill/SKILL.md ``` -`SKILL.md` must start with YAML frontmatter: +Frontmatter: ```markdown --- name: my-skill -description: One sentence describing what this skill does AND when to trigger it. Front-load the literal keywords or filenames the user will say. +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. --- # My Skill @@ -136,24 +142,13 @@ description: One sentence describing what this skill does AND when to trigger it (skill body in markdown: instructions, examples, references) ``` -Frontmatter rules: -- `name` (required): lowercase, hyphen-separated, up to 64 chars, must match the folder name. -- `description` (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 not fire on adjacent topics. +- `name` is required, lowercase hyphen-separated, up to 64 chars, and matches the folder name. +- `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. - Optional: `license`, `compatibility`, `metadata` (string-string map). -### Registering skills from a non-default location - -```json -{ - "skills": { - "paths": [".opencode/skills", "shared-skills"], - "urls": ["https://example.com/.well-known/skills/"] - } -} -``` - -Each path is scanned recursively for `**/SKILL.md`. Each URL must serve a list -of skills. +Register skills from non-default locations via `skills.paths` (scanned +recursively for `**/SKILL.md`) and `skills.urls` (each URL serves a list of +skills). ## Agents @@ -175,7 +170,7 @@ Two ways to define an agent. Use the file form for anything non-trivial. } ``` -### File (preferred) +### File ``` .opencode/agent/my-reviewer.md OR .opencode/agents/my-reviewer.md @@ -192,28 +187,28 @@ permission: --- You are a strict PR reviewer. Focus on... -(file body becomes the agent's `prompt`. Do NOT also put `prompt:` in frontmatter.) ``` -Allowed `mode` values: `"primary"` | `"subagent"` | `"all"`. +The file body becomes the agent's `prompt`. Do not also put `prompt:` in the +frontmatter. -Allowed top-level frontmatter fields: `name, model, variant, description, mode, -hidden, color, steps, options, permission, disable, tools, temperature, top_p`. -Any unknown field is silently routed into `options`. +`mode` is one of `"primary"`, `"subagent"`, `"all"`. -`tools: { read: true, edit: false }` is deprecated. Use `permission` instead. +Allowed top-level frontmatter fields: `name, model, variant, description, mode, +hidden, color, steps, options, permission, disable, temperature, top_p`. Any +unknown field is silently routed into `options`. -To disable a built-in agent: `agent: { build: { disable: true } }` (or in a -file, `disable: true` in frontmatter). +To disable a built-in agent: `agent: { build: { disable: true } }`, or in a +file, `disable: true` in frontmatter. `default_agent` must point to a non-hidden, primary-mode agent. ### Built-in agents -opencode ships with: `build`, `plan`, `general`, `explore`, plus optionally +opencode ships with `build`, `plan`, `general`, `explore`, plus optionally `scout` (gated on `OPENCODE_EXPERIMENTAL_SCOUT`). Hidden internal agents: `compaction`, `title`, `summary`. To override a built-in's fields, define the -same key in `agent: { build: { ... } }`. +same key in `agent: { : { ... } }`. ## Plugins @@ -229,13 +224,13 @@ same key in `agent: { build: { ... } }`. ] ``` -Auto-discovered plugins (no config entry needed): any `*.ts` or `*.js` file -inside `.opencode/plugin/` or `.opencode/plugins/`. - -### Authoring a plugin +Auto-discovered plugins (no config entry needed): any `*.ts` or `*.js` file in +`.opencode/plugin/` or `.opencode/plugins/`. A plugin module exports `default` (or any named export) of type -`Plugin = (input: PluginInput, options?) => Promise`. +`Plugin = (input: PluginInput, options?) => Promise`. The export is a +function, not a plain object literal, and the function returns an object +(return `{}` if there is nothing to register). ```ts import type { Plugin } from "@opencode-ai/plugin" @@ -253,7 +248,7 @@ export default (async ({ client, project, directory, $ }) => { ``` Hook surface (mutate `output` in place; return `void`): -- `event(input)`: fires for every bus event +- `event(input)`: every bus event - `config(cfg)`: once on init with the merged config - `chat.message`, `chat.params`, `chat.headers` - `tool.execute.before`, `tool.execute.after` @@ -265,11 +260,8 @@ Hook surface (mutate `output` in place; return `void`): `experimental.session.compacting`, `experimental.compaction.autocontinue`, `experimental.text.complete` -Special hook objects: `tool: { my_tool: { ... } }`, `auth: { ... }`, -`provider: { ... }` are object-shaped, not callbacks. - -A plugin must return an object. Return `{}` if there is nothing to register. Do -not export a plain object literal: the loader requires a function. +Special object-shaped (not callbacks): `tool: { my_tool: { ... } }`, +`auth: { ... }`, `provider: { ... }`. ## MCP servers @@ -296,9 +288,8 @@ not export a plain object literal: the loader requires a function. } ``` -`command` MUST be an array of strings, never a single string. Missing `type` -silently fails to load. Use `enabled: false` to disable a server inherited from -a parent config. +`command` is an array of strings. `type` is required. Use `enabled: false` to +disable a server inherited from a parent config. ## Permissions @@ -318,7 +309,7 @@ opencode evaluates the LAST matching rule, so put broad rules first and narrow rules last. `permission: "allow"` (a string at the top level) is shorthand for "allow -everything" and is rarely what the user actually wants. +everything" and is rarely what the user wants. Known permission keys: `read, edit, glob, grep, list, bash, task, external_directory, todowrite, question, webfetch, websearch, codesearch, @@ -332,24 +323,23 @@ or globs like `~/projects/**`). Per-agent `permission:` overrides top-level `permission:`. Plan Mode lives on the `plan` agent's permission ruleset (`edit: deny *`). -## Useful escape hatches +## Escape hatches When a user's config is broken and opencode won't start, these env vars help: -- `OPENCODE_DISABLE_PROJECT_CONFIG=1`: skips the project's local `opencode.json` - so opencode starts from globals only. Run from the project directory, - opencode loads, the user can edit the broken file, then they restart without - the flag. +- `OPENCODE_DISABLE_PROJECT_CONFIG=1`: skip the project's local `opencode.json` + and start from globals only. Run from the project directory, opencode loads, + the user edits the broken file, then they restart without the flag. - `OPENCODE_CONFIG=/path/to/file.json`: load an additional explicit config. - `OPENCODE_CONFIG_CONTENT='{"$schema":"https://opencode.ai/config.json"}'`: inject inline JSON as a final local-scope merge. - `OPENCODE_DISABLE_DEFAULT_PLUGINS=1`: skip default plugins. - `OPENCODE_PURE=1`: skip external plugins entirely. -- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1` and +- `OPENCODE_DISABLE_EXTERNAL_SKILLS=1`, `OPENCODE_DISABLE_CLAUDE_CODE_SKILLS=1`: skip the external skill scans under `~/.claude/` and `~/.agents/`. -## When proposing edits to the user +## When proposing edits - Validate against the schema before writing. If you are unsure of a field's exact shape, fetch `https://opencode.ai/config.json` rather than guessing. @@ -360,5 +350,4 @@ When a user's config is broken and opencode won't start, these env vars help: hatch above so they can edit from inside opencode without breaking their session. - opencode hard-fails on invalid config by design. There is no graceful - degradation. A wrong shape means a startup error, so get it right the first - time. + degradation, so get the shape right the first time. From 94bf0b12b4e166c5954c4a724df3c6cb21d83525 Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Sat, 9 May 2026 21:50:55 -0400 Subject: [PATCH 3/4] gate built-in skill behind OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL Default-on for dev/beta/local channels (mirrors the rollout pattern used by OPENCODE_EXPERIMENTAL_HTTPAPI before it graduated). Stable users opt in via the env var. Set =false to force off, =true to force on. Factor the channel-default check into an unstableDefault() helper so future experiments with the same rollout shape can reuse it. --- packages/core/src/flag/flag.ts | 11 +++++++++++ packages/opencode/src/skill/index.ts | 12 +++++++----- 2 files changed, 18 insertions(+), 5 deletions(-) diff --git a/packages/core/src/flag/flag.ts b/packages/core/src/flag/flag.ts index 175c723c5fd8..3fe765575997 100644 --- a/packages/core/src/flag/flag.ts +++ b/packages/core/src/flag/flag.ts @@ -1,4 +1,5 @@ import { Config } from "effect" +import { InstallationChannel } from "../installation/version" function truthy(key: string) { const value = process.env[key]?.toLowerCase() @@ -10,6 +11,13 @@ function falsy(key: string) { return value === "false" || value === "0" } +// Channels where new experiments default to ON (unstable / internal users). +// Stable channels (`prod`, `latest`) stay opt-in. +const UNSTABLE_CHANNELS = new Set(["dev", "beta", "local"]) +function unstableDefault(key: string) { + return truthy(key) || (!falsy(key) && UNSTABLE_CHANNELS.has(InstallationChannel)) +} + function number(key: string) { const value = process.env[key] if (!value) return undefined @@ -48,6 +56,9 @@ export const Flag = { OPENCODE_DISABLE_CLAUDE_CODE_PROMPT: OPENCODE_DISABLE_CLAUDE_CODE || truthy("OPENCODE_DISABLE_CLAUDE_CODE_PROMPT"), OPENCODE_DISABLE_CLAUDE_CODE_SKILLS, OPENCODE_DISABLE_EXTERNAL_SKILLS: truthy("OPENCODE_DISABLE_EXTERNAL_SKILLS"), + // Default-on for dev/beta/local; opt-in for stable. Set + // OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL=false to force off, =true to force on. + OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL: unstableDefault("OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL"), OPENCODE_FAKE_VCS: process.env["OPENCODE_FAKE_VCS"], OPENCODE_SERVER_PASSWORD: process.env["OPENCODE_SERVER_PASSWORD"], OPENCODE_SERVER_USERNAME: process.env["OPENCODE_SERVER_USERNAME"], diff --git a/packages/opencode/src/skill/index.ts b/packages/opencode/src/skill/index.ts index e532efa3d823..01bffdb02adb 100644 --- a/packages/opencode/src/skill/index.ts +++ b/packages/opencode/src/skill/index.ts @@ -242,11 +242,13 @@ export const layer = Layer.effect( const s: State = { skills: {}, dirs: new Set() } // Register the built-in skill BEFORE disk discovery so a user-disk // skill with the same name can override it. - s.skills[CUSTOMIZE_OPENCODE_SKILL_NAME] = { - name: CUSTOMIZE_OPENCODE_SKILL_NAME, - description: CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION, - location: "", - content: CUSTOMIZE_OPENCODE_SKILL_BODY, + if (Flag.OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL) { + s.skills[CUSTOMIZE_OPENCODE_SKILL_NAME] = { + name: CUSTOMIZE_OPENCODE_SKILL_NAME, + description: CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION, + location: "", + content: CUSTOMIZE_OPENCODE_SKILL_BODY, + } } yield* loadSkills(s, yield* InstanceState.get(discovered), bus) return s From 479e5c876276f62f763ff603039cd8e076d5f0db Mon Sep 17 00:00:00 2001 From: Kit Langton Date: Sat, 9 May 2026 21:56:09 -0400 Subject: [PATCH 4/4] test: disable built-in customize-opencode skill in test preload The skill defaults ON for the 'local' channel (where CI runs), which made disk-discovery tests off-by-one ('returns empty array when no skills exist' returned 1, 'discovers N skills' returned N+1). Force the flag off in preload so existing skill counts hold. --- packages/opencode/test/preload.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/opencode/test/preload.ts b/packages/opencode/test/preload.ts index b408f7ef11b8..1ba0554d3ee4 100644 --- a/packages/opencode/test/preload.ts +++ b/packages/opencode/test/preload.ts @@ -35,6 +35,11 @@ process.env["XDG_CONFIG_HOME"] = path.join(dir, "config") process.env["XDG_STATE_HOME"] = path.join(dir, "state") process.env["OPENCODE_MODELS_PATH"] = path.join(import.meta.dir, "tool", "fixtures", "models-api.json") process.env["OPENCODE_EXPERIMENTAL_EVENT_SYSTEM"] = "true" +// Tests assert exact skill counts from disk discovery; the built-in +// customize-opencode skill is opt-in for stable channels and on by default +// for unstable channels (including "local" where CI runs). Disable it here +// so disk-discovery tests aren't off-by-one. +process.env["OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL"] = "false" // Set test home directory to isolate tests from user's actual home directory // This prevents tests from picking up real user configs/skills from ~/.claude/skills