Explain Work Visually

Skill · explain-work-visually

The work is done. Checking it is the hard part.

Explain Work Visually is a skill for AI agents. When an agent finishes a task, it builds a single web page. It explains what it did, shows the evidence, and flags the decisions it made for you. You can highlight any sentence, leave a note, paste a screenshot, and send the page back. This page was built by the skill, about the skill.

One HTML fileNo servers, build steps, or extra setup.
7 steps, 2 gatesThe agent drafts everything, then cuts the noise.
5 key judgmentsOnly important decisions make the page.
A full round tripYour notes go straight back to the agent in the same file.

Chat logs show what happened. They don't tell you what to check.

An agent can write hundreds of lines of code in seconds, but verifying its assumptions takes hours. This skill turns the summary into a visual report you can read, mark up, and hand back to the agent before it touches your codebase.

The review round trip between you, the agent, and the report Eight ordered messages. You ask the agent for work. The agent works and keeps a private working record. The agent publishes one self-contained HTML report. The report states the outcome, the evidence, and the open judgments. You highlight text, write notes, and paste screenshots into the same page. The page exports an annotated copy of itself. You return that copy to the agent. The agent reads every note before it starts new work. You The agent The report 1 Do the work. 2 Works, and keeps a working record. 3 Publishes one self-contained HTML file. 4 States the outcome, the evidence, and the open judgments. 5 You highlight text, write notes, and paste screenshots. 6 Exports an annotated copy of itself, with your notes inside. 7 You return that copy. 8 Reads every note before new work.
Read from top to bottom. Solid lines show hand-offs. The dashed line is the file downloading to your computer. Steps 5 to 8 are what normal chat misses.

Scroll the diagram sideways to see all of it.

02

Why it exists

Chat logs follow the agent's timeline. The report follows yours.

Agents can now work for hours on their own. When they finish, they hand you a wall of confident text. It sounds convincing, but checking it takes forever. Worse, risky assumptions look just as confident as solid facts.

Reading chat

Follows the agent's timeline

  • Every small step is listed with equal importance.
  • Big choices get buried in the middle of routine logs.
  • Confidence is claimed, not proven. You can't tell what was tested.
  • To give feedback, you have to re-explain what you're talking about.

Fine if you already know what you're looking for.

Reading the page

Focuses on what matters to you

  • The final outcome sits right at the top.
  • Assumptions, risks, and leftover tasks are grouped together.
  • Claims show proof, and unverified points are clearly marked.
  • Feedback pins directly to the words you want to change.

Takes a moment to make. Much faster when you need to decide if you trust the work.

When to use which

Read the chat log if you already know the specific answer you need. Ask for a visual report when you need to decide if the work is safe to merge, ship, or build on.

Real example · The chat summary

“I added the skill files and wrote the report.”

Sounds neat and complete, but conceals all the real questions:

  • Doesn't mention what was actually tested vs. assumed.
  • Hides the fact that it was only verified in a single browser.
  • Gives no hint whether the skill works on large, complex codebases.

Result: False confidence. You have to take the agent's word for it.

Real example · What this report showed

Surfaces the facts, limits, and real boundaries

Presents the evidence clearly so you can judge for yourself:

  • Separates sources: Distinguishes code facts from single-test observations.
  • Calls out boundaries: Openly states it was tested on Chrome/Mac and needs large-repo testing.
  • Enables review: Lets you leave numbered notes directly on the claims that matter.

Result: Real confidence. You see the evidence and decide what to trust.

03

The procedure

The page is filtered by a clear checklist, not generated at random.

The skill has 181 lines of rules and reference guides behind it. Most of what the agent tries never goes into the report. Two quality gates filter out the fluff.

The seven steps and two gates that produce a report Step one copies the canonical template. Step two reads returned feedback first, and applies only when the input is an already annotated report. Step three builds the reader and evidence picture. A gate then asks whether an unresolved question could make the work wrong. If yes, the agent pauses and that exact question opens the report. If no, work continues at step four, which discovers the explanation and runs the salience gate that removes routine work. Step five composes for a short scan and a deeper audit. Step six reviews the rendered page. Step seven exercises the feedback system as a reader, and any failure sends the work back to step six for repair. Delivery happens only when every gate passes. 1 · Copy the canonical template Never start from blank HTML. 2 · Read returned feedback Only for an annotated report. 3 · Build the evidence picture Inspect the artifacts, not the chat. Could an open question make the work wrong? Pause That question opens the report. Yes No 4 · Discover the explanation The salience gate cuts routine work. 5 · Compose two depths A short scan and a deeper audit. 6 · Review the rendered page Look at the page, not the source. 7 · Use the feedback system Select, comment, export, reopen. Deliver Only when every gate passes. Repair
Follow the arrows from step to step. The dashed line loops back if something needs fixing. The diamond is Gate 1 (checking for doubts). The final box is Gate 2 (only delivered if all tests pass).

