Building Skills for Claude Code: A Practical Guide

If you’ve used Claude Code for a while, you’ve probably noticed a pattern: you keep explaining the same workflows over and over. “When I say deploy, run these three commands in order.” “Always check for linting errors before committing.” “Use our team’s PR template, not the default.”

Skills solve this. A skill is a set of instructions, packaged as a simple folder, that teaches Claude how to handle specific tasks or workflows. Instead of re-explaining your preferences in every conversation, you teach Claude once and benefit every time.

Anthropic recently published The Complete Guide to Building Skills for Claude, and I’ve been building skills for my own workflows for a while now. This post walks through the process of creating a skill from scratch, covering the concepts that actually matter in practice.

What Is a Skill?

At its core, a skill is a folder containing a SKILL.md file with YAML frontmatter and Markdown instructions. That’s the minimum. Optionally, you can include scripts, reference documentation, and templates:

your-skill-name/
├── SKILL.md                    # Required - main skill file
├── scripts/                    # Optional - executable code
│   ├── process_data.py
│   └── validate.sh
├── references/                 # Optional - documentation
│   ├── api-guide.md
│   └── examples/
└── assets/                     # Optional - templates, etc.
    └── report-template.md

The key insight from Anthropic’s guide is progressive disclosure. Skills use a three-level system:

YAML frontmatter is always loaded in Claude’s system prompt. This is how Claude decides whether to use the skill at all.
SKILL.md body is loaded only when Claude thinks the skill is relevant. Contains the full instructions.
Linked files are additional files in the skill directory that Claude can discover and read as needed.

This matters because context window space is limited. A well-structured skill loads the minimum information needed and pulls in details on demand.

Building a Skill: Step by Step

Let’s build a practical skill: a changelog generator that creates consistent, well-formatted changelogs from git history. This is the kind of repetitive task that benefits most from a skill. It has a clear workflow, specific formatting requirements, and you want it done the same way every time.

Step 1: Define the Use Case

Before writing any instructions, the guide recommends identifying 2-3 concrete use cases. For our changelog skill:

Use Case: Generate Release Changelog
Trigger: User says "generate changelog", "what changed since last
release", or "prepare release notes"
Steps:
1. Identify the last release tag
2. Collect commits since that tag
3. Categorize changes (features, fixes, breaking changes)
4. Format as markdown changelog
Result: Well-structured changelog ready for the release

Ask yourself:

What does the user want to accomplish?
What multi-step workflow does this require?
Which tools are needed (built-in shell commands, git)?
What domain knowledge or formatting rules should be embedded?

Step 2: Write the Frontmatter

The YAML frontmatter is the most important part. It’s the only thing Claude sees when deciding whether to load your skill. Get this wrong and your skill either never triggers or triggers on everything.

---
name: changelog-generator
description: Generates well-formatted changelogs from git commit
  history. Use when user asks to "generate changelog", "prepare
  release notes", "what changed since last release", or wants to
  summarize recent commits for a release.
---

A few rules to follow:

name must be kebab-case. No spaces, no capitals, no underscores.

# Good
name: changelog-generator

# Bad - these will all fail
name: Changelog Generator
name: changelog_generator
name: ChangelogGenerator

description must include both what the skill does and when to use it. This is the pattern Anthropic recommends:

[What it does] + [When to use it] + [Key capabilities]

Here’s the difference between descriptions that work and ones that don’t:

# Too vague - Claude won't know when to trigger this
description: Helps with changelogs.

# Missing triggers - Claude won't match user phrases
description: Creates sophisticated multi-format changelogs
  with categorization support.

# Good - specific about what AND when
description: Generates well-formatted changelogs from git commit
  history. Use when user asks to "generate changelog", "prepare
  release notes", or wants to summarize recent commits for a release.

The description has a 1024 character limit, and XML angle brackets (< >) are forbidden for security reasons.

Step 3: Write the Instructions

After the frontmatter comes the actual instruction body in Markdown. Here’s the complete SKILL.md for our changelog skill:

