laily
f1ed320991
Replace install/uninstall with add/remove, add publish for git ops in ~/.skills, and resolve bin/skiff symlinks so commands work from any cwd. Co-authored-by: Cursor <cursoragent@cursor.com>
176 lines
4.8 KiB
Markdown
176 lines
4.8 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`，专用于 **~/.skills 自研 skill**。
|
||
|
||
```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
|
||
skiff setup ~/code/gitea/skills # 将 ~/.skills 软链到仓库
|
||
```
|
||
|
||
若仓库本身就在 `~/.skills`（开发场景），`setup` 会自动识别，无需额外操作。
|
||
|
||
## 命令参考
|
||
|
||
### 仓库关联
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `skiff setup <path>` | 关联 `~/.skills` 到 skills 仓库 |
|
||
|
||
### 查看
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `skiff list` | 列出自研 skill 与 registry 中的外部 skill |
|
||
| `skiff status [--target all\|cursor\|claude\|codex]` | 安装状态总览 |
|
||
|
||
### 全局安装（自研 skill）
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `skiff add <name> [--global] [-a AGENT...] [-y]` | 安装到 Agent 目录（软链） |
|
||
| `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>` | 克隆/更新到 `~/.local/share/skills/externals/<name>/` |
|
||
| `skiff add <name> [-g] [-a AGENT...]` | 安装 registry 中的外部 skill（缺失时自动 fetch） |
|
||
|
||
### 项目级
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `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>` | 从 `skills/_template/` 创建自研 skill |
|
||
| `skiff doctor [--target all] [--fix]` | 检查软链健康状态，`--fix` 自动修复 |
|
||
|
||
## 常用工作流
|
||
|
||
### 新建并全局启用自研 skill
|
||
|
||
```bash
|
||
skiff create my-skill
|
||
# 编辑 skills/my-skill/SKILL.md
|
||
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
|
||
```
|
||
|
||
### 安装外部 Git skill
|
||
|
||
```bash
|
||
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 读写
|
||
├── project.py # .skills.yaml 管理
|
||
├── symlinks.py # 软链创建/检查/修复
|
||
└── yaml_io.py # 轻量 YAML 解析（无第三方依赖）
|
||
```
|
||
|
||
入口脚本：[../bin/skiff](../bin/skiff)
|
||
|
||
## 路径约定
|
||
|
||
| 变量 | 路径 | 说明 |
|
||
|------|------|------|
|
||
| `SKILLS_HOME` | `~/.skills` | skills 仓库（软链） |
|
||
| `SKILLS_DIR` | `~/.skills/skills/` | 自研 skill 目录 |
|
||
| `REGISTRY_FILE` | `~/.skills/registry.yaml` | 外部 skill 注册表 |
|
||
| `EXTERNALS_DIR` | `~/.local/share/skills/externals/` | 已 fetch 的外部仓库 |
|
||
|
||
## 注意事项
|
||
|
||
- **禁止**在 `~/.cursor/skills/` 等 Agent 目录直接创建非软链的 skill
|
||
- Claude Code 对 symlink 支持不稳定；建议对单个 skill 目录软链，不要软链整个 `~/.claude/skills/`
|
||
- 若 Agent 将软链替换为普通目录，运行 `skiff doctor --fix` 重建
|
||
|
||
## 相关文档
|
||
|
||
- [项目 README](../README.md)
|
||
- [AGENTS.md](../AGENTS.md)
|