write-openapi
Author, configure, structure, and troubleshoot OpenAPI/Swagger API reference documentation in GitBook. Use this whenever a task involves a GitBook OpenAPI block or `{% openapi %}` block, adding or updating an OpenAPI/Swagger spec in GitBook (by file or URL, via the API, MCP, CLI, or app UI), generating API reference pages from a spec, configuring the interactive "Test it" runner (auth, servers, CORS, proxy), customizing pages with GitBook `x-*` extensions (icons, titles, navigation hierarchy, code samples, enum descriptions), marking operations experimental/deprecated/hidden, or automating spec updates in CI/CD. Trigger even when the user only mentions GitBook plus OpenAPI, puts an `x-` extension on a spec destined for GitBook, or asks "why isn't my spec loading" or "why doesn't Test it work", without naming this skill.
Install
With your agent
Install OMGSkills skill "gitbookio/gitbook-skills:skills/write-openapi" into this agent's normal skills directory: call the OMGSkills MCP get_install_plan tool for your agent and run the script it returns (it installs only the pinned commit and verifies SKILL.md), and stop if MCP or the pin is unavailable. Do not overwrite or change existing skills without asking me.
Manual command
git clone https://github.com/GitbookIO/gitbook-skills /tmp/gitbook-skills && ln -s /tmp/gitbook-skills/skills/write-openapi ~/.claude/skills/write-openapiFrom README
GitBook OpenAPI GitBook turns an OpenAPI document into interactive, testable API reference blocks. You give it a spec (as JSON or YAML), and it renders endpoints, parameters, schemas, auth, and an in-page request runner. Most of the customization happens inside the spec itself through x- extensions, not in the GitBook UI, so the bulk of any task here is editing OpenAPI YAML correctly. This skill covers the full surface: getting a spec into GitBook, generating reference pages, structuring navigation, making the "Test it" runner work, controlling how operations and schemas display, and automating updates from CI/CD. How you can talk to GitBook Most of this skill — editing the OpenAPI YAML/JSON itself — is transport-agnostic. But getting a spec into GitBook, or generating/inserting reference pages, does touch GitBook, and there's more than one way to do that: GitBook's MCP server and the REST API.