# Agent Skills 仓库

自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。


| 仓库              | 地址                                                                       | 职责              |
| --------------- | ------------------------------------------------------------------------ | --------------- |
| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill 内容与规范     |
| **skiff**       | [https://git.yumee.top/laily/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
├── discussion-notes/           # 讨论沉淀笔记
│   ├── 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/校验并迭代直到通过 |
| [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](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)