Thariq recently wrote about HTML being a more effective output format from AI agents — his core point being that it helps humans "stay in the loop." Karpathy echoed the sentiment. The argument is simple: when agents produce output for humans, richer formats win. HTML is visual, navigable, and people actually read it. Markdown beyond 100 lines? Most don't.
But here's what's been on my mind: as tech and non-tech folks alike start using Claude Code and other AI tools to generate documents for each other — specs, proposals, analysis — I've noticed we're getting better at producing ideas and worse at understanding each other's. Everyone generates. Few truly read. In a recent project, I watched teammates (myself included) pass AI-generated docs back and forth, each one polished and structured, each one largely unread by the other party. Everyone keen to be understood, to get their point across, to prove their idea is the right one. But no one pausing to genuinely understand first.
"Seek first to understand, then to be understood."
I think this principle is harder to practice now than ever. AI validates whatever framing we give it. The output sounds right because it reflects our own assumptions back at us. We feel understood by the machine, so we stop trying to understand the human on the other end.
What This Skill Actually Does
This tool doesn't solve that communication problem. But it aligns with what Thariq is saying — if we're going to pass ideas around, the least we can do is make them easy to consume. Reduce friction between "I made this" and "you can read this." Maybe if things are easier to open and read, we'll actually do more reading and less generating.
The pain point I kept seeing from others:
People can generate beautiful HTML files with Claude Code
But then they're stuck — it's a local file
Sharing means "here's an attachment" or "double-click to open in Chrome"
Non-technical teammates can't easily view or access them
No one wants to set up hosting infrastructure just to share a spec
So I built a skill + CLI that makes sharing a one-command operation. No deployment knowledge needed. No infrastructure to manage. Just: generate HTML → share it.
Both are open source:
htmldrop CLI — the npm package, works standalone
Claude Code skill — guided conversational flow for non-technical users
How It Works
The setup is one-time and takes about 30 seconds:
Step 1: Install
npm install -g htmldrop
Step 2: Initialize (one-time)
htmldrop init
This asks you for:
A subdomain name (e.g.,
team-docs→ your files live athttps://team-docs.surge.sh/)Your email (for the free Surge.sh account)
A verification — click the link in your email, done
That's it. Just an email, verify once, done. I've open-sourced everything — use it, break it, give me feedback.
Step 3: Share anything
htmldrop push my-spec.html
# → Published: https://team-docs.surge.sh/my-spec.html
Two Ways to Use It
Mode 1: CLI directly — for terminal users or scripting:
htmldrop push report.html # Public
htmldrop push spec.html --password teamSecret # Private
htmldrop push internal.html --noindex # Public but hidden from crawlers
Mode 2: Claude Code skill — conversational, guided flow:
If you install the ccc skills collection, Claude Code becomes your sharing assistant. Just say:
"Share this HTML file"
Claude will ask you through a guided flow:
How would you like to share this?
Public — Anyone with the link can view it
Password-protected — Encrypted, viewers need a password
If you choose password-protected:
What password would you like? (or I can generate one)
Then it handles encryption (AES-256, in-browser decryption) and deploys:
Published with password protection!
URL: https://team-docs.surge.sh/spec.html
Password: blue-canyon-77
Share both with your team.
For public files, it asks one follow-up:
Block search engines and AI crawlers from indexing?
If yes — adds noindex tags so your internal discussions don't get scraped.
The skill is especially useful for non-technical users on Claude Code — no need to remember flags or syntax. Just describe what you want in plain English and the skill handles the rest.
Privacy Levels at a Glance
Level | Crawlers blocked? | Link-only access? | Content encrypted? |
|---|---|---|---|
Public | No | Yes | No |
Public + noindex | Yes | Yes | No |
Password-protected | Yes (encrypted blob) | Need password | Yes (AES-256) |
Password protection means: even if someone finds the URL, they see a password prompt and encrypted gibberish. No AI agent can index the content.
Why Not Just Use Google Drive or Notion?
You could. But:
Those require the recipient to have an account or install an app
They don't render custom HTML (interactive elements, SVG diagrams, embedded scripts)
The whole point of HTML is it's self-contained and rich — a Drive link defeats that
htmldrop is fully open source (MIT). No platform lock-in, no subscription, no data on someone else's server. Your files deploy to your own Surge subdomain. If Surge disappears tomorrow, the tool is a thin wrapper — swap the backend in an afternoon.
The Bigger Picture
This won't fix the communication breakdown I described earlier. But I do think friction contributes to it. When sharing is hard, we default to attachments no one opens. When formats are flat, we skim instead of engage.
The current state of AI-assisted team communication:
People generate MORE content (AI makes it easy)
People read LESS of others' content (too much, too polished, feels complete)
Everyone uses AI to validate their own position rather than genuinely engaging with the other side
The "7 Habits" principle of understanding before being understood is breaking down because AI makes "being understood" so easy that we skip the "understanding" step
If making things easier to share means even one more person actually reads and considers what their teammate wrote — instead of just responding with their own AI-generated counter-document — that's a small win.
But sharing is only half the problem. The other half is discussion — the back-and-forth, the feedback, the "I read this and here's what I think about this specific part." Right now, that happens in Slack threads that get buried, in chat messages nobody can find later, or worse — in competing documents that never actually respond to each other.
I have a longer-term idea for this: facilitating asynchronous, contextual discussion directly on shared artifacts — built for how distributed teams actually work across time zones. A system where the document evolves from the conversation rather than getting replaced by V1, V2, V3 copies.
Still exploring. Stay tuned.
Closing
Seek first to understand. Then be understood. And at minimum, make the thing easy to open.
Thanks for reading. If you've faced the same communication frustrations — AI making it easier to talk past each other, docs getting longer but understanding getting shallower — I'd genuinely love to hear about it. Reach out, leave a comment, share your experience. I'm trying to understand this problem better before building more solutions for it.
Links: