.pouch/skills/pouch/SKILL.md

name, description

name	description
pouch	创建、校验、转正、安装或发布 ~/.pouch 自研 skill，初始化 skill 项目状态， 或优化 skill 分层加载结构以减少 token 浪费。 触发词：pouch、skiff、自研 skill、创建 skill、publish skill、安装自研 skill、 初始化 skill、优化 skill 结构、减少 token 浪费、skill 太长、分层加载。

pouch 自研 Skill 工作流

SSOT 固定在 ~/.pouch/skills/<name>/。内容通过 symlink 分发到各 agent，改 SSOT 即全项目生效。

开始时解析当前 SKILL.md 所在目录，记为 <pouch-skill-dir>。

选择模式

• 创建、完善、转正草稿：执行「创建新的 skill」。
• 行为不对、触发不准、校验失败、可复用优化回流：执行「问题或优化回流」。
• 优化结构、减少 token 浪费、skill 太长、分层加载：执行「优化 skill 结构」。先读 token-structure.md。
• 安装、卸载、浏览、init、status：执行「安装与维护」。

---

在项目中使用 skill

先浏览可用的 builtin skill，再安装到当前项目：

pouch add --list
pouch add <name> -a cursor -a claude -a codex -a agents -y

pouch add <name> 默认安装到当前项目；只有用户明确需要所有项目使用时才加 -g。安装结果是指向 ~/.pouch/skills/<name>/ 的软链，不要在 Agent 目录创建副本。

创建新的 skill

从项目想法创建 skill

当用户在项目开发中提出“想创建一个 skill”时：

1. 用一句话确认它要解决的重复问题，并建议符合小写连字符规范的名称；信息足够时不要为了形式追问。
2. 读取当前项目中与想法直接相关的代码和规范，区分可复用工作流与项目私有事实。
3. 创建草稿：

pouch create <name> --idea "<用户原始想法>" --from-project .

4. 编辑 ~/.pouch/.drafts/<name>/SKILL.md，按 token-structure.md 写触发条件、步骤、边界与验证。
5. 编辑同目录的 README.md，用面向人类的语言说明用途、准备事项、可直接复制的请求示例、Agent 会做什么以及如何判断完成。README 不应复述 Agent 内部指令。
6. 仅在确有必要时增加 references/、scripts/ 或 assets/。不要把项目专属路径、私有业务规则、一次性命令或密钥复制到通用 skill。
7. 运行校验并修复所有问题：

pouch check <name>

8. 向用户展示名称、description、README 的人类使用方式、核心步骤和验证方式。获得确认后再转正：

pouch finalize <name>

转正不会自动 commit、push 或安装。用户明确要求后再执行 pouch publish 或 pouch add。

问题或优化回流

在项目里使用 skills 遇到问题，或者发现可复用的优化时：

1. 先记录最小证据：触发用户表达、使用的 skill 名称、实际结果、期望结果，以及能复现问题的必要项目上下文。
2. 判断归属：
   • 通用工作流、触发条件或验证缺陷：回流 builtin skill。
   • 仅当前项目成立的命令、路径、业务规则：留在项目文档或项目配置，不写回通用 skill。
   • CLI 安装、软链或校验行为异常：修改 ~/.pouch/pouch/ 中的 CLI 和测试。
   • 第三方 skill：不要复制成 builtin skill 或直接改安装目录；整理证据反馈上游，除非用户明确决定维护 fork。
3. 确认真实来源。Agent 目录通常是软链，builtin skill 的 SSOT 固定为：

~/.pouch/skills/<name>/

4. 修改 SSOT。行为修复应先补能复现问题的测试或示例，再改 SKILL.md、引用文件或脚本。
5. 校验并在原项目重跑最初失败的场景：

pouch check <name>

6. 汇报修改内容、验证结果和影响范围。只有用户明确要求提交或推送时才运行：

pouch publish skills/<name> -m "update <name>" --push

