Communitygithub.com

xFurti/skillctl

通用 Agent 技能包管理器 CLI —— 管理清单、锁定文件,支持多智能体同步(Cursor、Claude、Codex、Gemini)。需要 Node ≥22.13。

skillctl 是什么?

skillctl 是一个通用的 Agent 技能包管理工具,专为 AI 编程助手(如 Cursor、Claude Code、Codex 和 Gemini)设计。它通过统一的命令行接口,帮助开发者管理多智能体协作环境中的技能包依赖。核心功能包括:使用 manifest 文件声明依赖、lock 文件锁定版本、支持多种 specifier 格式(本地文件、GitHub 仓库、npm 包等)、自动为不同 agent 创建符号链接。工具遵循“一个规范存储”原则,所有技能存放在 `~/.skillctl/skills/` 目录下,通过 `sync` 命令保证各 agent 使用相同版本。提供 `doctor` 和 `audit` 命令验证环境一致性,支持团队级可复现构建(通过 `--frozen` 参数)。特别适合需要同时使用多个 AI 编程工具并保持技能包版本一致的高级开发者。

兼容平台✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode
npx skills add xFurti/skillctl

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

skillctl 是做什么的?

使用 skillctl CLI 管理 Agent 技能的操作手册。请运行真实命令;不要模拟输出或手动将 SKILL.md 文件复制到 agent 目录之间。

黄金规则

  1. 一个规范存储 — 技能存放在 ~/.skillctl/skills/<name>/ 下;agent 通过 sync 获得符号链接。
  2. 提交 manifest + lock — 将 agent-skills.json 和 agent-skills.lock 纳入版本控制,确保团队可重现。
  3. 仅使用可移植描述符 — 使用 file:./<path>、local:imported/<name>、github:、npm: 或 skills.sh/;切勿提交绝对的家目录路径。
  4. 先安装后同步 — install 在存储中物化技能;sync 仅重新链接 agent。
  5. 变更后验证 — 运行 skillctl doctor(以及在 CI 中运行 skillctl audit)。
  6. 优先导入而非手动复制 — 使用 import from-project 或 import from-npx,而不是复制技能文件夹。

决策树

情境命令
新项目,无 manifestskillctl init 或 skillctl init --with-skill
添加远程或本地技能skillctl add <描述符> 然后 skillctl install
技能已存在于 .claude/skills、.codex/skills 等skillctl import from-project
从 npx skills 迁移skillctl import from-npx
仅重新链接(lock 未更改)skillctl sync
从上游重新获取skillctl update 或 skillctl update <名称>
CI 可重现安装skillctl install --frozen 然后 skillctl audit --strict
lock 中存在不可移植路径运行 skillctl install 重写;检查 skillctl doctor 的警告

快速示例

# 初始化
skillctl init --with-skill
skillctl add github:vercel-labs/agent-skills#web-design-guidelines
skillctl install

# 项目本地技能
skillctl add file:./my-skill
skillctl install
skillctl sync

# 导入已有 agent 目录
skillctl import from-project --dry-run
skillctl import from-project

# 检查
skillctl list
skillctl doctor
skillctl audit --json

执行 add file:./my-skill + install 后预期结果:manifest 描述符为 file:./my-skill,lock 中的 canonicalPath 类似于 ~/.skillctl/skills/my-skill。

可移植性(0.3.1+)

  • 可移植: file:./rel、local:imported/<name>、远程描述符、canonicalPath: ~/.skillctl/skills/<name>。
  • 不可移植: 绝对路径 file:/Users/...、local:/abs/path、来自其他机器的绝对 canonicalPath。
  • 如果 doctor 警告不可移植路径,运行 skillctl install 以从 manifest 重写 lock。

故障模式

症状操作
canonical path missingskillctl install
完整性不匹配skillctl update <名称> 或 skillctl install
符号链接失败(Windows)doctor 会注明;配置 defaultMode: copy
没有 agent 被链接skillctl sync;在 ~/.skillctl/config.json 中启用 agent
Frozen install failed存储已不同步;运行不带 --frozen 的 install

参考

相关技能