SKILL.md
$2c
- Collect context — confirm feature name, relevant endpoints, DTOs, auth rules, and edge cases.
- Create/update handoff file — write the document to
.claude/docs/ai/<feature-name>/api-handoff.md. Increment the iteration suffix (-v2,-v3, …) if rerunning after feedback.
- Paste template — fill every section below with concrete data. Omit subsections only when truly not applicable (note why).
- Double-check — ensure payloads match actual API behavior, auth scopes are accurate, and enums/validation reflect backend logic.
Output Format
Produce a single markdown block structured as follows. Keep it dense—no fluff, no repetition.
# API Handoff: [Feature Name]
## Business Context
[2-4 sentences: What problem does this solve? Who uses it? Why does it matter? Include any domain terms the frontend needs to understand.]
## Endpoints
### [METHOD] /path/to/endpoint
- **Purpose**: [1 line: what it does]
- **Auth**: [required role/permission, or "public"]
- **Request**:
```json
{
"field": "type — description, constraints"
}- Response (success):
{
"field": "type — description"
}- Response (error): [HTTP codes and shapes, e.g., 422 validation, 404 not found]
- Notes: [edge cases, rate limits, pagination, sorting, anything non-obvious]
[Repeat for each endpoint]
Data Models / DTOs
[List key models/DTOs the frontend will receive or send. Include field types, nullability, enums, and business meaning.]
// Example shape for frontend typing
interface ExampleDto {
id: number;
status: 'pending' | 'approved' | 'rejected';
createdAt: string; // ISO 8601
}Enums & Constants
[List any enums, status codes, or magic values the frontend needs to know. Include display labels if relevant.]
Value
Meaning
Display Label
pending
Awaiting review
Pending
Validation Rules
[Summarize key validation rules the frontend should mirror for UX—required fields, min/max, formats, conditional rules.]
Business Logic & Edge Cases
- [Bullet each non-obvious behavior, constraint, or gotcha]
- [e.g., "User can only submit once per day", "Soft-deleted items excluded by default"]
Integration Notes
- Recommended flow: [e.g., "Fetch list → select item → submit form → poll for status"]
- Optimistic UI: [safe or not, why]
- Caching: [any cache headers, invalidation triggers]
- Real-time: [websocket events, polling intervals if applicable]
Test Scenarios
[Key scenarios frontend should handle—happy path, errors, edge cases. Use as acceptance criteria or test cases.]
- Happy path: [brief description]
- Validation error: [what triggers it, expected response]
- Not found: [when 404 is returned]
- Permission denied: [when 403 is returned]
Open Questions / TODOs
[Anything unresolved, pending PM decision, or needs frontend input. If none, omit section.]
---
## Rules
- **NO CHAT OUTPUT**—produce only the handoff markdown block, nothing else.
- Be precise: types, constraints, examples—not vague prose.
- Include real example payloads where helpful.
- Surface non-obvious behaviors—don't assume frontend will "just know."
- If backend made trade-offs or assumptions, document them.
- Keep it scannable: headers, tables, bullets, code blocks.
- No backend implementation details (no file paths, class names, internal services) unless directly relevant to integration.
- If something is incomplete or TBD, say so explicitly.
## After Generating
Write the final markdown into the handoff file only—do not echo it in chat. (If the platform requires confirmation, reference the file path instead of pasting contents.)