How to Create Your Own Custom Claude Code Skills
A comprehensive guide to writing, testing, and sharing custom Claude Code skills. Learn the markdown format, frontmatter structure, best practices, and how to make your skills effective.
Why Create Custom Skills?
While the Claude Skills Hub offers a growing library of pre-built skills, your team and projects have unique requirements. Custom skills let you encode your organization's specific coding standards, architectural patterns, and workflows into reusable instruction sets that Claude follows consistently.
Imagine never having to explain your team's commit message format, test structure, or API conventions again. A well-crafted custom skill handles all of that automatically.
The Skill File Format
Every Claude Code skill is a markdown file (.md) with two main parts: frontmatter for metadata and a body with instructions.
Basic Structure
---
title: My Custom Skill
description: A brief description of what this skill does
author: Your Name
version: 1.0.0
tags: [typescript, testing, react]
---
# My Custom Skill
## Purpose
Clearly state what this skill accomplishes.
## Instructions
Step-by-step directions for Claude to follow.
## Rules
Constraints and requirements that must be met.
## Examples
Input/output examples showing expected behavior.
Frontmatter Fields
The frontmatter section sits between two --- delimiters at the top of the file. Here are the available fields:
| Field | Required | Description |
|---|---|---|
title | Yes | Human-readable name for the skill |
description | Yes | One-line summary of the skill's purpose |
author | Yes | Creator's name or organization |
version | No | Semantic version number |
tags | No | Array of relevant tags for discovery |
Writing Effective Instructions
The body of your skill is where the real power lives. This is the part Claude reads and follows. Here are the key sections to include:
1. Purpose Section
Start with a clear, concise explanation of what the skill does:
## Purpose
This skill generates React component unit tests using Vitest and
React Testing Library. It creates comprehensive test suites that
cover rendering, user interactions, prop variations, and edge cases.
Be specific. "Helps with testing" is vague. "Generates Vitest unit tests for React components with coverage for rendering, events, and edge cases" tells Claude exactly what to produce.
2. Instructions Section
This is the core of your skill. Write clear, sequential instructions:
## Instructions
1. Analyze the target component to understand:
- Props and their types
- State management
- Side effects and hooks
- User interaction handlers
- Conditional rendering logic
2. Create the test file with the naming convention:
`ComponentName.test.tsx`
3. Structure tests using describe/it blocks:
- Top-level describe with the component name
- Nested describes for logical groupings
- Individual it blocks for specific behaviors
4. Include these test categories:
- Rendering: Does it render without crashing?
- Props: Does it handle different prop values correctly?
- Interactions: Do click/input handlers work?
- Edge cases: What about null/undefined/empty values?
3. Rules and Constraints
Define boundaries and non-negotiable requirements:
## Rules
- ALWAYS use `screen` queries from Testing Library (never container queries)
- NEVER use `getByTestId` unless no semantic query is available
- ALWAYS clean up after async operations
- Use `userEvent` over `fireEvent` for user interactions
- Mock external dependencies, never test third-party library internals
- Each test must be independent and not rely on execution order
Using strong language like "ALWAYS" and "NEVER" helps Claude understand which rules are strict requirements versus soft preferences.
4. Examples Section
Examples are incredibly powerful. They show Claude the exact output format and quality you expect:
## Examples
### Input Component
```tsx
interface ButtonProps {
label: string;
onClick: () => void;
disabled?: boolean;
}
export function Button({ label, onClick, disabled }: ButtonProps) {
return (
<button onClick={onClick} disabled={disabled}>
{label}
</button>
);
}
Expected Test Output
import { render, screen } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { describe, it, expect, vi } from 'vitest';
import { Button } from './Button';
describe('Button', () => {
it('renders with the provided label', () => {
render(<Button label="Click me" onClick={() => {}} />);
expect(screen.getByRole('button', { name: 'Click me' })).toBeInTheDocument();
});
it('calls onClick when clicked', async () => {
const handleClick = vi.fn();
render(<Button label="Click me" onClick={handleClick} />);
await userEvent.click(screen.getByRole('button'));
expect(handleClick).toHaveBeenCalledOnce();
});
it('is disabled when disabled prop is true', () => {
render(<Button label="Click me" onClick={() => {}} disabled />);
expect(screen.getByRole('button')).toBeDisabled();
});
});
## Best Practices for Writing Skills
### Be Opinionated
The best skills make clear decisions. Instead of saying "you can use either Jest or Vitest," pick one and commit. Skills that try to cover every possibility end up being vague and produce inconsistent results.
### Use Progressive Detail
Start with the big picture, then drill into specifics. Claude processes instructions sequentially, so establish context before diving into details.
### Include Anti-Patterns
Telling Claude what NOT to do is just as valuable as telling it what to do:
```markdown
## Anti-Patterns (Do NOT Do These)
- Don't test implementation details (internal state, private methods)
- Don't snapshot test entire components
- Don't write tests that pass regardless of component behavior
- Don't ignore TypeScript errors in test files
Keep Skills Focused
A skill should do one thing well. If you find a skill growing beyond 200 lines, consider splitting it into two specialized skills. A focused skill produces more reliable, consistent output.
Version Your Skills
As your practices evolve, update skills and bump the version number. This makes it easy to track changes and roll back if needed.
Testing Your Custom Skill
Before sharing a skill, test it thoroughly:
Step 1: Install It Locally
cp my-custom-skill.md ~/.claude/skills/
Step 2: Run It Against Known Code
Test the skill against code where you already know what the output should look like. This helps you verify the skill produces correct, high-quality results.
Step 3: Test Edge Cases
Try the skill with:
- Simple, straightforward input
- Complex, multi-file scenarios
- Edge cases and unusual patterns
- Different languages or frameworks (if the skill is supposed to be generic)
Step 4: Iterate
Refine the instructions based on output quality. If Claude misses something, add explicit instructions. If it produces unnecessary content, add constraints.
Sharing Your Skills
Once your skill is polished, share it with others:
Share on Claude Skills Hub
Submit your skill to our hub so the entire community can benefit. Well-documented skills with clear examples get the most adoption.
Share via Git Repository
Create a repository with your team's skills:
our-claude-skills/
README.md
skills/
react-component-test.md
api-endpoint-generator.md
commit-message-writer.md
examples/
sample-outputs/
Share via Package Manager
For broader distribution, consider creating an npm package or similar that installs skills to the correct directory:
npx install-claude-skills @yourorg/skills-collection
Real-World Custom Skill Ideas
Here are some ideas to inspire your own custom skills:
- Migration Writer - Generates database migrations following your ORM's conventions
- PR Description Generator - Creates thorough pull request descriptions from git diffs
- Error Handler - Implements error handling following your team's error hierarchy
- Component Scaffolder - Creates new components with your team's folder structure and boilerplate
- Config Generator - Produces configuration files for your specific tech stack
- Documentation Writer - Generates JSDoc or TSDoc following your documentation standards
- Code Reviewer - Reviews code against your team's specific style guide and patterns
Common Mistakes to Avoid
- Being too vague - "Write good code" is useless. Be specific about what "good" means.
- Overloading a single skill - Keep each skill focused on one task.
- Skipping examples - Examples are the most effective way to communicate expected output.
- Ignoring edge cases - Address what should happen with unexpected or empty input.
- Not testing - Always test against real code before sharing.
Conclusion
Creating custom Claude Code skills is a powerful way to standardize your development workflow and multiply your team's productivity. Start with one skill for a task you repeat often, refine it through testing, and gradually build a library that encodes your team's collective wisdom.
The investment pays off quickly: a well-crafted skill saves minutes on every use, and those minutes compound into hours saved every week. Start building your first custom skill today.