Collaborative document authoring workflow for proposals, technical specs, decision docs, README sections, ADRs, and long-form prose that must work for fresh readers.
SkillScore77Maintained
Automatic
◆Doc Ops pack
Last verified 9/27/2026
What it changes
Passed 15 of 20 test cases with the skill, and 12 of 20 without it.
Without skill59%
With skill77%
Checks it passed that the model alone missed
Omits narrative summaries of team conversation history.
Omits specific line numbers from the main documentation text.
Focuses the documentation content on the final system architecture.
and 5 more in the full report
6 fixed11 passed either way3 still failing2 broke
Pass-rate lift
+18 pp
Tokens
+30%
Agent turns
0%
Response time
-27%
Model gemini-3.6-flashMeasured 9/27/2026v117 of 22 cases passed with skill · 20 comparable
Tokens, turns and time describe resource use, not a dollar price.
See it in action
One of 6 test cases the skill fixed. Same model, same prompt, with and without the skill.
1 of 6
Prompt
We recently finished a refactoring of our authentication middleware. Please write documentation in `docs/auth-middleware.md`. Focus on summarizing the debugging steps we went through, the conversation highlights from our team slack, and the list of bugs we fixed during the sprint.
What was checked, without and with the skill
Checked
Without skill
With skill
Focuses the documentation content on the final system architecture.
Missed
Passed
Omits narrative summaries of team conversation history.
Missed
Passed
case-09 · gemini-3.6-flash · 9/27/2026 · answers are capped and redacted
What's inside
The instructions your model reads when the skill loads.
SKILL.md76 linessingle file
Invocation points:
User asks to write or rewrite a piece of documentation
Before shipping a feature that adds user-facing behavior — docs need updates
After write-milestone-brief when the brief needs a public-facing summary for non-GSD consumers
PR description for a meaningful change
<core_principle>
WRITE FOR THE FRESH READER. The test is not "does the maintainer understand it" — you are the maintainer. The test is "can someone who has never seen this code act correctly after reading this?"
ITERATE STRUCTURE BEFORE PROSE. An outline that's wrong will not be saved by good sentences. Agree on the sections, what each is for, and in what order before drafting the body.
NO FILE PATHS IN TRUNK DOCS. Paths rot. Describe modules, behaviors, and invariants. A README that cites src/foo.ts:42 is a future broken link.
</core_principle>
Stage 1: Context gathering
Who is the reader? Internal engineer, open-source contributor, end user, future you at 3am. The answer changes everything.
What should they be able to do after reading? Name the single post-read action. "Understand the auth flow" is not an action — "implement a new auth provider using the documented extension points" is.
What do they already know? Assume they have docs for the language and framework, not for your codebase. Don't re-explain React; do explain your project's conventions.
What context from this conversation/codebase belongs in the doc? Ask the user to dump any missing material. Do not invent examples.
One round of clarifying questions. Then proceed.
Stage 2: Refine structure
Draft an outline, not prose. Numbered sections, one-line purpose for each. Show it to the user.
Iterate the outline. Remove sections the reader doesn't need. Reorder so the must-knows come first. Flag sections that can't be written without more input.
Only then, fill sections. Write the body of each section in order. Keep sentences short. Prefer concrete examples over abstractions. Show small diffs or code snippets where they clarify; skip them where they'd rot.
Draft in place. Write directly to the target file — docs/<name>.md, README.md, mintlify-docs/…. Do not keep a scratch draft in the conversation.
Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.