Skip to main content

Lesson 5: Skills System

Learning Objectives​

After completing this lesson, you will be able to:

  • Understand what skills are and how they work
  • Use built-in skills effectively
  • Invoke skills with slash commands
  • Create your first custom skill
  • Understand skill structure and organization
  • Know where skills are located and how they're prioritized
  • Use skill hot-reload (automatic in 2.1.x) ⭐ NEW!

Prerequisites​

  • Completed Lessons 1-4 - Core Claude Code operations
  • Comfortable with chat mode - Basic conversational usage
  • Text editor ready - For creating skill files

Estimated Time: 25 minutes

⭐ Updated for 2.1.33: Includes skill hot-reload and advanced frontmatter!

What Are Skills?​

Skills are reusable, prompt-based commands that extend Claude Code's functionality. Think of them as custom shortcuts or macros for common tasks.

Why Skills Exist​

Reusability:

  • Execute complex tasks with a single command
  • Share workflows across teams
  • Build a library of useful operations

Consistency:

  • Same prompt produces consistent results
  • Standardized approaches to common tasks
  • Team alignment on workflows

Efficiency:

  • Don't repeat complex instructions
  • One command instead of multiple steps
  • Faster workflows

Skill vs. Regular Prompt​

Regular Prompt:

You> I want you to create a git commit with a conventional commit message.
Make sure to follow the conventional commit format with type, scope,
and subject. Also include Co-Authored-By: Claude...

Skill:

You> /commit

Both accomplish the same thing, but the skill is much faster!

Built-in Skills Overview​

Claude Code comes with several built-in skills ready to use.

Commit Skill​

Purpose: Create git commits with formatted messages

Usage:

You> /commit

What it does:

  • Checks git status
  • Stages changes
  • Creates a conventional commit message
  • Includes proper attribution
  • Creates the commit

Example output:

You> /commit

[Git operations shown]
Commit created: feat: add user authentication flow

Memory Skill​

Purpose: Edit the CLAUDE.md file for project context

Usage:

You> /memory

What it does:

  • Opens CLAUDE.md for editing
  • Adds project-specific context
  • Helps Claude remember important information

Example:

You> /memory

Claude: I'll open CLAUDE.md where you can add context about this project
that I should remember across sessions.

Config Skill​

Purpose: Interactive configuration setup

Usage:

You> /config

What it does:

  • Guides you through settings
  • Creates configuration files
  • Sets up project-specific options

Stats Skill​

Purpose: Show session statistics and costs

Usage:

You> /stats

What it does:

  • Shows token usage
  • Displays API costs
  • Session duration
  • Number of operations

Other Built-in Skills​

  • /exit - Exit the session
  • /help - Show help information
  • /plan - Enter plan mode
  • /mode - Change permission mode

Invoking Skills with /​

All skills are invoked using the slash (/) prefix.

Basic Invocation​

You> /skill-name

Skills with Arguments​

Some skills accept arguments:

You> /commit -m "Fix login bug"

Discovering Available Skills​

Method 1: Help command

You> /help skills

Method 2: List skills directory

ls ~/.claude/skills/

Method 3: Ask Claude

You> What skills are available?

Creating Your First Custom Skill​

Let's create a simple skill for a common task.

Skill Concept: Code Review​

We'll create a skill that performs a standard code review.

Step 1: Choose Skill Location​

Skills are searched in this order:

  1. Project skills: /.claude/skills/
  2. User skills: ~/.claude/skills/
  3. Managed skills: Installation directory

Step 2: Create Skill Directory​

mkdir -p ~/.claude/skills/review

Step 3: Create SKILL.md​

Create ~/.claude/skills/review/SKILL.md:

# Code Review

Perform a comprehensive code review of the specified file or directory.

## Usage

/review [file-or-directory]

## Examples

/review src/main.py
/review .
/review @src/auth.js

## What to Check

- Code quality and readability
- Potential bugs or issues
- Security vulnerabilities
- Performance concerns
- Best practices violations
- Missing error handling
- Documentation completeness

