158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
# 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 add declarative-openspec-loop -g
|
||
skiff select # 交互式选择并批量安装
|
||
skiff list
|
||
skiff status
|
||
```
|
||
|
||
## 仓库结构
|
||
|
||
```
|
||
skills/ # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
|
||
skiff/ # CLI 源码（Python 3）
|
||
bin/skiff # CLI 入口
|
||
catalog.yaml # skiff 预置 Skill 来源目录
|
||
AGENTS.md # 详细规范与架构说明
|
||
```
|
||
|
||
| 路径 | 说明 |
|
||
|------|------|
|
||
| [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md`，可附带 references、templates 和 scripts |
|
||
| [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI |
|
||
| [catalog.yaml](catalog.yaml) | skiff 预置 Skill 来源目录 |
|
||
| [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 |
|
||
|
||
## 自研 Skill
|
||
|
||
| Skill | 说明 |
|
||
|-------|------|
|
||
| [orc](skills/orc/SKILL.md) | 显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位 |
|
||
| [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
|
||
| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
|
||
| [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
|
||
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |
|
||
|
||
ACK 是包含规范、模板与校验脚本的完整 Skill。安装 Skill 后可初始化当前项目状态：
|
||
|
||
```bash
|
||
skiff init ack
|
||
skiff init ack --project ~/app
|
||
```
|
||
|
||
初始化会生成默认关闭的 `docs/ack/delivery.yaml`；项目可用自然语言让 `/ack` 维护
|
||
DEB、镜像、PR、发布与部署 profile，任务验证通过后再按已确认计划执行。
|
||
|
||
新建 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 add <name> -g # 安装到 ~/.cursor/skills/ 等
|
||
skiff add <name> -g -a cursor
|
||
```
|
||
|
||
### 项目级
|
||
|
||
在项目根目录维护 `.skills.yaml`：
|
||
|
||
```yaml
|
||
skills:
|
||
- name: declarative-openspec-loop
|
||
source: builtin
|
||
- name: think
|
||
source: catalog:waza
|
||
|
||
targets: # 可选，默认 all
|
||
- cursor
|
||
- claude
|
||
- codex
|
||
```
|
||
|
||
```bash
|
||
skiff add declarative-openspec-loop
|
||
skiff sync
|
||
skiff remove declarative-openspec-loop
|
||
```
|
||
|
||
## Catalog 与 Custom Source
|
||
|
||
安装 catalog 中预置的来源：
|
||
|
||
```bash
|
||
skiff fetch waza
|
||
skiff add waza/think -g
|
||
```
|
||
|
||
接入团队自己的本地目录或 Git 仓库：
|
||
|
||
```bash
|
||
skiff source add company --local ~/code/company-skills --skills-path skills
|
||
skiff add company/internal-review -g
|
||
```
|
||
|
||
**社区来源**（Vercel CLI）：
|
||
|
||
```bash
|
||
npx skills add vercel-labs/agent-skills -g -y
|
||
npx skills find typescript
|
||
```
|
||
|
||
## 架构概览
|
||
|
||
```
|
||
本仓库
|
||
├── skills/<name>/ ←── skiff install / enable
|
||
├── catalog.yaml ←── 预置来源发现与 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 所需规范、模板和脚本与 `SKILL.md` 放在同一目录
|
||
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)
|