skills.rest
richardthe3rd
richardthe3rdCOMMUNITY
Explore all skills by this author →
GitHub

api-contract

Enforce proto-first API contract workflows for the Cambridge Beer Festival app.

2|3|Updated Nov 28, 2025
Search Tags:#openapi#api-design#api-contract#aip#proto#buf#cloudflare-worker
One-click install
npx skills add https://github.com/richardthe3rd/cambridge-beer-festival-app --skill api-contract-richardthe3rd
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-contract
Source: https://github.com/richardthe3rd/cambridge-beer-festival-app/tree/main/.claude/skills/api-contract
Command: npx skills add https://github.com/richardthe3rd/cambridge-beer-festival-app --skill api-contract-richardthe3rd

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill eliminates the risk of inconsistent, broken API contracts for the Cambridge Beer Festival app by enforcing a strict proto-first workflow, where Protocol Buffer (proto) definitions are the single source of truth for all API surfaces, preventing accidental drift between the contract, generated artifacts, and deployed Cloudflare Worker implementation.

Core Features & Use Cases

  • Proto-first workflow enforcement: Provides the exact ordered command sequence for formatting, linting, API linting, and generating OpenAPI specs and client code after any proto change, plus documents CI gate behavior and sandbox limitations for proto tasks.
  • AIP guideline defence: Includes a canonical AIP known-facts table with concrete evidence from the repo's own contract to resist incorrect automated review suggestions (e.g., duplicate etag fields, wrong soft-delete return types, incorrect parent annotations).
  • Contract drift tracking: Explicitly documents the gap between the current proto contract (DrinkEntry/DrinkSummary) and the deployed worker's older Review/ReviewSummary surface, plus rules for evolving the contract without breaking existing clients.
  • Use Case: If an automated review comment claims an API change requires adding a duplicate etag request field, use this Skill to verify the AIP-154 rule that etag is OUTPUT_ONLY and the correct fix is documenting If-Match support, not adding a redundant request field.

Quick Start

Use the api-contract skill to validate a proposed API change against AIP guidelines and the repo's contract rules before editing any proto files or responding to automated review comments.

Frequently Asked Questions about api-contract

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

FAQPage Schema
How do I enforce a proto-first workflow to prevent breaking API contracts?▼

A proto-first workflow ensures Protocol Buffer definitions act as the single source of truth for all REST API surfaces, preventing drift by enforcing an ordered sequence of formatting, linting, and generating OpenAPI specs before implementation.

How do I validate AIP guideline compliance against automated API review comments?▼

Validating AIP compliance involves checking automated review suggestions against a canonical known-facts table, resisting incorrect claims like duplicate etag fields by verifying rules such as AIP-154 where etag is OUTPUT_ONLY.

What is the best way to track contract drift between proto definitions and a deployed Cloudflare Worker?▼

Tracking contract drift involves explicitly documenting the gap between current proto definitions and the deployed worker's older API surfaces, applying rules to evolve the contract safely without breaking existing clients.

Can I use buf to generate OpenAPI specs and client code after modifying proto files?▼

Yes, you can use buf to generate OpenAPI specs and client code by following an exact ordered command sequence for formatting, linting, API linting, and generation after any proto file modification.

Why does my automated review comment claim I need a duplicate etag request field?▼

Automated review comments often incorrectly claim a duplicate etag field is needed; however, AIP-154 dictates etag is OUTPUT_ONLY, meaning the correct fix is documenting If-Match support rather than adding a redundant request field.

How do I safely evolve a proto API contract without breaking existing clients?▼

Safely evolving a proto API contract requires applying specific rules for non-breaking changes, ensuring generated artifacts are never hand-edited, and maintaining the proto definitions as the canonical source of truth.

Related Skills

Explore More Software Engineering Skills→
Manu343726Manu343726

protobuf

Guide proto design, validation, and buf-based verification workflows.

Community
Intermediate
ralvarezdevralvarezdev
3

api-contract-reviewer

Assesses REST and gRPC contracts for breaking changes and drift using architectural rules.

Community
Advanced
gabriellpequenogabriellpequeno
8

web-design-guidelines

Enforce external UI guideline compliance during front-end design reviews and critiques.

Community
Basic
mescamesca

spec-driven

Align OpenAPI/OpenRPC contracts with Pydantic models and services.

Community
Intermediate