feat: rename skills/skiff to pouch and move ACK state under .pouch

Use ~/.pouch, the pouch CLI, and .pouch.yaml as the SSOT container. Keep the inner skills/ packages, and store ACK project state in .pouch/ack instead of docs/ack.
2026-08-25 15:20:02 +08:00
parent ee31278947
commit f3cd56b78e
83 changed files with 1265 additions and 1192 deletions
@@ -1,35 +1,44 @@
-# Agent Skills
+# pouch

-自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。Skill 内容与 **skiff** CLI 在本仓库一并维护。
+自研 [Agent Skills](https://agentskills.io) 的单一事实来源（SSOT）。仓库、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。Skill 内容与 CLI 在本仓库一并维护。

 ## 快速开始

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

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

+从旧的 `~/.skills` / `skiff` 迁移：
+
+```bash
+mv ~/.skills ~/.pouch
+~/.pouch/install.sh
+```
+
+`install.sh` 会安装 `pouch` 命令，并保留 `skiff` 作为旧命令别名。项目里已有的 `.skills.yaml` 仍可读取；新写入使用 `.pouch.yaml`。
+
 ## 仓库结构

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

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

 ## 自研 Skill
@@ -38,44 +47,44 @@ AGENTS.md         # 详细规范与架构说明
 |-------|------|
 | [orc](skills/orc/SKILL.md) | 显式编排开发、版本发布和产物任务，支持 low/mid/high Agent 档位 |
 | [ack](skills/ack/SKILL.md) | 显式初始化、检查并运行 ACK 三角色协作及可选交付闭环 |
-| [skiff](skills/skiff/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
+| [pouch](skills/pouch/SKILL.md) | 在项目中创建、安装、反馈和维护 builtin skill |
 | [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 |
 | [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 |

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

 ```bash
-skiff init ack
-skiff init ack --project ~/app
+pouch init ack
+pouch init ack --project ~/app
 ```

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

 新建 skill：

 ```bash
-skiff create my-skill --idea "描述要解决的重复问题" --from-project .
-# 由 Agent 完善 ~/.skills/.drafts/my-skill/SKILL.md
-skiff check my-skill
-skiff finalize my-skill
-skiff add my-skill -g   # 全局安装验证
+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 按 `skiff` skill 收集实际结果与期望结果，修改 `~/.skills/skills/<name>/` 的 SSOT，并执行 `skiff check <name>`。项目专属规则保留在项目内，不回流到通用 skill。
+项目里使用 skill 发现通用问题或优化时，让 Agent 按 `pouch` skill 收集实际结果与期望结果，修改 `~/.pouch/skills/<name>/` 的 SSOT，并执行 `pouch check <name>`。项目专属规则保留在项目内，不回流到通用 skill。

 ## 安装方式

 ### 全局（用户级）

 ```bash
-skiff add <name> -g                   # 安装到 ~/.cursor/skills/ 等
-skiff add <name> -g -a cursor
+pouch add <name> -g                   # 安装到 ~/.cursor/skills/ 等
+pouch add <name> -g -a cursor
 ```

 ### 项目级

-在项目根目录维护 `.skills.yaml`：
+在项目根目录维护 `.pouch.yaml`：

 ```yaml
 skills:
@@ -91,9 +100,9 @@ targets:          # 可选，默认 all
 ```

 ```bash
-skiff add declarative-openspec-loop
-skiff sync
-skiff remove declarative-openspec-loop
+pouch add declarative-openspec-loop
+pouch sync
+pouch remove declarative-openspec-loop
 ```

 ## Catalog 与 Custom Source
@@ -101,15 +110,15 @@ skiff remove declarative-openspec-loop
 安装 catalog 中预置的来源：

 ```bash
-skiff fetch waza
-skiff add waza/think -g
+pouch fetch waza
+pouch add waza/think -g
 ```

 接入团队自己的本地目录或 Git 仓库：

 ```bash
-skiff source add company --local ~/code/company-skills --skills-path skills
-skiff add company/internal-review -g
+pouch source add company --local ~/code/company-skills --skills-path skills
+pouch add company/internal-review -g
 ```

 **社区来源**（Vercel CLI）：
@@ -123,24 +132,24 @@ npx skills find typescript

 ```
 本仓库
-├── skills/<name>/     ←── skiff install / enable
+├── skills/<name>/     ←── pouch install / enable
 ├── catalog.yaml       ←── 预置来源发现与 fetch
-└── skiff/             ←── python3 -m skiff
+└── pouch/             ←── python3 -m pouch
         ↑
-    ~/.skills（symlink）
+    ~/.pouch（symlink）
         │
    ┌────┴────────────────┐
    ▼                     ▼
 ~/.cursor/skills/    project/.agents/skills/
 ~/.claude/skills/    project/.claude/skills/
-~/.codex/skills/     project/.skills.yaml
+~/.codex/skills/     project/.pouch.yaml
 ~/.agents/skills/    （agents 标准目录，覆盖 OMP）
 ```

 ## 设计原则

 1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`
-2. **项目自治** — 各项目自行维护 `.skills.yaml`
+2. **项目自治** — 各项目自行维护 `.pouch.yaml`
 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
 4. **能力内聚** — Skill 所需规范、模板和脚本与 `SKILL.md` 放在同一目录
 5. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译
@@ -148,7 +157,7 @@ npx skills find typescript
 ## 文档

 - [AGENTS.md](AGENTS.md) — 完整规范、多 Agent 路径、编写约定
- [skiff/README.md](skiff/README.md) — CLI 命令参考与开发说明
+- [pouch/README.md](pouch/README.md) — CLI 命令参考与开发说明

 ## 参考