Back to Lab

How to Build a Claude Code Skill from Scratch

Skills Turn Claude Code from Assistant into Expert

Claude Code is powerful out of the box. But without skills, every new session starts from zero. You explain your workflow, your preferences, your conventions - again. Skills fix that. They give Claude persistent expertise that loads on demand via slash commands.

As of 2026, the Claude Code skill ecosystem is still early. Anthropic introduced the skill system in late 2025, and adoption has been growing rapidly. A growing number of AI-assisted developers use some form of custom instruction or skill system, and adoption has roughly quadrupled since 2024. The ones who do report significantly less time spent on repetitive prompting.

This guide walks you through building a skill from scratch, testing it, and optionally packaging it for distribution or sale.

What a Skill Actually Is

A Claude Code skill is a directory containing a SKILL.md file. That's it at the minimum. The SKILL.md file contains structured instructions that Claude loads when triggered. Think of it as a specialized prompt that persists across sessions and activates on command.

Skills live in ~/.claude/skills/ by default. Each skill gets its own subdirectory:

~/.claude/skills/
  my-skill/
    SKILL.md
    examples/        (optional)
    templates/       (optional)
    assets/          (optional)

When you type a slash command that matches a skill's trigger, Claude reads the SKILL.md and gains that expertise for the current session. No context wasted on explaining what you want. No drift from your standards.

Anatomy of SKILL.md

The SKILL.md file follows a specific structure. Here's the skeleton:

# Skill Name

## Trigger
/your-command

## Description
One-line description of what this skill does.

## Instructions
The actual expertise. This is where you define:
- What Claude should know
- How it should behave
- What conventions to follow
- What output format to use

## Examples (optional)
Input/output pairs showing expected behavior.

## Constraints (optional)
Hard rules Claude must follow when this skill is active.

The ## Trigger section is critical. It defines the slash command that activates the skill. When you type /your-command in Claude Code, it searches installed skills for a matching trigger and loads the corresponding SKILL.md.

Building a Real Skill: Git Quiz

Let's build a simplified version of a git learning skill. This is based on the architecture behind Git Dojo, stripped down to teach the core concepts.

Create the directory:

mkdir -p ~/.claude/skills/git-quiz

Now create the SKILL.md. Skills that include structured examples perform noticeably better on task accuracy compared to instruction-only skills. So we'll include examples.

# Git Quiz

## Trigger
/git-quiz

## Description
Interactive git knowledge quiz with progressive difficulty.

## Instructions
When triggered, present the user with a git scenario and ask
them to provide the correct command or explain the concept.

### Difficulty Levels
- Beginner: basic commands (add, commit, push, pull, status)
- Intermediate: branching, merging, rebasing, stash
- Advanced: reflog, bisect, cherry-pick, interactive rebase

### Quiz Format
1. Present a real-world scenario (2-3 sentences)
2. Ask the user for the correct git command or explanation
3. Wait for their answer
4. Grade it: correct, partially correct, or incorrect
5. Explain the right answer with context
6. Track score across the session

### Rules
- Never give the answer before the user attempts it
- Use realistic scenarios, not textbook examples
- After each answer, show running score (correct/total)
- Offer to increase difficulty after 3 correct in a row

## Examples

### Example Scenario (Beginner)
"You just created three new files in your project. You want to
stage all of them and create a commit with the message 'Add
initial components'. What commands do you run?"

Expected: git add . && git commit -m "Add initial components"
Also acceptable: git add -A && git commit -m "Add initial components"

### Example Scenario (Advanced)
"You made a commit 5 commits ago that introduced a bug, but you
only realized it now. You want to undo just that one commit
without affecting the 4 commits after it. What do you use?"

Expected: git revert [commit-hash]

## Constraints
- Never use em dashes
- Keep explanations under 100 words
- Always relate answers to practical dev workflows

Testing Your Skill

Testing is straightforward. Open Claude Code and type your trigger command:

/git-quiz

Claude should load the skill and start presenting quiz scenarios. Test these specific things:

• Trigger recognition: Does the slash command activate the skill?
• Instruction adherence: Does Claude follow the format you defined?
• Constraint compliance: Does it respect your hard rules?
• Edge cases: What happens with ambiguous answers? Does it handle partial credit?
• Persistence: Does it maintain score tracking across the session?

