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, then 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
Pasting steps into an agent runs two translations back to back, and the second one drops what the first threw away. Your intent became prose when you wrote the docs; now the agent turns that prose back into actions.
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.
A shipped prompt
Here is the one from the status line post, sitting right beside the manual chmod-and-wire steps:
Copy this prompt to your coding agent
Fetch https://dotfiles.pro/blog/best-claude-code-statusline and take the
complete status line script from the "whole script" block. Save it to
~/.claude/statusline.sh, make it executable, and add the statusLine command
to ~/.claude/settings.json (type "command", padding 0). Then verify it by
piping a sample JSON payload through the script and showing me the rendered
line. Finally, tune the named variables in the script for me: change the
separator from " | " to " · ", and replace the emoji icons (icon_git,
icon_model, icon_usage) with plain Nerd Font glyphs.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
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 holds its emoji icons in ordinary shell variables the agent can overwrite; the Nerd Font variants, and the icon-style switch that picks between the two sets, exist only in the provisioning template. An early draft of that prompt asked the agent to "switch it to the mono icon style". There is no such style in the standalone script, so that is an instruction to confabulate. The shipped version names the variables and says what to put in them. 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 as 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.
Most pages are not how-tos. An essay or a comparison has nothing to install, so 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.
Nor is a web deep link the right surface. "Open in ChatGPT" and "Open in Claude" buttons prefill a chat on the web, while 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.
And a prompt that over-promises is worse than no prompt at all. 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.