Claude Skills Guide

# Cursor Rules (project-wide conventions)
- Use TypeScript strict mode
- Follow ESLint config
- Use tabs for indentation

# Claude Skills (specialized task knowledge)
- How to create a React component in THIS project
- How to write and run tests with YOUR test framework
- How to deploy to YOUR specific infrastructure

<agent_skill fullPath="/path/to/SKILL.md">
  Guides users through creating React components.
  Use when the user wants to create, scaffold, or
  generate a new React component.
</agent_skill>

1. User sends a message to the AI agent
2. Agent checks available skills against the request
3. If a skill matches, agent reads the SKILL.md file
4. Agent follows the skill's instructions step-by-step
5. Agent uses the skill's tools, templates, and patterns
6. Result is delivered following the skill's output format

# Global skills (available in all projects)
~/.cursor/skills-cursor/
├── create-component/
│   └── SKILL.md
├── write-tests/
│   └── SKILL.md
└── deploy-app/
    └── SKILL.md

# Project-specific skills (only this project)
your-project/
├── .cursor/
│   └── skills/
│       ├── project-setup/
│       │   └── SKILL.md
│       └── api-patterns/
│           └── SKILL.md
└── src/

# Skill Name

Brief one-line description of what this skill does.

## Description

A more detailed explanation of the skill's purpose,
when it should be used, and what it accomplishes.

## Instructions

Step-by-step instructions the agent should follow:

1. First, do this...
2. Then check for...
3. Next, create...
4. Finally, verify...

## Templates

Code templates or boilerplate the agent should use.

## Examples

### Example 1: Basic Usage
Input: "Create a new user service"
Expected output: ...

## Notes

- Additional context or caveats
- Edge cases to watch for
- Related skills or resources

# Title          → Clear, descriptive skill name
## Description   → When and why to use this skill
## Instructions  → Step-by-step directions for the agent

## Templates     → Code scaffolds and boilerplate
## Examples      → Input/output demonstrations
## Notes         → Edge cases and additional context
## Configuration → Configurable parameters
## Validation    → How to verify the output is correct

# For a global skill
mkdir -p ~/.cursor/skills-cursor/create-api-route

# For a project-specific skill
mkdir -p .cursor/skills/create-api-route

# Create API Route

Scaffolds a new API route handler with validation,
error handling, and TypeScript types.

## Description

Use this skill when the user wants to create a new
API endpoint or route handler. This ensures consistent
patterns across the project including proper error
handling, input validation, and response formatting.

## Instructions

1. Ask the user for:
   - The HTTP method (GET, POST, PUT, DELETE)
   - The route path (e.g., /api/users)
   - The expected request/response shape

2. Create the route file at the correct path:
   - Routes live in `src/app/api/`
   - Follow Next.js App Router conventions
   - File should be named `route.ts`

3. Include these patterns in every route:
   - Zod schema for request validation
   - Try/catch with standardized error responses
   - TypeScript types for request and response
   - JSDoc comments for documentation

4. After creating the file:
   - Add any new Zod schemas to `src/lib/validators/`
   - Update the API documentation if it exists
   - Run the TypeScript compiler to verify types

import { NextRequest, NextResponse } from 'next/server';
import { z } from 'zod';

const requestSchema = z.object({
  // define schema here
});

type RequestBody = z.infer<typeof requestSchema>;

export async function METHOD(request: NextRequest) {
  try {
    const body: RequestBody = requestSchema.parse(
      await request.json()
    );

    // Implementation here

    return NextResponse.json(
      { data: result },
      { status: 200 }
    );
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json(
        { error: 'Validation failed', details: error.errors },
        { status: 400 }
      );
    }
    return NextResponse.json(
      { error: 'Internal server error' },
      { status: 500 }
    );
  }
}

<agent_skill fullPath="~/.cursor/skills-cursor/create-api-route/SKILL.md">
  Scaffolds new API route handlers with validation and
  error handling. Use when the user wants to create a
  new API endpoint, route handler, or REST resource.
</agent_skill>

# Create React Component

Scaffolds a new React component following project
conventions with TypeScript, styles, and tests.

## Instructions

1. Create the component directory at the specified path
2. Generate the component file with:
   - TypeScript interface for props
   - Functional component with proper typing
   - Default export
3. Create a co-located CSS module file
4. Create a test file with a basic render test
5. Create an index.ts barrel export

ComponentName/
├── ComponentName.tsx
├── ComponentName.module.css
├── ComponentName.test.tsx
└── index.ts

# Write Tests

Creates comprehensive test suites following the
project's testing patterns and conventions.

## Instructions

