Skills vs Commands vs Agents: Choosing the Right Tool

Claude Code offers three main extensibility mechanisms: skills, commands, and agents. Each serves a different purpose and works differently. Choosing the right tool for your task makes the difference between a smooth workflow and fighting against the system.

This guide explains each tool in depth, compares them directly, and provides guidance on when to use which.

Understanding Each Tool

Skills: Session-Wide Context

Skills are markdown files that load at session start and persist throughout. They shape how Claude understands and responds to requests in a specific domain.

Location: ~/.claude/skills/

Structure:

# Skill Name

Instructions that shape Claude's behavior for this domain.

## Guidelines
What Claude should know and do.

## Output Format
How responses should be structured.

Activation: Automatic (based on project context) or explicit loading.

Lifespan: Entire session until unloaded.

Example use: Python code review standards, API documentation format, security review criteria.

Commands: Triggered Actions

Commands are single-purpose operations triggered by a slash. They execute a specific task and complete.

Location: ~/.claude/commands/

Structure:

---
description: What this command does
arguments:
  - name: argument_name
    description: What this argument is for
---

# Command Name

Instructions for this specific action.

Activation: Explicit trigger with /command-name

Lifespan: Single execution.

Example use: /commit to create a commit, /format to format code, /test to run tests.

Agents: Autonomous Workflows

Agents are goal-oriented systems that observe, decide, and act autonomously. They pursue objectives through multiple steps without constant human direction.

Location: ~/.claude/agents/

Structure:

---
description: What this agent does
tools:
  - filesystem
  - shell
  - git
---

# Agent Name

## Objective
The goal this agent pursues.

## Decision Framework
How this agent makes decisions.

## Execution Process
Steps this agent follows.

## Termination Conditions
When this agent stops.

Activation: Explicit invocation or event trigger.

Lifespan: Until objective achieved or limits reached.

Example use: Code cleanup agent, test generation agent, documentation sync agent.

Detailed Comparison

Scope of Influence

Skills influence every related interaction. Load a Python skill, and all Python-related responses improve.

Commands execute once. Run /commit, get a commit, done.

Agents work toward goals, executing multiple steps, making decisions, iterating until complete.

Control Model

Skills: Passive Influence

You ask question → Skill context shapes response → Response

The skill does not initiate action. It shapes how Claude understands and responds.

Commands: Direct Execution

You trigger /command → Command executes → Output → Done

You initiate, command runs, task completes.

Agents: Autonomous Operation

You set goal → Agent plans → Agent executes step → Agent evaluates →
Agent decides next step → Agent executes → ... → Goal achieved

You set the goal, agent takes over until completion or termination.

Complexity Handling

Skills: Handle complexity by providing comprehensive context for a domain. Complex domains get complex skills.

Commands: Handle complexity by being specific. One command does one thing well. Complex workflows chain multiple commands.

Agents: Handle complexity by making decisions. They adapt to what they find and adjust their approach.

User Interaction

Skills: Zero interaction during use. Load once, forget they are there.

Commands: Minimal interaction. Trigger, possibly provide arguments, receive output.

Agents: Variable interaction. Some agents work fully autonomously. Others checkpoint for human confirmation at key points.

Decision Framework

Use a Skill When:

1. You need consistent behavior across many interactions

   • Code reviews should always check the same things
   • Documentation should always follow the same format
   • Error handling should always follow team standards

2. You are establishing domain expertise

   • Teaching Claude about your API structure
   • Explaining your coding conventions
   • Describing your testing philosophy

3. The instructions apply broadly

   • Not task-specific but domain-specific
   • Relevant to many different requests
   • Part of a consistent methodology

4. You want to set and forget

   • No per-use configuration
   • No manual triggering
   • Always active when relevant

Skill Example: TypeScript Standards

# TypeScript Standards

When working with TypeScript in this project:

## Type Strictness
- Use strict mode
- Avoid `any` type
- Prefer `unknown` over `any` for external data
- Use type guards for runtime validation

## Conventions
- Interface names: IUserService
- Type names: UserDTO
- Enum names: UserStatus
- Generic parameters: T, K, V for standard, descriptive for complex

## Best Practices
- Discriminated unions over type assertions
- Const assertions for literals
- Utility types (Pick, Omit, Partial) over manual typing
- Generic constraints for type safety

Use a Command When:

1. You have a repeatable, discrete task

   • Create a commit
   • Run tests
   • Format code
   • Generate documentation

2. The task has clear start and end

   • Trigger → Execute → Done
   • No ongoing influence needed
   • Results are immediate

3. You want to trigger explicitly

   • User decides when to run
   • Not automatic background behavior
   • Control over timing

4. The task might need parameters

   • /commit "message" - commit with custom message
   • /test --coverage - test with coverage
   • /deploy staging - deploy to specific environment

Command Example: Generate Tests

---
description: Generate unit tests for a file
arguments:
  - name: file
    description: File to generate tests for
---

# Generate Tests

Generate comprehensive unit tests for the specified file.

