How to Create Custom Agent Skills in 5 Steps

So you've used the official Agent Skills, and now you want to build your own. Maybe you want a skill that automates your specific deployment pipeline, or one that writes documentation in your company's unique style.

Creating a custom Agent Skill is surprisingly straightforward. It's essentially "packaging" your best prompts and scripts into a format Claude understands.

The Anatomy of a Skill

A Skill is just a folder with a specific structure:

my-cool-skill/
├── SKILL.md          # Required: The brain of the skill
├── scripts/          # Optional: Python/Bash scripts Claude can run
└── references/       # Optional: Docs, templates, examples

Let's build a simple "Code Reviewer" skill together.

Step 1: Create the Directory Structure

Open your terminal and create your skill folder. If you are using Claude Code locally, navigate to your project root.

mkdir -p .claude/skills/code-reviewer
touch .claude/skills/code-reviewer/SKILL.md

Note: Placing it in .claude/skills/ allows Claude Code to discover it automatically.

Step 2: Write the Frontmatter

Open SKILL.md. Every skill needs YAML frontmatter at the top. This tells Claude what the skill is.

---
name: code-reviewer
description: Reviews code pull requests against company standards for security, style, and performance. Use when the user asks for a "code review" or "PR audit".
version: 1.0
---

Tip: The description is crucial. This is what Claude reads before loading the skill. Make it clear and keyword-rich so Claude knows when to activate it.

Step 3: Define the Instructions

Below the frontmatter, write the instructions. This is your "System Prompt" for this specific capability.

# Code Review Guidelines

You are an expert Senior Engineer. When asked to review code, you must check for:

1.  **Security:** SQL injection, XSS, unvalidated inputs.
2.  **Performance:** N+1 queries, expensive loops.
3.  **Style:** Application of clean code principles (DRY, SOLID).

## Output Format

Always format your review as a markdown table followed by detailed comments:

| Severity | File | Line | Issue |
|----------|------|------|-------|
| High     | ...  | ...  | ...   |

## Tone
Be constructive but rigorous. Focus on the code, not the person.

Step 4: Add Examples (The Secret Sauce)

Claude learns best by example. Add an "Examples" section to your SKILL.md.

## Examples

**User:** "Review this python function."

**Response:**
| Severity | File | Line | Issue |
|----------|------|------|-------|
| High     | db.py| 12   | SQL Injection risk in raw query construction |

**Comment:**
Line 12 uses f-strings to insert user input into SQL. This is dangerous.
*Recommendation:* Use parameterized queries instead.

Step 5: Testing Your Skill

Save the file. Now, in your Claude environment (like Claude Code), simply say:

"Reload my skills"

Then test it:

"Please review the auth.py file I just wrote."

Claude should match your request to the code-reviewer skill, load your instructions, and give you that nice markdown table you defined!

Advanced: Adding Scripts

You can make your skill executable. Create a scripts/analyze_complexity.py file in your skill folder that calculates cyclomatic complexity.

Then add this to your SKILL.md:

## Tools
To analyze complexity, run the script:
```python
python .claude/skills/code-reviewer/scripts/analyze_complexity.py <filename>

Now Claude knows it can run that specific script to help with its review!

## Summary

Building Agent Skills is a powerful way to codify your team's knowledge. Start simple with just a `SKILL.md`, and evolve it by adding scripts and reference files as you go.

Ready to refine your skills? Check out **[Agent Skills Best Practices](/blog/agent-skills-best-practices)**.