---
name: changelog-generator
description: Generates well-formatted changelogs from git commit
  history. Use when user asks to "generate changelog", "prepare
  release notes", "what changed since last release", or wants to
  summarize recent commits for a release.
---

# Changelog Generator

## Instructions

### Step 1: Identify the Version Range
Run `git tag --sort=-version:refname` to find the latest release
tag. If no tags exist, use the initial commit as the starting point.

Confirm the version range with the user before proceeding:
"I'll generate the changelog from [last tag] to HEAD. OK?"

### Step 2: Collect Commits
Run `git log [last-tag]..HEAD --oneline --no-merges` to get the
commit list.

### Step 3: Categorize Changes
Group commits into these categories based on conventional commit
prefixes:

- **Breaking Changes** - commits with `BREAKING CHANGE` in the
  body or `!` after the type
- **Features** - commits starting with `feat:`
- **Bug Fixes** - commits starting with `fix:`
- **Other Changes** - everything else (chore, docs, refactor, etc.)

If commits don't follow conventional commit format, categorize
by reading the commit message content.

### Step 4: Format the Changelog
Use this exact format:

## [version] - YYYY-MM-DD

### Breaking Changes
- Description of breaking change ([commit-hash])

### Features
- Description of feature ([commit-hash])

### Bug Fixes
- Description of fix ([commit-hash])

### Other Changes
- Description of change ([commit-hash])

Rules:
- Rewrite commit messages to be human-readable (not just the raw
  commit message)
- Include the short commit hash as a reference
- Omit empty categories
- Sort entries within each category alphabetically

### Step 5: Present and Confirm
Show the generated changelog to the user. Ask if they want to:
1. Save it to CHANGELOG.md (prepend to existing content)
2. Copy it for use elsewhere
3. Adjust any entries

## Common Issues

### No Git Tags Found
If `git tag` returns nothing:
1. Ask the user for a starting commit or date
2. Use `git log --after="YYYY-MM-DD"` as an alternative

### Non-Standard Commit Messages
If commits don't follow any convention:
- Group by file paths changed (feature area)
- Use the commit message as-is but clean up formatting

Notice a few things about the instruction style:

Commands are specific and actionable. Instead of “check the git history,” the skill says exactly which command to run: git log [last-tag]..HEAD --oneline --no-merges.

The format is explicit. Rather than “format it nicely,” there’s a literal template showing the expected output structure.

Error handling is included. The “Common Issues” section tells Claude what to do when things don’t go as expected: no tags found, messy commit messages, etc.

There’s a confirmation step. Step 1 asks the user to confirm before proceeding, and Step 5 gives options for what to do with the result. This keeps the user in control.

The Three Skill Categories

Anthropic identifies three main categories of skills. Understanding which one you’re building helps you choose the right patterns.

Document and Asset Creation

Creating consistent output: documents, code, designs, reports. The changelog skill above falls into this category.

Key techniques:

Embedded formatting standards
Template structures for consistent output
Quality checklists before finalizing

Workflow Automation

Multi-step processes that benefit from consistent methodology, including coordination across multiple tools.

Example: a sprint planning skill that fetches project status, analyzes capacity, suggests priorities, and creates tasks. All in a specific sequence with validation at each step.

Key techniques:

Step-by-step workflow with validation gates
Templates for common structures
Built-in review and improvement suggestions

MCP Enhancement

If you’re already using MCP servers, skills act as a knowledge layer on top. MCP provides the tools (connectivity to services like Linear, Notion, GitHub), while skills provide the recipes (how to use those tools effectively).

Think of it like a professional kitchen: MCP gives you the equipment and ingredients, skills give you the recipes.

Writing Instructions That Actually Work

After iterating on several skills, here are the patterns that make the biggest difference:

Be Specific, Not Vague

# Good
Run `python scripts/validate.py --input {filename}` to check
data format.
If validation fails, common issues include:
- Missing required fields (add them to the CSV)
- Invalid date formats (use YYYY-MM-DD)

