# pouch

创建、维护、安装和发布团队自研的 Agent Skill。唯一来源在 `~/.pouch/skills/<name>/`，装到各 Agent 时用软链。

## 什么时候使用

- 想把项目里的重复工作沉淀成一个 skill。
- 想完善、校验、转正或发布已有 skill。
- 想把自研 skill 安装到当前项目或全局 Agent。
- 想让 Agent 代装 pouch，或介绍有哪些 skill、在当前项目接入。
- 想检查并修复 skill 软链接。
- 想优化某个已有 skill 的结构，减少点中后灌进上下文的内容。

## 使用前准备

- 已把本仓库 clone 到 `~/.pouch` 并跑过 `./install.sh`（会把本 skill 装到所有 Agent）。
- Python 3；`~/.local/bin` 已加入 `PATH`。
- 至少一种 Agent：Cursor、Claude Code、Codex，或 agents 标准目录。
- 要推到远端时，本仓库的 git remote 可写。

CLI 命令细节见仓库里的 [pouch/README.md](../../pouch/README.md)。

## 使用示例

```text
帮我安装 pouch。
帮我装 https://git.yumee.top/laily/pouch
有哪些自研 skill，各用一句话介绍。
把这个项目该用的 skill 接上。
帮我把「评审 PR 时按这份清单走」做成一个自研 skill。
pouch 帮我检查 discussion-notes 这个 skill。
pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费。
把 ack 装到当前项目的 Cursor。
检查一下 skill 软链，坏了就修。
```

## 创建一个 skill

```bash
pouch create my-skill \
  --idea "描述这个 skill 要解决的重复问题" \
  --from-project .
```

命令会在 `~/.pouch/.drafts/my-skill/` 创建：

- `SKILL.md`：给 Agent 阅读的工作流与约束。
- `README.md`：给人类阅读的用途、准备事项、示例和完成标准。
- `brief.yaml`：草稿来源信息，转正时自动移除。

完善 `SKILL.md` 和 `README.md` 后运行：

```bash
pouch check my-skill
pouch finalize my-skill
```

转正不会自动 commit、push 或安装。

## 优化已有 skill 的结构

skill 能用但正文太长、所有模式写在一份 `SKILL.md` 里，或点中后把用不到的参考一并读进上下文时：

```text
pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费
```

Agent 会先测量该 skill 的体积，再按分层加载改 SSOT：`SKILL.md` 只留路由和全模式边界，细节按条件读 `references/`。不会为了缩字删掉发版、部署一类的安全限制。改完仍需 `pouch check` 通过。

不要对社区 catalog skill 的安装目录直接改；那些不是本仓库的 SSOT。

## 提交和发布

```bash
pouch publish skills/my-skill -m "add my-skill"
pouch publish skills/my-skill -m "add my-skill" --push
```

## 安装与维护

`./install.sh` 会执行 `pouch bootstrap`，把本 skill 全局装到所有 Agent。也可以随时重跑：

```bash
pouch bootstrap
```

安装其它 skill：

```bash
pouch add my-skill -a codex -y          # 当前项目的 Codex
pouch add my-skill -a codex -g -y       # 全局 Codex
pouch select                            # 交互多选，默认当前项目
pouch select -g                         # 交互多选，装到全局
```

项目状态初始化（目前用于 ack）：

```bash
pouch init ack
pouch init ack --project ~/app
```

builder / deployer 不要 `pouch init`，对 Agent 说「用 builder / deployer 初始化」。

软链出问题：

```bash
pouch status
pouch doctor
pouch doctor --fix
```

## Agent 会做什么

1. 本机还没有 `~/.pouch` 时，按安装剧本 clone 或链接，跑 `install.sh`，再介绍 builtin skill。
2. 在业务仓库里按文件信号建议 skill，`pouch add` 之后问一句要不要初始化 ack / builder / deployer。
3. 创建草稿到 `~/.pouch/.drafts/`，按你的想法完善 `SKILL.md` 和给人看的 `README.md`。
4. 跑 `pouch check`；你确认后再 `finalize` 到 `skills/`。
5. 安装只建指向 SSOT 的软链，不复制文件。默认装当前项目；只有你明确要求时才加 `-g`。
6. 优化结构时先测量再改 SSOT，不删发版、部署类安全限制。
7. 未要求时不 commit、不 push、不全局安装。

## 如何判断完成

- `pouch check <name>` 输出校验通过。
- 正式 skill 同时包含 `SKILL.md` 和 `README.md`。
- `pouch status` 或 `pouch doctor` 显示目标软链接正常。
- 代装完成后 CLI 可用，且介绍了 builtin skill 的一句话和示例请求。
- 项目接入后，建议的 skill 已 `pouch add`；ack / builder / deployer 要么已初始化，要么明确问过。
- 优化结构时：审计报告有前后体积，安全限制仍在 `SKILL.md`，没有为缩字删掉模式。