Overview
A skill specializing in the design and creation of API specifications compliant with the OpenAPI 3.x specification. Based on RESTful API design principles, it creates secure and highly maintainable API specifications. It comprehensively carries out endpoint design, schema definition, authentication/authorization settings, error handling, and documentation generation.
For detailed procedures and background, refer to the references/ directory.
Workflow
Phase 1: Requirements Definition
Purpose: Clarify the requirements for the API specification
Actions:
references/basics.mdto confirm the basic OpenAPI structure- Define the number of endpoints, authentication method, and rate limits
- Check whether an existing API specification exists (determine whether to update or create new)
Phase 2: Specification Design
Purpose: Design and create the OpenAPI specification
Actions:
agents/design-api.mdto carry out the designassets/openapi-base-template.yamlas a base to create the specificationreferences/schema-design-patterns.mdfor schema designreferences/security-schemes.mdfor security configuration
Task: agents/design-api.md refer to
Phase 3: Validation
Purpose: Validation and recording of the specification
Actions:
agents/validate-spec.mdto carry out validationscripts/validate-openapi.mjsfor syntax checking- Check security settings and best practices
Task: agents/validate-spec.md refer to
Task Specifications (Navigation)
| Task | Start Timing | Input | Output |
|---|---|---|---|
| design-api | At the start of Phase 2 | API requirements | Specification draft |
| validate-spec | At the start of Phase 3 | Specification draft | Validated specification |
Detailed Specifications: For details of each Task, refer to the corresponding file in the agents/ directory
Best Practices
What to Do
- When creating a new OpenAPI specification:
openapi-base-template.yamlas a template and cover all sections: info, servers, paths, and components - When updating an existing OpenAPI specification: Clarify the differences in the specification before and after the change, and verify that there are no breaking changes
- When designing endpoints or schemas:
schema-design-patterns.mdとopenapi-structure.mdto maintain consistency - When resolving OpenAPI syntax errors:
validate-openapi.mjsto identify the specific error location before fixing it - When configuring security schemes:
security-schemes.mdbest practices and apply appropriate authentication to all endpoints - Level-based Learning: Proceed in the order of Basics (Level 1) → Practical (Level 2) → Advanced (Level 3) → Expert (Level 4)
- Version Management: Record the update history of the API specification in CHANGELOG.md and notify users of impacts
Things to Avoid
- Avoid proceeding without checking anti-patterns and cautions
- Do not add security scheme settings after the fact (incorporate them from the design stage)
- Avoid inconsistent schema definitions across multiple endpoints
- Do not skip defining error responses
requiredDo not make field specifications ambiguous- Do not hard-code security-related settings (make them switchable per environment)
- Do not deploy to production while skipping validation of the OpenAPI specification
Resource references
references/ (detailed knowledge)
| Resources | Paths | Purpose |
|---|---|---|
| Basic knowledge | See references/basics.md | OpenAPI basic structure |
| Structure guide | See references/openapi-structure.md | All section specifications |
| Schema Patterns | See references/schema-design-patterns.md | Schema design |
| Security | See references/security-schemes.md | Authentication and authorization settings |
assets/ (Templates)
| Resources | Paths | Purpose |
|---|---|---|
| Base Template | assets/openapi-base-template.yaml |
Specification-based |
| Endpoints | assets/endpoint-template.yaml |
Individual path definitions |
Change history
| Version | Date | Changes |
|---|---|---|
| 1.2.0 | 2026-01-02 | Added agents/, integrated Level structure |
| 1.1.0 | 2025-12-31 | Compliant with the 18-skills.md specification |
| 1.0.0 | 2025-12-24 | Initial implementation |