laily
2be0964d73
Teach pouch to optimize a named skill's loading layout: keep SKILL.md as a router, move mode-specific steps to references, and measure footprint with an audit script instead of dumping the whole skill into context.
82 lines
2.2 KiB
Markdown
82 lines
2.2 KiB
Markdown
# pouch
|
||
|
||
`pouch` 用于创建、维护、安装和发布团队自研的 Agent Skill。Skill 的唯一来源位于
|
||
`~/.pouch/skills/<name>/`，安装到各 Agent 时使用软链接。
|
||
|
||
## 什么时候使用
|
||
|
||
- 想把项目里的重复工作沉淀成一个 skill。
|
||
- 想完善、校验、转正或发布已有 skill。
|
||
- 想把自研 skill 安装到当前项目或全局 Agent。
|
||
- 想检查并修复 skill 软链接。
|
||
- 想优化某个已有 skill 的结构，减少点中后灌进上下文的内容。
|
||
|
||
## 创建一个 skill
|
||
|
||
```bash
|
||
pouch create my-skill \
|
||
--idea "描述这个 skill 要解决的重复问题" \
|
||
--from-project .
|
||
```
|
||
|
||
命令会在 `~/.pouch/.drafts/my-skill/` 创建：
|
||
|
||
- `SKILL.md`：给 Agent 阅读的工作流与约束。
|
||
- `README.md`：给人类阅读的用途、准备事项、示例和完成标准。
|
||
- `brief.yaml`：草稿来源信息，转正时自动移除。
|
||
|
||
完善 `SKILL.md` 和 `README.md` 后运行：
|
||
|
||
```bash
|
||
pouch check my-skill
|
||
pouch finalize my-skill
|
||
```
|
||
|
||
## 优化已有 skill 的结构
|
||
|
||
skill 能用但正文太长、所有模式写在一份 `SKILL.md` 里，或点中后把用不到的参考一并读进上下文时：
|
||
|
||
```text
|
||
pouch 帮忙优化 ack 这个 skill 结构，减少 token 浪费
|
||
```
|
||
|
||
Agent 会先测量该 skill 的体积，再按分层加载改 SSOT：`SKILL.md` 只留路由和全模式边界，细节按条件读 `references/`。不会为了缩字删掉发版/部署一类的安全限制。改完仍需 `pouch check` 通过。
|
||
|
||
不要对社区 catalog skill 的安装目录直接改；那些不是本仓库的 SSOT。
|
||
|
||
## 提交和发布
|
||
|
||
只提交：
|
||
|
||
```bash
|
||
pouch publish skills/my-skill -m "add my-skill"
|
||
```
|
||
|
||
提交并推送：
|
||
|
||
```bash
|
||
pouch publish skills/my-skill -m "add my-skill" --push
|
||
```
|
||
|
||
## 安装
|
||
|
||
安装到当前项目的 Codex：
|
||
|
||
```bash
|
||
pouch add my-skill -a codex -y
|
||
```
|
||
|
||
安装到全局 Codex：
|
||
|
||
```bash
|
||
pouch add my-skill -a codex -g -y
|
||
```
|
||
|
||
## 如何判断完成
|
||
|
||
- `pouch check <name>` 输出校验通过。
|
||
- 正式 skill 同时包含 `SKILL.md` 和 `README.md`。
|
||
- `pouch status` 或 `pouch doctor` 显示目标软链接正常。
|
||
- 优化结构时：审计报告有前后体积，安全限制仍在 `SKILL.md`，没有为缩字删掉模式。
|
||
|