Back to Details

readout

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Readout

Readout

A readout turns an investigation into a durable HTML document someone can read weeks later without any of the original context. It starts one of two ways:
  • Snapshot mode — invoked mid-conversation ("write this up"): the conversation's accumulated findings are the source material.
  • Research mode — invoked fresh ("/readout on how github webhook events are processed in the server"): there is no conversation to mine, so the investigation itself is part of the job.
Either way, invoking this skill is a side task. Your job as the main agent is to sharpen the scope, launch a child agent with a good brief, and get out of the way — the child does the mining/research and the writing, keeping that (often large) work out of your context window.
Readout可将调查内容转化为一份持久化的HTML文档，即使数周后阅读，读者也无需依赖任何原始上下文。它有两种启动方式：
  • 快照模式 —— 在对话中途调用（如“write this up”）：以对话中积累的发现作为素材。
  • 研究模式 —— 首次调用（如“/readout on how github webhook events are processed in the server”）：无对话内容可挖掘，因此调查本身也是任务的一部分。
无论哪种方式，调用此技能都是一项辅助任务。作为主Agent，你的职责是明确范围、为子Agent提供清晰的任务简报并让其独立工作——子Agent负责挖掘/研究和写作，将（通常体量较大的）工作内容移出你的上下文窗口。

Orchestrator workflow

编排器工作流

1. Sharpen the scope — ask before launching

1. 明确范围 —— 启动前先询问

A vague brief produces a vague document. Before launching you should be able to list the specific questions the document will answer; if you can't, interview the user first:
  • Ask 2–4 targeted questions, offering concrete options rather than open prompts — take a quick look at the code or topic first so the options are real (subsystems, entry points, competing concerns). For "/readout on how github webhook events are processed": which direction matters — inbound triggers, post-back, or both? a current-state reference or a gotcha hunt? which repo(s)?
  • Always pin down depth and audience: high-level orientation vs. deep mechanics with line-level grounding; personal notes vs. shared with the team.
  • Respect a shrug. "Just a high-level overview" is a valid answer — record it in the brief and move on rather than interrogating. Even then, try to extract the two or three questions the reader most needs answered; specificity is what makes a readout useful.
  • Skip the interview when the scope is already specific — a snapshot of a focused conversation, or a precise research request, needs no questions. In snapshot mode the conversation usually supplies the questions; ask only when the invocation is ambiguous about which threads to include.
模糊的任务简报会产出模糊的文档。启动前，你应当能列出文档需要解答的具体问题；如果做不到，先与用户沟通：
  • 提出2–4个针对性问题，提供具体选项而非开放式提问——先快速查看代码或主题，确保选项真实可信（如子系统、入口点、需要权衡的问题）。例如对于“/readout on how github webhook events are processed”：重点是入站触发、回传，还是两者兼顾？是当前状态参考还是问题排查？涉及哪些仓库？
  • 始终明确深度和受众：是高层概览还是带有代码行级细节的深入机制说明；是个人笔记还是团队共享文档。
  • 尊重用户的模糊答复。“只要高层概览”是合理的回答——将其记录在简报中即可继续，无需追问。即便如此，也要尝试提炼出读者最需要解答的2–3个问题；具体性是Readout实用价值的核心。
  • 当范围已经明确时，跳过沟通环节——聚焦对话的快照，或者精准的研究请求，无需提问。在快照模式下，对话通常已经提供了问题；仅当调用指令对需要包含哪些线程存在歧义时才需要询问。

2. Compose the brief

2. 撰写任务简报

Write a short brief (roughly 10–20 lines) carrying pointers, not payloads:
  • A working title / topic, and the mode (snapshot or research)
  • The specific questions the document must answer (from the conversation or the interview), plus depth and audience
  • Scope: which threads/subsystems to cover, and anything to explicitly exclude
  • Snapshot mode: headline conclusions worth centering the doc on, one line each — the child pulls the full content from conversation history itself, so don't paste findings wholesale
  • Research mode: starting pointers — entry-point files, symbols, or directories you already know about
  • Absolute paths to the repos/directories that ground the work
  • Each repo's hosted URL and the examined commit when known (e.g. 
    github.com/org/repo @ abc123
    ), so the document can hyperlink code references
