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,132 @@
+# Agent Skills
+
+自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。Skill 内容与 **skiff** CLI 在本仓库一并维护。
+
+## 快速开始
+
+```bash
+git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
+cd ~/code/gitea/skills
+./install.sh
+skiff setup ~/code/gitea/skills
+
+skiff install declarative-openspec-loop
+skiff list
+skiff status
+```
+
+## 仓库结构
+
+```
+skills/           # 自研 skill（SSOT）
+skiff/            # CLI 源码（Python 3）
+bin/skiff         # CLI 入口
+registry.yaml     # 外部 Git skill 目录
+AGENTS.md         # 详细规范与架构说明
+```
+
+| 路径 | 说明 |
+|------|------|
+| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md` |
+| [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI |
+| [registry.yaml](registry.yaml) | 外部 Git skill 注册表 |
+| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |
+
+## 自研 Skill
+
+| Skill | 说明 |
+|-------|------|
+| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
+| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |
+
+新建 skill：
+
+```bash
+skiff create my-skill    # 从 _template/ 脚手架创建
+# 编辑 skills/my-skill/SKILL.md
+skiff install my-skill   # 全局安装验证
+```
+
+## 安装方式
+
+### 全局（用户级）
+
+```bash
+skiff install <name>                  # 安装到 ~/.cursor/skills/ 等
+skiff install <name> --target cursor
+```
+
+### 项目级
+
+在项目根目录维护 `.skills.yaml`：
+
+```yaml
+skills:
+  - declarative-openspec-loop
+  - name: superpowers
+    source: registry
+    ref: main
+
+targets:          # 可选，默认 all
+  - cursor
+  - claude
+  - codex
+```
+
+```bash
+skiff enable declarative-openspec-loop
+skiff sync
+skiff disable declarative-openspec-loop
+```
+
+## 外部 Skill
+
+**Git 来源**（经 skiff 管理）：
+
+```bash
+skiff fetch superpowers
+skiff install-external superpowers
+```
+
+**社区来源**（Vercel CLI）：
+
+```bash
+npx skills add vercel-labs/agent-skills -g -y
+npx skills find typescript
+```
+
+## 架构概览
+
+```
+本仓库
+├── skills/<name>/     ←── skiff install / enable
+├── registry.yaml      ←── skiff add / fetch
+└── skiff/             ←── python3 -m skiff
+         ↑
+    ~/.skills（symlink）
+         │
+    ┌────┴────────────────┐
+    ▼                     ▼
+~/.cursor/skills/    project/.agents/skills/
+~/.claude/skills/    project/.claude/skills/
+~/.codex/skills/     project/.skills.yaml
+```
+
+## 设计原则
+
+1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`
+2. **项目自治** — 各项目自行维护 `.skills.yaml`
+3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
+4. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译
+
+## 文档
+
+- [AGENTS.md](AGENTS.md) — 完整规范、多 Agent 路径、编写约定
+- [skiff/README.md](skiff/README.md) — CLI 命令参考与开发说明
+
+## 参考
+
+- [Agent Skills 开放标准](https://agentskills.io)
+- [Vercel skills CLI](https://github.com/vercel-labs/skills)
+- [skills.sh](https://skills.sh)
+- [Cursor Skills 文档](https://cursor.com/docs/context/skills)