feat: init

2026-07-02 23:57:59 +08:00
commit ea3621a065
7 changed files with 759 additions and 0 deletions
@@ -0,0 +1,282 @@
+# Agent Skills 仓库
+
+自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。
+
+| 仓库 | 地址 | 职责 |
+|------|------|------|
+| **skills**（本仓库） | https://git.yumee.top/laily/skills | skill 内容与规范 |
+| **skiff** | https://git.yumee.top/laily/skiff | 安装、symlink、健康检查 |
+
+---
+
+## 快速开始
+
+```bash
+# 1. 克隆并关联
+git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
+git clone https://git.yumee.top/laily/skiff.git ~/code/gitea/skiff
+cd ~/code/gitea/skiff && ./install.sh
+skiff setup ~/code/gitea/skills
+
+# 2. 全局安装 skill
+skiff install declarative-openspec-loop
+
+# 3. 查看状态
+skiff list
+skiff status
+```
+
+---
+
+## 仓库结构
+
+```
+skills/
+├── _template/                  # 新建 skill 的脚手架
+├── declarative-openspec-loop/  # 自研 skill
+│   ├── SKILL.md
+│   └── reference.md
+registry.yaml                   # 外部 Git skill 来源目录
+AGENTS.md                       # 本文档
+```
+
+**本仓库包含**：`skills/`、`registry.yaml`、`AGENTS.md`  
+**本仓库不包含**：CLI 代码、各项目的 skill 启用清单
+
+---
+
+## Skill 目录
+
+### 自研（Owned）
+
+| Skill | 说明 |
+|-------|------|
+| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
+
+新建 skill：复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md`，在本仓库 commit。
+
+### 外部（External Git）
+
+在 `registry.yaml` 中注册，通过 skiff 拉取安装：
+
+| Skill | 来源 |
+|-------|------|
+| superpowers | https://github.com/obra/superpowers |
+
+```bash
+skiff fetch superpowers
+skiff install-external superpowers
+```
+
+### 社区（External NPM / GitHub）
+
+推荐使用 Vercel CLI 安装第三方 skill：
+
+```bash
+npx skills add vercel-labs/agent-skills -g -y
+npx skills find typescript
+```
+
+---
+
+## 设计原则
+
+1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`，不在 Agent 目录直接创建
+2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单
+3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
+4. **仓库分离** — skill 内容与 CLI 工具分仓库，互不影响更新
+
+---
+
+## 架构
+
+```
+skills 仓库（本仓库）              skiff CLI
+skills/<name>/              ←──   skiff install / enable
+registry.yaml               ←──   skiff add / fetch
+         ↑
+    ~/.skills（symlink）
+         │
+    ┌────┴────┐
+    ▼         ▼
+~/.cursor/skills/     project/.agents/skills/
+~/.claude/skills/     project/.claude/skills/
+~/.codex/skills/      project/.skills.yaml
+```
+
+### Skill 三层分类
+
+| 层级 | 位置 | 维护方式 |
+|------|------|---------|
+| **Owned** | `skills/<name>/` | 本仓库 commit |
+| **External Git** | `~/.local/share/skills/externals/` | `skiff fetch` |
+| **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` |
+
+### 多 Agent 路径
+
+| Agent | 全局 | 项目 |
+|-------|------|------|
+| Cursor | `~/.cursor/skills/` | `.agents/skills/` |
+| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
+| Codex | `~/.codex/skills/` | `.agents/skills/` |
+
+---
+
+## 项目级启用
+
+每个项目**自己维护** `.skills.yaml`，不由本仓库管理：
+
+```yaml
+# .skills.yaml（在项目根目录）
+skills:
+  - declarative-openspec-loop
+  - name: superpowers
+    source: registry
+    ref: main
+
+targets:          # 可选，默认 all
+  - cursor
+  - claude
+  - codex
+```
+
+| 概念 | 类比 |
+|------|------|
+| skills 仓库 | npm registry |
+| `.skills.yaml` | `package.json` dependencies |
+| `skiff enable` | `npm install` |
+| `skiff sync` | `npm ci` |
+
+项目级命令（skiff 待实现）：
+
+```bash
+cd ~/code/my-app
+skiff enable declarative-openspec-loop
+skiff disable declarative-openspec-loop
+skiff sync
+```
+
+---
+
+## skiff 命令
+
+详见 [skiff README](https://git.yumee.top/laily/skiff)。
+
+### 已实现
+
+| 命令 | 说明 |
+|------|------|
+| `skiff setup <path>` | 关联 `~/.skills` 到本仓库 |
+| `skiff list` | 列出所有 skill |
+| `skiff status` | 安装状态总览 |
+| `skiff install <name>` | 全局安装（symlink） |
+| `skiff uninstall <name>` | 移除 symlink |
+| `skiff add / fetch / install-external` | 外部 Git skill |
+
+### 待实现
+
+| 命令 | 说明 |
+|------|------|
+| `skiff enable / disable` | 项目级启用/关闭 |
+| `skiff sync` | 按 `.skills.yaml` 重建 symlink |
+| `skiff create` | 从 `_template/` 脚手架创建 skill |
+| `skiff doctor` | symlink 健康检查 |
+
+---
+
+## Skill 编写规范
+
+遵循 [Agent Skills 开放标准](https://agentskills.io)：
+
+```
+skill-name/
+├── SKILL.md          # 必需
+├── reference.md      # 可选
+├── examples.md       # 可选
+└── scripts/          # 可选
+```
+
+### Frontmatter
+
+```yaml
+---
+name: skill-name
+description: >-
+  做什么、何时触发。description 是 Agent 决定是否加载的唯一依据，务必写清触发关键词。
+---
+```
+
+### 命名
+
+- 目录名 = frontmatter `name`
+- 小写 + 连字符：`security-review`
+- 禁止 camelCase、空格、下划线
+
+### 新建流程
+
+1. `cp -r skills/_template skills/my-skill`
+2. 编辑 `skills/my-skill/SKILL.md`
+3. `skiff install my-skill --target cursor` 验证
+4. 在本仓库 commit
+5. 各项目 `skiff enable my-skill`（待实现）
+
+**禁止**在 `~/.cursor/skills/` 或项目 Agent 目录直接创建非 symlink 的 skill。
+
+---
+
+## Skill 修改回流
+
+symlink 正确时，Agent 在项目里改 skill 文件 = 直接改 SSOT：
+
+```
+project/.agents/skills/foo/SKILL.md
+  → ~/.skills/skills/foo/SKILL.md
+  → 在本仓库 commit
+```
+
+---
+
+## Claude Code 注意事项
+
+Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入时将 symlink 替换成普通文件。
+
+| 场景 | 建议 |
+|------|------|
+| Cursor / Codex | symlink，正常 |
+| Claude Code | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` |
+| symlink 被替换 | `skiff doctor`（待实现）→ 重建 symlink |
+
+---
+
+## 工具分工
+
+| 场景 | 工具 |
+|------|------|
+| 自研 skill 安装/管理 | **skiff** |
+| 社区 skill 安装 | **Vercel `npx skills add`** |
+| NPM 包内 skill | **skills-npm** / **skill-indexer** |
+| 搜索发现 | **npx skills find** / [skills.sh](https://skills.sh) |
+
+---
+
+## 日常速查
+
+| 我要… | 命令 | 在哪 |
+|-------|------|------|
+| 首次 setup | `skiff setup ~/code/gitea/skills` | 任意 |
+| 新建 skill | 复制 `_template/` → 编辑 → commit | 本仓库 |
+| 全局启用 | `skiff install <name>` | 任意 |
+| 项目启用 | `skiff enable <name>` | 项目目录 |
+| 看状态 | `skiff status` | 任意 |
+| 装社区 skill | `npx skills add owner/repo -g -y` | 任意 |
+| 更新外部 skill | `skiff fetch <name>` | 任意 |
+
+---
+
+## 参考
+
+- [Agent Skills 开放标准](https://agentskills.io)
+- [skiff CLI](https://git.yumee.top/laily/skiff)
+- [Vercel skills CLI](https://github.com/vercel-labs/skills)
+- [skills.sh](https://skills.sh)
+- [Cursor Skills 文档](https://cursor.com/docs/context/skills)