SKILL.md Format Guide: Writing Effective Claude Code Skills

# Write API Endpoint
# ^ H1: skill name — verb-noun, ≤5 words

## Description
# ^ Tell Claude WHEN to use this skill
Use this skill when asked to create a new REST API endpoint, route handler, or controller.
Applies to: Express/Fastify routes, Next.js API routes, tRPC procedures.
Do NOT use for: GraphQL resolvers (use write-resolver skill instead).

## Context
# ^ Project-specific facts + @imported current state
- API framework: Fastify 4.x
- Auth middleware: `src/middleware/auth.ts` — attach as preHandler
- Validation: Zod schemas in `src/schemas/`
- Error responses: use `reply.sendError()` from `src/utils/errors.ts`
- Route files: `src/routes/[resource].ts`

@src/utils/errors.ts
@src/middleware/auth.ts

## Instructions
# ^ Numbered steps — be explicit about files, commands, checks
1. Identify the resource and HTTP method from the request
2. Create or open `src/routes/[resource].ts`
3. Define a Zod schema for request body/params in `src/schemas/[resource].ts`
4. Write the route handler with:
   - Auth preHandler (unless public route — confirm with user)
   - Zod validation of request body/params
   - Business logic or service call
   - Typed response using `reply.send()`
5. Register the route in `src/app.ts`
6. Write a unit test in `src/routes/[resource].test.ts`
7. Run `pnpm test routes/[resource]` and `pnpm typecheck` to verify

## Rules
# ^ Explicit prohibitions — most important constraints
- NEVER skip auth middleware on non-public routes
- NEVER inline business logic — call a service or repository function
- NEVER return raw database errors — map them to HTTP responses
- ALWAYS include a test for at least the happy path and a 400 case

## Examples
# ^ Input/output pairs — show real code

### Example: GET /api/users/:id

Route file (`src/routes/users.ts`):
```typescript
import { FastifyPluginAsync } from 'fastify'
import { z } from 'zod'
import { getUserById } from '../services/users'
import { requireAuth } from '../middleware/auth'

const ParamsSchema = z.object({
  id: z.string().cuid(),
})

const usersRoutes: FastifyPluginAsync = async (fastify) => {
  fastify.get<{ Params: z.infer<typeof ParamsSchema> }>(
    '/users/:id',
    { preHandler: [requireAuth] },
    async (request, reply) => {
      const { id } = ParamsSchema.parse(request.params)
      const user = await getUserById(id)
      if (!user) return reply.sendError(404, 'User not found')
      return reply.send(user)
    }
  )
}

export default usersRoutes
```

# Before committing a skill, verify:

## Description quality
- [ ] Reads like 'Use when [specific condition]'
- [ ] Has 'Do NOT use for' if there are common misapplications
- [ ] Specific enough that a different skill wouldn't match the same task

## Instructions quality  
- [ ] All steps are numbered
- [ ] File paths are explicit (not 'the route file' but 'src/routes/[resource].ts')
- [ ] Commands are exact (`pnpm test` not 'run tests')
- [ ] Includes a verification step
- [ ] Rules section has explicit prohibitions

## Examples quality
- [ ] At least one realistic example
- [ ] Code blocks use the actual format expected
- [ ] Example shows the output Claude should produce, not just the input

## Test the skill
- [ ] Invoked on a simple case and produced correct output
- [ ] Invoked on an edge case and handled it correctly
- [ ] Did NOT trigger on an unrelated task