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

packages/opencode/src/skill/index.ts

@@ -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

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

@@ -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.