Back to Details

doc

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Documentation Skill

文档Skill

Config-driven documentation scaffolding. Config lives inside the skill at 
config/defaults.yaml
— no repo-root files needed.
基于配置驱动的文档脚手架。配置文件位于Skill内部的
config/defaults.yaml
中——无需在仓库根目录放置文件。

Commands

命令

CommandWhat to run
start <name>
bash ${CLAUDE_SKILL_DIR}/scripts/start.sh "<name>"
expt <name>
bash ${CLAUDE_SKILL_DIR}/scripts/expt.sh "<name>"
plan <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/plan.sh <index> "<title>"
finding <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/finding.sh <index> "<title>"
ckpt <index> <description>
bash ${CLAUDE_SKILL_DIR}/scripts/ckpt.sh <index> "<description>"
research <index> <topic>
bash ${CLAUDE_SKILL_DIR}/scripts/research.sh <index> "<topic>"
review <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/review.sh <index> "<title>"
learn <index> <domain> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/learn.sh <index> "<domain>" "<title>"
list
bash ${CLAUDE_SKILL_DIR}/scripts/list.sh
status <index>
bash ${CLAUDE_SKILL_DIR}/scripts/status.sh <index>
resume <index>
bash ${CLAUDE_SKILL_DIR}/scripts/resume.sh <index>
start
= scaffold docs/ + create experiment. Use this when beginning new work. 
expt
= create experiment only. Use when docs/ already exists.
Command执行命令
start <name>
bash ${CLAUDE_SKILL_DIR}/scripts/start.sh "<name>"
expt <name>
bash ${CLAUDE_SKILL_DIR}/scripts/expt.sh "<name>"
plan <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/plan.sh <index> "<title>"
finding <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/finding.sh <index> "<title>"
ckpt <index> <description>
bash ${CLAUDE_SKILL_DIR}/scripts/ckpt.sh <index> "<description>"
research <index> <topic>
bash ${CLAUDE_SKILL_DIR}/scripts/research.sh <index> "<topic>"
review <index> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/review.sh <index> "<title>"
learn <index> <domain> <title>
bash ${CLAUDE_SKILL_DIR}/scripts/learn.sh <index> "<domain>" "<title>"
list
bash ${CLAUDE_SKILL_DIR}/scripts/list.sh
status <index>
bash ${CLAUDE_SKILL_DIR}/scripts/status.sh <index>
resume <index>
bash ${CLAUDE_SKILL_DIR}/scripts/resume.sh <index>
start
= 搭建docs/目录结构 + 创建实验。 开始新工作时使用此命令。 
expt
= 仅创建实验。 当docs/目录已存在时使用此命令。

Agent Behavior — READ THIS

Agent行为须知 — 请仔细阅读

You are responsible for tracking the active experiment per conversation. When the user creates an experiment or references one, remember its index. Pass it to every script call — scripts are stateless and parallel-safe.
你需要负责跟踪每次对话中的活跃实验。 当用户创建或引用某个实验时，请记住其索引。将索引传递给每个脚本调用——脚本是无状态且支持并行安全的。

When to use each command

各命令的使用场景

User says...You do...
"Let's investigate X" / starts new work
/doc start "<name>"
— remember the returned index
"Plan this" / "How should we approach"
/doc plan <idx> "<title>"
then write plan content into the created file
User enters plan modeSTOP. Do NOT use 
.claude/plan.md
. Instead run 
/doc plan <idx> "<title>"
and write directly there. Plans live in experiment folders, never in ephemeral storage.
You discover something significant
/doc finding <idx> "<title>"
then write finding content
Conversation wrapping up / context switch
/doc ckpt <idx> "<short-label>"
— short label only (2-5 words), then write body content into the file with What/Why/How + mermaid diagram. Do this automatically without being asked.
"Research X" / "Look into Y"
/doc research <idx> "<topic>"
— write prompt, do research, write results
"Review X" / "Check this output"
/doc review <idx> "<title>"
then write review content with verdict
"Remember this" / "Key learning"
/doc learn <idx> <domain> "<title>"
— write distilled insight
"Continue experiment 19" / "Pick up"
/doc resume <idx>
— reads meta + latest plan + latest checkpoint. Set as active for this conversation.
"What experiments exist?"
/doc list
"What's the state of experiment 19?"
/doc status <idx>
用户说...你需要...
"Let's investigate X" / 开始新工作
/doc start "<name>"
— 记住返回的索引
"Plan this" / "How should we approach"
/doc plan <idx> "<title>"
然后将计划内容写入生成的文件
用户进入计划模式停止。 请勿使用
.claude/plan.md
。请运行
/doc plan <idx> "<title>"
并直接在生成的文件中编写内容。计划必须存储在实验文件夹中，绝不能放在临时存储里。
你发现重要内容
/doc finding <idx> "<title>"
然后编写发现内容
对话即将结束/切换上下文
/doc ckpt <idx> "<简短标签>"
— 标签仅需2-5个单词，然后将正文内容写入文件，包含内容/原因/方法 + mermaid图表。无需用户请求，自动执行此操作。
"Research X" / "Look into Y"
/doc research <idx> "<主题>"
— 编写提示词，开展研究，写入结果
"Review X" / "Check this output"
/doc review <idx> "<标题>"
然后编写包含结论的审核内容
"Remember this" / "Key learning"
/doc learn <idx> <领域> "<标题>"
— 编写提炼后的见解
"Continue experiment 19" / "Pick up"
/doc resume <idx>
— 读取元数据 + 最新计划 + 最新检查点。将其设为本次对话的活跃实验。
"What experiments exist?"
/doc list
"What's the state of experiment 19?"
/doc status <idx>

