.pouch/pouch/README.md

pouch

Agent Skills 安装与管理 CLI。纯 Python 3 实现，无第三方依赖，无需编译。

安装

cd /path/to/pouch   # 本仓库根目录
./install.sh         # 软链到 ~/.local/bin/pouch

确保 ~/.local/bin 在 PATH 中。

命令风格

接口对齐 Vercel skills CLI 的 add / remove， 统一管理 builtin skill、预置 catalog source 和用户命名的 custom source。

# 浏览可用自研 skill
pouch add --list

# 装到当前项目 / 全局
pouch add discussion-notes -a cursor -y
pouch add discussion-notes -a cursor -g -y

# 卸载
pouch remove discussion-notes -a cursor -y
pouch rm discussion-notes -g -y

# 改完 skill 后提交推送（在任意目录执行，操作 ~/.pouch）
pouch publish skills/discussion-notes -m "update discussion-notes" --push

开发时也可直接运行：

PYTHONPATH=/path/to/pouch python3 -m pouch <command>

首次安装

git clone https://git.yumee.top/laily/pouch.git ~/.pouch
~/.pouch/install.sh

install.sh 会安装 CLI，并自动执行 pouch bootstrap，将本仓库的 pouch skill 全局软链到 Cursor、Claude Code 和 Codex。也可以随时手动重跑：

pouch bootstrap

命令参考

查看

命令	说明
pouch list [--source NAME]	列出所有来源或指定 source 中的 skill
pouch status [--target all|cursor|claude|codex|agents]	安装状态总览

项目初始化

命令	说明
pouch bootstrap	将本项目的 pouch skill 全局安装到所有 Agent
pouch update	在 ~/.pouch 执行 git pull，更新 pouch 自身
pouch init <name> [--project DIR]	使用 builtin skill 自带模板初始化项目状态（目前用于 ack）

Skill 安装

命令	说明
pouch add <name> [--global] [-a AGENT...] [-y]	安装到 Agent 目录（软链）
pouch select [--global] [-a AGENT...]	打开终端多选界面，批量安装 skill
pouch remove <name> [--global] [-a AGENT...] [-y]	移除软链（rm / r 别名）
pouch add --list	列出可用 builtin skill
pouch publish [paths] -m MSG [--push]	在 ~/.pouch 内 git add/commit/push

旧命令 install / uninstall 已移除，请改用 add / remove。

全局目标路径：

Agent	路径
cursor	~/.cursor/skills/
claude	~/.claude/skills/
codex	~/.codex/skills/
agents	~/.agents/skills/（agents 标准目录，覆盖 OMP）

预置 Catalog Source

命令	说明
pouch catalog add <name> <repo-url> [--ref main] [--path .]	写入 catalog.yaml
pouch fetch <name>	克隆或更新 catalog source checkout
pouch add <name> [-g] [-a AGENT...]	安装 catalog 中的单个 skill 或完整 collection（缺失时自动 fetch）
pouch add <collection>/<skill> [...]	只安装 collection 中指定的 skill

catalog.yaml 条目可额外提供 description 和 tags。description 会显示在 pouch select 的候选列表中。path 可以直接指向含 SKILL.md 的单个 skill，也可以指向由多个 skill 目录组成的 collection。 collection 会自动发现下一层所有含 SKILL.md 的目录；pouch add <name> 安装全部，pouch select 则展开为 <name>/<skill> 供分别勾选。同一 repo 与 ref 共享一份 Git checkout。

交互式批量安装

pouch select                         # 当前项目，全部 Agent
pouch select -a codex                # 当前项目，仅 Codex
pouch select -g                      # 全局安装
pouch select --project ~/code/app    # 指定项目

使用方向键移动、空格勾选、/ 搜索、Enter 安装，按 q 或 Esc 取消。普通 pouch select 只安装到项目，并在每一项旁只读显示各 Agent 的 全局安装状态；pouch select -g 只安装到全局。已经安装到目标范围的 skill 默认勾选；取消勾选不会卸载已有 skill，卸载请使用 pouch remove。如果全局 存在同名但指向其它来源的 skill，项目选择器会显示“全局同名冲突”。 项目模式会把成功选择的项目写入 .pouch.yaml。非交互环境请使用 pouch add <name>...。使用 -a 限定 Agent 时，该范围会记录在对应的 skill 条目中，后续 pouch sync 不会扩散到其他 Agent。

