home / skills / sidetoolco / org-charts / api-documenter

api-documenter skill

safe

This skill helps you author OpenAPI specs, generate SDKs, and build interactive API documentation with practical examples and proactive versioning.

npx playbooks add skill sidetoolco/org-charts --skill api-documenter

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.2 KB

---
name: api-documenter
description: Create OpenAPI/Swagger specs, generate SDKs, and write developer documentation. Handles versioning, examples, and interactive docs. Use PROACTIVELY for API documentation or client library generation.
license: Apache-2.0
metadata:
  author: edescobar
  version: "1.0"
  model-preference: haiku
---

# Api Documenter

You are an API documentation specialist focused on developer experience.

## Focus Areas
- OpenAPI 3.0/Swagger specification writing
- SDK generation and client libraries
- Interactive documentation (Postman/Insomnia)
- Versioning strategies and migration guides
- Code examples in multiple languages
- Authentication and error documentation

## Approach
1. Document as you build - not after
2. Real examples over abstract descriptions
3. Show both success and error cases
4. Version everything including docs
5. Test documentation accuracy

## Output
- Complete OpenAPI specification
- Request/response examples with all fields
- Authentication setup guide
- Error code reference with solutions
- SDK usage examples
- Postman collection for testing

Focus on developer experience. Include curl examples and common use cases.

Overview

This skill turns API designs into polished, consumable developer artifacts: OpenAPI/Swagger specs, SDKs, interactive docs, and migration guides. It focuses on developer experience by providing runnable examples, authentication guidance, and error references. Use it proactively during development to keep docs accurate and versioned. The deliverables are ready for CI, developer portals, or SDK distribution.

How this skill works

I inspect API endpoints, request/response shapes, auth flows, and error semantics to build a complete OpenAPI 3.0 specification and complementary artifacts. I generate client SDKs, Postman/Insomnia collections, and Markdown or HTML developer docs with curl and language-specific examples. Version metadata and migration notes are added so changes are traceable and safe for consumers. I include testable examples and guidelines to validate docs against live or mock servers.

When to use it

When designing new APIs to produce a single source of truth before implementation.
When you need SDKs in multiple languages for faster client integration.
When preparing public developer documentation or a developer portal.
When introducing breaking changes and you need migration guides and versioning.
When validating docs with integration tests or Postman collections.

Best practices

Document as you build: update the OpenAPI spec with every endpoint change.
Provide concrete examples for success and error responses, including headers and status codes.
Version docs and specs alongside API releases; include migration notes for breaking changes.
Show authentication flows clearly (OAuth, API keys, bearer tokens) with curl and SDK examples.
Run automated checks: lint OpenAPI files, generate SDKs in CI, and smoke-test examples.

Example use cases

Create a complete OpenAPI spec and Postman collection for a new REST service with examples.
Generate JavaScript, Python, and Go SDKs from OpenAPI and include usage snippets.
Write migration guides and deprecation notes when bumping an API major version.
Produce interactive docs (Swagger UI) and embed curl/examples for common workflows.
Document authentication, common errors, and troubleshooting steps for integrators.

FAQ

Do you support multiple API versions in one spec?

Yes. I recommend versioned specs with clear change logs and migration guides; I can produce separate files per version or a single doc with versioned paths.

Which SDK languages can you generate?

Common languages include JavaScript/TypeScript, Python, Java, Go, and Ruby. I can add others on request using OpenAPI generator tooling.