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

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.