API Contract

What it does

When your agent uses it

• Asks about API contract
• Api-contract.md
• Shared interface
• TypeScript interfaces

Example prompts

• “API contract”
• “api-contract.md”
• “shared interface”
• “/api-contract”

Requirements

• Compatibility (from SKILL.md): Designed for Claude Code
• Pre-approved tools (allowed-tools): Read

Workflow steps

6 steps, taken from the first numbered list in SKILL.md.

1. 1Create api-contract.md in the sprint directory (.claude/sprint/[N]/api-contract.md). Define each endpoint using the standard format: HTTP…
2. 2Define TypeScript interfaces for all request and response types. Use explicit types instead of any, mark optional fields with ?, and use…
3. 3For list endpoints, include pagination parameters and the PaginatedResponse wrapper. Standardize on page, limit, sort, and order query…
4. 4Document all response states: success (200, 201, 204), client errors (400, 401, 403, 404, 422), and empty states. Use a consistent error…
5. 5Follow best practices from ${CLAUDE_SKILL_DIR}/references/best-practices.md: be specific about field constraints (e.g., "string, required…
6. 6Share the contract file path in SPAWN REQUEST blocks so both backend and frontend agents read the same interface definition.

What it can do on your machine

Read from SKILL.md and the folder at commit 80f86df. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are markdown and typescript).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Designed for Claude Code

  From compatibility in the SKILL.md frontmatter.

Context cost

API Contract loads about 1.4k tokens when it runs, and up to ~5.4k if it reads all its reference files. Until then it costs about 103 tokens; SKILL.md has 441 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~103

When it runs · the whole SKILL.md, loaded when a task matches

~1.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~5.4k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit 80f86df, republished under its MIT licence (© jeremylongshore). 441 words, ~1,439 tokens.

name

api-contract

description

Configure this skill should be used when the user asks about "API contract", "api-contract.md", "shared interface", "TypeScript interfaces", "request response schemas", "endpoint design", or needs guidance on designing contracts that coordinate backend and frontend agents. Use when building or modifying API endpoints. Trigger with phrases like 'create API', 'design endpoint', or 'API scaffold'.

allowed-tools

Read

compatibility

Designed for Claude Code

version

1.20.0

author

Damien Laine <damien.laine@gmail.com>

license

MIT

tags

community, api, typescript

#### POST /auth/register

Create a new user account.

**Request:**
{
  "email": "string (required, valid email)",
  "password": "string (required, min 8 chars)",
  "name": "string (optional)"
}

**Response (201):**  # HTTP 201 Created
{
  "id": "uuid",
  "email": "string",
  "name": "string | null",
  "createdAt": "ISO 8601 datetime"  # 8601 = configured value
}

**Errors:**
- 400: Invalid request body  # HTTP 400 Bad Request
- 409: Email already exists  # HTTP 409 Conflict
- 422: Validation failed  # HTTP 422 Unprocessable Entity

#### GET /products

List products with pagination.

**Query Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| page | integer | 1 | Page number |
| limit | integer | 20 | Items per page (max 100) |
| sort | string | createdAt | Sort field |
| order | string | desc | Sort order (asc/desc) |

**Response (200):**  # HTTP 200 OK
{
  "data": [Product],
  "pagination": { "page": 1, "limit": 20, "total": 150, "totalPages": 8 }
}

interface ApiError {
  code: string;
  message: string;
  details?: Record<string, string[]>;
}

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 6 other files (references) in skills/.curated/api-contract of jeremylongshore/tons-of-skills-marketplace.

• SKILL.md
• references/best-practices.md
• references/errors.md
• references/examples.md
• references/pagination.md
• references/typescript-interfaces.md
• references/writing-endpoints.md

Open the folder on GitHubat commit 80f86df