Authoring Developer Guide

authoring-developer-guide — SKILL.md

Variant: standard · When to use: authoring (or amending) the developer-tool adoption + integration narrative — to a bar where a developer can install the tool, grasp its model, complete the common integration scenarios, self-serve the common errors, and operate it in production from the guide alone, with runnable code, every step matching what the tool actually does.

Overview

This skill is the how-to of writing a strong developer guide — the consumer-facing adoption and integration narrative for a developer-tool product (an SDK, library, CLI, framework, or API platform). It is the prose a developer reads to go from zero to a working integration and on to a correct production integration: reach a first successful call fast, find their way (a signposted start-here), understand the tool's mental model, follow code-centric recipes, build a small real thing end to end, apply production best-practices, and self-serve the common errors — with pointers out to the exhaustive reference. It spans the full Diataxis quadrant (tutorial / how-to / explanation / reference) for a technical reader. This skill carries the producer's judgment — the research method and the quality bar — not the section list. It assumes two collaborators: a developer-guide template tool that supplies the section structure, and a deep-research capability to ground the guide in established developer-experience (DX) docs practice, Diataxis, and the developer-docs quality rubric (Findability / Accuracy / Relevance / Clarity / Completeness / Readability). The producer is handed the upstream documents the plan determined inform this guide — never a blank page. The bar to clear: a developer can install, grasp the model, complete the common integration scenarios, and recover from the common errors from the guide alone, with runnable code, every step matching what the tool actually does.

This skill also amends an existing guide (the common real operation — see Step 6): a developer guide is the most change-driven of docs because its subject (the tool) moves.

When to activate

• Authoring the adoption + integration narrative for a developer-tool product (SDK, library, CLI, framework, or API platform).
• Writing the getting-started, core-concepts, integration recipes, end-to-end tutorial, best-practices, and troubleshooting a developer needs.
• Amending an existing developer guide when the tool changes (a new version, a deprecated/renamed/changed capability) or a recipe/concept needs correcting — see Step 6.
• Filling a developer-guide template with researched, runnable, accurate content driven off the handed-in feature-spec and api-reference.

Do NOT activate when:

• Writing the exhaustive per-endpoint / per-symbol api-reference catalog → a separate document. This guide narrates and links into the reference; it never re-lists it.
• Writing the non-technical end-user user-guide (product task help, no code, a different audience) → the producer picks by the upstream PRD's audience.
• Writing the internal engineering docs — the api-spec (the wire contract), the architecture-doc (system design), or the data-model (persistence schema).
• Reviewing or grading a finished developer guide → use reviewing-developer-guide; this skill is produce-side only.

Inputs

Read every document the plan hands you — your depends_on set — and trace each how-to and concept back to them. The typical upstreams are guidance, not a fixed cap.

• Typical upstreams. The feature-spec (the capabilities the guide teaches), the api-reference (the endpoints the integration recipes drive — when the tool exposes an API), and the PRD (the audience + the value); where present, the user-flows (integration scenarios) and the architecture-doc (auth/deployment context). Drive the recipes off the handed-in api-reference — real endpoints, real capabilities. On an amend, you are also handed the existing guide + the change request + the changed upstreams (Step 6).
• Self-contained + graceful. Produce from whatever context you receive. When an expected upstream is absent (e.g. a non-API library/CLI has no api-reference), proceed on what you have and surface the gap as an explicit assumption; never fabricate a capability, endpoint, or code path.
• Research for comprehensiveness. Use deep-research to ground the guide in established DX-docs / Diataxis practice, not merely to fill the template.

Workflow

Step 1: Take the structure from the template tool — don't invent an outline

Get the section structure from your developer-guide template tool (comprehensive variant). Do not restate or re-derive a section list here; this skill supplies the method that fills those sections well. If no template is available, obtain a comprehensive developer-guide structure (request/forge one, or fall back to the canonical set: overview/orientation + a signposted start-here, getting-started, core concepts, integration how-to guides, end-to-end tutorial, best-practices, troubleshooting/common-errors, api-reference pointers, tool versioning/migration, a document changelog, open questions), then proceed.

Step 2: Load the upstreams; drive coverage off the feature-spec + api-reference

