How to Build Custom Claude Code Skills: Step-by-Step Guide

What Are Claude Code Skills?

Claude Code skills are reusable instruction files that teach Claude Code specific workflows, coding conventions, and procedures. They act as expert knowledge packages that Claude Code references when performing relevant tasks. A skill might define how to create a new API endpoint following your team's patterns, how to write database migrations with your ORM, or how to structure test files for your testing framework.

Skills are written in Markdown, typically in a file called SKILL.md. They follow a structured format that includes a description of the skill, trigger conditions (when Claude Code should activate it), and step-by-step instructions. Because they are plain text files, they can be version-controlled, shared with teammates, and published to the community.

Think of skills as reusable recipes: you write them once, and Claude Code follows them every time the relevant task comes up. This is fundamentally different from repeating the same instructions in every conversation.

Skill File Structure

Every skill follows a consistent structure that helps Claude Code understand when and how to use it. Here is the anatomy of a well-structured skill file:

# Skill Name

## Description
A brief explanation of what this skill does and when it should be used.

## Trigger
Describe when Claude Code should activate this skill.
Example: "Use this skill when the user asks to create a new API endpoint."

## Instructions

### Step 1: Analyze the Request
- Understand the resource name and required fields
- Check existing endpoints for patterns to follow

### Step 2: Create the Route File
- Create the file at `src/routes/[resource].ts`
- Follow the existing route structure
- Include input validation using Zod

### Step 3: Create the Controller
- Business logic goes in `src/controllers/[resource].controller.ts`
- Always return typed responses
- Handle errors with the standard error handler

### Step 4: Add Tests
- Create test file at `tests/routes/[resource].test.ts`
- Cover happy path and error cases
- Use the test helpers from `tests/helpers.ts`

## Examples
Show concrete before/after examples when helpful.

## Notes
Any caveats, edge cases, or additional context.

The key sections are the Trigger (tells Claude Code when to use the skill) and the Instructions(tells it exactly what to do). The more specific and concrete your instructions, the more consistent Claude Code's output will be.

Step-by-Step: Building Your First Skill

Let us build a practical skill that teaches Claude Code how to create React components following your team's conventions.

Step 1: Create the Skills Directory

Skills live in a .claude/skills/ directory. Create it at the root of your project:

Step 2: Write the Skill File

Create a file called .claude/skills/react-component.md with the following content:

# Create React Component

## Description
Creates a new React component following our team's conventions
including TypeScript types, tests, and Storybook stories.

## Trigger
Use when the user asks to create a new React component, UI element,
or page section.

## Instructions

### 1. Component File
Create `src/components/[ComponentName]/[ComponentName].tsx`:
- Use named exports (not default)
- Define Props interface above the component
- Use forwardRef when the component wraps a DOM element
- Add JSDoc comments for complex props

### 2. Types
If the component has more than 3 props, create a separate
types file at `src/components/[ComponentName]/types.ts`.

### 3. Styles
Use Tailwind CSS classes. Do not create separate CSS files.
For complex conditional styles, use the `cn()` utility.

### 4. Tests
Create `src/components/[ComponentName]/[ComponentName].test.tsx`:
- Test rendering with default props
- Test each interactive behavior
- Test accessibility (role, aria attributes)
- Use @testing-library/react

### 5. Index Export
Create `src/components/[ComponentName]/index.ts` that re-exports
the component and its types.

### 6. Barrel Export
Add the component to `src/components/index.ts`.

## Example

For a "Button" component, the file structure should be:
```
src/components/Button/
  Button.tsx
  Button.test.tsx
  index.ts
  types.ts (if needed)
```

Step 3: Test the Skill

Open Claude Code in your project directory and ask it to create a component:

Claude Code will automatically detect the relevant skill and follow the conventions you defined. It will create the component file, test file, index export, and add it to the barrel export -- all following your exact patterns.

Step 4: Iterate and Refine

After testing, refine your skill based on the output. If Claude Code missed a convention or made assumptions you did not intend, add more specific instructions. The best skills are built iteratively -- start simple and add detail as you discover edge cases.

Best Practices for Writing Skills

• 1.
  Be specific, not vague. Instead of "follow best practices," write "use Zod for input validation with schemas defined in src/schemas/." Claude Code performs better with concrete instructions than abstract principles.
• 2.
  Include examples. Show Claude Code what the output should look like. A concrete code example is worth a paragraph of explanation.
• 3.
  Keep skills focused. One skill should handle one type of task. A "Create API Endpoint" skill and a "Write Database Migration" skill are better than a single "Backend Development" skill that tries to cover everything.
• 4.
  Reference existing code. Point Claude Code to files in your project that demonstrate the pattern. "Follow the structure in src/routes/users.tsas a reference" is incredibly effective.
• 5.
  Define clear triggers. The trigger description helps Claude Code decide when to activate the skill. Be explicit about the conditions so it does not apply the skill to unrelated tasks.
• 6.
  Version control your skills. Commit skill files to your repository. They evolve with your codebase, and version control lets you track what changed and why.

Publishing and Sharing Skills

Project-Level Sharing

The simplest way to share skills is through your project repository. Any skills in the .claude/skills/ directory are automatically available to everyone who clones the repo and uses Claude Code. This is ideal for team-specific conventions.

Global Skills

For skills you want available across all your projects, place them in ~/.claude/skills/. These global skills apply regardless of which project you are working in. Good candidates for global skills include your personal coding preferences, commit message conventions, and debugging workflows.

Community Publishing

To share your skills with the broader community, you can publish them on Claude 4 World, where developers discover and download skills for various frameworks, languages, and workflows. You can also package skills as part of an npm package or GitHub repository for easy distribution.

When publishing, include a clear README explaining what the skill does, which projects it is designed for, and any prerequisites. Good documentation makes the difference between a skill that gets adopted and one that gets ignored.

Advanced: Composing Skills

Skills can reference other skills, creating composable workflows. For example, a "Create Feature" skill might orchestrate several smaller skills:

# Create Feature

## Description
Full workflow for creating a new feature including API,
frontend, and tests.

## Instructions

### 1. API Layer
Follow the "Create API Endpoint" skill to build the backend.

### 2. Frontend Component
Follow the "Create React Component" skill for the UI.

### 3. Integration
- Connect the component to the API using React Query
- Add the route to the router in `src/router.tsx`
- Update navigation if needed

### 4. E2E Test
Create a Playwright test in `tests/e2e/[feature].spec.ts`
covering the complete user flow.

This composition pattern lets you build sophisticated workflows from simple, well-tested building blocks. Each individual skill remains focused and maintainable, while the composite skill handles orchestration.

Frequently Asked Questions