Custom source（多-skill 仓库）

公司或团队维护的仓库通常包含多个 skill。使用命名 source 接入：

# Git 仓库，默认 clone 到 ~/.local/share/pouch/sources/company
pouch source add company \
  git@git.company.com:platform/agent-skills.git \
  --ref main \
  --skills-path internal/skills

# 或接入已有本地仓库
pouch source add company \
  --local ~/code/company-agent-skills \
  --skills-path skills

pouch source list
pouch source fetch company
pouch list --source company
pouch add company/code-review -g -a codex

命令	说明
pouch source add <name> <repo> [--ref REF] [--checkout PATH] [--skills-path PATH]	注册并克隆 Git source
pouch source add <name> --local PATH [--skills-path PATH]	接入已有本地仓库
pouch source list / show <name>	查看 source
pouch source fetch <name> / fetch --all	clone 或 fast-forward 更新
pouch source remove <name>	移除配置并保留 checkout

配置保存在 ~/.config/pouch/config.yaml。Git/SSH 认证复用本机 Git 配置， pouch 不保存 token。可以使用 company/code-review，也可以使用 pouch add code-review --source company。多个来源包含同名 skill 时，必须明确来源。

项目级

命令	说明
pouch enable <name> [--target all] [--project <dir>]	写入 .pouch.yaml 并创建项目软链
pouch disable <name> [--target all] [--project <dir>]	从 manifest 移除并删除软链
pouch sync [--target all] [--project <dir>]	按 .pouch.yaml 重建软链

项目目标路径：

Agent	路径
cursor	<project>/.agents/skills/
claude	<project>/.claude/skills/
codex	<project>/.agents/skills/
agents	<project>/.agents/skills/（与 cursor/codex 共用路径，软链幂等）

脚手架与健康检查

命令	说明
pouch create <name> [--idea TEXT] [--from-project PATH]	从模板创建含 SKILL.md、README.md 的草稿
pouch check <name>	校验草稿或正式 skill，包括人类使用说明
pouch finalize <name>	校验草稿并移动到正式 skills/
pouch doctor [--target all] [--fix]	检查软链健康状态，--fix 自动修复

常用工作流

新建并全局启用自研 skill

pouch create my-skill --idea "描述要解决的重复问题" --from-project .
# 由 Agent 完善草稿中的 SKILL.md 和 README.md
pouch check my-skill
pouch finalize my-skill
pouch publish skills/my-skill -m "add my-skill" --push
pouch add my-skill -a cursor -g -y
pouch doctor -a cursor

在项目中启用 skill

cd ~/code/my-app
pouch add declarative-openspec-loop -a cursor -y

添加 Catalog Source

pouch catalog add my-ext https://github.com/org/repo --ref main
pouch fetch my-ext
pouch add my-ext -g

源码结构

pouch/
├── __init__.py      # 版本号
├── __main__.py      # python3 -m pouch 入口
├── cli.py           # 命令定义与调度
├── paths.py         # 路径常量与 Agent 目标
├── skills.py        # builtin/catalog/custom 统一解析
├── catalog.py       # catalog.yaml 读写与 Skill 发现
├── sources.py       # custom source 配置、发现与 Git 管理
├── project.py       # .pouch.yaml 管理
├── symlinks.py      # 软链创建/检查/修复
└── yaml_io.py       # 轻量 YAML 解析（无第三方依赖）

入口脚本：../bin/pouch

路径约定

变量	路径	说明
POUCH_HOME	~/.pouch	pouch 仓库（软链；兼容 ~/.skills）
SKILLS_DIR	~/.pouch/skills/	builtin skill 目录
CATALOG_FILE	~/.pouch/catalog.yaml	预置 Skill 来源目录
CATALOG_CACHE_DIR	~/.local/share/pouch/externals/	catalog checkout 缓存；按 repo/ref 共享
CONFIG_FILE	~/.config/pouch/config.yaml	custom source 配置
SOURCES_DIR	~/.local/share/pouch/sources/	custom Git source 默认 checkout

注意事项

• 禁止在 ~/.cursor/skills/ 等 Agent 目录直接创建非软链的 skill
• Claude Code 对 symlink 支持不稳定；建议对单个 skill 目录软链，不要软链整个 ~/.claude/skills/
• 若 Agent 将软链替换为普通目录，运行 pouch doctor --fix 重建

相关文档

• 项目 README
• AGENTS.md