Welcome to this course on extending Claude's capabilities! In this first unit, we'll explore one of Claude Code's most powerful features: the Skills system.

Think of Skills as specialized expertise Claude can apply automatically. Instead of explaining your analysis methodology every time you need to analyze data, or repeating your documentation standards whenever you write docs, you can package these instructions into Skills. Then, when you ask Claude to analyze data or write documentation, it automatically applies your methodology without you needing to invoke a specific command.

In this lesson, we'll understand what Skills are, how Claude discovers and uses them, and when to create them. By the end, you'll have a solid foundation for building your own Skills in the upcoming practice sections.

Skills are packaged instructions that extend Claude's capabilities for specific tasks. Instead of explaining the same workflow repeatedly, you create a Skill that Claude can reference and apply automatically when relevant.

Here's what makes Skills special:

• Self-contained: Each Skill is a directory with instructions for a specific task
• Reusable: Once created, a Skill works across multiple sessions
• Automatic: Claude selects and applies Skills based on your request, without you manually triggering them

For example, imagine you frequently analyze CSV data with specific statistical methods and reporting requirements. Create a CSV analysis Skill, and when you say "analyze this sales data," Claude automatically applies your methodology — no need to explain your process each time.

Your project knowledge can't all load at once. If Claude tried to remember every detail about every possible task at session start, the context would be overwhelming and most of it would be irrelevant to what you're actually doing.

Here's how different approaches handle this:

Your CLAUDE.md might say "use async/await" — that's always relevant. But detailed CSV analysis procedures with statistical methods, insight generation, and reporting formats? Those only matter when you're actually analyzing data. Skills keep specialized expertise available without cluttering your base context.

Skills live in two locations:

Precedence: When a project Skill and a personal Skill share the same name, the project-level Skill takes priority. This lets you override a personal Skill with a project-specific version without modifying your global setup. If two Skills have different names but overlapping descriptions, Claude may select either one — avoid ambiguous descriptions across both locations to prevent unpredictable selection.

When you start a session, Claude scans these directories and reads a brief description from each Skill. This gives Claude a lightweight index of available capabilities. When you make a request, checks if any descriptions match what you're asking for. If there's a match, loads that full instructions.

Understanding how Claude scans for Skills helps you troubleshoot when Skills aren't being detected:

What Gets Scanned:

• Claude scans only the immediate subdirectories of .claude/skills/ and ~/.claude/skills/
• Each subdirectory should contain one SKILL.md file
• Nested subdirectories within a Skill folder are ignored during scanning

Example structure:

Error Handling:

• If SKILL.md is missing from a directory, that directory is skipped
• If SKILL.md has invalid frontmatter syntax, Claude may skip that Skill or report an error
• Missing required fields (name, description, ) prevent the from loading

Let's see what we have in a fresh environment:

The output shows:

You start with no Skills. This is intentional — Claude Code expects you to build the Skills your projects need, rather than providing generic ones that might not fit your workflow.

A Skill is simply a folder with a special file inside. The folder name becomes the Skill's identifier:

The SKILL.md file is the only required component. You can add supporting files later (templates, examples, reference docs), but you start with just this one file.

Every SKILL.md file has two parts:

1. Frontmatter - Metadata that helps Claude know when to use this Skill:

2. Instructions - The actual guidance Claude follows:

The frontmatter tells Claude about the Skill, and the instructions tell Claude what to do when using it.

Let's break down the three essential frontmatter fields:

name: A unique identifier for the Skill

• Should match the directory name
• Use lowercase with hyphens
• Example: csv-analyzer, api-tester, doc-generator

description: Tells Claude when to select this Skill

• Be specific about what the Skill does
• Include keywords users might say
• Example: "Analyze CSV data and generate summary statistics with insights"

allowed-tools: Which capabilities this Skill can use

• Limits what the Skill can do (security)
• Common tools: Read, Write, Edit, Bash
• Only include what's needed

The description is especially important because it guides automatic selection. When you ask to "analyze this sales data," checks which descriptions match your request.

After the frontmatter, you write instructions in clear markdown. A good pattern is:

The When to Use section helps Claude recognize appropriate situations. The Process section provides step-by-step guidance. The Example section shows concrete reference material.

Keep instructions clear and sequential. The better organized your instructions, the more effectively Claude can apply the Skill.

When you make a request, here's what happens:

1. Claude reads your request: "Analyze this sales CSV and give me insights"
2. Claude checks available Skill descriptions for matches
3. If csv-analyzer description mentions "analyze" and "CSV", it's a match
4. Claude asks permission to use the Skill
5. After approval, Claude follows the Skill's instructions

You don't type /csv-analyzer to invoke it. Claude figures out which Skill to use based on what you're asking for. This is what makes Skills powerful — they work automatically when relevant.

A common question: When should I use CLAUDE.md versus creating a Skill?

Use CLAUDE.md for universal project rules:

• Coding style guidelines (e.g., "Always use async/await")
• Tech stack information
• Standards that apply to all work
• General project conventions

Use Skills for specific, repeatable tasks:

• CSV data analysis with specific statistical methods
• Testing methodology with particular steps
• Documentation generation with template patterns
• Any specialized workflow you repeat regularly

Think of CLAUDE.md as your project's constitution — general rules that always apply. Skills are specialized procedures for particular jobs that only load when needed.

In this lesson, we've explored the Skills system: what Skills are, how Claude discovers and selects them automatically, and how they differ from CLAUDE.md. We've examined the structure of a Skill file with frontmatter and instructions, and we understand why Skills load expertise on-demand.

The key takeaway is that Skills give you a way to package specialized knowledge that Claude can apply automatically when relevant. They keep your context clean while making powerful, domain-specific capabilities available exactly when needed.

Now it's time to build! In the next lesson, you'll create your first complete Skills from scratch — a data analysis Skill and a visualization standards Skill. You'll write the frontmatter, define the instructions, and watch Claude automatically select and apply them. Let's put this knowledge into practice!