KeiSeiKit-1.0/skills/quick-api/SKILL.md

name	description	disable-model-invocation	arguments
quick-api	Use when scaffolding a new API endpoint — types, test, handler, validation, route, docs	true	name description required endpoint Endpoint description, e.g. 'POST /api/users — create user' true

Quick API Scaffold Workflow

Step 1: Detect Framework

• Auto-detect from project:
  • Python: FastAPI (main.py, routers/), Flask, Django
  • JS/TS: Next.js (app/api/), Express, Hono
  • Go: net/http, gin, echo
• Find existing endpoint examples to match patterns

Step 2: API Contract (Types First)

• Define request/response types BEFORE implementation
• Place types where project keeps them (types/, schemas/, models/)
• Include validation rules in type definitions
• Document in OpenAPI format if project uses it

Step 3: Write Test First

• Create test file matching project conventions
• Test cases:
  • Happy path (valid request → expected response)
  • Validation error (invalid input → 400/422)
  • Auth error if endpoint requires auth (no token → 401)
  • Not found if applicable (→ 404)

Step 4: Checkpoint

• checkpoint: before quick-api $endpoint

Step 5: Implement Handler

• Follow existing handler patterns exactly
• Input validation using project's validation approach
• Error handling matching existing patterns
• Keep handler thin — business logic in service layer if project uses one

Step 6: Register Route

• Add route in the project's routing configuration
• Match URL pattern, middleware, and auth guards from existing routes

Step 7: Verify

• Run tests — all pass
• Test manually with curl if appropriate
• Check that OpenAPI/Swagger docs update if auto-generated

Step 8: Commit

• feat: add $endpoint endpoint