laily
c2d6a5a0d7
Redeploy locally with docker compose when the node is 127.0.0.1 and the image already exists. Make list/sync/remote/deb importable under python3 -I -S. Add human README.md for every builtin skill, slim ack's user-facing docs, and drop unused OpenSpec config.
255 lines
8.8 KiB
Markdown
255 lines
8.8 KiB
Markdown
# pouch
|
||
|
||
自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。仓库、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。Skill 内容与 CLI 在本仓库一并维护。
|
||
|
||
人类用法看各 skill 的 `README.md`；`SKILL.md` 是给 Agent 的指令。用户要你代装时，按 [让 Agent 代装](#让-agent-代装) 自己执行，不要只把命令贴回去。
|
||
|
||
## 前置
|
||
|
||
- 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 代装
|
||
|
||
用户说「帮我安装 pouch」「把 skill 装上」时按本节做。CLI 只认 `~/.pouch`。不要用 `pouch select`（必须交互式 TTY）。不要在未确认时覆盖已有的 `~/.pouch`。
|
||
|
||
### 1. 确认本机
|
||
|
||
需要 `python3` 和 `git`。缺了先说明怎么装，不要继续。
|
||
|
||
### 2. 让 `~/.pouch` 指向本仓库
|
||
|
||
按现状只走一条：
|
||
|
||
| 现状 | 动作 |
|
||
| --- | --- |
|
||
| 当前目录就是这份仓库（有 `install.sh` 和 `skills/`），且没有 `~/.pouch` | `ln -sfn "$(pwd)" "$HOME/.pouch"` |
|
||
| `~/.pouch` 已在且含 `skills/`、`install.sh` | 沿用 |
|
||
| 只有 `~/.skills` | `mv ~/.skills ~/.pouch` |
|
||
| 都没有 | `git clone https://git.yumee.top/laily/pouch.git ~/.pouch`。失败则问用户本地路径或可用 remote |
|
||
| `~/.pouch` 在，但不是这份仓库 | 停下问用户，不要删、不要覆盖 |
|
||
|
||
### 3. 装 CLI 和 `pouch` skill
|
||
|
||
```bash
|
||
"$HOME/.pouch/install.sh"
|
||
export PATH="$HOME/.local/bin:$PATH"
|
||
command -v pouch
|
||
pouch status
|
||
```
|
||
|
||
`install.sh` 会改 rc，当前会话仍要 `export PATH`。不要让用户重开终端才继续。
|
||
|
||
### 4. 安装用户要的其它 skill
|
||
|
||
先 `pouch add --list`。用户没点名就问一次：装哪些、全局还是当前项目。能判断就不要追问。
|
||
|
||
```bash
|
||
pouch add <name> -g -y # 全局，所有项目都能用
|
||
pouch add <name> -y # 仅当前项目
|
||
```
|
||
|
||
默认 `pouch add` 装到当前工作目录。cwd 是 pouch 仓库本身时用 `-g`，除非用户就在维护 pouch。用户是在自己的应用仓库里请你代装，才做项目级安装。
|
||
|
||
`install.sh` 已经全局装好 `pouch` skill。其它 skill 不要默认全装。
|
||
|
||
### 5. 验收并告诉用户下一步
|
||
|
||
```bash
|
||
pouch status
|
||
pouch doctor
|
||
```
|
||
|
||
说明：打开 Cursor / Claude Code / Codex 后，按各 skill README 里的示例说话即可。软链异常则 `pouch doctor --fix`。已经装好时只汇报状态，问还要不要加 skill，不要重新 clone。
|
||
|
||
## 装完之后怎么用
|
||
|
||
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 低保真原型和用户动线 |
|
||
| [manage-release](skills/manage-release/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
|
||
| [memory-distill](skills/memory-distill/README.md) | 任务结束后把可复用结论写入通用记忆和项目记忆 |
|
||
| [orc](skills/orc/README.md) | 把开发、发版、DEB / Docker 意图编排成阶段，按档位分发给对应 skill |
|
||
| [pouch](skills/pouch/README.md) | 创建、校验、安装和维护 builtin skill |
|
||
|
||
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
|
||
```
|
||
|
||
接入团队自己的本地目录或 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 直接运行，无需编译
|
||
|
||
## 文档
|
||
|
||
- [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)
|