skill-master

English | 简体中文

跨平台 Skill 生命周期管理器。它不仅能可靠地安装和管理 skill，现在还支持发现、审查、推荐、验证、组合与编排。

新增能力

• ✅ 任务到 Skill 的推荐 —— 从用户任务出发给出可解释推荐
• ✅ 静态审查 —— 安装前审查候选 skill
• ✅ 安装后验证 —— 检查 env、结构、冲突和 smoke 状态
• ✅ Skill 组合 —— 改造、融合或生成新的 skill 输出
• ✅ 结构化 JSON 接口 —— find、inspect、recommend、verify、compose、solve 均可作为机器接口使用
• ✅ Solve 工作流 —— solve 将发现、推荐、可选安装、可选验证串成一次调用
• ✅ 内建设计文档 —— 见 docs/skill-lifecycle-platform.md

特性

• ✅ 智能 .env 管理 — 三级备份策略，更新时自动合并新配置
• ✅ 平台自动检测 — 根据项目目录自动识别目标平台
• ✅ 统一目录结构 — ~/.agents/ 集中管理所有 skill 和配置
• ✅ 原子化操作 — 安装失败自动回滚，保证数据完整性
• ✅ 诊断工具 — doctor 命令快速排查配置问题

安装

npm install -g skill-master

或直接使用：

npx skill-master add <skill-source>

快速开始

发现、审查与推荐

# 查找候选 skill
skill-master find "code review"
skill-master find cli --owner vercel-labs
skill-master find "code review" --json

# 审查某个 source 或已安装 skill
skill-master inspect owner/repo
skill-master inspect my-skill --json

# 从任务出发推荐 skill
skill-master recommend "监控 deploy 状态"
skill-master recommend "监控 deploy 状态" --safe --local-first
skill-master recommend "监控 deploy 状态" --json

# 推荐并安装最佳匹配
skill-master recommend "获取最新库文档" --install

任务编排（solve）

# 发现 + 推荐
skill-master solve "search web docs"

# 输出结构化 orchestrator 结果
skill-master solve "search web docs" --json

# 一次调用完成推荐、安装和验证
skill-master solve "search web docs" --install --verify --json

安装 Skill

# 从 GitHub 安装
skill-master add https://github.com/user/skill-name

# 从本地路径安装
skill-master add ./local-skill
skill-master add ../skills/my-skill
skill-master add /absolute/path/to/my-skill

# 从包含多个 skill 的本地目录中发现或选择 skill
skill-master add ./skills --list
skill-master add ./skills --skill my-skill
skill-master add ./skills --full-depth

# 指定目标平台
skill-master add https://github.com/user/skill --agent=cursor

# 使用复制而非符号链接（Windows 推荐）
skill-master add https://github.com/user/skill --copy

# 固定到指定 commit（tree URL 或 skills 字段 ref）
skill-master add https://github.com/user/skill/tree/<40位SHA>

# 直接下载 URL：单个 SKILL.md 或 .zip/.tgz/.tar.gz 归档
skill-master add https://example.com/skill.tgz
skill-master add https://example.com/SKILL.md

# 机器可读输出（隐含 --yes；错误同样以 JSON 返回）
skill-master add owner/repo --json
skill-master add https://github.com/user/repo/releases/download/v1/skill.zip

用于本地开发和测试 skill 时：

• add 支持直接接收本地目录作为 source。
• 如果目录里包含多个 skill，可以用 --list、--skill 或 --full-depth 来发现或筛选要安装的 skill。
• 本地安装会先把 skill 复制到 canonical skill store，再链接到目标 agent 或项目。
• 修改原始本地 skill 目录后，需要重新执行一次 skill-master add <path>，更新后的内容才会重新安装。

大型 GitHub skill 合集（数百 MB）以前会在第 1 步失败：git clone --depth 1 被硬限制在 60 秒。现在 add 会先下 GitHub tarball，失败再回退 git clone，默认超时 5 分钟。可用 SKILL_MASTER_CLONE_TIMEOUT_MS 覆盖，或先本地 clone 再传路径安装。

