laily/.pouch
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
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.
This commit is contained in:
laily
2026-08-25 15:20:02 +08:00
parent ee31278947
commit f3cd56b78e
83 changed files with 1265 additions and 1192 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+71 -72
View File
@@ -1,12 +1,11 @@
# Agent Skills 仓库
# pouch
自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。
自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。仓库名、家目录 `~/.pouch` 和 CLI 都叫 **pouch**。旧名是 `skills` / `skiff`。
| 仓库 | 地址 | 职责 |
| --------------- | ------------------------------------------------------------------------ | -------------------------- |
| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill、规范包、skiff CLI 的当前 SSOT |
| **skiff** | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff) | skiff CLI 的独立来源 / 上游同步参考 |
| **pouch**（本仓库） | [https://git.yumee.top/laily/pouch](https://git.yumee.top/laily/pouch) | skill、规范包、pouch CLI 的当前 SSOT |
---
@@ -15,16 +14,16 @@
```bash
# 1. 克隆并关联
git clone https://git.yumee.top/laily/skills.git ~/.skills
cd ~/.skills && ./install.sh
git clone https://git.yumee.top/laily/pouch.git ~/.pouch
cd ~/.pouch && ./install.sh
# install.sh 会自动把 skiff 项目 skill 安装到所有 Agent
# install.sh 会自动把 pouch 项目 skill 安装到所有 Agent
# 2. 安装其他 skill
skiff add declarative-openspec-loop -g
pouch add declarative-openspec-loop -g
# 3. 查看状态
skiff list
skiff status
pouch list
pouch status
```
---
@@ -41,13 +40,13 @@ skills/
├── discussion-notes/ # 讨论沉淀笔记
│ ├── SKILL.md
│ └── reference.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/`、`skiff/`、`bin/skiff`、`catalog.yaml`、`AGENTS.md`
**本仓库包含**：`skills/`、`pouch/`、`bin/pouch`、`catalog.yaml`、`AGENTS.md`
**本仓库不包含**：各项目的 skill 启用清单
---
@@ -61,7 +60,7 @@ AGENTS.md # 本文档
| ---------------------------------------------------------------------- | ------------------------------------------------- |
| [orc](skills/orc/SKILL.md) | ORC 入口：显式编排开发、版本发布与产物任务，支持 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 自动 propose/apply/校验并迭代直到通过 |
| [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记，无 .raw.md |
@@ -73,12 +72,12 @@ Skill 需要的稳定规范、模板、示例和脚本直接放在自己的目
项目状态，不复制或链接 Skill 内容：
```bash
skiff init ack
pouch init ack
```
### 预置目录（Catalog）
在 `catalog.yaml` 中预置，通过 skiff 拉取安装：
在 `catalog.yaml` 中预置，通过 pouch 拉取安装：
| Source | 来源 |
@@ -87,8 +86,8 @@ skiff init ack
```bash
skiff fetch waza
skiff add waza/think -g
pouch fetch waza
pouch add waza/think -g
```
### 自定义仓库（Custom Sources）
@@ -96,21 +95,21 @@ skiff add waza/think -g
公司或团队维护、且一个仓库中包含多个 skill 时，使用命名 custom source：
```bash
skiff source add company \
pouch source add company \
git@git.company.com:platform/agent-skills.git \
--skills-path skills
skiff list --source company
skiff add company/internal-review -g
pouch list --source company
pouch add company/internal-review -g
```
也可以接入已有本地 checkout：
```bash
skiff source add company --local ~/code/company-skills --skills-path skills
pouch source add company --local ~/code/company-skills --skills-path skills
```
配置保存在 `~/.config/skiff/config.yaml`，Git source 默认 clone 到
`~/.local/share/skiff/sources/<source>/`。项目 `.skills.yaml` 只记录逻辑
配置保存在 `~/.config/pouch/config.yaml`，Git source 默认 clone 到
`~/.local/share/pouch/sources/<source>/`。项目 `.pouch.yaml` 只记录逻辑
source 名称，每台机器独立配置实际仓库地址。
### 社区（External NPM / GitHub）
@@ -127,28 +126,28 @@ npx skills find typescript
## 设计原则
1. **SSOT** — 自研 skill 只存在于 `skills/<name>/`，不在 Agent 目录直接创建
2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单
2. **项目自治** — 每个项目自己维护 `.pouch.yaml`，本仓库不维护项目清单
3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT
4. **能力内聚** — Skill 使用的规范、模板和脚本与 `SKILL.md` 同目录维护
5. **一体维护** — skill 与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步
5. **一体维护** — skill 与 CLI 同仓库维护
---
## 架构
```
skills 仓库（本仓库） skiff CLI
skills/<name>/ ←── skiff install / enable
skiff/ ←── python3 -m skiff
catalog.yaml ←── skiff add / fetch
pouch 仓库（本仓库） pouch CLI
skills/<name>/ ←── pouch install / enable
pouch/ ←── python3 -m pouch
catalog.yaml ←── pouch add / fetch
↑
~/.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）
```
@@ -158,8 +157,8 @@ catalog.yaml ←── skiff add / fetch
| 层级 | 位置 | 维护方式 |
| ---------------- | ---------------------------------- | ------------------------------- |
| **Builtin** | `skills/<name>/` | 本仓库 commit |
| **Catalog** | `catalog.yaml` + checkout 缓存 | `skiff catalog add / fetch` |
| **Custom Source** | `~/.local/share/skiff/sources/` 或本地路径 | `skiff source add/fetch` |
| **Catalog** | `catalog.yaml` + checkout 缓存 | `pouch catalog add / fetch` |
| **Custom Source** | `~/.local/share/pouch/sources/` 或本地路径 | `pouch source add/fetch` |
| **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` |
### 非 Skill 资料分类
@@ -184,10 +183,10 @@ catalog.yaml ←── skiff add / fetch
## 项目级启用
每个项目**自己维护** `.skills.yaml`，不由本仓库管理：
每个项目**自己维护** `.pouch.yaml`，不由本仓库管理：
```yaml
# .skills.yaml（在项目根目录）
# .pouch.yaml（在项目根目录）
skills:
- name: declarative-openspec-loop
source: builtin
@@ -205,38 +204,38 @@ targets: # 可选，默认 all
| 概念 | 类比 |
| -------------- | --------------------------- |
| skills 仓库 | npm registry |
| `.skills.yaml` | `package.json` dependencies |
| `skiff enable` | `npm install` |
| `skiff sync` | `npm ci` |
| pouch 仓库 | npm registry |
| `.pouch.yaml` | `package.json` dependencies |
| `pouch enable` | `npm install` |
| `pouch sync` | `npm ci` |
项目级命令：
```bash
cd ~/code/my-app
skiff enable declarative-openspec-loop
skiff disable declarative-openspec-loop
skiff sync
pouch enable declarative-openspec-loop
pouch disable declarative-openspec-loop
pouch sync
```
---
## skiff 命令
## pouch 命令
详见 [skiff README](https://git.yumee.top/laily/skiff)。
详见 [pouch README](https://git.yumee.top/laily/pouch)。
### 已实现
| 命令 | 说明 |
| -------------------------------------- | ------------------- |
| `skiff bootstrap` | 将 skiff 项目 skill 全局安装到所有 Agent |
| `skiff list` | 列出所有 skill |
| `skiff status` | 安装状态总览 |
| `skiff add <name> [-g]` | 项目或全局安装（symlink） |
| `skiff remove <name> [-g]` | 移除 symlink |
| `skiff catalog add` / `skiff fetch` | 管理和拉取 catalog source |
| `pouch bootstrap` | 将 pouch 项目 skill 全局安装到所有 Agent |
| `pouch list` | 列出所有 skill |
| `pouch status` | 安装状态总览 |
| `pouch add <name> [-g]` | 项目或全局安装（symlink） |
| `pouch remove <name> [-g]` | 移除 symlink |
| `pouch catalog add` / `pouch fetch` | 管理和拉取 catalog source |
### 草稿与健康检查
@@ -244,10 +243,10 @@ skiff sync
| 命令 | 说明 |
| --- | --- |
| `skiff create <name> --idea TEXT [--from-project PATH]` | 从 `_template/` 创建草稿 |
| `skiff check <name>` | 校验草稿或正式 skill |
| `skiff finalize <name>` | 校验并将草稿转为正式 skill |
| `skiff doctor [--fix]` | symlink 健康检查与修复 |
| `pouch create <name> --idea TEXT [--from-project PATH]` | 从 `_template/` 创建草稿 |
| `pouch check <name>` | 校验草稿或正式 skill |
| `pouch finalize <name>` | 校验并将草稿转为正式 skill |
| `pouch doctor [--fix]` | symlink 健康检查与修复 |
---
@@ -282,12 +281,12 @@ description: >-
### 新建流程
1. `skiff create my-skill --idea "..." --from-project .`
2. Agent 编辑 `~/.skills/.drafts/my-skill/SKILL.md`
3. `skiff check my-skill`
4. 用户确认后执行 `skiff finalize my-skill`
5. `skiff add my-skill -a cursor -g -y` 验证
6. 在本仓库 commit；需要的项目再用 `skiff add my-skill` 启用
1. `pouch create my-skill --idea "..." --from-project .`
2. Agent 编辑 `~/.pouch/.drafts/my-skill/SKILL.md`
3. `pouch check my-skill`
4. 用户确认后执行 `pouch finalize my-skill`
5. `pouch add my-skill -a cursor -g -y` 验证
6. 在本仓库 commit；需要的项目再用 `pouch add my-skill` 启用
**禁止**在 `~/.cursor/skills/` 或项目 Agent 目录直接创建非 symlink 的 skill。
@@ -299,7 +298,7 @@ symlink 正确时，Agent 在项目里改 skill 文件 = 直接改 SSOT：
```
project/.agents/skills/foo/SKILL.md
→ ~/.skills/skills/foo/SKILL.md
→ ~/.pouch/skills/foo/SKILL.md
→ 在本仓库 commit
```
@@ -314,7 +313,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
| -------------- | ----------------------------------------------------- |
| Cursor / Codex | symlink，正常 |
| Claude Code | symlink 单个 skill 目录，不要 symlink 整个 `~/.claude/skills/` |
| symlink 被替换 | `skiff doctor --fix` → 重建 symlink |
| symlink 被替换 | `pouch doctor --fix` → 重建 symlink |
---
@@ -324,7 +323,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
| 场景 | 工具 |
| -------------- | ---------------------------------------------------- |
| 自研 skill 安装/管理 | **skiff** |
| 自研 skill 安装/管理 | **pouch** |
| 社区 skill 安装 | **Vercel `npx skills add`** |
| NPM 包内 skill | **skills-npm** / **skill-indexer** |
| 搜索发现 | **npx skills find** / [skills.sh](https://skills.sh) |
@@ -337,13 +336,13 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
| 我要… | 命令 | 在哪 |
| ---------- | --------------------------------- | ---- |
| 首次安装 | `git clone <repo> ~/.skills && ~/.skills/install.sh` | 任意 |
| 新建 skill | `skiff create` → Agent 完善 → `check/finalize` | 任意项目 |
| 全局启用 | `skiff install <name>` | 任意 |
| 项目启用 | `skiff enable <name>` | 项目目录 |
| 看状态 | `skiff status` | 任意 |
| 首次安装 | `git clone <repo> ~/.pouch && ~/.pouch/install.sh` | 任意 |
| 新建 skill | `pouch create` → Agent 完善 → `check/finalize` | 任意项目 |
| 全局启用 | `pouch install <name>` | 任意 |
| 项目启用 | `pouch enable <name>` | 项目目录 |
| 看状态 | `pouch status` | 任意 |
| 装社区 skill | `npx skills add owner/repo -g -y` | 任意 |
| 更新外部 skill | `skiff fetch <name>` | 任意 |
| 更新外部 skill | `pouch fetch <name>` | 任意 |
---
@@ -351,7 +350,7 @@ Claude Code 对 symlink 支持不稳定：可能无法发现 skill，或写入
## 参考
- [Agent Skills 开放标准](https://agentskills.io)
- [skiff CLI](https://git.yumee.top/laily/skiff)
- [pouch CLI](https://git.yumee.top/laily/pouch)
- [Vercel skills CLI](https://github.com/vercel-labs/skills)
- [skills.sh](https://skills.sh)
- [Cursor Skills 文档](https://cursor.com/docs/context/skills)