How is the project structure organized?

It follows a 'one file per route' philosophy with co-located tests, ensuring that as your API grows, the codebase remains navigable and maintainable.

How does it handle dependency injection?

It utilizes a Route Factory Pattern where handlers are created via functions that accept dependencies as arguments, allowing for easy mocking and unit testing without global state.

What frameworks does this skill support?

This skill primarily focuses on patterns compatible with @orpc/server and Zod, but the architectural principles regarding thin handlers and dependency injection can be adapted to most TypeScript backend frameworks.

Is error handling standardized?

Absolutely. The skill enforces a consistent JSON error envelope with machine-readable codes, human-readable messages, and correlation IDs (X-Request-ID) for efficient debugging.

Does it include health checks?

Yes, it provides specific implementation patterns for /health (liveness) and /ready (readiness) endpoints to ensure proper traffic routing in containerized environments.

Production-Ready API Design

Name: Production-Ready API Design
Author: jagreehal

byjagreehal

0•

API Development

Builds robust, production-grade HTTP APIs using clean handlers, consistent error envelopes, and operational best practices.

The api-design skill provides Claude with the architectural blueprints and implementation patterns required to build high-quality HTTP APIs. It emphasizes the 'thin handler' principle, separating HTTP concerns from domain logic through dependency injection and route factories. By enforcing standardized error envelopes, health check endpoints, idempotency for mutations, and graceful shutdown procedures, this skill ensures that backend services are not only functional but also operationally excellent and maintainable at scale.

Key Features

01Enforces consistent JSON error envelopes and standard HTTP status mapping

02Adds support for idempotency keys and rate limiting with Retry-After headers

03Implements the Route Factory Pattern with dependency injection for testable handlers

04Configures operational essentials like health/readiness checks and graceful shutdown

05Provides a standardized file organization structure for scalable API routes

060 GitHub stars

Use Cases

01Standardizing error handling and operational monitoring across backend microservices

02Bootstrapping a new TypeScript-based REST or RPC API with @orpc/server

03Refactoring messy controller logic into clean, testable handlers

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add jagreehal/jagreehal-claude-skills api-design

For use in Claude.ai and ChatGPT

Download Skill