设置了 HTTPS_PROXY/HTTP_PROXY/ALL_PROXY 时，tarball 下载会改用 curl（Node 内置 fetch 不读取这些变量），并在终端显示进度条；tarball 下载超时后会自动回退 git clone 再试一次。

直接下载 URL（.md、.zip、.tgz、.tar.gz，含 codeload.github.com tarball 与 GitHub Release 资产）无需 git 即可安装，同样走上述代理逻辑。下载体积默认上限 10 MiB，可用 SKILL_MASTER_DOWNLOAD_MAX_BYTES 覆盖；解压复用 well-known 的加固解压器（防路径穿越/符号链接/压缩炸弹）。

私有仓库

GitHub API 访问（blob 快路径）使用认证阶梯：匿名 → 显式环境变量 token（GITHUB_TOKEN/GH_TOKEN）→ gh api 子进程（execFile、无 shell）。Node 进程永远不会读取 gh CLI 存储的凭证——认证由 gh 子进程自行注入；遇到 401/404/限流后，本次进程内跳过匿名档。API 阶梯全部失败时回退认证 git clone（走你配置的 git 凭证助手）。SKILL_MASTER_GH_API=0 可关闭 gh 子进程档。

验证与组合

# 验证已安装 skill
skill-master verify my-skill
skill-master verify my-skill --json

# 组合多个 source 输出一个新 skill 目录
skill-master compose path/to/skill-a path/to/skill-b -o ./generated-skill
skill-master compose path/to/skill-a path/to/skill-b -o ./generated-skill --json

管理环境变量

# 查看所有 skill 的配置状态
skill-master env list

# 设置环境变量
skill-master env set tavily-web TAVILY_API_KEY=your_key_here

# 用编辑器打开 .env 文件
skill-master env edit tavily-web

更新和删除

# 更新 skill（自动保护 .env）
skill-master update tavily-web

# 删除 skill
skill-master remove tavily-web

# 删除 skill 并清除配置
skill-master remove tavily-web --purge

同步 npm Skills

sync 安装 node_modules 里自带 skill 的依赖包，以及 package.json skills 字段声明的技能，并随依赖保持同步；依赖消失（卸载）的 skill 会被自动清理。

# 扫描 node_modules + skills 字段并同步
skill-master sync

# 在 package.json 中声明技能依赖
{
  "skills": {
    "my-skill": "npm:some-pkg",              // 根目录带 SKILL.md 的包
    "inner": "npm:@scope/pkg/inner-skill",   // 从多 skill 包中选择一个
    "from-git": "owner/repo",                 // git 来源，安装仓库内全部 skill
    "pinned": "owner/repo#v1.2.0"             // git 来源固定到指定 ref
  }
}

# 只同步指定 skill / 跳过某些 skill
skill-master sync --include my-skill --exclude other-skill

# 同时读取 workspace 子包的 skills 字段
skill-master sync --recursive

包可以发布单个 skill（<pkg>/SKILL.md）或多个 skill（<pkg>/skills/*/SKILL.md、<pkg>/dist/skills/*/SKILL.md）。npm: 条目要求包已安装（先 npm install）；sync 可重复执行——内容哈希未变的 skill 自动跳过，git 来源用 skill-master update 刷新。

查看信息

# 列出所有已安装的 skill
skill-master list

# 查看 skill 详细信息
skill-master info tavily-web

# 检查更新
skill-master check

# 运行诊断
skill-master doctor

JSON 接口

以下命令已经支持结构化输出，适合作为上层产品或脚本的稳定接口：

skill-master find <query> --json
skill-master inspect <source|skill> --json
skill-master recommend "<task>" --json
skill-master verify <skill-name> --json
skill-master compose <source...> --json
skill-master solve "<task>" --json

字段级契约与 schema 入口：

• CLI JSON 契约说明
• recommend v1 schema
• solve v1 schema
• verify v1 schema

find、inspect、compose 已在契约文档中说明，但本轮未单独提供 schema。

推荐偏好参数

recommend 与 solve 支持偏好控制：

--safe              优先低风险候选
--local-first       提升本地和项目内候选优先级
--no-remote         过滤远程候选
--prefer-installed  优先已安装 skill

支持的平台

支持 80 个 AI 编程代理。具有项目目录标记的代理支持自动检测：