撰写一份简短的简报（约10–20行），提供指向性信息，而非完整内容：
  • 暂定标题/主题，以及模式（快照或研究）
  • 文档必须解答的具体问题（来自对话或沟通），以及深度和受众
  • 范围：需要覆盖的线程/子系统，以及明确需要排除的内容
  • 快照模式：值得作为文档核心的核心结论，每条一行——子Agent会自行从对话历史中提取完整内容，因此无需粘贴全部发现
  • 研究模式：起始指向信息——已知的入口文件、符号或目录
  • 支撑工作的仓库/目录的绝对路径
  • 已知的每个仓库的托管URL和检查的提交记录（例如
    github.com/org/repo @ abc123
    ），以便文档可以添加代码引用的超链接

3. Launch one local child agent

3. 启动一个本地子Agent

Spawn exactly one child agent via 
run_agents
, local execution. Local matters: the document lands on the user's filesystem and opens in their browser. Name the child 
readout-<topic-slug>
.
Build the child's prompt from the template below. It must include:
  • The brief
  • The source-material block matching the mode (snapshot mode also needs your agent run ID — 
    current_run_id
    from the orchestration runtime context — so the child can mine the parent conversation with 
    search_conversation_history
    )
  • The instruction to read 
    references/doc-guide.md
    from this skill's directory before writing
  • The output path convention and completion protocol
通过
run_agents
启动恰好一个子Agent，采用本地执行方式。本地执行很重要：文档会保存到用户的文件系统并在浏览器中打开。将子Agent命名为
readout-<topic-slug>
。
根据以下模板构建子Agent的提示词，必须包含：
  • 任务简报
  • 与模式匹配的素材块（快照模式还需要你的Agent运行ID——即编排运行时上下文的
    current_run_id
    ——以便子Agent可以通过
    search_conversation_history
    挖掘父对话内容）
  • 要求在写作前阅读此技能目录下的
    references/doc-guide.md
    的指令
  • 输出路径约定和完成协议

4. Get back to work

4. 返回主任务

After launching, resume whatever you were doing, or end your turn — the child's completion message arrives on its own; relay the file path to the user with a one-line description when it does. In research mode a fresh conversation may have nothing else pending; just end the turn. Don't sit in a wait loop unless the user asked to wait for the document.
启动子Agent后，继续你之前的工作，或者结束当前轮次——子Agent完成后会自行发送消息；当收到消息时，向用户发送一行描述并附上文件路径。在研究模式下，新对话可能没有其他待处理任务；直接结束轮次即可。除非用户要求等待文档完成，否则不要进入等待循环。

Child agent prompt template

子Agent提示词模板

Adapt this; keep the structure, and include the source-material block that matches the mode.
You are producing a "readout": a single self-contained HTML document that answers a
specific set of questions about <topic>, for a reader who has none of this context.

Brief:
<brief — including the questions to answer, depth, and audience>

Source material (snapshot mode):
- The parent conversation: agent run ID <current_run_id>. Use search_conversation_history
  with agent_run_id set to that ID. Make several targeted queries — one per question in
  the brief — rather than one broad query; targeted queries surface far more usable detail.
- The codebase(s) at <absolute paths>. The conversation is your starting point, not a cage:
  verify file references before asserting them, and where a section needs more depth to
  stand on its own, go read the code and fill the gap.

Source material (research mode):
- Investigate directly in the codebase(s) at <absolute paths>. Let the brief's questions
  drive the investigation: trace the actual code paths, read the real implementations, and
  ground every claim in file:line references. Distinguish verified from inferred. Do not
  pad the document with generic knowledge — its value is what's true of THIS codebase.

