Understanding the Basics of Agent Skills in Claude Code

Learn how to use Agent Skills in Claude Code to automate repetitive tasks, save your context window, and share reusable instructions with your team.

Background

A few weeks ago, I was working on a feature branch with Claude Code. Everything was going smoothly until I asked it to create a pull request. The PR description it generated was… fine. But it wasn’t the format my team uses. So I typed out the instructions: “Use this template, include a What section, a Why section, list the changes as bullet points…”

The next day, I started a new session and asked Claude to create another PR. Same problem. I had to explain the format all over again.

Then it happened with commit messages. Then with code reviews. Every session, I was spending the first few minutes re-teaching Claude things it should already know. My CLAUDE.md was getting bloated with instructions that were only relevant sometimes, eating up my context window on every single conversation.

That’s when I found Agent Skills, and they solved this problem completely.

What Are Skills?

Skills are markdown files that teach Claude Code how to do specific tasks. Unlike CLAUDE.md which is always loaded into context, Skills only activate when they’re relevant to what you’re doing:

Ask Claude to write a PR? The PR skill kicks in.
Ask it to review code? The review skill loads.
Everything else stays out of your context window.

Here’s how they compare to the other options:

Feature	Skills	CLAUDE.md	Commands
Loading	Auto, on demand	Always loaded	Explicitly invoked
Context cost	Low (only when relevant)	Always consumes context	Only when invoked
Location	`.claude/skills/`	Project root	`.claude/commands/`
Best for	Repeatable tasks	Global project rules	One-off workflows

Rule of thumb: If you find yourself explaining the same thing to Claude more than twice, it should be a Skill.

Where Do Skills Live?

Skills can live in two places:

Personal Skills at ~/.claude/skills/: apply to all projects on your machine. These are your personal preferences: commit style, review checklist, debugging approach.
Project Skills at .claude/skills/: apply to a specific project and can be committed to version control. These are your team’s shared standards: PR templates, coding conventions, deployment checklists.

I think of it this way: personal skills are your habits. Project skills are your team’s agreements.

Creating Your First Skill

A skill has three parts:

name: an identifier for the skill
description: tells Claude when to use it
Content (body): tells Claude what to do

Let me show you the first skill I actually wrote. After explaining the PR format for the third time, I created this:

---
name: pr-description
description: Writes pull request descriptions. Use when creating a PR,
  writing a PR, or when the user asks to summarize changes for a PR.
---

When writing a PR description:
1. Run `git diff main...HEAD` to see all changes on this branch
2. Write a description following this format:

## What
One sentence explaining what this PR does.

## Why
Brief context on why this change is needed.

## Changes
- Bullet points of specific changes made
- Group related changes together
- Mention any files deleted or renamed

After restarting Claude Code, I asked it to create a PR. It followed the format perfectly without any extra prompting. That moment felt like magic.

Here’s another one I use daily, a conventional commit formatter:

---
name: conventional-commit
description: Formats commit messages using conventional commit style.
  Use when the user wants to commit, make a commit, or save changes.
---

When writing a commit message:
1. Run `git diff --staged` to see staged changes
2. Format the commit message as:

<type>(<scope>): <short description>

<body - what and why, not how>

Types: feat, fix, docs, style, refactor, test, chore
Scope: the module or area affected

And for my team, I wrote a frontend review skill that we committed to the project repo:

---
name: frontend-review
description: Reviews frontend code for quality, accessibility, and
  performance. Use when reviewing React/Vue components, CSS, or
  frontend pull requests.
---

When reviewing frontend code, check these areas:

**Accessibility**
- All images have alt text
- Form inputs have associated labels
- Interactive elements are keyboard accessible
- Color contrast meets WCAG AA (4.5:1 for text)

**Performance**
- No unnecessary re-renders
- Large lists use virtualization
- Images are lazy loaded

**Code Quality**
- Components follow single responsibility
- Props have proper TypeScript types
- Error states are handled

