<aside> ⚡

This is the complete, updated guide (March 2026) — covers Skills from zero to production, with real examples, community resources, YouTube tutorials, and copy-paste templates you can use today.

</aside>

What Are Claude Code Skills?

A Claude Code Skill is a **SKILL.md file** that packages specialized instructions, context, and workflows into a reusable module. Think of it like hiring a specialist — instead of explaining your requirements every single session, you write them once and Claude follows them automatically, every time.

Without Skills

Repeat the same context every session
Inconsistent outputs across runs
Claude forgets your preferences
One-size-fits-all behavior

With Skills

Claude loads your rules automatically
Consistent, predictable results always
Persistent domain knowledge built in
Specialist behavior on demand

<aside> 💡

Key insight from the Anthropic docs: Skills are NOT tools that execute and return results. They are instruction sets that modify how Claude processes requests — loading into context and changing execution environment before Claude continues the conversation.

</aside>

How Skills Work Under the Hood

Understanding the architecture helps you build better skills.

The Progressive Disclosure System (how Claude loads skills efficiently)
How Claude decides which skill to invoke
The two-message invocation pattern

The Full File Structure

your-project/
├── CLAUDE.md                    ← Claude's memory (loads every session)
└── .claude/
    ├── settings.json            ← Permissions, hooks, model config
    ├── settings.local.json      ← Your personal settings (gitignored)
    ├── rules/                   ← Path-scoped modular instructions
    │   ├── api-rules.md
    │   └── testing-rules.md
    ├── skills/                  ← Reusable skills (invoke with /skill-name)
    │   └── my-skill/
    │       ├── SKILL.md         ← Required: main instruction file
    │       ├── scripts/         ← Optional: executable scripts
    │       │   └── helper.py
    │       ├── resources/       ← Optional: reference files
    │       │   └── template.json
    │       └── examples/        ← Optional: sample outputs
    │           └── sample.md
    ├── agents/                  ← Specialized sub-agents
    └── .mcp.json                ← External tool integrations

~/.claude/                       ← User-level (applies to ALL projects)
├── CLAUDE.md                    ← Your global personal preferences
└── skills/                      ← Skills available in every project
    └── my-global-skill/
        └── SKILL.md

<aside> 📌

Skill discovery paths — Claude Code scans these locations in order:

~/.config/claude/skills/ — user settings
~/.claude/skills/ — user home
.claude/skills/ — project-level
Plugin-provided skills
Built-in Anthropic skills </aside>