🛠️ The Ultimate Guide to Agent Skills: Teaching Claude New Tricks

Last updated: January 2025 | Reading time: 25 minutes

This guide walks you through creating, using, and managing Agent Skills in Claude Code. Think of Skills as little bundles of expertise—organized folders packed with instructions, scripts, and resources that make Claude even smarter.

Before We Dive In

You'll need:

Claude Code version 1.0 or later
Some basic know-how with Claude Code

What's the Big Idea Behind Agent Skills?

Agent Skills are like teaching moments packaged into neat little capabilities. Each Skill has a SKILL.md file that Claude reads when it's relevant, plus any bonus files like scripts and templates you want to throw in.

The cool part about how Skills work: They're model-invoked—meaning Claude decides on its own when to bust them out based on what you're asking for and what the Skill says it can do. This is totally different from slash commands, which are user-invoked (you have to literally type /command to make them happen).

Why you'll love Skills:

Supercharge Claude for your specific workflows
Share your team's expertise through git
Stop repeating the same prompts over and over
Mix and match Skills for complex tasks

Want the full scoop? Check out the Agent Skills overview.

Creating Your First Skill

Skills live in directories with a SKILL.md file inside.

Personal Skills (Just for You)

Personal Skills work across all your projects. Stash them in ~/.claude/skills/:

Text

mkdir -p ~/.claude/skills/my-skill-name

Perfect for:

Your own quirky workflows and preferences
Experimental Skills you're tinkering with
Personal productivity hacks

Project Skills (Team Spirit)

Project Skills get shared with your whole crew. Keep them in .claude/skills/ within your project:

Text

mkdir -p .claude/skills/my-skill-name

Great for:

Team workflows and shared conventions
Project-specific know-how
Utilities and scripts everyone uses

Project Skills live in git, so they automatically show up for your teammates. Nice!

Plugin Skills (The Easy Route)

Skills can also come bundled with Claude Code plugins. When you install a plugin, any Skills it includes become available automatically. They work exactly like personal and project Skills.

Crafting Your SKILL.md File

Create a SKILL.md file with YAML frontmatter up top and Markdown below:

Text

---
name: Your Skill Name
description: Brief description of what this Skill does and when to use it
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

The description field is super important—it's how Claude figures out when to use your Skill. Make sure it explains both what the Skill does and when Claude should reach for it. For the full playbook, check out the best practices guide.

Adding Extra Goodies

Throw in some supporting files alongside SKILL.md:

Text

my-skill/
├── SKILL.md (gotta have this one)
├── reference.md (optional documentation)
├── examples.md (optional examples)
├── scripts/
│   └── helper.py (optional utility)
└── templates/
    └── template.txt (optional template)

Reference these files from SKILL.md:

Text

For advanced usage, see [reference.md](reference.md).

Run the helper script:
```bash
python scripts/helper.py input.txt
```

Claude only reads these files when it actually needs them, using progressive disclosure to keep things efficient. Smart!

Playing It Safe with allowed-tools

Use the allowed-tools frontmatter field to limit which tools Claude can use when a Skill is active:

Text

---
name: Safe File Reader
description: Read files without making changes. Use when you need read-only file access.
allowed-tools: Read, Grep, Glob
---

# Safe File Reader

This Skill provides read-only file access.

## Instructions
1. Use Read to view file contents
2. Use Grep to search within files
3. Use Glob to find files by pattern

When this Skill kicks in, Claude can only use those specific tools (Read, Grep, Glob) without asking permission first. This rocks for:

Read-only Skills that shouldn't touch your files
Skills with a narrow focus (like data analysis only, no file writing)
Security-conscious workflows where you want to lock things down

No allowed-tools specified? Claude will ask for permission to use tools like usual, following the standard permission model.

Heads up: allowed-tools only works for Skills in Claude Code.

Checking Out Available Skills

Claude automatically discovers Skills from three places:

Personal Skills: ~/.claude/skills/
Project Skills: .claude/skills/
Plugin Skills: bundled with installed plugins

To see all available Skills, just ask Claude:

Text

What Skills are available?

Text

List all available Skills

This shows everything from all sources, including plugin Skills.

To peek at a specific Skill, you can also check the filesystem:

Text

# List personal Skills
ls ~/.claude/skills/

# List project Skills (if in a project directory)
ls .claude/skills/

# View a specific Skill's content
cat ~/.claude/skills/my-skill/SKILL.md

Taking Your Skill for a Spin

After creating a Skill, test it by asking questions that match your description.

Example: If your description mentions "PDF files":

Text

Can you help me extract text from this PDF?

Claude decides on its own to use your Skill if it fits the request—you don't have to explicitly call it out. The Skill activates automatically based on what you're asking about.

When Things Go Sideways

If Claude isn't using your Skill, here are the usual suspects:

Make Your Description Pop

Too wishy-washy:

