Files

T

laily c2d6a5a0d7 feat(deployer): skip sync on localhost and complete skill READMEs

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.

2026-09-04 00:07:15 +08:00

3.8 KiB

Raw Blame History

pouch

创建、维护、安装和发布团队自研的 Agent Skill。唯一来源在 ~/.pouch/skills/<name>/，装到各 Agent 时用软链。

什么时候使用

想把项目里的重复工作沉淀成一个 skill。
想完善、校验、转正或发布已有 skill。
想把自研 skill 安装到当前项目或全局 Agent。
想检查并修复 skill 软链接。
想优化某个已有 skill 的结构，减少点中后灌进上下文的内容。

使用前准备

已把本仓库 clone 到 ~/.pouch 并跑过 ./install.sh（会把本 skill 装到所有 Agent）。
Python 3；~/.local/bin 已加入 PATH。
至少一种 Agent：Cursor、Claude Code、Codex，或 agents 标准目录。
要推到远端时，本仓库的 git remote 可写。

CLI 命令细节见仓库里的 pouch/README.md。

使用示例

帮我把「评审 PR 时按这份清单走」做成一个自研 skill。
pouch 帮我检查 discussion-notes 这个 skill。
pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费。
把 ack 装到当前项目的 Cursor。
检查一下 skill 软链，坏了就修。

创建一个 skill

pouch create my-skill \
  --idea "描述这个 skill 要解决的重复问题" \
  --from-project .

命令会在 ~/.pouch/.drafts/my-skill/ 创建：

SKILL.md：给 Agent 阅读的工作流与约束。
README.md：给人类阅读的用途、准备事项、示例和完成标准。
brief.yaml：草稿来源信息，转正时自动移除。

完善 SKILL.md 和 README.md 后运行：

pouch check my-skill
pouch finalize my-skill

转正不会自动 commit、push 或安装。

优化已有 skill 的结构

skill 能用但正文太长、所有模式写在一份 SKILL.md 里，或点中后把用不到的参考一并读进上下文时：

pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费

Agent 会先测量该 skill 的体积，再按分层加载改 SSOT：SKILL.md 只留路由和全模式边界，细节按条件读 references/。不会为了缩字删掉发版、部署一类的安全限制。改完仍需 pouch check 通过。

不要对社区 catalog skill 的安装目录直接改；那些不是本仓库的 SSOT。

提交和发布

pouch publish skills/my-skill -m "add my-skill"
pouch publish skills/my-skill -m "add my-skill" --push

安装与维护

./install.sh 会执行 pouch bootstrap，把本 skill 全局装到所有 Agent。也可以随时重跑：

pouch bootstrap

安装其它 skill：

pouch add my-skill -a codex -y          # 当前项目的 Codex
pouch add my-skill -a codex -g -y       # 全局 Codex
pouch select                            # 交互多选，默认当前项目
pouch select -g                         # 交互多选，装到全局

项目状态初始化（目前用于 ack）：

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

builder / deployer 不要 pouch init，对 Agent 说「用 builder / deployer 初始化」。

软链出问题：

pouch status
pouch doctor
pouch doctor --fix

Agent 会做什么

创建草稿到 ~/.pouch/.drafts/，按你的想法完善 SKILL.md 和给人看的 README.md。
跑 pouch check；你确认后再 finalize 到 skills/。
安装只建指向 SSOT 的软链，不复制文件。默认装当前项目；只有你明确要求时才加 -g。
优化结构时先测量再改 SSOT，不删发版、部署类安全限制。
未要求时不 commit、不 push、不全局安装。

如何判断完成

pouch check <name> 输出校验通过。
正式 skill 同时包含 SKILL.md 和 README.md。
pouch status 或 pouch doctor 显示目标软链接正常。
优化结构时：审计报告有前后体积，安全限制仍在 SKILL.md，没有为缩字删掉模式。

3.8 KiB Raw Blame History Unescape Escape