Context resolution (when user doesn't give an index)

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

  1. Experiment created or resumed in this conversation → use it
  2. User referenced one by name/number → use it
  3. User's request clearly relates to one experiment → use it
  4. Ambiguous → ask: "Which experiment?" then run 
    /doc list
    to show options
You resolve context. Scripts just take a number.
  1. 本次对话中创建或恢复的实验 → 使用该实验的索引
  2. 用户通过名称/编号引用的实验 → 使用该实验的索引
  3. 用户的请求明确关联某个实验 → 使用该实验的索引
  4. 存在歧义 → 询问："要操作哪个实验？"，然后运行
    /doc list
    展示可选实验
由你负责解析上下文。脚本仅接受数字索引。

Auto-behaviors

自动行为

  • Checkpoint automatically at natural stopping points — end of conversation, before context switch, after a milestone. Don't wait to be asked.
  • Plans go in experiments. NEVER write plans to 
    .claude/plan.md
    or any ephemeral storage. ALWAYS use 
    /doc plan
    .
  • Never overwrite. Always create new numbered files. Plans evolve: 01, 02, 03.
  • Resume before continuing. When picking up an existing experiment, run 
    /doc resume
    first to load context.
  • 自动创建检查点：在自然停顿点自动执行——对话结束时、上下文切换前、完成里程碑后。无需等待用户请求。
  • 计划必须存储在实验文件夹中。 绝不能将计划写入
    .claude/plan.md
    或任何临时存储。务必使用
    /doc plan
    命令。
  • 禁止覆盖。 始终创建新的编号文件。计划版本迭代：01、02、03。
  • 继续前先恢复。 当继续处理已有实验时，先运行
    /doc resume
    加载上下文。

Checkpoint content — MANDATORY

检查点内容要求 — 必须遵守

The 
ckpt
command arg is a short label (2-5 words), NOT the checkpoint content. After the script creates the file, you MUST write the body into it using this structure:
markdown
```mermaid
graph LR
    A[Starting state] --> B[What was done]
    B --> C[Current state]
    C --> D[Next steps]
```
ckpt
命令的参数是简短标签（2-5个单词），而非检查点内容。脚本创建文件后，你必须按照以下结构编写正文：
markdown
```mermaid
graph LR
    A[Starting state] --> B[What was done]
    B --> C[Current state]
    C --> D[Next steps]
```

What

What

What was accomplished. Bullet points, brief.
完成的内容。使用项目符号，简洁描述。

Key Takeaways

Key Takeaways

Surprising findings, confirmed/rejected hypotheses, numbers that matter.
意外发现、已证实/推翻的假设、关键数据。

Issues

Issues

Blockers hit, workarounds used, unresolved problems. Include error messages if relevant.
遇到的阻碍、使用的解决方法、未解决的问题。如有相关错误信息请一并附上。

Decisions

Decisions

Key choices made and why. What was considered and rejected.
做出的关键选择及原因。考虑过的方案及放弃的原因。

Next

Next

Concrete next steps with enough detail that a new agent can pick up cold. Include file paths, command examples, and what to watch out for.

The checkpoint must contain **everything a fresh agent needs to continue the work without asking questions.** Be brief but complete — file paths, key numbers, what worked, what didn't.

**DO NOT** cram content into the description argument. Keep the arg short: `/doc ckpt 7 "v1 analysis complete"` then edit the file.
具体的下一步操作，需足够详细以便新Agent无需询问即可接手。 包含文件路径、命令示例及注意事项。

检查点必须包含**新Agent接手工作所需的全部信息，无需额外询问。** 内容需简洁但完整——包括文件路径、关键数据、有效方法及无效尝试。

**请勿**将内容塞进描述参数中。参数需简短：`/doc ckpt 7 "v1 analysis complete"`，然后编辑文件。

Experiment Structure

实验结构

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
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

Setup

设置

/doc start my-investigation
— that's it. Scaffolds docs/ and creates the first experiment.
To customize folder structure or naming: edit 
config/defaults.yaml
inside the skill.
/doc start my-investigation
— 仅此一步即可完成设置。搭建docs/目录结构并创建首个实验。
如需自定义文件夹结构或命名：编辑Skill内部的
config/defaults.yaml
文件。

Rules

规则

  1. Scripts only create empty templates (frontmatter + headings). YOU must write the actual content into the file after the script runs. Never treat the script call as the finished step.
  2. Always use the scripts for file creation. Never manually create experiment dirs or edit 
    .meta.json
    .
  3. Index is just the number. 
    23
    not 
    023
    not 
    023-docs-and-structs
    .
  4. No auto-commit. Scripts scaffold files — you or the user decide when to commit.
  5. Plans go in experiments. Never in 
    .claude/plan.md
    . This is non-negotiable.
  6. Files are immutable. Don't edit old plans/findings — create a new numbered one.
  7. Valid learnings domains are listed in 
    config/defaults.yaml
    . 
    learn
    will error on invalid domains.
  8. Keep titles short. Titles become filenames. Use 2-5 words max — concise and descriptive. 
    "auth-flow"
    not 
    "investigation-into-authentication-flow-reliability-issues"
    . The numbering prefix handles ordering; the title just needs to identify the topic at a glance.
$ARGUMENTS
  1. 脚本仅创建空白模板（前置内容 + 标题）。脚本运行后，你必须将实际内容写入文件。 绝不能将脚本调用视为完成步骤。
  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