Claude Skills: How to Create Custom Claude Code Skills (2026)

Claude Skills: How to Create Custom Claude Code Skills (2026)

Claude Code is Anthropic's AI-powered CLI for software development. One of its most powerful but underutilized features is custom skills -- reusable slash commands that you can create to automate repetitive tasks, enforce team conventions, and build standardized workflows.

This guide covers everything you need to know about creating, configuring, and sharing Claude Code skills.

What Are Claude Code Skills?

Skills are custom slash commands that provide Claude Code with specific instructions for common tasks. When you type /your-skill-name in Claude Code, it loads a predefined prompt with context, constraints, and examples that guide Claude's behavior.

Think of skills as saved prompts on steroids. They can:

• Define specific output formats.
• Include project-specific context.
• Enforce coding standards and conventions.
• Automate multi-step workflows.
• Be shared across a team via version control.

How Skills Work

Skills are stored as markdown files in specific directories. When invoked, Claude Code reads the file and uses its contents as instructions.

Aspect	Details
File format	Markdown (.md)
Storage location	.claude/skills/ in your project or ~/.claude/skills/ globally
Invocation	Type /skill-name in Claude Code
Scope	Project-level or user-level
Sharing	Commit to version control for team sharing

Setting Up Your First Skill

Step 1: Create the Skills Directory

mkdir -p .claude/skills

For global skills available across all projects:

mkdir -p ~/.claude/skills

Step 2: Create a Skill File

Create .claude/skills/commit.md:

# Commit

Generate a git commit message for the current staged changes.

## Rules

1. Analyze all staged changes using `git diff --cached`
2. Write a commit message following the Conventional Commits format
3. First line: type(scope): description (max 72 characters)
4. Types: feat, fix, refactor, docs, test, chore, perf, ci
5. Include a body if the changes are non-trivial
6. Reference related issue numbers if mentioned in the code changes
7. Do NOT include emoji in commit messages
8. Stage the commit but let the user confirm before executing

## Format

type(scope): short description

Longer description of what changed and why. This is optional for simple changes.

Refs: #issue-number (if applicable)

## Examples

Good:
- `feat(auth): add JWT refresh token rotation`
- `fix(api): handle null response in user endpoint`
- `refactor(db): migrate from raw SQL to Prisma ORM`

Bad:
- `updated stuff` (too vague)
- `fix bug` (no scope, no description)
- `FEAT: Add new feature!!!` (wrong format, emoji-like energy)

Step 3: Use the Skill

In Claude Code, type:

/commit

Claude Code reads the skill file and follows the instructions to generate a properly formatted commit message.

Practical Skill Examples

Code Review Skill

Create .claude/skills/review.md:

# Code Review

Perform a thorough code review of the specified file or recent changes.

## Process

1. If no file is specified, review all uncommitted changes using `git diff`
2. Analyze the code for these categories:

### Security
- SQL injection, XSS, CSRF vulnerabilities
- Hardcoded secrets or credentials
- Improper input validation
- Authentication/authorization issues

### Performance
- N+1 queries
- Missing indexes (if database-related)
- Unnecessary re-renders (if React)
- Memory leaks
- Inefficient algorithms

### Code Quality
- Naming conventions
- Function length (flag functions > 50 lines)
- Duplicated logic
- Missing error handling
- Missing TypeScript types (if TS project)

### Testing
- Are new functions covered by tests?
- Edge cases considered?
- Are mocks appropriate?

## Output Format

For each issue found, provide:
- **Severity**: Critical / Warning / Suggestion
- **Location**: File and line number
- **Issue**: What the problem is
- **Fix**: Specific code to resolve it

End with a summary: total issues by severity and an overall assessment.

API Endpoint Skill

Create .claude/skills/api-endpoint.md:

# API Endpoint

Create a new API endpoint following project conventions.

## Stack

This project uses:
- Next.js App Router (Route Handlers)
- TypeScript with strict mode
- Zod for validation
- Prisma for database access
- NextAuth for authentication

## Requirements

1. Create the route handler in `src/app/api/[endpoint]/route.ts`
2. Include input validation with Zod schemas
3. Add authentication check using `getServerSession`
4. Handle errors with proper HTTP status codes
5. Return typed JSON responses
6. Add JSDoc comments for the endpoint

## Template

