跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
浏览器与自动化

create-handler

Create a new API handler following the handler pattern. Use when the user asks to create an endpoint, handler, or route.

girijashankarj · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add girijashankarj/cursor-handbook --skill create-handler

技能说明


name: create-handler description: Create a new API handler following the handler pattern. Use when the user asks to create an endpoint, handler, or route.

Skill: Create API Handler

Step-by-step workflow for creating a new API handler following the {{CONFIG.patterns.handlerFlowSteps}}-step handler pattern.

Scripts (Cursor skills scripts/ support)

This skill includes a scripts/ folder. The agent can run these scripts as part of the workflow:

  • scripts/scaffold-handler-dirs.sh — Creates the handler directory structure. Usage: ./scripts/scaffold-handler-dirs.sh <entity> <operation> (e.g. order create).

Trigger

When the user asks to create a new API endpoint, handler, or route.

Prerequisites

  • Project configuration loaded ({{CONFIG.paths.handlerBasePath}} exists)
  • Understanding of the entity and operation

Steps

Step 1: Gather Requirements

  • Identify the entity (e.g., Order, Product, User)
  • Identify the operation (e.g., create, read, update, list, delete)
  • Determine HTTP method and URL path
  • Identify request parameters and body schema
  • Identify response format

Step 2: Create Directory Structure

mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/logic
mkdir -p {{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/schemas

Expected structure:

{{CONFIG.paths.handlerBasePath}}/{entity}/{operation}/
├── {{CONFIG.fileNames.handlerEntry}}
├── logic/
│   ├── validate-request.ts
│   ├── validate-business.ts
│   ├── pre-processing.ts
│   ├── operation.ts
│   ├── post-operation.ts
│   └── response.ts
└── schemas/
    ├── {{CONFIG.fileNames.requestSchema}}
    └── {{CONFIG.fileNames.responseSchema}}

Step 3: Create Request Schema

  • Define JSON Schema in schemas/{{CONFIG.fileNames.requestSchema}}
  • Include all required and optional fields
  • Add type validation and constraints
  • Add description for each field

Step 4: Create Response Schema

  • Define JSON Schema in schemas/{{CONFIG.fileNames.responseSchema}}
  • Follow response envelope pattern: { data, meta }
  • Include all response fields with types

Step 5: Implement Logic Steps

For each file in logic/:

  • validate-request.ts — Validate request against schema
  • validate-business.ts — Check business rules and entity state
  • pre-processing.ts — Transform and enrich data
  • operation.ts — Execute core business logic
  • post-operation.ts — Trigger side effects (events, notifications)
  • response.ts — Format response with envelope

Step 6: Create Handler Entry Point

  • Import all logic steps
  • Wire up the {{CONFIG.patterns.handlerFlowSteps}}-step flow
  • Add error handling with try/catch
  • Add structured logging with correlationId
  • Export handler function

Step 7: Register Route

  • Add route in the appropriate router file
  • Apply authentication middleware
  • Apply rate limiting if needed

Step 8: Add Tests

  • Create test file: {entity}/{operation}/__tests__/handler.test.ts
  • Test each logic step independently
  • Test handler integration (success path)
  • Test error cases (validation, business, not found)
  • Verify {{CONFIG.testing.coverageMinimum}}% coverage

Step 9: Validate

  • Run type check: {{CONFIG.testing.typeCheckCommand}}
  • Run tests for the new handler only
  • Verify schemas match implementation

Completion

Handler is created, tested, and type-checked. Ready for code review.

If a step fails

  • Step 2 (directory): Ensure {{CONFIG.paths.handlerBasePath}} exists. Run mkdir -p from project root.
  • Step 3–4 (schemas): If schema validation fails, check JSON Schema syntax. Use a minimal schema first.
  • Step 5 (logic): If imports fail, verify paths match {{CONFIG.paths.commonPath}} and handler structure.
  • Step 8 (tests): If tests fail, run {{CONFIG.testing.typeCheckCommand}} first. Fix type errors before test logic.
  • Step 9 (validate): If type-check fails, fix reported errors before proceeding. Do not skip validation.