api-design

Files (7)

• SKILL.md
• openai.yaml · agents/
• CITATIONS.md · assets/authority/
• authority.yaml · assets/authority/
• OpenAPI-Specification-3.1.0.md · assets/authority/reference-source/openapi-specification/
• source-map.yaml · assets/authority/
• operational-guidance.md · references/

SKILL.md (first lines)

# API Design

## Overview

Produce and evaluate HTTP API contracts that are clear, stable, and aligned with the OpenAPI Specification. This skill covers contract structure, reusable components, versioning, and design conventions.

## When to Use

- Designing a new API contract from requirements.
- Reviewing a contract for spec compliance and consistency.
- Deciding how to version paths, schemas, or security schemes.
- Choosing resource naming, operation semantics, or error response shapes.

Do not use when another more specific skill owns the task.

## Core Pattern

1. Start with the OpenAPI Object, then fill `info`, `servers`, and `paths`.
2. Define reusable schemas, parameters, responses, and security schemes under `components`.
3. Prefer explicit version declarations; keep breaking changes out of patch releases.
4. Use consistent resource naming and HTTP methods; return structured problem details for errors.
5. Reference reusable components with `$ref` to keep the contract DRY.

## Common Mistakes

- Mixing transport, framework, or generator concerns with the contract itself. → Keep the contract independent of implementation.
- Hard-coding repeated schemas instead of using `components/schemas`. → Extract and reference reusable components.
- Changing path semantics without a version bump. → Treat breaking changes as major-version events.
- Treating optional fields as required or missing security scope definitions. → Declare `required` and `security` explicitly.

For detailed guidance, see `references/operational-guidance.md`.

From HarleyBartles/agent-asset-marketplace, MIT.

More from HarleyBartles/agent-asset-marketplace