Building a Better Workflow for Agent-Generated HTML Writeups

Why I use HTML instead of Markdown

I first came across Thariq’s idea of using HTML for plans and, honestly, didn’t think much of it. Markdown had always been good enough for most of my use cases, so I didn’t see much reason to switch.

But there are a couple of situations where I need to understand the code or architecture of a codebase more effectively, especially with good visualization and interactivity. So, I started asking my agent to generate an HTML file for those cases, and I was honestly impressed. It not only helped me understand the content better, but it also made the overall look, feel, and reading experience much better. A nicely formatted HTML document, with its visual and interactive elements, makes things click for me in a way a plain Markdown file never did.

Since then, I haven’t looked back. Anytime I need to understand something in depth or read through a plan carefully, I ask my agent to generate an HTML document.

Making My Agent Better at HTML

So, I built a SKILL.md called HTML-Writeup that contains all the details I need for making HTML files look good, easy to read, and easy to write, along with some other guidelines. Every time the agent creates an HTML plan, it looks at this skill.

But there was one problem. Most of the time, when I asked my agent to generate an HTML file, it would save it in a local folder. That’s fine until I ask it to create a document and then step away from my laptop to go for a walk. At that point, I can’t view any of it on my phone.

So, I built a small service called plan-hub to solve this. It runs a single command that uploads HTML files to Cloudflare R2 (ph-upload), and there is an Astro website that fetches and displays them. This has also helped me a lot with remote agentic development. I can prompt my agent from my phone, have the agent upload the result to the service, and then read it in my browser.

The idea came from Theo, one of my favorite tech YouTubers. He has a service called PostPlan where his agents upload HTML plans. After seeing that, I got the idea to build something similar. I could have just used his service, but I figured, why not build my own and learn something along the way?

It took about a day to build, and I have been using it ever since.

The Skills I Use with HTML

Here are some skills I pair with it:

1. Unslop, a skill by Poteto. It makes AI agents sound more natural and human. It’s a global skill, so whenever an agent writes text in its output, it uses this to keep the tone plain and readable. AI agents love em dashes and over-decorated text, which is unnecessary when all I want is to understand what the agent did or plans to do. In the html-writeup skill, I specifically use Unslop to generate the body text. Very helpful.
2. Eli5, which Thariq recently posted about. I always asked agents to explain things as if I were five, but I never thought I needed a skill for it since agents are smart enough to figure out what I mean. Still, after Thariq posted about it, I have used it a few times, and now a slash command gets me a simple explanation.

Building the upload service

I built plan-hub around Cloudflare R2 and an Astro site deployed to Cloudflare Workers.

For uploads, I wrote a small CLI script (ph-upload) that wraps the wrangler CLI. Once authenticated with wrangler login, the agent (or I) runs ph-upload plan.html. The script verifies the file ends with .html or .htm, runs wrangler r2 object put with the text/html; charset=utf-8 content type, and outputs the viewable URL.

The frontend is an SSR Astro app running on Cloudflare Workers. On the home page, it fetches all the HTML files stored in the R2 bucket and displays them as a list of titles. When I click on any title, it opens that HTML file by using its file key (the file name or path stored in the R2 bucket, such as plan.html) to retrieve the file from R2 and stream the HTML directly to the browser.

Auth was the tricky part. On the upload side, authentication is handled through the Wrangler CLI using Cloudflare R2 access. On the web side, I needed secure login restricted to my email, but I didn’t want to deal with configuring OAuth apps and credentials in the Google Cloud Console. I used Shoo, a project by Theo, to handle the sign-in flow and return the user’s profile details. The Cloudflare Worker then checks the email against an allowlist and only lets approved users in.

That’s the whole thing: a small service that made remote agentic development much nicer for me. I hope you like the idea and maybe build something similar yourself.