Claude Code Skills Tutorial: Build Custom Skills From Scratch (2026)

What Are Claude Code Skills?

A Claude Code skill is a folder containing a SKILL.md file with YAML frontmatter and markdown instructions. When Claude detects a relevant conversation topic, it loads the skill automatically. You can also invoke any skill directly by typing /skill-name in the CLI. Skills follow the open Agent Skills standard at agentskills.io, which means they work across multiple AI coding tools -- not just Claude Code.

According to Anthropic's documentation, the official frontend-design skill alone has over 277,000 installs as of March 2026. The skill ecosystem includes bundled skills like /simplify, /debug, and /batch, plus thousands of community-contributed skills.

Skills vs CLAUDE.md vs Slash Commands

Claude Code has three customization layers that serve different purposes. Choosing wrong means either wasted context tokens or instructions Claude never sees. Here is exactly when to use each.

The rule of thumb: if it is a fact or a one-line convention, put it in CLAUDE.md. If it is a procedure with steps, make it a skill. If CLAUDE.md is over 500 lines, you almost certainly have procedures that should be skills.

Where Claude Code Skills Live

Skills can be stored at four levels, each with different scope and priority. When two skills share the same name, the higher-priority location wins. Understanding this hierarchy prevents naming conflicts and makes team distribution straightforward.

Create Your First Claude Code Skill (Step by Step)

This walkthrough creates a real, useful skill -- a code review checklist that Claude applies whenever you ask for a review. The entire process takes under 2 minutes.

Step 1: Create the directory

Step 2: Write the SKILL.md

Every skill needs exactly one file: SKILL.md. It has two parts -- YAML frontmatter between --- markers, then markdown instructions.

---
name: review-checklist
description: >
  Code review checklist for PRs. Use when reviewing
  code, checking pull requests, or when the user asks
  for a review.
---

When reviewing code, check every item:

## Security
- No hardcoded secrets or API keys
- Input validation on all user-facing endpoints
- SQL queries use parameterized statements

## Performance
- No N+1 queries in database calls
- Large lists use pagination or virtualization
- Expensive computations are memoized where appropriate

## Code Quality
- Functions do one thing and are under 50 lines
- Error handling is explicit, not swallowed
- Tests cover the happy path and at least one edge case

Step 3: Test it

No restart required -- Claude Code detects new skills in watched directories immediately. Test both invocation methods:

SKILL.md Frontmatter: Every Field Explained

The YAML frontmatter controls how Claude discovers, loads, and executes your skill. All fields are optional, but description is strongly recommended. Without it, Claude guesses from the first paragraph -- and guesses poorly.

5 Production-Ready Skill Examples

These are skills we use daily at KaiShips. Each one solves a real problem -- not a toy demo. Copy the SKILL.md content into the right directory and they work immediately.

---
name: deploy
description: Deploy to production safely
disable-model-invocation: true
allowed-tools: Bash(git *) Bash(npm *)
---

Deploy to production:
1. Run npm run build -- fail = stop
2. Run npm test -- fail = stop
3. git push origin main
4. Verify deploy at $ARGUMENTS or production URL

---
name: cc
description: >
  Create a conventional commit. Use when committing
  changes, staging files, or creating git commits.
allowed-tools: Bash(git *)
---

Create a conventional commit:
1. Run git diff --staged (if empty, stage relevant files)
2. Analyze changes and pick type: feat|fix|docs|refactor|test|chore
3. Write message: type(scope): description
4. Keep subject under 72 characters
5. Add body only if the "why" is non-obvious

---
name: deep-research
description: >
  Research a codebase topic thoroughly. Use when asked
  to explain how something works or investigate a system.
context: fork
agent: Explore
---

Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Map dependencies and data flow
4. Summarize findings with specific file references

---
name: pr-summary
description: Summarize the current PR with live data
context: fork
agent: Explore
allowed-tools: Bash(gh *)
---

## Live PR context
- Diff: !`gh pr diff`
- Comments: !`gh pr view --comments`
- Changed files: !`gh pr diff --name-only`

Summarize this PR: what changed, why, and
what reviewers should focus on.

---
name: api-conventions
description: >
  REST API patterns for this codebase. Use when writing
  or modifying API endpoints.
user-invocable: false
paths: "src/api/**/*.ts"
---

When writing API endpoints:
- Use RESTful naming: GET /users, POST /users, etc.
- Return { data, error, meta } envelope
- Validate with zod schemas at the handler level
- Errors: { error: { code: string, message: string } }
- Pagination: cursor-based, not offset-based

Advanced Skill Patterns

Once you have basic skills working, these patterns unlock the real power. Dynamic context injection, argument parsing, and supporting files turn simple instruction sets into complete automation workflows.

Directory structure for complex skills

my-skill/
  SKILL.md              # Main instructions (required)
  template.md           # Template for Claude to fill in
  examples/
    sample.md           # Example output format
  scripts/
    validate.sh         # Script Claude can execute
    visualize.py        # Generate HTML reports

Reference supporting files from SKILL.md so Claude knows what each one contains. Example: "For API details, see reference.md. For usage examples, see examples/sample.md." Claude loads them on demand, not upfront.

How Skills Load and Persist in Context

Understanding the skill lifecycle prevents a common frustration: skills that seem to stop working after 10-15 messages. Here is exactly what happens from invocation through auto-compaction.

Troubleshooting Claude Code Skills

Most skill issues come down to three causes: description mismatch, context budget overflow, or directory placement. Here are the fixes.

Frequently Asked Questions

Keep Learning

Skills are one piece of the Claude Code customization stack. These guides cover the rest.