## Process
1. Analyze the file to understand its structure
2. Identify all exported functions and classes
3. For each function:
   - Test normal execution paths
   - Test edge cases
   - Test error conditions
4. Output test file following project conventions

## Output
Create a test file named `[original_name].test.ts` with:
- Imports from testing framework
- Describe blocks for each function/class
- It blocks for each test case
- Setup/teardown as needed

Use an Agent When:

1. The task requires multiple decisions

   • What to do depends on what you find
   • Different paths for different situations
   • Cannot predetermine exact steps

2. The task is goal-oriented, not task-oriented

   • "Clean up the codebase" vs "remove unused import"
   • "Ensure tests pass" vs "run tests"
   • "Document the API" vs "add docstring to function"

3. Autonomy is desirable

   • You want to set a goal and walk away
   • Human intervention should be exception not rule
   • The task might take significant time

4. The task involves iteration

   • Try something, evaluate, adjust
   • Repeat until satisfactory
   • Learn from intermediate results

Agent Example: Documentation Sync

---
description: Keep documentation in sync with code
tools:
  - filesystem
  - git
---

# Documentation Sync Agent

## Objective
Ensure all public APIs have accurate, up-to-date documentation.

## Decision Framework

### What to Document
- All exported functions
- All exported classes and their public methods
- All exported types and interfaces
- All exported constants with non-obvious values

### Documentation Quality
- Description explains purpose, not implementation
- Parameters fully documented with types
- Return values documented
- Exceptions/errors listed
- Examples for complex functionality

## Process

### Phase 1: Discovery
1. Scan all source files
2. Identify public exports
3. Match with existing documentation
4. Flag undocumented or stale items

### Phase 2: Documentation
For each flagged item:
1. Read the code thoroughly
2. Understand the purpose
3. Draft documentation
4. Verify accuracy

### Phase 3: Verification
1. Check for consistency
2. Validate examples run correctly
3. Cross-reference with tests

## Termination
Complete when:
- All public APIs documented
- All documentation verified
- Changes committed with summary

Combining Tools

The real power emerges from combining tools:

Skills + Commands

Skills set context, commands execute:

Session with TypeScript skill loaded:

/commit → Creates commit following TypeScript conventions
/test → Runs tests considering TypeScript best practices
/review → Reviews code against TypeScript standards

The skill ensures commands operate within your standards.

Skills + Agents

Skills guide agent behavior:

Session with Security skill loaded:

Agent: Code cleanup
→ Cleanup considers security implications
→ Does not remove security checks
→ Flags potential vulnerabilities found

The skill shapes how the agent makes decisions.

Commands + Agents

Commands can invoke agents:

---
description: Deep clean the codebase
---

# Deep Clean Command

Run the cleanup agent with these parameters...

Invoke: cleanup-agent with scope=full

Commands provide the trigger; agents provide the intelligence.

All Three Together

Load: python-standards skill
Load: security skill

/deep-review → Invokes review-agent

Agent considers:
- Python standards from skill
- Security requirements from skill
- Its own review methodology
- Specific project context

Produces comprehensive, standards-compliant review

Common Patterns

Pattern: Domain + Actions

Skills for domain expertise:

• python-standards
• react-patterns
• api-design

Commands for actions in that domain:

• /format
• /lint
• /document
• /test

The domain skills ensure all actions follow proper conventions.

Pattern: Quality Gates

Skills for quality criteria:

• code-quality
• security-standards
• performance-requirements

Agent for enforcement:

• quality-gate-agent

Agent checks code against all loaded skill criteria before allowing merge.

Pattern: Progressive Automation

Start with commands for manual control:

/commit → /push → /pr-create

Evolve to agent for automation:

/ship → Agent handles commit, push, PR with intelligence

The agent replaces the command chain with goal-oriented execution.

Anti-Patterns

Skill as Command

Wrong:

# Format Code

When user says "format", format the code.

This is a command pretending to be a skill. Use a command instead.

Command as Skill

Wrong:

---
description: Python code standards
---

Apply these standards to all Python code...

Putting ongoing standards in a command file. They will not persist. Use a skill.

Agent for Simple Task

Wrong: Using an agent to format a single file. Commands are simpler and faster for discrete tasks.

Skill for One-Time Task

Wrong: Creating a skill for a unique, never-to-be-repeated task. Just write a prompt.

Summary

Skills are context. They shape understanding and persist throughout sessions. Use them for standards, domain knowledge, and consistent behavior.

Commands are actions. They execute specific tasks when triggered. Use them for repeatable, discrete operations with clear inputs and outputs.

Agents are goals. They pursue objectives autonomously through multiple steps. Use them for complex, decision-requiring workflows that benefit from autonomy.

The right choice depends on:

• Scope: Domain-wide vs. single task vs. goal pursuit
• Duration: Session vs. execution vs. until complete
• Control: Passive influence vs. triggered action vs. autonomous operation
• Complexity: Context shaping vs. single task vs. multi-step decisions

Most effective setups combine all three: skills for expertise, commands for actions, agents for complex workflows.

---

Ready to design effective skills? Continue to Anatomy of an Effective AI Skill to learn the components that make skills work.