1. Identify the file or function to test
2. Read the source code to understand behavior
3. Create the test file following naming convention:
   - Unit tests: `*.test.ts` next to source
   - Integration tests: `__tests__/` directory
4. Write tests covering:
   - Happy path (expected behavior)
   - Edge cases (empty input, boundaries)
   - Error cases (invalid input, failures)
5. Use existing test utilities from `src/test/helpers/`
6. Run the tests to verify they pass

# Create Database Migration

Generates database migration files with up/down
operations following the project's ORM conventions.

## Instructions

1. Ask the user what schema changes are needed
2. Generate the migration file with a timestamp prefix
3. Include both `up` and `down` operations
4. Add appropriate indexes for new columns
5. Handle nullable fields and default values
6. Run the migration in dry-run mode to verify SQL
7. Update the schema types file if applicable

# Bad - too vague
## Instructions
Create a component with good practices.

# Good - specific and actionable
## Instructions
1. Create a functional component using arrow function syntax
2. Define a TypeScript interface for props named `{Name}Props`
3. Destructure props in the function signature
4. Use CSS Modules for styling (import as `styles`)
5. Add a `data-testid` attribute to the root element
6. Export the component as the default export

## Instructions

1. Read the existing configuration in `next.config.js`
2. Check if the feature flag already exists in the config
3. If it exists, update the value; if not, add a new entry
4. Validate the config file still parses correctly
5. Restart the dev server if it's currently running

## Instructions

1. Check if the project uses TypeScript or JavaScript:
   - If TypeScript: create `.tsx` files with interfaces
   - If JavaScript: create `.jsx` files with PropTypes

2. Check the styling approach:
   - If CSS Modules: create `*.module.css` files
   - If Tailwind: use utility classes inline
   - If styled-components: create styled wrappers

3. Check the testing framework:
   - If Jest: use `describe/it` blocks
   - If Vitest: use `describe/it` blocks (same API)
   - If Playwright: create e2e test in `tests/` folder

## Instructions

1. Components go in `src/components/{Category}/`
2. Hooks go in `src/hooks/`
3. Utilities go in `src/lib/utils/`
4. Types go in `src/types/`
5. Tests are co-located with source files
6. Shared test helpers are in `src/test/helpers/`

create-feature/
├── SKILL.md              # Main instructions
├── component.template    # Component boilerplate
├── test.template         # Test boilerplate
└── styles.template       # Styles boilerplate

# In SKILL.md

## Instructions

1. Read the component template from `component.template`
   in the same directory as this skill file
2. Replace all placeholders:
   - `{{NAME}}` → component name (PascalCase)
   - `{{PATH}}` → file path relative to src/
   - `{{DATE}}` → current date in ISO format
3. Write the processed template to the target path

# Create Full Feature

## Instructions

1. Use the "Create React Component" skill to scaffold
   the UI component
2. Use the "Create API Route" skill to scaffold the
   backend endpoint
3. Use the "Write Tests" skill to generate tests for
   both the component and the API route
4. Wire up the component to call the API route
5. Add the route to the navigation if applicable

## Validation

After completing the task, verify:

1. [ ] TypeScript compiles with no errors
2. [ ] All new files follow the naming convention
3. [ ] No circular imports were introduced
4. [ ] Tests pass when run with `npm test`
5. [ ] Linting passes with `npm run lint`
6. [ ] The feature works when tested manually

## Instructions

Before generating any code:

1. Read `package.json` to determine:
   - Framework version (React 18 vs 19)
   - Available dependencies (state management, etc.)
   - Script commands for testing/building

2. Read `tsconfig.json` to determine:
   - Path aliases (e.g., `@/` prefix)
   - Strict mode settings
   - Target ECMAScript version

3. Scan `src/components/` for existing patterns:
   - How are props interfaces named?
   - Are default exports or named exports used?
   - What styling approach is used?

4. Now generate code matching these discovered patterns.

# Bad - too broad
"Do Everything" Skill
- Creates components
- Writes tests
- Handles deployment
- Manages database migrations
- Configures CI/CD

# Good - focused and specific
"Create React Component" Skill
- Scaffolds component file
- Creates co-located test
- Adds barrel export
- Follows project naming conventions

# Bad - too generic, will trigger on unrelated requests
"Use when the user asks about code."

# Good - specific trigger conditions
"Scaffolds new React components with TypeScript, CSS
Modules, and tests. Use when the user wants to create,
generate, or scaffold a new React component, page, or
layout."

## Instructions

...

## Error Handling

If the target directory doesn't exist:
→ Create it and any parent directories

If a file with the same name already exists:
→ Ask the user before overwriting

If required dependencies are missing:
→ Install them with the project's package manager

