Skip to content
Get packs

Guide · Agent skill

How to use the API Documentation agent skill: OpenAPI, guides and docs

Updated · written with AI from the project's own documentation and checked against our catalogue data

The api-documentation skill is a workflow checklist that tells an AI agent how to produce API documentation for an existing REST API. It covers seven phases, from discovering endpoints to maintaining the docs after release, and it names other skills to call in each phase. This guide explains what the skill does, how to install it, how to trigger it, and what to check before anything goes public.

API Documentation Workflowsickn33/agentic-awesome-skills · MIT

Quick start

  1. 1Download the ZIP. Download the api-documentation skill ZIP from this page.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project.
  3. 3Or upload in the Claude apps. In the Claude apps, go to Settings, then Capabilities, then Skills, and upload the ZIP.
  4. 4Install the referenced helper skills. Add api-documenter, openapi-spec-generation and the other named skills, since the workflow relies on them and they are not included in this file.
  5. 5Ask for a specific documentation task. Describe the artifact you want, such as an OpenAPI spec or developer guide, and point the agent at your API source.
  6. 6Review and preview. Check generated specs and examples against the real system and preview the docs locally before any publishing.

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that an AI agent reads when a request matches the skill's description. The file gives the agent a structured procedure to follow instead of starting from scratch.

This skill is an index-style workflow. It is not a generator on its own. It breaks API documentation into seven phases: discover endpoints, write an OpenAPI spec, draft a developer guide, add code examples, set up interactive docs, build a documentation site, and maintain it. Each phase lists the helper skills to invoke, a set of actions, and a copy-paste prompt.

  • Phase 1: API discovery (inventory endpoints, document request and response, identify authentication, map error codes, note rate limits)
  • Phase 2: OpenAPI specification (schemas, paths, security, examples)
  • Phase 3: Developer guide (getting started, authentication, common patterns, troubleshooting, FAQ)
  • Phase 4: Code examples (requests, SDK examples, curl examples, tutorials)
  • Phase 5: Interactive docs (Swagger UI, Redoc, try-it functionality)
  • Phase 6: Documentation site (platform, structure, navigation, search)
  • Phase 7: Maintenance (auto-generation, validation, review, updates, feedback)

How do you install the api-documentation skill?

Download the ZIP for this skill from this page. Then either unzip it into your personal skills folder at ~/.claude/skills/, or unzip it into a project's .claude/skills/ folder so it applies only to that project.

You can also upload the skill in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the ZIP there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a natural request?

You do not need a special command. Describe the documentation task in plain language and name the artifact you want. The skill's description covers OpenAPI specs, developer guides and API documentation, so requests about those topics are the ones it is meant to match.

The source also provides copy-paste prompts for each phase. You can use them directly, for example asking the agent to use the documentation skill to discover and document your endpoints.

  • "Document the endpoints in this repository and note how authentication works."
  • "Create an OpenAPI specification from our existing route handlers."
  • "Write a developer guide with getting started, authentication and troubleshooting sections."
  • "Add curl examples for the main endpoints and test them against our sandbox."
Use @api-documenter to discover and document API endpoints

What do you need before you start?

The skill names several referenced skills that must be installed separately: api-documenter, openapi-spec-generation, api-documentation-generator, documentation-templates, tutorial-engineer, docs-architect and wiki-page-writer. They are not included in this file, and the workflow does not define how they behave. If they are missing, the workflow only names them and cannot rely on them.

The skill is most useful when you have an existing REST API to document, ideally with access to its real implementation or specification. The file says the contract should be based on the actual implementation or specification, so the agent needs that source material.

  • An existing REST API or its implementation/specification
  • The referenced helper skills installed alongside this one
  • Sandbox endpoints and test credentials if you want try-it features

What are the safety notes for scripts and network use?

According to the file's metadata, this skill runs no scripts and uses no network access. Its instructions still set boundaries for the agent. Cloud calls, host configuration, publishing, destructive operations and spending require the applicable authorization, and a checklist does not grant that authorization.

Try-it features can send real requests, so the file asks for explicit sandbox endpoints and test credentials. Keep secrets out of examples. Preview docs locally before publishing, because deployment is a separate authorized action.

  • Keep API keys and secrets out of examples and specs
  • Use explicit sandbox endpoints for try-it features
  • Preview documentation locally before any publishing
  • Deployment needs separate authorization and is not performed by this skill alone

What tips help you get reliable output?

Choose only the phases that match your task. The skill is an index, not an instruction to run every listed phase. Read each referenced skill before using it, and respect your repository's and your own constraints.

Check every generated spec and example against the real system before release. The skill's limitations state that its output does not replace environment-specific validation, testing or expert review. If required inputs or permissions are missing, the agent should stop and ask.

  • Start with Phase 1 or Phase 2 for an existing API, and skip phases you do not need
  • Verify generated examples by running them against a sandbox
  • Use the quality gates as a final checklist: spec complete, guide written, examples working, interactive docs functional, documentation deployed

What people use it for

  • Inventorying endpoints of an existing REST API and noting its authentication, error codes and rate limits
  • Drafting an OpenAPI specification from the real route handlers or existing schema
  • Writing a developer guide with getting started, authentication and troubleshooting sections
  • Generating curl and SDK examples that you then test against a sandbox
  • Planning a documentation site structure and a maintenance routine for updates

Frequently asked questions

Is the api-documentation skill free to use?

The source file is released under the MIT licence, as stated on this page. Check the licence file in the repository for the full terms before reusing it.

How do I install the api-documentation agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder. You can also upload the ZIP in the Claude apps under Settings, then Capabilities, then Skills.

Does this skill publish my API docs automatically?

No. The file says deployment needs separate authorization and is not performed by this skill alone. Preview docs locally before any publishing step.

Why does the skill mention other skills like api-documenter?

The workflow names helper skills for each phase, such as api-documenter and openapi-spec-generation. These are not included in this file and their behaviour is not defined here, so install them separately if you want the full workflow.

Does the skill run scripts or use the network?

According to its metadata, it runs no scripts and uses no network access. Try-it features can still send real requests, so use sandbox endpoints and test credentials.

How does this compare to a documentation generator tool?

This skill is a structured workflow that guides an AI agent through documentation phases and names other skills to call. It does not define its own generator, so the quality of output depends on the agent and the helper skills you install.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits developers and technical writers who want a checklist-style plan for OpenAPI specs, developer guides and interactive docs for an existing REST API. Skip it if you expect automatic publishing, if you have not installed the helper skills it names, or if you cannot verify generated examples against your real system.

Download the skill