Scroll the diagram sideways to see all of it.

Why this protects you

Two steps exist solely to keep the agent honest:

Step 3 stops the agent from guessing. If the agent is unsure about something that could break your project, it has to stop and ask. Without this check, agents guess quietly in a confident tone, and you only discover the bug weeks later.

Step 7 makes the agent test the feedback tools before handing the page to you. The agent actually clicks, highlights, comments, and exports the file to make sure everything works. That way, you never get stuck trying to leave feedback on a broken button.

The 7 steps in plain English
  1. Start with a fresh template. Every report begins with clean, standard code instead of messy leftovers.
  2. Read existing feedback first. If you already sent back notes, the agent addresses every comment before touching any code.
  3. Gather real evidence. Check actual project files, separate facts from assumptions, and pause if a big question is still unanswered.
  4. Structure the explanation. Group the answers around your real questions and cut routine clutter.
  5. Write for two reading speeds. Put the quick summary upfront for a 30-second scan, and details below for a deep dive.
  6. Check the actual page in a browser. The agent opens the rendered page to see what you will see, rather than just inspecting raw code.
  7. Test the comment tools. The agent highlights text, writes a test note, attaches an image, and exports the file to confirm it works.
04

What makes the cut

A weak report dumps doubts on you. A strong report gives you clear choices.

Anyone can dump a wall of text. The real test of an agent is whether its questions respect your time. Instead of asking lazy, open-ended questions, the agent filters all its work through five critical decision types.

The five decision types the report can surface, what each one protects the reader from, and what the report must show for it.
What gets flaggedWhy it mattersWhat the report must show
AssumptionsStops you from building on an unproven guess.The guess, why it was made, what breaks if it's wrong, and how to verify it.
Key choicesFlags big decisions (like new tools or irreversible changes) made on your behalf.What was chosen, why, what alternatives existed, and how easy it is to undo.
UncertaintyPrevents false confidence when data is missing or untested.What was checked, what is still unknown, and the quickest way to find out.
Human decisionsMakes sure trade-offs, preferences, and permissions stay in your hands.The exact options, a suggested pick if possible, and what input is needed.
Leftover workMakes sure unfinished tasks aren't disguised as finished.What's done, what's left, who needs to do it, and the next step.

Weak question · Lazy hand-off

“Is one example enough to prove this works?”

What went wrong: The agent dumps its raw, unorganized doubts in your lap.

  • Forces you to investigate: You have to dig through files to find out what was actually tested.
  • No recommendation: The agent provides no suggested answer or risk assessment.
  • Vague stakes: You don't know what breaks if you say yes or no.

The cost: You spend 15 minutes doing the analysis the agent should have done.

Strong question · Decision-ready

“The core loop is verified here, but untested on large repos. Run on legacy backend now, or ship to beta?”

Why it works: States what is proven, isolates the unknown, and offers clear paths.

  • Clear boundaries: Separates proven facts (core loop runs) from open limits (large codebases).
  • Actionable trade-off: Gives you two distinct options with known trade-offs.
  • Fast to decide: You can answer in 5 seconds without opening a single code file.

The payoff: Respects your time. You make the judgment call and move on.

How the filter works

Every decision is tested on its own and as part of the whole picture. Small routine choices stay in private logs; only decisions that could change your mind earn space on the page. If no risky assumptions or open questions survive the filter, the section is left off entirely—meaning the work is clean and ready to go.

05

Anatomy

The layout stays predictable so you can focus on the content.

Every report uses the same clean frame: the same header, navigation, layout width, and comment tools. Only the explanation changes. You learn how to use it once, and every report feels familiar.

The anatomy of a report page, with six labelled regions A wireframe of the report. Region one is the sticky header holding Export and Feedback, and it is fixed. Region two is the section index rail, also fixed. Region three is the outcome statement, which is written for each report. Region four is the evidence strip. Region five is the primary visual on a dark stage. Region six is the comment composer with its numbered pin, which is fixed. Regions three, four, and five change with the subject. Regions one, two, and six are identical in every report. Report title Export Feedback The outcome, in one sentence Evidence strip Scale Proof Primary visual The relationship that matters. Optional evidence, folded away Add comment Screenshot Save 9 1 2 3 4 5 6
A wireframe of the layout. The numbered items below show which parts stay fixed across every report and which parts adapt to the task.

