Files

T

laily f1ed320991 feat(skiff): align CLI with Vercel skills and fix entry symlink

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>

2026-07-04 12:11:53 +08:00

4.8 KiB

Raw Blame History

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。

# 浏览可用自研 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>

首次配置

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

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

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 读写
├── 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 的外部仓库

注意事项

禁止在 ~/.cursor/skills/ 等 Agent 目录直接创建非软链的 skill
Claude Code 对 symlink 支持不稳定；建议对单个 skill 目录软链，不要软链整个 ~/.claude/skills/
若 Agent 将软链替换为普通目录，运行 skiff doctor --fix 重建

4.8 KiB Raw Blame History Unescape Escape