Updated Sep 2026

Claude Code Agents & Skills

The hands-on build guide. Create your own subagents

Subagent

A specialized AI agent Claude Code can delegate a task to. It works in its own separate context window with its own tools and instructions, then reports back a summary. Define one as a Markdown file in `.claude/agents/` (project) or `~/.claude/agents/` (personal) with `name` and `description` frontmatter; Explore, Plan, and general-purpose are built in.

"Like hiring a specialist contractor for a specific part of a project. They work independently and report back when done."

(specialists that work in their own context) and skills

Claude Skill

A folder with a SKILL.md file that teaches Claude how to do a specific task. Claude loads it automatically when your request matches its description, or you run it directly as `/skill-name`. Skills live in `.claude/skills/<name>/SKILL.md` (project), `~/.claude/skills/` (personal), or inside plugins, and they now also cover what used to be custom slash commands.

"Like a recipe card Claude can reference. When you ask for something matching the recipe's purpose, Claude pulls out the card and follows the instructions."

(reusable know-how Claude loads when needed), test them, and avoid the classic mistakes. Not sure which one you need? Start with Agents vs Skills.

Official Documentation

Subagents Docs Skills Docs

1Start With the Built-in Subagents

Before you build anything, know what ships in the box. Each subagent runs in its own context window, does its job, and hands back a summary, so the messy middle never clutters your main conversation.

Explore

Read-only codebase searching. "Use Explore to find everywhere we read the session."

Plan

Read-only research that feeds an implementation plan, used during plan mode.

general-purpose

Multi-step tasks that need both reading and doing.

2Create a Custom Subagent

A subagent is one Markdown file: YAML frontmatter for settings, and the body is its system prompt. The /agents command is no longer a wizard; the easiest route is to ask Claude to write the file, then tweak it.

Option A: ask Claude

Create a project subagent in .claude/agents/ called code-reviewer.
It should be read-only, use Sonnet, and review changed files for
security issues, missing error handling, and Next.js 16 mistakes.

Project agents

.claude/agents/code-reviewer.md

This repo only. Commit it to share with your team.

User agents

~/.claude/agents/code-reviewer.md

Available in all your projects.

Option B: write it yourself (.claude/agents/code-reviewer.md)

---
name: code-reviewer
description: Reviews changed code for bugs, security issues, and Next.js mistakes. Use proactively after finishing a feature.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
---

You are a senior reviewer for a Next.js 16 + Drizzle + Neon app.

1. Run git diff main --stat to find what changed, then read those files.
2. Check: auth on every server action and route handler, Zod validation
   on inputs, no secrets in client components, awaited params/cookies().
3. Report issues grouped by severity with file:line and a concrete fix.
4. If everything looks fine, say so in one line. Don't pad the review.

Frontmatter you'll actually use

