feat: add skiff

2026-07-04 10:50:03 +08:00
parent 8b5ac01a9d
commit c2acbc3809
16 changed files with 1501 additions and 73 deletions
@@ -0,0 +1,149 @@
+# skiff
+
+Agent Skills 安装与管理 CLI。纯 Python 3 实现，无第三方依赖，无需编译。
+
+## 安装
+
+```bash
+cd /path/to/skills   # 本仓库根目录
+./install.sh         # 软链到 ~/.local/bin/skiff
+```
+
+确保 `~/.local/bin` 在 `PATH` 中。开发时也可直接运行：
+
+```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 install <name> [--target all]` | 软链到 Agent 全局目录 |
+| `skiff uninstall <name> [--target all]` | 移除软链 |
+
+全局目标路径：
+
+| Agent | 路径 |
+|-------|------|
+| cursor | `~/.cursor/skills/` |
+| claude | `~/.claude/skills/` |
+| codex | `~/.codex/skills/` |
+
+### 外部 Git skill
+
+| 命令 | 说明 |
+|------|------|
+| `skiff add <name> <repo-url> [--ref main] [--path .]` | 写入 `registry.yaml` |
+| `skiff fetch <name>` | 克隆/更新到 `~/.local/share/skills/externals/<name>/` |
+| `skiff install-external <name> [--target all]` | 安装外部 skill 到 Agent 目录 |
+
+### 项目级
+
+| 命令 | 说明 |
+|------|------|
+| `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 install my-skill --target cursor
+skiff doctor --target cursor
+```
+
+### 在项目中启用 skill
+
+```bash
+cd ~/code/my-app
+skiff enable declarative-openspec-loop --target cursor
+skiff sync
+```
+
+### 安装外部 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)