Commands vs Skills vs Agents: Which to Build (Decision Framework)
A practical decision framework for choosing between Claude Code commands, skills, and agents. Includes decision tree, use cases, and migration paths.
Commands vs Skills vs Agents: Which to Build (Decision Framework)
Claude Code offers three primary extension types: commands, skills, and agents. Each serves a different purpose, and choosing the wrong one leads to awkward user experiences or unnecessary complexity.
This guide provides a clear decision framework. By the end, you'll know exactly which extension type fits your use case—and how to migrate between them when requirements change.
The Three Extension Types
Before diving into decisions, let's clarify what each type does:
Commands
Commands are user-triggered actions invoked with a slash. They execute a specific workflow when the user explicitly asks.
# /deploy
Deploy the application to the specified environment.
## Instructions
1. Run tests
2. Build the application
3. Deploy to target environment
4. Verify deployment
Invocation: /deploy staging
Key characteristic: Explicit user intent required.
Skills
Skills are passive context that shape Claude Code's behavior without explicit invocation. They're always available, influencing every interaction.
# TypeScript Standards
Always use strict TypeScript with these conventions:
- No `any` types
- Prefer interfaces over types
- Use named exports
Invocation: Automatic—always active.
Key characteristic: Background influence, no explicit trigger.
Agents
Agents are specialized personas with their own system prompts, focus areas, and sometimes tool restrictions. They can be triggered explicitly or automatically based on context.
# Security Auditor
You are a security expert. Your primary focus is identifying vulnerabilities.
## Expertise
- OWASP Top 10
- Authentication patterns
- Input validation
Invocation: Explicit (@security-auditor) or contextual (triggered by security-related tasks).
Key characteristic: Persona with specialized expertise.
The Decision Tree
Use this flowchart to determine which extension type you need:
START
│
▼
Does the user need to explicitly trigger this?
│
├── YES ──▶ Is it a multi-step workflow?
│ │
│ ├── YES ──▶ COMMAND
│ │
│ └── NO ──▶ Does it require a specialized persona?
│ │
│ ├── YES ──▶ AGENT
│ │
│ └── NO ──▶ COMMAND (simple)
│
└── NO ──▶ Should it influence ALL interactions?
│
├── YES ──▶ SKILL
│
└── NO ──▶ Should it activate for specific domains?
│
├── YES ──▶ AGENT (auto-triggered)
│
└── NO ──▶ Reconsider requirements
Decision Criteria Deep Dive
When to Build a Command
Build a command when:
1. The action requires explicit user intent
Users should decide when to run it. Examples:
/deploy- User chooses when to deploy/commit- User decides when to commit/review- User initiates code review
2. It's a multi-step workflow
The action involves multiple sequential steps:
- Run tests → Build → Deploy → Verify
- Fetch data → Transform → Generate report
3. It produces specific output
The result is a discrete artifact:
- Generated documentation
- Pull request description
- Test coverage report
4. It might be destructive or irreversible
Actions that modify external state should be explicit:
- Database migrations
- File deletions
- API calls with side effects
Command Examples
# /migrate
Run database migrations safely.
## Instructions
1. Check current migration status
2. Show pending migrations
3. Ask for confirmation
4. Run migrations
5. Verify database state
# /release
Create a new release.
## Instructions
1. Bump version number
2. Update changelog
3. Create git tag
4. Push to remote
5. Create GitHub release
When to Build a Skill
Build a skill when:
1. The context should always be available
The information is relevant to every interaction:
- Coding standards
- Project architecture
- Team conventions
2. It's reference material, not action
The content informs decisions rather than executing steps:
- API documentation
- Design patterns to follow
- Error handling guidelines
3. It should influence default behavior
You want to change how Claude Code operates by default:
- Always use TypeScript strict mode
- Follow conventional commits
- Prefer functional patterns
4. No explicit trigger makes sense
You can't imagine a user saying "now apply coding standards"—they should just always apply.
Skill Examples
# Project Architecture
## Structure
- /src/components - React components
- /src/hooks - Custom hooks
- /src/lib - Utilities
- /src/api - API clients
## Patterns
- Use React Query for data fetching
- Use Zustand for state management
- Use Tailwind for styling
All code should follow these patterns unless explicitly told otherwise.
# Error Handling Standards
## Requirements
- All async functions must have try/catch
- Errors should be logged with context
- User-facing errors need friendly messages
- Internal errors need stack traces
## Example
```typescript
async function fetchUser(id: string) {
try {
return await api.get(`/users/${id}`);
} catch (error) {
logger.error('Failed to fetch user', { id, error });
throw new UserFetchError(id, error);
}
}
### When to Build an Agent
Build an agent when:
**1. The task requires a specialized persona**
The expertise is deep and focused:
- Security auditor
- Performance optimizer
- Accessibility expert
**2. The interaction style should change**
The agent should communicate differently:
- More technical depth
- Different priorities
- Specific output formats
**3. Domain expertise is the primary value**
The agent brings knowledge, not just process:
- Understanding of security vulnerabilities
- Performance optimization patterns
- Accessibility requirements
**4. Context switching is valuable**
Users benefit from explicitly entering a specialized mode:
- "Now I want security focus"
- "Let's optimize performance"
- "Check accessibility compliance"
### Agent Examples
```markdown
# Performance Expert
You are a performance optimization specialist. Every suggestion should consider:
- Time complexity
- Space complexity
- Network efficiency
- Rendering performance
## Communication Style
- Lead with impact: "This change will reduce load time by ~200ms"
- Provide benchmarks when possible
- Explain trade-offs clearly
## Focus Areas
- Bundle size optimization
- Database query efficiency
- Caching strategies
- Lazy loading opportunities
# Accessibility Auditor
You are an accessibility expert ensuring WCAG 2.1 AA compliance.
## Automatic Checks
- Semantic HTML usage
- ARIA attribute correctness
- Color contrast ratios
- Keyboard navigation
- Screen reader compatibility
## Output Format
For each issue:
- [LEVEL] Criterion violated
- Location in code
- Impact on users
- Remediation steps
Comparison Matrix
| Aspect | Command | Skill | Agent |
|---|---|---|---|
| Trigger | Explicit (/command) | Automatic | Explicit or contextual |
| Purpose | Execute workflow | Provide context | Specialized expertise |
| Interaction | One-shot | Background | Conversational |
| Output | Specific result | Influenced behavior | Domain-focused response |
| User control | High | Low | Medium |
| Complexity | Medium | Low | High |
Hybrid Patterns
Often, the best solution combines multiple types:
Command + Skill
A command that relies on skills for context:
# Skill: Review Standards
(Defines what to check, severity levels, etc.)
# Command: /review
(Executes the review using the standards)
Agent + Commands
An agent with specialized commands:
# Agent: DevOps Expert
(Provides infrastructure expertise)
# Command: /deploy (within agent context)
(Deployment workflow with DevOps knowledge)
Skill + Hooks
Skills that enforce themselves via hooks:
# Skill: Security Standards
(Defines security requirements)
# Hook: PreToolUse
(Validates operations against security standards)
Migration Paths
Requirements change. Here's how to migrate between types:
Command → Skill
When: The command is being invoked constantly, suggesting it should always apply.
Before (Command):
# /strict-types
Enable strict TypeScript checking for this file.
After (Skill):
# TypeScript Standards
Always use strict TypeScript. Never allow `any` types.
Skill → Agent
When: The skill needs deeper expertise and specialized interaction.
Before (Skill):
# Security Guidelines
Check for XSS, SQL injection, etc.
After (Agent):
# Security Auditor
You are a security expert. Beyond basic checks, you understand:
- Attack vectors and exploitation
- Defense in depth strategies
- Secure architecture patterns
Agent → Command
When: The agent's value is really in one specific workflow.
Before (Agent):
# Documentation Expert
Generate comprehensive documentation.
After (Command):
# /generate-docs
Generate API documentation for the specified module.
Command → Agent
When: The command needs more context and conversational depth.
Before (Command):
# /security-scan
Scan for security vulnerabilities.
After (Agent):
# Security Auditor
Perform thorough security analysis. Can be invoked for:
- Full codebase audits
- Specific vulnerability investigation
- Security architecture review
Anti-Patterns to Avoid
1. The "Do Everything" Command
Problem: A command that tries to do too much.
# /develop
1. Review code
2. Fix issues
3. Write tests
4. Update docs
5. Create commit
6. Open PR
Solution: Break into focused commands (/review, /test, /commit, /pr).
2. The "Never Used" Skill
Problem: A skill with content that rarely applies.
# Kubernetes Deployment Standards
(In a project that deploys to Kubernetes once a year)
Solution: Make it a command (/k8s-deploy) that loads context when needed.
3. The "Personality-Only" Agent
Problem: An agent that's just a persona with no real expertise.
# Friendly Coder
You are a friendly, helpful coder. Be nice!
Solution: That's not an agent—it's a system prompt preference. Add real domain expertise.
4. The "Trigger-Happy" Hook
Problem: A hook that fires too often, slowing everything down.
---
event: PreToolUse
# No tool filter - matches EVERYTHING
---
Solution: Filter to specific tools and operations.
Real-World Decision Examples
Example 1: Code Formatting
Requirement: Ensure code follows formatting standards.
Analysis:
- Should it always apply? Yes
- Does it require explicit trigger? No
- Is it reference information? Yes
Decision: Skill
# Code Formatting
Use Prettier with these settings:
- 2 space indentation
- Single quotes
- No semicolons
- Trailing commas
Example 2: Database Migration
Requirement: Run database migrations safely.
Analysis:
- Does it need explicit trigger? Yes (destructive)
- Is it a multi-step workflow? Yes
- Does it need specialized persona? No
Decision: Command
# /migrate
Run database migrations with safety checks.
Example 3: Accessibility Review
Requirement: Review UI for accessibility compliance.
Analysis:
- Is it a workflow or expertise? Expertise
- Does interaction style change? Yes (WCAG focus)
- Is deep domain knowledge needed? Yes
Decision: Agent
# Accessibility Expert
WCAG 2.1 AA compliance specialist.
Example 4: Git Commit Messages
Requirement: Ensure commits follow conventional format.
Analysis:
- Should it always apply? Yes
- Is it enforcing standards? Yes
- Could a hook handle it? Yes
Decision: Skill + Hook
# Skill: Commit Standards
# Hook: PreToolUse (validates git commit commands)
Conclusion
The choice between commands, skills, and agents isn't arbitrary—it follows clear principles:
- Commands: User-triggered workflows with specific outputs
- Skills: Background context that shapes all interactions
- Agents: Deep domain expertise with specialized personas
Start by asking: "Does this need explicit user intent?" If yes, it's a command. If no, ask: "Does this need specialized expertise?" If yes, it's an agent. Otherwise, it's a skill.
And remember—you can always migrate. Start with the simplest option that works, and evolve as you learn how it's actually used.
Ready to boost your productivity? Check out our Keyboard Shortcuts Guide to work 10x faster in Claude Code.