# Bad
Validate the data before proceeding.

The bad version gives Claude no actionable information. The good version tells it exactly what to run and what to expect.

Use Progressive Disclosure

Keep the main SKILL.md focused on core instructions. Move detailed documentation into references/ files and link to them:

Before writing queries, consult `references/api-patterns.md` for:
- Rate limiting guidance
- Pagination patterns
- Error codes and handling

This prevents your skill from consuming excessive context window space. Anthropic recommends keeping SKILL.md under 5,000 words.

Include Error Handling

## Common Issues

### MCP Connection Failed
If you see "Connection refused":
1. Verify MCP server is running: Check Settings > Extensions
2. Confirm API key is valid
3. Try reconnecting: Settings > Extensions > [Service] > Reconnect

Without error handling instructions, Claude will either guess at solutions or ask the user what to do. Both of which defeat the purpose of having a skill.

Fight Model Laziness

Claude sometimes takes shortcuts on complex tasks. The guide suggests adding explicit encouragement:

## Performance Notes
- Take your time to do this thoroughly
- Quality is more important than speed
- Do not skip validation steps

This might feel odd, but it genuinely helps with multi-step workflows where Claude might otherwise cut corners.

Testing Your Skill

The guide recommends testing across three areas:

1. Triggering Tests

Does your skill load at the right times?

Should trigger:
- "Generate a changelog for the release"
- "What changed since v2.1.0?"
- "Prepare release notes"

Should NOT trigger:
- "What's the weather?"
- "Help me write Python code"
- "Create a git branch"

A useful debugging technique: ask Claude “When would you use the changelog-generator skill?” It’ll quote the description back and explain its reasoning. If something is missing, adjust the description.

2. Functional Tests

Does the skill produce correct output? Run the same request 3-5 times and compare results for consistency. Check that:

Outputs match the expected format
All steps in the workflow execute
Error handling works when things go wrong

3. Performance Comparison

Compare results with and without the skill enabled. A good skill should reduce the number of back-and-forth messages, eliminate failed tool calls, and produce more consistent output.

Iteration Signals

Skills are living documents. Watch for these signals:

Undertriggering means the skill doesn’t load when it should. Users have to manually invoke it. Fix: add more trigger phrases and keywords to the description.

Overtriggering means the skill loads for unrelated queries. Fix: add negative triggers to the description (“Do NOT use for simple data exploration”) and be more specific about scope.

Instructions not followed means Claude loads the skill but doesn’t follow the instructions. Common causes:

Instructions are too verbose (use bullet points, not paragraphs)
Critical instructions are buried in the middle (put them at the top)
Language is ambiguous (“Make sure to validate things properly” vs “CRITICAL: Before proceeding, verify that the project name is non-empty”)

Distribution

Once your skill works, there are a few ways to share it:

Personal use: Place the skill folder in your Claude Code skills directory (~/.claude/skills/) or upload it via Claude.ai Settings > Capabilities > Skills.

Team use: Admins can deploy skills workspace-wide with automatic updates and centralized management.

Open source: Host on GitHub with a clear README, installation instructions, and example usage. Note that the README is for human readers, separate from the SKILL.md that Claude reads.

Skills are also available via the API for programmatic use cases, using the /v1/skills endpoint and container.skills parameter in Messages API requests.

Quick Checklist

Before uploading your skill, run through this:

Getting Started

The investment in building a skill pays off quickly if you have workflows you repeat across conversations. The key principles are straightforward: make the frontmatter descriptive enough for Claude to know when to use the skill, make the instructions specific enough that Claude knows how to execute the workflow, and iterate based on real usage.

Start with your most repeated workflow, the one where you find yourself typing the same instructions every session. Build a skill for that, test it, and iterate. Once you have one working well, the pattern becomes second nature.

For the full guide with additional patterns and examples, check out Anthropic’s Complete Guide to Building Skills for Claude. And for ready-made skills you can customize, browse the public skills repository.