How to Create Custom Skills in Claude Code: A Complete Guide

Mar 11, 2026

I kept typing the same prompts over and over. “Review this code for security issues.” “Write tests following TDD principles.” “Extract text from this PDF.” Each time, I’d paste my checklist, explain my preferences, and hope Claude remembered the context.

Then I discovered custom skills in Claude Code. Now I just run /security-review or /tdd-workflow and Claude immediately knows what to do.

What Are Claude Code Skills?

Skills are modular packages that extend Claude’s capabilities. Each skill contains a SKILL.md file with instructions, plus optional resources like scripts, documentation, and templates.

Think of skills as onboarding guides for specific tasks. They turn Claude from a general-purpose assistant into a specialist that understands your domain, follows your workflows, and has your resources ready.

What Skills Provide

Specialized workflows: Multi-step procedures for specific domains. A TDD skill guides Claude through the red-green-refactor cycle. A deployment skill walks through staging, testing, and production steps.

Tool integrations: Instructions for working with specific file formats or APIs. A PDF skill knows how to extract text and tables. A database skill understands query optimization patterns.

Domain expertise: Company-specific knowledge, schemas, and business logic. Your API conventions, your naming patterns, your architecture decisions.

Bundled resources: Scripts for deterministic tasks, documentation for reference, templates for output. Everything Claude needs, packaged together.

How Claude Loads Skills

Claude uses a progressive disclosure system:

Metadata (name + description): Always loaded in context (~100 words)
SKILL.md body: Loaded when the skill triggers (<5k words recommended)
Bundled resources: Loaded only when needed (no practical limit)

This architecture matters. You can include extensive documentation in references/ without bloating every conversation. Claude fetches those resources only when the task requires them.

The Anatomy of a Skill

A skill has one required file and optional resource directories:

my-skill/
├── SKILL.md              # Required: Instructions and metadata
└── resources/            # Optional: Supporting files
    ├── scripts/          # Python/Bash scripts for deterministic tasks
    ├── references/       # Documentation loaded as needed
    └── assets/           # Templates, images, boilerplate

The Required SKILL.md

The SKILL.md file starts with YAML frontmatter:

---
name: "my-skill"
description: "What this skill does and when to use it"
---

# Instructions

Your skill instructions go here.

The description field is critical. Claude reads this to decide when to trigger your skill. Include:

What the skill does
Specific triggers (file types, scenarios, tasks)
Keywords that should activate it

A vague description like “Helps with code” won’t trigger reliably. A specific description like “Security review for authentication code, API endpoints, and user input handling” will trigger when users mention those topics.

Optional Resource Directories

scripts/ — Put executable code here when you need deterministic reliability. If Claude must run the exact same operation every time, use a script. Examples: file transformations, API calls with specific parameters, data validation scripts.

references/ — Store documentation that Claude loads on demand. This keeps SKILL.md lean while providing deep context when needed. Examples: API documentation, schema definitions, style guides, architecture decision records.

assets/ — Place templates, logos, and boilerplate files here. Claude uses these for output generation. Examples: license file templates, configuration file templates, documentation templates.

Not every skill needs all three directories. A simple skill might only have a SKILL.md file. A complex skill might use all three.

Step-by-Step: Creating Your First Skill

Step 1: Understand What Your Skill Should Do

Before writing anything, answer these questions:

What functionality should this skill support?
How would users request this skill?
What phrases should trigger it?

For a database query helper skill, users might say:

“Help me write a complex SQL join”
“Optimize this slow query”
“Explain this database schema”

These phrases inform your description field.

Step 2: Plan Your Resources

For each use case, decide what resources help:

Same code rewritten often? Create a script in scripts/
Same documentation referenced? Add it to references/
Same templates used? Store them in assets/

Not every skill needs resources. A simple skill might only have a SKILL.md file.

Step 3: Initialize the Skill

Use the skill-creator tooling to scaffold your skill:

python scripts/init_skill.py my-skill --path ~/.claude/skills/

This creates:

my-skill/
├── SKILL.md
└── resources/
    ├── scripts/
    ├── references/
    └── assets/

The SKILL.md contains a template you can customize.

Step 4: Write the SKILL.md

Edit the frontmatter description first. This determines when Claude uses your skill:

---
name: "database-query-helper"
description: "SQL query assistance for writing joins, optimizing slow queries, and explaining schemas. Use when working with databases or SQL files."
---

Then write concise instructions in the body. Use imperative form:

# Database Query Helper

## Writing Complex Joins

1. Identify the tables involved
2. Determine join types (INNER, LEFT, RIGHT)
3. Specify join conditions clearly
4. Add appropriate indexes to the WHERE clause

## Query Optimization

Run EXPLAIN ANALYZE first. Look for:
- Sequential scans on large tables
- Missing indexes on join columns
- Inefficient subqueries

