doncheli-api-contract skill

by doncheli·doncheli/don-cheli-sdd·57 stars·Apache-2.0

Design complete API contracts covering endpoints, auth, rate limiting, error handling, retries, circuit breaker and idempotency. Activate when user mentions "api contract", "api design", "endpoint", "webhook", "REST", "GraphQL", "OpenAPI", "design the API".

A100/100content scan

Is the doncheli-api-contract skill safe?

Clean: nothing in its files matched our rules. We read 1 file in the folder on 2026-09-28.

No findings.

Install the doncheli-api-contract skill

A skill is a folder. Copy it into your agent's skills folder and the agent loads it when the task matches its description.

git clone --depth 1 https://github.com/doncheli/don-cheli-sdd.git /tmp/don-cheli-sdd
mkdir -p ~/.claude/skills
cp -r /tmp/don-cheli-sdd/.opencode/skills/doncheli-api-contract ~/.claude/skills/doncheli-api-contract

available in every project

In the Claude apps, zip the folder and upload it from the Skills settings. The folder on GitHub

The instructions your agent would load

SKILL.md as published, without the frontmatter. Read it on GitHub

Don Cheli: API Contract Designer

Instructions

Identify the API style: REST, GraphQL, gRPC, Webhook, or mixed
For each resource/operation, define:

Method + path (REST) or operation name (GraphQL/gRPC)
Request schema: headers, path params, query params, body
Response schemas: success + all error cases

Design cross-cutting concerns:

Auth: mechanism (JWT, OAuth2, API Key, mTLS), scopes, token lifetime
Rate limiting: strategy (token bucket / leaky bucket), limits per tier, headers exposed
Error handling: standard error envelope, HTTP status mapping, error codes catalog
Retries: which operations are safe to retry, backoff strategy, max attempts
Circuit breaker: thresholds, half-open probe, fallback behavior
Idempotency: which operations require idempotency keys, TTL, conflict semantics

Define versioning strategy (URL path, header, or content negotiation)
Flag breaking vs. non-breaking changes policy

Output Format

## API Contract: <service/feature name>

### Style & Version
- Protocol: REST / GraphQL / gRPC / Webhook
- Base URL: …
- Version: v1 (strategy: <path/header/content-negotiation>)

### Endpoints / Operations

#### <METHOD> <path>
**Purpose:** …
**Auth required:** yes/no — scope: …
**Request:**

{ "field": "type — description" }

**Response 200:**

{ … }

**Error responses:**
| Status | Code          | Meaning              |
|--------|---------------|----------------------|
| 400    | INVALID_INPUT | …                    |
| 409    | CONFLICT      | …                    |

**Idempotency:** required / not required — key: <header name>

---

### Cross-Cutting Concerns

**Auth:** …
**Rate Limiting:** X req/min per API key; headers: X-RateLimit-Remaining, X-RateLimit-Reset
**Retry Policy:** safe methods (GET, PUT, DELETE) — exponential backoff, max 3 attempts
**Circuit Breaker:** open at 50% error rate over 10s window; half-open probe after 30s
**Error Envelope:**

{ "error": { "code": "…", "message": "…", "trace_id": "…" } }

### Breaking Change Policy
- Breaking: removing fields, changing types, removing endpoints → requires major version bump
- Non-breaking: adding optional fields, new endpoints → compatible within same version

Quality Gate

Every endpoint must have at least one documented error response
Idempotency policy must be explicit (required or not required) for every mutating operation
Auth scopes must be listed for every endpoint that requires authentication
Rate limit headers must be named consistently across all endpoints

Do not use this skill when

The API already exists and the user wants to review it (use doncheli-review instead)
The user only wants implementation, not contract design (use doncheli-implement instead)

More skills from doncheli/don-cheli-sdd

Adoncheli-api-contractDesign complete API contracts covering endpoints, auth, rate limiting, error handling, retries, circuit breaker and idempotency. Activate when user mentions "api contract", "api design", "endpoint", "webhook", "REST", "GraphQL", "OpenAPI", "design the API".
Adoncheli-audit-trailRecord and query the decision log for a project. Activate when user mentions "audit", "trail", "log decisions", "decision history", "why was this decided", "ADR", "architecture decision".
Adoncheli-audit-trailRecord and query the decision log for a project. Activate when user mentions "audit", "trail", "log decisions", "decision history", "why was this decided", "ADR", "architecture decision".
Adoncheli-changelogAuto-generate CHANGELOG.md entries from git commit history. Activate when user mentions "changelog", "release notes", "what changed", "generate changelog", "CHANGELOG", "release history".
Adoncheli-changelogAuto-generate CHANGELOG.md entries from git commit history. Activate when user mentions "changelog", "release notes", "what changed", "generate changelog", "CHANGELOG", "release history".
Adoncheli-context-healthReport the current state of the context window and recommend compression or cleanup actions. Activate when user mentions "context health", "context window", "how much context", "context full", "running out of context", "compress context".
Adoncheli-context-healthReport the current state of the context window and recommend compression or cleanup actions. Activate when user mentions "context health", "context window", "how much context", "context full", "running out of context", "compress context".
Adoncheli-data-policyAudit and document what personal or sensitive data the project collects, processes, and stores. Activate when user mentions "privacy", "data policy", "what data", "GDPR", "personal data", "data retention", "PII".
Adoncheli-data-policyAudit and document what personal or sensitive data the project collects, processes, and stores. Activate when user mentions "privacy", "data policy", "what data", "GDPR", "personal data", "data retention", "PII".
Adoncheli-debateRun an adversarial multi-role debate to surface trade-offs and reach a reasoned decision. Activate when user mentions "debate", "discuss", "trade-off", "decision", "compare options", "pros and cons", "choose between".
Adoncheli-debateRun an adversarial multi-role debate to surface trade-offs and reach a reasoned decision. Activate when user mentions "debate", "discuss", "trade-off", "decision", "compare options", "pros and cons", "choose between".
Adoncheli-diagramAuto-generate Mermaid or C4 diagrams from code analysis. Activate when user mentions "diagram", "mermaid", "architecture diagram", "C4", "class diagram", "sequence diagram", "ERD", "flowchart", "visualize code".

All agent skills → · MCP servers