Openapi Expert

If you're designing REST APIs or need to document existing ones, this gives you comprehensive OpenAPI 3.1 guidance with working examples. It covers the full spec including paths, schemas, security schemes, and reusable components, so you can generate client libraries, validate requests, and maintain actual API contracts instead of outdated wiki pages. The examples show real patterns like pagination, JWT auth, and proper error responses. Honestly, the spec itself has a learning curve, but once you're past the YAML verbosity, having machine-readable API definitions beats manual documentation every time. Best for teams that need consistent API design or want to automate SDK generation.

skills.sh installs: 280
GitHub stars: 44
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add personamanagmentlayer/pcl --skill openapi-expert --agent claude-code

Installs into .claude/skills of the current project.

Files

OpenAPI Expert

Expert guidance for OpenAPI Specification (formerly Swagger) - industry-standard for describing RESTful APIs with automatic documentation and code generation.

Core Concepts

OpenAPI Specification (OAS)

API description format (YAML/JSON)
Version 3.1 (latest) and 3.0
Machine-readable API contracts
Automatic documentation generation
Client/server code generation
API validation and testing

Key Components

Paths (endpoints)
Operations (HTTP methods)
Parameters
Request/Response bodies
Schemas (data models)
Security schemes
Components (reusable objects)

Advanced Features

Webhooks (OpenAPI 3.1)

webhooks:
  postCreated:
    post:
      summary: Post created webhook
      operationId: onPostCreated
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Post'
      responses:
        '200':
          description: Webhook received