Best practices for the body:

Use imperative form (“Extract text” not “Extracting text”)
Keep under 500 lines
Include concrete code examples
Structure with clear headings
Each section should answer one question

Common mistakes to avoid:

Don’t write long introductions explaining what a database is
Don’t include “When to Use This Skill” sections (that’s the frontmatter’s job)
Don’t copy-paste entire documentation files into the body

Step 5: Package the Skill

Validate and package your skill for distribution:

python scripts/package_skill.py ~/.claude/skills/my-skill

This creates a .skill file you can share with teammates.

Step 6: Iterate

Use your skill on real tasks. Notice where Claude struggles or asks for clarification. Update the SKILL.md to address those gaps.

Skills improve with use. Your first version won’t be perfect, and that’s fine.

Real Examples: Skills in Action

Let me show you three skills I use regularly. Each demonstrates a different structure pattern.

PDF Processing Skill (Task-Based)

---
name: "pdf"
description: "PDF manipulation for extracting text/tables, creating, merging, splitting documents. Use when working with .pdf files for extraction, creation, or modification."
---

Structure: Quick Start → Merge → Split → Extract → Forms

Why this structure works: PDF operations are independent tasks. Users don’t need to merge a PDF before extracting text. Each section stands alone, so Claude jumps to the relevant operation.

How I use it: I run /pdf when I need to extract text from invoices, merge multiple reports, or split a large document into chapters. The skill has scripts for each operation in resources/scripts/.

TDD Workflow Skill (Workflow-Based)

---
name: "tdd-workflow"
description: "Use when writing new features, fixing bugs, or refactoring. Enforces test-driven development with 80%+ coverage including unit, integration, and E2E tests."
---

Structure: Principles → Workflow Steps → Test Patterns → Coverage

Why this structure works: TDD follows a strict sequence. You can’t refactor until tests pass. You can’t implement until tests fail. The workflow-based structure enforces this order.

How I use it: When I start a new feature, I run /tdd-workflow. Claude guides me through writing the test first, seeing it fail, then implementing the minimum code to pass. The skill includes test patterns in references/ for common scenarios.

Security Review Skill (Guidelines-Based)

---
name: "security-review"
description: "Use when adding authentication, handling user input, working with secrets, creating API endpoints, or implementing payment features. Provides security checklist and verification patterns."
---

Structure: Checklist → Patterns → Verification Steps

Why this structure works: Security isn’t a workflow. It’s a set of concerns you check. The checklist ensures nothing gets missed. The patterns show correct implementations. The verification steps confirm compliance.

How I use it: Before any commit, I run /security-review. Claude checks for hardcoded secrets, validates input handling, and verifies authentication patterns. The skill has a detailed checklist in the body and OWASP references in resources/references/.

Pro Tips for Effective Skills

Be Concise

The context window is a shared resource. Claude is already smart. Challenge each paragraph: does this justify its token cost?

Remove background explanations. Claude knows what a database is. Claude knows what TDD means. Your skill should focus on specifics: your conventions, your patterns, your requirements.

Set Appropriate Degrees of Freedom

Match the specificity of instructions to the task’s fragility:

High freedom (text instructions): Multiple valid approaches exist. Use for creative tasks, architecture decisions, code review. Claude can exercise judgment.
Medium freedom (pseudocode + patterns): Some patterns are preferred but not mandatory. Use for feature implementation, refactoring, documentation. Claude follows your style.
Low freedom (specific scripts): Operations are fragile and need exact code. Use for file transformations, API calls, data processing. Claude runs your scripts verbatim.

Choose the Right Structure

Workflow-based: For sequential processes with clear steps. The order matters. Each step builds on the previous. Examples: deployment pipelines, code review processes, incident response.

Task-based: For tool collections where users pick what they need. Tasks are independent. Users might only use one feature. Examples: file format handling, API utilities, data transformation.

Guidelines-based: For standards, checklists, and specifications. No specific order. Everything applies simultaneously. Examples: security requirements, code style guides, accessibility standards.

Test Your Description

After writing your skill, test the description. Ask yourself:

Would this trigger when I say the phrases I identified in Step 1?
Would this trigger when I mention the file types?
Would this not trigger for unrelated requests?

If the answer to any of these is “maybe,” refine the description. Be specific about triggers.

Iterate Based on Real Usage

Your first version won’t be perfect. Use the skill for a week. Notice where Claude:

Asks for clarification → Add details to that section
Makes wrong assumptions → Add explicit constraints
Misses edge cases → Add examples for those cases
Does something unexpected → Tighten the instructions

Skills evolve. The TDD skill I use today is the 12th revision. Each version fixed a real problem I encountered.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 skill-creator GitHub Repository
👨‍💻 Claude Code Official Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!