Scroll the diagram sideways to see all of it.

  1. 1Fixed. Export & Feedback buttons always sit at the top right, never hidden in a menu.
  2. 2Fixed. Section links stay in a sidebar on desktop or a top bar on mobile, giving every note a permanent address.
  3. 3Contextual. The outcome statement leads with the final result or the single question that matters—no filler.
  4. 4Contextual. The evidence strip highlights project-specific metrics like scale, risk, or test coverage.
  5. 5Contextual. Primary visuals adapt to the problem (flowcharts, sequence diagrams, or wireframes). If no diagram is needed, plain text is used instead of fluff.
  6. 6Fixed. The comment composer, numbered pins, screenshot pasting, and HTML export work the exact same way on every page.
Why this helps

You never have to figure out a new interface. The layout stays consistent, so the agent can't hide messy thinking behind flashy design.

06

The return leg

Comments attach to exact words, so you don't have to explain where they go.

Giving feedback to an agent is usually tedious because you spend half your time explaining which paragraph you mean. Here, your notes attach directly to the highlighted text.

  1. Highlight any text on the page

    Select text with your mouse or keyboard across headings, lists, or sections. A simple Comment button pops up right next to your selection.

  2. Type a note and paste screenshots

    A draggable note box opens. Type your thoughts, paste images directly from your clipboard, or upload files (up to 4 images per note). Everything stays saved inside the file in your browser.

  3. Each comment gets a permanent number

    Saving drops a numbered pin beside your highlight. That number never changes—even if you edit, delete, or reorder notes. Comment 4 will always be Comment 4.

  4. Send it back however you like

    Click Export to download an updated HTML copy with your notes included, or open the drawer and click Copy all as Markdown to paste directly into chat. Both formats keep your exact words paired with the highlighted text.

    # Review comments

## Comment 1

**Section:** The loop

**Highlighted content**

> Usually, an agent dumps a long message in chat and stops.

**Comment**

This is the claim I most want proof of. Show the returned file, not the promise.

  5. The agent addresses every note before making changes

    When you return an annotated report, the agent must plan how it will handle every single comment before modifying any files. If two notes seem to conflict, it asks for clarification instead of guessing.

The Feedback drawer open on this report. Comment 1 is pinned to two sentences in The loop, and shows the quoted sentences, the note written about them, and an attached screenshot, with View highlight, Edit, Delete, and Copy all as Markdown.
The feedback drawer with the real comment used while drafting this section. Your notes, quote snippets, and screenshots stay bundled together.
How highlights stay attached if text moves

When you leave a note, the page creates a 3-tier safety net so your comment never gets lost or misplaced:

  1. Exact spot: On page load, it tries the exact position in the section first.
  2. Exact quote: If paragraphs were edited or rearranged, it automatically searches the section for your quoted words.
  3. Surrounding context: If the same phrase appears in multiple places, it checks the surrounding sentences to snap to the exact paragraph you highlighted.

If text was heavily rewritten or deleted, the note is marked as ambiguous or unresolved in the drawer—so your feedback is never quietly dropped.

07

Limits and cost

What this page can't tell you, and when to skip it.

A report shouldn't just praise itself. Here are three honest limits to keep in mind.

Limited test data

Everything here comes from two sources: the skill's source files and this single test run. There is no third-party benchmark or measured time-savings yet. What the skill does is documented in code; whether it is useful for you is best tested on your own projects.

When not to use it

Generating a full page takes extra tokens and time. For a quick one-line bugfix, checking the git diff is much faster. Use this report when an agent ran a long, complex task on its own, or when you need to review and hand off work you didn't watch being built.

Browser testing

This page was verified in one modern browser on a Mac, tested at mobile and desktop widths. It runs entirely offline without servers or dependencies, so you can test it locally by opening the file.

The main takeaway

A good report isn't a play-by-play log of everything the agent did. It highlights only the key decisions and evidence you need to evaluate the work, making it easy to review and give feedback.

Open source

Explain Work Visually is open source—just a folder of reference files and an HTML template. Any agent with access to skills can use it. View Explain Work Visually on GitHub.