11 KiB
11 KiB
Agent Skills 仓库
自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。
| 仓库 | 地址 | 职责 |
|---|---|---|
| skills（本仓库） | https://git.yumee.top/laily/skills | skill、规范包、skiff CLI 的当前 SSOT |
| skiff | https://git.yumee.top/laily/skiff | skiff CLI 的独立来源 / 上游同步参考 |
快速开始
# 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 | 本项目工作流：创建、使用、反馈与更新 owned skill |
| declarative-openspec-loop | 声明式编程循环：用户提供校验方式，Agent 自动 propose/apply/校验并迭代直到通过 |
| discussion-notes | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |
新建 skill：复制 skills/_template/ → skills/<name>/，编辑 SKILL.md，在本仓库 commit。
规范包（Kits，不是 Skill）
kits/ 放可复制到项目的流程规范、模板、检查清单和示例资料。它们不是 Agent Skill：
- 不放
SKILL.mdfrontmatter - 不由
skiff install/skiff add安装 - 不会被 Agent 自动触发加载
- 使用方式是复制到目标项目文档目录，或在目标项目
AGENTS.md中引用
| Kit | 说明 | 推荐落地位置 |
|---|---|---|
| agent-collaboration-kit | 多 Agent 协作闭环规范包 | docs/agent-collaboration-kit/ |
新建规范包：创建 kits/<name>/README.md，写清适用场景、复制到项目后的推荐目录、需要项目填充的占位符，并在本仓库 commit。
外部（External Git）
在 registry.yaml 中注册，通过 skiff 拉取安装：
| Skill | 来源 |
|---|---|
| superpowers | https://github.com/obra/superpowers |
skiff fetch superpowers
skiff install-external superpowers
社区（External NPM / GitHub）
推荐使用 Vercel CLI 安装第三方 skill：
npx skills add vercel-labs/agent-skills -g -y
npx skills find typescript
设计原则
- SSOT — 自研 skill 只存在于
skills/<name>/，不在 Agent 目录直接创建 - 项目自治 — 每个项目自己维护
.skills.yaml，本仓库不维护项目清单 - 软链优先 — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
- 类型分离 —
skills/只放可安装 skill；非 skill 的规范包、模板包放kits/ - 一体维护 — 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，不由本仓库管理：
# .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 |
项目级命令：
cd ~/code/my-app
skiff enable declarative-openspec-loop
skiff disable declarative-openspec-loop
skiff sync
skiff 命令
详见 skiff README。
已实现
| 命令 | 说明 |
|---|---|
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 编写规范
skill-name/
├── SKILL.md # 必需
├── reference.md # 可选
├── examples.md # 可选
└── scripts/ # 可选
Frontmatter
---
name: skill-name
description: >-
做什么、何时触发。description 是 Agent 决定是否加载的唯一依据，务必写清触发关键词。
---
命名
- 目录名 = frontmatter
name - 小写 + 连字符：
security-review - 禁止 camelCase、空格、下划线
新建流程
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 -a cursor -g -y验证- 在本仓库 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 |
日常速查
| 我要… | 命令 | 在哪 |
|---|---|---|
| 首次安装 | 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> |
任意 |