warpdotdev/common-skills

readout

Produce a polished, self-contained HTML "readout" document under ~/.readouts (with an auto-maintained index page), either by snapshotting the findings accumulated in the current conversation or — when invoked fresh, e.g.

查看源码

使用方法

  1. 复制安装命令,在自己的智能体环境安装前先检查源码包。
  2. 从原始文档核对所需工具、凭据和支持的宿主。
  3. 说明输入材料与期望交付物,并对照来源检查输出。
npx skills add https://github.com/warpdotdev/common-skills --skill readout

开始前需了解

  • 安装不包含模型订阅、API 额度或访问文件的权限。
  • 仓库星数和安装量反映活跃情况,不等于独立质量或安全测试。
仓库原始内容

按源仓库内容呈现,保留标题、案例、代码、表格、链接以及原文引用的演示图片。

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.

Orchestrator workflow

1. Sharpen the scope — ask before launching

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. Compose the brief

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

3. Launch one local child 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

4. Get back to work

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.

Child agent prompt template

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.

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.

按任务相关推荐

来自同一仓库

更多 Skills

全部 Skills
warpdotdev
社区

council

Run a model-diverse subagent council to investigate the same problem from multiple perspectives, compare findings, and produce a final recommendation. Use this skill whenever the user asks for a council, second opinions, multiple agents/models to evaluate one question, parallel investigation, red-team/blue-team comparison, or help deciding between competing technical approaches.

1小时安装量
2
GitHub Stars
718
最近更新
11月11日
warpdotdev
社区

respond-to-pr-comments-in-blocklist

Interactively walk a user through PR review comments one at a time, collect a per-comment decision, then post agent-authored replies on GitHub and resolve the review threads once the user approves a preview. Use only when the user wants to reply to or resolve review threads on GitHub. Skip when the user only wants comments fetched or displayed (use pr-comments), or only wants the code changes made without posting anything back to GitHub.

1小时安装量
2
GitHub Stars
718
最近更新
11月11日
warpdotdev
社区

skill-doctor

Grades agent skills by scoring agent conversations for efficiency, code quality, procedure compliance, and verbosity, then drafts concrete skill edits and a shareable report. Use when the user wants their agent setup graded from real conversation history, or asks which of their installed skills are actually working.

1小时安装量
3
GitHub Stars
718
最近更新
11月11日
warpdotdev
社区

write-feature-docs

Draft a complete documentation page for a new Warp feature from its PRODUCT.md and/or TECH.md spec. Use when an engineer has written a spec and needs to produce a first-pass MDX draft for the warpdotdev/docs repo. Also handles features without specs by researching the codebase first. Invoke this skill whenever an engineer mentions writing docs for a feature, drafting a docs page, creating feature documentation, starting the eng-docs workflow, or converting a spec into documentation. Requires an

1小时安装量
2
GitHub Stars
718
最近更新
11月11日