LLM/opencode
1
0
Fork 0
mirror of https://github.com/anomalyco/opencode.git synced 2026-05-13 23:52:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(skill): enable customize-opencode by default, link full schema (#26899)

Browse Source
This commit is contained in:
Kit Langton
2026-05-11 13:13:41 -04:00
committed by GitHub
parent 25b12ed754
commit df386bd651
5 changed files with 48 additions and 43 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
packages/core/src/flag/flag.ts
View File

@@ -1,5 +1,4 @@
import { Config } from "effect"
import { InstallationChannel } from "../installation/version"
function truthy(key: string) {
const value = process.env[key]?.toLowerCase()
@@ -11,13 +10,6 @@ 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
@@ -56,9 +48,6 @@ 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"],

12
packages/opencode/src/skill/index.ts
View File

@@ -242,13 +242,11 @@ 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.
if (Flag.OPENCODE_EXPERIMENTAL_CUSTOMIZE_SKILL) {
s.skills[CUSTOMIZE_OPENCODE_SKILL_NAME] = {
name: CUSTOMIZE_OPENCODE_SKILL_NAME,
description: CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION,
location: "<built-in>",
content: CUSTOMIZE_OPENCODE_SKILL_BODY,
}
s.skills[CUSTOMIZE_OPENCODE_SKILL_NAME] = {
name: CUSTOMIZE_OPENCODE_SKILL_NAME,
description: CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION,
location: "<built-in>",
content: CUSTOMIZE_OPENCODE_SKILL_BODY,
}
yield* loadSkills(s, yield* InstanceState.get(discovered), bus)
return s

43
packages/opencode/src/skill/prompt/customize-opencode.md
View File

@@ -1,17 +1,39 @@
<!--
Built-in skill. Name and description are registered in code at
packages/opencode/src/skill/index.ts (see SKILL_NAME and SKILL_DESCRIPTION).
The body below becomes the skill's content.
packages/opencode/src/skill/index.ts (see CUSTOMIZE_OPENCODE_SKILL_NAME
and CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION). The body below becomes the
skill's content.
-->
# Customizing opencode
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.
is wrong. The shapes below cover the common surface area, but they are a
**summary, not the source of truth**.
Every `opencode.json` should declare `"$schema": "https://opencode.ai/config.json"`
so the user's editor catches mistakes as they type.
## Full schema reference
The authoritative list of every config option — with field types, enums,
defaults, and descriptions — lives in the published JSON Schema:
**<https://opencode.ai/config.json>**
If a field is not documented in this skill, or you need to confirm an exact
shape before writing config, **fetch that URL and read the schema directly**
rather than guessing. opencode hard-fails on invalid config, so the cost of a
wrong shape is a broken startup.
Independently, every `opencode.json` should declare
`"$schema": "https://opencode.ai/config.json"` so the user's editor catches
mistakes as they type.
## Applying changes
Config is loaded once when opencode starts and is not hot-reloaded. After
saving changes to `opencode.json`, an agent file, a skill, a plugin, or any
other config-time file, **tell the user to quit and restart opencode** for
the changes to take effect. The running session will keep using the
already-loaded config until then.
## Where files live
@@ -343,12 +365,13 @@ When a user's config is broken and opencode won't start, these env vars help:
## 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.
exact shape, or the field is not covered in this skill, fetch
`https://opencode.ai/config.json` and read the schema 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
hatches 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, so get the shape right the first time.
- After saving any config change, remind the user to quit and restart opencode
— running sessions keep using the already-loaded config.

5
packages/opencode/test/preload.ts
View File

@@ -35,11 +35,6 @@ 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

20
packages/opencode/test/skill/skill.test.ts
View File

@@ -63,7 +63,7 @@ Instructions here.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
const item = list.find((x) => x.name === "test-skill")
expect(item).toBeDefined()
@@ -133,7 +133,7 @@ description: Second test skill.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(2)
expect(list.find((x) => x.name === "skill-one")).toBeDefined()
expect(list.find((x) => x.name === "skill-two")).toBeDefined()
@@ -157,7 +157,7 @@ Just some content without YAML frontmatter.
)
const skill = yield* Skill.Service
expect(yield* skill.all()).toEqual([])
expect((yield* skill.all()).filter((s) => s.location !== "<built-in>")).toEqual([])
}),
{ git: true },
),
@@ -182,7 +182,7 @@ Instructions here.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
const item = list.find((x) => x.name === "manual-skill")
expect(item).toBeDefined()
@@ -212,7 +212,7 @@ description: A skill in the .claude/skills directory.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
const item = list.find((x) => x.name === "claude-skill")
expect(item).toBeDefined()
@@ -235,7 +235,7 @@ description: A skill in the .claude/skills directory.
yield* Effect.promise(() => createGlobalSkill(tmp.path))
yield* Effect.gen(function* () {
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
expect(list[0].name).toBe("global-test-skill")
expect(list[0].description).toBe("A global skill from ~/.claude/skills for testing.")
@@ -251,7 +251,7 @@ description: A skill in the .claude/skills directory.
() =>
Effect.gen(function* () {
const skill = yield* Skill.Service
expect(yield* skill.all()).toEqual([])
expect((yield* skill.all()).filter((s) => s.location !== "<built-in>")).toEqual([])
}),
{ git: true },
),
@@ -275,7 +275,7 @@ description: A skill in the .agents/skills directory.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
const item = list.find((x) => x.name === "agent-skill")
expect(item).toBeDefined()
@@ -314,7 +314,7 @@ This skill is loaded from the global home directory.
yield* Effect.gen(function* () {
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(1)
expect(list[0].name).toBe("global-agent-skill")
expect(list[0].description).toBe("A global skill from ~/.agents/skills for testing.")
@@ -355,7 +355,7 @@ description: A skill in the .agents/skills directory.
)
const skill = yield* Skill.Service
const list = yield* skill.all()
const list = (yield* skill.all()).filter((s) => s.location !== "<built-in>")
expect(list.length).toBe(2)
expect(list.find((x) => x.name === "claude-skill")).toBeDefined()
expect(list.find((x) => x.name === "agent-skill")).toBeDefined()