# Agent Skills 仓库

自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。


| 仓库              | 地址                                                                       | 职责                         |
| --------------- | ------------------------------------------------------------------------ | -------------------------- |
| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill、规范包、skiff CLI 的当前 SSOT |
| **skiff**       | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff)   | skiff CLI 的独立来源 / 上游同步参考    |


---

## 快速开始

```bash
# 1. 克隆并关联
git clone https://git.yumee.top/laily/skills.git ~/.skills
cd ~/.skills && ./install.sh

# install.sh 会自动把 skiff 项目 skill 安装到所有 Agent
# 2. 安装其他 skill
skiff add declarative-openspec-loop -g

# 3. 查看状态
skiff list
skiff status
```

---

## 仓库结构

```
skills/
├── _template/                  # 新建 skill 的脚手架
├── ack/                        # 完整 ACK skill，含 references/templates/scripts
├── declarative-openspec-loop/  # 自研 skill，必须含 SKILL.md
│   ├── SKILL.md
│   └── reference.md
├── discussion-notes/           # 讨论沉淀笔记
│   ├── SKILL.md
│   └── reference.md
skiff/                          # CLI 源码（Python 3）
bin/skiff                       # CLI 入口
catalog.yaml                   # skiff 预置 Skill 来源目录
AGENTS.md                       # 本文档
```

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

---

## Skill 目录

### 内置（Builtin）


| Skill                                                                  | 说明                                                |
| ---------------------------------------------------------------------- | ------------------------------------------------- |
| [orc](skills/orc/SKILL.md)                                             | ORC 入口：显式编排开发、版本发布与产物任务，支持 Agent 分档         |
| [ack](skills/ack/SKILL.md)                                             | ACK 入口：显式初始化、检查并运行项目三角色协作闭环                  |
| [skiff](skills/skiff/SKILL.md)                                         | 本项目工作流：创建、使用、反馈与更新 builtin 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。

Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如
`skills/ack/references/`、`templates/`、`examples/` 和 `scripts/`。项目初始化只生成
项目状态，不复制或链接 Skill 内容：

```bash
skiff init ack
```

### 预置目录（Catalog）

在 `catalog.yaml` 中预置，通过 skiff 拉取安装：


| Source | 来源 |
| --- | --- |
| waza | [https://github.com/tw93/Waza](https://github.com/tw93/Waza) |


```bash
skiff fetch waza
skiff add waza/think -g
```

### 自定义仓库（Custom Sources）

公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：

```bash
skiff source add company \
  git@git.company.com:platform/agent-skills.git \
  --skills-path skills
skiff list --source company
skiff add company/internal-review -g
```

也可以接入已有本地 checkout：

```bash
skiff source add company --local ~/code/company-skills --skills-path skills
```

配置保存在 `~/.config/skiff/config.yaml`，Git source 默认 clone 到
`~/.local/share/skiff/sources/<source>/`。项目 `.skills.yaml` 只记录逻辑
source 名称，每台机器独立配置实际仓库地址。

### 社区（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 使用的规范、模板和脚本与 `SKILL.md` 同目录维护
5. **一体维护** — skill 与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步

---

## 架构

```
skills 仓库（本仓库）              skiff CLI
skills/<name>/              ←──   skiff install / enable
skiff/                      ←──   python3 -m skiff
catalog.yaml               ←──   skiff add / fetch
         ↑
    ~/.skills（symlink）
         │
    ┌────┴────┐
    ▼         ▼
~/.cursor/skills/     project/.agents/skills/
~/.claude/skills/     project/.claude/skills/
~/.codex/skills/      project/.opencode/skills/
~/.config/opencode/skills/  project/.skills.yaml
```

### Skill 三层分类


| 层级               | 位置                                 | 维护方式                            |
| ---------------- | ---------------------------------- | ------------------------------- |
| **Builtin**        | `skills/<name>/`                   | 本仓库 commit                      |
| **Catalog** | `catalog.yaml` + checkout 缓存 | `skiff catalog add / fetch` |
| **Custom Source** | `~/.local/share/skiff/sources/` 或本地路径 | `skiff source add/fetch` |
| **External NPM** | `node_modules/`                    | `npx skills add` / `skills-npm` |

### 非 Skill 资料分类

| 类型 | 位置 | 维护方式 |
| --- | --- | --- |
| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 |


### 多 Agent 路径


| Agent       | 全局                  | 项目                |
| ----------- | ------------------- | ----------------- |
| Cursor      | `~/.cursor/skills/` | `.agents/skills/` |
| Claude Code | `~/.claude/skills/` | `.claude/skills/` |
| Codex       | `~/.codex/skills/`  | `.agents/skills/` |
| OpenCode    | `~/.config/opencode/skills/` | `.opencode/skills/` |


---

## 项目级启用

每个项目**自己维护** `.skills.yaml`，不由本仓库管理：

```yaml
# .skills.yaml（在项目根目录）
skills:
  - name: declarative-openspec-loop
    source: builtin
  - name: think
    source: catalog:waza
  - name: internal-review
    source: company

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 命令

详见 [skiff README](https://git.yumee.top/laily/skiff)。

### 已实现


| 命令                                     | 说明                  |
| -------------------------------------- | ------------------- |
| `skiff bootstrap`                      | 将 skiff 项目 skill 全局安装到所有 Agent |
| `skiff list`                           | 列出所有 skill          |
| `skiff status`                         | 安装状态总览              |
| `skiff add <name> [-g]`                | 项目或全局安装（symlink） |
| `skiff remove <name> [-g]`             | 移除 symlink |
| `skiff catalog add` / `skiff fetch`    | 管理和拉取 catalog source |


### 草稿与健康检查


| 命令 | 说明 |
| --- | --- |
| `skiff create <name> --idea TEXT [--from-project PATH]` | 从 `_template/` 创建草稿 |
| `skiff check <name>` | 校验草稿或正式 skill |
| `skiff finalize <name>` | 校验并将草稿转为正式 skill |
| `skiff doctor [--fix]` | 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. `skiff create my-skill --idea "..." --from-project .`
2. Agent 编辑 `~/.skills/.drafts/my-skill/SKILL.md`
3. `skiff check my-skill`
4. 用户确认后执行 `skiff finalize my-skill`
5. `skiff add my-skill -a cursor -g -y` 验证
6. 在本仓库 commit；需要的项目再用 `skiff add 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) |


---

## 日常速查


| 我要…        | 命令                                | 在哪   |
| ---------- | --------------------------------- | ---- |
| 首次安装       | `git clone <repo> ~/.skills && ~/.skills/install.sh` | 任意   |
| 新建 skill   | `skiff create` → Agent 完善 → `check/finalize` | 任意项目 |
| 全局启用       | `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)