Provide feedback in this format:
- **Must fix**: Issues that block merging
- **Should fix**: Important but not blocking
- **Nice to have**: Suggestions for improvement

Now every developer on the team gets the same review standards without anyone having to memorize the checklist.

The Key to Making Skills Work: Good Descriptions

Here’s something I learned the hard way. My first attempt at a review skill had this description:

description: A skill for reviews

Claude almost never triggered it. The description was too vague; Claude didn’t know when to activate it.

I rewrote it to:

description: Reviews frontend code for quality, accessibility, and
  performance. Use when reviewing React/Vue components, CSS, or
  frontend pull requests.

That fixed it immediately. A good description answers two questions: what does the skill do, and when should Claude use it? Be specific about the trigger phrases. If your skill is about writing tests, mention “write tests”, “add tests”, “create test file” in the description.

Optional Configuration

Beyond name and description, you can also set:

allowed-tools: restrict which tools Claude can use (e.g., Read, Grep, Glob, Bash)
model: specify which Claude model to use (e.g., sonnet, haiku)

Example:

---
name: quick-search
description: Quickly searches the codebase for patterns and definitions.
allowed-tools: Read, Grep, Glob
model: haiku
---

This is useful for lightweight tasks where you don’t need Claude’s full toolkit.

Scaling Up: Multi-file Skills

At some point, one of my skills grew past 500 lines. It was an onboarding skill that tried to cover our entire project architecture, API patterns, and database conventions in a single file. The context window impact defeated the purpose.

The solution is to split it into multiple files with lazy loading:

.claude/skills/
  codebase-onboarding/
    SKILL.md
    references/
      architecture-guide.md
      api-reference.md

In the main SKILL.md, instead of including everything, you reference sub-documents with a loading instruction:

## Architecture Overview

**Only load when user requests more detail.** See
[architecture-guide.md](references/architecture-guide.md).

## API Patterns

**Only load when user asks about API conventions.** See
[api-reference.md](references/api-reference.md).

The phrase “Only load when…” tells Claude to defer loading until the information is actually needed. This keeps your context lean by default and only expands when you drill into a specific topic.

Good to Know

A few things worth mentioning before you get started:

Skills vs Hooks. Skills tell Claude what to do based on conversation context. Hooks are shell commands that fire automatically on events (like running a linter when a file is saved). They serve different purposes and work well together.
Name conflicts. If a personal skill and a project skill share the same name, personal wins. The full priority order is: Enterprise > Personal > Project > Plugins. Use specific names like frontend-review instead of just review to avoid surprises.
Restart required. After creating, updating, or deleting a skill, you must restart Claude Code for the changes to take effect. I’ve been burned by this more than once.
Sharing via Plugins. You can package skills as Claude Plugins for wider distribution. Just make sure to explicitly list them in the plugin’s agent definition with the skills field, otherwise the plugin won’t be able to see them.

Try It Now

Here’s everything you need to get started:

mkdir -p .claude/skills

Create a file at .claude/skills/SKILL.md:

---
name: your-skill-name
description: What it does. When Claude should use it.
---

When [doing the task]:
1. [First step]
2. [Second step]
3. [Output format]

Restart Claude Code, and it’s ready.

Think about what you keep repeating. Your commit format? Your PR template? Your test conventions? That’s your first skill.

Conclusion

Skills are a simple idea, just markdown files with instructions. But they fundamentally changed how I use Claude Code:

I stopped wasting time re-explaining my preferences every session.
My CLAUDE.md got shorter because I moved context-specific instructions into skills.
My team now shares consistent standards without anyone having to memorize them.

Start with one skill for your most annoying repetitive task. Once you feel how much smoother your workflow gets, you’ll want to write more.

Thank you for reading 👋

On this page

Background
What Are Skills?
Where Do Skills Live?
Creating Your First Skill
The Key to Making Skills Work: Good Descriptions
Optional Configuration
Scaling Up: Multi-file Skills
Good to Know
Try It Now
Conclusion