fix(skill): customize-opencode off by default; promote browser-execute guide to a registered skill

Eval-agent deep-dive on v0.1.6 regressed traces: the only skill registered in browser sessions was upstream's customize-opencode (opencode.json schema authoring) — pure pollution for browser-driving workflows. Meanwhile the genuinely useful browser-execute-guide.md was not a registered skill, only surfaced because the tool description said 'you MUST Read this file first.'

Two changes:

1) Gate customize-opencode built-in registration on BCODE_ENABLE_CUSTOMIZE_OPENCODE=1 (default off). A user-disk skill of the same name still loads, since the gate runs before disk discovery.

2) Rename packages/bcode-browser/skills/browser-execute-guide.md → browser-execute/SKILL.md, add frontmatter (name: browser-execute, description front-loads 'Use ONLY when calling browser_execute'), and extend discoverSkills to scan <dataDir>/skills/ where the bcode-browser package already materializes first-party skills. The skill now appears in <available_skills> at planning time and is loaded via the skill tool.

Updated browser-execute.txt to instruct 'you MUST use the skill tool first to load the browser-execute skill' — keeps the strong MUST language verbatim per user confirmation that the wording materially improves eval scores.

Author: bcode

packages/bcode-browser/README.md

@@ -12,7 +12,7 @@ See `decisions.md §1c` (three-level model) and `§1d` (this package) in the Bro
 | `src/browser-execute.ts` | In-process JS-eval `browser_execute` body. |
 | `src/session-store.ts` | Per-opencode-session CDP `Session` map. The agent calls `session.connect(...)` from a snippet; subsequent snippets find the same Session. |
 | `src/skills.ts` | Runtime resolver for embedded skills (extract on first call in compiled mode; in-tree path in dev). |
