Ship the prompt: put a paste-ready agent prompt in your docs

You are reading a project's install page with a coding agent open in the next pane. The page has eight steps: clone this, create that file, add a line to .chezmoiignore, set an env var, wire the rest. You don't run them by hand. You select the whole section, paste it into the agent, and say do this.

It mostly works. The agent reverse-engineers prose back into actions — and guesses at everything the prose left implicit, because docs written for a human never spell out the parts a human infers. The fix is small, and it belongs to whoever wrote the docs: ship the prompt. Next to the manual steps, add one paste-ready block that hands the whole job to the reader's agent, written by the person who knows exactly what the thing supports.

The prose round trip is lossy

Pasting steps into an agent runs two translations back to back. Your intent became prose when you wrote the docs; now the agent turns that prose back into actions. The second hop drops information the first one threw away.

Prose omits what a reader supplies for free: that the env var goes in settings.json and not the shell, that the path is relative to the repo root, that step three is idempotent and safe to re-run, that "the collection" means the one pinned in requirements.yml two steps up. A person fills those gaps from context without noticing. An agent guesses, and a wrong guess in a setup script is a support ticket with your name on it.

You already know every answer — you wrote the thing. A shipped prompt is you spending that knowledge once, in the page, instead of every reader's agent re-deriving it a little worse.

What a shipped prompt looks like

Here is one from the status line post, sitting right beside the manual chmod-and-wire steps:

Copy this prompt to your coding agent

Fetch the status line script from https://dotfiles.pro/blog/best-claude-code-statusline
(the "whole script" block). Save it to ~/.claude/statusline.sh, make it
executable, and point ~/.claude/settings.json at it. Verify by piping a sample
JSON payload through the script and showing me the rendered line. Then tune the
variables at the top for me: short path, and drop the 7-day usage window — I'm
on Pro.

It reads like the manual steps because it encodes the same steps. What it adds is everything the prose left implicit: the exact file to fetch, the exact target paths, a verification beat, and one sentence at the end the reader rewrites for their own setup. It is addressed to the agent, and it says the quiet parts out loud.

Three rules that keep it honest

The pattern is easy to get wrong in ways that are worse than plain steps. Three rules, each one I learned by breaking it.

• Only ask for what the artifact supports. The standalone status line bakes emoji icons into named variables at the top; the Nerd Font variants live only in the provisioning template. An early draft of that prompt asked the agent to "use the mono icons" — against the standalone script, that is an instruction to confabulate. A prompt you haven't run against the real artifact is a guess in a confident voice.
• Keep a human in the loop. End with a confirmation beat: show me the plan before you write anything, show me install.sh before creating the rest. A setup prompt edits the reader's machine or repo; one line turns a blind run into a review.
• Leave the last line to the reader. Sections, icons, which clients, which paths — the closing sentence is theirs to edit. That is what makes it a prompt and not a script: it is parameterized by a sentence, not a flag.

The prompt is also documentation

A good prompt does a second job for free. Written out in plain language, it records the artifact's tunable surface — the knobs, in the order you'd reach for them. A reader who never pastes it still learns something by reading it: oh, I can change the separator, drop a section, swap the icons.

Steps tell you how to install the thing. The prompt tells you what's negotiable about it. That is documentation a features table rarely delivers as clearly.

Where it doesn't belong

Like any pattern, it turns into noise the moment it's applied everywhere.

• Not every page is a how-to. An essay or a comparison has nothing to install; bolting a prompt onto it is cargo-culting. The trigger is narrow: does this page walk a reader through changing their machine? If not, no prompt.
• A web deep link is the wrong surface. "Open in ChatGPT" and "Open in Claude" buttons prefill a chat on the web. Your reader is in a terminal with a coding agent that can actually touch their files. Copy-to-clipboard is the real affordance; a deep link opens the wrong app.
• An over-promising prompt is worse than none. Ask for something the artifact can't do and a capable agent will produce a plausible-looking result anyway, and the reader ships it. The honesty rule above is not politeness — it's the difference between a prompt and a trap.

How I ship it here

The prompts on this blog render through a small VitePress container, ::: prompt. It wraps an ordinary fenced code block rather than replacing it, so it keeps the built-in copy button, and because it only decorates the fence it degrades to plain markdown everywhere the styled HTML doesn't reach: the RSS feed, and the llms-full.txt an agent is as likely to read as the page itself. It's about fifteen lines of config and a little CSS — the pattern is the point, not the plugin. You can see it in place on the chezmoi, devcontainers, and multiple-Slack posts, each one a genuine setup walk-through with a prompt beside the steps.

Install docs used to end at the last step. Now the last step is a paste — so write that paste yourself, in the one place that knows what the thing can do. The alternative is every reader's agent reconstructing it from your prose, once each, a little wrong.