Skills vs Agents
We'll talk about Skills vs Agents in scope of Claude Code.
Skills = reusable instructions that load into your current conversation. Think: a recipe card Claude pulls out when relevant.
Subagents = separate Claude instances with their own context window. Think: delegating to a colleague who comes back with a summary.
Skills
Location: .claude/skills/<name>/SKILL.md (project) or ~/.claude/skills/<name>/SKILL.md (personal)
A skill's body loads on-demand into your main conversation. It stays there and shares your context. Good for: conventions, checklists, step-by-step procedures, code generation templates.
# ~/.claude/skills/api-review/SKILL.md
---
name: api-review
description: Review API endpoints for REST conventions and error handling
allowed-tools: Read Grep Glob
---
When reviewing API code:
1. Check RESTful naming (plural nouns, no verbs)
2. Verify consistent error response format: { error, code, message }
3. Ensure input validation on all endpoints
4. Flag missing rate limiting or auth middleware
Invoke with /api-review or let Claude auto-trigger based on the description.
Agents
Location: .claude/agents/<name>.md (project) or ~/.claude/agents/<name>.md (personal)
Agent runs in an isolated context — it can't see your conversation history. It does heavy work (reading hundreds of files, running tests) without polluting your main context, then returns a summary. Good for: research, parallel tasks, large-scale analysis.
# ~/.claude/agents/security-scanner.md
---
description: Scans codebase for security vulnerabilities. Use after code changes or before releases.
tools:
- Read
- Grep
- Glob
- Bash
model: sonnet
---
You are a security-focused code reviewer.
1. Search for common vulnerability patterns (SQL injection, XSS, SSRF, path traversal)
2. Check dependency versions against known CVEs using `npm audit` or equivalent
3. Review auth/authz middleware for bypass risks
4. Return a prioritized list: Critical > High > Medium > Low
Claude auto-delegates when a task matches the description, or you say "use the security-scanner agent."
Summary
| Skills | Agents | |
|---|---|---|
| Context | Shares your conversation | Own isolated context |
| Location | .claude/skills/ |
.claude/agents/ |
| When to use | Reusable knowledge, procedures, conventions | Heavy/parallel tasks, context-expensive work |
| Invocation | /skill-name or auto by Claude |
Auto-delegation or explicit request |
| Result | Instructions stay in your chat | Summary returned, detail discarded |
| Key frontmatter | disable-model-invocation, context, allowed-tools |
tools, model, permissionMode, memory |
Hybrid pattern
A skill with context: fork runs its instructions as an agent — you get the reusable template of a skill with the context isolation of an agent:
# ~/.claude/skills/deep-research/SKILL.md
---
name: deep-research
description: Research a topic thoroughly in the codebase
context: fork
agent: Explore
---
Research $ARGUMENTS:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with file references
The mental model: skills teach Claude how to do something; agents give Claude a separate workspace to do it in. Use skills when you need the knowledge inline, agents when you need the isolation.