TL;DR: Skills are like recipes, subagents are like specialized coworkers. Both extend Claude Code, but knowing when to use which saves you a ton of headache.
So I was building a document reader for Claude Code (to process Word docs, PDFs, Excel files from support tickets), and I hit this question: "Should this be a skill or a subagent?"
Turns out, this is a pretty common confusion. Let me save you the research time.
The Quick Version
Here's the cheat sheet:
| Aspect | Skills | Subagents |
|---|---|---|
| What it is | Instructions that extend Claude's knowledge | A separate AI assistant with its own context |
| When Claude uses it | Automatically when relevant | Delegated for complex workflows |
| Best for | Utility functions, recipes, how-tos | Multi-step analysis, code review, research |
| Context | Shares your main chat context | Gets its own isolated context window |
Think of it this way:
- Skill = giving Claude a cookbook
- Subagent = hiring a sous chef
Skills: The Recipe Approach
Skills are markdown files with instructions. Claude reads them when it needs help with something specific.
Example structure:
~/.claude/skills/document-reader/
├── SKILL.md (main instructions)
├── examples.md (usage examples)
└── scripts/
└── converter.py (optional helper script)
When to use skills:
- Converting files (PDF → text, DOCX → text)
- Template generation
- Style guides for code/writing
- Domain knowledge (business rules, API docs)
- Quick utility functions
Why skills are great:
- ⚡ Fast - Claude just reads instructions
- 🔄 Reusable - any conversation can use them
- 🪶 Lightweight - no separate AI needed
- 🤖 Auto-activated - Claude decides when to use them
Example skill description:
---
name: document-reader
description: Converts document files (.pdf, .docx, .xlsx) to text. Use when reading document attachments, analyzing files from tickets, or extracting content from PDFs and spreadsheets.
---
Notice: it tells Claude what it does and when to use it. That's key.
Subagents: The Specialized Coworker
Subagents are like delegating work to a specialist. They get their own context window and run independently.
When to use subagents:
- Code review workflows
- Multi-file analysis
- Research tasks that need deep investigation
- Tasks that would clutter your main conversation
- When you need focused, dedicated reasoning
Why subagents rock:
- 🧠 Deep focus - dedicated context for complex tasks
- 🔍 Multi-step reasoning - can work through problems systematically
- 🎯 Specialized - custom prompts for specific workflows
- 🧹 Clean separation - doesn't pollute main chat
Example subagent:
---
name: code-reviewer
description: Reviews code for best practices and security issues. Use when reviewing PRs or analyzing code quality.
tools: Read, Grep, Glob
---
You are a specialized code reviewer...
[detailed instructions for review process]
Real Example: Document Reader
Here's how I decided for my document reader:
The task: Read PDF/DOCX/XLSX files from support tickets
My thought process:
- Is this complex multi-step reasoning? No - just file conversion
- Does it need its own context? No - simple input/output
- Is it a utility function? Yes - convert file to text
- Will other agents need this? Yes - zahtevki-researcher needs it
Decision: Make it a skill ✅
If I needed to analyze documents across multiple tickets, compare them, and generate reports? That would be a subagent.
How They Work Together
Here's the cool part - they complement each other:
zahtevki-researcher (subagent)
↓
Downloads ticket attachment.docx
↓
Invokes document-reader (skill)
↓
Converts to text
↓
Analyzes content
↓
Returns findings
The subagent handles the complex workflow, the skill handles the utility function.
Decision Tree
Use this when you're stuck:
Is it a utility/conversion/template? → Skill
Does it need multiple steps of reasoning? → Subagent
Will it be reused across different tasks? → Skill
Is it a complex workflow with validation loops? → Subagent
Is it knowledge Claude doesn't have? → Skill
Does it need to coordinate multiple operations? → Subagent
Quick Tips
For Skills:
- Keep SKILL.md under 500 lines
- Use progressive disclosure (main file → reference files)
- Write descriptions in third person
- Include trigger words (when to use it)
- Make them discoverable
For Subagents:
- Write detailed system prompts
- Define clear responsibilities (single focus)
- Limit tool access to what's needed
- Test that they activate correctly
What I Learned
After building both, here's my take:
Start with a skill unless you specifically need subagent features. Skills are simpler, faster, and easier to maintain.
Upgrade to subagent when you're doing actual workflows - things with multiple steps, decision points, validation loops.
My document reader? Perfect as a skill. It's fast, reusable, and other agents can invoke it seamlessly.
Try It Yourself
Want to build your own? Here's a 5-minute starter:
# Create a skill directory
mkdir -p ~/.claude/skills/my-skill
# Create SKILL.md
cat > ~/.claude/skills/my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: What it does and when to use it
---
# My Skill
Instructions go here...
EOF
Next time you chat with Claude, it'll automatically discover and use your skill!
What are you building with Claude Code? Skills or subagents? Share in the comments - I'd love to hear what you're working on! 🚀
P.S. - If you found this helpful, I'm documenting my whole journey building skills for an insurance system. Follow along if you're into that sort of thing!
Top comments (0)