When to Use a Claude Skill vs a Claude Sub-Agent

Skills: Prompt Templates That Inject Instructions

Skills are specialized prompt templates that inject domain-specific instructions into Claude's current context when relevant.

Think of them like this: you're working on a React component. Claude detects "React" in your files and loads a skill with patterns like "use explicit props over spreading" or "prefer function components." Those instructions guide Claude's responses for that specific task.

Key characteristics:

• Model-invoked: Claude decides when to load them based on context
• Lightweight: Start at ~few dozen tokens
• Progressive disclosure: Load only relevant information as needed
• No direct execution: They guide responses, not run code
• Personal or project-scoped: ~/.claude/skills/ or .claude/skills/

What they contain:

• Specialized instructions
• Design patterns
• Coding conventions
• Templates and examples
• Domain-specific knowledge
• Documentation references

Sub-Agents: Isolated AI Assistants for Complex Tasks

Sub-agents are specialized AI assistants that run in separate context windows with their own system prompts and tool access.

Think of them like this: you ask Claude to review your entire codebase for security issues. That's not a quick task—it needs multiple steps, careful analysis, and its own context. A sub-agent spins up, does the work, and reports back with findings.

Key characteristics:

• User-invoked or automatic: Ask Claude to "use the security-reviewer agent" or Claude invokes them automatically when appropriate
• Full context: Complete context window for complex work
• Tool access: Can read files, run commands, execute code
• Autonomous: Complete multi-step tasks independently
• Maintains expertise: Specialized system prompts for specific domains

What they do:

• Multi-step code reviews
• Architecture analysis
• Complex refactoring across multiple files
• Documentation generation
• Test suite creation
• Specialized problem-solving

Scenario 1: Reusable Coding Patterns

You have a house style for TypeScript that you want applied consistently: named exports only, no default exports, explicit return types.

Use a skill:

---
name: typescript-conventions
description: TypeScript coding standards for our codebase
---

# TypeScript Conventions

## Exports
- Use named exports only
- Never use default exports
- Group related exports at end of file

## Type Annotations
- Explicit return types on all functions
- No implicit any
- Prefer interfaces over types for objects

## Code Organization
- One component per file
- Co-locate tests with implementation
- Use barrel exports for directories

Save this as .claude/skills/typescript-conventions/SKILL.md. Claude loads it when working on TypeScript files and applies these patterns automatically.

Why this works: The patterns are simple, contextual, and apply across many files. You don't need a separate context window—you just need Claude to remember your preferences.

Scenario 2: Framework-Specific Knowledge

You're migrating to Next.js App Router. There are dozens of gotchas: async components, client boundaries, route segments, metadata API.

Use a skill:

prpm install @nextjs/app-router

This skill contains:

• Server component patterns
• When to use 'use client'
• Metadata API examples
• Loading/error state conventions
• Route group patterns

Claude loads this when it detects Next.js and App Router in your project. You get framework-specific guidance without constantly looking up docs.

Why this works: The knowledge is specific to Next.js App Router but applies to many files. Skills enable progressive disclosure—Claude loads route group patterns only when you're actually working on route organization.

Scenario 3: Domain-Specific Vocabulary

You're working on a fintech app with specific terminology: "settlements," "clearing," "merchant accounts," "payment rails."

Use a skill:

---
name: fintech-glossary
description: Domain terminology for payment processing
---

# Payment Processing Terms

## Settlement
The process of transferring funds from acquiring bank to merchant account.
- Batch settlement: Once per day
- Real-time settlement: Within minutes (premium)

## Clearing
Reconciliation between issuing and acquiring banks.
- Timeline: T+1 to T+3
- Handles chargebacks and disputes

## Merchant Account
Bank account that holds funds before settlement.
- Reserve requirements: 5-20% typical
- Rolling reserve: Held for 6 months

[...]

Now when you discuss payments, Claude uses correct terminology and understands domain constraints.

Why this works: Domain knowledge improves all conversations about this topic. It doesn't need isolated execution—it needs consistent context.

Scenario 4: Testing Standards

You want every PR to include specific test types: unit tests, integration tests, edge case coverage.

Use a skill:

---
name: testing-standards
description: Testing requirements for all code changes
---

# Testing Standards

## Required Coverage
- Unit tests for all public functions
- Integration tests for API endpoints
- Edge case tests for error handling
- No tests for trivial getters/setters

## Test Organization
- Co-locate tests with implementation
- Use descriptive test names (no "test1", "test2")
- One assertion per test when possible
- Mock external dependencies

## Edge Cases to Cover
- Null/undefined inputs
- Empty arrays/objects
- Boundary values (0, -1, max)
- Concurrent operations
- Network failures

Claude references this when writing or reviewing code, ensuring consistent test coverage.

Why this works: Testing standards apply to many files and many conversations. Skills make them available without repeating yourself.

Scenario 1: Comprehensive Code Review

You need a security audit of your authentication flow across multiple files.

Use a sub-agent:

Ask Claude: "Use the security-reviewer agent to audit my auth flow"

The sub-agent:

1. Reads all authentication-related files
2. Traces token flow from login to protected routes
3. Checks for common vulnerabilities (CSRF, XSS, SQL injection)
4. Tests edge cases (expired tokens, concurrent logins)
5. Reports findings with severity levels and file locations

Why this works: This requires reading dozens of files, maintaining context across the entire auth system, and applying specialized security knowledge. A sub-agent maintains its own context window and can spend hundreds of tokens analyzing each file.

