.pouch/AGENTS.md

pouch

自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。仓库名、家目录 ~/.pouch 和 CLI 都叫 pouch。旧名是 skills / pouch。

仓库	地址	职责
pouch（本仓库）	https://git.yumee.top/laily/pouch	skill、规范包、pouch CLI 的当前 SSOT

---

快速开始

需要 Python 3、git，以及 Cursor / Claude Code / Codex 或其它兼容 Agent Skills 的 Agent。人类用法见根 README.md 和各 skill 的 README.md。用户要代装时：pouch skill 已安装则走其「安装 pouch」模式；否则读 skills/pouch/references/install.md 并执行。不要只用 pouch select。

git clone https://git.yumee.top/laily/pouch.git ~/.pouch
cd ~/.pouch && ./install.sh

# install.sh 只把 pouch skill 装到所有 Agent；其它 skill 用 select / add
pouch select -g
pouch list
pouch status

---

仓库结构

skills/           # 自研 skill（SSOT）：每个子目录含 SKILL.md（Agent）和 README.md（人类）
pouch/            # CLI 源码（Python 3）
bin/pouch         # CLI 入口
catalog.yaml      # pouch 预置 Skill 来源目录
AGENTS.md         # 本文档

本仓库包含：skills/、pouch/、bin/pouch、catalog.yaml、AGENTS.md 本仓库不包含：各项目的 skill 启用清单

---

Skill 目录

内置（Builtin）

Skill	说明
ack	显式初始化、检查并运行三角色闭环：需求 / bug、测试环境、发版与回归
builder	按统一契约构建和发布 DEB / Docker 镜像
declarative-openspec-loop	你给校验方式，Agent 自动 propose / apply / 校验直到通过
deployer	用 Git 里的 Compose 或 Argo CD 清单部署服务
discussion-notes	边讨论边维护 Markdown 笔记
draw-prototype-flow	把产品想法画成可编辑的 Draw.io 低保真原型和用户动线
eli5	用大图少字的单页 HTML 把话题讲给完全没背景的人听
host-sec-check	对 Linux/VPS 做入侵取向的安全检查，默认只出报告
memory-distill	任务结束后把可复用结论写入通用记忆和项目记忆
note-style	把材料整理成可长期查阅的知识笔记
orc	把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill
pouch	创建、校验、安装和维护 builtin skill
previewer	用 Node 提供 HTML/静态文件预览，返回 URL 并复用已有服务
pr-ship	把已有 PR 从检查、合并推进到回归、构建和部署
releaser	给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release
ship	把一次变更从说明推进到配置允许的 PR、合并或部署；short 或 long
short-ship	已弃用：ship 的旧名兼容占位，不含流程
long-ship	已弃用：ship 的旧名兼容占位，不含流程
specifier	把复杂需求整理成多轮评审的 HTML PRD，批准后交给 ship
delivery-loop	ship 与 pr-ship 共用的验证到部署状态机
manage-release	已弃用：releaser 的旧名兼容占位，不含流程
bugfix-ship	已弃用：ship 的旧名兼容占位，不含流程
requirement-flow	已弃用：ship 的旧名兼容占位，不含流程

改名后旧名保留一个纯占位 skill，避免已装软链悬空和旧项目 .pouch.yaml 失效。确认没有 项目再按旧名启用后，删除对应占位目录即可，不丢任何内容。

新建 skill：优先 pouch create；或复制 skills/_template/ → skills/<name>/，编辑 SKILL.md 和 README.md，在本仓库 commit。

Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如 skills/ack/references/、templates/、examples/ 和 scripts/。项目初始化只生成 项目状态，不复制或链接 Skill 内容：

pouch init ack

builder 与 deployer 的项目接入走各自 skill 的「初始化」模式（检查配置并引导补齐）， 不要 pouch init builder / pouch init deployer。

预置目录（Catalog）

在 catalog.yaml 中预置，通过 pouch 拉取安装：

Source	来源
waza	https://github.com/tw93/Waza
taste-skill	https://github.com/Leonxlnx/taste-skill

pouch fetch waza
pouch add waza/think -g
pouch add taste-skill/taste-skill -g

自定义仓库（Custom Sources）

公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：

pouch source add company \
  git@git.company.com:platform/agent-skills.git \
  --skills-path skills
pouch list --source company
pouch add company/internal-review -g

也可以接入已有本地 checkout：

pouch source add company --local ~/code/company-skills --skills-path skills

配置保存在 ~/.config/pouch/config.yaml，Git source 默认 clone 到 ~/.local/share/pouch/sources/<source>/。项目 .pouch.yaml 只记录逻辑 source 名称，每台机器独立配置实际仓库地址。

社区（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. 项目自治 — 每个项目自己维护 .pouch.yaml，本仓库不维护项目清单
3. 软链优先 — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
4. 能力内聚 — Skill 使用的规范、模板和脚本与 SKILL.md 同目录维护
5. 一体维护 — skill 与 CLI 同仓库维护

