@cli-skill/cli 0.0.1-beta-d3a2d41

package/bin/cli-skill

@@ -0,0 +1,3 @@
+#!/usr/bin/env bun
+
+import "../src/index.ts";

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@cli-skill/cli",
+  "version": "0.0.1-beta-d3a2d41",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "cli-skill": "./bin/cli-skill"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc --noEmit -p tsconfig.json"
+  },
+  "dependencies": {
+    "@cli-skill/core": "^0.0.1-beta-d3a2d41",
+    "cac": "^6.7.14",
+    "lodash": "^4.17.21"
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: cli-skill-creator
+description: 当需要创建、接通、安装或维护 cli skill 时，使用 cli-skill CLI 完成标准流程。
+---
+
+# cli-skill-creator
+
+当用户要创建一个新的 cli skill，接通本地开发中的 skill，安装一个已发布的 skill，或者维护 cli-skill 的全局配置时，使用这个 skill。
+
+## 何时使用
+
+- 用户说“创建一个 cli skill”
+- 用户要把一个本地 skill 接成可直接执行的 CLI
+- 用户要安装或卸载一个已发布的 cli skill
+- 用户要查看或修改 `~/.cli-skill/config.json`
+- 用户要更新某个 skill 的 `SKILL.md` 中的 Tool / Config 文档区块
+
+## 默认流程
+
+如果用户要新建一个 skill，默认按下面顺序执行：
+
+```bash
+cli-skill create <skill-name> --cli-name <cli-name>
+bun install
+cli-skill enable <skill-name>
+cli-skill sync-skill --write
+```
+
+如果用户没有指定 `cli-name`，默认令它等于 `skill-name`。
+
+## 命令对照
+
+| 场景 | 命令 |
+| --- | --- |
+| 创建 skill | `cli-skill create <skill-name> --cli-name <cli-name> [--template <templateName>]` |
+| 激活本地 skill | `cli-skill enable <skill-name> [--agentPath <path>]` |
+| 取消激活本地 skill | `cli-skill disable <skill-name> [--agentPath <path>]` |
+| 安装已发布 skill | `cli-skill install <skill-name>` |
+| 卸载已发布 skill | `cli-skill uninstall <package-name>` |
+| 发布本地 skill | `cli-skill publish <skill-name> [--dry-run]` |
+| 查看 skill 列表 | `cli-skill list` |
+| 同步 skill 文档 | 在 skill 根目录执行 `cli-skill sync-skill --write` |
+| 读取配置 | `cli-skill config get [keyPath]` |
+| 写入配置 | `cli-skill config set <keyPath> <value>` |
+
+## 关键规则
+
+- `create` 会通过 `bunx` 调 templates 包创建 skill 项目。
+- 默认模板名是 `basic`，对应 templates 包里的内置基础模板。
+- `create` 只创建项目，不会自动执行 `bun install`，也不会自动注册 CLI。
+- `enable` 只做两件事：
+  - 把目标 skill 的 bin 接到 Bun 全局 bin
+  - 把目标 skill 的 `./skill` 注册到目标 skill 目录，默认是 `~/.agents/skills/<skill-name>`
+- `enable` / `disable` 都通过 `skill-name` 到 `~/.cli-skill/skills/<skill-name>` 查找本地 skill 项目
+- `install` / `uninstall` 面向已发布或已打包的 skill：
+  - `install` 会把 skill 安装到 `~/.cli-skill/installed`
+  - 同时把 bin 接到 Bun 全局 bin
+  - 同时把 `skill/` 注册到目标 skill 目录，默认是 `~/.agents/skills/<skill-name>`
+- `install <skill-name>` 会先按 skill 名去 npm search API 查找：
+  - 搜索条件包含 `cli-skill` 和 `<skill-name>`
+  - 只有唯一命中时才会安装
+- `install <skill-name> --packageName <package-name>` 会直接按显式包名安装
+- `i` 是 `install` 的简写
+- `publish <skill-name>` 会从 `~/.cli-skill/skills/<skill-name>` 找到本地 skill 项目，并执行 `bun publish`
+- skill 项目默认创建在：
+  - `~/.cli-skill/skills/<skill-name>`
+- 托管安装的 skill 默认放在：
+  - `~/.cli-skill/installed`
+- agent 读取 skill 的目录默认是：
+  - `~/.agents/skills/<skill-name>`
+- 包名可以带 `cli-skill-` 前缀，但 agent 使用的 skill 名不带这个前缀。
+- 如果用户只是要修改某个已有 skill，不要重新 `create`，直接进入现有 skill 目录工作。
+
+## 配置规则
+
+- 全局配置文件是：
+  - `~/.cli-skill/config.json`
+- 通过下面命令读写：
+
+```bash
+cli-skill config get
+cli-skill config get skillConfig.fx
+cli-skill config set skillConfig.fx.baseUrl https://example.com
+```
+
+- `get` / `set` 支持点路径，如：
+  - `skillConfig.fx.baseUrl`
+  - `skillConfig.fx.env.TEST_VALUE`
+
+## 文档同步规则
+
+- skill 的 `SKILL.md` 里，`Tool Reference` 和 `Config Reference` 应由平台命令生成。
+- 当工具或配置发生变化后，优先执行：
+
+```bash
+cli-skill sync-skill --write
+```
+
+- 不要手写维护这两个生成区块，除非用户明确要求。
+
+## 不要做的事
+
+- 不要把 `create` 当成“已经可执行”
+- 不要让 `enable` 隐式执行 `install`
+- 不要手动改 `~/.agents/skills`，优先通过 `cli-skill` CLI 管理
+- 不要把测试 skill 长期留在工作区；测试时统一使用 `test-skill-1`、`test-skill-2` 这类名字

package/skill/agents/openai.yaml

@@ -0,0 +1,3 @@
+display_name: Browser Skill
+short_description: 创建、接通和安装 cli skill 的操作说明
+default_prompt: 使用 $cli-skill 帮我创建、注册或安装一个 cli skill。

package/src/app.ts

@@ -0,0 +1,28 @@
+import { cac } from "cac";
+import { registerConfigCommand } from "./commands/config";
+import { registerCreateCommand } from "./commands/create";
+import { registerDisableCommand } from "./commands/disable";
+import { registerSyncSkillCommand } from "./commands/docs";
+import { registerEnableCommand } from "./commands/enable";
+import { registerInstallCommand } from "./commands/install";
+import { registerListCommand } from "./commands/list";
+import { registerPublishCommand } from "./commands/publish";
+import { registerUninstallCommand } from "./commands/uninstall";
+
+export function createApp() {
+  const cli = cac("cli-skill");
+
+  registerCreateCommand(cli);
+  registerConfigCommand(cli);
+  registerSyncSkillCommand(cli);
+  registerListCommand(cli);
+  registerEnableCommand(cli);
+  registerDisableCommand(cli);
+  registerInstallCommand(cli);
+  registerUninstallCommand(cli);
+  registerPublishCommand(cli);
+
+  cli.help();
+  cli.version("0.1.0");
+  return cli;
+}

package/src/bun.ts

@@ -0,0 +1,51 @@
+import { execFile } from "node:child_process";
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+export async function runBun(
+  args: string[],
+  cwd?: string,
+  envOverrides?: Record<string, string | undefined>,
+): Promise<void> {
+  await execFileAsync("bun", args, {
+    cwd,
+    env: {
+      ...process.env,
+      ...envOverrides,
+    },
+  });
+}
+
+export async function runBunx(args: string[], cwd?: string): Promise<string> {
+  const { stdout } = await execFileAsync("bunx", args, {
+    cwd,
+    env: process.env,
+  });
+  return stdout.trim();
+}
+
+export async function runBunAndCapture(args: string[], cwd?: string): Promise<string> {
+  const { stdout } = await execFileAsync("bun", args, {
+    cwd,
+    env: process.env,
+  });
+  return stdout.trim();
+}
+
+export async function getBunGlobalBinDir(): Promise<string> {
+  return runBunAndCapture(["pm", "bin", "-g"]);
+}
+
+export async function installPackageToDirectory(packageSpec: string, installDir: string): Promise<void> {
+  await rm(installDir, { recursive: true, force: true });
+  await mkdir(installDir, { recursive: true });
+  await writeFile(
+    path.join(installDir, "package.json"),
+    `${JSON.stringify({ name: "cli-skill-managed-install", private: true }, null, 2)}\n`,
+    "utf8",
+  );
+  await runBun(["add", packageSpec], installDir);
+}

package/src/commands/config.ts

@@ -0,0 +1,53 @@
+import type { CAC } from "cac";
+import {
+  getBrowserSkillConfigPath,
+  getConfigValue,
+  loadBrowserSkillCliConfig,
+  parseConfigCliValue,
+  saveBrowserSkillCliConfig,
+  setConfigValue,
+} from "../config";
+
+function printConfigValue(value: unknown): void {
+  if (typeof value === "string") {
+    console.log(value);
+    return;
+  }
+
+  if (typeof value === "undefined") {
+    console.log("undefined");
+    return;
+  }
+
+  console.log(JSON.stringify(value, null, 2));
+}
+
+export function registerConfigCommand(cli: CAC): void {
+  cli
+    .command("config [...args]", "Manage cli-skill config")
+    .usage("config get [keyPath]\n  cli-skill config set <keyPath> <value>")
+    .action(async (args: string[] = []) => {
+      const [subcommand, keyPath, rawValue] = args;
+
+      if (subcommand === "get") {
+        const currentConfig = await loadBrowserSkillCliConfig();
+        const value = getConfigValue(currentConfig, keyPath);
+        printConfigValue(value);
+        return;
+      }
+
+      if (subcommand === "set") {
+        if (!keyPath || typeof rawValue === "undefined") {
+          throw new Error("Usage: cli-skill config set <keyPath> <value>");
+        }
+
+        const currentConfig = await loadBrowserSkillCliConfig();
+        const nextConfig = setConfigValue(currentConfig, keyPath, parseConfigCliValue(rawValue));
+        await saveBrowserSkillCliConfig(nextConfig);
+        console.log(getBrowserSkillConfigPath());
+        return;
+      }
+
+      throw new Error("Usage: cli-skill config get [keyPath] | cli-skill config set <keyPath> <value>");
+    });
+}

package/src/commands/create.ts

@@ -0,0 +1,25 @@
+import type { CAC } from "cac";
+import { DEFAULT_TEMPLATE_NAME } from "../constants";
+import { createSkillProject } from "../project";
+
+function resolveTemplateName(templateOption?: string): string {
+  return templateOption ?? DEFAULT_TEMPLATE_NAME;
+}
+
+export function registerCreateCommand(cli: CAC): void {
+  cli
+    .command("create <skillName>", "Create a cli skill project")
+    .option("--cli-name <cliName>", "Override the generated CLI name")
+    .option(
+      "--template <templateName>",
+      `Template name. Defaults to ${DEFAULT_TEMPLATE_NAME}`,
+    )
+    .action(async (skillName: string, options: { cliName?: string; template?: string }) => {
+      const targetDir = await createSkillProject(
+        skillName,
+        options.cliName ?? skillName,
+        resolveTemplateName(options.template),
+      );
+      console.log(targetDir);
+    });
+}

package/src/commands/disable.ts

@@ -0,0 +1,13 @@
+import type { CAC } from "cac";
+import { getLocalSkillProjectDir, removeLocalSkill } from "../registry";
+
+export function registerDisableCommand(cli: CAC): void {
+  cli
+    .command("disable <skillName>", "Disable a local skill")
+    .option("--agentPath <agentPath>", "Override the target agent skill directory")
+    .action(async (skillName: string, options: { agentPath?: string }) => {
+      const projectDir = await getLocalSkillProjectDir(skillName);
+      const targetPath = await removeLocalSkill(projectDir, { skillRoot: options.agentPath });
+      console.log(targetPath);
+    });
+}

package/src/commands/docs.ts

@@ -0,0 +1,22 @@
+import type { CAC } from "cac";
+import { renderSkillDocsMarkdown, writeSkillDocsMarkdown } from "@cli-skill/core";
+import { ensureValidSkillProject, loadSkillDefinition } from "../project";
+
+export function registerSyncSkillCommand(cli: CAC): void {
+  cli
+    .command("sync-skill", "Generate Tool / Config sections for the current skill")
+    .option("--write", "Write generated sections back into skill/SKILL.md")
+    .action(async (options: { write?: boolean }) => {
+      const projectDir = process.cwd();
+      await ensureValidSkillProject(projectDir);
+      const skill = await loadSkillDefinition(projectDir);
+
+      if (options.write) {
+        const updatedPath = await writeSkillDocsMarkdown(skill);
+        console.log(updatedPath);
+        return;
+      }
+
+      console.log(renderSkillDocsMarkdown(skill));
+    });
+}

package/src/commands/enable.ts

@@ -0,0 +1,13 @@
+import type { CAC } from "cac";
+import { getLocalSkillProjectDir, setupLocalSkill } from "../registry";
+
+export function registerEnableCommand(cli: CAC): void {
+  cli
+    .command("enable <skillName>", "Enable a local skill for use")
+    .option("--agentPath <agentPath>", "Override the target agent skill directory")
+    .action(async (skillName: string, options: { agentPath?: string }) => {
+      const projectDir = await getLocalSkillProjectDir(skillName);
+      const targetPath = await setupLocalSkill(projectDir, { skillRoot: options.agentPath });
+      console.log(targetPath);
+    });
+}

package/src/commands/install.ts

@@ -0,0 +1,120 @@
+import type { CAC } from "cac";
+import https from "node:https";
+import path from "node:path";
+import { installPackageToDirectory } from "../bun";
+import { getInstalledSkillsRoot } from "../constants";
+import { installManagedSkill } from "../registry";
+
+interface SearchResultPackage {
+  name: string;
+  keywords?: string[];
+}
+
+interface SearchResultObject {
+  package: SearchResultPackage;
+}
+
+interface NpmSearchResponse {
+  objects?: SearchResultObject[];
+}
+
+function fetchJson<T>(url: string): Promise<T> {
+  return new Promise((resolve, reject) => {
+    https
+      .get(url, (response) => {
+        const statusCode = response.statusCode ?? 500;
+        if (statusCode < 200 || statusCode >= 300) {
+          reject(new Error(`Request failed with status ${statusCode}`));
+          response.resume();
+          return;
+        }
+
+        let raw = "";
+        response.setEncoding("utf8");
+        response.on("data", (chunk) => {
+          raw += chunk;
+        });
+        response.on("end", () => {
+          try {
+            resolve(JSON.parse(raw) as T);
+          } catch (error) {
+            reject(error);
+          }
+        });
+      })
+      .on("error", reject);
+  });
+}
+
+async function searchSkillPackages(skillName: string): Promise<SearchResultPackage[]> {
+  const params = new URLSearchParams({
+    text: `keywords:cli-skill ${skillName}`,
+    size: "20",
+    from: "0",
+    quality: "0.65",
+    popularity: "0.5",
+    maintenance: "0.5",
+  });
+
+  const response = await fetchJson<NpmSearchResponse>(
+    `https://registry.npmjs.org/-/v1/search?${params.toString()}`,
+  );
+
+  return (response.objects ?? [])
+    .map((entry) => entry.package)
+    .filter((pkg) => {
+      const keywords = new Set(pkg.keywords ?? []);
+      return keywords.has("cli-skill") && keywords.has(skillName);
+    });
+}
+
+async function resolveInstallTarget(
+  skillName: string,
+  explicitPackageName?: string,
+): Promise<{ packageSpec: string; packageName: string }> {
+  if (explicitPackageName) {
+    return { packageSpec: explicitPackageName, packageName: explicitPackageName };
+  }
+
+  const matchedPackages = await searchSkillPackages(skillName);
+  if (matchedPackages.length === 1) {
+    const [pkg] = matchedPackages;
+    return { packageSpec: pkg.name, packageName: pkg.name };
+  }
+
+  if (matchedPackages.length > 1) {
+    const names = matchedPackages.map((pkg) => pkg.name).join(", ");
+    throw new Error(`Multiple skill packages matched "${skillName}": ${names}`);
+  }
+
+  throw new Error(
+    `No cli skill package matched "${skillName}". Publish a package with keywords "cli-skill" and "${skillName}", or install by explicit package name via --packageName.`,
+  );
+}
+
+export function registerInstallCommand(cli: CAC): void {
+  cli
+    .command("install <skillName>", "Install a cli skill into cli-skill managed storage")
+    .alias("i")
+    .option("--packageName <packageName>", "Install directly by explicit package name")
+    .option("--package-name <packageName>", "Install directly by explicit package name")
+    .option("--skill-root <skillRoot>", "Override the target skill registration directory")
+    .action(
+      async (
+        skillName: string,
+        options: { packageName?: string; "package-name"?: string; skillRoot?: string },
+      ) => {
+        const explicitPackageName = options.packageName ?? options["package-name"];
+        const { packageSpec, packageName } = await resolveInstallTarget(skillName, explicitPackageName);
+
+        const installedSkillsRoot = await getInstalledSkillsRoot();
+        const installDir = path.join(installedSkillsRoot, packageName.replaceAll("/", "__"));
+        await installPackageToDirectory(packageSpec, installDir);
+        const packageDir = path.join(installDir, "node_modules", packageName);
+        const targetPath = await installManagedSkill(packageName, packageSpec, packageDir, {
+          skillRoot: options.skillRoot,
+        });
+        console.log(targetPath);
+      },
+    );
+}

package/src/commands/list.ts

@@ -0,0 +1,76 @@
+import type { CAC } from "cac";
+import os from "node:os";
+import { listBrowserSkills } from "../registry";
+
+function pad(value: string, width: number): string {
+  return value.padEnd(width, " ");
+}
+
+function formatPath(value: string): string {
+  const home = os.homedir();
+  if (value === home) {
+    return "~";
+  }
+
+  if (value.startsWith(`${home}/`)) {
+    return `~/${value.slice(home.length + 1)}`;
+  }
+
+  return value;
+}
+
+export function registerListCommand(cli: CAC): void {
+  cli.command("list", "List local and installed cli skills").action(async () => {
+    const skills = await listBrowserSkills();
+    if (skills.length === 0) {
+      console.log("无");
+      return;
+    }
+
+    const rows = skills.map((skill) => ({
+      skillName: skill.skillName,
+      source: skill.source === "local" ? "local" : "remote",
+      packageName: skill.packageName,
+      active: skill.active ? "yes" : "no",
+      agentPaths: `[${skill.agentPaths.map((agentPath) => formatPath(agentPath)).join(", ")}]`,
+    }));
+
+    const headers = {
+      skillName: "Skill",
+      source: "Source",
+      packageName: "Package",
+      active: "Active",
+      agentPaths: "AgentPaths",
+    };
+
+    const widths = {
+      skillName: Math.max(headers.skillName.length, ...rows.map((row) => row.skillName.length)),
+      source: Math.max(headers.source.length, ...rows.map((row) => row.source.length)),
+      packageName: Math.max(headers.packageName.length, ...rows.map((row) => row.packageName.length)),
+      active: Math.max(headers.active.length, ...rows.map((row) => row.active.length)),
+      agentPaths: Math.max(headers.agentPaths.length, ...rows.map((row) => row.agentPaths.length)),
+    };
+
+    console.log(
+      [
+        pad(headers.skillName, widths.skillName),
+        pad(headers.source, widths.source),
+        pad(headers.packageName, widths.packageName),
+        pad(headers.active, widths.active),
+        headers.agentPaths,
+      ].join("  "),
+    );
+
+    for (const row of rows) {
+      console.log(
+        [
+          pad(row.skillName, widths.skillName),
+          pad(row.source, widths.source),
+          pad(row.packageName, widths.packageName),
+          pad(row.active, widths.active),
+          row.agentPaths,
+        ].join("  "),
+      );
+    }
+  });
+}

package/src/commands/publish.ts

@@ -0,0 +1,24 @@
+import type { CAC } from "cac";
+import { runBun } from "../bun";
+import { getLocalSkillProjectDir } from "../registry";
+
+export function registerPublishCommand(cli: CAC): void {
+  cli
+    .command("publish <skillName>", "Publish a local skill package")
+    .option("--dry-run", "Run publish in dry-run mode")
+    .option("--tag <tag>", "Publish under the given dist-tag")
+    .action(async (skillName: string, options: { dryRun?: boolean; tag?: string }) => {
+      const projectDir = await getLocalSkillProjectDir(skillName);
+      const args = ["publish"];
+
+      if (options.dryRun) {
+        args.push("--dry-run");
+      }
+
+      if (options.tag) {
+        args.push("--tag", options.tag);
+      }
+
+      await runBun(args, projectDir);
+    });
+}

package/src/commands/uninstall.ts

@@ -0,0 +1,12 @@
+import type { CAC } from "cac";
+import { removeManagedSkill } from "../registry";
+
+export function registerUninstallCommand(cli: CAC): void {
+  cli
+    .command("uninstall <packageName>", "Uninstall a managed cli skill")
+    .option("--skill-root <skillRoot>", "Override the target skill registration directory")
+    .action(async (packageName: string, options: { skillRoot?: string }) => {
+      const targetPath = await removeManagedSkill(packageName, { skillRoot: options.skillRoot });
+      console.log(targetPath);
+    });
+}

package/src/config.ts

@@ -0,0 +1,150 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import get from "lodash/get";
+import set from "lodash/set";
+import os from "node:os";
+import path from "node:path";
+
+export interface BrowserSkillCliConfig {
+  skillsRoot?: string;
+  installedSkillsRoot?: string;
+  agentsSkillsRoot?: string;
+  skillConfig?: Record<string, Record<string, unknown>>;
+}
+
+function resolveUserPath(inputPath: string): string {
+  if (inputPath === "~") {
+    return os.homedir();
+  }
+
+  if (inputPath.startsWith("~/")) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+
+  return inputPath;
+}
+
+export function getBrowserSkillHome(): string {
+  return path.join(os.homedir(), ".cli-skill");
+}
+
+export function getBrowserSkillConfigPath(): string {
+  return path.join(getBrowserSkillHome(), "config.json");
+}
+
+export async function loadBrowserSkillCliConfig(): Promise<BrowserSkillCliConfig> {
+  try {
+    const raw = await readFile(getBrowserSkillConfigPath(), "utf8");
+    return (JSON.parse(raw) as BrowserSkillCliConfig) ?? {};
+  } catch {
+    return {};
+  }
+}
+
+export function getDefaultBrowserSkillCliConfig(): Required<
+  Pick<BrowserSkillCliConfig, "skillsRoot" | "installedSkillsRoot" | "agentsSkillsRoot" | "skillConfig">
+> {
+  return {
+    skillsRoot: path.join(getBrowserSkillHome(), "skills"),
+    installedSkillsRoot: path.join(getBrowserSkillHome(), "installed"),
+    agentsSkillsRoot: path.join(os.homedir(), ".agents", "skills"),
+    skillConfig: {},
+  };
+}
+
+export async function getResolvedBrowserSkillCliConfig(): Promise<
+  Required<Pick<BrowserSkillCliConfig, "skillsRoot" | "installedSkillsRoot" | "agentsSkillsRoot">> &
+    BrowserSkillCliConfig
+> {
+  const config = await loadBrowserSkillCliConfig();
+  const defaults = getDefaultBrowserSkillCliConfig();
+
+  return {
+    ...config,
+    skillConfig: config.skillConfig ?? defaults.skillConfig,
+    skillsRoot: resolveUserPath(config.skillsRoot ?? defaults.skillsRoot),
+    installedSkillsRoot: resolveUserPath(config.installedSkillsRoot ?? defaults.installedSkillsRoot),
+    agentsSkillsRoot: resolveUserPath(config.agentsSkillsRoot ?? defaults.agentsSkillsRoot),
+  };
+}
+
+export async function ensureBrowserSkillCliConfig(): Promise<string> {
+  const configPath = getBrowserSkillConfigPath();
+  const defaults = getDefaultBrowserSkillCliConfig();
+
+  try {
+    const raw = await readFile(configPath, "utf8");
+    const parsed = (JSON.parse(raw) as BrowserSkillCliConfig) ?? {};
+    const nextConfig: BrowserSkillCliConfig = {
+      ...parsed,
+      skillsRoot: parsed.skillsRoot ?? defaults.skillsRoot,
+      installedSkillsRoot: parsed.installedSkillsRoot ?? defaults.installedSkillsRoot,
+      agentsSkillsRoot: parsed.agentsSkillsRoot ?? defaults.agentsSkillsRoot,
+      skillConfig: parsed.skillConfig ?? defaults.skillConfig,
+    };
+
+    if (JSON.stringify(parsed) !== JSON.stringify(nextConfig)) {
+      await saveBrowserSkillCliConfig(nextConfig);
+    }
+
+    return configPath;
+  } catch {
+    await saveBrowserSkillCliConfig(defaults);
+    return configPath;
+  }
+}
+
+export async function saveBrowserSkillCliConfig(config: BrowserSkillCliConfig): Promise<void> {
+  const configPath = getBrowserSkillConfigPath();
+  await mkdir(path.dirname(configPath), { recursive: true });
+  await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}
+
+export function getConfigValue(config: BrowserSkillCliConfig, keyPath?: string): unknown {
+  if (!keyPath) {
+    return config;
+  }
+
+  return get(config, keyPath);
+}
+
+export function setConfigValue(
+  config: BrowserSkillCliConfig,
+  keyPath: string,
+  value: unknown,
+): BrowserSkillCliConfig {
+  const nextConfig = structuredClone(config);
+  set(nextConfig as object, keyPath, value);
+  return nextConfig;
+}
+
+export function parseConfigCliValue(rawValue: string): unknown {
+  if (rawValue === "true") {
+    return true;
+  }
+
+  if (rawValue === "false") {
+    return false;
+  }
+
+  if (rawValue === "null") {
+    return null;
+  }
+
+  if (/^-?\d+(\.\d+)?$/.test(rawValue)) {
+    return Number(rawValue);
+  }
+
+  if (
+    (rawValue.startsWith("{") && rawValue.endsWith("}")) ||
+    (rawValue.startsWith("[") && rawValue.endsWith("]")) ||
+    (rawValue.startsWith("\"") && rawValue.endsWith("\""))
+  ) {
+    try {
+      return JSON.parse(rawValue);
+    } catch {
+      return rawValue;
+    }
+  }
+
+  return rawValue;
+}

package/src/constants.ts

@@ -0,0 +1,21 @@
+import path from "node:path";
+import { getResolvedBrowserSkillCliConfig } from "./config";
+
+export const LOCAL_CORE_PACKAGE_PATH = path.resolve(import.meta.dirname, "../../core");
+export const LOCAL_TEMPLATE_PACKAGE_PATH = path.resolve(import.meta.dirname, "../../templates");
+export const DEFAULT_TEMPLATE_NAME = "basic";
+
+export async function getDefaultSkillsRoot(): Promise<string> {
+  const config = await getResolvedBrowserSkillCliConfig();
+  return config.skillsRoot;
+}
+
+export async function getInstalledSkillsRoot(): Promise<string> {
+  const config = await getResolvedBrowserSkillCliConfig();
+  return config.installedSkillsRoot;
+}
+
+export async function getAgentsSkillsRoot(): Promise<string> {
+  const config = await getResolvedBrowserSkillCliConfig();
+  return config.agentsSkillsRoot;
+}

package/src/index.ts

@@ -0,0 +1,15 @@
+import { createApp } from "./app";
+import { ensureBrowserSkillCliConfig } from "./config";
+export { createSkillProject } from "./project";
+
+async function main(argv = process.argv.slice(2)): Promise<void> {
+  await ensureBrowserSkillCliConfig();
+  const cli = createApp();
+  cli.parse(["node", "cli-skill", ...argv], { run: false });
+  await cli.runMatchedCommand();
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});

