# Agent Skills

自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。Skill 内容与 **skiff** CLI 在本仓库一并维护。

## 快速开始

```bash
git clone https://git.yumee.top/laily/skills.git ~/.skills
cd ~/.skills
./install.sh  # 安装 CLI，并将 skiff 项目 skill 安装到所有 Agent

skiff install declarative-openspec-loop
skiff select  # 交互式选择并批量安装
skiff list
skiff status
```

## 仓库结构

```
skills/           # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
kits/             # 可复制到项目的规范包 / 模板包，不是 Agent Skill
skiff/            # CLI 源码（Python 3）
bin/skiff         # CLI 入口
registry.yaml     # 外部 Git skill 目录
AGENTS.md         # 详细规范与架构说明
```

| 路径 | 说明 |
|------|------|
| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md` |
| [kits/](kits/) | 项目规范包、协作模板、可复制资料，不由 skiff 安装 |
| [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI |
| [registry.yaml](registry.yaml) | 外部 Git skill 注册表 |
| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |

## 自研 Skill

| Skill | 说明 |
|-------|------|
| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 owned skill |
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |

## 规范包（不是 Skill）

`kits/` 用来维护可复制到项目里的规范说明、模板和检查清单。它们没有 `SKILL.md`，不会被 `skiff install`、`skiff add` 或 Agent 自动加载。

| Kit | 说明 |
|-----|------|
| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包，复制到项目 `docs/agent-collaboration-kit/` 后按项目情况填写 |

新建 skill：

```bash
skiff create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
skiff check my-skill
skiff finalize my-skill
skiff add my-skill -g   # 全局安装验证
```

项目里使用 skill 发现通用问题或优化时，让 Agent 按 `skiff` skill 收集实际结果与期望结果，修改 `~/.skills/skills/<name>/` 的 SSOT，并执行 `skiff check <name>`。项目专属规则保留在项目内，不回流到通用 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
├── kits/<name>/       ←── 手动复制 / 项目文档引用
├── 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 的流程规范、模板包放在 `kits/<name>/`，不混入 `skills/`
5. **一体维护** — 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)