readout Skill (warpdotdev): Turn Findings Into an HTML Doc

Makes your agent write up an investigation as a single polished HTML page you can share, saved in ~/.readouts with an auto-built index.

Installs: 17.6K; on skills.sh
Stars: 644; on GitHub
Files: 5; besides SKILL.md
Updated: Oct 2026; last repo commit

readout works in two modes. In snapshot mode you say "write this up" and the findings from the current chat become a document. In research mode you give a topic, such as how GitHub webhook events are processed, and the agent investigates the code before writing. Either way it asks 2 to 4 short questions first about scope, depth and audience, then hands the writing to one child agent so your main chat stays light.

The result is one HTML file with all CSS and JavaScript inline, written to ~/.readouts/<date>-<topic>.html, plus a regenerated index.html listing every readout. Code references become links pinned to a commit and open in a side pane. The skill is written around Warp's agent tools (run_agents and search_conversation_history). If child agents are not available it tells the main agent to write the document itself.

Good for

Engineers who want a codebase investigation written up for teammates
Anyone ending a long chat who wants the findings saved as a readable page
Agents that can launch a local child agent (it calls run_agents); others write the page themselves

Install readout

Claude Code

Copy this prompt.

Install the readout skill in Claude Code. Run this command:

npx skills add https://github.com/warpdotdev/common-skills --skill readout

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

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. "/readout on how github webhook events are processed" — by sharpening scope with clarifying questions and researching the codebase before documenting. The work runs in a child agent so the main conversation's context stays clean. Use whenever the user invokes /readout, says "write this up", "turn this into a doc/page", "make a readout", or asks for a readable, shareable document capturing findings or explaining how something works.

Sections in SKILL.md

Orchestrator workflow
1. Sharpen the scope — ask before launching
2. Compose the brief
3. Launch one local child agent
4. Get back to work
Child agent prompt template
Fallbacks

Key facts

Author: warpdotdev
Repo: warpdotdev/common-skills
License: MIT (as listed by the crawl)
Installs on skills.sh: 17,608 (Nov 2, 2026)
GitHub stars: 644 (repo, Nov 2, 2026)
Last commit: 2026-10-28
Files: 6 files including SKILL.md: 1 guide, 2 HTML assets and 2 Python scripts
Output: ~/.readouts/<date>-<topic>.html plus index.html
Needs: python3 for the helper scripts; git checkout to embed source

What it includes

Starts the skill; also "write this up", "turn this into a doc", "make a readout"
Snapshot mode uses the current chat. Research mode takes a topic, as in "/readout on how github webhook events are processed".
Try: “/readout on how github webhook events are processed in the server”
Write · /readout
Asks 2 to 4 questions with concrete options, including depth and audience
Skipped when the request is already specific. A shrug is accepted and recorded in the brief.
Sharpen the scope
Writes a 10 to 20 line brief of pointers: topic, questions, scope, repo paths, commit
It passes pointers, not pasted findings. The child agent pulls detail from the chat history itself.
Compose the brief
Runs one local child agent named readout-<topic> that does the research and writing
It runs locally so the file lands on your machine and opens in your browser.
Runs code · Launch one child agent
Writes one self-contained .html from assets/template.html to ~/.readouts
The shared styling blocks are copied verbatim so every readout looks alike. If the filename exists it adds -2, -3 and so on.
Write · HTML document
Embeds referenced source files at their pinned commit into the document
Uses git show on local checkouts and ships the source inside the HTML, so it also works offline and for private repos.
Runs code · embed_snippets.py
Regenerates ~/.readouts/index.html listing every readout, newest first
Rebuilds the index from the readouts folder each time it runs.
Runs code · update_index.py
Writes the doc itself if child agents are unavailable, or takes a pasted summary
Also accepts transcripts, files or links as the source material in place of a conversation.
Fallbacks

From the official docs

Permissions

Low risk

The skill writes HTML files to ~/.readouts and can embed your source code inside them. Check who will get a page before you share it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

Embedded source travels with the file
embed_snippets.py puts whole referenced files into the HTML. Check who will receive the page before you share it. github.com
It writes outside your project
Documents and the index go to ~/.readouts, and the skill runs python3 update_index.py and embed_snippets.py. github.com
The code pane can ask a reader for a GitHub token
For private repos the finished page offers a paste-a-token form that retries through api.github.com; the doc guide says the token stays in that tab's sessionStorage and never goes into the document. Never put a token in a readout. github.com

Technical details

Talks to	raw.githubusercontent.com, cdnjs.cloudflare.com (highlight.js) and api.github.com (only if a reader pastes a token), all only when a reader clicks a code link in the finished page

Questions

What does readout do?

It turns an investigation into a durable HTML page that someone can read weeks later without the original chat. It can summarise the current conversation or research a topic in your codebase first, then write the page.

How do I install readout?

Use the install box above. The skill is one folder with a template, a guide, a code-viewer asset and two Python scripts, so copy the whole folder, not just SKILL.md.

Where does it save the document?

In ~/.readouts as <date>-<topic>.html, with an index.html beside it. It opens the file in your browser unless the environment is headless.

Does it work outside Warp?

The repo README does not name supported clients. SKILL.md is written around Warp-style tools (run_agents, search_conversation_history), and it says the main agent should write the document itself if child agents are unavailable.

Do I need an API key or Python?

SKILL.md names no API key. The index and snippet scripts run with python3, and embedding source needs a git checkout of the repo you reference.

Can the page leak my private code?

It can. When a repo is checked out locally, the helper embeds the referenced files into the HTML, so anyone you share it with gets that source. The guide says to think about the audience before embedding.

Does the page work offline?

The document itself is meant to render fully offline. Only clicking a code reference can reach the network: it may fetch the file from raw.githubusercontent.com and load highlight.js from a CDN.

Is it safe to run?

It writes HTML files into ~/.readouts and runs two local Python scripts. The main risk is sharing a page that embeds private source. Do not paste tokens into the page.

Information

updated Nov 2, 2026

Repository: warpdotdev/common-skills
Folder: .agents/skills/readout

warpdotdev/common-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

readout SKILL.md · github.com
doc-guide.md · github.com
skills.sh listing · skills.sh
warpdotdev/common-skills · github.com
embed_snippets.py · github.com
update_index.py · github.com