new-endpoint
Scaffold a new API endpoint following project conventions. Use when asked to add a new endpoint or resource.
SKILL.md.claude/skills/new-endpoint/SKILL.md
GitHubScaffold a complete new endpoint for the resource: $ARGUMENTS
Step 1 — Understand the project stack and conventions
Before creating anything:
- Detect the stack: check
package.json,pyproject.toml,composer.json, etc. - Read 1-2 existing endpoints/routes to understand the project's patterns
- Identify: where routes live, how validation is done, how errors are handled
Rule: zero file creation until patterns are understood.
Step 2 — Scaffold based on stack
Next.js / Node.js
- Route:
app/api/$ARGUMENTS/route.ts(Next.js App Router) orroutes/$ARGUMENTS.ts - Schema/validation: Zod schema for request body
- Handler: validate input → business logic → return response
- Error handling: try/catch with appropriate HTTP status codes
Python (FastAPI)
- Schema:
app/schemas/$ARGUMENTS.py— Create, Update, Response models - Model:
app/models/$ARGUMENTS.py— ORM model if needed - Repository:
app/repositories/$ARGUMENTS.py— DB operations - Service:
app/services/$ARGUMENTS.py— business logic - Router:
app/routers/$ARGUMENTS.py— HTTP layer only - Register in main entry point
Laravel (PHP)
- Model + migration:
php artisan make:model $ARGUMENTS -m - Controller:
php artisan make:controller ${ARGUMENTS}Controller --resource --api - Request:
php artisan make:request Store${ARGUMENTS}Request - Resource:
php artisan make:resource ${ARGUMENTS}Resource - Register routes in
routes/api.php
Step 3 — Standard endpoints to implement
GET /— list (with pagination if applicable)POST /— createGET /{id}— detailPUT /{id}orPATCH /{id}— updateDELETE /{id}— delete
Step 4 — Create tests
Follow the project's existing test patterns. Cover:
- Happy path for each endpoint
- Main error cases (not found, validation failure, unauthorized)
Step 5 — Verify
Run the project's test command (see run-tests skill) and confirm the new endpoint works.
$ARGUMENTS