page-serve, give a human a URL
An agent that renders a page for a human needs a way to hand it over. The pattern
that grew in sessions was python3 -m http.server 8991 plus portless alias <name> 8991
typed by hand: no record of the process, no stop, servers outliving the session,
and one measured night (2026-09-06) where the same session did it twice and the
server was still up the next morning. This skill is that pattern with a state file,
a stop, a status, and a loud failure when the URL contract cannot be met.
The contract
- The URL is
https://<name>.localhost/<file>. No port, ever. portless's 443 service
owns the port; a :1355 or :8991 in the URL is the pre-service fallback and the
skill refuses rather than emit one.
- One static server per name, on a free loopback port, rooted at the file's
directory (so sibling assets resolve) or at the directory you pass.
- State in
.claude/state/page-serve/<name>.json: root, file, port, pid, url, time.
status re-measures pid, route, and HTTP on every call; it never trusts the file.
- Idempotent per name: same name + same root reuses the live server; a different root
replaces it;
--force on the alias overrides a stale route with the same name.
Usage
The skill is three scripts in its own folder. Run them by path:
bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" ./report.html
bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" ./pages/ --name pages
bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" <path> --screenshot # agent-browser, returns the png path
bash "${CLAUDE_SKILL_DIR}/scripts/status.sh" [--json]
bash "${CLAUDE_SKILL_DIR}/scripts/stop.sh" <name>
bash "${CLAUDE_SKILL_DIR}/scripts/stop.sh" --all
serve.sh prints url=, name=, port=, pid=, http=, optional screenshot=,
and the exact stop= line to paste. Put the url= line in your reply's Open section.
Modes
| Invocation |
Script |
What happens |
<path> [flags] |
scripts/serve.sh |
prerequisites, server, alias, state, curl check, optional screenshot |
status [--json] |
scripts/status.sh |
one line per served page: server up/dead, route registered/missing, HTTP code |
stop <name> or stop --all |
scripts/stop.sh |
alias removed, server killed, state and screenshot deleted; every step reports |
Failure modes, all loud
| Condition |
Exit |
What it says |
| portless not installed |
2 |
install line, then portless service install |
| 443 service not responding |
2 |
portless service status, the operator's launchctl kickstart line, and "do not fall back to a :port URL" |
| server did not bind |
3 |
port and log path |
| alias registration failed |
2 |
portless's own message, server cleaned up |
| route up but URL not 200 |
4 |
code, curl rc, and portless list; server left running for inspection |
| screenshot failed |
0 |
reported on stderr, page still served, screenshot= line omitted |
A page that "served" but does not answer 200 through the proxy is exit 4, not 0, so a
caller that only reads the exit code cannot report a dead link as done.
Screenshot
With agent-browser installed the default is to take one (--no-screenshot to skip;
--screenshot to insist and get a stderr line if it is missing). The png lands
beside the state file. The screenshot is evidence the page rendered, not proof it
rendered correctly: read the image before claiming the page looks right
(the glyph skill's rule 1).
What this is not
- Not a dev server. For a framework app with hot reload use
dev, which wraps
the app's own dev command in portless. This skill serves static files.
- Not a publisher. Nothing leaves the machine;
.localhost resolves locally only.
- Not a docs-site deploy. Lab pages under
docs/site/public/lab/ still ship through
the docs-site build; this skill is for the hand-over before or beside that.
Retiring the old pattern (#3900)
Any skill or page that tells an agent to run python3 -m http.server or to type
portless alias by hand should use this skill instead. The skills that hand a
human a page (glyph, visualize-plan, expect) are the ones to keep pointed here.
Related skills
dev, the dev-loop sibling for framework apps (portless wrapping a dev command)
portless (the reference skill, model-invoked): service install, LAN mode, gotchas
glyph, visualize-plan, and the separate playground plugin, the producers of pages this serves
expect, browser verification against the URL this prints
1---2name: page-serve3compatibility: "Claude Code 2.1.277+"4description: "Serves a static HTML page at a stable https://NAME.localhost/ URL via portless, never a port, and stops it on request. Use when an agent made a page a person should open. Not for app dev servers (use dev)."5license: MIT6argument-hint: "[path] [--name slug] [--screenshot|--no-screenshot] | stop [name|--all] | status [--json]"7user-invocable: true8disable-model-invocation: false9context: inherit10metadata:11 source: https://skillmd.com/skills/yonatangross/page-serve12 category: devops13 milestone: M16614 upstream-packages: ["portless", "agent-browser"]15 version: "1.0.0"16 author: "OrchestKit"17 complexity: "low"18 tags: "page-serve, portless, agent-browser, playground, glyph, dev-loop, m166"19---2021# page-serve, give a human a URL2223An agent that renders a page for a human needs a way to hand it over. The pattern24that grew in sessions was `python3 -m http.server 8991` plus `portless alias <name> 8991`25typed by hand: no record of the process, no stop, servers outliving the session,26and one measured night (2026-09-06) where the same session did it twice and the27server was still up the next morning. This skill is that pattern with a state file,28a stop, a status, and a loud failure when the URL contract cannot be met.2930## The contract3132- The URL is `https://<name>.localhost/<file>`. No port, ever. portless's 443 service33 owns the port; a `:1355` or `:8991` in the URL is the pre-service fallback and the34 skill refuses rather than emit one.35- One static server per name, on a free loopback port, rooted at the file's36 directory (so sibling assets resolve) or at the directory you pass.37- State in `.claude/state/page-serve/<name>.json`: root, file, port, pid, url, time.38 `status` re-measures pid, route, and HTTP on every call; it never trusts the file.39- Idempotent per name: same name + same root reuses the live server; a different root40 replaces it; `--force` on the alias overrides a stale route with the same name.4142## Usage4344The skill is three scripts in its own folder. Run them by path:4546```bash47bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" ./report.html48bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" ./pages/ --name pages49bash "${CLAUDE_SKILL_DIR}/scripts/serve.sh" <path> --screenshot # agent-browser, returns the png path50bash "${CLAUDE_SKILL_DIR}/scripts/status.sh" [--json]51bash "${CLAUDE_SKILL_DIR}/scripts/stop.sh" <name>52bash "${CLAUDE_SKILL_DIR}/scripts/stop.sh" --all53```5455`serve.sh` prints `url=`, `name=`, `port=`, `pid=`, `http=`, optional `screenshot=`,56and the exact `stop=` line to paste. Put the `url=` line in your reply's Open section.5758## Modes5960| Invocation | Script | What happens |61|---|---|---|62| `<path> [flags]` | `scripts/serve.sh` | prerequisites, server, alias, state, curl check, optional screenshot |63| `status [--json]` | `scripts/status.sh` | one line per served page: server up/dead, route registered/missing, HTTP code |64| `stop <name>` or `stop --all` | `scripts/stop.sh` | alias removed, server killed, state and screenshot deleted; every step reports |6566## Failure modes, all loud6768| Condition | Exit | What it says |69|---|---|---|70| portless not installed | 2 | install line, then `portless service install` |71| 443 service not responding | 2 | `portless service status`, the operator's `launchctl kickstart` line, and "do not fall back to a :port URL" |72| server did not bind | 3 | port and log path |73| alias registration failed | 2 | portless's own message, server cleaned up |74| route up but URL not 200 | 4 | code, curl rc, and `portless list`; server left running for inspection |75| screenshot failed | 0 | reported on stderr, page still served, `screenshot=` line omitted |7677A page that "served" but does not answer 200 through the proxy is exit 4, not 0, so a78caller that only reads the exit code cannot report a dead link as done.7980## Screenshot8182With agent-browser installed the default is to take one (`--no-screenshot` to skip;83`--screenshot` to insist and get a stderr line if it is missing). The png lands84beside the state file. The screenshot is evidence the page rendered, not proof it85rendered correctly: read the image before claiming the page looks right86(the glyph skill's rule 1).8788## What this is not8990- Not a dev server. For a framework app with hot reload use `dev`, which wraps91 the app's own dev command in portless. This skill serves static files.92- Not a publisher. Nothing leaves the machine; `.localhost` resolves locally only.93- Not a docs-site deploy. Lab pages under `docs/site/public/lab/` still ship through94 the docs-site build; this skill is for the hand-over before or beside that.9596## Retiring the old pattern (#3900)9798Any skill or page that tells an agent to run `python3 -m http.server` or to type99`portless alias` by hand should use this skill instead. The skills that hand a100human a page (glyph, visualize-plan, expect) are the ones to keep pointed here.101102## Related skills103104- `dev`, the dev-loop sibling for framework apps (portless wrapping a dev command)105- `portless` (the reference skill, model-invoked): service install, LAN mode, gotchas106- `glyph`, `visualize-plan`, and the separate `playground` plugin, the producers of pages this serves107- `expect`, browser verification against the URL this prints