Agent skill
openapi-specification
Quellcode ansehen: nickcrew/claude-cortex
Installation
npx skills add nickcrew/claude-cortex --skill openapi-specification67
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 testsPhase 1: API Design
Start with a high-level design before writing the spec:
- Identify resources -- what nouns does this API expose?
- Map operations -- what CRUD and custom actions apply to each resource?
- Define relationships -- how do resources reference each other?
- Plan authentication -- what security schemes are needed?
- 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
$refto reference shared schemas -- never duplicate definitions - Apply
allOffor composition,oneOf/anyOffor polymorphism - Add
examplevalues to every schema and property - Use
requiredarrays explicitly -- don't rely on implicit behavior - Document nullable fields with
type: [string, "null"](3.1) ornullable: 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.yamlCommon 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
$reftocomponents/schemasfor anything reused - Do not mix API versions in a single spec file
- Do not use
200 OKfor create operations -- use201 Created - Do not omit error response schemas -- document
4xxand5xxconsistently - Do not use
additionalProperties: truewithout clear justification
Verwandte Skills
Mehr aus dieser Quelle: nickcrew/claude-cortex
react-performance-optimization
nickcrew/claude-cortex
1.9K installs
owasp-top-10
nickcrew/claude-cortex
760 installs
ui-design-aesthetics
nickcrew/claude-cortex
362 installs
threat-modeling-techniques
nickcrew/claude-cortex
357 installs
token-efficiency
nickcrew/claude-cortex
245 installs
repo-cleanup
nickcrew/claude-cortex
183 installs
So verwenden Sie diesen Skill
- 1
Install openapi-specification by running
npx skills add nickcrew/claude-cortex --skill openapi-specificationin 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
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
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.