If the TypeScript compiler reports errors:
→ Fix the type errors before proceeding

# Create API Route

Version: 2.1.0
Last updated: 2026-02-06
Author: Team Name

## Changelog
- 2.1.0: Added Zod validation template
- 2.0.0: Migrated from Pages Router to App Router
- 1.0.0: Initial skill creation

## Test Cases

Try these prompts to verify the skill works:

1. "Create a UserProfile component" → Should scaffold
   full component with props, styles, and test

2. "Create a simple Button component" → Should handle
   minimal components without over-engineering

3. "Create a DataTable component with sorting" → Should
   handle complex requirements and include relevant
   props in the interface

# Create Next.js Page

Scaffolds a new Next.js App Router page with metadata,
loading states, and error boundaries.

## Description

Use when the user wants to create a new page or route
in a Next.js App Router project. Handles layout
nesting, metadata, and loading/error UI.

## Instructions

1. Determine the route path from the user's request
2. Create the directory under `src/app/`
3. Generate these files:
   - `page.tsx` — Main page component
   - `loading.tsx` — Loading skeleton UI
   - `error.tsx` — Error boundary component
   - `layout.tsx` — Only if page needs its own layout
4. Add SEO metadata using the Metadata API
5. If the page needs data, create a server component
   with async data fetching
6. Update navigation if the page should be linked

import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: '{{PageTitle}} | App Name',
  description: '{{Description}}',
};

export default async function PageNamePage() {
  return (
    <main>
      <h1>Page Title</h1>
    </main>
  );
}

# Write Documentation

Generates documentation for code following the project's
documentation standards and conventions.

## Description

Use when the user wants to document a function, module,
API endpoint, or component. Creates clear, concise docs
with examples.

## Instructions

1. Read the source code to understand its purpose
2. Identify the public API (exports, parameters, returns)
3. Generate documentation including:
   - Brief description (one line)
   - Detailed explanation (one paragraph)
   - Parameters table with types and descriptions
   - Return value description
   - At least 2 usage examples (basic and advanced)
   - Any thrown errors or edge cases
4. Use JSDoc format for inline code documentation
5. Use Markdown for standalone documentation files

/**
 * Brief one-line description.
 *
 * Detailed explanation of what this function does,
 * when to use it, and any important considerations.
 *
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws {ErrorType} When this condition occurs
 *
 * @example
 * // Basic usage
 * const result = functionName('input');
 *
 * @example
 * // Advanced usage with options
 * const result = functionName('input', { option: true });
 */

# Review Pull Request

Performs a thorough code review following the team's
review standards and checklist.

## Description

Use when the user asks to review code, a pull request,
or a set of changes. Provides structured feedback with
actionable suggestions.

## Instructions

1. Read all changed files in the diff
2. For each file, evaluate:
   - Correctness: Does the code work as intended?
   - Types: Are TypeScript types correct and specific?
   - Security: Are there any vulnerabilities?
   - Performance: Any unnecessary re-renders or loops?
   - Readability: Is the code clear and well-named?
3. Categorize findings as:
   - 🔴 Must Fix — Bugs, security issues, broken logic
   - 🟡 Should Fix — Code quality, naming, patterns
   - 🟢 Suggestion — Nice-to-haves, minor improvements
4. Provide specific code suggestions for each finding
5. End with an overall summary and approval status

Problem: Agent doesn't use the skill when expected

Solutions:
1. Check the trigger description — is it specific
   enough to match the user's request?
2. Verify the file path in the skill registration
   is correct and the file exists
3. Make sure the SKILL.md file is readable (check
   file permissions)
4. Try being more explicit: "Use the create component
   skill to scaffold a new Button component"

Problem: Agent follows the skill but output is wrong

Solutions:
1. Add more specific instructions — don't assume
   the agent will infer your preferences
2. Include concrete examples in the skill showing
   expected input → output
3. Add validation steps so the agent verifies its
   own output before finishing
4. Use templates with clear placeholder markers

Problem: Agent skips some instruction steps

Solutions:
1. Break complex steps into smaller sub-steps
2. Number every step explicitly (avoid nested bullets
   for critical actions)
3. Add checkpoint notes: "Before proceeding to step 4,
   verify that steps 1-3 are complete"
4. Keep the total instruction count manageable (under
   15-20 steps per skill)

Problem: Multiple skills trigger for the same request

Solutions:
1. Make trigger descriptions more specific and
   non-overlapping
2. Add exclusion notes: "Do NOT use this skill for
   API routes — use the Create API Route skill instead"
3. Reduce the number of generic skills
4. Prefer project-specific skills over global ones
   for common tasks