Agent Types

Not every subagent needs full tool access. Agents provide several specialized agent types, each optimized for a particular category of work. Choosing the right agent type improves both performance and safety — a read-only explorer cannot accidentally modify your codebase, and a planning agent can focus on architecture without getting distracted by implementation details.

Overview of Agent Types

When you dispatch a subagent via the Task tool, you can specify a type parameter that controls what tools the agent has access to and how it behaves. The available types are:

• General-purpose (default) — Full tool access, suitable for any task.
• Explore — Read-only codebase search and analysis. Fast and lightweight.
• Plan — Architecture and design work. Produces plans but does not execute them.
• Custom — You define the exact tool set through skill configuration.

General-Purpose Agents

The default agent type has access to every tool available in the agent: Read, Write, Edit, Bash, Glob, Grep, WebFetch, and more. This is the most flexible type and is appropriate when the subagent needs to both analyze and modify the codebase.

---
description: Add error handling to all API route handlers
allowed-tools:
  - Task
---

# Add Error Handling

Use the Task tool to launch a general-purpose subagent:

"Find all API route handler files in src/app/api/**/route.ts.
 For each handler that lacks a try/catch wrapper, add standardized
 error handling using the AppError class from @/lib/errors.
 Run the type checker after modifications to ensure no type errors.
 Return a summary of which files were modified."

This agent needs full tool access because it will:
- Glob and Grep to find files (read tools)
- Read to analyze current error handling
- Edit to add try/catch wrappers (write tools)
- Bash to run the type checker (execution tools)

General-purpose agents are powerful but carry risk. They can run arbitrary shell commands and modify any file. Use them when the task genuinely requires both read and write capabilities.

Explore Agents

Explore agents are optimized for fast, read-only codebase navigation. They have access to search and read tools only — Glob, Grep, Read, and WebFetch. They cannot write files, run shell commands, or make modifications. This makes them safe to dispatch without worrying about side effects.

---
description: Find all usages of a deprecated API and report migration paths
allowed-tools:
  - Task
---

# Deprecated API Finder

Launch an Explore-type subagent to search the codebase:

Use the Task tool with the following prompt:

"Search the entire codebase for usages of the deprecated
 `legacyHttpClient` import from @/lib/http.

 For each usage found:
 1. Note the file path and line number
 2. Identify which method is being called (get, post, put, delete)
 3. Check if the file already imports the new `httpClient`
 4. Determine the complexity of migration (simple drop-in vs. needs refactoring)

 Return a structured report sorted by migration complexity."

The subagent should be Explore type — it only needs to read and search.
It does not need to modify anything.

Explore agents are the workhorse of codebase analysis. Because they cannot modify anything, you can safely launch multiple explore agents in parallel without worrying about conflicts or race conditions.

Plan Agents

Plan agents are designed for architecture and design work. They can read the codebase to understand the current state, but their primary output is a structured plan — not code modifications. Plan agents have read access plus the ability to create structured documents, but they do not execute changes.

---
description: Design the migration plan for moving from REST to GraphQL
allowed-tools:
  - Task
---

# GraphQL Migration Planner

Launch a Plan-type subagent:

"You are an architecture planning agent. Analyze the current REST API
 structure in src/app/api/ and design a migration plan to GraphQL.

 Your plan should include:

 1. **Schema Design**
    - Map each REST endpoint to a GraphQL type
    - Identify shared types that can be unified
    - Design the Query and Mutation root types

 2. **Migration Phases**
    - Phase 1: Add GraphQL alongside REST (parallel running)
    - Phase 2: Migrate consumers to GraphQL
    - Phase 3: Deprecate REST endpoints
    - Phase 4: Remove REST endpoints

 3. **Risk Assessment**
    - Which endpoints have the most consumers?
    - Which endpoints have complex query patterns?
    - What are the breaking change risks?

 4. **Effort Estimates**
    - T-shirt size each phase (S/M/L/XL)
    - Identify which phases can be parallelized

 Return the plan as a structured markdown document."

This agent only needs to read and analyze. It should NOT make any changes.

Plan agents are valuable for the "analyze then execute" pattern. You dispatch a plan agent first to understand the scope of work, review its plan, and then dispatch a general-purpose agent to execute the approved plan. This separation gives you a review checkpoint before any modifications happen.

Custom Agent Configurations

Sometimes the built-in types do not match your needs exactly. Custom agent configurations let you specify the precise tool set a subagent should have. You do this by combining the Task tool dispatch with explicit tool restrictions in the prompt.

---
description: Run the deployment safety checklist
allowed-tools:
  - Task
---

# Deployment Safety Check

Launch a custom subagent with restricted tool access:

"You are a deployment readiness checker. You have access to
 Read, Glob, Grep, and Bash. Use ONLY these tools.

 Run the following checks:

 1. `npm run typecheck` — must pass with zero errors
 2. `npm run test -- --coverage` — coverage must be above 80%
 3. `npm run lint` — must pass with zero warnings
 4. Check that CHANGELOG.md has an entry for the current version
 5. Check that no .env files are staged in git
 6. Verify package.json version matches git tag

 For each check, report PASS or FAIL with details.
 If ANY check fails, prominently state DEPLOYMENT BLOCKED
 at the top of your response."

This agent gets Bash access for running commands but NOT Write/Edit access.
It can verify the codebase state but cannot modify it.

Choosing the Right Type

The decision of which agent type to use comes down to the principle of least privilege. Give each subagent only the capabilities it actually needs:

• Just searching? Use an Explore agent. It is fast, safe, and can be parallelized freely.
• Designing or planning? Use a Plan agent. It forces a structured output without the temptation to start implementing prematurely.
• Need to read and write? Use a general-purpose agent, but scope its task narrowly so it does not make changes outside its mandate.
• Need specific tool combinations? Use a custom configuration. For example, an agent that can Read and Bash but not Write is perfect for validation and testing tasks.

Combining Agent Types in a Workflow

The most powerful skills combine multiple agent types in a coordinated workflow. A typical pattern is:

1. Explore agent scans the codebase and gathers data.
2. Plan agent takes the exploration results and designs a change plan.
3. General-purpose agent executes the approved plan.
4. Custom validation agent (Read + Bash) verifies the changes are correct.

This pipeline ensures that each phase has exactly the capabilities it needs, maximizes safety, and creates natural review points between analysis, planning, and execution.

What's Next

Now that you understand the different agent types and how to choose between them, the next lesson covers hooks integration — how skills can work together with the agent's hook system for event-driven automation.