## Output Format

Provide a structured review with:
1. Summary (2-3 sentences)
2. Issues found (categorized by severity)
3. Positive observations
4. Specific recommendations
5. Code examples for improvements (if applicable)

Step 4: Test the Skill​

claude
You> /review @sample.py

Claude: [Performs comprehensive code review following your guidelines]

Skill Structure​

Skills have a specific structure that defines how they work.

Required Files​

SKILL.md (Required)

  • Defines the skill's behavior
  • Contains instructions for Claude
  • Written in markdown
  • Can include examples, guidelines, templates

Optional Components​

examples/ (Optional)

  • Sample inputs and outputs
  • Demonstration use cases
  • Test cases

scripts/ (Optional)

  • Shell scripts or utilities
  • Helper programs
  • Automation logic

README.md (Optional)

  • Documentation for users
  • Installation instructions
  • Usage examples

Complete Skill Example​

my-skill/
├── SKILL.md          # Required: Instructions for Claude
├── README.md         # Optional: User documentation
├── examples/         # Optional: Example usage
│   ├── input1.txt
│   └── output1.txt
└── scripts/          # Optional: Helper scripts
    └── helper.sh

Skill Locations and Priority​

Claude Code searches for skills in multiple locations with specific priority.

Search Order (Highest to Lowest Priority)​

  1. Project Skills (./.claude/skills/)

    • Specific to current project
    • Highest priority
    • Override other skills with same name
    • Git-tracked with your project

  2. User Skills (~/.claude/skills/)

    • Personal skills
    • Available in all projects
    • Good for personal workflows
    • Not shared with team

  3. Managed Skills (Installation directory)

    • Built-in skills
    • Lowest priority
    • Overridden by project/user skills

Practical Implications​

Scenario: You have a /test skill in multiple locations

Project: /.claude/skills/test/SKILL.md
User:    ~/.claude/skills/test/SKILL.md
Managed: (installation)/skills/test/SKILL.md

Result: The project skill is used.

Project-specific skills:

my-project/
└── .claude/
    └── skills/
        ├── deploy/      # Project deployment
        └── db-migrate/  # Database migrations

Personal skills:

~/.claude/skills/
├── review/      # Your code review style
├── refactor/    # Your refactoring preferences
└── document/    # Your documentation format

⭐ Skill Hot-Reload (NEW in 2.1.x!)​

What is Hot-Reload?​

Before 2.1.x, you had to restart Claude Code to see skill changes.

2.1.x and later: Skills are automatically reloaded when modified!

How It Works​

Automatic detection:

.claude/skills/
├── refactor.md
├── test.md
└── deploy.md

[You edit refactor.md]

Claude Code detects file change → Reloads skill instantly → Skill ready to use

No restart needed!

Supported Locations​

Hot-reload works for skills in:

  • ~/.claude/skills/ - User-level skills
  • .claude/skills/ - Project-level skills
  • Nested .claude/skills/ - Subdirectory skills

Hot-Reload in Action​

You: Edit the test skill to include coverage reporting

[You open ~/.claude/skills/test.md]
[Add coverage reporting instructions]
[Save file]

Claude: I've detected an update to the test skill.
The skill has been reloaded and is ready to use.

You: /test

Claude: [Running updated test skill with coverage reporting]

Rapid Development Workflow​

Before (old behavior):

# Edit skill file
vim ~/.claude/skills/refactor.md

# Restart Claude Code
exit
claude

# Now skill is updated

After (2.1.x behavior):

# Edit skill file
vim ~/.claude/skills/refactor.md

# Skill is immediately available!
# No restart needed

Development Loop​

# Development loop
vim ~/.claude/skills/feature.md  # Edit
/feature                          # Test
vim ~/.claude/skills/feature.md  # Edit again
/feature                          # Test again

For more advanced skill features (context forking, language settings, agent specification), see Lesson 19: Forked Context & Advanced Skills.

Advanced Skill Creation​

Let's create a more sophisticated skill.