Text

description: Helps with documents

Nice and specific:

Text

description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.

Include both what the Skill does and when to use it in the description.

Double-Check the File Path

Personal Skills: ~/.claude/skills/skill-name/SKILL.md Project Skills: .claude/skills/skill-name/SKILL.md

Verify the file exists:

Text

# Personal
ls ~/.claude/skills/my-skill/SKILL.md

# Project
ls .claude/skills/my-skill/SKILL.md

YAML Syntax Check

Bad YAML = Skill won't load. Check your frontmatter:

Text

cat SKILL.md | head -n 10

Make sure:

Opening --- is on line 1
Closing --- comes before the Markdown content
YAML syntax is solid (no tabs, proper indentation)

Peek at the Errors

Run Claude Code in debug mode to spot Skill loading errors.

Sharing Skills with Your Team

Best bet: Share Skills through plugins. To share via plugin:

Create a plugin with Skills in the skills/ directory
Add the plugin to a marketplace
Team members install the plugin

For the complete rundown, see Add Skills to your plugin.

You can also share Skills directly through project repos:

Step 1: Create a project Skill:

Text

mkdir -p .claude/skills/team-skill
# Create SKILL.md

Step 2: Commit to git:

Text

git add .claude/skills/
git commit -m "Add team Skill for PDF processing"
git push

Step 3: Team members get Skills automatically:

When teammates pull the latest changes, Skills show up right away:

Text

git pull
claude  # Skills are now available

Updating a Skill

Edit SKILL.md directly:

Text

# Personal Skill
code ~/.claude/skills/my-skill/SKILL.md

# Project Skill
code .claude/skills/my-skill/SKILL.md

Changes kick in next time you start Claude Code. Already running Claude Code? Restart it to load the updates.

Getting Rid of a Skill

Delete the Skill directory:

Text

# Personal
rm -rf ~/.claude/skills/my-skill

# Project
rm -rf .claude/skills/my-skill
git commit -m "Remove unused Skill"

Pro Tips

Keep Skills Laser-Focused

One Skill = one capability:

Focused (the good stuff):

"PDF form filling"
"Excel data analysis"
"Git commit messages"

Too scattered (not so good):

"Document processing" (break it into separate Skills)
"Data tools" (split by data type or operation)

Write Descriptions That Work

Help Claude figure out when to use Skills by dropping specific triggers in your description:

Crystal clear:

Text

description: Analyze Excel spreadsheets, create pivot tables, and generate charts. Use when working with Excel files, spreadsheets, or analyzing tabular data in .xlsx format.

Pretty vague:

Text

description: Data analysis

Test Drive with Your Team

Have teammates try out Skills and give you feedback:

Does the Skill activate when it should?
Are the instructions crystal clear?
Any missing examples or weird edge cases?

Keep Track of Versions

You can document Skill versions right in your SKILL.md to track changes. Add a version history section:

Text

# My Skill

## Version History
- v2.0.0 (2025-10-01): Breaking changes to API
- v1.1.0 (2025-09-15): Added new features
- v1.0.0 (2025-09-01): Initial release

This helps teammates understand what changed between versions.

Troubleshooting Time

Claude Ignores My Skill

What's happening: You ask a relevant question but Claude doesn't use your Skill.

Check: Is the description specific enough? Vague descriptions make it tough for Claude to discover. Include both what the Skill does and when to use it, with key terms users would mention.

Too generic:

Text

description: Helps with data

Specific:

Text

description: Analyze Excel spreadsheets, generate pivot tables, create charts. Use when working with Excel files, spreadsheets, or .xlsx files.

Check: Is the YAML valid? Validate to catch syntax errors:

Text

# View frontmatter
cat .claude/skills/my-skill/SKILL.md | head -n 15

# Check for common issues
# - Missing opening or closing ---
# - Tabs instead of spaces
# - Unquoted strings with special characters

Check: Is the Skill in the right spot?

Text

# Personal Skills
ls ~/.claude/skills/*/SKILL.md

# Project Skills
ls .claude/skills/*/SKILL.md

Skill Loads But Acts Wonky

What's happening: The Skill loads but doesn't work right.

Check: Are dependencies available? Claude will automatically install required dependencies (or ask permission to install them) when needed.

Check: Do scripts have execute permissions?

Text

