Skills and agents are Claude Code’s two extension mechanisms. Skills (also called commands) are invoked by the user with a slash command like /chief-of-staff and create an interactive conversation environment. Agents are invoked by Claude itself to handle focused, single-purpose tasks like code review or research. Skills live in .claude/skills/, agents in .claude/agents/. Skills are rooms the user enters; agents are runners Claude dispatches.
What are skills and agents in Claude Code?
Skills and agents are both ways to extend Claude Code using markdown files, but they serve different purposes. A skill is a custom slash command the user invokes to enter a specific working context, like /chief-of-staff for daily planning. An agent is a specialist worker that Claude itself decides to deploy when it recognizes a matching task, like sending out a code reviewer to audit files.
Claude Code has two ways to extend what it can do: skills (also called commands) and agents. They live in similar places on your file system. They’re both defined with markdown files. From the outside, they look nearly identical.
But they work completely differently. And once you understand the distinction, everything about how Claude Code is structured starts to make sense.
The one-sentence version
Skills are things YOU invoke. Agents are things CLAUDE invokes.
You type /chief-of-staff and you’re suddenly in a headquarters you built. You ask Claude to “review this codebase and find any security issues” and Claude decides to spin up a code-review agent to go do that work independently.
That’s the whole thing. Everything else is just details.
Rooms and runners
Here’s the mental model that makes this stick.
Skills are rooms you’ve decorated. When you type /chief-of-staff, you’re walking into a room. You built that room. You decided what’s on the walls (which files get loaded), the vibe (the tone, the role Claude plays), the tools within reach, and what happens next (the workflow). You’re inside this room with Claude. You’re talking to each other. The room shapes how Claude thinks WITH you.
You can only be in one room at a time. That’s fine. The room IS the context.
Agents are runners you dispatch. While you’re in any room (or no room at all), you can say “go research this and come back.” The runner leaves. It does work independently. It returns with findings. You can send multiple runners out at once. They don’t change the room you’re in. They just bring stuff back.
The difference:
| Skills (Rooms) | Agents (Runners) | |
|---|---|---|
| Who invokes it | You | Claude |
| Type of interaction | Conversation | Task + results |
| Direction | Claude thinks WITH you | Claude works FOR you |
| When to use | Interactive, back-and-forth work | Focused, single-purpose tasks |
| Example | /chief-of-staff |
code-reviewer agent |
Where the files live
Both types live inside .claude/ in your home directory (or your project directory).
Skills go in .claude/skills/:
~/.claude/skills/
chief-of-staff/
SKILL.md
c4c/
SKILL.md
Agents go in .claude/agents/:
~/.claude/agents/
code-reviewer.md
research-assistant.md
What a SKILL.md looks like
Every skill has a SKILL.md file. This file is what gets loaded when you invoke the command. It defines the role, the context, the tools, and the workflow.
A minimal skill:
---
name: chief-of-staff
description: Strategic planning and decision support
tools: [Read, Write, Bash]
---
You are Alex's chief of staff. When invoked, read the current tasks.json
and morning-sweep-report.md before doing anything else.
Start by asking: "What are we working on today?"
The frontmatter controls the metadata. The body is the system prompt that shapes Claude’s behavior for this session. You can tell it which files to read automatically, what tone to use, what questions to ask first, and what the workflow looks like.
When you type /chief-of-staff, Claude loads this file and becomes that context. You’re in the room.
For a full step-by-step tutorial on building one, see How to Make a Claude Code Skill.
What an agent file looks like
Agent files use similar frontmatter but with one key difference: the description field matters a lot more. That’s what Claude reads to decide whether to deploy this agent for a given task.
---
name: code-reviewer
description: Reviews code for security issues, performance problems, and style violations. Use when asked to audit, review, or analyze a codebase.
tools: [Read, Bash]
---
You are a thorough code reviewer. When given a codebase or file path:
1. Read the relevant files
2. Check for security vulnerabilities
3. Flag performance issues
4. Note any style or convention violations
Return a structured report with findings organized by severity.
Notice what’s different: no “start by asking a question.” No interactive workflow. The agent gets a task, does the work, and returns results. It’s not a conversation. It’s a job.
The description field is what Claude uses to match tasks to agents. Write it the way you’d describe the agent’s specialty to a coworker: “use this when you need X.”
A real example of each
Say you want help planning out a new course module. You type /c4c to load your course creation skill. Claude reads your course outline, checks the student notes, looks at what week you’re building. Now you’re in a conversation. You bounce ideas back and forth. Claude pushes back on some things, helps you build the structure. That’s a skill. You’re both in the room together.
Now while you’re planning, you say “go research what other creators are teaching about this topic and come back with a summary.” Claude recognizes that’s a research task, deploys a research agent, and comes back five minutes later with findings. You didn’t leave the planning room. A runner went out and came back.
That’s the interplay. You stay in context. Work gets done in parallel.
Why this distinction matters
The practical reason to understand this: it changes how you build things.
If you’re building something for yourself to invoke, where you want to be IN the conversation, that’s a skill. Give it a SKILL.md. Put it in .claude/skills/. Write a workflow that assumes back-and-forth.
If you’re building a specialist worker you want Claude to deploy when relevant, that’s an agent. Put it in .claude/agents/. Write a task-focused prompt. Make the description specific enough that Claude knows when to use it.
Get these backwards and things feel off. A skill that’s too quiet feels like a tool, not a workspace. An agent that tries to have a conversation is annoying because it keeps asking questions when you just wanted results.
The bigger picture
What’s interesting about this design is that skills and agents work well together. You build a headquarters skill for your main work, then staff it with specialist agents. The chief-of-staff skill loads your context. Code-reviewer, research-assistant, and content-editor agents handle focused tasks when needed. You’re running a small operation.
As Alex describes it: “/chief-of-staff FEELS like a headquarters because it IS one. You decorated it. You’re inside it. That’s why it doesn’t feel like using a tool. It feels like being somewhere.” The full build for this skill is covered in How to Give Claude Code Memory Across Sessions.
The goal isn’t to memorize which folder goes where. The goal is to stop thinking about Claude Code as a chatbot and start thinking about it as a workspace you configure. Skills are how you shape the space. Agents are how you staff it.
Further reading
- Claude Code documentation for the official overview of how Claude Code works
- Claude Code skills reference for the full spec on slash commands and SKILL.md format
- Claude Code agents reference for how subagents work and how Claude decides to deploy them
- skills.sh for a growing library of pre-built skills you can install and modify
Common Questions
What is the difference between a skill and an agent in Claude Code?
Skills are invoked by the user and create interactive, conversational workspaces. Agents are invoked by Claude itself to perform focused tasks independently. Skills live in .claude/skills/ with a SKILL.md file. Agents live in .claude/agents/ as standalone markdown files.
Where do Claude Code skills and agents live on the file system?
Skills go in ~/.claude/skills/ (or .claude/skills/ in a project). Each skill is a folder containing a SKILL.md file. Agents go in ~/.claude/agents/ as individual markdown files like code-reviewer.md.
Can I use skills and agents together in Claude Code?
Yes. A common pattern is to invoke a skill for your main workspace, then ask Claude to deploy agents for specific subtasks. The skill provides context and conversation flow while agents handle focused work in parallel.
How does Claude decide when to use an agent?
Claude reads the description field in each agent’s markdown file. When a user request matches what the agent is designed to handle, Claude deploys it automatically. Writing specific, clear descriptions helps Claude match tasks to the right agent.
A note from Alex: hi i’m alex - i run code for creatives. i’m a writer so i feel that it is important to say - i had claude write this piece based on my ideas and ramblings, voice notes, and teachings. the concepts were mine but the words themselves aren’t. i want to say that because its important for me to distinguish, as a writer, what is written ‘by me’ and what’s not. maybe that idea will seem insane and antiquated in a year, i’m not sure, but for now it helps me feel okay about putting stuff out there like this that a) i know is helpful and b) is not MY voice but exists within the umbrella of my business and work. If you have any thoughts or musings on this, i’d genuinely love to hear them - its an open question, all of this stuff, and my guess is as good as yours.