pouch
自研 Agent Skills 的单一事实来源（SSOT）。仓库、家目录 ~/.pouch 和 CLI 都叫 pouch。Skill 内容与 CLI 在本仓库一并维护。
pouch 本义是小袋子，这里取做锦囊妙计的锦囊：skill 就是里面的妙计。
给同事看怎么装、怎么打版本、怎么构建，读 docs/getting-started.md。人类用法看各 skill 的 README.md；SKILL.md 是给 Agent 的指令。用户要你代装时，读 skills/pouch/references/install.md 并执行，不要只把命令贴回去，也不要用 pouch select。
前置
- Python 3、git
- Cursor、Claude Code、Codex，或其它兼容 Agent Skills 的 Agent
~/.local/bin需要在PATH里（install.sh会写入 bash / zsh / fish 的 rc，当前 shell 要重开或source一次才生效）
快速开始
git clone https://git.yumee.top/laily/pouch.git ~/.pouch
cd ~/.pouch
./install.sh
# install.sh 会安装 pouch 命令，并把 pouch 这一个 skill 装到所有 Agent
# 若当前 shell 找不到 pouch：重开终端，或 source 对应 rc
pouch select # 交互选择要装的 skill（默认当前项目）
pouch select -g # 或装到全局，所有项目都能用
pouch list
pouch status
从旧的 ~/.skills / pouch 迁移：
mv ~/.skills ~/.pouch
~/.pouch/install.sh
install.sh 会安装 pouch 命令，并保留 pouch 作为旧命令别名。项目里已有的 .skills.yaml 仍可读取；新写入使用 .pouch.yaml。
让 Agent 代装
对 Agent 说「帮我安装 pouch」，或把仓库地址丢给它。步骤只维护在
skills/pouch/references/install.md：
确认 python3/git → 处理 ~/.pouch → install.sh → 用短清单介绍 skill → 问要装哪些。
不要用 pouch select。不要在未确认时覆盖已有的 ~/.pouch。
自己装仍看上面的「快速开始」。
装完之后怎么用
- 打开已安装目标的 Agent（Cursor / Claude Code / Codex 等）。
- 项目级安装：打开那个项目再说话。全局安装（
-g）：任意项目都可以。 - 按对应 skill 的 README，把示例请求发给 Agent。
./install.sh 只全局安装 pouch。其它 skill 都要 pouch add 或 pouch select。
cd ~/code/my-app
pouch add ack # 当前项目
pouch add discussion-notes -g # 全局
仓库结构
skills/ # 自研 skill（SSOT）：每个子目录含 SKILL.md 和 README.md
pouch/ # CLI 源码（Python 3）
bin/pouch # CLI 入口
catalog.yaml # pouch 预置 Skill 来源目录
AGENTS.md # 详细规范与架构说明
| 路径 | 说明 |
|---|---|
| skills/ | 自研 skill，每个子目录含给人看的 README.md 和给 Agent 的 SKILL.md |
| pouch/ | 安装、软链、健康检查 CLI |
| catalog.yaml | pouch 预置 Skill 来源目录 |
| AGENTS.md | 设计原则、编写规范、架构详解 |
自研 Skill
| 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 | 通过 Tailscale Serve 将静态文件暴露为 tailnet 内 HTTP 预览 |
| releaser | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
| specifier | 把复杂需求整理成多轮评审的 HTML PRD，并在批准后生成 ACK handoff |
| manage-release | 已弃用：releaser 的旧名兼容占位，不含流程 |
ACK 是包含规范、模板与校验脚本的完整 Skill。安装后可初始化当前项目状态：
pouch init ack
pouch init ack --project ~/app
初始化会生成默认关闭的 .pouch/ack/delivery.yaml 和空的 .pouch/ack/regression.yaml。
项目可用自然语言让 /ack 把测试环境绑到 deployer、维护发版 profile，并在任务
验证通过后收获回归用例。
builder 与 deployer 的项目接入走各自 skill 的「初始化」模式，不要 pouch init builder 或 pouch init deployer。
新建 skill：
pouch create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善 ~/.pouch/.drafts/my-skill/SKILL.md 和 README.md
pouch check my-skill
pouch finalize my-skill
pouch add my-skill -g # 全局安装验证
项目里使用 skill 发现通用问题或优化时，让 Agent 按 pouch skill 收集实际结果与期望结果，修改 ~/.pouch/skills/<name>/ 的 SSOT，并执行 pouch check <name>。项目专属规则保留在项目内，不回流到通用 skill。
安装方式
全局（用户级）
pouch add <name> -g # 安装到 ~/.cursor/skills/ 等
pouch add <name> -g -a cursor
项目级
在项目根目录维护 .pouch.yaml：
skills:
- name: ack
source: builtin
- name: think
source: catalog:waza
targets: # 可选，默认 all
- cursor
- claude
- codex
pouch add ack
pouch sync
pouch remove ack
Catalog 与 Custom Source
安装 catalog 中预置的来源：
pouch fetch waza
pouch add waza/think -g
接入团队自己的本地目录或 Git 仓库：
pouch source add company --local ~/code/company-skills --skills-path skills
pouch add company/internal-review -g
社区来源（Vercel CLI）：
npx skills add vercel-labs/agent-skills -g -y
npx skills find typescript
架构概览
本仓库
├── skills/<name>/ ←── pouch add / select
├── catalog.yaml ←── 预置来源发现与 fetch
└── pouch/ ←── python3 -m pouch
↑
~/.pouch（symlink）
│
┌────┴────────────────┐
▼ ▼
~/.cursor/skills/ project/.agents/skills/
~/.claude/skills/ project/.claude/skills/
~/.codex/skills/ project/.pouch.yaml
~/.agents/skills/ （agents 标准目录，覆盖 OMP）
设计原则
- SSOT — 自研 skill 只存在于
skills/<name>/ - 项目自治 — 各项目自行维护
.pouch.yaml - 软链优先 — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
- 能力内聚 — Skill 所需规范、模板和脚本与
SKILL.md放在同一目录 - 一体维护 — skill 与 CLI 同仓库，Python 3 直接运行，无需编译
文档
- docs/getting-started.md：给同事的安装、打版本、构建教程
- AGENTS.md — 完整规范、多 Agent 路径、编写约定
- pouch/README.md — CLI 命令参考与开发说明
- 各 skill 的人类说明见上表
README.md