软链正确时无需重新安装；SSOT 保存后项目立即读取新内容。

优化 skill 结构

用户要求优化某个 skill 的结构、减少 token 浪费、skill 太长或分层加载时执行。只改 builtin 或草稿的 SSOT。第三方 catalog skill 不改安装目录，除非用户明确要维护 fork。

1. 确认目标名称。SSOT 为 ~/.pouch/skills/<name>/ 或 ~/.pouch/.drafts/<name>/。

2. 读取 token-structure.md。

3. 只读审计输出，不要把目标 skill 的 references/ 全量读进上下文：

   python3 <pouch-skill-dir>/scripts/audit_skill_structure.py <name>
   

4. 审计 status: within-budget 且无空泛引用、无条件批量加载警告：按该文件报告 Keep，不改文件。

5. 否则按该文件改 SSOT。一次只改点名的那一个 skill。

6. 运行 pouch check <name>，并按该文件做模式场景核对。

7. 再跑审计脚本，按该文件报告。不自动 commit 或 pouch publish。

安装与维护

安装本项目的 pouch skill 到所有 Agent：

pouch bootstrap

安装其他 skill：

# 当前项目
cd ~/code/my-app
pouch add discussion-notes -a cursor -y

# 全局（所有项目）
pouch add discussion-notes -a cursor -g -y

# 多个 agent
pouch add discussion-notes -a cursor -a codex -g -y

catalog source既可以指向单个 skill，也可以指向包含多个 skill 目录的 collection。安装 collection 全部内容或其中一个：

pouch add waza -a codex -g -y
pouch add waza/think -a codex -g -y

pouch select 会把 collection 显示为两级菜单：选择 waza 仓库会选中其 全部子 skill，也可以只选择 waza/think、waza/ui 中的若干项。 普通 pouch select 只向项目安装，并只读显示每个 Agent 的全局安装状态； pouch select -g 只向全局安装。取消已勾选项不会卸载，卸载继续使用 pouch remove。

卸载：

pouch remove discussion-notes -a cursor -y          # 当前项目
pouch remove discussion-notes -g -a cursor -y     # 全局
pouch rm discussion-notes -g -y                     # rm 别名

浏览可用自研 skill：

pouch add --list

使用 Skill 自带模板初始化项目状态：

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

pouch 只负责可靠地生成项目状态文件，不复制或链接 Skill。需要分析项目并完善 ACK 配置、检查接入状态或 运行三角色闭环时，显式调用全局 /ack skill。builder / deployer 的项目接入走 对应 skill 的「初始化」模式，不要 pouch init builder 或 pouch init deployer。

---

与 Vercel npx skills 的分工

场景	工具
自研 skill（~/.pouch）	pouch
社区 skill（GitHub 任意仓库）	npx skills add

---

命令对照

pouch	说明
bootstrap	将本项目的 pouch skill 全局安装到所有 Agent
update	在 ~/.pouch 执行 git pull，更新 pouch 自身
add <name> [-g] [-a AGENT...] [-y]	安装
remove <name> [-g] [-a AGENT...] [-y]	卸载（rm / r 别名）
add --list	列出可用自研 skill
publish [paths] -m MSG [--push]	git add / commit / push
list	列出 ~/.pouch 目录结构
status	查看软链安装状态
create <name> --idea TEXT [--from-project PATH]	创建自研 skill 草稿
check <name>	校验草稿或正式 skill
finalize <name>	校验草稿并转为正式 skill
init <name> [--project DIR]	使用 skill 模板初始化项目状态

---

注意

• 不要在 project/.agents/skills/ 里直接改文件；应改 ~/.pouch/skills/ 再 publish
• 未完成的内容保留在 ~/.pouch/.drafts/，不要直接放进正式 skills/
• symlink 正确时，不需要 reinstall；保存 SSOT 后各项目自动读到新内容
• 社区 skill 用 npx skills add，不要用 pouch catalog add 除非团队要 pin 版本