Claude Code Agents & Skills

Extend Claude Code with specialized subagents for isolated tasks and reusable skills for standardized workflows. Build your own or use the built-ins.

Official Documentation

Subagents Docs Skills Docs

1What Are Subagents?

Subagents are specialized AI agents that Claude Code can delegate tasks to. Each subagent operates in its own separate context window with custom tools, instructions, and even a different model.

Isolated Context

Works independently in its own context window — prevents pollution of the main conversation.

Custom Tools

Restrict or grant specific tool access. Read-only agents, database-only agents, etc.

Model Selection

Use Haiku for speed, Sonnet for balance, or Opus for complex tasks — per agent.

Custom System Prompt

Detailed instructions that guide the agent's behavior and approach.

Built-in Subagents

Explore Agent

Fast, read-only agent optimized for codebase searching. Uses Haiku for low-latency. Supports "quick", "medium", or "very thorough" exploration levels.

Plan Agent

Read-only agent for researching and designing implementation plans. Used automatically in plan mode.

General-Purpose Agent

Handles complex, multi-step tasks requiring both exploration and action. Full tool access.

2What Are Skills?

Skills are Markdown files that teach Claude how to do something specific. When your request matches a skill's description, Claude automatically discovers and applies it — like a recipe card it can reference.

Auto-Discovery

Claude matches your request to skills via semantic similarity. No explicit invocation needed.

Self-Contained

A directory with SKILL.md plus optional supporting files, scripts, and docs.

Progressive Disclosure

Only the name/description loads at startup. Full content loads when needed — keeps startup fast.

Tool Restrictions

Limit which tools Claude can use without permission when the skill is active.

Skill Structure

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── reference.md      # Optional: detailed docs
├── examples.md       # Optional: usage examples
└── scripts/
    └── helper.py     # Optional: utility scripts

3Creating Custom Subagents

Create a Markdown file with YAML frontmatter in your agents directory. Claude Code will discover it automatically.

Project Agents

.claude/agents/my-agent.md

Available only in this project. Shareable via git.

User Agents

~/.claude/agents/my-agent.md

Available across all your projects.

Example Agent Definition

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code changes for bugs, security issues, and best practices
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---

# Code Reviewer Agent

You are a senior code reviewer. Your job is to:

1. Review the specified files for bugs and issues
2. Check for security vulnerabilities
3. Suggest improvements following best practices
4. Be thorough but constructive in feedback

Always explain WHY something is a problem, not just WHAT.

4Creating Custom Skills

Create a directory with a SKILL.md file. The description determines when Claude applies the skill.

Project Skills

.claude/skills/my-skill/SKILL.md

Available only in this project.

Personal Skills

~/.claude/skills/my-skill/SKILL.md

Available across all your projects.

Example Skill Definition

.claude/skills/commit-style/SKILL.md

---
name: commit-style
description: Use when creating git commits to follow our team's conventional commit format
allowed-tools:
  - Bash
---

# Commit Message Style Guide

When creating commits, use this format:

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

[optional body]
```

## Types
- feat: New feature
- fix: Bug fix
- docs: Documentation only
- refactor: Code restructure
- test: Adding tests

## Examples
- feat(auth): add Google OAuth login
- fix(api): handle null user in endpoint
- docs(readme): update setup instructions

Key Insight: The description is critical — it determines when Claude automatically applies your skill. Include keywords users would naturally say, like "create commit", "git commit", "commit message".

5Storage Locations & Precedence

Type	Location	Scope
Project Agents	.claude/agents/	This project only
User Agents	~/.claude/agents/	All projects
Project Skills	.claude/skills/	This project only
Personal Skills	~/.claude/skills/	All projects
Enterprise Skills	Admin-configured	Organization-wide

Precedence: Project agents override user agents with the same name. For skills: Enterprise > Personal > Project > Plugin.

Not sure which to use?

Our comparison guide breaks down exactly when agents shine vs. when skills are better.

Agents vs Skills PRO Tips