Claude Code Skills: The Complete Guide to Custom AI Behaviors in 2026

May 14, 2026 · Tutorial · 12 min read

If you're using Claude Code (Anthropic's CLI coding assistant), you've probably noticed it works well out of the box. But the real power comes from Skills — custom SKILL.md files that teach Claude specialized behaviors for your specific workflow.

In this guide, I'll cover everything: what Skills are, how they work, how to write your own, and where to find the best pre-built ones.

What Are Claude Code Skills?

A Skill is a Markdown file (SKILL.md) placed in your project's .claude/skills/ directory. When Claude Code starts a session, it loads these files as additional context, giving it domain-specific instructions.

Think of it like this: Claude is a smart generalist. Skills turn it into a specialist.

Example: Without vs. With Skills

Without a skill, if you ask Claude to review your code, it gives generic feedback.

With the Code Review Sensei skill, Claude knows to check for OWASP vulnerabilities, language-specific anti-patterns, performance traps, and architectural issues. It produces a structured report with severity ratings.

How Skills Work (Under the Hood)

When Claude Code starts, it scans for SKILL.md files in:

1. ~/.claude/skills/ — Global skills (apply to all projects)
2. .claude/skills/ — Project-specific skills
3. .claude/skills/*/SKILL.md — Namespaced skills

Each file becomes part of Claude's system context. The format is plain Markdown with structured sections:

# Skill Name

## Description
What this skill does.

## Instructions
Step-by-step instructions Claude follows.

## Examples
Concrete examples of input/output.

Creating Your First Skill

Let's build a simple PR description generator:

# Generate PR Description

## Description
Analyzes staged changes and writes a clear PR description.

## Instructions
1. Run `git diff --staged` to see pending changes
2. Categorize changes: new features, bug fixes, refactors, docs
3. Generate a PR description with:
   - Summary (2-3 sentences)
   - Changes list (grouped by type)
   - Breaking changes (if any)
   - Testing notes
4. Use conventional commit style

## Examples
User: "write a PR description"
AI: [generates structured description from staged diff]

Save this as .claude/skills/pr-description/SKILL.md and you're done. Next time you ask Claude to write a PR description, it follows your instructions.

The 5 Types of Skills You Should Have

1. Code Review Skills

A structured review skill catches bugs and security issues that Claude might miss in normal conversation. Look for one that covers OWASP Top 10 and has language-specific rules.

2. Architecture Skills

Skills that enforce project-specific patterns (e.g., "always use repository pattern in this project" or "React Server Components only, no client-side fetching").

3. Documentation Skills

Generate API docs, READMEs, and architecture guides that follow your team's style guide automatically.

4. DevOps Skills

Skills that understand your CI/CD pipeline and can generate deployment configs, Docker files, and monitoring setup.

5. Domain-Specific Skills

For specialized work: Chinese market content, SaaS pricing, data pipeline design, etc.

Pre-Built Skills (Save Time)

Instead of writing everything from scratch, check out these communities:

• YunDu AI Skills — 15 professional skills covering development, security, marketing, and Chinese market
• Claude Code Official — Anthropic's examples and documentation
• awesome-claude-skills — Community curated list of skills

Advanced Tips

Tip 1: Use Multiple Skills Together

Stack skills for compound effects. Example: Code Review Sensei + Security Audit Code Reviewer gives you both quality and security reviews in one pass.

Tip 2: Add Anti-Patterns

The best skills include an "anti-patterns" section — things Claude should not do. This is often more useful than positive instructions.

Tip 3: Version Your Skills

Keep skills in your git repo. When your project evolves, update the skills too. This creates a living knowledge base.

Tip 4: Test Skills with Examples

Include concrete examples in your SKILL.md. Claude follows examples more reliably than abstract instructions.

Common Mistakes

1. Too long: Skills over 200 lines dilute Claude's attention. Keep it focused.
2. Too vague: "Write good code" is useless. "Use repository pattern, always return Result" is useful.
3. No examples: Without examples, Claude interprets instructions differently than you expect.
4. Copy-pasting: A skill written for a REST API project won't work well for a GraphQL project. Customize.

Conclusion

Claude Code Skills are the single highest-leverage way to improve your AI-assisted coding. A well-crafted 50-line SKILL.md can save hours of back-and-forth with Claude and produce dramatically better output.

Start with one skill for your most repetitive task. Once you see the difference, you'll want skills for everything.

→ Browse 15 pre-built professional skills