.pouch/skiff/README.md

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 重建

相关文档

• 项目 README
• AGENTS.md