governing-component-reuse

What problem does it solve?

This Skill addresses the maintenance nightmares and silent divergence caused by duplicated or inconsistently managed OpenAPI component definitions, ensuring DRY principles are applied at the specification level.

Core Features & Use Cases

• Component Extraction & Referencing: Guides the extraction of reusable schemas, responses, and parameters into the components section and their subsequent referencing using $ref.
• Inline Schema Auditing: Identifies and provides rules for when inline schemas are acceptable versus when they must be extracted to prevent duplication and SDK generation issues.
• Schema Composition Governance: Enforces best practices for allOf, oneOf (with discriminator), and anyOf to ensure clarity, maintainability, and compatibility with code generation tools.
• RFC 9457 ProblemDetails: Promotes the use of a standardized, reusable error schema for consistent API error handling.
• Use Case: When reviewing an OpenAPI specification, use this Skill to audit the usage of $ref, identify inline schemas that should be components, and ensure that polymorphic types (oneOf) are correctly implemented with discriminators.

Quick Start

Use the governing-component-reuse skill to audit the OpenAPI specification for inline schema anti-patterns and ensure all response bodies are defined as reusable components.