diff --git a/AGENTS.md b/AGENTS.md index 54a789a..099b811 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,12 +1,12 @@ # Agent Skills 仓库 -自研 Agent Skills 的单一事实来源（SSOT）。Skill 内容在本仓库维护；安装与管理由 [skiff](https://git.yumee.top/laily/skiff) CLI 负责。 +自研 Agent Skills 与配套规范资料的单一事实来源（SSOT）。Skill 内容、规范包与可运行的 skiff CLI 在本仓库一并维护。 -| 仓库 | 地址 | 职责 | -| --------------- | ------------------------------------------------------------------------ | --------------- | -| **skills**（本仓库） | [https://git.yumee.top/laily/skills](https://git.yumee.top/laily/skills) | skill 内容与规范 | -| **skiff** | [https://git.yumee.top/laily/skiff](https://git.yumee.top/laily/skiff) | 安装、symlink、健康检查 | +| 仓库 | 地址 | 职责 | +| --------------- | ------------------------------------------------------------------------ | -------------------------- | +| **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 的独立来源 / 上游同步参考 | --- @@ -35,18 +35,22 @@ skiff status ``` skills/ ├── _template/ # 新建 skill 的脚手架 -├── declarative-openspec-loop/ # 自研 skill +├── declarative-openspec-loop/ # 自研 skill，必须含 SKILL.md │ ├── SKILL.md │ └── reference.md ├── discussion-notes/ # 讨论沉淀笔记 │ ├── SKILL.md │ └── reference.md +kits/ +└── agent-collaboration-kit/ # 可复制到项目的协作规范包，不是 skill +skiff/ # CLI 源码（Python 3） +bin/skiff # CLI 入口 registry.yaml # 外部 Git skill 来源目录 AGENTS.md # 本文档 ``` -**本仓库包含**：`skills/`、`registry.yaml`、`AGENTS.md` -**本仓库不包含**：CLI 代码、各项目的 skill 启用清单 +**本仓库包含**：`skills/`、`kits/`、`skiff/`、`bin/skiff`、`registry.yaml`、`AGENTS.md` +**本仓库不包含**：各项目的 skill 启用清单 --- @@ -63,6 +67,21 @@ AGENTS.md # 本文档 新建 skill：复制 `skills/_template/` → `skills//`，编辑 `SKILL.md`，在本仓库 commit。 +### 规范包（Kits，不是 Skill） + +`kits/` 放可复制到项目的流程规范、模板、检查清单和示例资料。它们不是 Agent Skill： + +- 不放 `SKILL.md` frontmatter +- 不由 `skiff install` / `skiff add` 安装 +- 不会被 Agent 自动触发加载 +- 使用方式是复制到目标项目文档目录，或在目标项目 `AGENTS.md` 中引用 + +| Kit | 说明 | 推荐落地位置 | +| --- | --- | --- | +| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包 | `docs/agent-collaboration-kit/` | + +新建规范包：创建 `kits//README.md`，写清适用场景、复制到项目后的推荐目录、需要项目填充的占位符，并在本仓库 commit。 + ### 外部（External Git） 在 `registry.yaml` 中注册，通过 skiff 拉取安装： @@ -94,7 +113,8 @@ npx skills find typescript 1. **SSOT** — 自研 skill 只存在于 `skills//`，不在 Agent 目录直接创建 2. **项目自治** — 每个项目自己维护 `.skills.yaml`，本仓库不维护项目清单 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT -4. **仓库分离** — skill 内容与 CLI 工具分仓库，互不影响更新 +4. **类型分离** — `skills/` 只放可安装 skill；非 skill 的规范包、模板包放 `kits/` +5. **一体维护** — skill、规范包与 CLI 同仓库维护；需要时再与独立 skiff 仓库同步 --- @@ -103,6 +123,8 @@ npx skills find typescript ``` skills 仓库（本仓库） skiff CLI skills// ←── skiff install / enable +kits// ←── 手动复制 / 项目文档引用 +skiff/ ←── python3 -m skiff registry.yaml ←── skiff add / fetch ↑ ~/.skills（symlink） @@ -123,6 +145,13 @@ registry.yaml ←── skiff add / fetch | **External Git** | `~/.local/share/skills/externals/` | `skiff fetch` | | **External NPM** | `node_modules/` | `npx skills add` / `skills-npm` | +### 非 Skill 资料分类 + +| 类型 | 位置 | 维护方式 | +| --- | --- | --- | +| **Kit** | `kits//` | 本仓库 commit；复制到目标项目 `docs/` 或由项目 `AGENTS.md` 引用 | +| **OpenSpec 配置** | `openspec/` | 本仓库 commit；服务于本仓库自身的规格流程 | + ### 多 Agent 路径 diff --git a/README.md b/README.md index 7dd0ab1..2b8409f 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,8 @@ skiff status ## 仓库结构 ``` -skills/ # 自研 skill（SSOT） +skills/ # 自研 skill（SSOT）：每个子目录必须有 SKILL.md +kits/ # 可复制到项目的规范包 / 模板包，不是 Agent Skill skiff/ # CLI 源码（Python 3） bin/skiff # CLI 入口 registry.yaml # 外部 Git skill 目录 @@ -28,6 +29,7 @@ AGENTS.md # 详细规范与架构说明 | 路径 | 说明 | |------|------| | [skills/](skills/) | 自研 skill，每个子目录含 `SKILL.md` | +| [kits/](kits/) | 项目规范包、协作模板、可复制资料，不由 skiff 安装 | | [skiff/](skiff/README.md) | 安装、软链、健康检查 CLI | | [registry.yaml](registry.yaml) | 外部 Git skill 注册表 | | [AGENTS.md](AGENTS.md) | 设计原则、编写规范、架构详解 | @@ -39,6 +41,14 @@ AGENTS.md # 详细规范与架构说明 | [declarative-openspec-loop](skills/declarative-openspec-loop/SKILL.md) | 声明式编程循环：用户提供校验方式，Agent 自动迭代直到通过 | | [discussion-notes](skills/discussion-notes/SKILL.md) | 讨论沉淀：边讨论边维护 Markdown 笔记 | +## 规范包（不是 Skill） + +`kits/` 用来维护可复制到项目里的规范说明、模板和检查清单。它们没有 `SKILL.md`，不会被 `skiff install`、`skiff add` 或 Agent 自动加载。 + +| Kit | 说明 | +|-----|------| +| [agent-collaboration-kit](kits/agent-collaboration-kit/README.md) | 多 Agent 协作闭环规范包，复制到项目 `docs/agent-collaboration-kit/` 后按项目情况填写 | + 新建 skill： ```bash @@ -100,6 +110,7 @@ npx skills find typescript ``` 本仓库 ├── skills// ←── skiff install / enable +├── kits// ←── 手动复制 / 项目文档引用 ├── registry.yaml ←── skiff add / fetch └── skiff/ ←── python3 -m skiff ↑ @@ -117,7 +128,8 @@ npx skills find typescript 1. **SSOT** — 自研 skill 只存在于 `skills//` 2. **项目自治** — 各项目自行维护 `.skills.yaml` 3. **软链优先** — 通过 symlink 映射到 Agent 目录，改 skill 即改 SSOT -4. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译 +4. **规范包分离** — 非 skill 的流程规范、模板包放在 `kits//`，不混入 `skills/` +5. **一体维护** — skill 与 CLI 同仓库，Python 3 直接运行，无需编译 ## 文档 diff --git a/skills/agent-collaboration-kit/AGENTS-template.md b/kits/agent-collaboration-kit/AGENTS-template.md similarity index 100% rename from skills/agent-collaboration-kit/AGENTS-template.md rename to kits/agent-collaboration-kit/AGENTS-template.md diff --git a/skills/agent-collaboration-kit/README.md b/kits/agent-collaboration-kit/README.md similarity index 100% rename from skills/agent-collaboration-kit/README.md rename to kits/agent-collaboration-kit/README.md diff --git a/skills/agent-collaboration-kit/adoption-checklist.md b/kits/agent-collaboration-kit/adoption-checklist.md similarity index 100% rename from skills/agent-collaboration-kit/adoption-checklist.md rename to kits/agent-collaboration-kit/adoption-checklist.md diff --git a/skills/agent-collaboration-kit/optimization-method.md b/kits/agent-collaboration-kit/optimization-method.md similarity index 100% rename from skills/agent-collaboration-kit/optimization-method.md rename to kits/agent-collaboration-kit/optimization-method.md diff --git a/skills/agent-collaboration-kit/orca-closed-loop.md b/kits/agent-collaboration-kit/orca-closed-loop.md similarity index 100% rename from skills/agent-collaboration-kit/orca-closed-loop.md rename to kits/agent-collaboration-kit/orca-closed-loop.md diff --git a/skills/agent-collaboration-kit/prompt-templates.md b/kits/agent-collaboration-kit/prompt-templates.md similarity index 100% rename from skills/agent-collaboration-kit/prompt-templates.md rename to kits/agent-collaboration-kit/prompt-templates.md diff --git a/skills/agent-collaboration-kit/roles-and-permissions.md b/kits/agent-collaboration-kit/roles-and-permissions.md similarity index 100% rename from skills/agent-collaboration-kit/roles-and-permissions.md rename to kits/agent-collaboration-kit/roles-and-permissions.md diff --git a/skills/agent-collaboration-kit/task-board-template.yaml b/kits/agent-collaboration-kit/task-board-template.yaml similarity index 100% rename from skills/agent-collaboration-kit/task-board-template.yaml rename to kits/agent-collaboration-kit/task-board-template.yaml