---

架构

pouch 仓库（本仓库）              pouch CLI
skills/<name>/              ←──   pouch install / enable
pouch/                      ←──   python3 -m pouch
catalog.yaml               ←──   pouch add / fetch
         ↑
    ~/.pouch（symlink）
         │
    ┌────┴────┐
    ▼         ▼
~/.cursor/skills/     project/.agents/skills/
~/.claude/skills/     project/.claude/skills/
~/.codex/skills/      project/.pouch.yaml
~/.agents/skills/     （agents 标准目录，覆盖 OMP）

Skill 三层分类

层级	位置	维护方式
Builtin	skills/<name>/	本仓库 commit
Catalog	catalog.yaml + checkout 缓存	pouch catalog add / fetch
Custom Source	~/.local/share/pouch/sources/ 或本地路径	pouch source add/fetch
External NPM	node_modules/	npx skills add / skills-npm

多 Agent 路径

Agent	全局	项目
Cursor	~/.cursor/skills/	.agents/skills/
Claude Code	~/.claude/skills/	.claude/skills/
Codex	~/.codex/skills/	.agents/skills/
Agents 标准	~/.agents/skills/	.agents/skills/（与 cursor/codex 共用；覆盖 OMP）

---

项目级启用

每个项目自己维护 .pouch.yaml，不由本仓库管理：

# .pouch.yaml（在项目根目录）
skills:
  - name: declarative-openspec-loop
    source: builtin
  - name: think
    source: catalog:waza
  - name: internal-review
    source: company

targets:          # 可选，默认 all
  - cursor
  - claude
  - codex

概念	类比
pouch 仓库	npm registry
.pouch.yaml	package.json dependencies
pouch enable	npm install
pouch sync	npm ci

项目级命令：

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

---

pouch 命令

详见 pouch README。

已实现

命令	说明
pouch bootstrap	将 pouch 项目 skill 全局安装到所有 Agent
pouch list	列出所有 skill
pouch status	安装状态总览
pouch add <name> [-g]	项目或全局安装（symlink）
pouch remove <name> [-g]	移除 symlink
pouch catalog add / pouch fetch	管理和拉取 catalog source
pouch update	更新 pouch 自身和已拉取的 catalog / custom source

草稿与健康检查

命令	说明
pouch create <name> --idea TEXT [--from-project PATH]	从 _template/ 创建草稿
pouch check <name>	校验草稿或正式 skill
pouch finalize <name>	校验并将草稿转为正式 skill
pouch doctor [--fix]	symlink 健康检查与修复

---

Skill 编写规范

遵循 Agent Skills 开放标准：

skill-name/
├── SKILL.md          # 必需，给 Agent
├── README.md         # 必需，给人类
├── reference.md      # 可选
├── examples.md       # 可选
└── scripts/          # 可选

Frontmatter

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

命名

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

新建流程

1. pouch create my-skill --idea "..." --from-project .
2. Agent 编辑 ~/.pouch/.drafts/my-skill/SKILL.md 和 README.md
3. pouch check my-skill
4. 用户确认后执行 pouch finalize my-skill
5. pouch add my-skill -a cursor -g -y 验证
6. 在本仓库 commit；需要的项目再用 pouch add my-skill 启用

禁止在 ~/.cursor/skills/ 或项目 Agent 目录直接创建非 symlink 的 skill。

---

Skill 修改回流

symlink 正确时，Agent 在项目里改 skill 文件 = 直接改 SSOT：

project/.agents/skills/foo/SKILL.md
  → ~/.pouch/skills/foo/SKILL.md
  → 在本仓库 commit

---

Claude Code 注意事项

Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入时将 symlink 替换成普通文件。

场景	建议
Cursor / Codex	symlink，正常
Claude Code	symlink 单个 skill 目录，不要 symlink 整个 ~/.claude/skills/
symlink 被替换	pouch doctor --fix → 重建 symlink

---

工具分工

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

---

日常速查

我要…	命令	在哪
首次安装	git clone <repo> ~/.pouch && ~/.pouch/install.sh	任意
让 Agent 代装	说「帮我安装 pouch」或丢仓库 URL	任意
介绍 / 接入 skill	说「有哪些 skill」或「把这个项目该用的 skill 接上」	项目目录
新建 skill	pouch create → Agent 完善 → check/finalize	任意项目
全局启用	pouch add <name> -g	任意
项目启用	pouch add <name> 或 pouch enable <name>	项目目录
看状态	pouch status	任意
装社区 skill	npx skills add owner/repo -g -y	任意
更新外部 skill	pouch fetch <name> 或日常命令自动更新	任意

---

参考

• Agent Skills 开放标准
• pouch CLI
• Vercel skills CLI
• skills.sh
• Cursor Skills 文档