api-contract

Writes and maintains API, event, and type contracts in board/contracts for parallel team development.

Updated Aug 23, 2026
One-click install
npx skills add https://github.com/vinodkrishna221/Q-Trace --skill api-contract-vinodkrishna221
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: api-contract
Source: https://github.com/vinodkrishna221/Q-Trace/tree/main/.agents/skills/api-contract
Command: npx skills add https://github.com/vinodkrishna221/Q-Trace --skill api-contract-vinodkrishna221

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Teams building frontend and backend in parallel often suffer from silent contract drift, where API shapes diverge between sides and cause expensive integration failures. This Skill defines a single shared contract surface so every track codes against the same agreed shapes. ## Core Features & Use Cases - Contract Authoring: Creates one contract file per resource domain in board/contracts/ with request/response shapes, error shapes, shared types, and event payloads. - Schema Mirroring: Keeps zod or pydantic models derived from the contract file so the compiler catches drift instead of humans. - Change Ritual: Enforces a mandatory four-step process (edit contract, bump version, log in DECISIONS.md, notify consumers) before any code changes. - Use Case: When a backend developer needs to add a field to the scoring endpoint, they update the contract file, bump its version, record the decision, and notify consumers before touching implementation code. ## Quick Start Ask the AI to draft an API contract for a new resource domain following the template in .agents/templates/api-contract.md and place it in board/contracts/.

Frequently Asked Questions about api-contract

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

FAQPage Schema
How do I write an API contract for parallel frontend and backend development?

Create one markdown contract file per resource domain listing each endpoint's method, path, request and response shapes with types and examples, plus error shapes. Both sides then mirror the contract in zod or pydantic so the compiler detects drift.

What should an API contract file contain?

A contract file contains the domain name and version, owner and consumers, endpoint request and response shapes with typed fields and examples, error shapes, shared type definitions, and event payloads. Every field needs a type plus an example, with IDs as strings and dates as ISO-8601.

How do I change an API contract without breaking consumers?

Follow the change ritual: edit the contract file and bump its version, add a three-line entry to DECISIONS.md, notify all listed consumers, and only then change the code on both sides in the same working session.

Does this contract approach work with Convex projects?

Yes. For Convex projects, the exported function signatures in the convex/ directory are the contract themselves, so the contract file only needs to list shared types and events rather than duplicating endpoint definitions.

Why does silent contract drift break hackathon projects?

Silent drift happens when one side changes API shapes without updating the shared contract, so integration fails late when fixes are expensive. Versioned contract files plus mirrored schemas let the compiler and reviewers catch mismatches immediately.