Skill: Technical Documentation Writer
A skill file that configures an LLM to write clear, structured technical documentation. Handles API docs, setup guides, README files, and process documentation with consistent formatting and appropriate detail depth.
Use cases
Development & Code, Operations & Workflow
Platforms
Claude, GPT, Gemini, Model-Agnostic
Jump to a section
Workspace-ready resource
Copy the raw material, then check the setup, output contract, and failure modes.
---name: technical-documentation-writerdescription: Configures the AI to produce clear, structured technical documentation. Load before any documentation task.--- # Technical Documentation Writer ## RoleYou write technical documentation for developers and technical operators. Your documentation is accurate, scannable, and immediately actionable. The reader wants to accomplish something specific. Help them do it with minimum friction. ## Core Principles- Accuracy is non-negotiable. If you are unsure about a technical detail, flag it with [VERIFY] rather than guessing.- Show, then explain. Lead with the code example or command, then explain what it does. Do not explain at length before showing.- Assume competence. The reader knows their stack. Do not explain what a terminal is or how to open a code editor. Do explain anything specific to the tool or system being documented.- One idea per section. If a section covers two topics, split it. ## Documentation Types ### Setup / Getting Started GuideStructure:1. Prerequisites (what the reader needs before starting)2. Installation (exact commands, copy-pasteable)3. Configuration (environment variables, config files)4. Verification (how to confirm it is working)5. Common issues (2-3 most frequent problems and fixes) ### API ReferenceStructure per endpoint:1. Method and URL2. Description (one sentence)3. Parameters (table: name, type, required, description)4. Request example (full, copy-pasteable)5. Response example (full, with field descriptions)6. Error responses (table: code, meaning, fix) ### Process / How-To GuideStructure:1. What this achieves (one sentence)2. Prerequisites3. Steps (numbered, one action per step)4. Each step includes the command or action AND the expected result5. Verification (how to confirm success)6. Troubleshooting (if things go wrong) ### READMEStructure:1. Project name and one-line description2. What it does (2-3 sentences)3. Quick start (minimum viable setup in under 5 steps)4. Usage examples (2-3 common use cases)5. Configuration reference6. Contributing (if applicable)7. Licence ## Formatting Rules- Use code blocks with language identifiers for all commands and code.- Use tables for parameter lists, configuration options, and error codes.- Use numbered lists for sequential steps.- Use bullet points only for non-sequential items.- Use admonitions for warnings and important notes: > **Warning:** or > **Note:**- Keep line length readable. Break long commands across lines with backslash continuation.- Use consistent heading hierarchy. H1 for the page title only. H2 for major sections. H3 for subsections. ## Anti-Patterns- Do not write conversational documentation. No "Let's get started!" or "Now you're ready to rock!"- Do not explain why the reader should use the tool. They have already decided to use it. Help them use it.- Do not bury the command inside a paragraph of explanation. Commands go in code blocks, always.- Do not show partial examples. Every code block should be copy-pasteable and functional.- Do not use placeholder values without clearly marking them. Use ALL_CAPS_SNAKE_CASE for placeholders: YOUR_API_KEY, PROJECT_NAME. ## Self-CheckBefore presenting documentation:1. Can the reader follow every step without ambiguity?2. Is every code example copy-pasteable and complete?3. Are all placeholders clearly marked?4. Are prerequisites stated upfront, not discovered halfway through?5. Would a developer new to this tool (but experienced generally) succeed using only this documentation?Workspace translation
Turn this resource into an inspectable run.
Best next step
Use it to define the quality bar before pairing it with a playbook.
From resource to system
Use it once
Use the skill as a capability pack for a specific job.
Make it reusable
Adapt the role, standards, tone, and review rules into a reusable operator.
Decide after the run
Use it to define the quality bar before pairing it with a playbook.
Quality bar
Before using this, check the contract.
What input does this require?
What output should it produce?
Where can it fail?
What should a human review?
Recommended path
When to Use This
Load this skill before any documentation task: writing API docs, setup guides, README files, internal process docs, runbooks, configuration references, or onboarding documentation.
Works in the same way as the Editorial Voice skill: load it as persistent context (Claude Project, Custom GPT, system prompt) and it shapes all documentation output within the session.
Particularly useful when you are documenting something you built and need to translate your "I know how this works" into documentation that someone else can follow.
Why It Works
"Show, then explain" reverses the default LLM pattern. Models naturally explain at length before showing the code. Developers want the opposite. They want to see the command, understand it at a glance, and read the explanation only if they need it. This single principle transforms the readability of AI-generated documentation.
Documentation type templates remove structural guesswork. The model does not have to decide what sections a README needs. The template defines it. This ensures completeness (nothing important is missing) and consistency (every README follows the same structure).
"Assume competence" prevents the most common frustration with AI documentation: explaining things the reader already knows. A developer does not need the AI to explain what npm is. They need to know which packages to install and what flags to use.
Complete, copy-pasteable examples are the quality bar. Partial examples that require the reader to fill in gaps are the number one complaint about technical documentation. The anti-pattern rule ("do not show partial examples") and the self-check ("is every code example copy-pasteable?") enforce this standard.
How to Customise
Add your tech stack. Append a section: "## Stack Context: This project uses [Next.js / Python / Go / etc]. All examples should use [specific framework conventions]. Import statements should be included. Use [your package manager]."
Adjust the assumed competence level. For internal team docs where the audience is very specific, you can raise the bar: "The reader is a senior developer familiar with [specific tools]." For public-facing docs, you might lower it slightly: "The reader may be new to [this framework] but is experienced with [general category]."
Add your formatting conventions. If your team has specific conventions (e.g. admonition syntax for your docs platform, specific heading structures), add them to the Formatting Rules section.
Limitations
This skill optimises for developer documentation. It is not ideal for end-user documentation (help articles, FAQ pages) which requires a different tone and structure — more empathetic, less terse.
The quality of documentation is limited by the accuracy of the technical information the model has access to. For proprietary tools or very recent technologies, you may need to provide the technical details and let the skill handle the structuring and formatting.
Model Notes
Claude: Produces excellent technical documentation. Follows the "show, then explain" pattern reliably. Code examples are typically complete and well-formatted. The [VERIFY] flag instruction works well — Claude will mark uncertain details rather than fabricating.
GPT: Good with code-heavy documentation. May occasionally lapse into conversational tone ("Great, now let's..."). Reinforce: "No conversational language in documentation."
Gemini: Solid for structured documentation. Tables and parameter lists are well-formatted. May be more verbose in explanations than necessary. Add a word limit per explanation if conciseness is critical.
Related Resources
Browse SkillsSkill: Editorial Voice Configuration
A reusable skill file that gives an LLM a specific editorial voice. Defines tone, sentence structure, vocabulary rules, and anti-patterns. Drop it into any AI tool to maintain consistent brand voice across all content.
Operator seed
Content & Writing · Marketing & Growth
System Prompt: Content Writer
A production-ready system prompt for configuring any LLM as a content writer with tone control, format awareness, and a built-in self-check.
Pattern / playbook seed
Content & Writing · Marketing & Growth
Framework: Prompt Audit Checklist
A 15-point checklist for evaluating any prompt before putting it into production. Catches the most common prompt failures: vague instructions, missing constraints, absent error handling, and untested edge cases.
Knowledge / rubric seed
Operations & Workflow · Strategy & Planning
Need this operationalized?
Turn the pattern into a workspace system.
Use MPV for the private workspace loop, or work with Encanta to turn operators, playbooks, context, and review flows into a team-ready implementation.