name	Required. Lowercase-and-hyphens id.
description	Required. When Claude should delegate to it. Be specific; add "use proactively after..." if you want it used automatically.
tools / disallowedTools	Allow-list or deny-list of tools. Leave tools out to inherit everything.
model	sonnet, opus, haiku, or inherit (use the main session's model).
permissionMode	Give this agent its own permission mode, e.g. plan for a read-only reviewer.
skills	Skills to preload into the agent's context at startup.
memory	user, project, or local: a memory folder that survives between runs.
isolation: worktree	Run in its own Git worktree so its edits can't collide with yours.
maxTurns	Cap how long it can run.
mcpServers / hooks	MCP servers and hooks scoped to just this agent.

Run it

Three ways, from loose to strict

# 1. Name it and let Claude delegate
Use the code-reviewer subagent to look at my changes

# 2. @-mention it to guarantee it runs
@"code-reviewer (agent)" look at the auth changes

# 3. Make it the whole session's agent (from the terminal)
claude --agent code-reviewer

Remember: a subagent starts with a fresh context. It loads your CLAUDE.md

CLAUDE.md

A Markdown file Claude Code reads at the start of every session: project context, commands, conventions, and rules. Put it at `./CLAUDE.md` (shared with the team), `~/.claude/CLAUDE.md` (personal, all projects), or `CLAUDE.local.md` (personal, gitignored). Run `/init` to generate a starter; AGENTS.md is read too.

"Like a welcome packet for a new team member. It tells Claude everything it needs to know about your project."

files but not your conversation, so the task you hand it must stand on its own. Claude Code picks up new or edited agent files within seconds, no restart needed.

3Create a Custom Skill

A skill is a folder with a SKILL.md. The folder name becomes a slash command

Slash Commands

Commands you type in Claude Code starting with `/`: built-ins like /help, /clear, /compact, /context, /resume, /usage, and /init, plus your own. Custom commands have been merged into skills: `.claude/skills/deploy/SKILL.md` and the older `.claude/commands/deploy.md` both create `/deploy`.

"Like keyboard shortcuts, but for conversation. Type a quick command instead of explaining what you want."

, and the description decides when Claude loads it by itself.

Terminal

mkdir -p .claude/skills/commit-style

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

---
name: commit-style
description: Writes git commit messages in our conventional-commit format. Use when committing, writing a commit message, or preparing a PR.
allowed-tools: Bash(git status *) Bash(git diff *) Bash(git commit *)
---

# Commit style

Format:
<type>(<scope>): <summary in imperative mood, max 72 chars>

Types: feat, fix, docs, refactor, test, chore

Rules:
- One logical change per commit. If the diff mixes changes, suggest splitting.
- Body explains WHY, not what. Skip it for trivial changes.
- Never commit .env files or anything in /secrets.

Examples:
feat(auth): add Google sign-in
fix(api): handle missing user in /api/me

Project skill

.claude/skills/<name>/SKILL.md

Personal skill

~/.claude/skills/<name>/SKILL.md

Test it both ways

Say "commit these changes". If Claude doesn't pick up the skill, your description is missing the words people actually use.

Type /commit-style to run it directly and check the instructions behave.

Skills can set their own tools and model too. allowed-tools pre-approves specific commands while the skill runs, and model / effort pick how it thinks. Add disable-model-invocation: true for anything with side effects so only you can trigger it. Full field list and the Claude apps / API versions: Skills Ecosystem.

4Writing Them Well

Description = trigger

Say what it does AND when to use it, in the words you'd type. "Reviews PRs. Use when reviewing code, a PR, or a diff."

One job each

A "do everything" agent or skill gets loaded at the wrong times and followed badly. Split it.

Least privilege

Give a reviewer Read/Grep/Glob, not Write. Restricting tools is both safer and more focused.

Define the output

Tell it exactly what to hand back: a list by severity, a PASS/FAIL, a file path. Vague asks get vague reports.

Keep SKILL.md short

Move long reference material into extra files the skill points to. They load only when needed.

Iterate from real misses

When it gets something wrong, add one line fixing that case. That's how good skills are built.

5Where Files Live and Who Wins

Subagents (highest first)

Managed settings (your organization)
--agents flag for this session
.claude/agents/ (project)
~/.claude/agents/ (you)
Plugin agents/ folders

Skills (highest first)

Enterprise (managed)
~/.claude/skills/ (personal)
.claude/skills/ (project)
Nested .claude/skills/ in subfolders

Plugin skills never clash: they're namespaced as /plugin-name:skill-name.

Note the flip: for subagents the project copy beats your personal one; for skills your personal copy wins.

6Common Traps

The skill never triggers

Rewrite the description with the phrases you actually type. Test by asking naturally, not with the skill's name.

The subagent "forgot" what we discussed

It never saw it. Subagents start fresh; include the goal, the files, and constraints in the handoff.

Claude deployed on its own

Side-effect skills need disable-model-invocation: true. For hard guarantees, add a hook.

Teammates don't get your agents

Personal files in ~/.claude/ stay on your machine. Put shared ones in the repo's .claude/ folder and commit, or ship a plugin.

Everything became an agent

Most "agents" people write should be skills. If it doesn't need its own context, tools, or model, make it a skill.

Built one? Level it up.

Add hooks for guarantees, bundle everything as a plugin, or run agents side by side with parallel agents.

Which One When? Plugins