How to Build Your Own Claude Code Skill

You use Claude Code daily and have developed recurring patterns? It's time to turn them into a reusable skill. This guide shows you how to create an effective skill from scratch.

Why Create a Skill?

• Consistency: Same instructions every session
• Sharing: Your team benefits from your best practices
• Quality: Claude follows a proven framework instead of improvising

Step 1: Identify the Need

Ask yourself:

1. What task do I repeat often? (code review, writing tests, generating docs)
2. What instructions do I always give Claude? (naming conventions, architectural patterns)
3. Where does Claude make recurring mistakes? (that's where instructions are most useful)

Step 2: Structure the Skill

Minimal Template

---
name: skill-name
description: Short, actionable description
platforms: [claude-code]
difficulty: intermediate
tags: [tag1, tag2]
---

# Skill Name

## When to Use This Skill

Describe trigger situations.

## Instructions

### Rule 1: [Rule Name]

Clear, concise explanation.

**Good example:**
\`\`\`
correct code
\`\`\`

**Bad example:**
\`\`\`
incorrect code
\`\`\`

### Rule 2: [Rule Name]

...

## Checklist

- [ ] Verification point 1
- [ ] Verification point 2

Step 3: Write Effective Instructions

Principle 1: Be Prescriptive, Not Descriptive

❌ "The code should be well tested" ✅ "Write a unit test for each public function. Use the AAA pattern (Arrange, Act, Assert). Each test has a single expect."

Principle 2: Use Concrete Examples

Examples are worth a thousand words. Show the expected output.

Principle 3: Define Anti-Patterns

Claude learns as much from what NOT to do:

## What NOT to Do

- Never use `any` in TypeScript
- Don't create files over 300 lines
- Don't add obvious comments

Principle 4: Structure in Steps

## Workflow

1. Read existing code in the target file
2. Identify patterns used
3. Write the test first (TDD)
4. Implement the feature
5. Verify all tests pass
6. Commit with a conventional message

Step 4: Test the Skill

1. Place the file in .claude/skills/
2. Launch Claude Code and test with real cases
3. Note where Claude deviates from expectations
4. Adjust instructions
5. Repeat until satisfied

Quality Metrics

• Precision: Does Claude do exactly what you want?
• Consistency: Is the result the same every time?
• Autonomy: Does Claude need clarifying questions?

Step 5: Publish and Share

On GitHub

1. Create a repo with your SKILL.md at the root
2. Add an explanatory README
3. Tag with topics claude-code, skill, claude-code-skill

On Skills Guides

Submit your skill via our contribution form to get it listed in the catalog.

Examples of Well-Designed Skills

• Playwright Skill: Very detailed instructions with patterns for each test type
• Loki Mode: Well-structured complex multi-step workflow
• VibeSec: Exhaustive security checklists with OWASP references

Conclusion

A good skill is an investment: a few hours of writing for hundreds of hours saved. Start simple, iterate often, and share with the community.