playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / api-contract

api-contract skill

/plugins/community/sprint/skills/api-contract

This skill helps design and validate API contracts guiding backend and frontend teams through type-safe interfaces and endpoint schemas.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill api-contract

Review the files below or copy the command above to add this skill to your agents.

Files (7)
SKILL.md
1.2 KB
---
name: api-contract
description: |
  Configure this skill should be used when the user asks about "API contract", "api-contract.md", "shared interface", "TypeScript interfaces", "request response schemas", "endpoint design", or needs guidance on designing contracts that coordinate backend and frontend agents. Use when building or modifying API endpoints. Trigger with phrases like 'create API', 'design endpoint', or 'API scaffold'.
allowed-tools: Read
version: 1.0.0
author: Damien Laine <[email protected]>
license: MIT
---

# Api Contract

## Overview

This skill provides automated assistance for the described functionality.

## Prerequisites

- Appropriate file access permissions
- Required dependencies installed

## Instructions

1. Invoke this skill when the trigger conditions are met
2. Provide necessary context and parameters
3. Review the generated output
4. Apply modifications as needed

## Output

The skill produces structured output relevant to the task.

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources

- Project documentation
- Related skills and commands

Overview

This skill helps design and validate API contracts that coordinate backend and frontend agents. It guides creation of clear endpoint definitions, request/response schemas, and TypeScript interfaces. Use it to generate consistent, versioned contracts that reduce integration errors.

How this skill works

The skill inspects described endpoints, parameters, and data shapes to produce structured contract artifacts: OpenAPI snippets, JSON Schema, and TypeScript interfaces. It validates consistency across request and response models, flags breaking changes, and can suggest versioning or migration notes. Output is human-readable and machine-usable for scaffolding code or generating mocks.

When to use it

  • Design new endpoints that will be consumed by multiple clients
  • Refactor or version existing APIs to avoid breaking clients
  • Generate TypeScript interfaces from backend models or schemas
  • Create request and response schemas for automated tests and mocks
  • Document shared interfaces between frontend and backend teams

Best practices

  • Keep request payloads minimal and explicit; avoid sending server-only fields from clients
  • Use consistent naming conventions and explicit types across schemas and interfaces
  • Version breaking changes and include migration guidance in the contract
  • Prefer JSON Schema or OpenAPI fragments for machine validation and TypeScript for client codegen
  • Validate contracts with example payloads and automated tests before release

Example use cases

  • Create an OpenAPI fragment and matching TypeScript interfaces for a new /orders endpoint
  • Generate JSON Schema for request validation and a response shape with nullable fields handled explicitly
  • Detect a breaking change when renaming a field and produce a migration plan with deprecation warnings
  • Scaffold mock data and TypeScript types to enable frontend development before backend implementation is ready
  • Produce endpoint examples and validation rules to feed into CI checks and API gateways

FAQ

Can this skill generate both OpenAPI and TypeScript output?

Yes. It can produce OpenAPI/JSON Schema snippets and corresponding TypeScript interfaces to keep runtime validation and client types synchronized.

How does it handle backward-incompatible changes?

It flags potential breaking changes, recommends version bumps or deprecation paths, and can generate migration notes and compatibility shims.

What inputs does it need to produce a contract?

Provide endpoint path, HTTP method, parameter descriptions, example payloads, and desired response shapes. Optionally include existing models or type hints for translation.