- Repo host + commit for linked code references, if known: <github.com/org/repo @ commit>
  (otherwise derive from git; see the doc guide's "Linked code references").

Start from the canonical template at <skill-directory>/assets/template.html — its
data-readout chrome blocks must be copied verbatim so every readout looks like every
other. Before writing, read <skill-directory>/references/doc-guide.md and follow it.

Output:
- Write ONE self-contained HTML file to ~/.readouts/<YYYY-MM-DD>-<topic-slug>.html
  (create ~/.readouts if it doesn't exist; suffix -2, -3, ... if the name is taken;
  get the date from `date +%F`).
- Embed referenced source per the doc guide when a repo is checked out
  (<skill-directory>/scripts/embed_snippets.py).
- Refresh the readouts index: python3 <skill-directory>/scripts/update_index.py
  (fully regenerates ~/.readouts/index.html listing every readout).
- When the file is written, open it with `open <path>` (skip this if the environment is
  headless).
- Report back to your orchestrator: the absolute file path, a 2–3 sentence summary of what
  the document covers, and anything you could not verify.
按需调整；保留结构，并包含与模式匹配的素材块。
You are producing a "readout": a single self-contained HTML document that answers a
specific set of questions about <topic>, for a reader who has none of this context.

Brief:
<brief — including the questions to answer, depth, and audience>

Source material (snapshot mode):
- The parent conversation: agent run ID <current_run_id>. Use search_conversation_history
  with agent_run_id set to that ID. Make several targeted queries — one per question in
  the brief — rather than one broad query; targeted queries surface far more usable detail.
- The codebase(s) at <absolute paths>. The conversation is your starting point, not a cage:
  verify file references before asserting them, and where a section needs more depth to
  stand on its own, go read the code and fill the gap.

Source material (research mode):
- Investigate directly in the codebase(s) at <absolute paths>. Let the brief's questions
  drive the investigation: trace the actual code paths, read the real implementations, and
  ground every claim in file:line references. Distinguish verified from inferred. Do not
  pad the document with generic knowledge — its value is what's true of THIS codebase.

- Repo host + commit for linked code references, if known: <github.com/org/repo @ commit>
  (otherwise derive from git; see the doc guide's "Linked code references").

Start from the canonical template at <skill-directory>/assets/template.html — its
data-readout chrome blocks must be copied verbatim so every readout looks like every
other. Before writing, read <skill-directory>/references/doc-guide.md and follow it.

Output:
- Write ONE self-contained HTML file to ~/.readouts/<YYYY-MM-DD>-<topic-slug>.html
  (create ~/.readouts if it doesn't exist; suffix -2, -3, ... if the name is taken;
  get the date from `date +%F`).
- Embed referenced source per the doc guide when a repo is checked out
  (<skill-directory>/scripts/embed_snippets.py).
- Refresh the readouts index: python3 <skill-directory>/scripts/update_index.py
  (fully regenerates ~/.readouts/index.html listing every readout).
- When the file is written, open it with `open <path>` (skip this if the environment is
  headless).
- Report back to your orchestrator: the absolute file path, a 2–3 sentence summary of what
  the document covers, and anything you could not verify.

Fallbacks

回退方案

  • Child spawning unavailable or denied: produce the document yourself, following 
    references/doc-guide.md
    . If a research subagent is available, delegate the conversation-mining or code investigation to it so your context still stays lean.
  • Child can't search conversation history (snapshot mode; it will report this back): reply to the child with a distilled dump of the findings so it can proceed — this is the one case where payload-in-prompt is the right call.
  • User-provided material instead of a conversation (transcripts, files, links): treat that material as the source; everything else in the workflow is unchanged.
  • 无法生成或被拒绝生成子Agent：自行生成文档，遵循
    references/doc-guide.md
    的要求。如果有研究子Agent可用，将对话挖掘或代码调查任务委托给它，以保持你的上下文简洁。
  • 子Agent无法搜索对话历史（快照模式；子Agent会反馈此问题）：向子Agent发送提炼后的发现内容，使其可以继续工作——这是唯一适合在提示词中包含完整内容的情况。
  • 用户提供素材而非对话（如转录文本、文件、链接）：将该素材作为来源；工作流的其他部分保持不变。