chmod +x .claude/skills/my-skill/scripts/*.py

Check: Are file paths correct? Use forward slashes (Unix style) in all paths:

Right: scripts/helper.py Wrong: scripts\helper.py (Windows style)

Skills Are Fighting Each Other

What's happening: Claude uses the wrong Skill or seems confused between similar Skills.

Be specific in descriptions: Help Claude pick the right Skill by using distinct trigger terms. Instead of:

Text

# Skill 1
description: For data analysis

# Skill 2
description: For analyzing data

Use:

Text

# Skill 1
description: Analyze sales data in Excel files and CRM exports. Use for sales reports, pipeline analysis, and revenue tracking.

# Skill 2
description: Analyze log files and system metrics data. Use for performance monitoring, debugging, and system diagnostics.

Real-World Examples

Simple Skill (just one file)

Text

commit-helper/
└── SKILL.md

Text

---
name: Generating Commit Messages
description: Generates clear commit messages from git diffs. Use when writing commit messages or reviewing staged changes.
---

# Generating Commit Messages

## Instructions

1. Run `git diff --staged` to see changes
2. I'll suggest a commit message with:
   - Summary under 50 characters
   - Detailed description
   - Affected components

## Best practices

- Use present tense
- Explain what and why, not how

Skill with Tool Permissions

Text

code-reviewer/
└── SKILL.md

Text

---
name: Code Reviewer
description: Review code for best practices and potential issues. Use when reviewing code, checking PRs, or analyzing code quality.
allowed-tools: Read, Grep, Glob
---

# Code Reviewer

## Review checklist

1. Code organization and structure
2. Error handling
3. Performance considerations
4. Security concerns
5. Test coverage

## Instructions

1. Read the target files using Read tool
2. Search for patterns using Grep
3. Find related files using Glob
4. Provide detailed feedback on code quality

Multi-File Skill (the whole package)

Text

pdf-processing/
├── SKILL.md
├── FORMS.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md:

Text

---
name: PDF Processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files, forms, or document extraction. Requires pypdf and pdfplumber packages.
---

# PDF Processing

## Quick start

Extract text:
```python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
```

For form filling, see [FORMS.md](FORMS.md).
For detailed API reference, see [REFERENCE.md](REFERENCE.md).

## Requirements

Packages must be installed in your environment:
```bash
pip install pypdf pdfplumber
```

List required packages in the description. Packages need to be installed in your environment before Claude can use them.

Claude loads additional files only when it needs them.

What's Next?

Ready to level up? Check out:

Now go forth and teach Claude some new tricks!

📚 Related Articles

Explore more AI development and productivity content:

Claude Skills: Your AI Assistant's Secret Superpowers - Introduction to Claude Skills and their capabilities
How to Launch a Product: Step-by-Step Guide for 2025 - Complete guide to successful product launches
The Ultimate Indie Hacker Tech Stack for 2025 - Essential tools for building and launching products
AI SEO Optimization: The Future of Search Rankings - Leverage AI to optimize your marketing
What is Launch Vault: Complete Guide - Learn how Launch Vault can amplify your product launch

🚀 Launch Your AI-Powered Development Tools with Launch Vault

Ready to showcase your Claude Skills, AI development tools, or automation solutions? Launch Vault is the perfect platform to reach developers and AI enthusiasts who appreciate cutting-edge technology.

Why Choose Launch Vault for Your AI Development Tools:

✅ Developer Community - Connect with developers, AI researchers, and tech innovators
✅ Tech-Focused Audience - Reach users who understand and value advanced AI tools
✅ Instant Visibility - Get featured on our high-traffic platform with engaged users
✅ SEO Benefits - Earn quality backlinks and boost your search rankings
✅ Launch Analytics - Track performance and optimize your launch strategy
✅ Expert Resources - Access proven launch strategies and best practices

Submit your AI development tool to Launch Vault →

Join hundreds of successful makers who've used Launch Vault to launch their AI-powered tools, automation solutions, and developer utilities. Build community and achieve your business goals.

Ready to launch your next AI development project? Whether you're building Claude Skills, automation tools, or AI-powered developer utilities, Launch Vault provides the platform and community to help you succeed. Submit your project today and connect with thousands of potential users and customers.

50% OFF Sponsor! Get maximum visibility for your product this holiday season

🛠️ The Ultimate Guide to Agent Skills: Teaching Claude New Tricks

Before We Dive In

What's the Big Idea Behind Agent Skills?

Creating Your First Skill

Personal Skills (Just for You)

Project Skills (Team Spirit)

Plugin Skills (The Easy Route)

Crafting Your SKILL.md File

Adding Extra Goodies

Playing It Safe with allowed-tools

Checking Out Available Skills

Taking Your Skill for a Spin

When Things Go Sideways

Make Your Description Pop

Double-Check the File Path

YAML Syntax Check

Peek at the Errors

Sharing Skills with Your Team

Updating a Skill

Getting Rid of a Skill

Pro Tips

Keep Skills Laser-Focused

Write Descriptions That Work

Test Drive with Your Team

Keep Track of Versions

Troubleshooting Time

Claude Ignores My Skill

Skill Loads But Acts Wonky

Skills Are Fighting Each Other

Real-World Examples

Simple Skill (just one file)

Skill with Tool Permissions

Multi-File Skill (the whole package)

What's Next?

📚 Related Articles

🚀 Launch Your AI-Powered Development Tools with Launch Vault