Stripe Inspired API Design Rules

JSON HTTP API design rules distilled from Stripe — resource modeling, identifier schemes, URL structure, request/response wire format, pagination, errors, idempotency, versioning, naming, webhooks, and authentication. Triggers on tasks involving OpenAPI specs, API design reviews, schema decisions, endpoint shaping, error envelope design, webhook delivery, or any "is this API well-designed" question. Apply when designing, reviewing, or refactoring a JSON HTTP API — even when the user doesn't mention Stripe by name, since the rules are general API-design principles distilled from the industry's

228 stars 19 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pproenca/dot-skills --skill stripe-inspired-api-design-rules
Manual install
git clone --depth 1 https://github.com/pproenca/dot-skills.git /tmp/dot-skills
mkdir -p ~/.claude/skills
cp -r /tmp/dot-skills/skills/.experimental/stripe-inspired-api-design-rules ~/.claude/skills/stripe-inspired-api-design-rules

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# Stripe-Inspired API Design Best Practices

A reference distillation of the design conventions behind Stripe's API — the most widely admired and copied JSON HTTP API in the industry. Contains 52 actionable rules across 8 categories, prioritised by how irreversibly a wrong decision cascades through every endpoint, every SDK, and every client integration. Each rule explains the WHY, shows incorrect-vs-correct code, and links to the canonical source.

## When to Apply

Reach for this skill when:

- Designing a new JSON HTTP API or a new endpoint on an existing one
- Reviewing an API design proposal, OpenAPI spec, or PR that adds/changes endpoints
- Debugging an integration where the "wrong" shape of the API is causing client bugs
- Auditing an API for naming consistency, error shape uniformity, or compatibility risks
- Producing an API design report (the kind your inspector tool emits — `Critical / Warning / Suggestion / Positive`)
- Picking between two designs and looking for an authoritative source to back the choice
- Onboarding to API design — these are the canonical patterns to internalise first

The rules are general — they apply to any JSON HTTP API, not just APIs imitating Stripe. Triggers include "API design", "OpenAPI", "endpoint", "schema", "webhook", "idempotency", "pagination", "API versioning", and reviews of YAML/JSON spec files.

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
Read the full skill on GitHub

Details

Skill name
stripe-inspired-api-design-rules
Path
skills/.experimental/stripe-inspired-api-design-rules/SKILL.md
License
MIT
Repo updated
15 August 2026

FAQ

What does the Stripe Inspired API Design Rules skill do?

JSON HTTP API design rules distilled from Stripe — resource modeling, identifier schemes, URL structure, request/response wire format, pagination, errors, idempotency, versioning, naming, webhooks, and authentication. Triggers on tasks involving OpenAPI specs, API design reviews, schema decisions, endpoint shaping, error envelope design, webhook delivery, or any "is this API well-designed" question. Apply when designing, reviewing, or refactoring a JSON HTTP API — even when the user doesn't mention Stripe by name, since the rules are general API-design principles distilled from the industry's

How do I install the Stripe Inspired API Design Rules skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add pproenca/dot-skills --skill stripe-inspired-api-design-rules. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Stripe Inspired API Design Rules popular?

It lives in pproenca/dot-skills, which has 228 GitHub stars and 19 forks.

Related skills

12 Factor App

228

pproenca/dot-skills

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Software Development19

37signals Rails

228

pproenca/dot-skills

37signals Rails coding principles and conventions from DHH, Jorge Manrubia, and the Fizzy/Basecamp/HEY codebase. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code following the 37signals philosophy — vanilla Rails, CRUD controllers, rich domain models, concerns, no service objects, Hotwire, Turbo, Stimulus, Solid Queue, Solid Cache, Solid Cable, multi-tenancy, Minitest, custom auth, or DHH conventions.

Software Development19

Acceptance Pipeline Catalog

228

pproenca/dot-skills

Use when implementing, reviewing, or debugging a Gherkin acceptance-test pipeline with mutation testing. Covers parser, JSON IR, generator, runtime, step handlers, test runner, mutator, value mutation rules, execution, result classification, reporting, project layout, conformance, and agent setup. Based on Uncle Bob's Acceptance Pipeline Specification. Trigger even when the user mentions Gherkin parsing, acceptance test generation, mutation testing for acceptance tests, or building a portable test pipeline.

Testing & QA19

System Design

191

jwynia/agent-skills

Diagnose design problems and guide architecture decisions for solo developers

Software Development24

Stp Framework

150

guia-matthieu/clawfu-skills

Apply Segmentation, Targeting, and Positioning framework to identify market opportunities and craft differentiated positioning

Software DevelopmentIn 1 list32

Ts Google

228

pproenca/dot-skills

Google TypeScript style guide for writing clean, consistent, type-safe code. This skill should be used when writing, reviewing, or refactoring TypeScript code. Triggers on TypeScript files, type annotations, module imports, class design, and code style decisions.

Software Development19

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.