Skill: Feature Template​

Create a skill that scaffolds new features consistently.

Step 1: Create Skill Structure​

mkdir -p ~/.claude/skills/feature

Step 2: Write SKILL.md​

~/.claude/skills/feature/SKILL.md:

# Feature Scaffolder

Create a new feature following our project's architecture patterns.

## Usage

/feature <feature-name> <description>

## Examples

/feature user-auth "Add JWT authentication"
/feature payment-processing "Integrate Stripe payments"

## Checklist

When creating a feature, ensure:

1. **Directory Structure:**
   - Create `src/features/<feature-name>/`
   - Add: `api.py`, `models.py`, `utils.py`

2. **Files to Create:**
   - API endpoints in `api.py`
   - Data models in `models.py`
   - Helper functions in `utils.py`
   - Tests in `tests/test_<feature-name>.py`

3. **Code Standards:**
   - Include type hints
   - Add docstrings to all functions
   - Implement error handling
   - Add logging statements

4. **Documentation:**
   - Create `docs/features/<feature-name>.md`
   - Document API endpoints
   - Include usage examples

5. **Integration:**
   - Register routes in main app
   - Add database migrations if needed
   - Update API documentation

## Project Context

This project uses:
- Framework: FastAPI
- Database: PostgreSQL with SQLAlchemy
- Testing: pytest
- Style: Black formatting

Step 3: Add Example​

~/.claude/skills/feature/examples/input.txt:

/feature user-profile "Add user profile management with avatar upload"

Step 4: Use the Skill​

claude
You> /feature email-notifications "Add email notification system"

Claude: I'll create the email-notifications feature following our project patterns.

[Claude creates the directory structure, files, tests, and documentation]

Practical Example: Using Built-in Skills​

Let's practice with the built-in skills.

Exercise 5.1: Memory Skill​

  1. Navigate to your test project:

    cd ~/claude-test/hello-world
    claude

  2. Use the memory skill:

    You> /memory

  3. Add project context: Claude will open/create CLAUDE.md. Add:

    # Hello World Project

    This is a learning project for Claude Code.

    ## Project Structure
    - hello.py - Main greeting script
    - utils/ - Utility functions

    ## Goals
    - Learn Claude Code basics
    - Practice file operations
    - Understand permissions

  4. Verify Claude remembers:

    You> What is this project about?
    [Claude uses context from CLAUDE.md]

Exercise 5.2: Commit Skill​

  1. Make a change:

    You> Add a comment to hello.py explaining what it does

  2. Review and approve the edit

  3. Commit with the skill:

    You> /commit

  4. Observe the commit message Claude will create a properly formatted commit.

Exercise 5.3: Stats Skill​

You> /stats

Review your session statistics.

✅ Check Your Understanding​

  1. What is a skill?

    • A programming language
    • A reusable prompt-based command
    • A file type
    • A keyboard shortcut

  2. Where are project-specific skills stored?

    • ~/claude/skills/
    • ./.claude/skills/
    • /usr/share/claude/skills/
    • ./skills/

  3. Which skill creates git commits?

    • /git
    • /commit
    • /save
    • /store

  4. True or False: User skills override project skills with the same name.

    • True
    • False

  5. What file is required in every skill?

    • README.md
    • script.sh
    • SKILL.md
    • config.json

Answers: 1-b, 2-b, 3-b, 4-False (project overrides user), 5-c

Summary​

In this lesson, you learned:

  • What skills are - Reusable prompt-based commands
  • Built-in skills - /commit, /memory, /config, /stats
  • Invoking skills - Use /skill-name syntax
  • Creating skills - SKILL.md file with instructions
  • Skill structure - SKILL.md required, others optional
  • Skill locations - Project > User > Managed priority

Next Steps​

In Lesson 6: Configuration and Settings, you'll learn:

  • Different settings scopes
  • Creating configuration files
  • Common settings to customize
  • Environment variables
  • CLAUDE.md for project context

Further Reading​

Continue to Lesson 6: Configuration and Settings →