Skip to content

seb1n/awesome-ai-agent-skills / writing-and-content/technical-writing

technical-writing

Verified

Write clear, concise, and accurate technical documentation including API references, user guides, tutorials, changelogs, and architecture docs, tailored to the target audience. Use when the user requests technical writing or provides relevant inputs for this workflow.

Technical Writing

This skill enables an AI agent to produce high-quality technical documentation across a range of formats — API references, user guides, getting-started tutorials, changelogs, architecture decision records, and more. The agent analyzes the target audience, structures information logically, applies consistent formatting standards, and ensures every document is accurate, scannable, and actionable.

Workflow

  1. Identify Document Type and Audience Determine which type of document is needed (API reference, tutorial, user guide, changelog, architecture doc) and who will read it (beginner developers, experienced engineers, end users, stakeholders). Adjust vocabulary, depth, and assumed prerequisites accordingly. A tutorial for beginners should explain every step; an API reference for senior engineers should be terse and precise.

  2. Gather Source Material Collect all relevant inputs: source code, existing documentation, design documents, user stories, API schemas (OpenAPI/Swagger), commit histories, or stakeholder interviews. Identify the authoritative source for each piece of information to ensure accuracy. Note any gaps that need clarification.

  3. Design the Document Structure Create an outline following the conventions of the document type. API references use a consistent per-endpoint template. Tutorials follow a step-by-step progression. Architecture docs follow a decision-record format (context, decision, consequences). Plan where code examples, tables, and callout boxes will appear.

  4. Write the Content Draft the document using clear, direct language. Prefer active voice and short sentences. Lead each section with the most important information. Include complete, runnable code examples that readers can copy and execute. Use consistent terminology and define acronyms on first use. Format according to the chosen standard (Markdown, reStructuredText, AsciiDoc).

  5. Add Navigation and Cross-References Insert a table of contents for long documents, anchor links between related sections, and links to prerequisite or follow-up documentation. Add "Next steps" sections at the end of tutorials.

  6. Review for Accuracy and Completeness Verify all code examples compile or run correctly. Confirm API endpoint paths, parameters, and response schemas match the actual implementation. Check that every tutorial step produces the described result. No placeholder text or TODO items should remain.

Usage

Provide the agent with:

  • Document type — API reference, tutorial, user guide, changelog, architecture decision record, README
  • Subject — the feature, API, tool, or system to document
  • Audience — skill level and role of the intended readers
  • Source material — code files, schemas, design docs, or a description of the feature
  • Format — Markdown, reStructuredText, AsciiDoc, or HTML

Example prompt: "Write an API reference for the /users endpoint. The audience is third-party developers. Here is the OpenAPI spec: [attached file]."

Examples

Example 1: API Endpoint Reference

Input: "Document the POST /api/v1/webhooks endpoint. Creates a webhook subscription. Requires Bearer token auth. Body: url (string, required), events (string[], required), secret (string, optional). Returns 201 or 422."

Output:

POST /api/v1/webhooks

Creates a new webhook subscription. Requires a Bearer token in the Authorization header.

FieldTypeRequiredDescription
urlstringYesHTTPS endpoint URL to receive payloads.
eventsstring[]YesEvent types to subscribe to (e.g., ["order.created"]).
secretstringNoHMAC-SHA256 signing secret. Auto-generated if omitted.
curl -X POST https://api.example.com/api/v1/webhooks \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://myapp.com/hooks","events":["order.created"]}'

201 Created: {"id":"wh_9a8b7c6d","url":"https://myapp.com/hooks","events":["order.created"],"active":true}

422 Error: {"error":{"code":"validation_error","details":[{"field":"url","message":"URL must use HTTPS."}]}}

Example 2: Getting-Started Tutorial

Input: "Write a getting-started tutorial for our Python SDK (acme-sdk). Install, authenticate, and list projects."

Output:

Getting Started with the Acme Python SDK

Prerequisites

  • Python 3.9+ and an Acme API key (found at Settings > API Keys)

Step 1: Install the SDK

pip install acme-sdk

Step 2: Set Your API Key

export ACME_API_KEY="sk_live_your_key_here"

Step 3: List Your Projects

import os
from acme_sdk import AcmeClient

client = AcmeClient(api_key=os.environ["ACME_API_KEY"])
for project in client.projects.list():
    print(f"{project.id}: {project.name}")

Expected output:

proj_abc123: My First Project
proj_def456: Marketing Site

Next Steps

Best Practices

  • Lead with the action. Start each section with what the reader needs to do, not background context. Put explanations after the instruction.
  • Provide complete, runnable code. Every code example should work as-is when copied. Include imports, variable declarations, and expected output.
  • Use consistent templates. API references should follow the same structure for every endpoint. Tutorials should follow the same step format throughout.
  • Write scannable content. Use headings, tables, bullet points, and code blocks so readers can find information quickly without reading every paragraph.
  • Version your documentation. Tie docs to specific software versions. Clearly indicate which version introduced a feature or deprecated an API.
  • Test your instructions. Walk through every step in a tutorial to confirm it produces the described result.

Edge Cases

  • Undocumented behavior: If source code reveals behavior not described in any spec, document it as "current behavior" and flag it for the engineering team to confirm as intentional.
  • Multiple audiences for one document: Use a layered approach — put essentials first with expandable "Advanced" sections or links to deeper docs.
  • Rapidly changing APIs: Note the version or date prominently and include a disclaimer that the interface may change.
  • Missing source material: Explicitly list what information is missing and request it rather than guessing.
  • Non-English documentation: Follow the technical writing conventions of that language's developer community rather than translating English conventions literally.
rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file).Stars: 198kUpdated Claude CodeCodexUnverifiedInstall
doc-coauthoringanthropics/skillsGuide 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.Stars: 198kUpdated Claude CodeCodexVerifiedInstall