argsbarg 4.0.4 → 4.1.1

package/src/mcp/claude.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
-import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CliProgram } from "../types.ts";
@@ -36,6 +37,7 @@ describe("claude plugin", () => {
   test("generatePluginManifest includes userConfig from program.appConfig", () => {
     const manifest = generatePluginManifest(configFixture, "myapp");
     expect(manifest.name).toBe("myapp");
+    expect(manifest.mcpServers).toBe(".mcp.json");
     const userConfig = manifest.userConfig as Record<string, Record<string, unknown>>;
     expect(userConfig.api_token?.description).toBe("Token from settings.");
     expect(userConfig.api_token?.sensitive).toBe(true);
@@ -72,6 +74,17 @@ describe("claude plugin", () => {
       expect(zipText).toContain("Server id: `myapp`");
       expect(zipText).not.toContain("skills/myapp/reference.md");
       expect(zipText).not.toContain("Invoke via shell");
+
+      writeFileSync(join(work, "out.zip"), zip);
+      const extract = join(work, "extract");
+      mkdirSync(extract, { recursive: true });
+      execSync("unzip -o -q ../out.zip", { cwd: extract });
+      const binMode = statSync(join(extract, "bin", "myapp")).mode & 0o777;
+      expect(binMode & 0o111).not.toBe(0);
+      const pluginJson = JSON.parse(
+        readFileSync(join(extract, ".claude-plugin", "plugin.json"), "utf8"),
+      ) as { mcpServers: string };
+      expect(pluginJson.mcpServers).toBe(".mcp.json");
     } finally {
       rmSync(work, { recursive: true, force: true });
     }

package/src/mcp/claude.ts

@@ -12,6 +12,7 @@ import {
   readdirSync,
   readFileSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from "node:fs";
 import { tmpdir } from "node:os";
@@ -22,7 +23,7 @@ import { applyPluginSkillHint } from "../skill/hint.ts";
 import type { CliMcpBundleConfig, CliProgram } from "../types.ts";
 import { defaultMcpBundlePaths, type PackMcpBundleOpts } from "./bundle.ts";
 import { mcpServerId } from "./tools.ts";
-import { zipStore } from "./zip.ts";
+import { type ZipFileEntry, zipStore } from "./zip.ts";
 
 const DIST_DIR = "dist";
 const CLAUDE_PLUGIN_DIR = "claude-plugin";
@@ -67,6 +68,7 @@ export function generatePluginManifest(
     version: program.version,
     description: program.description,
     author: defaultAuthor(bundle),
+    mcpServers: ".mcp.json",
   };
   const userConfig = buildProgramUserConfig(program);
   if (userConfig) {
@@ -93,8 +95,8 @@ export function generatePluginMcpJson(
   };
 }
 
-function collectZipEntries(rootDir: string, dir = rootDir): { name: string; data: Buffer }[] {
-  const entries: { name: string; data: Buffer }[] = [];
+function collectZipEntries(rootDir: string, dir = rootDir): ZipFileEntry[] {
+  const entries: ZipFileEntry[] = [];
   for (const ent of readdirSync(dir, { withFileTypes: true }) as Dirent[]) {
     const full = join(dir, ent.name);
     if (ent.isDirectory()) {
@@ -105,7 +107,12 @@ function collectZipEntries(rootDir: string, dir = rootDir): { name: string; data
       continue;
     }
     const rel = relative(rootDir, full).split("\\").join("/");
-    entries.push({ name: rel, data: readFileSync(full) });
+    const stMode = statSync(full).mode;
+    const entry: ZipFileEntry = { name: rel, data: readFileSync(full) };
+    if (stMode & 0o111) {
+      entry.unixMode = stMode;
+    }
+    entries.push(entry);
   }
   return entries;
 }

package/src/mcp/env.test.ts

@@ -0,0 +1,92 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { applyShellEnv, bootstrapMcpEnv } from "./env.ts";
+
+const TEST_VAR = "ARGS_BARG_SHELL_ENV_TEST";
+
+describe("mcp/env", () => {
+  test("applyShellEnv merges PATH and fills missing vars", () => {
+    const prevPath = process.env.PATH;
+    const prevTest = process.env[TEST_VAR];
+    delete process.env[TEST_VAR];
+    try {
+      process.env.PATH = "/host/bin";
+      applyShellEnv({
+        PATH: "/shell/bin:/host/bin",
+        [TEST_VAR]: "from-shell",
+      });
+      expect(process.env.PATH).toBe("/shell/bin:/host/bin");
+      expect(process.env[TEST_VAR]).toBe("from-shell");
+    } finally {
+      if (prevPath === undefined) delete process.env.PATH;
+      else process.env.PATH = prevPath;
+      if (prevTest === undefined) delete process.env[TEST_VAR];
+      else process.env[TEST_VAR] = prevTest;
+    }
+  });
+
+  test("applyShellEnv does not overwrite host vars except PATH merge", () => {
+    const prev = process.env.HOME;
+    process.env.HOME = "/host/home";
+    try {
+      applyShellEnv({ HOME: "/shell/home" });
+      expect(process.env.HOME).toBe("/host/home");
+    } finally {
+      if (prev === undefined) delete process.env.HOME;
+      else process.env.HOME = prev;
+    }
+  });
+});
+
+describe("bootstrapMcpEnv", () => {
+  let fakeShell: string;
+  let prevShell: string | undefined;
+  let prevTest: string | undefined;
+
+  beforeEach(() => {
+    const dir = mkdtempSync(join(tmpdir(), "argsbarg-shell-env-"));
+    fakeShell = join(dir, "fake-shell.sh");
+    writeFileSync(
+      fakeShell,
+      `#!/bin/sh
+if [ "$1" = "-l" ] && [ "$2" = "-c" ] && [ "$3" = "env" ]; then
+  echo "${TEST_VAR}=from_fake_shell"
+fi
+`,
+    );
+    chmodSync(fakeShell, 0o755);
+    prevShell = process.env.SHELL;
+    prevTest = process.env[TEST_VAR];
+    delete process.env[TEST_VAR];
+    process.env.SHELL = fakeShell;
+  });
+
+  afterEach(() => {
+    if (prevShell === undefined) delete process.env.SHELL;
+    else process.env.SHELL = prevShell;
+    if (prevTest === undefined) delete process.env[TEST_VAR];
+    else process.env[TEST_VAR] = prevTest;
+  });
+
+  test("defaults on when shellEnv is undefined", () => {
+    bootstrapMcpEnv({});
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("runs when shellEnv is true", () => {
+    bootstrapMcpEnv({ shellEnv: true });
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("uses explicit shell path when shellEnv is a string", () => {
+    bootstrapMcpEnv({ shellEnv: fakeShell });
+    expect(process.env[TEST_VAR]).toBe("from_fake_shell");
+  });
+
+  test("skips capture when shellEnv is false", () => {
+    bootstrapMcpEnv({ shellEnv: false });
+    expect(process.env[TEST_VAR]).toBeUndefined();
+  });
+});

package/src/mcp/env.ts

@@ -39,21 +39,22 @@ export function applyShellEnv(env: Record<string, string>): void {
   }
 }
 
-/** Applies mcpServer shellEnv bootstrap. */
+/** Applies mcpServer shellEnv bootstrap (default on; opt out with `shellEnv: false`). */
 export function bootstrapMcpEnv(config: { shellEnv?: boolean | string }): void {
+  if (config.shellEnv === false) {
+    return;
+  }
   const shellEnvCfg = config.shellEnv;
-  if (shellEnvCfg) {
-    const shell =
-      typeof shellEnvCfg === "string"
-        ? shellEnvCfg
-        : (process.env.SHELL ?? (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash"));
-    const captured = captureShellEnv(shell);
-    if (Object.keys(captured).length === 0) {
-      process.stderr.write(
-        `[argsbarg] shellEnv: failed to capture shell environment from ${shell}\n`,
-      );
-    } else {
-      applyShellEnv(captured);
-    }
+  const shell =
+    typeof shellEnvCfg === "string"
+      ? shellEnvCfg
+      : (process.env.SHELL ?? (process.platform === "darwin" ? "/bin/zsh" : "/bin/bash"));
+  const captured = captureShellEnv(shell);
+  if (Object.keys(captured).length === 0) {
+    process.stderr.write(
+      `[argsbarg] shellEnv: failed to capture shell environment from ${shell}\n`,
+    );
+  } else {
+    applyShellEnv(captured);
   }
 }

package/src/mcp/zip.test.ts

@@ -0,0 +1,17 @@
+import { expect, test } from "bun:test";
+import { execSync } from "node:child_process";
+import { mkdtempSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { zipStore } from "./zip.ts";
+
+test("zipStore preserves unix executable mode on extract", () => {
+  const work = mkdtempSync(join(tmpdir(), "zip-exec-"));
+  const data = Buffer.from("#!/bin/sh\necho hi\n");
+  const zip = zipStore([{ name: "bin/tool", data, unixMode: 0o100755 }]);
+  writeFileSync(join(work, "plugin.zip"), zip);
+  execSync("unzip -o -q plugin.zip", { cwd: work });
+  const mode = statSync(join(work, "bin", "tool")).mode & 0o777;
+  expect(mode & 0o111).not.toBe(0);
+  expect(readFileSync(join(work, "bin", "tool"), "utf8")).toBe("#!/bin/sh\necho hi\n");
+});

package/src/mcp/zip.ts

@@ -2,6 +2,41 @@
 Minimal ZIP writer (store method, no compression) for MCPB and Claude plugin bundles.
 */
 
+/** Info-ZIP Unix UID/GID extra field (`0x7875`) for permission restore on extract. */
+function unixUxExtraField(uid: number, gid: number): Buffer {
+  const uidBuf = Buffer.alloc(4);
+  uidBuf.writeUInt32LE(uid >>> 0, 0);
+  const gidBuf = Buffer.alloc(4);
+  gidBuf.writeUInt32LE(gid >>> 0, 0);
+  const payload = Buffer.concat([Buffer.from([1, 4]), uidBuf, Buffer.from([4]), gidBuf]);
+  const header = Buffer.alloc(4);
+  header.writeUInt16LE(0x7875, 0);
+  header.writeUInt16LE(payload.length, 2);
+  return Buffer.concat([header, payload]);
+}
+
+/** Info-ZIP Unix permission extra field (`0x7855`). */
+function unixUpExtraField(unixMode: number): Buffer {
+  const payload = Buffer.alloc(5);
+  payload.writeUInt8(1, 0);
+  payload.writeUInt32LE(unixMode >>> 0, 1);
+  const header = Buffer.alloc(4);
+  header.writeUInt16LE(0x7855, 0);
+  header.writeUInt16LE(payload.length, 2);
+  return Buffer.concat([header, payload]);
+}
+
+function unixExtraFields(unixMode: number): Buffer {
+  const { uid, gid } = defaultUnixIds();
+  return Buffer.concat([unixUpExtraField(unixMode), unixUxExtraField(uid, gid)]);
+}
+
+function defaultUnixIds(): { uid: number; gid: number } {
+  const uid = typeof process.getuid === "function" ? process.getuid() : 501;
+  const gid = typeof process.getgid === "function" ? process.getgid() : 20;
+  return { uid, gid };
+}
+
 /** CRC-32 for ZIP local headers. */
 function crc32(data: Buffer): number {
   let crc = 0xffffffff;
@@ -18,8 +53,16 @@ function crc32(data: Buffer): number {
   return (crc ^ 0xffffffff) >>> 0;
 }
 
+/** One file entry for {@link zipStore}. */
+export interface ZipFileEntry {
+  name: string;
+  data: Buffer;
+  /** Unix permission bits (e.g. `0o755`). Encoded in ZIP external attributes when set. */
+  unixMode?: number;
+}
+
 /** Writes a minimal ZIP (store, no compression) with one or more files. */
-export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
+export function zipStore(files: ZipFileEntry[]): Buffer {
   const parts: Buffer[] = [];
   const central: Buffer[] = [];
   let offset = 0;
@@ -27,9 +70,11 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
   for (const file of files) {
     const nameBuf = Buffer.from(file.name, "utf8");
     const crc = crc32(file.data);
-    const local = Buffer.alloc(30 + nameBuf.length);
+    const unixMode = file.unixMode;
+    const extra = unixMode !== undefined ? unixExtraFields(unixMode) : Buffer.alloc(0);
+    const local = Buffer.alloc(30 + nameBuf.length + extra.length);
     local.writeUInt32LE(0x04034b50, 0);
-    local.writeUInt16LE(20, 4);
+    local.writeUInt16LE(unixMode !== undefined ? 10 : 20, 4);
     local.writeUInt16LE(0, 6);
     local.writeUInt16LE(0, 8);
     local.writeUInt16LE(0, 10);
@@ -38,13 +83,15 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
     local.writeUInt32LE(file.data.length, 18);
     local.writeUInt32LE(file.data.length, 22);
     local.writeUInt32LE(nameBuf.length, 26);
-    local.writeUInt16LE(0, 28);
+    local.writeUInt16LE(extra.length, 28);
     nameBuf.copy(local, 30);
+    extra.copy(local, 30 + nameBuf.length);
 
-    const centralHdr = Buffer.alloc(46 + nameBuf.length);
+    const centralHdr = Buffer.alloc(46 + nameBuf.length + extra.length);
     centralHdr.writeUInt32LE(0x02014b50, 0);
-    centralHdr.writeUInt16LE(20, 4);
-    centralHdr.writeUInt16LE(20, 6);
+    // macOS Info-ZIP stores version made by before version needed (non-APPNOTE layout).
+    centralHdr.writeUInt16LE(unixMode !== undefined ? 0x031e : 20, 4);
+    centralHdr.writeUInt16LE(unixMode !== undefined ? 10 : 20, 6);
     centralHdr.writeUInt16LE(0, 8);
     centralHdr.writeUInt16LE(0, 10);
     centralHdr.writeUInt16LE(0, 12);
@@ -53,13 +100,19 @@ export function zipStore(files: { name: string; data: Buffer }[]): Buffer {
     centralHdr.writeUInt32LE(file.data.length, 20);
     centralHdr.writeUInt32LE(file.data.length, 24);
     centralHdr.writeUInt32LE(nameBuf.length, 28);
-    centralHdr.writeUInt16LE(0, 30);
+    centralHdr.writeUInt16LE(extra.length, 30);
     centralHdr.writeUInt16LE(0, 32);
     centralHdr.writeUInt16LE(0, 34);
     centralHdr.writeUInt16LE(0, 36);
-    centralHdr.writeUInt32LE(0, 38);
+    if (unixMode !== undefined) {
+      const externalAttr = (unixMode << 16) >>> 0;
+      centralHdr.writeUInt32LE(externalAttr, 38);
+    } else {
+      centralHdr.writeUInt32LE(0, 38);
+    }
     centralHdr.writeUInt32LE(offset, 42);
     nameBuf.copy(centralHdr, 46);
+    extra.copy(centralHdr, 46 + nameBuf.length);
 
     parts.push(local, file.data);
     central.push(centralHdr);

package/src/mcp.integration.test.ts

@@ -469,7 +469,7 @@ test("MCP ping returns empty result", async () => {
 test("minimal.ts mcp without opt-in fails", async () => {
   const { stderr, exitCode } = await $`bun run examples/minimal.ts mcp`.nothrow().quiet();
   expect(exitCode).toBe(1);
-  expect(stderr.toString()).toContain("MCP is not enabled");
+  expect(stderr.toString()).toContain("MCP is not available");
 });
 
 test("MCP resources/list includes custom resource", async () => {

package/src/parse.test.ts

@@ -495,7 +495,7 @@ test("leaf completion help prints correctly", async () => {
   const out = stdout.toString();
   expect(exitCode).toBe(0);
   expect(out).toContain("Show help for this command.");
-  expect(out).toContain("Manual install:");
+  expect(out).toContain("Homebrew");
   expect(stderr.toString()).toBe("");
 });
 
@@ -529,6 +529,7 @@ test("docs schema exports JSON for leaf roots", async () => {
     "completion",
     "version",
     "install",
+    "uninstall",
     "docs",
   ]);
 });
@@ -614,7 +615,7 @@ test("cliSchemaExport resolves program key in install notes", () => {
 
   const json = cliSchemaJson(root);
   expect(json).not.toContain("{argsbarg:program}");
-  expect(json).toContain("myapp install --all --yes");
+  expect(json).toContain("brew install");
 });
 
 test("cliSchemaExport resolves {argsbarg:program} in consumer notes", () => {
@@ -1124,6 +1125,17 @@ test("install config on non-root node is rejected", () => {
   expect(() => cliValidateProgram(root)).toThrow(/install is only supported on the program root/);
 });
 
+test("install.prefix is rejected", () => {
+  const root = {
+    key: "app",
+    version: "0.0.0",
+    description: "",
+    install: { prefix: "/opt/bin" },
+    handler: () => {},
+  } as unknown as CliProgram;
+  expect(() => cliValidateProgram(root)).toThrow(/install\.prefix removed/);
+});
+
 test("generateSkillBundle includes frontmatter and compact command index", () => {
   const bundle = generateSkillBundle(nestedMcpFixture, "cursor");
   expect(bundle.dirName).toBe("nested_ts");

package/src/paths/host.ts

@@ -21,20 +21,20 @@ export function expandTilde(path: string): string {
   return path;
 }
 
+/** Display path using `~/` when under the user home directory. */
+export function displayHomePath(absolutePath: string, home = userHome()): string {
+  if (home.length > 0 && absolutePath.startsWith(home)) {
+    return `~${absolutePath.slice(home.length)}`;
+  }
+  return absolutePath;
+}
+
 /** XDG config base directory (`$XDG_CONFIG_HOME` or `~/.config`). */
 export function xdgConfigHome(home = userHome()): string {
   return process.env.XDG_CONFIG_HOME ?? join(home, ".config");
 }
 
-/** Windows `%APPDATA%` (or `~/AppData/Roaming`). */
-export function appDataHome(home = userHome()): string {
-  return process.env.APPDATA ?? join(home, "AppData", "Roaming");
-}
-
-/** OS-appropriate base directory for app config files. */
-export function appConfigHome(home = userHome()): string {
-  if (process.platform === "win32") {
-    return appDataHome(home);
-  }
-  return xdgConfigHome(home);
+/** App config library root (`~/.local/lib`). */
+export function appConfigLibHome(home = userHome()): string {
+  return join(home, ".local", "lib");
 }

package/src/paths/remove-empty-dir.ts

@@ -0,0 +1,13 @@
+import { existsSync, readdirSync, rmdirSync } from "node:fs";
+
+/** Removes a directory when it exists and is empty. Returns true when removed. */
+export function removeEmptyDir(path: string): boolean {
+  if (!existsSync(path)) return false;
+  try {
+    if (readdirSync(path).length > 0) return false;
+    rmdirSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/prompt.ts

@@ -0,0 +1,10 @@
+/** Shared terminal prompt helpers. */
+
+import { readSync } from "node:fs";
+
+/** Read one line from stdin (no masking). */
+export function readPromptLine(): string {
+  const buf = Buffer.alloc(4096);
+  const n = readSync(0, buf, { length: 4096 });
+  return buf.toString("utf8", 0, n).replace(/\r?\n$/, "");
+}

package/src/schema.ts

@@ -13,7 +13,15 @@ import {
   leafOutputSchema,
 } from "./types.ts";
 
-const RESERVED = new Set(["completion", "install", "docs", "mcp", "version", "config"]);
+const RESERVED = new Set([
+  "completion",
+  "install",
+  "uninstall",
+  "docs",
+  "mcp",
+  "version",
+  "config",
+]);
 
 function exportCommand(cmd: CliNode, root: CliProgram): CliSchemaExport | null {
   if (cmd.hidden) {

package/src/skill/generate.ts

@@ -13,8 +13,10 @@ import {
 } from "../mcp/tools.ts";
 import { collectOptionDefs } from "../parse.ts";
 import { CliOptionKind, type CliProgram } from "../types.ts";
+import type { SkillTarget } from "./naming.ts";
+import { skillDirNameForTarget, skillFrontmatterName } from "./naming.ts";
 
-export type SkillTarget = "cursor" | "claude";
+export type { SkillTarget } from "./naming.ts";
 
 export interface SkillBundle {
   dirName: string;
@@ -103,7 +105,7 @@ function buildConfigurationSection(root: CliProgram): string[] {
 
 /** Builds SKILL.md body for the given target. */
 function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): string {
-  const name = sanitizeToolSegment(root.key);
+  const name = skillFrontmatterName(root.key, target);
   const description = skillDescription(root);
   const tools = collectMcpTools(root);
 
@@ -161,7 +163,7 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       "Do not install under `~/.cursor/skills-cursor/` (reserved for Cursor built-ins).",
       "",
     );
-  } else {
+  } else if (target === "claude") {
     lines.push(
       "## Claude Code",
       "",
@@ -171,6 +173,18 @@ function buildSkillMd(root: CliProgram, target: SkillTarget, dirName: string): s
       `- Bundled files in this directory are available via \`\${CLAUDE_SKILL_DIR}\` when the skill runs.`,
       "",
     );
+  } else if (target === "codex") {
+    lines.push(
+      "## Codex",
+      "",
+      `- Global: \`~/.codex/skills/${dirName}/\``,
+      "- Enable skills in `~/.codex/config.toml` if required.",
+      "",
+    );
+  } else if (target === "opencode") {
+    lines.push("## OpenCode", "", `- Global: \`~/.config/opencode/skills/${dirName}/\``, "");
+  } else {
+    lines.push("## OpenClaw", "", `- Global: \`~/.openclaw/skills/${dirName}/\``, "");
   }
 
   return lines.join("\n");
@@ -231,7 +245,7 @@ export function generatePluginSkillBundle(root: CliProgram): PluginSkillBundle {
 
 /** Generates SKILL.md and reference.md for Cursor or Claude Code. */
 export function generateSkillBundle(root: CliProgram, target: SkillTarget): SkillBundle {
-  const dirName = sanitizeToolSegment(root.key);
+  const dirName = skillDirNameForTarget(root.key, target);
   return {
     dirName,
     skillMd: buildSkillMd(root, target, dirName),

package/src/skill/install.ts

@@ -5,19 +5,28 @@ import type { CliProgram } from "../types.ts";
 import { generateSkillBundle, type SkillTarget } from "./generate.ts";
 import { applySkillInstallHints } from "./hint.ts";
 
+export { skillDirNameForTarget, skillFrontmatterName, skillSlug } from "./naming.ts";
+
 export interface SkillInstallOpts {
   global?: boolean;
-  /** When true, remove an existing skill directory before writing. */
   rimraf?: boolean;
-  /** When true, skip writes but return paths that would change. */
   dry?: boolean;
 }
 
 function resolveSkillDir(target: SkillTarget, dirName: string, global: boolean): string {
-  const base = global
-    ? join(userHome(), target === "cursor" ? ".cursor" : ".claude", "skills")
-    : join(process.cwd(), target === "cursor" ? ".cursor" : ".claude", "skills");
-  return join(base, dirName);
+  const home = userHome();
+  switch (target) {
+    case "cursor":
+      return join(global ? home : process.cwd(), ".cursor", "skills", dirName);
+    case "claude":
+      return join(global ? home : process.cwd(), ".claude", "skills", dirName);
+    case "codex":
+      return join(global ? home : process.cwd(), ".codex", "skills", dirName);
+    case "opencode":
+      return join(global ? home : process.cwd(), ".config", "opencode", "skills", dirName);
+    case "openclaw":
+      return join(global ? home : process.cwd(), ".openclaw", "skills", dirName);
+  }
 }
 
 /** Writes SKILL.md and reference.md; returns changed file paths. */
@@ -47,3 +56,21 @@ export function cliSkillInstall(
   changed.push(skillPath, refPath);
   return changed;
 }
+
+/** Maps install action kind to skill target. */
+export function skillTargetFromActionKind(kind: string): SkillTarget | undefined {
+  switch (kind) {
+    case "cursor-skill":
+      return "cursor";
+    case "claude-skill":
+      return "claude";
+    case "codex-skill":
+      return "codex";
+    case "opencode-skill":
+      return "opencode";
+    case "openclaw-skill":
+      return "openclaw";
+    default:
+      return undefined;
+  }
+}

package/src/skill/naming.ts

@@ -0,0 +1,28 @@
+/** Agent skill install targets. */
+export type SkillTarget = "cursor" | "claude" | "codex" | "opencode" | "openclaw";
+
+import { sanitizeToolSegment } from "../mcp/tools.ts";
+
+/** Kebab-case skill folder + frontmatter name for agents that require hyphen slugs. */
+export function skillSlug(programKey: string): string {
+  return programKey
+    .replace(/[^a-zA-Z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .toLowerCase();
+}
+
+/** Directory name for a skill target (underscore vs kebab conventions). */
+export function skillDirNameForTarget(programKey: string, target: SkillTarget): string {
+  if (target === "cursor" || target === "claude") {
+    return sanitizeToolSegment(programKey);
+  }
+  return skillSlug(programKey);
+}
+
+/** Frontmatter `name` for SKILL.md by target. */
+export function skillFrontmatterName(programKey: string, target: SkillTarget): string {
+  if (target === "cursor" || target === "claude") {
+    return sanitizeToolSegment(programKey);
+  }
+  return skillSlug(programKey);
+}