```typescript
import { NextRequest, NextResponse } from "next/server";
import { getServerSession } from "next-auth";
import { z } from "zod";
import { authOptions } from "@/lib/auth";
import { prisma } from "@/lib/prisma";

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

/**
 * Description of what this endpoint does
 * @method POST/GET/PUT/DELETE
 * @auth Required
 */
export async function POST(request: NextRequest) {
  try {
    const session = await getServerSession(authOptions);
    if (!session?.user) {
      return NextResponse.json({ error: "Unauthorized" }, { status: 401 });
    }

    const body = await request.json();
    const validated = requestSchema.parse(body);

    // Implementation here

    return NextResponse.json({ data: result });
  } catch (error) {
    if (error instanceof z.ZodError) {
      return NextResponse.json({ error: error.errors }, { status: 400 });
    }
    console.error("[API_ENDPOINT]", error);
    return NextResponse.json({ error: "Internal server error" }, { status: 500 });
  }
}

When asked to create an endpoint, follow this template exactly and adapt it to the specific use case.

### Component Skill

Create `.claude/skills/component.md`:

```markdown
# Component

Create a new React component following project conventions.

## Stack

- React 19 with Server Components (default)
- TypeScript strict mode
- Tailwind CSS v4 for styling
- Shadcn/ui for base components
- Use "use client" directive only when needed (event handlers, hooks, browser APIs)

## Rules

1. Create the component in the appropriate directory:
   - Shared UI: `src/components/ui/`
   - Feature-specific: `src/components/[feature]/`
   - Page-level: Co-locate with the page
2. Use interface for props (not type)
3. Export as named export (not default)
4. Include proper TypeScript types for all props
5. Use `cn()` utility for conditional classes
6. Make components accessible (ARIA attributes, keyboard navigation)
7. Keep components under 150 lines. Split if larger.

## Naming

- File: `kebab-case.tsx`
- Component: `PascalCase`
- Props interface: `ComponentNameProps`

## Template

```tsx
import { cn } from "@/lib/utils";

interface ComponentNameProps {
  className?: string;
  children?: React.ReactNode;
}

export function ComponentName({ className, children }: ComponentNameProps) {
  return (
    <div className={cn("base-styles", className)}>
      {children}
    </div>
  );
}

### Database Migration Skill

Create `.claude/skills/migration.md`:

```markdown
# Migration

Create a Prisma database migration.

## Process

1. Ask what the migration should do (add table, modify column, add index, etc.)
2. Update the Prisma schema in `prisma/schema.prisma`
3. Run `npx prisma migrate dev --name descriptive-name`
4. If the migration creates a new model, also create:
   - A Zod validation schema in `src/lib/validations/`
   - Basic CRUD functions in `src/lib/db/`
5. Verify the migration succeeded

## Naming Convention

Migration names should be descriptive kebab-case:
- `add-users-table`
- `add-email-index-to-users`
- `rename-post-title-to-headline`
- `add-subscription-status-enum`

## Rules

- Never modify existing migration files
- Always add default values for new required columns on existing tables
- Add indexes for columns used in WHERE clauses
- Use `@map` and `@@map` for snake_case database names

Project-Level vs. Global Skills

Scope	Location	Use Case
Project	.claude/skills/	Team conventions, project-specific workflows
Global	~/.claude/skills/	Personal preferences, cross-project tools

Project-level skills override global skills with the same name. This lets teams enforce conventions while developers keep personal preferences.

Sharing Skills with Your Team

Since skills are just markdown files in your repository, sharing them is as simple as committing to version control:

git add .claude/skills/
git commit -m "feat: add team coding skills for Claude Code"
git push

Every team member who uses Claude Code will automatically get the skills when they pull the repository.

Tips for Writing Effective Skills

1. Be specific about output format. Vague instructions produce inconsistent results. Show exact code templates.
2. Include examples. Good and bad examples help Claude understand your expectations.
3. State the tech stack. Skills that reference your specific framework, language, and tools produce better results.
4. Keep skills focused. One skill per task. A "review" skill and a "commit" skill, not a "review-and-commit" skill.
5. Iterate on skill files. Start simple, then refine based on Claude's output quality.
6. Use constraints. "Do NOT use default exports" is more effective than "prefer named exports."

Debugging Skills

If a skill is not working as expected:

1. Check the file location. Must be in .claude/skills/ or ~/.claude/skills/.
2. Check the file extension. Must be .md.
3. Restart Claude Code. Skills are loaded when Claude Code starts.
4. Test the prompt directly. Copy the skill content and paste it as a regular message to isolate the issue.

Wrapping Up

Custom Claude Code skills transform Claude from a general-purpose assistant into a team-aware development partner that knows your conventions, frameworks, and workflows. The setup takes minutes, and the productivity gains compound with every use.

If your development workflow includes AI-generated media, try Hypereal AI free -- 35 credits, no credit card required. Its API can be called directly from Claude Code for tasks like image generation, video creation, and avatar production during development.