Video Lesson: Create a custom subagent in Claude Code

This lesson is being re-recorded

A new video is coming soon. The written lesson below is from the previous version, so some info may be out of date.

Lessons

Create a custom subagent in Claude Code

Build a PHPDoc generator subagent in .claude/agents and run several copies of it in parallel across a Laravel codebase.


Lesson Content

Subagents really shine when you need to do the same task across many files at once. Instead of processing files one by one in your main thread, you can spawn off multiple subagents that work in parallel, and each has its own context window.

Let's build a really useful example: a PHPDoc generator agent that documents your entire Laravel codebase.

Why PHPDoc generation?

Generating docblocks within a subagent makes sense because it's low-risk and highly visible. The subagent will read your code, understand what each method does, and add the related documentation -- without touching any actual logic.

It's also a task that benefits massively from running in parallel. Rather than documenting one file at a time, multiple agents can be spawned off at the same time to document your controllers, models, services, and all other classes.

Create the subagent file

Subagents live in the .claude/agents/ directory within your project. If it doesn't exist, you can create it:

mkdir -p .claude/agents

Then let's create a new file called phpdoc-generator.md with the contents:

---
name: phpdoc-generator
description: Generates PHPDoc blocks for PHP classes and methods. Use proactively when asked to document code or add docblocks.
tools: Read, Edit, Glob, Grep
model: sonnet
---

You are a PHPDoc documentation specialist for Laravel applications.

When invoked, you will be given a specific directory or file path to document. Your job is to add comprehensive PHPDoc blocks to all classes and methods in that scope.

For each class, add:
- A description of the class purpose
- @package annotation

For each method, add:
- A brief description of what it does
- @param annotations for all parameters with types and descriptions
- @return annotation with type and description
- @throws annotations if exceptions are thrown

Rules:
- Never modify actual code logic; only add or update docblocks
- Preserve existing docblocks if they're already comprehensive
- Use Laravel-appropriate types (Collection, Model, Request, etc.)
- Keep descriptions concise but meaningful
- Match the existing code style

When complete, report which files were documented and how many methods were processed.

That's it -- your subagent is now ready to use.

Using your subagent

You can invoke it explicitly by asking Claude Code to use it:

Document all my controllers using the phpdoc-generator agent

You can also direct it to spawn off multiple instances to work in parallel, if you have many files to be processed at once:

Use the phpdoc-generator agent to document every class within the app directory. Spawn separate agents for each directory within it; app/Models, app/Http/Controllers, app/Services, etc.

Claude Code will now spin up as many subagents as it needs to, and each will work at the same time and within their own context window. They'll run simultaneously, then report back their findings to your main conversation thread.

How it works under the hood

When you trigger parallel execution, each subagent:

  1. Gets its own isolated context window

  2. Receives the specific path or scope you assigned

  3. Works autonomously without needing feedback

  4. Returns a summary to your main conversation

Your main thread stays clean and focused while the subagents handle the heavy lifting. Once they finish, you get a consolidated report of everything that was documented.