playbooks

home / skills / shotaiuchi / dotclaude / feature-api

feature-api skill

/dotclaude/skills/feature-api

This skill helps design and implement robust API endpoints, schemas, and versioning across features, ensuring consistency, reliability, and maintainability.

npx playbooks add skill shotaiuchi/dotclaude --skill feature-api

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

Files (1)
SKILL.md
1.8 KB
---
name: feature-api
description: >-
  API design and implementation. Apply when designing endpoints,
  request/response schemas, error handling, versioning, rate limiting,
  and integration contracts for new features.
user-invocable: false
---

# API Designer Implementation

Design and implement API endpoints for new features.

## Implementation Checklist

### Endpoint Design
- Define RESTful resource paths and HTTP methods
- Verify consistent naming conventions across endpoints
- Check for proper use of query parameters vs path parameters
- Ensure idempotency for PUT/DELETE operations
- Validate rate limiting and throttling configuration

### Request/Response Schema
- Define clear request body schemas with required/optional fields
- Ensure response envelopes follow project conventions
- Verify pagination structure for collection endpoints
- Check for consistent date/time formats and data types
- Validate content negotiation headers

### Error Handling
- Define standard error response format with error codes
- Ensure proper HTTP status code usage (4xx vs 5xx)
- Verify descriptive error messages without leaking internals
- Check for consistent error handling across all endpoints
- Validate retry-safe error classifications

### Versioning & Compatibility
- Verify API versioning strategy is applied
- Check backward compatibility with existing clients
- Ensure deprecation notices for changed endpoints
- Validate migration path for breaking changes
- Check integration contract tests with consumers

## Output Format

Report implementation status:

| Status | Description |
|--------|-------------|
| Complete | Fully implemented and verified |
| Partial | Implementation started, needs remaining work |
| Blocked | Cannot proceed due to dependency or decision needed |
| Skipped | Not applicable to this feature |

Overview

This skill helps design and implement HTTP APIs for new features, covering endpoints, schemas, error handling, versioning, and rate limits. It produces a clear implementation status report and actionable checks to ensure compatibility and operability. Use it to validate new API work before release or integration testing.

How this skill works

The skill inspects endpoint design, request and response schemas, error handling, and versioning practices against a checklist of best practices. It verifies naming, parameter usage, idempotency, pagination, content negotiation, and rate limiting, then outputs a status (Complete, Partial, Blocked, Skipped) for each area. It highlights compatibility risks and recommends remediation steps for breaking changes or missing tests.

When to use it

  • Designing new REST endpoints for a feature
  • Reviewing API contracts before integration with consumers
  • Preparing a public API or third-party integration
  • Auditing backward compatibility and versioning plans
  • Assessing error classification and retry behavior

Best practices

  • Use consistent resource naming and HTTP methods aligned with RESTful conventions
  • Distinguish path vs query parameters and document required fields clearly
  • Ensure PUT/DELETE operations are idempotent and document side effects
  • Standardize response envelopes, date/time formats, and pagination structure
  • Define a clear versioning strategy and provide deprecation notices for breaking changes
  • Use structured error codes, appropriate 4xx/5xx status codes, and non-sensitive error messages

Example use cases

  • Designing CRUD endpoints for a new product catalog service with pagination
  • Reviewing an authentication API for consistent error responses and retry-safe classifications
  • Validating a v2 API rollout: compatibility checks and migration path planning
  • Setting rate limits and throttling rules for a high-traffic public endpoint
  • Creating integration contract tests to ensure consumer compatibility before deployment

FAQ

What output does the skill produce?

A concise implementation status report for each checklist area with remediation guidance when issues are found.

How does it handle breaking changes?

It checks for versioning, deprecation notices, and migration paths, and flags breaking changes as Blocked until an agreed plan is provided.