harveyz-skill 0.1.1 → 0.2.0

package/skills/harness/diataxis-docs/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: diataxis-docs
+description: Use when creating, updating, or deleting any file under docs/ — including writing a new guide, updating reference content, adding an ADR, or removing an outdated page. Also use when searching docs before writing, to avoid duplicating existing content.
+---
+
+# Diataxis 文档管理
+
+本项目 `docs/` 目录遵循 **Diátaxis** 文档方法论。根据操作类型走对应流程。
+
+---
+
+## 先读索引
+
+**任何操作之前**，先读 `docs/INDEX.md`，它列出了所有文件及一句话说明。
+
+- 若 `docs/INDEX.md` 不存在：读 skill 目录下的 `references/index-template.md` 新建它，再继续。
+
+---
+
+## 按操作类型选择流程
+
+### 删除文档
+
+只需一步：从 `docs/INDEX.md` 中移除对应行，然后删除文件。
+
+---
+
+### 修改文档
+
+1. 对照索引确认文件位置和分类（如分类错误，先迁移文件）。
+2. 修改内容，遵循该分类的职责边界（见下方「各类型职责」）。
+3. 若文档描述变化，同步更新 `docs/INDEX.md` 中对应行。
+
+---
+
+### 新建文档
+
+按顺序完成以下步骤：
+
+#### 1. 内容分类
+
+问自己：**读者到达这篇文档时处于什么状态？**
+
+```
+                 学习导向          ←→          工作导向
+实践性    │  tutorials/          │  how-to/
+          │  （跟着做，学原理）    │  （解决具体问题）
+──────────┼──────────────────────┼──────────────────
+理论性    │  explanation/        │  reference/
+          │  （理解为什么）        │  （查找信息）
+```
+
+**判断流程：**
+
+```
+内容包含从零开始的引导式练习？
+  是 → tutorials/
+  否 → 包含完成某个具体任务的操作步骤？
+          是 → how-to/
+          否 → 包含稳定的事实、规范或 API 定义？
+                  是 → reference/
+                  否 → explanation/
+```
+
+> 项目可能有额外目录（如 `adr/`、`rfcs/`）。需要新建此类目录时，先读 skill 目录下的 `references/custom-categories.md`。
+
+**内容跨越多个分类？** 先拆成独立文档，再对每篇从「内容分类」重新开始走一遍完整流程。
+
+#### 2. 检查已有文档重叠
+
+扫描 INDEX.md 中**同类目录**的条目：
+
+- 已有文件覆盖相同主题 → **更新已有文件**（切换到「修改文档」流程），不要新建。
+- 角度不同 → 继续新建，并在两篇文章中互相注明关联。
+
+#### 3. 命名文件
+
+| 类型 | 规则 | 示例 |
+|------|------|------|
+| 长期文档（tutorials/how-to/reference/explanation） | `kebab-case.md`，不带日期 | `api.md`、`deploy.md` |
+| 有时间意义的文档（adr/rfcs/归档等） | `YYYY-MM-DD-topic.md` | `2026-04-23-dag-rewrite.md` |
+| 根目录文档 | `SCREAMING_SNAKE.md` | `INDEX.md`、`GUIDE.md` |
+
+#### 4. 写文档
+
+遵循该分类的职责边界（见下方「各类型职责」）。
+
+#### 5. 更新索引
+
+在 `docs/INDEX.md` 对应分类的表格中添加一行：
+
+```
+| [路径/文件.md](路径/文件.md) | 一句话说明这篇文档的用途 |
+```
+
+描述要简洁、对 Agent 友好——它是判断是否需要读全文的主要依据。
+
+---
+
+## 各类型职责边界
+
+| 类型 | 只包含 | 不包含 |
+|------|--------|--------|
+| **tutorials** | 引导式步骤，目标是完成一个具体成果 | 原理解释、完整参考信息 |
+| **how-to** | 完成具体任务的最短路径 | 为什么这样做的解释 |
+| **reference** | 稳定的事实、规范、API 定义 | 操作步骤、设计原理 |
+| **explanation** | 背景、原理、设计原因 | 操作步骤、完整参考信息 |
+
+---
+
+## 常见错误
+
+| 错误 | 正确做法 |
+|------|---------|
+| 在 reference 里写操作步骤 | 步骤移到 `how-to/`，reference 只保留事实 |
+| 在 how-to 里解释设计原因 | 原理移到 `explanation/`，how-to 只保留步骤 |
+| 跨分类内容不拆分直接新建 | 先拆，对每篇独立走完整流程 |
+| 写完文档忘记更新 `docs/INDEX.md` | 最后一步必须更新索引 |
+| 长期文档文件名带日期前缀 | 日期前缀只用于有时间意义的文档 |
+
+---
+
+## 参考文件（skill 内置，按需读取）
+
+| 文件 | 何时读 |
+|------|--------|
+| `references/index-template.md` | `docs/INDEX.md` 不存在，需要初始化时 |
+| `references/custom-categories.md` | 需要在四类之外新建额外目录时 |