You can't do this with a skill—skills don't execute tasks, they guide responses.

Scenario 2: Large-Scale Refactoring

You're renaming a core abstraction used in 50+ files with inconsistent patterns.

Use a sub-agent:

Ask Claude: "Use the refactoring-assistant agent to help rename this abstraction"

The sub-agent:

1. Searches codebase for all uses of the old name
2. Analyzes context to understand each usage pattern
3. Generates refactoring plan with risk assessment
4. Updates files incrementally with safety checks
5. Runs tests after each batch to catch breaks early

Why this works: This is a complex multi-step task requiring careful coordination and error handling. Sub-agents can maintain state across steps and adapt their approach based on results.

A skill would just tell Claude how to refactor. A sub-agent actually does the refactoring.

Scenario 3: Architecture Analysis

You need to document the architecture of an unfamiliar codebase you just inherited.

Use a sub-agent:

Ask Claude: "Use the architecture-documenter agent to analyze this codebase"

The sub-agent:

1. Scans directory structure for entry points
2. Traces dependencies to map data flow
3. Identifies design patterns and architectural decisions
4. Documents module responsibilities
5. Generates diagrams (Mermaid format)
6. Flags potential issues (tight coupling, circular deps)

Why this works: Understanding architecture requires reading the entire codebase systematically, maintaining a mental model across hundreds of files, and synthesizing high-level insights. That's exactly what sub-agents excel at.

Scenario 4: Specialized Problem Domains

You're debugging a complex distributed systems issue with race conditions.

Use a sub-agent:

Ask Claude: "Use the distributed-systems-expert agent to analyze this race condition"

The sub-agent has a specialized system prompt with deep knowledge of:

• CAP theorem implications
• Consistency models (eventual, strong, causal)
• Common race conditions in distributed systems
• Debugging techniques for non-deterministic bugs

It analyzes your logs, traces, and code to identify the specific race condition and suggest fixes.

Why this works: Distributed systems expertise requires deep specialized knowledge applied systematically across multiple files and logs. The sub-agent's isolated context lets it maintain the mental model needed for this complexity.

How Skills Work Under the Hood

Skills use Claude's tool-use capability but in a clever way. They're "meta-tools"—prompt templates that inject specialized instructions into Claude's context.

Simon Willison calls them "lightweight and practical." Lee Hanchung explains they "enable progressive disclosure of context, allowing agents to load only relevant information as needed."

The loading mechanism:

1. You start a task involving React components
2. Claude's model sees "React" in file paths and content
3. It autonomously invokes the get_skill tool: get_skill("react-patterns")
4. The skill content gets injected into current context
5. Claude now has React-specific guidance for this conversation

Token efficiency:

• Initial injection: ~50-200 tokens (just metadata)
• Full load: ~500-2000 tokens (if Claude needs details)
• Progressive: More context loaded only if needed

No code execution: Skills cannot run scripts, read files, or execute commands. They provide instructions. Claude still does the work.

How Sub-Agents Work Under the Hood

Sub-agents run in completely isolated context windows with their own system prompts.

The isolation mechanism:

1. You ask: "Use the security-reviewer agent"
2. Claude spawns new context window
3. Loads sub-agent's custom system prompt
4. Sub-agent has full tool access (read files, run commands)
5. Maintains conversation state independently
6. Reports back to main context when done

Token budget:

• Separate allocation from main conversation
• Can use thousands of tokens without affecting your main work
• Context preserved across sub-agent's entire task

Full autonomy: Sub-agents can execute complex workflows without constant user input. They make decisions, adapt based on results, and complete multi-step processes.

Why the Distinction Matters

Anthropic explains: "Skills feel closer to the spirit of LLMs"—they're about guiding the model with context, not programming task automation.

Sub-agents are for when guidance isn't enough. When you need actual execution, systematic analysis, or isolated expertise.

Getting this wrong:

• Using sub-agent for code style → waste of context window
• Using skill for code review → can't analyze multiple files
• Using sub-agent for glossary → unnecessary complexity
• Using skill for refactoring → no execution capability

Installing Skills from PRPM

# Install a skill
prpm install @nextjs/app-router
prpm install @stripe/migration-guide
prpm install @testing/jest-patterns

These go to .claude/skills/ and Claude loads them automatically based on context.

Installing Sub-Agents from PRPM

# Install a sub-agent
prpm install @code-review/security-auditor
prpm install @refactoring/architecture-analyzer
prpm install @documentation/api-documenter

These go to .claude/agents/ and you invoke them by asking: "Use the security-auditor agent"

Publishing Your Own

Package structure is identical:

Skill:

my-skill/
├── SKILL.md           # Main content with metadata
└── examples/          # Optional supporting files

Sub-agent:

my-agent/
├── agent.md           # Agent definition with system prompt and metadata
└── tools/             # Optional tool configs

The registry handles both. Install command is the same. Only difference is where they land and how Claude uses them.

Why PRPM matters here:

1. Cross-editor support: Skills work in Claude Code today. Tomorrow you might use Cursor. PRPM converts formats automatically.
2. Versioning: Lock skills and sub-agents to specific versions. Prevent breaking changes.
3. Collections: Install related skills as bundles:

   prpm install collection/nextjs-full-stack  # Gets app-router, api-routes, deployment skills

4. Discovery: Browse 6,000+ packages in the registry. Find skills for your framework, language, or domain.