laily
a15a046e4e
Promote ship to the user-facing delivery skill. Kind is short or long from an explicit mode, then self-judgment, then a question, defaulting to short. Old names remain deprecation stubs.
371 lines
14 KiB
Markdown
371 lines
14 KiB
Markdown
# pouch
|
||
|
||
自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。仓库名、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。旧名是 `skills` / `pouch`。
|
||
|
||
|
||
| 仓库 | 地址 | 职责 |
|
||
| --------------- | ------------------------------------------------------------------------ | -------------------------- |
|
||
| **pouch**（本仓库） | [https://git.yumee.top/laily/pouch](https://git.yumee.top/laily/pouch) | skill、规范包、pouch CLI 的当前 SSOT |
|
||
|
||
|
||
---
|
||
|
||
## 快速开始
|
||
|
||
需要 Python 3、git，以及 Cursor / Claude Code / Codex 或其它兼容 Agent Skills 的 Agent。人类用法见根 [README.md](README.md) 和各 skill 的 `README.md`。用户要代装时：pouch skill 已安装则走其「安装 pouch」模式；否则读 [skills/pouch/references/install.md](skills/pouch/references/install.md) 并执行。不要只用 `pouch select`。
|
||
|
||
```bash
|
||
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](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/静态文件预览，返回 URL 并复用已有服务 |
|
||
| [pr-ship](skills/pr-ship/README.md) | 把已有 PR 从检查、合并推进到回归、构建和部署 |
|
||
| [releaser](skills/releaser/README.md) | 给已准备好的 commit 发版本：更新说明、tag、可选 Forge Release |
|
||
| [ship](skills/ship/README.md) | 把一次变更从说明推进到配置允许的 PR、合并或部署；short 或 long |
|
||
| [short-ship](skills/short-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
|
||
| [long-ship](skills/long-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
|
||
| [specifier](skills/specifier/README.md) | 把复杂需求整理成多轮评审的 HTML PRD，批准后交给 ship |
|
||
| [delivery-loop](skills/delivery-loop/README.md) | ship 与 pr-ship 共用的验证到部署状态机 |
|
||
| [manage-release](skills/manage-release/README.md) | 已弃用：`releaser` 的旧名兼容占位，不含流程 |
|
||
| [bugfix-ship](skills/bugfix-ship/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
|
||
| [requirement-flow](skills/requirement-flow/README.md) | 已弃用：`ship` 的旧名兼容占位，不含流程 |
|
||
|
||
改名后旧名保留一个纯占位 skill，避免已装软链悬空和旧项目 `.pouch.yaml` 失效。确认没有
|
||
项目再按旧名启用后，删除对应占位目录即可，不丢任何内容。
|
||
|
||
|
||
新建 skill：优先 `pouch create`；或复制 `skills/_template/` → `skills/<name>/`，编辑 `SKILL.md` 和 `README.md`，在本仓库 commit。
|
||
|
||
Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目录中，例如
|
||
`skills/ack/references/`、`templates/`、`examples/` 和 `scripts/`。项目初始化只生成
|
||
项目状态，不复制或链接 Skill 内容：
|
||
|
||
```bash
|
||
pouch init ack
|
||
```
|
||
|
||
builder 与 deployer 的项目接入走各自 skill 的「初始化」模式（检查配置并引导补齐），
|
||
不要 `pouch init builder` / `pouch init deployer`。
|
||
|
||
### 预置目录（Catalog）
|
||
|
||
在 `catalog.yaml` 中预置，通过 pouch 拉取安装：
|
||
|
||
|
||
| Source | 来源 |
|
||
| --- | --- |
|
||
| waza | [https://github.com/tw93/Waza](https://github.com/tw93/Waza) |
|
||
| taste-skill | [https://github.com/Leonxlnx/taste-skill](https://github.com/Leonxlnx/taste-skill) |
|
||
|
||
|
||
```bash
|
||
pouch fetch waza
|
||
pouch add waza/think -g
|
||
pouch add taste-skill/taste-skill -g
|
||
```
|
||
|
||
### 自定义仓库（Custom Sources）
|
||
|
||
公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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：
|
||
|
||
```bash
|
||
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`，不由本仓库管理：
|
||
|
||
```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` |
|
||
|
||
|
||
项目级命令：
|
||
|
||
```bash
|
||
cd ~/code/my-app
|
||
pouch enable declarative-openspec-loop
|
||
pouch disable declarative-openspec-loop
|
||
pouch sync
|
||
```
|
||
|
||
---
|
||
|
||
## pouch 命令
|
||
|
||
详见 [pouch README](https://git.yumee.top/laily/pouch)。
|
||
|
||
### 已实现
|
||
|
||
|
||
| 命令 | 说明 |
|
||
| -------------------------------------- | ------------------- |
|
||
| `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 开放标准](https://agentskills.io)：
|
||
|
||
```
|
||
skill-name/
|
||
├── SKILL.md # 必需，给 Agent
|
||
├── README.md # 必需，给人类
|
||
├── reference.md # 可选
|
||
├── examples.md # 可选
|
||
└── scripts/ # 可选
|
||
```
|
||
|
||
### Frontmatter
|
||
|
||
```yaml
|
||
---
|
||
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](https://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 开放标准](https://agentskills.io)
|
||
- [pouch CLI](https://git.yumee.top/laily/pouch)
|
||
- [Vercel skills CLI](https://github.com/vercel-labs/skills)
|
||
- [skills.sh](https://skills.sh)
|
||
- [Cursor Skills 文档](https://cursor.com/docs/context/skills)
|