package/skills/harness/diataxis-docs/references/custom-categories.md

@@ -0,0 +1,32 @@
+# 扩展分类标准（非核心目录）
+
+四个 Diátaxis 分类能覆盖绝大多数文档需求。只有当内容**确实无法归入任何一类**时，才考虑增加新目录。
+
+## 判断是否需要新分类
+
+在新建目录前，先问：
+
+1. **能否放入现有四类？** 绝大多数内容都可以。如果模棱两可，优先放现有目录。
+2. **这类内容有多处？** 单篇文章不需要新目录，至少要有 2～3 篇同类内容才值得单独建目录。
+3. **读者的使用场景是否根本不同？** 新目录要有独特的读者状态，不能与四类重叠。
+
+## 可接受的扩展分类（示例）
+
+| 目录名 | 适用场景 | 与四类的区别 |
+|--------|---------|-------------|
+| `adr/` | 已落地的架构决策记录 | 不可修改、有时间戳、记录决策过程而非知识 |
+| `rfcs/` | 提案、尚未实现的设计 | 状态是「待决策」，不是稳定知识 |
+| `archive/` | 历史文档，只读归档 | 不再维护，仅供回溯 |
+
+## 新目录必须满足的条件
+
+- **不与四类重叠**：如果内容放进 `reference/` 或 `explanation/` 毫无违和感，就不应新建目录。
+- **读者目的明确且独特**：能用一句话说清「读者在什么情况下会来这里」。
+- **在 INDEX.md 中有独立分区**：新目录必须同步在索引中建立对应章节，并写清用途说明。
+- **在 GUIDE.md（若存在）中登记**：如项目有文档指南，需同步更新目录说明。
+
+## 不应新建目录的情况
+
+- 内容只是某个 Diátaxis 类型的子话题（用文件名区分即可，无需新目录）。
+- 想把「设计文档」单独放一个目录——设计背景 → `explanation/`，设计决策 → `adr/`，设计规范 → `reference/`。
+- 「临时笔记」「草稿」类内容不属于 `docs/` 的管理范围。

package/skills/harness/diataxis-docs/references/index-template.md

@@ -0,0 +1,29 @@
+# INDEX.md 模板
+
+当 `docs/INDEX.md` 不存在时，根据项目实际目录结构新建，至少包含四个 Diátaxis 分类：
+
+```markdown
+# docs/ 文档索引
+
+## tutorials/ — 教程
+
+| 文件 | 用途 |
+|------|------|
+
+## how-to/ — 操作指南
+
+| 文件 | 用途 |
+|------|------|
+
+## reference/ — 参考文档
+
+| 文件 | 用途 |
+|------|------|
+
+## explanation/ — 理解类
+
+| 文件 | 用途 |
+|------|------|
+```
+
+**注意**：如果项目有额外分类（如 `adr/`、`rfcs/`），在上面模板基础上追加对应分区即可。每个分区都应有简短的用途说明，帮助 Agent 判断相关性。