-| `skills/` | `browser-execute-guide.md` (the agent's prompt for `browser_execute`, covering all three connection Ways including Browser Use cloud provisioning via raw HTTP from inside a snippet). Embedded into the binary by `script/embed-skills.ts`. The interaction-skills set inherited from the Python harness was archived 2026-05-09 — we'll reintroduce only what evals show is needed, one skill at a time. |
+| `skills/` | `browser-execute/SKILL.md` (the agent-facing reference for `browser_execute`, covering all three connection Ways including Browser Use cloud provisioning via raw HTTP from inside a snippet). Registered as an opencode skill via frontmatter; surfaced in `<available_skills>` and loaded with the `skill` tool. Embedded into the binary by `script/embed-skills.ts`. The interaction-skills set inherited from the Python harness was archived 2026-05-09 — we'll reintroduce only what evals show is needed, one skill at a time. |
 | `script/embed-skills.ts` | Build-time embed; emits `bcode-skills.gen.ts` consumed by the compiled binary. |
 | `test/` | `bun test` smoke coverage for the workspace dynamic-import pattern. |
 

…-browser/skills/browser-execute-guide.md …-browser/skills/browser-execute/SKILL.mdpackages/bcode-browser/skills/browser-execute-guide.md renamed to packages/bcode-browser/skills/browser-execute/SKILL.md packages/bcode-browser/skills/browser-execute-guide.md renamed to packages/bcode-browser/skills/browser-execute/SKILL.md

@@ -1,3 +1,8 @@
+---
+name: browser-execute
+description: Use ONLY when calling the `browser_execute` tool or driving a real browser via the Chrome DevTools Protocol. Required reading before the first `browser_execute` call in a session. Covers the three connection methods (local Chrome with remote debugging, isolated debug-port profile, Browser Use cloud), the in-process `session` / `console` snippet model, attaching to a page target, common CDP commands, the per-project `.bcode/agent-workspace/` for reusable scripts, and screenshot auto-attachment.
+---
+
 The `browser_execute` tool evaluates JavaScript against a connected browser `session` via the Chrome DevTools Protocol.
 The snippet runs in-process; `session` is bound to a long-lived CDP `Session` that persists. Connect once, then drive many snippets.
 There is no helper namespace, just `session`, `console`, and standard JS globals. 

packages/bcode-browser/src/browser-execute.ts

@@ -56,7 +56,7 @@ const MAX_TIMEOUT_MS = 10 * 60 * 1000
 export const parameters = Schema.Struct({
   code: Schema.String.annotate({
     description:
-      "The JavaScript snippet to execute. `session` (CDP Session) and `console` are in scope; see browser-execute-guide.md for the snippet model.",
+      "The JavaScript snippet to execute. `session` (CDP Session) and `console` are in scope; see the `browser-execute` skill for the snippet model.",
   }),
   timeout: Schema.optional(Schema.Number).annotate({
     description: `Optional timeout in milliseconds (default ${DEFAULT_TIMEOUT_MS}, max ${MAX_TIMEOUT_MS})`,
@@ -145,7 +145,7 @@ const serialize = (v: unknown): string => {
 
 // Snippet executor. The CDP Session is resolved per-call from `SessionStore`
 // keyed on `ctx.sessionID`. The agent connects with `await session.connect(...)`
-// in one snippet (Way 1 / Way 2 / Way 3 in browser-execute-guide.md); the Session persists
+// in one snippet (Way 1 / Way 2 / Way 3 in skills/browser-execute/SKILL.md); the Session persists
 // for follow-up snippets in the same opencode session.
 //
 // `dataDir` is opencode's XDG_DATA_HOME for bcode (~/.local/share/bcode/ on

packages/bcode-browser/src/index.ts

@@ -11,10 +11,10 @@
 //   src/browser-execute.ts — in-process JS-eval browser_execute body
 //   src/session-store.ts   — per-opencode-session CDP Session map
 //   src/skills.ts          — runtime resolver for embedded skills
-//   skills/                — browser-execute-guide.md (embedded into binary)
+//   skills/                — browser-execute/SKILL.md (embedded into binary)
 //
 // Cloud browser provisioning is intentionally NOT a separate Level-1
-// surface. The agent reads Way 3 of `skills/browser-execute-guide.md` and
+// surface. The agent reads Way 3 of `skills/browser-execute/SKILL.md` and
 // writes the fetch+connect snippet itself, matching how local-browser
 // connect works (snippet-side, not tool-side). Decisions trail in
 // `memory/browsercode/decisions.md` §3.4.

packages/bcode-browser/test/skills.test.ts

@@ -14,7 +14,7 @@ test("resolveSkillsDir materializes skills with {{SKILLS_DIR}} substituted", asy
   try {
     const dir = await Skills.resolveSkillsDir(dataDir)
     expect(dir).toBe(path.join(dataDir, "skills"))
-    const browser = (await fs.readFile(path.join(dir, "browser-execute-guide.md"), "utf8")).replaceAll("\\", "/")
+    const browser = (await fs.readFile(path.join(dir, "browser-execute", "SKILL.md"), "utf8")).replaceAll("\\", "/")
     expect(browser).not.toContain("{{SKILLS_DIR}}")
     expect(browser).toContain(`${dir.replaceAll("\\", "/")}/`)
   } finally {
@@ -29,8 +29,8 @@ test("different dataDirs get their own substituted paths", async () => {
     const dirA = await Skills.resolveSkillsDir(a)
     const dirB = await Skills.resolveSkillsDir(b)
     const [browserA, browserB] = (await Promise.all([
-      fs.readFile(path.join(dirA, "browser-execute-guide.md"), "utf8"),
-      fs.readFile(path.join(dirB, "browser-execute-guide.md"), "utf8"),
+      fs.readFile(path.join(dirA, "browser-execute", "SKILL.md"), "utf8"),
+      fs.readFile(path.join(dirB, "browser-execute", "SKILL.md"), "utf8"),
     ])).map((s) => s.replaceAll("\\", "/"))
     const [a2, b2] = [dirA.replaceAll("\\", "/"), dirB.replaceAll("\\", "/")]
     expect(browserA).toContain(a2)

packages/bcode-browser/test/workspace-import.test.ts

@@ -3,7 +3,7 @@
 // at runtime from a `browser_execute` snippet via
 // `await import("/abs/path?t=" + Date.now())`. We don't run a real
 // `browser_execute` here — the point is to verify the dynamic-import
-// mechanism behaves as the browser-execute-guide.md prompt claims.
+// mechanism behaves as the browser-execute skill prompt claims.
 //
 // All four scenarios run against a real tmp dir, real .ts files, and
 // the real Bun module loader. No mocks.

packages/opencode/src/skill/index.ts

@@ -14,6 +14,7 @@ import { ConfigMarkdown } from "@/config/markdown"
 import { RuntimeFlags } from "@/effect/runtime-flags"
 import { Glob } from "@opencode-ai/core/util/glob"
 import * as Log from "@opencode-ai/core/util/log"
+import { Skills as BcodeSkills } from "@browser-use/bcode-browser/skills"
 import { Discovery } from "./discovery"
 import CUSTOMIZE_OPENCODE_SKILL_BODY from "./prompt/customize-opencode.md" with { type: "text" }
 import { isRecord } from "@/util/record"
@@ -216,6 +217,16 @@ const discoverSkills = Effect.fnUntraced(function* (
     }
   }
 
+  // BrowserCode-shipped skills (browser-execute and any future first-party
+  // reference docs) live at <dataDir>/skills/<name>/SKILL.md after the
+  // bcode-browser materialization step. Scan unconditionally — the dir may
+  // not exist yet on the very first launch before BrowserExecute.make has
+  // run, and that's fine (Glob returns empty).
+  const bcodeSkillsDir = BcodeSkills.skillsDir(global.data)
+  if (yield* fsys.isDir(bcodeSkillsDir)) {
+    yield* scan(state, bcodeSkillsDir, SKILL_PATTERN, { scope: "bcode" })
+  }
+
   return {
     matches: Array.from(state.matches),
     dirs: Array.from(state.dirs),
@@ -258,13 +269,26 @@ 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 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: "<built-in>",
-          content: CUSTOMIZE_OPENCODE_SKILL_BODY,
+        // BrowserCode gate: the upstream `customize-opencode` built-in is
+        // off-by-default in BrowserCode. The skill describes opencode.json,
+        // opencode plugins, opencode agents — not useful for browser-driving
+        // sessions, and registering it unconditionally pollutes the system
+        // prompt with negative-signal content (eval data showed a measurable
+        // regression on browser-task scores when this skill was forced on).
+        // Set BCODE_ENABLE_CUSTOMIZE_OPENCODE=1 to opt back in for sessions
+        // where the user is actually editing bcode.json or agent configs.
+        // Skipped registration happens BEFORE disk discovery, so a user-disk
+        // skill named `customize-opencode` still loads normally.
+        const customizeEnabled =
+          process.env.BCODE_ENABLE_CUSTOMIZE_OPENCODE === "1" ||
+          process.env.BCODE_ENABLE_CUSTOMIZE_OPENCODE?.toLowerCase() === "true"
+        if (customizeEnabled) {
+          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/tool/browser-execute.txt

@@ -3,5 +3,5 @@ Executes JavaScript in a browser via CDP.
 Usage:
 - Use this tool whenever the task requires driving a real browser.
 - Use this tool to read webpages that block the webfetch tool.
-- IMPORTANT: you MUST use the Read tool first to read `{{SKILLS_DIR}}/browser-execute-guide.md`. This tool will fail if you did not read these directions first.
+- IMPORTANT: you MUST use the skill tool first to load the `browser-execute` skill. This tool will fail if you did not read those directions first.
 - Returns console output from the snippet; screenshots taken attach automatically as images.