Claude Code Skill / Agent -- Overview and How They Work

What Are Skills and Agents?

Claude Code is Anthropic’s terminal-based AI coding assistant. Two core mechanisms extend it: Skills and Subagents (often just called “Agents”).

Aspect	Skill	Subagent
What it is	A reusable instruction bundle	An independent worker with its own context
Storage	`~/.claude/skills/` or `.claude/skills/`	`~/.claude/agents/` or `.claude/agents/`
Context	Loaded into the current conversation	Separate context window, returns only a summary
Tools	Inherits parent session tools	Restricted via the `tools` field
Model	Uses the parent model	Configurable (sonnet / opus / haiku / inherit)
When to use	Reusable “how-to” expertise	A parallel worker you delegate a task to

As an analogy, a Skill is like a manual in your desk drawer — you pull it out and follow it yourself. A Subagent is like a colleague sitting next to you — you hand them the whole task and only get the report back.

How Skills Work

Skills are defined in SKILL.md files. At session start, Claude pre-reads only each Skill’s frontmatter (name + description) — roughly 100 tokens per skill. The full body (typically under 5k tokens) is loaded only when the Skill is actually invoked.

There are two invocation paths:

Automatic: Claude matches the user’s request against each Skill’s description and loads relevant ones on its own
Manual: The user types /skill-name as a slash command

# Manual invocation (Skill named test-runner)
/test-runner

# Passing args (shell-style: $0, $1, ...)
/commit-helper "fix: resolve login bug"

Because a Skill runs inside the parent conversation, it uses the current session’s tools. Read/Write/Bash permissions carry over directly.

Skill Priority

When the same name exists in multiple locations, Claude resolves them in this order.

Order	Location	Notes
1	Enterprise	Organization-wide deployment (configurable)
2	Personal	`~/.claude/skills/` — user-global
3	Project	`.claude/skills/` — project-local

How Subagents Work

A Subagent spins up a separate AI session that you delegate work to. Three traits stand out.

Independent context: Doesn’t bloat the parent conversation. Isolates exploration/research from main context
Tool restriction: Can only use tools listed in tools — e.g., a read-only agent might be limited to Read, Grep, Glob
Model choice: Pick Haiku (fast, cheap), Sonnet (balanced), or Opus (deep reasoning) per task

Subagents are launched via Claude Code’s Task tool or the Agent tool.

User: "Find security issues in this PR"
  ↓
Main Claude: invokes security-reviewer agent
  ↓
Subagent (separate context, Opus model, only Read+Grep+Bash)
  → Reads 30 files and scans
  → Returns only a summary
  ↓
Main Claude: relays the summary to the user

Why Use a Subagent?

Reason	Explanation
Context protection	Reading 30 files doesn’t pollute the main conversation
Parallelism	Run multiple independent agents concurrently
Cost optimization	Simple lookups on Haiku, complex analysis on Opus
Permission boundary	A reviewer agent gets read-only access, no write tools

Limitation: A Subagent cannot directly spawn child Subagents. For nesting you chain from the main session or use headless mode (claude -p).

When to Use Skill vs Subagent

The decision flow is simple.

Q1: "Do I want to codify a repeatable how-to?"
  Yes → Skill
  No  → Q2

Q2: "Do I want an independent worker that returns a summary?"
  Yes → Subagent
  No  → Plain slash command or a regular prompt

Concrete examples:

Scenario	Choice	Why
”Apply commit message conventions”	Skill	Rules are instructions; executed in the current chat
”Full security review of just-written code”	Subagent	Needs to read many files — isolate the context
”Enforce Python PEP 8 style”	Skill	Style rules = instructions
”Prototype three implementation approaches in parallel”	Subagent	Independent work benefits from parallelism
”Fix Docker build errors step-by-step”	Skill + Subagent	Skill holds the procedure, agent does the actual fix

How They Interact

The two mechanisms aren’t mutually exclusive. A common real-world pattern is a Skill that instructs the parent to call an agent at a specific step — e.g., “at this point, invoke the code-reviewer agent.” The Skill itself doesn’t execute the Agent tool; it directs the parent conversation to do so.

Conversely, Subagents do not automatically inherit the parent’s Skills by default. If you need them, list them explicitly in the agent’s frontmatter (covered in the next post).

Wrap-up

One-line summary:

Skill = instruction catalog: Save frequently used know-how under a name; load automatically or manually
Subagent = independent worker: Delegate tasks with its own context, tools, and model; get only a summary

Since Anthropic officially launched Skills in October 2025, the Claude Code extension ecosystem has shifted toward designing “what knowledge becomes a Skill, and what work gets delegated to an agent.” The next post covers how to actually author your own Skills and Subagents.