pouch

自研 Agent Skills 的单一事实来源（SSOT）。仓库、家目录 ~/.pouch 和 CLI 都叫 pouch。Skill 内容与 CLI 在本仓库一并维护。

快速开始

git clone https://git.yumee.top/laily/pouch.git ~/.pouch
cd ~/.pouch
./install.sh  # 安装 CLI，并将 pouch 项目 skill 安装到所有 Agent

pouch add declarative-openspec-loop -g
pouch select  # 交互式选择并批量安装
pouch list
pouch status

从旧的 ~/.skills / skiff 迁移：

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

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

仓库结构

skills/           # 自研 skill（SSOT）：每个子目录必须有 SKILL.md
pouch/            # CLI 源码（Python 3）
bin/pouch         # CLI 入口
catalog.yaml      # pouch 预置 Skill 来源目录
AGENTS.md         # 详细规范与架构说明

路径	说明
skills/	自研 skill，每个子目录含 SKILL.md，可附带 references、templates 和 scripts
pouch/	安装、软链、健康检查 CLI
catalog.yaml	pouch 预置 Skill 来源目录
AGENTS.md	设计原则、编写规范、架构详解

自研 Skill

Skill	说明
orc	显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位
ack	显式初始化、检查并运行 ACK 三角色协作及可选交付闭环
pouch	在项目中创建、安装、反馈和维护 builtin skill
declarative-openspec-loop	声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过
discussion-notes	讨论沉淀：边讨论边维护 Markdown 笔记

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

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

初始化会生成默认关闭的 .pouch/ack/delivery.yaml；项目可用自然语言让 /ack 维护 DEB、镜像、PR、发布与部署 profile，任务验证通过后再按已确认计划执行。

新建 skill：

pouch create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善 ~/.pouch/.drafts/my-skill/SKILL.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: declarative-openspec-loop
    source: builtin
  - name: think
    source: catalog:waza

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

pouch add declarative-openspec-loop
pouch sync
pouch remove declarative-openspec-loop

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 install / enable
├── 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 — 完整规范、多 Agent 路径、编写约定
• pouch/README.md — CLI 命令参考与开发说明

参考

• Agent Skills 开放标准
• Vercel skills CLI
• skills.sh
• Cursor Skills 文档