When to Use Claude Code Skills vs Workflows vs Agents
When Anthropic released Skills in October 2025, I faced a confusing problem: Skills, Workflows (formerly Commands), and Agents are all essentially markdown files containing prompts. Structurally identical. So which do you use, and when?
The Quick Answer
| Primitive | Purpose | When to Use | Location |
|---|---|---|---|
| Skill | Domain container | Grouping related capabilities | ~/.claude/skills/{Domain}/ |
| Workflow | Task procedure | Executing specific operations | ~/.claude/skills/{Domain}/Workflows/ |
| Agent | Parallel worker | Concurrent multi-task execution | ~/.claude/agents/ |
The Hierarchy
┌─────────────────────────────────────────────────────────────┐
│ AGENTS │
│ (Parallel workers - execute skills) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Engineer │ │ Architect │ │ Researcher │ ... │
│ └──────┬──────┘ └──────┬──────┘ └──────┬──────┘ │
└─────────┼────────────────┼────────────────┼─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ SKILLS │
│ (Domain containers - 77+ skills) │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Blogging/ Research/ Art/ ... │ │
│ │ ├── SKILL.md ├── SKILL.md ├── SKILL.md │ │
│ │ ├── Workflows/ ├── Workflows/ ├── Workflows/ │ │
│ │ ├── Tools/ ├── Tools/ ├── Tools/ │ │
│ │ └── *.md └── *.md └── *.md │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────────────────────────────────────────────────┐
│ WORKFLOWS │
│ (Task procedures inside skills) │
│ Create.md Publish.md Deploy.md Research.md │
└─────────────────────────────────────────────────────────────┘Skills = Domain containers (Blogging, Research, Art, Security) Workflows = Task procedures (Create, Publish, Deploy - nested inside skills) Agents = Parallel workers (Engineer, Architect, Researcher - execute skills concurrently)
Skill Structure
Every skill follows this flat structure:
~/.claude/skills/
├── Blogging/ # Domain container (TitleCase)
│ ├── SKILL.md # Main file: triggers, routing, docs
│ ├── Voice.md # Context file (in root, NOT in subdirectory)
│ ├── Formatting.md # Context file (in root, NOT in subdirectory)
│ ├── Workflows/ # Task procedures only
│ │ ├── Create.md # Write new content
│ │ ├── Publish.md # Deploy to production
│ │ └── Rewrite.md # Edit existing content
│ └── Tools/ # CLI automation
│ └── DevServer.ts # TypeScript toolingKey rules:
- TitleCase naming everywhere (
Blogging, notblogging) - Context files in root (no
context/subdirectory) - Workflows/ contains only execution procedures
- Tools/ contains CLI automation scripts
- Maximum 2 levels deep (flat hierarchy)
Skill Anatomy: SKILL.md
The main skill file has two parts:
1. YAML Frontmatter (what triggers activation):
---
name: Blogging
description: Blog workflow. USE WHEN blog, website, publish, deploy, write.
---2. Markdown Body (routing and documentation):
# Blogging
## Workflow Routing
| Workflow | Trigger | File |
|----------|---------|------|
| **Create** | "write a post" | `Workflows/Create.md` |
| **Publish** | "deploy", "publish" | `Workflows/Publish.md` |
| **Rewrite** | "edit this post" | `Workflows/Rewrite.md` |Claude matches your intent to the description, loads the skill, and routes to the appropriate workflow.
The Three Tiers Explained
Tier 1: Skills (Domain Containers)
When to use: Organizing a domain of related capabilities.
Skills are self-contained modules. Everything for blogging lives in skills/Blogging/. Everything for research lives in skills/Research/.
When you say "write a blog post," the Blogging skill activates, analyzes your intent, and routes to Workflows/Create.md.
Tier 2: Workflows (Task Procedures)
When to use: Executing a specific task within a domain.
Workflows are step-by-step procedures that live inside their parent skill. They're the "how to do X" files.
Examples:
Blogging/Workflows/Create.md— How to write a new postResearch/Workflows/ExtensiveResearch.md— How to conduct deep researchArt/Workflows/Essay.md— How to create blog header images
Tier 3: Agents (Parallel Workers)
When to use: Concurrent execution of multiple tasks.
Agents are standalone files in ~/.claude/agents/ that execute work in parallel. They invoke skills and workflows as workers.
Example flow:
- You request complex research
- The Research skill spawns 3 parallel agents
- Each agent executes research workflows on different sources
- Results merge back together
Example: My Current Structure
~/.claude/
├── skills/ # 77+ domain containers
│ ├── Blogging/
│ │ ├── SKILL.md # Routing and documentation
│ │ ├── Voice.md # Writing style guidelines
│ │ ├── Formatting.md # Post structure rules
│ │ ├── Workflows/
│ │ │ ├── Create.md
│ │ │ ├── Publish.md
│ │ │ └── Rewrite.md
│ │ └── Tools/
│ │ └── DevServer.ts
│ ├── Research/
│ │ ├── SKILL.md
│ │ ├── Sources.md
│ │ ├── Workflows/
│ │ │ ├── QuickResearch.md
│ │ │ ├── StandardResearch.md
│ │ │ └── ExtensiveResearch.md
│ │ └── Tools/
│ ├── Art/
│ │ ├── SKILL.md
│ │ ├── Aesthetic.md
│ │ ├── Workflows/
│ │ │ ├── Essay.md
│ │ │ ├── TechnicalDiagrams.md
│ │ │ └── Mermaid.md
│ │ └── Tools/
│ │ └── Generate.ts
│ └── ... (74 more skills)
├── agents/ # Parallel workers
│ ├── Engineer.md
│ ├── Architect.md
│ ├── Researcher.md
│ └── ... (20+ agents)
└── MEMORY/ # Learning and state
├── LEARNING/
└── STATE/Key Benefits
Encapsulation: All blogging capabilities live in one place.
Discoverability: ls skills/Blogging/Workflows/ shows all blogging tasks.
Portability: Skills are self-contained and shareable.
Intent routing: Natural language triggers the right skill automatically.
Modularity: Small, focused files instead of monolithic prompts.
Decision Flowchart
When adding new capability, ask:
- Does this belong to an existing domain? → Add to that skill
- Is this a new domain? → Create new skill
- Is this a specific task? → Create workflow inside skill
- Does this need CLI automation? → Create tool inside skill
- Does this need parallel execution? → Create agent
The system is working well—I currently have 77 skills, hundreds of workflows, and 20+ agents, all following this structure.
Notes
- Simon Willison's analysis of Claude Skills from October 2025. Claude Skills are awesome, maybe a bigger deal than MCP
- Daniel's Personal AI Infrastructure project is open source. PAI on GitHub
- Anthropic's official Skills documentation. Agent Skills Documentation
- 🤖 AIL 1: Daniel wrote this post. I (Kai, his AI assistant) helped with proofreading, formatting, and the header image. Learn more about AIL.