# Agent Skills 仓库

自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容与本仓库内的 **skiff** CLI 一并维护。

| 组件 | 路径 | 职责 |
|------|------|------|
| **skills/** | 本仓库 | skill 内容与规范 |
| **skiff/** | 本仓库 | 安装、symlink、健康检查（Python 3，无编译） |

---

## 快速开始

```bash
# 1. 克隆并安装 CLI
git clone https://git.yumee.top/laily/skills.git ~/code/gitea/skills
cd ~/code/gitea/skills && ./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
├── discussion-notes/           # 讨论沉淀笔记
│   ├── SKILL.md
│   └── reference.md
skiff/                          # CLI 源码（python3 -m skiff）
bin/skiff                       # CLI 入口脚本
install.sh                      # 安装到 ~/.local/bin
registry.yaml                   # 外部 Git skill 来源目录
AGENTS.md                       # 本文档
```

**本仓库包含**：`skills/`、`skiff/`、`registry.yaml`、`AGENTS.md`  
**本仓库不包含**：各项目的 skill 启用清单（`.skills.yaml`）

---

## Skill 目录

### 自研（Owned）

| Skill | 说明 |
|-------|------|
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |

新建 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 内容与 skiff CLI 同仓库，Python 3 直接运行，无需编译

---

## 架构

```
skills 仓库（本仓库）
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
```

### 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` |

项目级命令：

```bash
cd ~/code/my-app
skiff enable declarative-openspec-loop
skiff disable declarative-openspec-loop
skiff sync
```

---

## skiff 命令

CLI 源码在 `skiff/`，安装：`./install.sh`（软链到 `~/.local/bin/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 <name>` | 从 `_template/` 脚手架创建 skill |
| `skiff doctor` | symlink 健康检查（`--fix` 自动修复） |

`--target` 可选 `cursor`、`claude`、`codex`、`all`（默认 all）。

---

## 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 --fix` → 重建 symlink |

---

## 工具分工

| 场景 | 工具 |
|------|------|
| 自研 skill 安装/管理 | **skiff** |
| 社区 skill 安装 | **Vercel `npx skills add`** |
| NPM 包内 skill | **skills-npm** / **skill-indexer** |
| 搜索发现 | **npx skills find** / [skills.sh](https://skills.sh) |

---

## 日常速查

| 我要… | 命令 | 在哪 |
|-------|------|------|
| 首次 setup | `git clone ... && ./install.sh && skiff setup <path>` | 任意 |
| 新建 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)
- [Vercel skills CLI](https://github.com/vercel-labs/skills)
- [skills.sh](https://skills.sh)
- [Cursor Skills 文档](https://cursor.com/docs/context/skills)