technical-writing

Este extracto es una copia guardada durante la revisión. La fuente externa contiene la versión completa y actual.

---
name: technical-writing
description: 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.
license: MIT
metadata:
  author: awesome-ai-agent-skills
  version: 1.0.0
---

# 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.
>
> | Field | Type | Required | Description |
> |-------|------|----------|-------------|
> | `url` | string | Yes | HTTPS endpoint URL to