Good API documentation often decides whether an API gets used at all. The API Playbook translates a technical specification, for example a Swagger file or a manual list of endpoints, into clear, directly usable documentation. The focus is on time to first successful API call: the documentation therefore always opens with a quick start guide and provides working code examples in multiple languages for every endpoint.
\nThe skill is built for product owners, technical writers and development teams who want to make an API accessible to internal or external users. Typical scenario: a REST API already exists, the current documentation is nothing more than a Swagger file, and partners need to be able to integrate without follow-up questions.
\nWhat the skill deliberately does not do: it does not implement an API and does not check code against a running API. It writes documentation based on the specification and sample data you provide. Where a detail is missing, the assistant flags it as an assumption rather than inventing it. Test the examples against the real API before publishing.
\n" }, { "id": "skill-text", "title": "Skill Text", "html": "Copy the prompt below in full into your AI tool. As a file: api-drehbuch.en.json
\n" } ], "schritte": [ { "nr": 1, "titel": "Provide the API specification", "beschreibung": "Endpoints, the authentication method, request and response formats, and the target audience are provided.", "rolle": "mensch" }, { "nr": 2, "titel": "Create the documentation", "beschreibung": "The API architecture is analyzed, then the quick start guide, authentication guide, endpoint reference with code examples, and error reference are written.", "rolle": "automatisch" }, { "nr": 3, "titel": "Finished API documentation", "beschreibung": "Complete, structured documentation is ready, from the overview to the changelog.", "rolle": "ergebnis" }, { "nr": 4, "titel": "Test the examples", "beschreibung": "The code examples are checked against the real API before the documentation is approved and published.", "rolle": "freigabe" } ], "herausgeber": "Voyage Digital", "version": "2.0", "stand": "2026-07-27", "umsetzung": [ { "titel": "Have the API specification ready", "text": "An OpenAPI or Swagger file, or alternatively a manually compiled list of endpoints, is prepared before starting." }, { "titel": "Set up the skill", "text": "The skill text is copied and the specification is provided as input." }, { "titel": "Generate the documentation", "text": "The assistant writes the documentation section by section, starting with the quick start guide." }, { "titel": "Test the examples", "text": "The generated code examples are checked against the real API before the documentation is published." }, { "titel": "Maintain it as a living document", "text": "Whenever endpoints are added or formats change, the documentation is run through again and updated." } ], "zutaten": [ "Endpoints", "Authentication method", "Request and response formats", "Target audience" ], "beispielSzenario": "A team has built a REST API for a booking system. Partner companies need to integrate it, but the existing documentation is nothing more than a Swagger file. What is needed is developer-friendly documentation with a quick start guide, an authentication guide, and examples in JavaScript and Python, so partners can make their first successful booking call within an hour.", "eingaben": [ { "feld": "API specification", "pflicht": true }, { "feld": "Request and response formats", "pflicht": true }, { "feld": "Authentication method", "pflicht": true }, { "feld": "Target audience", "pflicht": false }, { "feld": "Existing documentation", "pflicht": false }, { "feld": "Sample data", "pflicht": false } ], "ausgabe": "Complete documentation with an overview, quick start guide, authentication guide, endpoint reference, code examples in multiple languages, error reference, rate limits, and changelog.", "prompt": "# TASK\nYou write developer-friendly API documentation. From a technical API specification, you produce clear, immediately usable documentation with working examples that lets developers integrate quickly.\n\n# INPUTS NEEDED\nRequired:\n- API specification: endpoints, HTTP methods, parameters\n- Request and response formats: JSON schemas, data types\n- Authentication method: API key, OAuth, JWT\n\nOptional, where available:\n- Target audience: frontend, backend, partners, external developers\n- Existing documentation: OpenAPI/Swagger, Postman\n- Sample data: realistic test data\n\n# APPROACH\n\nClarify the foundation: capture the API's purpose, its endpoints, and the underlying data model before writing a single line of documentation.\n\nWrite the core documents: start with the quick start guide, the shortest path to the first successful API call. Then authentication, with concrete examples and troubleshooting notes, since integrations most often stall at exactly these two points.\n\nBuild out the full reference: document URL, method, parameters, and response for every endpoint, complete with examples, so no follow-up question to the development team is needed.\n\nCover the edges and check the work: capture every error code and the rate limits. Finally, review all examples for correctness and consistency.\n\n# STRUCTURE OF THE DOCUMENTATION\nThe result is complete API documentation with exactly these sections, in this order:\n1. Overview: what the API does, base URL, versioning\n2. Getting started: quick start guide\n3. Authentication: guide with examples\n4. Endpoint reference: per endpoint URL, method, parameters, response\n5. Request examples: Curl, JavaScript, Python\n6. Response examples: success and error\n7. Error reference: HTTP status codes and messages\n8. Rate limits: usage restrictions\n9. Changelog: version history\n\n# QUALITY BAR\nThe documentation only counts as finished once:\n- every endpoint is fully documented,\n- the quick start guide actually enables a fast start,\n- authentication is described clearly and is easy to follow,\n- every endpoint has a working example,\n- error responses are documented,\n- all code examples are syntactically correct.\n\n# LIMITS AND LANGUAGE\n- Global placeholders: COMPANY, TECH_STACK\n- Domain knowledge drawn on: REST API design, HTTP standards, authentication protocols\n- This task covers writing documentation only, not implementing an API.\n- Address the user in a professional manner throughout.\n- Where details on the API are missing or unclear, explicitly flag the affected part as an assumption instead of setting it silently.\n\n# OPENING THE CONVERSATION\nWhich API should be documented? Share the endpoints, the authentication method, and the target audience, and developer-friendly API documentation will follow.", "einrichtung": { "intro": "Step-by-step guides for ChatGPT, Claude, Copilot Studio and Langdock.", "plattformen": [ { "plattform": "ChatGPT", "anbieter": "OpenAI", "schritte": [ "Copy the skill text above using the copy button.", "Click your profile picture and select \"Skills\".", "Click \"Create skill\" and paste the copied text as the instruction.", "Adjust inputs, outputs and format where your case requires it.", "Save the skill. It is available in all chats from that point on." ], "doku": { "label": { "de": "OpenAI Dokumentation: Skills in ChatGPT", "en": "OpenAI documentation: Skills in ChatGPT" }, "url": "https://help.openai.com/de-de/articles/20001066-skills-in-chatgpt" } }, { "plattform": "Claude", "anbieter": "Anthropic", "schritte": [ "Copy the skill text above using the copy button.", "Open claude.ai and go to \"Skills\" in your profile.", "Create a new skill and paste the copied text as the instruction.", "The skill works in claude.ai, in Claude Code and through the API.", "Available on the Pro, Max, Team and Enterprise plans." ], "doku": { "label": { "de": "Anthropic Dokumentation: Benutzerdefinierte Skills erstellen", "en": "Anthropic documentation: Creating custom skills" }, "url": "https://support.claude.com/de/articles/12512198-benutzerdefinierte-skills-erstellen" } }, { "plattform": "Copilot Studio", "anbieter": "Microsoft", "schritte": [ "Copy the skill text above using the copy button.", "Open Copilot Studio and create a new agent.", "Paste the copied text as the instruction.", "Connect knowledge sources and tools where needed.", "Publish the agent for yourself or for your organisation." ], "doku": { "label": { "de": "Microsoft Dokumentation: Einen Agent erstellen und bereitstellen", "en": "Microsoft documentation: Create and deploy an agent" }, "url": "https://learn.microsoft.com/de-de/microsoft-copilot-studio/fundamentals-get-started" } }, { "plattform": "Langdock", "anbieter": null, "schritte": [ "Copy the skill text above using the copy button.", "Open the sidebar and click \"Add skill\".", "Paste the copied text directly as the instruction.", "Connect the skill to integrations such as Gmail or Slack where needed.", "Save the skill and release it for yourself or your team." ], "doku": { "label": { "de": "Langdock Dokumentation: Skills", "en": "Langdock documentation: Skills" }, "url": "https://docs.langdock.com/de/product/chat/skills" } } ] }, "itemIcon": "webhook", "recommended": [ { "slug": "bugreport-protokoll", "category": "skill", "name": "The Bug Report Protocol", "teaser": "Turns a freeform bug description into a structured bug report that can be entered directly into your ticketing system, with reproducible steps, a clear separation between expected and actual behavior, environment data, and a severity estimate.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "bug" }, { "slug": "anleitungs-dokumentierer", "category": "assistent", "name": "The Documentation Writer", "teaser": "Creates complete, understandable technical documentation from product information, technical specifications and a defined audience, from the product overview through installation and usage to troubleshooting and glossary.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "book-open-check" }, { "slug": "review-protokoll", "category": "skill", "name": "The Review Protocol", "teaser": "Turns rough code review notes into structured, constructive review feedback with severity-sorted remarks, rationale, and a clear approve/request-changes/comment recommendation.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "search-check" }, { "slug": "stripe-agent-skills", "category": "tool", "name": "Stripe Agent Skills", "teaser": "Stripe Agent Skills is Stripe's official collection of agent skills for best practices, project setup and version upgrades, giving AI coding agents current, correct patterns for building Stripe integrations.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "stripe-agent-skills.png", "logoEinzug": 0.78 }, { "slug": "mcp-builder", "category": "skill", "name": "The MCP Builder", "teaser": "Guides you through research, implementation, testing and evaluation of an MCP server: typed tools, clean error handling, pagination and ten verified evaluation questions for reliable access by a language model to an external service.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "plug" }, { "slug": "vba-uebersetzer", "category": "assistent", "name": "The VBA Translator", "teaser": "Translates automation tasks in Excel into working VBA code based on the concrete file structure, and debugs existing macros.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "code" }, { "slug": "netlify", "category": "tool", "name": "Netlify", "teaser": "Netlify is a hosting and deployment platform for static websites and Jamstack applications with a Git-based build workflow, automatic deploy previews and a global CDN.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "netlify.svg", "logoEinzug": 1 }, { "slug": "runpod", "category": "tool", "name": "Runpod", "teaser": "Cloud platform for GPU compute, billed by the second, with serverless endpoints that scale up on demand and back down to zero.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "runpod.png", "logoEinzug": 0.78 }, { "slug": "stripe", "category": "tool", "name": "Stripe", "teaser": "Stripe is a payment infrastructure with an extensive developer API for payment processing, subscription billing and marketplace payouts.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "stripe.svg", "logoEinzug": 0.78 }, { "slug": "zweitverwertungs-strecke", "category": "workflow", "name": "The Content Repurposing Pipeline", "teaser": "Automatically turns every new blog post into several channel-ready content drafts and files them directly as tasks for your team.", "domaene": "Content & Redaktion", "itemIcon": "recycle" } ] }