339 lines
11 KiB
Markdown
339 lines
11 KiB
Markdown
# 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 的脚手架
|
||
├── declarative-openspec-loop/ # 自研 skill，必须含 SKILL.md
|
||
│ ├── SKILL.md
|
||
│ └── reference.md
|
||
├── discussion-notes/ # 讨论沉淀笔记
|
||
│ ├── SKILL.md
|
||
│ └── reference.md
|
||
kits/
|
||
└── agent-collaboration-kit/ # 可复制到项目的协作规范包，不是 skill
|
||
skiff/ # CLI 源码（Python 3）
|
||
bin/skiff # CLI 入口
|
||
registry.yaml # 外部 Git skill 来源目录
|
||
AGENTS.md # 本文档
|
||
```
|
||
|
||
**本仓库包含**：`skills/`、`kits/`、`skiff/`、`bin/skiff`、`registry.yaml`、`AGENTS.md`
|
||
**本仓库不包含**：各项目的 skill 启用清单
|
||
|
||
---
|
||
|
||
## Skill 目录
|
||
|
||
### 自研（Owned）
|
||
|
||
|
||
| Skill | 说明 |
|
||
| ---------------------------------------------------------------------- | ------------------------------------------------- |
|
||
| [skiff](skills/skiff/SKILL.md) | 本项目工作流：创建、使用、反馈与更新 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。
|
||
|
||
### 规范包（Kits，不是 Skill）
|
||
|
||
`kits/` 放可复制到项目的流程规范、模板、检查清单和示例资料。它们不是 Agent Skill：
|
||
|
||
- 不放 `SKILL.md` frontmatter
|
||
- 不由 `skiff install` / `skiff add` 安装
|
||
- 不会被 Agent 自动触发加载
|
||
- 使用方式是复制到目标项目文档目录，或在目标项目 `AGENTS.md` 中引用
|
||
|
||
| Kit | 说明 | 推荐落地位置 |
|
||
| --- | --- | --- |
|
||
| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包 | `docs/agent-collaboration-kit/` |
|
||
|
||
新建规范包：创建 `kits/<name>/README.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. **类型分离** — `skills/` 只放可安装 skill；非 skill 的规范包、模板包放 `kits/`
|
||
5. **一体维护** — skill、规范包与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步
|
||
|
||
---
|
||
|
||
## 架构
|
||
|
||
```
|
||
skills 仓库（本仓库） skiff CLI
|
||
skills/<name>/ ←── skiff install / enable
|
||
kits/<name>/ ←── 手动复制 / 项目文档引用
|
||
skiff/ ←── python3 -m skiff
|
||
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` |
|
||
|
||
### 非 Skill 资料分类
|
||
|
||
| 类型 | 位置 | 维护方式 |
|
||
| --- | --- | --- |
|
||
| **Kit** | `kits/<name>/` | 本仓库 commit；复制到目标项目 `docs/` 或由项目 `AGENTS.md` 引用 |
|
||
| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 |
|
||
|
||
|
||
### 多 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 命令
|
||
|
||
详见 [skiff README](https://git.yumee.top/laily/skiff)。
|
||
|
||
### 已实现
|
||
|
||
|
||
| 命令 | 说明 |
|
||
| -------------------------------------- | ------------------- |
|
||
| `skiff bootstrap` | 将 skiff 项目 skill 全局安装到所有 Agent |
|
||
| `skiff list` | 列出所有 skill |
|
||
| `skiff status` | 安装状态总览 |
|
||
| `skiff install <name>` | 全局安装（symlink） |
|
||
| `skiff uninstall <name>` | 移除 symlink |
|
||
| `skiff add / fetch / install-external` | 外部 Git skill |
|
||
|
||
|
||
### 草稿与健康检查
|
||
|
||
|
||
| 命令 | 说明 |
|
||
| --- | --- |
|
||
| `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)
|