Skip to content

Commit bb769ba

Browse files
committed
docs(skill): add 'Applying changes' section + review polish
Config is loaded once at startup and is not hot-reloaded, but the skill never said so. Add an 'Applying changes' section so the model will tell the user to quit and restart opencode after editing config, agents, skills, or plugins. Mirror that as a final bullet in 'When proposing edits'. While reviewing the file, fix a few smaller issues: - HTML comment referenced SKILL_NAME / SKILL_DESCRIPTION; the actual constants are CUSTOMIZE_OPENCODE_SKILL_NAME and CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION. - Replace ambiguous 'or the field is not covered above' with 'in this skill' (the schema reference is at the top, not above the bullet). - Reword '$schema' paragraph from 'also' (mid-topic-shift) to 'Independently' for cleaner flow. - Tighten 'Full schema reference' intro with em-dashes.
1 parent c46999d commit bb769ba

1 file changed

Lines changed: 20 additions & 10 deletions

File tree

packages/opencode/src/skill/prompt/customize-opencode.md

Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
<!--
22
Built-in skill. Name and description are registered in code at
3-
packages/opencode/src/skill/index.ts (see SKILL_NAME and SKILL_DESCRIPTION).
4-
The body below becomes the skill's content.
3+
packages/opencode/src/skill/index.ts (see CUSTOMIZE_OPENCODE_SKILL_NAME
4+
and CUSTOMIZE_OPENCODE_SKILL_DESCRIPTION). The body below becomes the
5+
skill's content.
56
-->
67

78
# Customizing opencode
@@ -12,8 +13,8 @@ is wrong. The shapes below cover the common surface area, but they are a
1213

1314
## Full schema reference
1415

15-
The authoritative list of every config option, with exact field types, enums,
16-
defaults, and descriptions, lives in the published JSON Schema:
16+
The authoritative list of every config option — with field types, enums,
17+
defaults, and descriptions lives in the published JSON Schema:
1718

1819
**<https://opencode.ai/config.json>**
1920

@@ -22,8 +23,17 @@ shape before writing config, **fetch that URL and read the schema directly**
2223
rather than guessing. opencode hard-fails on invalid config, so the cost of a
2324
wrong shape is a broken startup.
2425

25-
Every `opencode.json` should also declare `"$schema": "https://opencode.ai/config.json"`
26-
so the user's editor catches mistakes as they type.
26+
Independently, every `opencode.json` should declare
27+
`"$schema": "https://opencode.ai/config.json"` so the user's editor catches
28+
mistakes as they type.
29+
30+
## Applying changes
31+
32+
Config is loaded once when opencode starts and is not hot-reloaded. After
33+
saving changes to `opencode.json`, an agent file, a skill, a plugin, or any
34+
other config-time file, **tell the user to quit and restart opencode** for
35+
the changes to take effect. The running session will keep using the
36+
already-loaded config until then.
2737

2838
## Where files live
2939

@@ -355,13 +365,13 @@ When a user's config is broken and opencode won't start, these env vars help:
355365
## When proposing edits
356366

357367
- Validate against the schema before writing. If you are unsure of a field's
358-
exact shape, or the field is not covered above, fetch
368+
exact shape, or the field is not covered in this skill, fetch
359369
`https://opencode.ai/config.json` and read the schema rather than guessing.
360370
- Preserve `$schema` and any existing fields the user did not ask to change.
361371
- For agent, skill, and plugin definitions, prefer creating new files in the
362372
correct location over inlining everything in `opencode.json`.
363373
- If the user's existing config is malformed, point them at the env-var escape
364-
hatch above so they can edit from inside opencode without breaking their
374+
hatches above so they can edit from inside opencode without breaking their
365375
session.
366-
- opencode hard-fails on invalid config by design. There is no graceful
367-
degradation, so get the shape right the first time.
376+
- After saving any config change, remind the user to quit and restart opencode
377+
— running sessions keep using the already-loaded config.

0 commit comments

Comments
 (0)