How to Create a Skill in Claude Code

How to Create a Skill in Claude Code

Create custom Skills to standardize your development workflows in Claude Code.

This tutorial covers the complete process: planning your Skill, writing the SKILL.md file, testing it, and sharing it with your team.

What Makes a Good Claude Code Skill?

Effective Skills are focused, clear, and actionable.

Good Skill characteristics:

• Single responsibility — One Skill per task type or pattern
• Clear instructions — Specific rules, not vague suggestions
• Concrete examples — Show code patterns, not just descriptions
• Consistency rules — Enforce team standards
• Context awareness — Account for common edge cases

Bad Skill characteristics:

• Too broad ("How to write good code")
• Contradictory rules
• Vague guidance ("Make it clean")
• Missing examples
• Ignores project context

Before creating a Skill, ask:

1. What specific task does this Skill address?
2. What patterns or rules should Claude follow?
3. Can I provide 2-3 concrete examples?
4. Does this Skill conflict with existing Skills?

SKILL.md Structure and Common Sections

Every Skill is defined by a SKILL.md file.

Common structure:

# Skill Name
Brief description of what this Skill does.
## Purpose
Explain when and why to use this Skill.
## Instructions
Detailed guidance for Claude:
- Specific rules to follow
- Patterns to apply
- Anti-patterns to avoid
## Examples
### Example 1: [Description]
\`\`\`typescript
// Show actual code following the Skill
\`\`\`
### Example 2: [Description]
\`\`\`typescript
// Another example demonstrating the pattern
\`\`\`
## Constraints
- List any hard requirements
- Note language or framework specifics
- Specify required dependencies

Frequently used sections:

• Skill Name — Short, descriptive title
• Purpose — When to use this Skill (1-2 sentences)
• Instructions — The core guidance for Claude
• Examples — Real code demonstrating correct patterns
• Constraints — Technical requirements or limitations

Many teams also add sections for anti-patterns, related skills, or changelog information.

Writing Effective Skill Instructions

Instructions should be specific and actionable.

Weak instruction:

> "Write good TypeScript code."

Strong instruction:

> "Use TypeScript strict mode. Define explicit return types for all functions. Use readonly for immutable properties. Prefer type over interface for unions."

Instruction writing tips:

1. Use imperative language

• ✓ "Define types before using them"
• ✗ "Types should probably be defined first"

1. Provide rationale when needed

• "Use const assertions for literal types (prevents accidental widening)"

1. List rules as bullets

## Component Structure
- Place imports in this order: React, third-party, local
- Define types before component
- Use named exports, not default
- Include PropTypes for runtime checking

1. Include negative rules (what NOT to do)

## Avoid
- Don't use `any` type
- Don't mutate props
- Don't inline complex logic in JSX

1. Reference official style guides when applicable

Follow the Airbnb React Style Guide with these additions:
- [specific team rules]

Testing Your Claude Code Skill

Test Skills before sharing with your team.

Step 1: Create a test skill

Skills are typically organized as folders containing a SKILL.md file. The current Claude Code docs use ~/.claude/skills/<skill-name>/SKILL.md for personal skills and .claude/skills/<skill-name>/SKILL.md for project skills, documented in Claude Code's skills guide.

Step 2: Write your SKILL.md file

Use your text editor to create the Skill following the structure above.

Step 3: Reference the Skill in Claude Code

Start Claude Code and try:

/test-skill
Create a function that validates email addresses.

Step 4: Evaluate Claude's output

Check if Claude followed your Skill instructions:

• Are specified patterns applied?
• Do examples match your Skill's style?
• Are constraints respected?

Step 5: Iterate on instructions

If Claude didn't follow your Skill correctly:

• Add more specific rules
• Provide additional examples
• Clarify ambiguous instructions
• Test again

Common issues and fixes:

Test across multiple scenarios:

Don't just test once. Try:

• Simple cases
• Edge cases
• Integration with other code
• Different file types or contexts

Create Skills in Verdent

Verdent provides a Skill builder interface for creating and testing Skills without manual file management.

Define Skill instructions, test them in an isolated environment, and deploy across all projects from the Verdent dashboard.

Try Verdent Skill Builder