252 lines
8.6 KiB
Markdown
252 lines
8.6 KiB
Markdown
# skiff
|
||
|
||
Agent Skills 安装与管理 CLI。纯 Python 3 实现，无第三方依赖，无需编译。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
cd /path/to/skills # 本仓库根目录
|
||
./install.sh # 软链到 ~/.local/bin/skiff
|
||
```
|
||
|
||
确保 `~/.local/bin` 在 `PATH` 中。
|
||
|
||
## 命令风格
|
||
|
||
接口对齐 [Vercel skills CLI](https://github.com/vercel-labs/skills) 的 `add` / `remove`，
|
||
统一管理 builtin skill、预置 catalog source 和用户命名的 custom source。
|
||
|
||
```bash
|
||
# 浏览可用自研 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
|
||
```
|
||
|
||
开发时也可直接运行：
|
||
|
||
```bash
|
||
PYTHONPATH=/path/to/skills python3 -m skiff <command>
|
||
```
|
||
|
||
## 首次安装
|
||
|
||
```bash
|
||
git clone https://git.yumee.top/laily/skills.git ~/.skills
|
||
~/.skills/install.sh
|
||
```
|
||
|
||
`install.sh` 会安装 CLI，并自动执行 `skiff bootstrap`，将本仓库的 `skiff` skill 全局软链到 Cursor、Claude Code 和 Codex。也可以随时手动重跑：
|
||
|
||
```bash
|
||
skiff bootstrap
|
||
```
|
||
|
||
## 命令参考
|
||
|
||
### 查看
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `skiff list [--source NAME]` | 列出所有来源或指定 source 中的 skill |
|
||
| `skiff status [--target all\|cursor\|claude\|codex]` | 安装状态总览 |
|
||
|
||
### 项目初始化
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `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/` |
|
||
|
||
### 预置 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。
|
||
|
||
### 交互式批量安装
|
||
|
||
```bash
|
||
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 接入：
|
||
|
||
```bash
|
||
# 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]` | 从模板创建含 `SKILL.md`、`README.md` 的草稿 |
|
||
| `skiff check <name>` | 校验草稿或正式 skill，包括人类使用说明 |
|
||
| `skiff finalize <name>` | 校验草稿并移动到正式 `skills/` |
|
||
| `skiff doctor [--target all] [--fix]` | 检查软链健康状态，`--fix` 自动修复 |
|
||
|
||
## 常用工作流
|
||
|
||
### 新建并全局启用自研 skill
|
||
|
||
```bash
|
||
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
|
||
|
||
```bash
|
||
cd ~/code/my-app
|
||
skiff add declarative-openspec-loop -a cursor -y
|
||
```
|
||
|
||
### 添加 Catalog Source
|
||
|
||
```bash
|
||
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](../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](../README.md)
|
||
- [AGENTS.md](../AGENTS.md)
|