laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
58de2650c2d9330f9f27787a4900845474be30c2
.pouch/AGENTS.md
T
laily 58de2650c2 docs: separate agent collaboration kit from skills 
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-07-06 09:32:50 +08:00

11 KiB
Raw Blame History

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 ~/code/gitea/skills
git clone https://git.yumee.top/laily/skiff.git ~/code/gitea/skiff
cd ~/code/gitea/skiff && ./install.sh
skiff setup ~/code/gitea/skills

# 2. 全局安装 skill
skiff install declarative-openspec-loop

# 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 说明
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.md frontmatter
  • 不由 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

设计原则

  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，不由本仓库管理：

# .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

项目级命令（skiff 待实现）：

cd ~/code/my-app
skiff enable declarative-openspec-loop
skiff disable declarative-openspec-loop
skiff sync

skiff 命令

详见 skiff README。

已实现

命令 说明
skiff setup <path> 关联 ~/.skills 到本仓库
skiff list 列出所有 skill
skiff status 安装状态总览
skiff install <name> 全局安装（symlink）
skiff uninstall <name> 移除 symlink
skiff add / fetch / install-external 外部 Git skill

待实现

命令 说明
skiff enable / disable 项目级启用/关闭
skiff sync 按 .skills.yaml 重建 symlink
skiff create 从 _template/ 脚手架创建 skill
skiff doctor symlink 健康检查

Skill 编写规范

遵循 Agent Skills 开放标准：

skill-name/
├── SKILL.md          # 必需
├── reference.md      # 可选
├── examples.md       # 可选
└── scripts/          # 可选

Frontmatter

---
name: skill-name
description: >-
  做什么、何时触发。description 是 Agent 决定是否加载的唯一依据，务必写清触发关键词。
---

命名

  • 目录名 = frontmatter name
  • 小写 + 连字符：security-review
  • 禁止 camelCase、空格、下划线

新建流程

  1. cp -r skills/_template skills/my-skill
  2. 编辑 skills/my-skill/SKILL.md
  3. skiff install my-skill --target cursor 验证
  4. 在本仓库 commit
  5. 各项目 skiff enable 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（待实现）→ 重建 symlink

工具分工

场景 工具
自研 skill 安装/管理 skiff
社区 skill 安装 Vercel npx skills add
NPM 包内 skill skills-npm / skill-indexer
搜索发现 npx skills find / skills.sh

日常速查

我要… 命令 在哪
首次 setup skiff setup ~/code/gitea/skills 任意
新建 skill 复制 _template/ → 编辑 → commit 本仓库
全局启用 skiff install <name> 任意
项目启用 skiff enable <name> 项目目录
看状态 skiff status 任意
装社区 skill npx skills add owner/repo -g -y 任意
更新外部 skill skiff fetch <name> 任意

参考

Reference in New Issue View Git Blame Copy Permalink