package/src/project.ts

@@ -0,0 +1,133 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { SkillDefinition } from "@cli-skill/core";
+import {
+  DEFAULT_TEMPLATE_NAME,
+  LOCAL_CORE_PACKAGE_PATH,
+  LOCAL_TEMPLATE_PACKAGE_PATH,
+  getDefaultSkillsRoot,
+} from "./constants";
+import { runBunx } from "./bun";
+
+export interface SkillPackageJson {
+  name?: string;
+  bin?: string | Record<string, string>;
+  cliSkill?: boolean | Record<string, unknown>;
+  version?: string;
+}
+
+async function getLocalCorePackageVersion(): Promise<string> {
+  const corePackageJsonPath = path.join(LOCAL_CORE_PACKAGE_PATH, "package.json");
+  const corePackageJson = JSON.parse(
+    await readFile(corePackageJsonPath, "utf8"),
+  ) as SkillPackageJson;
+
+  if (typeof corePackageJson.version !== "string" || corePackageJson.version.length === 0) {
+    throw new Error(`Missing version in ${corePackageJsonPath}`);
+  }
+
+  return corePackageJson.version;
+}
+
+export async function createSkillProject(
+  skillName: string,
+  cliName = skillName,
+  templateName = DEFAULT_TEMPLATE_NAME,
+  targetRoot?: string,
+): Promise<string> {
+  const resolvedTargetRoot = targetRoot ?? (await getDefaultSkillsRoot());
+  const targetDir = path.join(resolvedTargetRoot, skillName);
+  const corePackageVersion = await getLocalCorePackageVersion();
+  await runBunx(
+    [
+      "--bun",
+      "--package",
+      `file:${LOCAL_TEMPLATE_PACKAGE_PATH}`,
+      "cli-skill-create-template",
+      "--template",
+      templateName,
+      "--skill-name",
+      skillName,
+      "--cli-name",
+      cliName,
+      "--target-dir",
+      targetDir,
+      "--core-package-version",
+      corePackageVersion,
+    ],
+    process.cwd(),
+  );
+
+  return targetDir;
+}
+
+export async function loadSkillPackageJson(projectDir: string): Promise<SkillPackageJson> {
+  const packageJsonPath = path.join(projectDir, "package.json");
+  return JSON.parse(await readFile(packageJsonPath, "utf8")) as SkillPackageJson;
+}
+
+export function getSkillNameFromPackageName(packageName: string): string {
+  const rawName = packageName.split("/").at(-1) ?? packageName;
+  return rawName.startsWith("cli-skill-")
+    ? rawName.slice("cli-skill-".length)
+    : rawName;
+}
+
+export async function ensureValidSkillProject(
+  projectDir: string,
+): Promise<{ packageName: string; skillName: string; bins: Record<string, string> }> {
+  const packageJson = await loadSkillPackageJson(projectDir);
+  if (!packageJson.cliSkill) {
+    throw new Error(`Missing cliSkill field in ${path.join(projectDir, "package.json")}`);
+  }
+
+  if (typeof packageJson.name !== "string" || packageJson.name.length === 0) {
+    throw new Error(`Missing package name in ${path.join(projectDir, "package.json")}`);
+  }
+
+  const skillFilePath = path.join(projectDir, "skill", "SKILL.md");
+  await readFile(skillFilePath, "utf8");
+
+  const bins =
+    typeof packageJson.bin === "string"
+      ? { [getSkillNameFromPackageName(packageJson.name)]: packageJson.bin }
+      : packageJson.bin && typeof packageJson.bin === "object"
+        ? packageJson.bin
+        : null;
+
+  if (!bins || Object.keys(bins).length === 0) {
+    throw new Error(`Missing bin field in ${path.join(projectDir, "package.json")}`);
+  }
+
+  return {
+    packageName: packageJson.name,
+    skillName: getSkillNameFromPackageName(packageJson.name),
+    bins,
+  };
+}
+
+export async function loadSkillDefinition(projectDir: string): Promise<SkillDefinition> {
+  await ensureValidSkillProject(projectDir);
+  const entryPath = path.join(projectDir, "src", "index.ts");
+  const previousCwd = process.cwd();
+
+  try {
+    process.chdir(projectDir);
+    const imported = await import(pathToFileURL(entryPath).href);
+    const skill = (imported.default ?? imported.skill) as SkillDefinition | undefined;
+
+    if (!skill) {
+      throw new Error(`Cannot find exported skill definition in ${entryPath}`);
+    }
+
+    return skill.rootDir
+      ? skill
+      : {
+          ...skill,
+          rootDir: projectDir,
+        };
+  } finally {
+    process.chdir(previousCwd);
+  }
+}

