.pouch/skiff

skiff

Agent Skills 安装与管理 CLI。纯 Python 3 实现，无第三方依赖，无需编译。

安装

cd /path/to/skills   # 本仓库根目录
./install.sh         # 软链到 ~/.local/bin/skiff

确保 ~/.local/bin 在 PATH 中。

命令风格

接口对齐 Vercel skills CLI 的 add / remove， 统一管理 builtin skill、预置 catalog source 和用户命名的 custom source。

# 浏览可用自研 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|agents]	安装状态总览

项目初始化

命令	说明
skiff bootstrap	将本项目的 skiff skill 全局安装到所有 Agent
skiff update	在 ~/.skills 执行 git pull，更新 skiff 自身
skiff init <name> [--project DIR]	使用 builtin skill 自带模板初始化项目状态

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	列出可用 builtin 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/
agents	~/.agents/skills/（agents 标准目录，覆盖 OMP）

预置 Catalog Source

命令	说明
skiff catalog add <name> <repo-url> [--ref main] [--path .]	写入 catalog.yaml
skiff fetch <name>	克隆或更新 catalog source checkout
skiff add <name> [-g] [-a AGENT...]	安装 catalog 中的单个 skill 或完整 collection（缺失时自动 fetch）
skiff add <collection>/<skill> [...]	只安装 collection 中指定的 skill

catalog.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 取消。普通 skiff select 只安装到项目，并在每一项旁只读显示各 Agent 的 全局安装状态；skiff select -g 只安装到全局。已经安装到目标范围的 skill 默认勾选；取消勾选不会卸载已有 skill，卸载请使用 skiff remove。如果全局 存在同名但指向其它来源的 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/
agents	<project>/.agents/skills/（与 cursor/codex 共用路径，软链幂等）

脚手架与健康检查

命令	说明
skiff create <name> [--idea TEXT] [--from-project PATH]	从模板创建含 SKILL.md、README.md 的草稿
skiff check <name>	校验草稿或正式 skill，包括人类使用说明
skiff finalize <name>	校验草稿并移动到正式 skills/
skiff doctor [--target all] [--fix]	检查软链健康状态，--fix 自动修复

常用工作流

新建并全局启用自研 skill

skiff create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善草稿中的 SKILL.md 和 README.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

添加 Catalog Source

skiff catalog add my-ext https://github.com/org/repo --ref main
skiff fetch my-ext
skiff add my-ext -g

源码结构

skiff/
├── __init__.py      # 版本号
├── __main__.py      # python3 -m skiff 入口
├── cli.py           # 命令定义与调度
├── paths.py         # 路径常量与 Agent 目标
├── skills.py        # builtin/catalog/custom 统一解析
├── catalog.py       # catalog.yaml 读写与 Skill 发现
├── 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/	builtin skill 目录
CATALOG_FILE	~/.skills/catalog.yaml	预置 Skill 来源目录
CATALOG_CACHE_DIR	~/.local/share/skills/externals/	catalog checkout 兼容缓存；按 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 重建

相关文档

• 项目 README
• AGENTS.md