| 平台 | 检测标识 | Skills 目录 | |------|---------|------------| | Claude Code | .claude/ | .claude/skills/ | | Cursor | .cursor/ | .cursor/skills/ | | Cline | .cline/ | .cline/skills/ | | Windsurf | .windsurf/ | .windsurf/skills/ | | OpenCode | ~/.config/opencode/ | .opencode/skills/ | | Roo Code | .roo/ | .roo/skills/ | | Augment | .augment/ | .augment/skills/ | | Continue | .continue/ | .continue/skills/ | | Goose | .goose/ | .goose/skills/ | | Kode | .kode/ | .kode/skills/ | | Trae | .trae/ | .trae/skills/ | | Kimi Code | .kimi-code/ | .kimi-code/skills/ | | MiniMax Code | .minimax/ | .minimax/skills/ |

Amp, Antigravity, Augment, Claude Code, OpenClaw, Cline, CodeBuddy, Codex, Command Code, Continue, Crush, Cursor, Droid, Gemini CLI, GitHub Copilot, Goose, Junie, iFlow CLI, Kilo Code, Kimi Code, Kimi Code CLI, Kiro CLI, Kode, Kukuai, MCPJam, MiniMax Code, Mirasim, Mistral Vibe, Mux, OpenCode, OpenHands, Pi, Qoder, Qwen Code, Replit, Roo Code, Trae, Trae CN, Windsurf, WorkBuddy, Zencoder, Neovate, Pochi, AdaL, AiderDesk, Antigravity CLI, AstrBot, Autohand Code CLI, CodeArts Agent, Codemaker, Code Studio, Devin for Terminal, Dexto, ForgeCode, fx, Grok Build, Hermes Agent, inference.sh, Jazz, Kimchi, Lingma, Loaf, Moxby, Ona, Posit Assistant, Qoder CN, Reasonix, Rovo Dev, Sarvam Code, Tabnine CLI, Terramind, Tinycloud, Zed, ZCode

命令别名

兼容 npx skills 命令：

skill-master add       # 或: a, install, i
skill-master remove    # 或: rm, r
skill-master list      # 或: ls
skill-master find      # 或: search, f, s
skill-master update    # 或: upgrade

开发

详见 CLAUDE.md 获取架构细节、开发命令和发布流程。

设计文档

完整平台设计见 docs/skill-lifecycle-platform.md。

与 npx skills 的对比

| 特性 | npx skills | skill-master | |------|-----------|---------------| | .env 保护 | ❌ 每次更新被删除 | ✅ 自动备份恢复 | | 跨平台支持 | ❌ 仅 Claude Code | ✅ 80 个平台 | | 配置管理 | ❌ 无 | ✅ env 子命令 | | 诊断工具 | ❌ 无 | ✅ doctor 命令 | | 发现与推荐 | ❌ 很弱 | ✅ 多源发现 + recommend | | 安装后验证 | ❌ 无 | ✅ verify 命令 | | 组合生成 | ❌ 无 | ✅ compose 命令 | | 工作流编排 | ❌ 无 | ✅ solve 命令 | | 结构化 JSON API | ❌ 无 | ✅ 核心生命周期命令支持 --json | | 符号链接 | ✅ | ✅ + 复制模式 | | Git 安装 | ✅ | ✅ | | 本地安装 | ✅ | ✅ |

常见问题

Q: 为什么需要 skill-master？

A: npx skills add 在安装/更新时会执行 rm -rf，导致 .env 文件被删除，用户每次更新后需要重新配置 API Key。skill-master 通过智能备份机制彻底解决这个问题，现在还能帮助用户做选择、验证和编排。

Q: 可以和 npx skills 共存吗？

A: 可以。skill-master 使用独立的 ~/.agents/ 目录，不会影响现有的 skill 安装。

Q: Windows 上符号链接失败怎么办？

A: 使用 --copy 参数：skill-master add <source> --copy

Q: 如何迁移现有的 skill？

A: 直接用 skill-master 重新安装即可，它会自动检测并保留现有的 .env 配置。

许可证

MIT

作者

BenedictKing

贡献

欢迎提交 Issue 和 Pull Request！