@khalilgharbaoui/opencode-claude-code-plugin 0.17.0 → 0.18.0

package/README.md

@@ -553,6 +553,20 @@ Notes:
 
 Fully restart opencode after upgrading to load the command and runtime changes. Other providers do not gain Claude's native side-question behavior from this command.
 
+## Configuration skill
+
+The package includes a `claude-code-plugin` skill so your agent can configure it without asking you to navigate all its options. Ask, for example:
+
+```text
+Use the claude-code-plugin skill to configure a work account and idle worker cleanup.
+```
+
+It covers accounts, models and agent effort, proxy tools, permissions, MCP/skill bridging, timeouts, logging, upgrades and troubleshooting. It directs the agent to preserve JSONC comments, change only requested settings, validate the result, protect credentials and ask before paid probes or broader permissions.
+
+The plugin registers the bundled directory with opencode's `skills.paths`, making it available to other providers too on supporting opencode versions. For ordinary headless Claude turns it also loads through Claude's native Skill tool as `opencode-skills:claude-code-plugin`, even when `bridgeOpencodeSkills` is off. This requires CLI `--plugin-dir` support; interactive transport, compaction and direct `doGenerate` calls do not load the native bridge.
+
+No separate skill installation or copying is needed. It ships with each package version, so upgrading updates the reference. Fully restart opencode to load it. `test-configure-skill.ts` checks coverage of provider/logging options, model ids, proxy tools and environment variables; maintainers must update behavior and default guidance in the same change as the implementation.
+
 ## Skill bridge
 
 opencode and Claude Code use the same on-disk skill format, a `<name>/SKILL.md` whose frontmatter carries `name` and `description`, but they read from different directories. opencode looks in `.opencode/skills/` and `~/.config/opencode/skills/`; the Claude CLI looks in `~/.claude/skills/` and its own plugins. So opencode advertises your skills in the system prompt it forwards, the model calls `Skill("browser-automation")`, and Claude answers `Unknown skill`.
