# pouch

自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。仓库、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。Skill 内容与 CLI 在本仓库一并维护。

pouch 本义是小袋子，这里取做锦囊妙计的锦囊：skill 就是里面的妙计。

给同事看怎么装、怎么打版本、怎么构建，读 [docs/getting-started.md](docs/getting-started.md)。人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，读 [skills/pouch/references/install.md](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` 一次才生效）

## 快速开始

```bash
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` 迁移：

```bash
mv ~/.skills ~/.pouch
~/.pouch/install.sh
```

`install.sh` 会安装 `pouch` 命令，并保留 `pouch` 作为旧命令别名。项目里已有的 `.skills.yaml` 仍可读取；新写入使用 `.pouch.yaml`。

## 让 Agent 代装

对 Agent 说「帮我安装 pouch」，或把仓库地址丢给它。步骤只维护在
[skills/pouch/references/install.md](skills/pouch/references/install.md)：
确认 python3/git → 处理 `~/.pouch` → `install.sh` → 用短清单介绍 skill → 问要装哪些。
不要用 `pouch select`。不要在未确认时覆盖已有的 `~/.pouch`。

自己装仍看上面的「快速开始」。

## 装完之后怎么用

1. 打开已安装目标的 Agent（Cursor / Claude Code / Codex 等）。
2. 项目级安装：打开那个项目再说话。全局安装（`-g`）：任意项目都可以。
3. 按对应 skill 的 README，把示例请求发给 Agent。

`./install.sh` 只全局安装 `pouch`。其它 skill 都要 `pouch add` 或 `pouch select`。

```bash
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/](skills/)           | 自研 skill，每个子目录含给人看的 `README.md` 和给 Agent 的 `SKILL.md` |
| [pouch/](pouch/README.md)    | 安装、软链、健康检查 CLI                                        |
| [catalog.yaml](catalog.yaml) | pouch 预置 Skill 来源目录                                   |
| [AGENTS.md](AGENTS.md)       | 设计原则、编写规范、架构详解                                        |


## 自研 Skill


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


ACK 是包含规范、模板与校验脚本的完整 Skill。安装后可初始化当前项目状态：

```bash
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：

```bash
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。

## 安装方式

### 全局（用户级）

```bash
pouch add <name> -g                   # 安装到 ~/.cursor/skills/ 等
pouch add <name> -g -a cursor
```

### 项目级

在项目根目录维护 `.pouch.yaml`：

```yaml
skills:
  - name: ack
    source: builtin
  - name: think
    source: catalog:waza

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

```bash
pouch add ack
pouch sync
pouch remove ack
```

## Catalog 与 Custom Source

安装 catalog 中预置的来源：

```bash
pouch fetch waza
pouch add waza/think -g
pouch add taste-skill/taste-skill -g   # 只要核心 frontend skill
pouch add taste-skill -g               # 或装整个 Taste Skill collection
```

接入团队自己的本地目录或 Git 仓库：

```bash
pouch source add company --local ~/code/company-skills --skills-path skills
pouch add company/internal-review -g
```

**社区来源**（Vercel CLI）：

```bash
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）
```

## 设计原则

1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`
2. **项目自治** — 各项目自行维护 `.pouch.yaml`
3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
4. **能力内聚** — Skill 所需规范、模板和脚本与 `SKILL.md` 放在同一目录
5. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译

## 文档

- [docs/getting-started.md](docs/getting-started.md)：给同事的安装、打版本、构建教程
- [AGENTS.md](AGENTS.md) — 完整规范、多 Agent 路径、编写约定
- [pouch/README.md](pouch/README.md) — CLI 命令参考与开发说明
- 各 skill 的人类说明见上表 `README.md`

## 参考

- [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)