Eine gute API-Dokumentation entscheidet oft darüber, ob eine API überhaupt genutzt wird. Das API-Drehbuch übersetzt eine technische Spezifikation, zum Beispiel eine Swagger-Datei oder eine manuelle Endpunkt-Liste, in eine klare, direkt nutzbare Dokumentation. Im Zentrum steht die Zeit bis zum ersten erfolgreichen API-Call: Die Dokumentation beginnt deshalb immer mit einem Quick Start Guide und liefert für jeden Endpunkt funktionierende Code-Beispiele in mehreren Sprachen.
\nDer Skill eignet sich für Product Owner, technische Redakteure und Entwicklungsteams, die eine API für interne oder externe Nutzerinnen und Nutzer zugänglich machen wollen. Typisches Szenario: Eine REST-API existiert bereits, die bisherige Doku besteht nur aus einer Swagger-Datei, Partner sollen aber ohne Rückfragen integrieren können.
\nWas der Skill bewusst nicht tut: Er implementiert keine API und prüft keinen Code gegen eine laufende API. Er schreibt Dokumentation auf Basis dessen, was Sie ihm an Spezifikation und Beispieldaten geben. Fehlt eine Angabe, kennzeichnet der Assistent das als Annahme, statt sie zu erfinden. Die Beispiele sollten Sie vor dem Veröffentlichen gegen die echte API testen.
\n" }, { "id": "skill-text", "title": "Skill-Text", "html": "Kopieren Sie den Prompt unten komplett in Ihr KI-Tool. Als Datei: api-drehbuch.de.json
\n" } ], "schritte": [ { "nr": 1, "titel": "API-Spezifikation bereitstellen", "beschreibung": "Endpunkte, Authentifizierungsmethode, Request- und Response-Formate sowie die Zielgruppe werden bereitgestellt.", "rolle": "mensch" }, { "nr": 2, "titel": "Dokumentation erstellen", "beschreibung": "Die API-Architektur wird analysiert, anschließend entstehen Quick Start Guide, Authentifizierungsanleitung, Endpunkt-Referenz mit Code-Beispielen und Fehler-Referenz.", "rolle": "automatisch" }, { "nr": 3, "titel": "Fertige API-Dokumentation", "beschreibung": "Eine vollständige, strukturierte Dokumentation liegt vor, von der Übersicht bis zum Changelog.", "rolle": "ergebnis" }, { "nr": 4, "titel": "Beispiele testen", "beschreibung": "Die Code-Beispiele werden gegen die echte API geprüft, bevor die Dokumentation freigegeben und veröffentlicht wird.", "rolle": "freigabe" } ], "herausgeber": "Voyage Digital", "version": "2.0", "stand": "2026-07-27", "umsetzung": [ { "titel": "API-Spezifikation bereithalten", "text": "Eine OpenAPI- oder Swagger-Datei, ersatzweise eine manuell erstellte Endpunkt-Liste, wird vor dem Start bereitgelegt." }, { "titel": "Skill einrichten", "text": "Der Skill-Text wird kopiert und die Spezifikation wird als Eingabe mitgegeben." }, { "titel": "Dokumentation erstellen lassen", "text": "Der Assistent schreibt die Dokumentation Abschnitt für Abschnitt, beginnend mit dem Quick Start Guide." }, { "titel": "Beispiele testen", "text": "Die generierten Code-Beispiele werden gegen die echte API geprüft, bevor die Dokumentation veröffentlicht wird." }, { "titel": "Als lebendes Dokument pflegen", "text": "Bei neuen Endpunkten oder geänderten Formaten wird die Dokumentation erneut durchlaufen und aktualisiert." } ], "zutaten": [ "Endpunkte", "Auth-Methode", "Request- und Response-Formate", "Zielgruppe" ], "beispielSzenario": "Ein Team hat eine REST-API für ein Buchungssystem entwickelt. Partnerunternehmen sollen sie integrieren, doch die bestehende Dokumentation besteht bislang nur aus einer Swagger-Datei. Gefragt ist eine entwicklerfreundliche Dokumentation mit Quick Start Guide, Authentifizierungsanleitung und Beispielen in JavaScript und Python, damit die Partner innerhalb einer Stunde ihren ersten erfolgreichen Booking-Call durchführen können.", "eingaben": [ { "feld": "API-Spezifikation", "pflicht": true }, { "feld": "Request- und Response-Formate", "pflicht": true }, { "feld": "Authentifizierungsmethode", "pflicht": true }, { "feld": "Zielgruppe", "pflicht": false }, { "feld": "Bestehende Dokumentation", "pflicht": false }, { "feld": "Beispieldaten", "pflicht": false } ], "ausgabe": "Eine vollständige Dokumentation mit Übersicht, Quick Start Guide, Authentifizierungsanleitung, Endpunkt-Referenz, Code-Beispielen in mehreren Sprachen, Fehler-Referenz, Rate Limits und Changelog.", "prompt": "# AUFGABE\nSie verfassen entwicklerfreundliche API-Dokumentation. Aus einer technischen API-Spezifikation entsteht eine klare, sofort nutzbare Dokumentation mit lauffähigen Beispielen, die Entwicklerinnen und Entwicklern eine zügige Integration erlaubt.\n\n# BENÖTIGTE EINGABEN\nPflichtangaben:\n- API-Spezifikation: Endpunkte, HTTP-Methoden, Parameter\n- Request- und Response-Formate: JSON-Schemas, Datentypen\n- Authentifizierungsmethode: API Key, OAuth, JWT\n\nOptionale Angaben, sofern vorhanden:\n- Zielgruppe: Frontend, Backend, Partner, externe Entwickler\n- Bestehende Dokumentation: OpenAPI/Swagger, Postman\n- Beispieldaten: realistische Testdaten\n\n# VORGEHEN\n\nGrundlagen klären: Zweck der API, ihre Endpunkte und das zugrunde liegende Datenmodell werden erfasst, bevor der erste Satz Dokumentation entsteht.\n\nKerndokumente verfassen: Zunächst der Quick Start Guide, der kürzeste Weg zum ersten erfolgreichen API-Call. Danach die Authentifizierung, mit konkreten Beispielen und Hinweisen zur Fehlerbehebung, denn an diesen beiden Stellen scheitert eine Integration am häufigsten.\n\nVollständige Referenz aufbauen: Für jeden Endpunkt werden URL, Methode, Parameter und Response mit Beispielen dokumentiert, sodass keine Rückfrage an das Entwicklungsteam nötig wird.\n\nRand und Kontrolle: Alle Fehlercodes und die Rate Limits werden erfasst. Zum Abschluss werden sämtliche Beispiele auf Korrektheit und Konsistenz durchgesehen.\n\n# AUFBAU DER DOKUMENTATION\nDas Ergebnis ist eine vollständige API-Dokumentation mit genau diesen Abschnitten, in dieser Reihenfolge:\n1. Übersicht: was die API leistet, Base URL, Versionierung\n2. Erste Schritte: Quick Start Guide\n3. Authentifizierung: Anleitung mit Beispielen\n4. Endpunkt-Referenz: pro Endpunkt URL, Methode, Parameter, Response\n5. Request-Beispiele: Curl, JavaScript, Python\n6. Response-Beispiele: Erfolg und Fehler\n7. Fehler-Referenz: HTTP-Statuscodes und Meldungen\n8. Rate Limits: Nutzungsbeschränkungen\n9. Changelog: Versionshistorie\n\n# QUALITÄTSMASSSTAB\nDie Dokumentation gilt erst als fertig, wenn:\n- jeder Endpunkt vollständig dokumentiert ist,\n- der Quick Start Guide einen schnellen Einstieg tatsächlich ermöglicht,\n- die Authentifizierung klar und nachvollziehbar beschrieben ist,\n- zu jedem Endpunkt ein funktionierendes Beispiel vorliegt,\n- Fehler-Responses dokumentiert sind,\n- alle Code-Beispiele syntaktisch korrekt sind.\n\n# GRENZEN UND SPRACHE\n- Globale Platzhalter: UNTERNEHMEN, TECH_STACK\n- Domänenwissen, auf das zurückgegriffen wird: REST-API-Design, HTTP-Standards, Authentifizierungsprotokolle\n- Diese Aufgabe umfasst ausschließlich das Schreiben von Dokumentation, keine Implementierung einer API.\n- Der Assistent spricht Nutzerinnen und Nutzer durchgehend in der Sie-Form an.\n- Fehlen Angaben zur API oder sind sie unklar, kennzeichnet der Assistent die betroffene Stelle ausdrücklich als Annahme, statt sie stillschweigend zu setzen.\n\n# EINSTIEG INS GESPRÄCH\nWelche API soll dokumentiert werden? Nennen Sie die Endpunkte, das Authentifizierungsverfahren und die Zielgruppe, daraus entsteht eine entwicklerfreundliche API-Dokumentation.", "einrichtung": { "intro": "Schritt-für-Schritt-Anleitungen für ChatGPT, Claude, Copilot Studio und Langdock.", "plattformen": [ { "plattform": "ChatGPT", "anbieter": "OpenAI", "schritte": [ "Kopieren Sie den Skill-Text oben über die Kopieren-Schaltfläche.", "Klicken Sie auf Ihr Profilbild und wählen Sie „Skills“.", "Klicken Sie auf „Skill erstellen“ und fügen Sie den kopierten Text als Anweisung ein.", "Passen Sie Eingaben, Ausgaben und Format an, wo es für Ihren Fall nötig ist.", "Speichern Sie den Skill. Er steht ab sofort in allen Chats zur Verfügung." ], "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": [ "Kopieren Sie den Skill-Text oben über die Kopieren-Schaltfläche.", "Öffnen Sie claude.ai und gehen Sie in Ihrem Profil auf „Skills“.", "Legen Sie einen neuen Skill an und fügen Sie den kopierten Text als Anweisung ein.", "Der Skill arbeitet in claude.ai, in Claude Code und über die API.", "Verfügbar in den Tarifen Pro, Max, Team und Enterprise." ], "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": [ "Kopieren Sie den Skill-Text oben über die Kopieren-Schaltfläche.", "Öffnen Sie Copilot Studio und legen Sie einen neuen Agent an.", "Fügen Sie den kopierten Text als Anweisung ein.", "Verbinden Sie bei Bedarf Wissensquellen und Werkzeuge.", "Veröffentlichen Sie den Agent für sich selbst oder für Ihre 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": [ "Kopieren Sie den Skill-Text oben über die Kopieren-Schaltfläche.", "Öffnen Sie die Seitenleiste und klicken Sie auf „Skill hinzufügen“.", "Fügen Sie den kopierten Text direkt als Anweisung ein.", "Verbinden Sie den Skill bei Bedarf mit Integrationen, etwa Gmail oder Slack.", "Speichern Sie den Skill und geben Sie ihn für sich oder Ihr Team frei." ], "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": "Das Bugreport-Protokoll", "teaser": "Bringt eine formlose Fehlerbeschreibung in eine Struktur, die ein Entwicklungsteam ohne Rückfrage bearbeiten kann.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "bug" }, { "slug": "anleitungs-dokumentierer", "category": "assistent", "name": "Der Anleitungs-Dokumentierer", "teaser": "Verwandelt Produktinfos und technische Spezifikationen in eine vollständige, verständliche Dokumentation, von der Übersicht bis zum Troubleshooting.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "book-open-check" }, { "slug": "review-protokoll", "category": "skill", "name": "Das Review-Protokoll", "teaser": "Verwandelt grobe Review-Notizen zu einem Code-Diff in ein strukturiertes, konstruktives Feedback mit klarer Kategorisierung und Empfehlung.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "search-check" }, { "slug": "stripe-agent-skills", "category": "tool", "name": "Stripe Agent Skills", "teaser": "Stripes offizielle Sammlung aus Agent-Skills für Best-Practices, Projekt-Setup und API-Versions-Upgrades, damit KI-Coding-Agenten korrekte Stripe-Integrationen schreiben.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "stripe-agent-skills.png", "logoEinzug": 0.78 }, { "slug": "mcp-builder", "category": "skill", "name": "Das Schnittstellen-Gerüst", "teaser": "Führt durch Recherche, Implementierung, Test und Evaluation eines MCP-Servers: typisierte Tools, saubere Fehlerbehandlung, Paginierung und zehn verifizierte Evaluationsfragen für zuverlässigen Zugriff eines Sprachmodells auf einen externen Dienst.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "plug" }, { "slug": "vba-uebersetzer", "category": "assistent", "name": "Der VBA-Übersetzer", "teaser": "Übersetzt Automatisierungsaufgaben in Excel in lauffähigen VBA-Code, analysiert dafür die konkrete Dateistruktur und debuggt bestehende Makros.", "domaene": "Softwareentwicklung & technische Infrastruktur", "itemIcon": "code" }, { "slug": "netlify", "category": "tool", "name": "Netlify", "teaser": "Hosting- und Deployment-Plattform für statische Websites und Jamstack-Anwendungen, mit Git-basiertem Build-Workflow, automatischen Deploy-Previews und globalem CDN.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "netlify.svg", "logoEinzug": 1 }, { "slug": "runpod", "category": "tool", "name": "Runpod", "teaser": "Cloud-Plattform für GPU-Rechenleistung, die sekundengenau abrechnet und für serverlose Inferenz bedarfsgesteuert hochfährt und wieder auf null zurückgeht.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "runpod.png", "logoEinzug": 0.78 }, { "slug": "stripe", "category": "tool", "name": "Stripe", "teaser": "Zahlungsinfrastruktur mit Entwickler-API für Zahlungsabwicklung, Subscription-Billing, Marktplatz-Auszahlungen und Betrugserkennung, abgerechnet pro Transaktion.", "domaene": "Softwareentwicklung & technische Infrastruktur", "logoFile": "stripe.svg", "logoEinzug": 0.78 }, { "slug": "zweitverwertungs-strecke", "category": "workflow", "name": "Die Zweitverwertungs-Strecke", "teaser": "Verwandelt jeden neuen Blogartikel automatisch in mehrere kanalgerechte Content-Entwürfe und legt diese direkt als Aufgaben für Ihr Team an.", "domaene": "Content & Redaktion", "itemIcon": "recycle" } ] }