Agent skill

openapi-specification

Quellcode ansehen: nickcrew/claude-cortex

#124Globales Ranking · von 124 SkillsSafe

Installation

npx skills add nickcrew/claude-cortex --skill openapi-specification

67

Installationen

EU-hosted inference API

Power your AI agent skills with open-source models.

Drop-in OpenAI-compatible API. No data leaves Europe.

MiniMax

MiniMax M3

$0.50 / $1.90

per M tokens

Z.ai

GLM 5.3 Flash

$0.20 / $0.60

per M tokens

MoonshotAI

Kimi K3

$4.00 / $18.00

per M tokens

DeepSeek

DeepSeek V4.1 Flash

$0.40 / $1.42

per M tokens

OpenAPI Specification

Design, validate, and maintain OpenAPI 3.x specifications for REST API contracts.
Covers schema patterns, security schemes, versioning, and code generation integration.

When to Use This Skill

  • Creating a new OpenAPI specification from scratch
  • Adding endpoints or schemas to an existing spec
  • Reviewing or validating an API contract for correctness
  • Setting up code generation from OpenAPI definitions
  • Designing reusable schema components for large APIs
  • Implementing security schemes in API specifications
  • Managing API versioning and deprecation

Quick Reference

Resource Purpose Load when
references/spec-patterns.md Schema patterns, security schemes, validation, versioning, reusable components Designing or reviewing specs

Workflow

Phase 1: Design       → Define API overview, resources, and operations
Phase 2: Schema       → Build data models with reusable components
Phase 3: Validate     → Lint and verify the spec for correctness
Phase 4: Integrate    → Generate docs, SDKs, and contract tests

Phase 1: API Design

Start with a high-level design before writing the spec:

  1. Identify resources -- what nouns does this API expose?
  2. Map operations -- what CRUD and custom actions apply to each resource?
  3. Define relationships -- how do resources reference each other?
  4. Plan authentication -- what security schemes are needed?
  5. Set conventions -- naming style, pagination, error format

Spec Skeleton

openapi: 3.1.0
info:
  title: [API Name]
  version: 1.0.0
  description: [What this API does]
paths:
  /resources:
    get:
      summary: List resources
      operationId: listResources
    post:
      summary: Create a resource
      operationId: createResource
  /resources/{id}:
    get:
      summary: Get a resource
      operationId: getResource
components:
  schemas: {}
  securitySchemes: {}

Phase 2: Schema Design

Build data models using components/schemas for reuse:

  • Use $ref to reference shared schemas -- never duplicate definitions
  • Apply allOf for composition, oneOf / anyOf for polymorphism
  • Add example values to every schema and property
  • Use required arrays explicitly -- don't rely on implicit behavior
  • Document nullable fields with type: [string, "null"] (3.1) or nullable: true (3.0)

Phase 3: Validate

Run validation before committing any spec changes:

# Spectral (recommended)
spectral lint openapi.yaml

# Redocly
redocly lint openapi.yaml

# swagger-cli
swagger-cli validate openapi.yaml

Common Validation Issues

Issue Fix
Missing operationId Add unique operationId to every operation
Unused schema Remove from components or add a $ref
Missing response description Add description to every response code
Path parameter not in path Match {param} in path with parameter definition
No 2xx response defined Add at least one success response per operation

Phase 4: Integrate

Use the validated spec to generate downstream artifacts:

  • Documentation: Redoc, Swagger UI, Stoplight
  • Client SDKs: openapi-generator, autorest, orval
  • Server stubs: openapi-generator with server templates
  • Contract tests: Schemathesis, Dredd, Prism

Quality Checklist

  • All paths have operationIds
  • HTTP methods match resource actions (GET reads, POST creates, etc.)
  • Every response has a description and schema
  • Security requirements defined at operation or global level
  • Examples provided for request and response bodies
  • Consistent naming conventions (camelCase, snake_case -- pick one)
  • Deprecation fields set on sunset endpoints
  • Spec passes linter with zero errors

Anti-Patterns

  • Do not inline schemas -- use $ref to components/schemas for anything reused
  • Do not mix API versions in a single spec file
  • Do not use 200 OK for create operations -- use 201 Created
  • Do not omit error response schemas -- document 4xx and 5xx consistently
  • Do not use additionalProperties: true without clear justification

So verwenden Sie diesen Skill

  1. 1

    Install openapi-specification by running npx skills add nickcrew/claude-cortex --skill openapi-specification in your project directory. Führen Sie den obigen Installationsbefehl in Ihrem Projektverzeichnis aus. Die Skill-Datei wird von GitHub heruntergeladen und in Ihrem Projekt platziert.

  2. 2

    Keine Konfiguration erforderlich. Ihr KI-Agent (Claude Code, Cursor, Windsurf usw.) erkennt installierte Skills automatisch und nutzt sie als Kontext bei der Code-Generierung.

  3. 3

    Der Skill verbessert das Verständnis Ihres Agenten für openapi-specification, und hilft ihm, etablierte Muster zu befolgen, häufige Fehler zu vermeiden und produktionsreifen Code zu erzeugen.

Was Sie erhalten

Skills sind Klartext-Anweisungsdateien — kein ausführbarer Code. Sie kodieren Expertenwissen über Frameworks, Sprachen oder Tools, das Ihr KI-Agent liest, um seine Ausgabe zu verbessern. Das bedeutet null Laufzeit-Overhead, keine Abhängigkeitskonflikte und volle Transparenz: Sie können jede Anweisung vor der Installation lesen und prüfen.

Kompatibilität

Dieser Skill funktioniert mit jedem KI-Coding-Agenten, der das skills.sh-Format unterstützt, einschließlich Claude Code (Anthropic), Cursor, Windsurf, Cline, Aider und anderen Tools, die projektbezogene Kontextdateien lesen. Skills sind auf Transportebene framework-agnostisch — der Inhalt bestimmt, für welche Sprache oder welches Framework er gilt.

Data sourced from the skills.sh registry and GitHub. Install counts and security audits are updated regularly.