Done Means a Link: How I Turn Codex Results into Reviewable HTML Reports

An AI agent can finish the hard part of a task and still leave the work unusable.

It researches the question, compares the options, and builds a polished HTML report. Then it returns a local path such as /output/report/index.html. The result looks good on my machine, but the teammate who needs to review it cannot open that path.

So I changed the completion rule:

A report is not done when the HTML exists. It is done when another person can open it from a link.

After one setup, the Agent can publish a polished, interactive webpage and return its link in the same conversation.

Why a local report is still an unfinished result

Chat is useful for directing an agent, but it is rarely the best place to read a substantial result. A serious analysis may contain a conclusion, comparison tables, charts, evidence, risks, and an appendix. In a transcript, all of those layers become one long scroll.

A local HTML file fixes the reading experience but not the handoff. A PDF travels easily, but it flattens interactive charts, expandable evidence, filters, and internal navigation.

The format I wanted was simple: a self-contained HTML report behind one browser link.

More importantly, I wanted a loop rather than a one-way export:

task → AI analysis → readable HTML → share link → anchored feedback → revision

The agent should not stop at “file written” or even “upload succeeded.” The openable link is the deliverable.

A concrete task

Take a typical assignment I might give Codex before a refactor:

Audit the error handling in src/api/.

Create a self-contained HTML report for a service owner
who has not seen this conversation:
- put the verdict and fix order first;
- include a findings table with severity, location, and evidence;
- give each finding a stable id in the markup;
- move detailed methodology into collapsible sections;
- make the page readable on desktop and mobile;
- do not load external scripts or fonts.

Use the html-report-sharing Skill to publish the report.
Return the openable share link in this conversation.
The task is not complete until the link is here.

This prompt defines three separate outcomes: the quality of the analysis, the reading experience, and the human handoff.

Two phrases do a surprising amount of work. “For a service owner who has not seen this conversation” forces the agent to write for a cold reader instead of assuming the transcript as context. “The task is not complete until the link is here” gives it a testable stopping condition.

Set up the Skill once

If all you need is read access, any static host closes the gap: GitHub Pages or a Netlify drop serves the same HTML. What pushed me to a report-sharing service was the second half of the loop — element-anchored comments the agent can read back later — without me building authentication and a comment API around a static site.

The setup starts on ReportArk’s Skills page:

1. Create an API key with only the report and comment permissions the agent needs.
2. Install the generated html-report-sharing Skill into the agent’s skills directory — for Codex that is ~/.codex/skills/html-report-sharing/.
3. Keep the service base URL and API key in the Skill’s private .env file, which its bundled client loads before each call.
4. Start a fresh Codex or Claude Code session so it discovers the Skill.

The credential stays in local configuration. It does not belong in the prompt, the report, the repository, or the share URL. Once the setup is finished, I no longer explain the upload API in every task. I describe the report I want and name the Skill.

What happens after the analysis

The agent writes a small static site. It can include HTML, CSS, JavaScript, images, and fonts, but the zip it uploads must contain index.html as its entry point.

The Skill then has a narrow job:

1. Package the report directory as a zip.
2. Upload the complete package with a title and plain-text description.
3. Verify that the service accepted it.
4. Extract the final share URL.
5. Put that URL back into the conversation.

Keeping the Skill narrow is deliberate: it does not decide how to research the topic or structure the argument. It only owns the repeatable publishing and feedback operations.

The result opens as a normal interactive report. The reader does not need the repository, a development server, or instructions for finding a local file.

The feedback loop is better than the link alone

A share link solves access. Contextual comments solve the next problem: feedback that becomes detached from the thing it refers to.

Without anchors, a reviewer might write “finding three is wrong” in a chat thread. Someone then has to locate finding three, interpret the objection, and carry it back to the agent. In this workflow, the reviewer can comment beside the exact heading, table row, chart, or recommendation.

Each anchor records enough structure for the agent to locate the feedback later: the page path, a CSS selector for the element, the selector’s match index, and the quoted text. This is why the earlier prompt asked for stable IDs and semantic headings — a selector like #finding-3 survives a revision; the fourth anonymous <div> on the page does not.

In a later session, I can ask:

List the comments on the error-handling audit report.
For each comment, identify the section and quoted text
it is anchored to. Group the requested changes and propose
a revised fix order. Do not create or delete comments.

I deliberately keep the first feedback pass read-only. The agent explains what the reviewer objected to and proposes a revision; I decide what should change before anything is published again.

Permission boundaries worth understanding

Connecting an agent to a publishing service should not turn its API key into a universal account credential.

• Reading and commenting are separate. While sharing is enabled, anyone with the link can read the report. Leaving a comment requires a signed-in, approved account, plus clearance for that report when it has one.
• Comment actions use separate scopes. Listing comments does not automatically grant permission to create or delete them.
• The publishing key is not a browser session. It cannot act as the report viewer, fetch protected report assets directly, or manage other API keys.
• A share link can be forwarded. Reports containing secrets, private code, customer data, or personal information still need a classification check before upload.

The Skill makes publishing repeatable. It does not make every result appropriate to publish.

What made the workflow reliable

After using this pattern for audits, comparisons, plans, and research summaries, four rules have mattered more than the upload itself.

Make delivery part of the acceptance criteria. If the prompt only asks for a report, the agent may reasonably stop after writing a file. Ask for the openable link and make it the completion test.

Name the reader and the decision. “Write a report about error handling” produces a document. “Write for the service owner who must choose the fix order” produces a decision tool. The conclusion moves up, evidence becomes easier to scan, and methodology stops dominating the page.

Design the HTML for feedback. Stable IDs, meaningful headings, tables with clear rows, and concise text blocks give comments precise places to land.

Read feedback before acting on it. A read-only first pass lets the agent organize objections without silently changing or deleting the human discussion.

The broader lesson

A Skill made the publishing step repeatable, but the most useful change was not teaching Codex one more API call. It was moving the definition of “done” to the point where another human can actually use the work.

The same test works for audits, benchmarks, research comparisons, launch plans, and data analysis: can the person who needs this open it right now, understand the conclusion without the original chat, and respond in context?

If not, the agent may have finished computing, but it has not finished delivering.

If you want to try this workflow, configure the HTML report sharing Skill on ReportArk and add one sentence to your next report prompt: “The task is not complete until the openable link is in this conversation.”