skiff
Agent Skills 安装与管理 CLI。纯 Python 3 实现，无第三方依赖，无需编译。
安装
cd /path/to/skills # 本仓库根目录
./install.sh # 软链到 ~/.local/bin/skiff
确保 ~/.local/bin 在 PATH 中。
命令风格
接口对齐 Vercel skills CLI 的 add / remove，
统一管理 ~/.skills 自研 skill、命名 custom source 和 registry 外部 skill。
# 浏览可用自研 skill
skiff add --list
# 装到当前项目 / 全局
skiff add discussion-notes -a cursor -y
skiff add discussion-notes -a cursor -g -y
# 卸载
skiff remove discussion-notes -a cursor -y
skiff rm discussion-notes -g -y
# 改完 skill 后提交推送（在任意目录执行，操作 ~/.skills）
skiff publish skills/discussion-notes -m "update discussion-notes" --push
开发时也可直接运行：
PYTHONPATH=/path/to/skills python3 -m skiff <command>
首次安装
git clone https://git.yumee.top/laily/skills.git ~/.skills
~/.skills/install.sh
install.sh 会安装 CLI，并自动执行 skiff bootstrap，将本仓库的 skiff skill 全局软链到 Cursor、Claude Code 和 Codex。也可以随时手动重跑：
skiff bootstrap
命令参考
查看
| 命令 | 说明 |
|---|---|
skiff list [--source NAME] |
列出所有来源或指定 source 中的 skill |
skiff status [--target all|cursor|claude|codex] |
安装状态总览 |
项目初始化
| 命令 | 说明 |
|---|---|
skiff bootstrap |
将本项目的 skiff skill 全局安装到所有 Agent |
skiff kit init <name> [--project DIR] [--copy] |
在项目的 docs/<name>/ 初始化规范包；默认软链接到 SSOT |
全局安装（自研 skill）
| 命令 | 说明 |
|---|---|
skiff add <name> [--global] [-a AGENT...] [-y] |
安装到 Agent 目录（软链） |
skiff select [--global] [-a AGENT...] |
打开终端多选界面，批量安装 skill |
skiff remove <name> [--global] [-a AGENT...] [-y] |
移除软链（rm / r 别名） |
skiff add --list |
列出可用自研 skill |
skiff publish [paths] -m MSG [--push] |
在 ~/.skills 内 git add/commit/push |
旧命令 install / uninstall 已移除，请改用 add / remove。
全局目标路径：
| Agent | 路径 |
|---|---|
| cursor | ~/.cursor/skills/ |
| claude | ~/.claude/skills/ |
| codex | ~/.codex/skills/ |
外部 Git skill
| 命令 | 说明 |
|---|---|
skiff registry add <name> <repo-url> [--ref main] [--path .] |
写入 registry.yaml |
skiff fetch <name> |
克隆或更新外部仓库缓存 |
skiff add <name> [-g] [-a AGENT...] |
安装 registry 中的单个 skill 或完整 collection（缺失时自动 fetch） |
skiff add <collection>/<skill> [...] |
只安装 collection 中指定的 skill |
registry.yaml 条目可额外提供 description 和 tags。description
会显示在 skiff select 的候选列表中。path 可以直接指向含
SKILL.md 的单个 skill，也可以指向由多个 skill 目录组成的 collection。
collection 会自动发现下一层所有含 SKILL.md 的目录；skiff add <name>
安装全部，skiff select 则展开为 <name>/<skill> 供分别勾选。同一
repo 与 ref 共享一份 Git checkout。
交互式批量安装
skiff select # 当前项目，全部 Agent
skiff select -a codex # 当前项目，仅 Codex
skiff select -g # 全局安装
skiff select --project ~/code/app # 指定项目
使用方向键移动、空格勾选、/ 搜索、Enter 安装，按 q 或 Esc
取消。已经安装到目标范围的 skill 默认勾选；取消勾选不会卸载已有 skill。
项目模式会把成功选择的项目写入 .skills.yaml。非交互环境请使用
skiff add <name>...。使用 -a 限定 Agent 时，该范围会记录在对应的
skill 条目中，后续 skiff sync 不会扩散到其他 Agent。
Custom source（多-skill 仓库）
公司或团队维护的仓库通常包含多个 skill。使用命名 source 接入：
# Git 仓库，默认 clone 到 ~/.local/share/skiff/sources/company
skiff source add company \
git@git.company.com:platform/agent-skills.git \
--ref main \
--skills-path internal/skills
# 或接入已有本地仓库
skiff source add company \
--local ~/code/company-agent-skills \
--skills-path skills
skiff source list
skiff source fetch company
skiff list --source company
skiff add company/code-review -g -a codex
| 命令 | 说明 |
|---|---|
skiff source add <name> <repo> [--ref REF] [--checkout PATH] [--skills-path PATH] |
注册并克隆 Git source |
skiff source add <name> --local PATH [--skills-path PATH] |
接入已有本地仓库 |
skiff source list / show <name> |
查看 source |
skiff source fetch <name> / fetch --all |
clone 或 fast-forward 更新 |
skiff source remove <name> |
移除配置并保留 checkout |
配置保存在 ~/.config/skiff/config.yaml。Git/SSH 认证复用本机 Git 配置，
skiff 不保存 token。可以使用 company/code-review，也可以使用
skiff add code-review --source company。多个来源包含同名 skill 时，必须明确来源。
项目级
| 命令 | 说明 |
|---|---|
skiff enable <name> [--target all] [--project <dir>] |
写入 .skills.yaml 并创建项目软链 |
skiff disable <name> [--target all] [--project <dir>] |
从 manifest 移除并删除软链 |
skiff sync [--target all] [--project <dir>] |
按 .skills.yaml 重建软链 |
项目目标路径：
| Agent | 路径 |
|---|---|
| cursor | <project>/.agents/skills/ |
| claude | <project>/.claude/skills/ |
| codex | <project>/.agents/skills/ |
脚手架与健康检查
| 命令 | 说明 |
|---|---|
skiff create <name> [--idea TEXT] [--from-project PATH] |
从模板创建草稿到 ~/.skills/.drafts/ |
skiff check <name> |
校验草稿或正式 skill |
skiff finalize <name> |
校验草稿并移动到正式 skills/ |
skiff doctor [--target all] [--fix] |
检查软链健康状态，--fix 自动修复 |
常用工作流
新建并全局启用自研 skill
skiff create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
skiff check my-skill
skiff finalize my-skill
skiff publish skills/my-skill -m "add my-skill" --push
skiff add my-skill -a cursor -g -y
skiff doctor -a cursor
在项目中启用 skill
cd ~/code/my-app
skiff add declarative-openspec-loop -a cursor -y
安装外部 Git skill
skiff add my-ext https://github.com/org/repo --ref main
skiff fetch my-ext
skiff install-external my-ext
源码结构
skiff/
├── __init__.py # 版本号
├── __main__.py # python3 -m skiff 入口
├── cli.py # 命令定义与调度
├── paths.py # 路径常量与 Agent 目标
├── skills.py # 自研 skill 发现
├── registry.py # registry.yaml 读写
├── sources.py # custom source 配置、发现与 Git 管理
├── project.py # .skills.yaml 管理
├── symlinks.py # 软链创建/检查/修复
└── yaml_io.py # 轻量 YAML 解析（无第三方依赖）
入口脚本：../bin/skiff
路径约定
| 变量 | 路径 | 说明 |
|---|---|---|
SKILLS_HOME |
~/.skills |
skills 仓库（软链） |
SKILLS_DIR |
~/.skills/skills/ |
自研 skill 目录 |
REGISTRY_FILE |
~/.skills/registry.yaml |
外部 skill 注册表 |
EXTERNALS_DIR |
~/.local/share/skills/externals/ |
已 fetch 的外部仓库；新条目按 repo/ref 共享缓存 |
CONFIG_FILE |
~/.config/skiff/config.yaml |
custom source 配置 |
SOURCES_DIR |
~/.local/share/skiff/sources/ |
custom Git source 默认 checkout |
注意事项
- 禁止在
~/.cursor/skills/等 Agent 目录直接创建非软链的 skill - Claude Code 对 symlink 支持不稳定；建议对单个 skill 目录软链，不要软链整个
~/.claude/skills/ - 若 Agent 将软链替换为普通目录，运行
skiff doctor --fix重建