doc

文档编写技能

由配置驱动的文档脚手架。配置位于技能目录中的 config/defaults.yaml——无需在仓库根目录创建文件。

命令

命令	执行内容
start <name>	bash ${AGENTS_SKILLS_DIR}/scripts/start.sh "<name>"
expt <name>	bash ${AGENTS_SKILLS_DIR}/scripts/expt.sh "<name>"
plan <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/plan.sh <index> "<title>"
finding <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/finding.sh <index> "<title>"
ckpt <index> <description>	bash ${AGENTS_SKILLS_DIR}/scripts/ckpt.sh <index> "<description>"
research <index> <topic>	bash ${AGENTS_SKILLS_DIR}/scripts/research.sh <index> "<topic>"
review <index> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/review.sh <index> "<title>"
learn <index> <domain> <title>	bash ${AGENTS_SKILLS_DIR}/scripts/learn.sh <index> "<domain>" "<title>"
list	bash ${AGENTS_SKILLS_DIR}/scripts/list.sh
status <index>	bash ${AGENTS_SKILLS_DIR}/scripts/status.sh <index>
resume <index>	bash ${AGENTS_SKILLS_DIR}/scripts/resume.sh <index>

start = 搭建 docs/ 脚手架 + 创建实验。 开始新工作时使用。 expt = 仅创建实验。 docs/ 已存在时使用。

Agent 行为——请仔细阅读

你负责在每次对话中跟踪当前实验。 用户创建实验或提及某个实验时，记住其索引。每次调用脚本时都传入该索引——脚本无状态且支持并行安全运行。

各命令的使用时机

用户说……	你应……
“我们来调查 X”／开始新工作	/doc start "<name>"——记住返回的索引
“制定计划”／“我们该怎么做”	如果近期没有涵盖此工作的计划：运行 /doc plan <idx> "<title>"，然后写入计划内容。如果要更新／完善近期计划：编辑同一个计划文件。
用户进入计划模式	停止。 不要使用 .claude/plan.md。如果是更新计划，使用现有的相关计划；否则运行 /doc plan <idx> "<title>" 并写入计划。计划应存放在实验文件夹中，不能放在临时存储中。
你发现了重要内容	/doc finding <idx> "<title>"，然后写入发现内容
对话即将结束／切换上下文	/doc ckpt <idx> "<short-label>"——仅使用简短标签（2–5 个词），然后在文件中写入包含 Mermaid 图表的完整 Agent 交接内容。请自动完成，无需用户提醒。
“研究 X”／“看看 Y”	/doc research <idx> "<topic>"——编写提示词、开展研究并写入结果
“审查 X”／“检查这份输出”	/doc review <idx> "<title>"，然后写入包含结论的审查内容
“记住这个”／“关键经验”	/doc learn <idx> <domain> "<title>"——写入提炼后的见解
“继续实验 19”／“接着做”	/doc resume <idx>——读取元数据、最新计划和最近 5 个检查点。将其设为本次对话的当前实验。
“有哪些实验？”	/doc list
“实验 19 的状态是什么？”	/doc status <idx>

上下文解析（用户未提供索引时）

1. 本次对话中已创建或恢复的实验 → 使用该实验
2. 用户通过名称／编号提到的实验 → 使用该实验
3. 用户的请求明显与某个实验相关 → 使用该实验
4. 有歧义 → 询问：“是哪个实验？”然后运行 /doc list 展示选项

由你解析上下文。脚本只接收编号。

自动行为

• 在自然停顿点自动创建检查点——对话结束、切换上下文前、完成里程碑后。不要等别人要求。
• **计划放在实验中。**绝不要将计划写入 .claude/plan.md 或任何临时存储。
• **当用户修订、完善或扩展某个产物时，更新同一个近期文件。**近期活动文档 = 你在本次对话中创建或恢复的计划／发现／审查／研究文件，或通过 /doc resume 找到的最新相关文件。直接编辑该文件。
• **当主题、决策点、里程碑或产物用途发生变化时，创建新的编号文件。**简而言之：不同工作创建新的编号文件。例如：旧计划已过时，需要新的实现方案；独立发现；新的审查；新的研究问题；检查点快照。
• **由 Agent 做决定。**如果无法确定是更新还是新建：只要近期活动文档仍代表当前工作，就优先编辑该文档；只有在需要保留不同版本的历史记录时才创建新文件。
• **继续之前先恢复上下文。**继续现有实验时，先运行 /doc resume 加载上下文，包括用于保持连续性的最近 5 个检查点。

检查点内容——必需

ckpt 命令参数是一个简短标签（2–5 个词），不是检查点内容。脚本创建文件后，必须按以下结构将正文写入文件：

```mermaid
graph TD
    A[Starting state] --> B[What was done]
    B --> C[Current state]
    C --> D[Next steps]
```

## What
What was accomplished. Bullet points, brief.

## Key Takeaways
Surprising findings, confirmed/rejected hypotheses, numbers that matter.

## Current State
Exact repo state: branch/commit if relevant, changed files, active experiment index, active plan/review/research files, commands already run, test results.

## Issues
Blockers hit, workarounds used, unresolved problems. Include exact error messages if relevant.

## Decisions
Key choices made and why. What was considered and rejected.

## Inferred Priority
Your inferred next priority based on conversation and repo state. Mark as "inferred" unless user stated it explicitly.

## Next
Concrete next steps with enough detail that a fresh agent can continue without reading chat history.
Include file paths, command examples, what to watch out for, and first command to run next.

检查点是一个完整的 Agent 交接文档。必须包含 Mermaid 图，以及足够的信息，让新接手的 Agent 无需查看聊天记录或询问情况，就能继续工作。简洁但完整——包括文件路径、关键数字、决策、当前状态、优先事项、有效的方法、无效的方法，以及确切的下一条命令。

不要将内容塞进描述参数。参数要简短：/doc ckpt 7 "v1 analysis complete"，然后编辑文件。

实验结构

experiments/NNN-{name}/
├── .meta.json          auto-updated by scripts
├── plans/              multiple plans, numbered
├── findings/           multiple findings, numbered  
├── checkpoints/        progress snapshots, numbered
├── review/             structured reviews, numbered
└── research/           prompt + response pairs, numbered

设置

/doc start my-investigation——就这样。该命令会搭建 docs/ 并创建第一个实验。

要自定义文件夹结构或命名方式：编辑技能中的 config/defaults.yaml。

规则

1. **脚本只创建空模板（frontmatter + 标题）。脚本运行后，你必须将实际内容写入文件。**绝不要把调用脚本当作已完成的步骤。
2. **创建文件时始终使用脚本。**绝不要手动创建实验目录或编辑 .meta.json。
3. **索引只写数字。**写 23，不要写 023，也不要写 023-docs-and-structs。
4. **不要自动提交。**脚本只搭建文件——由你或用户决定何时提交。
5. **计划放在实验中。**绝不要放入 .claude/plan.md。这是不可协商的。
6. **近期活动文档可编辑；历史文档只追加。**修订当前工作时，更新同一个近期文件。不同主题、里程碑、决策或快照应创建新的编号文件。
7. 有效的学习领域列在 config/defaults.yaml 中。learn 遇到无效领域时会报错。
8. **标题要简短。**标题会成为文件名。最多使用 2–5 个词——简洁且能说明内容。用 "auth-flow"，不要用 "investigation-into-authentication-flow-reliability-issues"。编号前缀负责排序；标题只需让人一眼看出主题。

$ARGUMENTS