Read the handed-in documents — your input, not a blank page. The feature-spec's capabilities are your concept- and recipe-coverage checklist; the api-reference's endpoints are what the recipes call. Every recipe and code sample traces to a real upstream capability/endpoint — no invented APIs. Where an upstream is thin or absent, make the gap an explicit assumption, never a silently-invented endpoint. Identify the tool archetype (API platform / per-language SDK / CLI / framework — a tool can be several) — it sets the emphasis throughout (Step 4).

Step 3: Research to ground the guide

Use a deep-research pass to ground the guide in established DX-docs practice (the Stripe/Twilio/Auth0 bar — a first call fast, runnable code, goal-organized, concepts before reference; time-to-first-call as the intent — minimize the steps to the first verified success), full Diataxis (the four modes, correctly typed + separated), and the developer-docs quality rubric (Findability/Accuracy/Relevance/Clarity/Completeness/Readability) — for this product. If no research capability is available, do NOT fabricate install commands, endpoints, parameters, or error shapes — flag them as assumptions to validate.

Step 4: Apply the per-section method

Fill the template's sections to this method. Collapse a section a thin tool doesn't need; size proportionally to the product and its archetype. (Depth — the rubric, IA, getting-started, concepts: references/structure-onboarding.md; best-practices, troubleshooting, archetypes, the amend procedure: references/bestpractices-archetype-amend.md.)

