home / skills / shaul1991 / shaul-agents-plugin / docs-api

docs-api skill

safe

This skill creates and maintains OpenAPI specs and API references, generating examples and changelogs to streamline documentation workflows.

npx playbooks add skill shaul1991/shaul-agents-plugin --skill docs-api

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

Files (1)

SKILL.md

442 B

---
name: docs-api
description: Docs API Agent. OpenAPI 스펙, API 레퍼런스 문서 작성을 담당합니다.
allowed-tools: Read, Write, Edit, Grep, Glob
---

# Docs API Agent

## 역할
API 문서 및 레퍼런스 작성을 담당합니다.

## 담당 업무
- OpenAPI 스펙 작성
- API 레퍼런스
- 요청/응답 예제
- 변경 로그

## 산출물 위치
- OpenAPI: `docs/api/openapi.yaml`
- 레퍼런스: `docs/api/reference/`

Overview

This skill generates and maintains API documentation for services, focusing on OpenAPI specifications and reference material. It produces clear request/response examples, change logs, and consumable API reference pages. The goal is accurate, machine-readable specs and developer-friendly documentation that stays in sync with the API.

How this skill works

The agent inspects API endpoints and produces an OpenAPI YAML that describes paths, parameters, schemas, security, and servers. It also generates human-focused reference pages with examples for requests and responses and records changelog entries for version updates. Outputs are organized so they can be published alongside the codebase or consumed by documentation tools.

When to use it

When creating a new API to provide a formal contract for clients
When updating endpoints to keep documentation and examples consistent with code
When preparing developer-facing reference pages for SDKs or public APIs
When producing machine-readable OpenAPI specs for tooling, testing, or codegen

Best practices

Keep route names, parameter types, and response schemas aligned with implementation to avoid drift
Provide concrete request and response examples for common success and error cases
Document authentication and authorization flows explicitly in the spec
Version the OpenAPI file and maintain a changelog for breaking vs non-breaking changes
Validate the YAML with an OpenAPI linter and run contract tests against example responses

Example use cases

Generate a complete OpenAPI 3.0 YAML for a new REST service to enable client code generation
Create API reference pages with sample payloads for a public developer portal
Update endpoints and produce changelog entries that highlight breaking changes and migration steps
Produce input/output examples to support automated integration tests and mock servers

FAQ

Can this skill generate client SDKs?

Indirectly. The skill produces a valid OpenAPI spec suitable for code generation tools that produce client SDKs.

How are breaking changes recorded?

Breaking changes are logged in the changelog output with a clear description, version, and migration notes to guide consumers.