Installing Your First Claude Code Skill: Step-by-Step Guide

You've heard about Claude Code skills—modular capabilities that supercharge your development workflow. Maybe you've seen developers automate code reviews, generate documentation, or manage Git workflows with a single command. Now you want in.

This guide walks you through installing your first skill from start to finish. No prior experience required. By the end, you'll have a working skill and understand the installation process well enough to add dozens more.

Prerequisites

Before we begin, ensure you have:

1. Claude Code CLI installed - If you haven't installed Claude Code yet, visit the official documentation for installation instructions
2. Terminal access - You'll be running commands in your terminal
3. A code project - Any project directory works; we'll use a simple example

Verify Your Claude Code Installation

Open your terminal and run:

claude --version

You should see version information like Claude Code v1.x.x. If you get a "command not found" error, Claude Code isn't installed correctly.

Understanding Skills: What Are You Installing?

Before installing anything, let's clarify what a skill actually is.

A skill is a packaged set of instructions that teaches Claude Code how to perform a specific task. Think of skills like browser extensions—they add new capabilities without changing the core application.

Skills can be:

• Commands - Slash commands like /commit or /review
• Agents - Autonomous workflows that make decisions
• Hooks - Automatic triggers that run on specific events
• MCP Servers - Connections to external tools and services

For your first installation, we'll start with a command—the most straightforward skill type.

Step 1: Choose Your First Skill

Let's install a practical skill that you'll actually use: the Commit Command skill. This skill helps you create well-formatted Git commits with AI-generated messages.

Why this skill?

• Immediately useful for any developer
• Simple to verify it's working
• Demonstrates core skill concepts

Step 2: Navigate to Your Project

Open your terminal and navigate to a project directory:

cd /path/to/your/project

Skills are typically installed at the project level, meaning they're available when you're working in that specific project. This keeps skills organized and prevents conflicts between different projects.

Step 3: Create the Skills Directory

Claude Code looks for skills in a specific location. Create the directory structure:

mkdir -p .claude/commands

This creates:

• .claude/ - The main Claude Code configuration directory
• .claude/commands/ - Where command skills live

Understanding the Directory Structure

Here's the full structure Claude Code uses:

your-project/
├── .claude/
│   ├── commands/     # Slash commands
│   ├── agents/       # Autonomous agents
│   ├── hooks/        # Event-triggered scripts
│   ├── skills/       # General skill definitions
│   └── settings.json # Project settings
└── your-code/

Step 4: Install the Skill

There are three ways to install a skill. We'll cover all three, starting with the simplest.

Method A: Direct Download (Recommended for Beginners)

Download the skill file directly into your commands directory:

curl -o .claude/commands/commit.md https://raw.githubusercontent.com/anthropics/claude-code-skills/main/commands/commit.md

Method B: Manual Creation

If you prefer to understand exactly what you're installing, create the file manually:

touch .claude/commands/commit.md

Then open .claude/commands/commit.md in your editor and add:

---
description: Create a well-formatted git commit with AI-generated message
---

# Commit Command

When the user runs /commit, help them create a Git commit:

1. Run `git status` to see current changes
2. Run `git diff --staged` to see what's staged (if anything)
3. If nothing is staged, ask if they want to stage all changes
4. Analyze the changes and generate a commit message that:
   - Starts with a type prefix (feat:, fix:, docs:, etc.)
   - Has a concise summary under 72 characters
   - Includes a body explaining the "why" if changes are complex
5. Show the proposed message and ask for confirmation
6. Execute the commit

Always follow conventional commit format.

Method C: Using a Package Manager (Advanced)

Some skill collections provide package managers. For example:

npx claude-skills install @claude-skills/commit

This method handles dependencies and updates automatically, but requires the skill author to publish to a registry.

Step 5: Verify the Installation

Let's confirm the skill is installed correctly.

Check the File Exists

ls -la .claude/commands/

You should see commit.md listed.

Check Claude Code Recognizes It

Start Claude Code in your project:

claude

Then type / to see available commands. You should see /commit in the list.

If you don't see it:

1. Make sure you're in the right project directory
2. Check the file has the .md extension
3. Verify the frontmatter (the --- section) is valid YAML

Step 6: Use Your New Skill

Now let's put the skill to work.

Make Some Changes

First, make a small change to any file in your project. For example:

echo "# Test" >> README.md

Stage the Changes

git add README.md

Run the Commit Skill

In Claude Code, type:

/commit

Claude will:

1. Check your staged changes
2. Analyze what you changed
3. Generate a commit message
4. Ask for your confirmation
5. Execute the commit

Verify the Commit

git log -1

You should see your new commit with an AI-generated message.

Troubleshooting Common Issues

"Command not found" Error

Symptom: Typing /commit shows "unknown command"

Solutions:

1. Restart Claude Code (exit then claude)
2. Check file is in .claude/commands/ not .claude/
3. Verify file extension is .md

"Permission denied" Error

Symptom: Can't create the .claude directory

Solutions:

1. Check you have write permissions: ls -la
2. Try with sudo (not recommended): sudo mkdir .claude
3. Check disk space: df -h

Skill Doesn't Behave as Expected

Symptom: The skill runs but doesn't do what you expect

Solutions:

1. Read the skill documentation
2. Check the skill file for required dependencies
3. Look for configuration options in the frontmatter

YAML Parsing Error

Symptom: Claude Code shows an error about invalid YAML

Solutions:

1. Check the frontmatter between --- markers
2. Ensure proper indentation (spaces, not tabs)
3. Quote strings with special characters

Installing Additional Skills

Now that you've mastered the process, here's how to discover and install more skills.

From AI Skill Market

Browse aiskill.market to find skills:

1. Search for a skill type or use case
2. Click on a skill to see details
3. Copy the installation command
4. Run it in your project

From GitHub Repositories

Many developers share skills on GitHub:

# Clone a skill collection
git clone https://github.com/user/skill-collection .claude-temp

# Copy the skills you want
cp .claude-temp/commands/review.md .claude/commands/

# Clean up
rm -rf .claude-temp

From Official Collections

Anthropic maintains official skill collections:

# Install from official repo
curl -o .claude/commands/review.md \
  https://raw.githubusercontent.com/anthropics/claude-code-skills/main/commands/review.md

Best Practices for Skill Management

Organize by Type

Keep your skills organized:

.claude/
├── commands/
│   ├── commit.md
│   ├── review.md
│   └── test.md
├── agents/
│   └── refactor-agent.md
└── hooks/
    └── pre-commit.md

Version Control Your Skills

Add .claude/ to your Git repository:

git add .claude/
git commit -m "Add Claude Code skills"

This lets your team share the same skills and tracks changes over time.

Document Custom Skills

If you modify a skill, add comments explaining why:

---
description: Commit command (customized for our team conventions)
# Modified 2025-01-18: Added JIRA ticket requirement
---

Regular Updates

Skills improve over time. Periodically update your skills:

# Re-download from source
curl -o .claude/commands/commit.md \
  https://raw.githubusercontent.com/source/commit.md

Understanding Skill Components

Now that you've installed a skill, let's understand what makes it work.

Frontmatter

The YAML block at the top defines metadata:

---
description: What this skill does
version: 1.0.0
author: skill-creator
---

Instructions

The markdown body contains instructions for Claude:

# Skill Name

When the user runs this skill, follow these steps:

1. First, do this
2. Then, do that
3. Finally, complete this

Conditional Logic

Skills can include conditions:

If the user is in a Git repository:
  - Run git status
  - Proceed with commit workflow

If not in a Git repository:
  - Inform the user
  - Suggest initializing Git

What's Next?

Congratulations! You've successfully installed your first Claude Code skill. Here's where to go from here:

Install More Skills

Try these popular skills next:

• Review - Code review automation
• Test - Generate unit tests
• Doc - Documentation generation

Create Your Own

Ready to build? Check out Creating Custom Skills for a complete guide.

Join the Community

• Browse skills at AI Skill Market
• Share your skills on GitHub
• Contribute to official collections

Quick Reference

Installation Commands

# Create skills directory
mkdir -p .claude/commands

# Download a skill
curl -o .claude/commands/SKILL.md URL

# List installed skills
ls .claude/commands/

# Start Claude Code
claude

# List available commands
/

Skill File Template

---
description: Brief description of what this skill does
---

# Skill Name

Instructions for Claude on how to execute this skill.

## Steps

1. First step
2. Second step
3. Third step

Troubleshooting Checklist

• Claude Code is installed (claude --version)
• You're in the right directory
• .claude/commands/ exists
• Skill file has .md extension
• Frontmatter YAML is valid
• You've restarted Claude Code

---

Now that you can install skills, learn to create your own custom skills and unlock the full potential of Claude Code.