skills.rest
wso2
wso2OFFICIAL
Explore all skills by this author →
WebsiteGitHub

api-design

Design, assess, and fix OpenAPI specifications for agent readiness, security, and design quality.

6|11|Updated Apr 20, 2026
Search Tags:#OWASP#api design#openapi#REST API#spectral#agent readiness#wso2
One-click install
npx skills add https://github.com/wso2/agent-skills --skill api-design-wso2
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design
Source: https://github.com/wso2/agent-skills/tree/main/plugins/api-platform/skills/api-design
Command: npx skills add https://github.com/wso2/agent-skills --skill api-design-wso2

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @stoplight/spectral-cli, and includes scripts (resource) and references (resource) and assets (resource) components.

What problem does it solve? Teams building REST APIs struggle to produce OpenAPI specs that follow design guidelines, pass security checks, and work reliably with AI agents, and fixing issues found in existing specs is slow manual work. ## Core Features & Use Cases - Guided Spec Design: Walks through a conversation-driven 7-step process grounded in WSO2 REST API Design Guidelines to generate a production-quality OpenAPI 3.x YAML spec from scratch. - Multi-Dimension Assessment: Runs Spectral-based checks across AI Agent Readiness (69 rules plus 11 LLM analysis categories), OWASP-derived Security Readiness, and WSO2 API Design Guidelines, producing JSON and self-contained HTML reports with severity-ranked scores. - Automated Fixing: Applies safe structural fixes in place, warns before breaking path renames, and generates missing descriptions, summaries, and examples with user confirmation. - Use Case: Share an existing openapi.yaml and ask for a full assessment; receive a scored HTML report listing critical issues like missing operationIds, then apply all autoFixable fixes with one follow-up command. ## Quick Start Ask the assistant to design an OpenAPI spec for your service, or share a spec file path and ask it to assess the spec for agent readiness, security, and design quality.

Frequently Asked Questions about api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I design an OpenAPI spec from scratch with AI?▼

Describe your service in a sentence or two and the skill guides you through domain understanding, data modeling, resource derivation, and outline confirmation before generating a complete OpenAPI 3.x YAML file following WSO2 REST design guidelines.

How do I check an OpenAPI spec for AI agent readiness?▼

Share the spec file path and request an agent readiness assessment. The skill runs 69 Spectral rules plus an LLM analysis across 11 guideline categories covering operationIds, descriptions, error responses, and workflow expressibility, then produces a scored report.

Does the OpenAPI assessment require Spectral CLI?▼

Yes, the Spectral CLI must be installed and on PATH before any assessment runs. Install it with npm install -g @stoplight/spectral-cli; the skill verifies availability with spectral --version before proceeding.

Can it automatically fix issues found in an OpenAPI spec?▼

Yes, fixes are applied in place to the spec file. AutoFixable structural issues are edited directly, path-renaming fixes require explicit confirmation since they break existing clients, and missing descriptions or examples are generated from spec context.

What security checks does the OpenAPI assessment run?▼

The security dimension runs OWASP-derived Spectral rules against the spec, checking authentication schemes, authorization coverage on mutating operations, and related API security top-10 concerns, with results merged into the same JSON and HTML report.

Why does the assessment report show low scores for my spec?▼

Scores are computed per dimension from the worst-severity penalty of each violated rule, so CRITICAL issues like missing operationIds or interactive OAuth flows lower scores quickly. The report lists each issue with a fixSuggestion you can apply.

Related Skills

Explore More Software Engineering Skills→
NAICNONAICNO

waldur-api

Retrieve Waldur OpenAPI endpoints, schemas, and operation details from waldur-openapi.json.

Official
Advanced
HouseGarofaloHouseGarofalo
3

azure-api-management

Configure and manage API gateways with Azure API Management services.

Official
Advanced
superluminar-iosuperluminar-io
10

api-mock-server

Generate HTTP and gRPC mock servers and clients from pinky-promise API specs.

Official
Intermediate
schalappeschalappe

openapi-spec-generation

Generate and maintain OpenAPI 3.1 specifications with validation and SDK generation.

Community
Advanced