api-documenter

Overview of api-documenter skill

What api-documenter does

The api-documenter skill helps an agent create and refine API documentation as OpenAPI/Swagger specs, with support material for REST-style API structure and a lighter mention of GraphQL. In practice, this is most useful when you need a usable openapi.yaml faster than starting from a blank file or a generic “write API docs” prompt.

Who should use api-documenter

Best fit readers are developers, technical writers, DX teams, and platform engineers who need to document endpoints, request/response shapes, authentication, and error handling in a standard machine-readable format. The api-documenter skill is especially helpful if your team wants docs that can later feed Swagger UI, code generation, validation, or review workflows.

The real job-to-be-done

Most users are not just “writing docs.” They are trying to turn scattered API knowledge into a valid-enough OpenAPI draft that others can review, implement against, or publish. api-documenter is strongest when you already know the API behavior and need structure, completeness, and consistency.

Why choose this over a plain prompt

The differentiator is not deep automation; it is guided structure. The repository gives you:

• a clear OpenAPI 3.0.3 starting pattern in references/openapi-template.yaml
• a starter generator in scripts/generate_openapi.py
• a simple validator in scripts/validate_openapi.py
• examples that reduce formatting guesswork

That makes api-documenter usage more repeatable than ad hoc prompting, even though you still need to supply the actual API details.

What it does not do for you

This skill does not discover your live API automatically, infer every schema accurately from code, or fully validate semantic OpenAPI correctness. The included validator is string-based and only checks for required sections, so adoption makes most sense when you want a guided draft workflow, not authoritative schema extraction.

How to Use api-documenter skill

api-documenter install context

This skill lives at skills/api-documenter in the zhaono1/agent-playbook repository: https://github.com/zhaono1/agent-playbook/tree/main/skills/api-documenter.

If your skills environment supports direct GitHub installs, use the install flow your tool expects for a remote skill collection. If not, clone the repository and point your agent tooling at the local skill directory. The baseline install pattern commonly used is:

npx skills add https://github.com/zhaono1/agent-playbook --skill api-documenter

If your environment differs, the key requirement is simply that the agent can read skills/api-documenter/SKILL.md and its supporting files.

Files to read before first use

For a quick api-documenter guide, read these in order:

1. SKILL.md for activation cues and the expected documentation shape
2. references/openapi-template.yaml for the minimum skeleton
3. scripts/generate_openapi.py for the starter file it can produce
4. scripts/validate_openapi.py to understand what the built-in check actually verifies
5. references/examples/openapi-example.yaml for a very small example

This reading order matters because the repo is more useful as a workflow scaffold than as a long-form handbook.

What input the skill needs

api-documenter performs best when you provide concrete source material, such as:

• endpoint list with methods and paths
• request parameters and body fields
• response examples and status codes
• auth method
• base URL or environments
• object/schema definitions
• naming conventions and tags

If you only say “document this API,” expect a generic shell. If you provide endpoint-by-endpoint facts, you get a draft that is closer to reviewable.

Turn a rough request into a strong prompt

Weak prompt:

Create OpenAPI docs for my API.

Stronger prompt:

Use the api-documenter skill to draft an OpenAPI 3.0.3 spec for a REST API.

Base URL: https://api.example.com/v1
Auth: Bearer token in Authorization header

Endpoints:
- GET /users?page={number}&limit={number}
  - 200 returns array of User plus pagination metadata
- POST /users
  - body: name, email
  - 201 returns created User
  - 409 if email already exists
- GET /users/{id}
  - 200 returns User
  - 404 if missing

Schemas:
- User: id string, name string, email string, createdAt string(date-time)

Please include:
- summary, operationId, description, tags
- parameters and requestBody
- success and error responses
- components.schemas
- components.securitySchemes

The stronger version works because it gives the skill enough structure to fill required OpenAPI sections without inventing business logic.

Use the included generator first when starting from zero

If you have no spec yet, generate a scaffold first:

python scripts/generate_openapi.py --output openapi.yaml --name users --version 1.0.0 --base-url https://api.example.com

This is useful because it creates a syntactically organized starting point with info, servers, paths, and a sample schema block. Then use the skill to replace placeholders with real endpoint and schema details.

Validate what the skill produced

After editing, run the included validator:

python scripts/validate_openapi.py --input openapi.yaml

This validator is intentionally lightweight. It checks whether required headings such as openapi:, info:, servers:, paths:, components:, and securitySchemes: appear in the file. It is good for catching incomplete drafts, not for proving full spec validity.

Suggested workflow for Technical Writing

For api-documenter for Technical Writing, a practical workflow is:

1. collect source truth from engineers, code, Postman collections, or existing docs
2. generate or copy a template skeleton
3. prompt the skill with endpoint facts, not prose-only descriptions
4. review naming consistency, response coverage, and auth details
5. run the validator
6. hand off the spec to engineers or render it in Swagger tooling for final review