package/src/registry.ts

@@ -0,0 +1,219 @@
+import { mkdir, readdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { getAgentsSkillsRoot, getDefaultSkillsRoot, getInstalledSkillsRoot } from "./constants";
+import { ensureValidSkillProject, getSkillNameFromPackageName, type SkillPackageJson } from "./project";
+import { getBunGlobalBinDir } from "./bun";
+
+interface SetupOptions {
+  skillRoot?: string;
+}
+
+interface RegisteredSkillInfo {
+  skillName: string;
+  packageName: string;
+  sourcePath: string;
+  skillPath: string;
+  binNames: string[];
+}
+
+interface InstalledSkillMetadata {
+  packageName: string;
+  packageSpec: string;
+}
+
+function installedPackageDirName(packageName: string): string {
+  return packageName.replaceAll("/", "__");
+}
+
+async function ensureSymlink(sourcePath: string, targetPath: string, type: "file" | "dir"): Promise<void> {
+  await rm(targetPath, { recursive: true, force: true });
+  await symlink(sourcePath, targetPath, type);
+}
+
+async function loadPackageJson(packageDir: string): Promise<SkillPackageJson> {
+  return JSON.parse(await readFile(path.join(packageDir, "package.json"), "utf8")) as SkillPackageJson;
+}
+
+function resolveBinEntries(
+  packageName: string,
+  bin: SkillPackageJson["bin"],
+): Record<string, string> {
+  if (typeof bin === "string") {
+    return { [getSkillNameFromPackageName(packageName)]: bin };
+  }
+
+  if (bin && typeof bin === "object") {
+    return bin;
+  }
+
+  return {};
+}
+
+async function setupBins(sourceDir: string, bins: Record<string, string>): Promise<string[]> {
+  const globalBinDir = await getBunGlobalBinDir();
+  await mkdir(globalBinDir, { recursive: true });
+
+  const installedBinNames: string[] = [];
+
+  for (const [binName, relativeBinPath] of Object.entries(bins)) {
+    const sourcePath = path.resolve(sourceDir, relativeBinPath);
+    const targetPath = path.join(globalBinDir, binName);
+    await ensureSymlink(sourcePath, targetPath, "file");
+    installedBinNames.push(binName);
+  }
+
+  return installedBinNames;
+}
+
+async function removeBins(binNames: string[]): Promise<void> {
+  const globalBinDir = await getBunGlobalBinDir();
+  for (const binName of binNames) {
+    await rm(path.join(globalBinDir, binName), { force: true });
+  }
+}
+
+export async function setupLocalSkill(projectDir: string, options: SetupOptions = {}): Promise<string> {
+  const { skillName, bins } = await ensureValidSkillProject(projectDir);
+  const agentsSkillsRoot = options.skillRoot ?? (await getAgentsSkillsRoot());
+  const targetPath = path.join(agentsSkillsRoot, skillName);
+
+  await mkdir(agentsSkillsRoot, { recursive: true });
+  await setupBins(projectDir, bins);
+  await ensureSymlink(path.join(projectDir, "skill"), targetPath, "dir");
+
+  return targetPath;
+}
+
+export async function removeLocalSkill(projectDir: string, options: SetupOptions = {}): Promise<string> {
+  const { skillName, bins } = await ensureValidSkillProject(projectDir);
+  const agentsSkillsRoot = options.skillRoot ?? (await getAgentsSkillsRoot());
+  const targetPath = path.join(agentsSkillsRoot, skillName);
+
+  await removeBins(Object.keys(bins));
+  await rm(targetPath, { recursive: true, force: true });
+
+  return targetPath;
+}
+
+export async function installManagedSkill(
+  packageName: string,
+  packageSpec: string,
+  packageDir: string,
+  options: SetupOptions = {},
+): Promise<string> {
+  const packageJson = await loadPackageJson(packageDir);
+  if (!packageJson.cliSkill) {
+    throw new Error(`Missing cliSkill field in ${path.join(packageDir, "package.json")}`);
+  }
+
+  const skillName = getSkillNameFromPackageName(packageName);
+  const bins = resolveBinEntries(packageName, packageJson.bin);
+  const agentsSkillsRoot = options.skillRoot ?? (await getAgentsSkillsRoot());
+  const targetPath = path.join(agentsSkillsRoot, skillName);
+  const installedSkillsRoot = await getInstalledSkillsRoot();
+  const metadataPath = path.join(installedSkillsRoot, installedPackageDirName(packageName), ".cli-skill.json");
+
+  await mkdir(path.dirname(metadataPath), { recursive: true });
+  await writeFile(metadataPath, `${JSON.stringify({ packageName, packageSpec }, null, 2)}\n`, "utf8");
+  await mkdir(agentsSkillsRoot, { recursive: true });
+  await setupBins(packageDir, bins);
+  await ensureSymlink(path.join(packageDir, "skill"), targetPath, "dir");
+
+  return targetPath;
+}
+
+export async function removeManagedSkill(packageName: string, options: SetupOptions = {}): Promise<string> {
+  const installedSkillsRoot = await getInstalledSkillsRoot();
+  const installDir = path.join(installedSkillsRoot, installedPackageDirName(packageName));
+  const packageDir = path.join(installDir, "node_modules", packageName);
+  const packageJson = await loadPackageJson(packageDir);
+  const bins = resolveBinEntries(packageName, packageJson.bin);
+  const skillName = getSkillNameFromPackageName(packageName);
+  const agentsSkillsRoot = options.skillRoot ?? (await getAgentsSkillsRoot());
+  const targetPath = path.join(agentsSkillsRoot, skillName);
+
+  await removeBins(Object.keys(bins));
+  await rm(targetPath, { recursive: true, force: true });
+  await rm(installDir, { recursive: true, force: true });
+
+  return targetPath;
+}
+
+export async function getRegisteredAgentSkillNames(skillRoot?: string): Promise<Set<string>> {
+  const agentsSkillsRoot = skillRoot ?? (await getAgentsSkillsRoot());
+  try {
+    const names = await readdir(agentsSkillsRoot);
+    return new Set(names);
+  } catch {
+    return new Set();
+  }
+}
+
+export async function listBrowserSkills(): Promise<
+  Array<{
+    source: "local" | "remote";
+    skillName: string;
+    packageName: string;
+    projectPath: string;
+    active: boolean;
+    agentPaths: string[];
+  }>
+> {
+  const agentsSkillsRoot = await getAgentsSkillsRoot();
+  const activeSkills = await getRegisteredAgentSkillNames(agentsSkillsRoot);
+  const results: Array<{
+    source: "local" | "remote";
+    skillName: string;
+    packageName: string;
+    projectPath: string;
+    active: boolean;
+    agentPaths: string[];
+  }> = [];
+
+  const skillsRoot = await getDefaultSkillsRoot();
+  try {
+    for (const entry of await readdir(skillsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const projectDir = path.join(skillsRoot, entry.name);
+      try {
+        const { skillName, packageName } = await ensureValidSkillProject(projectDir);
+        results.push({
+          source: "local",
+          skillName,
+          packageName,
+          projectPath: projectDir,
+          active: activeSkills.has(skillName),
+          agentPaths: activeSkills.has(skillName) ? [path.join(agentsSkillsRoot, skillName)] : [],
+        });
+      } catch {}
+    }
+  } catch {}
+
+  const installedSkillsRoot = await getInstalledSkillsRoot();
+  try {
+    for (const entry of await readdir(installedSkillsRoot, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      const installDir = path.join(installedSkillsRoot, entry.name);
+      const metadataPath = path.join(installDir, ".cli-skill.json");
+      try {
+        const metadata = JSON.parse(await readFile(metadataPath, "utf8")) as InstalledSkillMetadata;
+        const skillName = getSkillNameFromPackageName(metadata.packageName);
+        results.push({
+          source: "remote",
+          skillName,
+          packageName: metadata.packageName,
+          projectPath: path.join(installDir, "node_modules", metadata.packageName),
+          active: activeSkills.has(skillName),
+          agentPaths: activeSkills.has(skillName) ? [path.join(agentsSkillsRoot, skillName)] : [],
+        });
+      } catch {}
+    }
+  } catch {}
+
+  return results.sort((a, b) => a.source.localeCompare(b.source) || a.skillName.localeCompare(b.skillName));
+}
+
+export async function getLocalSkillProjectDir(skillName: string): Promise<string> {
+  const skillsRoot = await getDefaultSkillsRoot();
+  return path.join(skillsRoot, skillName);
+}

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src"]
+}