• Organize around developer GOALS, not endpoints. Frame the whole guide + name how-to recipes by what the developer wants to accomplish ("accept a payment"), never by the API symbol. Lead with what you can build.
• Information architecture — a signposted start-here + a reader-journey order. Make the entry point unmistakable (orient → first success → concepts → recipes → tutorial → best-practices → troubleshooting → reference); position auth + getting-started prominently; keep cross-links predictable; scannable headings + a focused ToC; reveal complexity gradually (common path first, edge options linked). Light accessibility for the prose: meaningful link text (never "click here"), alt text on any diagram, acronyms defined on first use, real heading hierarchy. (Findability is the rubric's first dimension; "no clear start-here" is a top abandonment driver.)
• Overview / orientation — what the tool does + the problem it solves (two lines), the assumed reader + prerequisites, the 2–4 headline scenarios (each linking to its recipe), the start-here path, and plainly that the exhaustive reference lives elsewhere (this guide links into it).
• Getting-started = a fast, verifiable first success. The smallest complete program that makes one real, successful call: prerequisites → install → configure credentials → first call → verify. Say where the credential comes from (the signup-to-key / dashboard path) and steer the first call through test/sandbox mode (not live). Code is runnable + copy-pasteable; credentials come from an env var / config, never hardcoded; the call shows real value, not hello-world. Minimize the steps to the first verified success (the TTFC intent). Close with the literal expected output + the 2–3 most common first-call failures (deeper ones go to troubleshooting). (Diataxis tutorial.)
• Core concepts BEFORE reference and recipes. Explain the mental model — the client/resource object, the domain nouns + relations, the request lifecycle (sync/async, webhooks, idempotency conceptually), environments (test vs live) — so parameters + recipes have meaning. (Diataxis explanation.)
• Integration how-to guides = goal-named, code-centric, independently-followable recipes for an already-oriented reader (Diataxis how-to). One subsection per common scenario, each with the goal, extra prerequisites, focused runnable code (relevant lines only), the success result, and a link into the reference for the full option set — do not inline the catalog. Size to the tool's real surface.
• End-to-end tutorial = build one small real thing, start to finish (Diataxis tutorial). Keep it separate from the section-4 lookup recipes — fusing how-to and tutorial is the most common cause of confusing docs. Close with the result + where to go next.
• Best-practices grounded in real production usage (Diataxis explanation, not an option dump): auth/secrets (env or secret manager, least-privilege scopes, test vs live keys); error handling typed retryable-vs-fatal; retries + idempotency (backoff with jitter, honor retry-after, idempotency key on writes); pagination (auto-iterator or cursor loop; the dropped-cursor pitfall); rate limits (429, Retry-After); webhooks where the tool emits them (signature verification, replay/dedup, ordering); resource hygiene (reuse one client, pooling, timeouts) — recommended pattern + a short snippet each.
• Troubleshooting / common-errors = a self-serve path for the frequent, knowable failures (beyond the getting-started first-call failures): group the frequent errors (auth 401/403, validation 400, rate-limit 429, not-found 404, version mismatch) as symptom → cause → fix; an error-code→meaning→fix table where the tool has codes; a short FAQ for recurring conceptual confusions (test vs live, async timing, idempotency). Proportional — a thin tool folds this into getting-started. ("No help when stuck" is a top abandonment driver.)
• Code samples accurate to the CURRENT tool. Every sample reflects a real capability/endpoint from the handed-in upstreams; write samples so they can be tested (self-contained, single-sourced from working code where possible) and state the tool version the guide targets so staleness is visible — the version stamp is for the amend staleness-sweep's benefit (Step 6), not a currency check the gate runs greenfield. (The CI-ing of samples is the project's pipeline, not the guide's content — but write them to be testable.)
• API-reference pointers — link OUT, never reproduce. State that the exhaustive catalog is the source of truth and lives in the separate api-reference; optionally map this guide's concepts/recipes to reference sections; list supporting resources (sample repo, support, status).
• Tool versioning + migration — the scheme (SemVer / date-based) + what major/minor/patch means + how to pin; the deprecation policy + timelines; link the changelog; per-major-jump migration notes with before/after for each breaking change + the migrate step order.
• Archetype-aware emphasis (proportional). API platform → curl + a language, auth flows, webhooks; per-language SDK → a first-success + recipes per supported language, client lifecycle, idiomatic patterns; CLI → args/flags, exit codes, the stdout/stderr contract, non-interactive/scripting use, shell completion; framework → scaffolding, conventions, lifecycle hooks. The bar adapts; it does not bloat every guide.

Step 5: Self-check against the adoptability + accuracy bar before handing off

Confirm all hold (this is the bar reviewing-developer-guide asserts — author and gate share it 1:1 so they don't drift). Each is proportional: a thin tool legitimately collapses what it doesn't need.

1. Goal-organized — framed around what the developer can build; recipes named by goal, not endpoint.
2. Getting-started reaches a verifiable first success — prerequisites (incl. where the credential comes from + test/sandbox path) → install → configure credentials → one real successful call → a verify step with expected output; runnable, copy-pasteable, real value (not hello-world), env-var (not hardcoded) credentials; the path is short + unblocked (TTFC intent).
3. Core concepts present and BEFORE the reference/recipes.
4. Integration how-tos cover the common scenarios in the handed-in upstreams — goal-named, code-centric, independently-followable, runnable, linking into the reference.
5. An end-to-end tutorial builds one small real thing, kept separate from the lookup recipes.
6. Best-practices grounded in real usage — auth/secrets, retryable-vs-fatal errors, retries+idempotency+backoff, pagination, rate limits, webhooks (where applicable), resource hygiene — recommended pattern + snippet, not an option dump.
7. Diataxis modes correctly typed + separated — no mode bleeds into another.
8. Links into — never duplicates — the api-reference.
9. Code samples runnable + accurate to the actual/CURRENT tool — every sample reflects real capabilities/endpoints from the handed-in upstreams; nothing contradicting the upstream contract; the targeted tool version stated.
10. Tool versioning + migration stated — scheme, deprecation policy/timelines, changelog link, per-major-jump before/after notes.
11. Grounded, not fabricated — capabilities/endpoints/code reflect the upstreams; gaps surfaced as explicit assumptions, not invented.
12. Amend (on iteration) is a clean delta — edited in place, the tool's change swept for stale samples, internal coherence held, the guide's own version bumped + changelog updated, superseded content marked (Step 6). (n/a on a greenfield first build.)
13. Troubleshooting / common-errors path present — the frequent knowable errors are self-servable (symptom→cause→fix); proportional (folded into getting-started for a thin tool).
14. Findable — a first-time reader can locate the start-here + their goal's section without already knowing the API (signposted entry + reader-journey order).

Thin-input gate: if a scenario the guide must teach cannot be researched or even credibly assumed into a runnable recipe, surface it as a blocker ("integration scenario under-defined — needs the api-reference / a product decision") rather than inventing an endpoint or code path.

Step 6: Amend an existing guide (iteration / delta)

A developer guide is the most amend-driven doc — its subject (the tool) moves: a new version, a deprecated/renamed endpoint, a changed signature, a new auth flow. The amend is upstream-driven + internal, with no derived-doc downstream (the guide is a leaf — the only consumer is the developer's own integration). On an amend (handed the existing guide + change request + the changed upstreams):

1. Scope the change. State what this delta touches (which recipes/samples/concepts/steps, for which tool version) and what is deliberately untouched.
2. Edit in place — change only the affected blocks; do NOT regenerate the whole guide (that loses provenance + risks breaking untouched, still-accurate samples).
3. Run the upstream-driven staleness sweep — find every guide location that referenced the changed/removed capability (samples, recipes, concepts, the getting-started call, the api-reference pointers) and re-make each accurate to the current tool. A sample left calling a removed/renamed capability is the highest-impact amend defect (a fabrication-by-staleness).
4. Re-make internal coherence — concepts-before-recipes still holds; the end-to-end tutorial still runs; no recipe contradicts the (possibly changed) concept section; the first-success still verifies.
5. Version + changelog the guide document — bump the guide's OWN version (distinct from the tool's version and the skill's semver); add a changelog row (who / when / what changed / why, e.g. "updated for SDK v3 — Client(key=) → Client.from_env()").
6. Mark superseded/deprecated content — with the version + the replacement, not a silent delete, so a developer still on the old version sees the path.

Rules

Hard rules (never violate):

• Narrate + link the api-reference; never re-derive the catalog. Point into it for full options — do not re-list parameters/types/errors inside the guide.
• Getting-started reaches a verifiable first success. A fast, runnable, copy-pasteable path to one real successful call, ending in a verify step; credentials from an env var / config, never hardcoded; say where the credential comes from + steer through test/sandbox.
• Concepts before reference. Explain the mental model before recipes or the reference.
• Goal-organized, not endpoint-organized, with a signposted start-here.
• Type the Diataxis modes correctly and keep them separated. No reference dumped into the tutorial, no concepts buried in a recipe, no how-to/tutorial fusion.
• Code samples runnable + accurate to the current tool. Never a sample for a capability the upstreams don't show; state the targeted tool version.
• Troubleshooting is a self-serve path, proportional — the frequent knowable errors map to a fix; never demand a named "Troubleshooting" section on a thin tool (fold it into getting-started).
• Amend in place + sweep for staleness. On a tool change, find and fix every stale sample/recipe/pointer; version + changelog the guide; mark superseded content. Never regenerate the whole guide.
• Never fabricate. Don't invent endpoints, capabilities, install commands, or code paths. With no source, state them as explicitly-flagged assumptions.
• Consume the handed-in upstreams; never a blank page, never one hardcoded input. When an expected upstream is absent (e.g. no api-reference for a non-API tool), build from what you have and surface the gap as an assumption.
• Compose, don't duplicate. Take the section structure from the template tool; this skill is the method that fills it.
• Narrative, not catalog, not end-user help, not engineering docs.

Preferences (override-able):

• "Comprehensive" sets output ambition; stay proportional to the tool + its archetype — a thin CLI collapses recipes, lightens concepts, folds troubleshooting into getting-started; a broad API platform expands recipes, webhooks, troubleshooting, + migration notes. The bar is first-success + a correct production integration, not word count.
• Prefer multi-language samples where the tool ships multiple SDKs (a first-success per language); for an API, prefer curl + at least one language.
• Prefer cursor-based pagination + backoff-with-jitter retries as the recommended patterns, deferring exhaustive options to the reference.

Gotchas

• Re-listing the api-reference inside the guide. Narrate the scenario, show the focused recipe, link out for the full option set.
• Hello-world getting-started. The first success must reach real value + a verifiable check, or the reader gains no confidence.
• Hardcoded credentials in samples. Teaches a security anti-pattern + won't run for the reader. Read from env / config every time.
• No clear start-here. A guide that drops the reader into endpoints with no orientation is abandoned; signpost the entry + order the journey.
• How-to and tutorial blurred together. The most common Diataxis failure — keep section-4 recipes as lookups, the tutorial as one guided build.
• Reference material leaking into the tutorial. Mention only what the step needs; link the rest.
• Stale samples after the tool moved. The dominant maintenance failure — on any tool change, sweep every sample/recipe for a removed/renamed capability (Step 6); a stale sample reads fine and breaks on run.
• A troubleshooting section that lists generic debugging advice. Make it the tool's frequent, knowable errors mapped to concrete fixes, not "check your logs".
• Fabricated endpoints/capabilities when an upstream is thin. Surface the gap as an assumption instead.
• Restating the template outline. Fill its sections with judgment instead.

Worked contrast — generic (looks plausible) vs adoptable (use it to self-detect):

If your fill reads like the left column — true of any tool, no runnable first success, no real concepts, the catalog pasted in, no start-here, stale on the tool's current version — it isn't done.

Anti-patterns

• "I'll list every endpoint so the guide is complete." That is the api-reference's job — narrate + link out.
• "Hello-world is a fine first call." Reach real value + verify it.
• "I'll hardcode the key to keep the sample short." Read it from the environment.
• "Recipes and the tutorial are the same thing." Different Diataxis modes — keep them separate.
• "This is also the user-guide, so I'll write for non-technical users." Different audience + document.
• "The api-reference is thin, I'll invent the endpoints." Surface the gap as an assumption.
• "The tool shipped v3, I'll just regenerate the guide." Amend in place + sweep for stale samples; version + changelog; mark superseded.
• "Skip the research, I know how SDKs work." The research grounds this product's surface, scenarios, + conventions.
• "I'll write the outline myself." Duplicates the template tool — take the structure from it.

Output

A comprehensive developer guide that meets the Step 5 adoptability + accuracy bar (goal-organized + signposted start-here; getting-started reaches a verifiable first success; concepts before reference; integration how-tos cover the handed-in scenarios; an end-to-end tutorial builds a small real thing; best-practices grounded; a proportional troubleshooting path; Diataxis modes correctly typed + separated; links into — not duplicates — the api-reference; samples runnable + accurate to the current tool; tool versioning/migration stated; the guide's own version + changelog maintained on amend; nothing fabricated). The artifact is textual — numbered setup steps + fenced install commands + fenced integration code samples (curl + ≥1 language where an API is involved), screens/flows described in words; the method + bar are medium-independent. The abstract consumer is the developer adopting + integrating the tool, and reviewing-developer-guide (which asserts the same 14-condition bar). The guide consumes the handed-in upstreams (typically feature-spec + api-reference + PRD) and links into the api-reference downstream. Its structure comes from the template tool; this skill supplies the content quality.

Related

• A developer-guide template tool (e.g. content-template-gateway) — supplies the section structure this skill fills. Compose with it; never restate its outline.
• A deep-research capability — grounds the guide in DX-docs practice (Stripe/Twilio/Auth0), Diataxis, and the developer-docs quality rubric.
• reviewing-developer-guide — the runtime gate; asserts the same 14-condition adoptability + accuracy bar on the finished guide; author + gate share one bar so they don't drift.
• An api-reference-authoring skill — produces the exhaustive endpoint/symbol catalog this guide narrates + links into, never re-derives.
• A user-guide-authoring skill — the non-technical end-user product help; a distinct audience + document this skill is not (the producer picks by the PRD's audience).
• A feature-spec (capabilities taught), an api-reference (endpoints the recipes drive), a PRD (audience + value) — the typical upstream inputs; where present, user-flows + architecture-doc.

Progressive disclosure

• references/structure-onboarding.md — depth for the structure + onboarding angles: the developer-docs quality rubric + Diataxis modes; information architecture / start-here / reader-journey + scannability/progressive-disclosure + light accessibility; the getting-started 6-step + TTFC + credential-acquisition/sandbox; concepts-before-recipes.
• references/bestpractices-archetype-amend.md — depth for production + change angles: the best-practices catalog (auth/errors/retries/pagination/rate-limits/webhooks/resource-hygiene), the troubleshooting symptom→cause→fix method, the four tool-archetype overlays, the docs-as-code/freshness habit, and the amend (Step 6) staleness-sweep procedure.
• references/sources.md — research provenance for the method + quality bar (Diataxis; DX-docs / IA practice; the developer-docs quality rubric; SDK/API documentation, error-handling, retries/idempotency, pagination, rate-limit, troubleshooting, versioning/migration, and docs-as-code/living-docs guidance). Load only to audit where the guidance came from.

Body budget

• description ≤ 1,024 chars (agentskills.io cap).
• Body ≤ ~500 lines / 5,000 tokens.
• Heavy content lives in references/, loaded on demand.