In practice, skills with 3+ concrete examples in their SKILL.md show a much higher rate of consistent behavior compared to those with instructions alone. If Claude isn't behaving as expected, add more examples before rewriting your instructions.

Common Skill Patterns

After building dozens of skills, patterns emerge. Here are the most useful architectures:

Pattern	Use Case	Key Feature
Quiz / Drill	Learning and practice	Score tracking, progressive difficulty
Code Review	Quality enforcement	Checklist-based analysis, severity ratings
Generator	Boilerplate creation	Templates, variable substitution
Workflow	Multi-step processes	Sequential instructions, checkpoints
Reference	Quick lookup	Structured knowledge base, search
Audit	Compliance checking	Rule sets, pass/fail criteria, reports

The generator pattern is the most popular. Template-based skills account for the majority of all shared skills. But the quiz/drill pattern has the highest user engagement, with significantly more repeat activations per user.

Adding Supporting Files

Skills can include more than just SKILL.md. For complex skills, you might add:

• examples/ - Sample input/output files Claude can reference
• templates/ - Code templates the skill generates from
• data/ - Reference data (checklists, rule sets, glossaries)

Reference these in your SKILL.md with relative paths. Claude will read them when the skill activates. Keep total skill size under 50KB for fast loading - anything larger slows down activation and eats into your context window.

Packaging for Distribution

If your skill is useful to you, it might be useful to others. Packaging options:

• GitHub repo: Users clone into ~/.claude/skills/. Free, easy to update.
• Zip download: Sell on your own store. Users extract to the skills directory.
• Installer script: A bash script that creates the directory and writes the files. Most user-friendly.

For selling skills, keep it simple. A zip file with a README explaining installation works. Git Dojo (5 EUR) uses this approach - download the zip, extract to your skills folder, type /git-dojo. No build step, no dependencies, no accounts.

The emerging market for Claude Code skills is small but real. Developer marketplaces have seen explosive growth in AI-tool extensions and plugins sold over the past two years. Skills are the Claude Code equivalent of VS Code extensions, just earlier in the adoption curve.

Debugging Tips

When your skill doesn't work as expected:

1. Check the trigger: Make sure the trigger in SKILL.md matches exactly what you're typing
2. Simplify instructions: If Claude ignores parts of your skill, your instructions might be too long. Cut to essentials.
3. Add negative examples: Show Claude what NOT to do. "Never respond with X" is often more effective than "Always respond with Y."
4. Test in isolation: Disable other skills temporarily to rule out conflicts
5. Check file encoding: SKILL.md must be UTF-8. Other encodings can cause silent parsing failures.

What Makes a Skill Worth Building

Not everything should be a skill. Build one when:

• You explain the same thing to Claude more than 3 times per week
• Your workflow has strict conventions that Claude needs to follow every time
• You want to teach or drill a concept interactively
• You have a multi-step process that benefits from structured guidance

Don't build a skill for one-off tasks or things that change frequently. Skills work best for stable workflows and persistent expertise.

Frequently Asked Questions

How many skills can I have installed at once?

There's no hard limit, but each active skill consumes context tokens when loaded. Practically, most developers have 10-30 skills installed. Only the triggered skill loads per session, so having many installed doesn't slow things down.

Can a skill call other skills?

Not directly. Skills are instruction sets, not executable code. However, you can reference other skills in your instructions ("After completing this workflow, suggest the user runs /deploy-check"). Claude will present it as a suggestion, and the user can trigger the next skill manually.

Do skills work with all Claude models?

Yes. Skills are model-agnostic since they're just structured prompts. However, complex skills with detailed instructions perform noticeably better with Opus or Sonnet compared to Haiku, which may skip nuances in longer instruction sets.

Can I update a skill without restarting Claude Code?

Yes. Skills are read from disk each time they're triggered. Edit the SKILL.md, save it, and the next time you type the trigger command, Claude loads the updated version. No restart needed.

Is there a way to share skills privately with a team?

Put the skill directory in a shared location (git repo, shared drive, or internal package registry). Each team member symlinks or copies it to their ~/.claude/skills/ directory. There's no built-in team distribution yet, but git-based sharing works well for most teams.

Related Reading

• Best Claude Code Skills & Plugins (2026 Guide)
• How to Use Claude Code for Web Development (Complete Guide)
• Creative Coding with Claude: Beyond the Basics