A general-purpose AI tool will do something with almost any prompt. The output quality varies, and so does the work to make it usable. A docs-grounded agent (one that knows your pages, your spec, and your style guide) is more sensitive to how you ask. Specific prompts produce drafts you can ship. Vague prompts produce drafts you have to rewrite.
The patterns below are the ones that consistently work with ReadMe's AI agent, but they apply to any agent that's been given real context to work from.
The "rewrite as" pattern
"Rewrite this section as active voice with shorter sentences." Or: "Rewrite this paragraph to use second person and remove marketing language."
This is the highest-value prompt for everyday editing. You're not asking the agent to invent anything. You're asking it to transform existing content along a clear axis. The output is bounded by the input. You can compare diffs side by side and accept or reject quickly.
Pair this with the Linter, which flags the style issues to fix, and the loop is tight: linter surfaces, agent rewrites, you approve.
The "restructure" pattern
"Break this page into three sections with H2 headings: setup, authentication, first request."
Long pages grow organically and rarely get refactored. A restructure prompt that names the sections you want forces the agent to commit to a structure. You can argue with the structure before you commit to the writing.
This works well alongside Docs Audit, which is good at surfacing the pages most in need of a structural refresh.
The "convert to component" pattern
"Convert this list of options into a tabbed component with one tab per language." Or: "Replace these three warnings with callout components."
Most docs platforms support interactive components that improve scannability. The hard part is remembering to use them. An agent that knows your component library can convert prose into the right component when asked. You don't have to remember the syntax.
The "compare against" pattern
"Rewrite this endpoint page to match the structure of the GET /users endpoint page."
A grounded agent can read the reference page and apply its structure to a new page. This is the pattern that scales consistency. You write one page well, then ask the agent to bring the others into line.
The "explain a constraint" pattern
"Add a paragraph explaining that this endpoint requires admin auth, with the same wording style we use on the billing endpoints."
Specific, narrow, and grounded in your existing content. The agent has the billing pages to reference, so the wording style is concrete instead of imagined.
What doesn't work
Prompts that ask the agent to make judgment calls without giving it the criteria:
- "Make this page better."
- "Clean this up."
- "Fix anything that needs fixing."
These produce unpredictable output because the agent has to invent its own criteria. The result is sometimes good, often inconsistent, and rarely worth the time spent reviewing the difference between what you wanted and what you got.
The fix is to give the agent the criteria. "Make this page better" turns into "Rewrite for active voice, break into three sections, and add a callout for the rate limit." Now you can evaluate the output against a target.
Why specificity compounds
The first few times you prompt an agent, this feels like extra work. By the tenth time, you have a small set of phrasings that produce reliable output, and the prompt becomes shorter than the diff. The investment is in learning what the agent is good at, then leaning on it for the parts it does well.
For more on getting started with the AI agent and the rest of our AI tooling, see Use ReadMe's AI Tools to Write Great Documentation.