This works well for technical writers because the skill reduces structural overhead while leaving editorial judgment with the human.

What the skill appears to optimize for

The repository content suggests the skill is optimized for:

• OpenAPI 3.0.3 structure
• complete endpoint sections
• explicit required vs recommended endpoint fields
• documentation that is good enough to standardize and review

It is less optimized for advanced multi-file specs, callbacks, webhooks, polymorphism, or full GraphQL schema documentation workflows.

Practical tips that improve output quality

A few small choices materially improve api-documenter usage:

• provide exact status codes instead of “handles errors”
• include at least one concrete response shape per endpoint
• specify whether fields are required, nullable, enum-like, or formatted
• define authentication once and ask the skill to reference it consistently
• ask for stable operationId naming early, before teams start integrating tooling

These details prevent the most common failure mode: a pretty but operationally vague spec.

Best repository paths for adapting the skill

If you want to tailor the skill to your own workflow, start with:

• skills/api-documenter/SKILL.md
• skills/api-documenter/references/openapi-template.yaml
• skills/api-documenter/scripts/generate_openapi.py
• skills/api-documenter/scripts/validate_openapi.py

That path gives you the activation rules, authoring template, starter generation, and quality gate in one pass.

api-documenter skill FAQ

Is api-documenter good for beginners?

Yes, if you already understand your API. The skill lowers OpenAPI formatting friction, but it does not teach the whole specification in depth. Beginners can use it effectively when they have concrete endpoint notes and compare results against the template and example files.

Is api-documenter only for REST APIs?

Mostly, yes in practical terms. The description mentions REST or GraphQL, but the repository evidence is centered on OpenAPI/Swagger patterns, sample YAML, RESTful path examples, and endpoint-style documentation. If your main job is GraphQL schema or resolver documentation, this may not be the best fit.

How is this different from asking an AI to write API docs?

The advantage of api-documenter is workflow discipline: activation cues, a reusable template, a generator script, and a validation script. A generic prompt may still work, but this skill gives your agent a clearer target structure and reduces blank-page drift.

Does api-documenter install include a full validator?

No. The built-in script is a simple completeness check, not a full OpenAPI parser or linter. If strict validation matters, pair this skill with dedicated OpenAPI tooling after the first draft.

When should I not use api-documenter?

Skip api-documenter if:

• you need automatic extraction from source code with minimal human input
• your API is primarily GraphQL and you need GraphQL-native docs
• you need advanced spec governance, bundling, linting, or contract testing out of the box
• you only want polished human-readable prose docs rather than an OpenAPI artifact

Can technical writers use api-documenter without coding heavily?

Yes. The strongest use case is often a technical writer who can gather endpoint facts, run a starter script, and iterate on YAML with engineering review. You do not need deep Python knowledge to benefit from the included scripts.

How to Improve api-documenter skill

Give api-documenter complete endpoint facts

The single best upgrade is better source input. For each endpoint, provide:

• method and path
• purpose
• parameters and body schema
• response schema by status code
• authentication
• edge-case or error responses

The skill can structure good material well; it cannot invent trustworthy API behavior.

Reduce ambiguity in schema descriptions

Many weak API docs fail because field intent is underspecified. Instead of “user object,” say:

• id: string, immutable
• email: string, unique
• createdAt: string, date-time
• status: enum active | suspended

This helps api-documenter produce components that are more reusable and less likely to need rewrites.

Ask for coverage, not just formatting

A better revision prompt is:

Review this OpenAPI draft with the api-documenter skill and identify missing:
- operationId values
- requestBody schemas
- error responses
- auth declarations
- shared component schemas
Then patch the spec.

That kind of prompt improves completeness more than simply asking the model to “clean up the YAML.”

Watch for the main failure modes

Common issues with this skill’s outputs are:

• placeholder descriptions left in place
• missing components.securitySchemes
• thin error response coverage
• path operations that have summaries but no meaningful schema detail
• drafts that pass the included validator but are still incomplete

Knowing these failure modes makes review faster.

Pair the template with your own style rules

If your team has naming and documentation conventions, state them explicitly:

• tag names by domain
• operationId verb style
• pagination format
• error envelope shape
• date and enum conventions

The stock api-documenter skill gives structure, but your local conventions are what make the output production-friendly.

Iterate after the first draft

A good second-pass prompt is usually narrower than the first:

Using the api-documenter skill, revise this spec to normalize schema names, move repeated objects into components.schemas, and add 401/403/404 responses where applicable.

This works better than regenerating from scratch because you preserve the useful structure while tightening consistency.

Extend the scripts if this becomes a recurring workflow

If you adopt api-documenter regularly, the highest-leverage improvement is customizing the helper scripts. For example:

• update generate_openapi.py to include your auth scheme and error envelope by default
• expand validate_openapi.py with extra required headings or tokens via --require
• store your own starter spec next to references/openapi-template.yaml

That turns a generic starter into a team-specific documentation accelerator.