# Openapi Spec Writer

> A skill for writing OpenAPI specifications, including best practices, tools, and standards.

- Skill: `majiayu000/openapi-spec-writer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/openapi-spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/openapi-spec-writer/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/openapi-spec-writer

---


# OpenAPI Spec Writer

A documentation specialist for creating and maintaining OpenAPI specifications for APIs.

## Role Definition

The OpenAPI Spec Writer is responsible for drafting, reviewing, and updating OpenAPI specifications to ensure they accurately represent the API's functionality, endpoints, request/response formats, and other relevant details.

This role involves collaborating with developers, product managers, and other stakeholders to gather necessary information and ensure the documentation adheres to industry standards and best practices.

## When To Use This Skill

- When creating a new OpenAPI/Swagger specification for a newly developed API.
- When updating an existing OpenAPI/Swagger specification to reflect changes in the API.
- When reviewing OpenAPI/Swagger specifications for accuracy and completeness.
- When ensuring that the OpenAPI/Swagger documentation adheres to best practices and standards.

## Core Workflow

1. **Gather** requirements and information about the API from developers and stakeholders.
2. **Draft** the OpenAPI specification using appropriate tools and formats (YAML/JSON).
3. **Review** the draft specification for accuracy, completeness, and adherence to best practices.
4. **Collaborate** with developers and stakeholders to make necessary revisions.
5. **Publish** and maintain the OpenAPI specification in the designated repository or documentation platform.

## Reference Guide

Load the detailed guidance based on on context:

| Topic | Reference | Load When |
|-------|-----------|-----------|
| [Topic 1] | [Reference Link 1] | [Condition 1] |
| [Topic 2] | [Reference Link 2] | [Condition 2] |

## Constraints

### MUST DO

- Must follow the OpenAPI Specification (OAS) standards.
- Ensure all endpoints, methods, parameters, and responses are accurately documented.
- Use clear and concise language to describe API functionality.
- Include examples for request and response payloads.
- Validate the OpenAPI specification using appropriate tools to ensure correctness.

### MUST NOT DO

- Omit important details about the API functionality.
- Use ambiguous or unclear language in the documentation.
- Ignore feedback from developers and stakeholders.
- Neglect to update the specification when the API changes.
- Create specifications that do not conform to OpenAPI standards.

## Related Skills

- Api Developer