@@ -568,7 +582,7 @@ Claude can invoke them with the Skill tool or as `/opencode-skills:<name>`. `--p
 
 Discovery order, first match wins: `.opencode/skills/` walking up from the working directory, then `~/.opencode/skills/`, then `$OPENCODE_CONFIG_DIR/skills/`, then `~/.config/opencode/skills/`. A project skill shadows a global one of the same name. If the skill set is unchanged the staged directory is reused between spawns.
 
-It is **off by default** here, unlike on the fork it came from: every bridged skill is also listed in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Turn it on when you see `Unknown skill`. It no-ops on the compaction path and on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
+Bridging **your own skills is off by default** here, unlike on the fork it came from: every bridged skill is also listed in the system prompt opencode already forwards, so a large skill set is paid for twice on every turn. Turn it on when you see `Unknown skill`. The bundled configuration skill is loaded independently of this opt-in. The native bridge is not used for compaction or interactive transport, or on a Claude CLI without `--plugin-dir` (the plugin probes `claude --help` and logs a notice).
 
 This bridge was written by [@broskees](https://github.com/broskees) (Joseph Roberts) on his fork and absorbed here with credit; see [Credits](#credits).
 

package/dist/index.d.ts

@@ -78,6 +78,10 @@ type OpenCodeConfig = {
         models?: Record<string, unknown>;
     }>;
     agent?: Record<string, Record<string, unknown>>;
+    skills?: {
+        paths?: string[];
+        urls?: string[];
+    };
 };
 /**
  * Bus events surface to plugins. Shape mirrors what opencode core publishes

package/dist/index.js

@@ -447,10 +447,13 @@ function detectCliSupportsFlag(cliPath, flag) {
   if (cached) return cached;
   const promise = (async () => {
     try {
-      const { stdout } = await execFileAsync(cliPath, ["--help"], {
+      const execution = execFileAsync(cliPath, ["--help"], {
         timeout: 5e3,
+        killSignal: "SIGKILL",
         maxBuffer: 4 * 1024 * 1024
       });
+      execution.child.stdin?.end();
+      const { stdout } = await execution;
       return stdout.includes(flag);
     } catch (err) {
       log.warn("failed to probe claude cli flag support", {
@@ -3302,7 +3305,17 @@ import * as crypto2 from "crypto";
 import * as fs3 from "fs";
 import * as os2 from "os";
 import * as path4 from "path";
+import { fileURLToPath } from "url";
 var SKILL_PLUGIN_NAME = "opencode-skills";
+function bundledSkillsDir() {
+  try {
+    const here = fileURLToPath(import.meta.url);
+    const dir = path4.resolve(path4.dirname(here), "..", "skills");
+    return dirExists(dir) ? dir : null;
+  } catch {
+    return null;
+  }
+}
 function dirExists(p) {
   try {
     return fs3.statSync(p).isDirectory();
@@ -3341,28 +3354,46 @@ function skillRoots(cwd) {
   if (xdg) push(path4.join(xdg, "opencode", "skills"));
   return roots;
 }
+function collectSkills(root, claimed, found) {
+  let entries;
+  try {
+    entries = fs3.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
+    const name = entry.name;
+    if (name.startsWith(".")) continue;
+    if (claimed.has(name)) continue;
+    const dir = path4.join(root, name);
+    if (!fileExists(path4.join(dir, "SKILL.md"))) continue;
+    claimed.add(name);
+    found.push({ name, dir });
+  }
+}
+var byName = (a, b) => a.name.localeCompare(b.name);
 function discoverOpencodeSkills(cwd) {
   const found = [];
   const claimed = /* @__PURE__ */ new Set();
-  for (const root of skillRoots(cwd)) {
-    let entries;
-    try {
-      entries = fs3.readdirSync(root, { withFileTypes: true });
-    } catch {
-      continue;
-    }
-    for (const entry of entries) {
-      if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
-      const name = entry.name;
-      if (name.startsWith(".")) continue;
-      if (claimed.has(name)) continue;
-      const dir = path4.join(root, name);
-      if (!fileExists(path4.join(dir, "SKILL.md"))) continue;
-      claimed.add(name);
-      found.push({ name, dir });
-    }
-  }
-  return found.sort((a, b) => a.name.localeCompare(b.name));
+  for (const root of skillRoots(cwd)) collectSkills(root, claimed, found);
+  return found.sort(byName);
+}
+function discoverBundledSkills() {
+  const root = bundledSkillsDir();
+  if (!root) return [];
+  const found = [];
+  collectSkills(root, /* @__PURE__ */ new Set(), found);
+  return found.sort(byName);
+}
+function registerBundledSkillPath(config) {
+  const dir = bundledSkillsDir();
+  if (!dir) return false;
+  config.skills ??= {};
+  const paths = config.skills.paths ??= [];
+  if (paths.some((p) => path4.resolve(p) === dir)) return false;
+  paths.push(dir);
+  return true;
 }
 function linkSkill(source, target) {
   try {
@@ -3408,8 +3439,10 @@ function buildSkillPluginDir(skills) {
   return root;
 }
 async function resolveSkillPluginDirs(opts) {
-  if (!opts.enabled) return [];
-  const skills = discoverOpencodeSkills(opts.cwd);
+  const user = opts.enabled ? discoverOpencodeSkills(opts.cwd) : [];
+  const claimed = new Set(user.map((s) => s.name));
+  const bundled = discoverBundledSkills().filter((s) => !claimed.has(s.name));
+  const skills = [...user, ...bundled].sort(byName);
   if (skills.length === 0) return [];
   const supported = await detectCliSupportsFlag(opts.cliPath, "--plugin-dir");
   if (!supported) {
@@ -3424,6 +3457,7 @@ async function resolveSkillPluginDirs(opts) {
   log.info("bridged opencode skills into claude", {
     count: skills.length,
     names: skills.map((s) => s.name),
+    bundled: bundled.map((s) => s.name),
     pluginDir: dir
   });
   return [dir];
@@ -7670,7 +7704,7 @@ import {
 } from "fs";
 import { homedir as homedir6 } from "os";
 import { join as join8, resolve as resolve4 } from "path";
-import { fileURLToPath } from "url";
+import { fileURLToPath as fileURLToPath2 } from "url";
 var STALE_PACKAGE_NAME = "opencode-claude-code-plugin";
 var SUSPECT_DESCRIPTION_TOKEN = "Claude Code";
 var alreadyRan = false;
@@ -7702,7 +7736,7 @@ function userIntendsToUseUnscoped() {
 }
 function ourLoadedDir() {
   try {
-    const filePath = fileURLToPath(import.meta.url);
+    const filePath = fileURLToPath2(import.meta.url);
     return realpathSync(resolve4(filePath, "..", ".."));
   } catch {
     return null;
@@ -7776,12 +7810,12 @@ import { execFile as execFile2 } from "child_process";
 import * as fs6 from "fs";
 import * as path8 from "path";
 import { promisify as promisify2 } from "util";
-import { fileURLToPath as fileURLToPath2 } from "url";
+import { fileURLToPath as fileURLToPath3 } from "url";
 var cachedPluginVersion;
 function pluginVersion() {
   if (cachedPluginVersion) return cachedPluginVersion;
   try {
-    const here = path8.dirname(fileURLToPath2(import.meta.url));
+    const here = path8.dirname(fileURLToPath3(import.meta.url));
     const raw = fs6.readFileSync(path8.join(here, "..", "package.json"), "utf8");
     const version = JSON.parse(raw).version;
     cachedPluginVersion = typeof version === "string" ? version : "unknown";
@@ -8177,6 +8211,7 @@ var server = async (input) => {
   return {
     config: async (config) => {
       if (registerSideQuestionCommand(config)) ownsSideQuestionCommand = true;
+      registerBundledSkillPath(config);
       config.provider ??= {};
       await buildAgentRegistry(config);
       const expanded = await expandAccountProviders(config);