skillctl 是做什么的?
使用 skillctl CLI 管理 Agent 技能的操作手册。请运行真实命令;不要模拟输出或手动将 SKILL.md 文件复制到 agent 目录之间。
黄金规则
- 一个规范存储 — 技能存放在
~/.skillctl/skills/<name>/下;agent 通过sync获得符号链接。 - 提交 manifest + lock — 将
agent-skills.json和agent-skills.lock纳入版本控制,确保团队可重现。 - 仅使用可移植描述符 — 使用
file:./<path>、local:imported/<name>、github:、npm:或skills.sh/;切勿提交绝对的家目录路径。 - 先安装后同步 —
install在存储中物化技能;sync仅重新链接 agent。 - 变更后验证 — 运行
skillctl doctor(以及在 CI 中运行skillctl audit)。 - 优先导入而非手动复制 — 使用
import from-project或import from-npx,而不是复制技能文件夹。
决策树
| 情境 | 命令 |
|---|---|
| 新项目,无 manifest | skillctl 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 missing | skillctl install |
| 完整性不匹配 | skillctl update <名称> 或 skillctl install |
| 符号链接失败(Windows) | doctor 会注明;配置 defaultMode: copy |
| 没有 agent 被链接 | skillctl sync;在 ~/.skillctl/config.json 中启用 agent |
Frozen install failed | 存储已不同步;运行不带 --frozen 的 install |
参考
- commands.md — 完整命令速查表
- specifiers.md — 描述符语法
- manifest-lock.md — manifest 和 lock 语义
- workflows.md — 团队入职、迁移、CI
- troubleshooting.md — doctor、Windows、共存