Help us improve
Share bugs, ideas, or general feedback.
From navigator
Generates production-ready REST or GraphQL API endpoints with request validation, error handling, and tests. Supports Express, Fastify, NestJS, and Next.js App Router.
npx claudepluginhub alekspetrov/navigator --plugin navigatorHow this skill is triggered — by the user, by Claude, or both
Slash command
/navigator:backend-endpointThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate production-ready REST or GraphQL endpoints with request validation, error handling, and comprehensive tests.
Builds production-ready REST API endpoints with input validation, authentication checks, error handling, business logic, and documentation for Express and Fastify. Useful for creating CRUD operations and backend routes.
Designs RESTful API routes with Next.js App Router, Zod validation, auth guards, and typed responses. Activates when discussing API endpoints, route structure, or request/response schemas.
Generates RESTful API endpoints with routes, request validation, error handling, and CRUD operations. Supports FastAPI, Flask, Django, Express, NestJS, Hono; auto-detects stack or recommends one.
Share bugs, ideas, or general feedback.
Generate production-ready REST or GraphQL endpoints with request validation, error handling, and comprehensive tests.
Auto-invoke when user mentions:
Before gathering requirements, query the knowledge graph for what we already know about API/endpoint work in this project. Mirrors navigator-research's Phase 0.
python3 skills/nav-graph/functions/graph_manager.py \
--action query --concept api \
--graph-path .agent/knowledge/graph.json 2>/dev/null | head -40
Also check authentication, validation, and security if the endpoint touches those areas.
If memories surface (PATTERN, PITFALL, DECISION entries), read the full memory files for relevant ones:
ls .agent/knowledge/memories/{patterns,pitfalls,decisions}/ 2>/dev/null
What to do with what you find:
pitfalls_avoided in Step 8)If the graph returns nothing useful, proceed without it. Skip this step only if the knowledge graph is disabled in .agent/.nav-config.json.
Ask user for endpoint details:
Endpoint path: [e.g., /api/users/:id]
HTTP method: [GET, POST, PUT, PATCH, DELETE]
Resource name: [e.g., User, Post, Product]
Framework:
- express (default)
- fastify
- nestjs
- nextjs (App Router Route Handler — app/api/<resource>/route.ts)
- graphql
Authentication required: [yes/no]
Request validation needed: [yes/no]
Validate endpoint path:
functions/route_validator.pyIMPORTANT: This step MUST be executed for high-stakes operations.
Before generating code, confirm interpretation with user.
Display verification:
I understood you want:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Endpoint: {METHOD} {PATH}
Resource: {RESOURCE_NAME}
Framework: {FRAMEWORK} (detected from package.json / specified)
Auth required: {yes/no}
Validation needed: {yes/no}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Assumptions I'm making:
- Using {VALIDATION_LIBRARY} for validation (detected from existing validators)
- Error handling follows existing pattern in {ERROR_HANDLER_PATH}
- Route will be registered at {ROUTE_PREFIX} prefix
Proceed with generation? [Y/n]
Skip verification if (HIGH-STAKES ONLY mode):
Always verify if:
/users/:userId/posts/:postId)Before generating code, optionally declare explicit assumptions (enabled by tom_features.belief_anchors in config).
Display belief state anchor:
📌 BELIEF STATE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
What I know (from context):
✅ Framework: {FRAMEWORK} (from package.json)
✅ TypeScript: {strict/normal} mode (from tsconfig.json)
✅ Validation: {LIBRARY} (from existing validators/)
What I'm assuming (inference):
🔸 Error handler follows pattern in {PATH}
🔸 Routes registered at {PREFIX} prefix
🔸 Using {CONVENTION} commit messages
What I don't know (using defaults):
❓ Request logging preference (will include)
❓ Rate limiting requirements (will skip)
❓ Response envelope format (will use standard)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Adjustments needed before I proceed?
Skip belief anchor if:
tom_features.belief_anchors is false in configShow belief anchor if:
Based on HTTP method and framework:
Use predefined function: functions/endpoint_generator.py
python3 functions/endpoint_generator.py \
--path "/api/users/:id" \
--method "GET" \
--resource "User" \
--framework "express" \
--auth true \
--validation true \
--template "templates/express-route-template.ts" \
--output "src/routes/users.ts"
Template includes:
Use predefined function: functions/validation_generator.py
python3 functions/validation_generator.py \
--resource "User" \
--method "POST" \
--fields "name:string:required,email:email:required,age:number:optional" \
--library "zod" \
--output "src/validators/user.validator.ts"
Supported validation libraries:
Output example (Zod):
import { z } from 'zod';
export const createUserSchema = z.object({
name: z.string().min(1),
email: z.string().email(),
age: z.number().optional(),
});
export type CreateUserInput = z.infer<typeof createUserSchema>;
Use predefined function: functions/error_handler_generator.py
python3 functions/error_handler_generator.py \
--framework "express" \
--template "templates/error-handler-template.ts" \
--output "src/middleware/errorHandler.ts"
Error handler includes:
Use predefined function: functions/test_generator.py
python3 functions/test_generator.py \
--endpoint "/api/users/:id" \
--method "GET" \
--framework "express" \
--template "templates/endpoint-test-template.spec.ts" \
--output "tests/routes/users.test.ts"
Test template includes:
Example test:
describe('GET /api/users/:id', () => {
it('returns user when found', async () => {
const response = await request(app)
.get('/api/users/123')
.expect(200);
expect(response.body).toMatchObject({
id: '123',
name: expect.any(String),
});
});
it('returns 404 when user not found', async () => {
await request(app)
.get('/api/users/999')
.expect(404);
});
});
JSDoc or OpenAPI annotation:
/**
* @route GET /api/users/:id
* @description Get user by ID
* @access Private
* @param {string} id - User ID
* @returns {User} User object
* @throws {404} User not found
* @throws {401} Unauthorized
*/
Display generated files and usage:
✅ Endpoint Created: GET /api/users/:id
Structure:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📁 src/
├── routes/users.ts (Route handler)
├── validators/user.validator.ts (Request validation)
└── middleware/errorHandler.ts (Error handling)
📁 tests/
└── routes/users.test.ts (Integration tests)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Route Registration:
import { userRoutes } from './routes/users';
app.use('/api', userRoutes);
Test:
curl http://localhost:3000/api/users/123
# or
npm test -- users.test.ts
Next Steps:
1. Implement business logic in controller
2. Connect to database/service layer
3. Run tests: npm test
4. Test with Postman/Thunder Client
After Step 7, emit an execution_summary JSON block. This is the parity equivalent of the research_findings block emitted by navigator-research, ingested into the knowledge graph so future endpoint work can surface what we learned.
Output the block verbatim (replace placeholders with actual values):
{
"execution_summary": {
"skill": "backend-endpoint",
"task": "{METHOD} {PATH}",
"files_created": ["{route, validator, test paths}"],
"files_modified": ["{router registration paths}"],
"tests_added": ["{test file path}"],
"stack_detected": "{e.g. express+typescript+zod}",
"patterns_followed": [
{"summary": "{convention applied — e.g. Zod schema for request validation}", "concepts": ["api"], "confidence": 0.8}
],
"decisions_made": [
{"summary": "{non-obvious choice — e.g. 404 over 422 because resource itself missing}", "concepts": ["api"], "confidence": 0.75, "evidence": "{path:line}"}
],
"pitfalls_avoided": [
{"summary": "{gotcha that future agents should know — e.g. middleware order matters: auth before validator}", "concepts": ["api"], "confidence": 0.85}
],
"assumptions_made": ["{e.g. project uses Express middleware pattern (detected via package.json)}"]
}
}
Ingestion (run from project root):
echo '<execution_summary JSON>' | python3 skills/nav-graph/functions/execution_to_graph.py -
Rules:
Validates route path follows REST conventions.
Usage:
python3 functions/route_validator.py --path "/api/users/:id" --method "GET"
Checks:
:id or {id})Returns: Valid path or error message
Generates endpoint handler from template.
Usage:
python3 functions/endpoint_generator.py \
--path "/api/users/:id" \
--method "GET" \
--resource "User" \
--framework "express" \
--auth true \
--validation true \
--template "templates/express-route-template.ts"
Parameters:
--path: API endpoint path--method: HTTP method--resource: Resource name (singular, PascalCase)--framework: Backend framework--auth: Include auth middleware--validation: Include validation middleware--template: Template file pathReturns: Generated endpoint code
Generates request validation schema.
Usage:
python3 functions/validation_generator.py \
--resource "User" \
--method "POST" \
--fields "name:string:required,email:email:required" \
--library "zod"
Supported field types:
string, number, booleanemail, url, uuidarray, objectdate, datetimeReturns: Validation schema code
Generates error handling middleware.
Usage:
python3 functions/error_handler_generator.py \
--framework "express" \
--template "templates/error-handler-template.ts"
Returns: Error handler middleware code
Generates endpoint integration tests.
Usage:
python3 functions/test_generator.py \
--endpoint "/api/users/:id" \
--method "GET" \
--framework "express" \
--template "templates/endpoint-test-template.spec.ts"
Generates tests for:
Returns: Generated test code
Express.js route handler template.
Placeholders:
${ROUTE_PATH} - API endpoint path${HTTP_METHOD} - HTTP method (lowercase)${RESOURCE_NAME} - Resource name (PascalCase)${VALIDATION_MIDDLEWARE} - Validation middleware${AUTH_MIDDLEWARE} - Authentication middlewareNext.js App Router Route Handler for a collection endpoint — no dynamic segment.
When to use: package.json has "next" in deps and the path has no [id]. Output path: app/api/<resource>/route.ts. Exports GET (list) + POST (create).
Next.js App Router Route Handler for a single resource endpoint with a dynamic segment.
When to use: path includes [id] (or similar). Output path: app/api/<resource>/[id]/route.ts. Exports GET (read), PATCH (update), DELETE.
Picking between them:
POST /api/favourites → collection templateGET /api/favourites/[id] → dynamic templateBoth templates encode Next.js 15+/16 conventions:
params is a Promise<…> — await it (Next.js 15+ change), only on dynamicPromise<{}> from the file path)NextResponse.json(...) with explicit status codes.agent/philosophy/NEXTJS-PATTERNS.md §E, §HPrefer Server Actions over Route Handlers for mutations from your own UI (forms, buttons). Use Route Handlers for webhooks, third-party callers, and public REST endpoints. See NEXTJS-PATTERNS.md §F.
Fastify route handler template (alternative).
GraphQL resolver template (alternative).
Zod validation schema template.
Integration test template with supertest.
Placeholders:
${ENDPOINT_PATH} - Endpoint to test${HTTP_METHOD} - HTTP method${TEST_CASES} - Generated test casesSee examples/ directory for reference implementations:
Each example includes:
/users, not /user)/users/:userId/posts/:postId)Problem: Endpoint returns 404 even though route is defined
Solutions:
Problem: Valid requests fail validation
Solutions:
Problem: Integration tests don't pass
Solutions:
--verbose flagThis skill succeeds when:
Auto-invoke this skill when creating API endpoints to ensure consistency and security 🔒