Pipeline IA del Technical Writer

What's in this pack

You're a technical writer or dev rel. Your job is API references, getting-started guides, tutorials, code samples in three languages, and a style guide that nobody else reads. AI can finally help — but the marketplace has 700 picks and most of them are general-purpose chat tools dressed up for marketing copy.

This pack is the opinionated nine-tool pipeline built for the technical-writing workflow specifically: audit what you have, draft what you need, generate code samples from API specs, lint for style consistency, render API references that don't look like 2014, and keep the whole thing discoverable to the AI editors your users are pasting your docs into.

Everything here is open-source or has a free tier that's actually usable. Nothing here is a generic "write blog posts with AI" tool. The order matters — each step feeds the next.

Install in this order (audit → first-draft → style → site → publish)

1. Skill Seekers — Convert Docs/Repos/PDFs to Skills (audit) — Start here. Feed it your existing docs, your repo, and any internal PDFs. It produces structured skills that downstream agents can actually load. This is your one-time audit of "what do we already know" before any agent writes a single paragraph.
2. Claude Code Agent: Technical Writer (first draft) — Anthropic-style subagent specifically tuned for API references, user guides, SDK docs, and getting-started flows. Drop it in .claude/agents/, point it at a topic, get a first draft you actually have to edit (not rewrite).
3. Claude Code Agent: Api Documenter (API-specific draft) — Sister agent to #2 but specialised for the OpenAPI/endpoint shape. Feed it a spec or a route handler, get reference prose with the right verbs, status codes, and example payloads.
4. OpenAPI Generator — Client SDKs + Server Stubs from Spec (code samples) — Generate working SDK code in 50+ languages from a single OpenAPI YAML. This is how you stop hand-writing the curl/Python/Node/Go examples on every page. Spec changes? Re-run the generator and your samples are fresh.
5. Scalar — Open-Source API Platform with Beautiful References (reference rendering) — Renders OpenAPI as a modern reference page that doesn't look like 2014 Swagger UI. Self-hostable, embeddable, themeable. This is the page your users actually land on from Google.
6. Vale — Syntax-Aware Prose Linter for Technical Writing (style enforcement) — The killer feature: lints Markdown/RST/AsciiDoc against your style guide without flagging code blocks. Ships with Microsoft, Google, and Write the Docs style packages. CI-friendly. Catches utilize → use and e.g., → for example automatically.
7. Markdownlint — Lint Markdown for AI Content Quality (format enforcement) — Mechanical Markdown checks (heading order, trailing spaces, list consistency, link syntax). Pair with Vale: Vale handles prose style, Markdownlint handles file structure. Both run in pre-commit.
8. Starlight — Documentation Framework for Astro (docs site) — The docs site itself. Astro-native, fast, dark-mode default, sidebar navigation that works on mobile. Plays nicely with the Markdown your agents and linters just produced. Skip the static-site-builder beauty contest — Starlight is the boring correct answer for new sites.
9. Context7 — Up-to-Date Docs MCP for AI Editors (publish) — The publish step nobody talks about. Once your docs are live, you want Cursor/Claude Code/Codex users to pull them as context when their LLM hallucinates your API. Context7 indexes your docs and serves them via MCP. The closing loop: AI helped you write, now AI helps your users use.

How they fit together

Existing docs/repo
   │
Skill Seekers (#1) ─── audit, produce agent-loadable skills
   │
   ├─→ Technical Writer agent (#2) ─── prose first draft
   │       │
   │       └─→ Markdown files
   │
   └─→ Api Documenter agent (#3) ←── OpenAPI spec
           │
           ├─→ OpenAPI Generator (#4) ─── code samples (Python/Go/Node/curl)
           └─→ Scalar (#5) ─── rendered API reference
                   │
Vale (#6) + Markdownlint (#7)
   │
   └─ runs on every commit, blocks merge on style/format failures
         │
Starlight (#8) ─── builds the docs site
   │
   └─ deploy → Context7 (#9) indexes it → AI editors fetch as context

The load-bearing trio is Skill Seekers + Technical Writer agent + Vale: audit, draft, enforce. Without the audit step the agent hallucinates; without the linter the draft drifts off-style every release. The other six are quality-of-life upgrades around that spine.

Tradeoffs you'll hit

• Technical Writer agent (#2) vs Api Documenter (#3) — Overlap is real. Technical Writer does the whole document (intro, tutorial, conceptual sections). Api Documenter is endpoint-focused (the reference rows). Use #2 for the /getting-started page; use #3 for /reference/users/create. If your docs are 80% reference, lean on #3.
• Scalar (#5) vs Swagger UI / Redoc — Swagger UI is the default in every backend framework but visually dated. Redoc is prettier but config-heavy. Scalar is the new entrant with the best out-of-box look and an OSS license that won't bite. If you're already on Swagger UI and shipping, don't migrate for taste alone — wait for a redesign.
• Vale (#6) vs grammar checkers — Vale lints against an explicit style guide (Microsoft, Google, custom). Grammarly/LanguageTool guess. For docs at scale, explicit > implicit — you want CI to fail on "utilize" so the agent learns, not a wavy underline three weeks after publish.
• Starlight (#8) vs the static-site-docs pack — The existing static-site-docs pack covers VitePress, Astro, Mintlify, Docusaurus, Slidev. Starlight is Astro-based but pre-themed for docs specifically. If you're greenfield, start with Starlight; if you have Docusaurus running, don't migrate.
• Context7 (#9) — is this overkill? — Only if your users don't use AI editors. They do.

Common pitfalls (especially AI hallucinating API params)

• Don't let agents invent endpoint parameters — #2 and #3 will happily make up a ?include= query param that doesn't exist. The fix: pass the actual OpenAPI spec as context (via #4 or a direct file paste), and add a rule in the agent's CLAUDE.md saying "if the parameter isn't in the spec, mark it [verify] instead of stating it."
• Vale styles fight each other — Don't enable Microsoft + Google + Write-the-Docs all at once. They disagree on Oxford commas, contractions, and which vs that. Pick one base style, layer one custom pack on top. The PRs from a conflicting setup will demoralise the team in a week.
• OpenAPI Generator template drift — Out-of-box templates produce correct-but-ugly SDKs. For published docs, override the templates once (it's a half-day) and check the overrides into your docs repo. Otherwise every spec change reverts your style.
• Markdownlint default rules block valid Markdown — MD013 line-length and MD041 first-line-heading will scream at perfectly fine files. Run with a project .markdownlint.json from day 1, not the defaults.
• Context7 indexing latency — Allow up to 24h after deploy for new pages to show up. Don't troubleshoot the integration if a brand-new tutorial isn't there yet; check tomorrow.