offline-html-kit

Teach your AI the facts it doesn't know about locked-down corporate networks.

An agent skill for building single-file HTML tools that run fully offline — no npm, no pip, no CDN, no admin rights. Distilled from tools actually shipped behind a corporate firewall.

Most agent skills teach your AI a task. This one teaches it your environment.

(No badges on this README. Badges are external images served by shields.io — which is blocked on the network where this kit was born. Everything here renders offline, including the README.)

中文说明 →

---

Why this exists

Ask any AI assistant to build you a small tool, and it will assume the open internet: pip install, npm install, a <script src="https://cdn..."> tag. On a locked-down corporate machine, roughly 90% of those suggestions die at step one — the package registry is blocked, the CDN is blocked, and you don't have admin rights to fix any of it.

The AI isn't being careless. It simply has no way to know your network. This skill fixes that: it feeds the agent a set of field-tested facts — which channels tend to survive corporate firewalls, how to bootstrap a JS runtime from a bare tarball, how to make an HTML file that needs nothing at all — so it stops guessing and starts routing around the wall on the first try.

The 48-hour lesson (why "test first" is rule #1)

While writing this very kit, the author's machine gave two opposite answers 48 hours apart:

	Thu (office network)	Sat (same machine)
cdnjs.cloudflare.com	❌ blocked	✅ 200
raw.githubusercontent.com	❌ blocked	✅ 200
registry.npmjs.org	❌ blocked	✅ 200

Same laptop, same user, no proxy change — the firewall policy itself differed. That's why the skill's first instruction is never "assume blocked" or "assume open", but spend 30 seconds probing before choosing a strategy. A hardcoded assumption in either direction would have been wrong within the week.

A concrete case: customer update emails on a machine that can't install Python

The classic moment: every customer needs an order-status email. Python can't be installed, and Outlook COM automation is exactly what IT policy kills first. The kit's route:

1. curl one tarball from a registry mirror, tar it open — and you have the bun JS runtime. No installer, no admin rights. This bootstrap route appears in none of bun's official install docs (their three routes — install script, scoop, npm -g — all die on a locked-down machine).
2. A ~25-line script: read the customer CSV, fill a template per row, write one .eml per customer.
3. An .eml is plain text; with X-Unsent: 1 in the header, double-clicking opens an editable draft in Outlook — review, hit send. No automation APIs touched.

Full real terminal transcript (with fictional sample data): examples/bun-bootstrap.md. This is also why rung 2 of the runtime tree exists: a browser page can't comfortably write 50 files; bun can.

What's inside

SKILL.md                      the agent skill (English, instruction-style, 9 sections, §0–§8)
examples/
  offline-single-file.html    a complete working tool in one file — zero network requests
  bun-bootstrap.md            real terminal transcript: JS runtime from tarball, no installer, no admin
  anti-example-setup.md       a death-by-assumptions case study (what happens without the skill)

Every environmental claim inside SKILL.md is tagged [tested + date] or [inference] — the skill is forbidden from presenting a guess as a fact, and so is the agent reading it.

The nine sections (§0–§8), one line each

§	Rule
0	Default assumption: you are behind a firewall until proven otherwise
1	Reality check first — 30 seconds of curl probes before any plan
2	Runtime decision tree: browser > bun-from-tarball > pre-installed python
3	Getting things through: mirror registries, direct tarball URLs, no package managers
4	Truly offline HTML: inline everything, Tailwind JIT offline, icons as data-URI masks
5	Prove it: the dead-proxy verification trick
6	Windows-specific traps (encoding, paths, PowerShell)
7	Shipping: one zip, one double-clickable file, one honest README
8	Honesty rules: never claim "offline-ready" without a dead-proxy pass

Install

No marketplace, no installer, no network required beyond getting the folder itself — fitting, for this repo. A skill is just a folder with a SKILL.md in it.

Claude Code — copy the folder into your skills directory:

~/.claude/skills/offline-html-kit/

(Clone the repo, or — the firewall-friendly route — download the GitHub zip once from any machine that can reach it, and carry it in.)

Claude.ai (paid plans) — Settings → Capabilities → Skills → upload the folder as a zip.

Any other agent that reads the SKILL.md format (Codex and other agentskills.io-compatible tools) — drop the folder into its skills directory, commonly .agent/skills/ in a project or ~/.config/<agent>/skills/.

Use

1. Ask your agent to build a tool, as you normally would.
2. With the skill loaded, it will probe the network first, pick a runtime that actually works there, and deliver a single HTML file instead of an install-dependent stack.
3. Verify the claim yourself: open the file behind a dead proxy (--proxy-server="http://127.0.0.1:1"). It should still work.

Who this is for

Anyone building tools on a machine they don't fully control: corporate analysts, ops staff, PMs — the growing group of non-engineers shipping real tools with AI assistance, inside networks that were never designed for them.

---

Part of a small series on AI-assisted tool-building in constrained environments: local-ocr-kit · ai-builder-portfolio-kit · offline-html-kit

Questions or suggestions: open an issue.

MIT License.