Agent Prompt Guide: Writing Effective Sub-Agent Descriptions

Agent Prompt Guide: Writing Effective Sub-Agent Descriptions

This guide explains how to write agent descriptions that enable Claude Code to **automatically delegate** tasks to your specialized sub-agents.

The Pattern

For Claude Code to proactively use your sub-agents, your agent description must follow this pattern:

description: [What the agent does]. Use PROACTIVELY when [specific trigger scenarios].

Required Components

1. The PROACTIVELY Keyword

This signals to Claude Code that it should use this agent without being explicitly asked.

Use PROACTIVELY when...

**Alternative phrasing:**

• Specialist for [task]. Use proactively for...
• Use this agent proactively when...
• Must be used when...

2. The WHEN Clause

This tells Claude Code **exactly when** to trigger this agent. Be specific!

**Good WHEN clauses:**

when designing Laravel applications, planning architecture, or discussing system design patterns
when implementing security features, reviewing code for vulnerabilities, or auditing applications
when optimizing database queries, fixing N+1 problems, or improving performance
when writing tests, implementing TDD, or building test suites

**Bad WHEN clauses (too vague):**

when needed
when appropriate
for Laravel development

Real Examples from This Marketplace

Laravel Architect

description: Expert Laravel architect specializing in scalable application design, modular architecture (nwidart/laravel-modules), SOLID principles, and modern PHP patterns. Masters service containers, dependency injection, repository patterns, event-driven architecture, and performance optimization. Use PROACTIVELY when designing Laravel applications, planning architecture, or discussing system design patterns.

**Why this works:**

• ✅ Clearly states expertise
• ✅ Uses "PROACTIVELY" keyword
• ✅ Specifies concrete scenarios: designing, planning, discussing architecture
• ✅ Claude Code knows to delegate when user asks about architecture

Security Engineer

description: Identify security vulnerabilities and ensure compliance with Laravel security standards and best practices. Masters authentication, authorization, CSRF/XSS prevention, SQL injection protection, and rate limiting. Use PROACTIVELY when implementing security features, reviewing code for vulnerabilities, or auditing applications.

**Why this works:**

• ✅ States what it identifies/ensures
• ✅ Lists specific security areas
• ✅ Clear triggers: implementing, reviewing, auditing
• ✅ Claude Code knows to delegate on security-related prompts

Adding Concrete Trigger Phrases

You can also add explicit keyword triggers:

description: Generates completion summaries with text-to-speech output. Use PROACTIVELY when tasks complete. If they say "TTS", "TTS summary", or "text to speech", use this agent.

This helps Claude Code match specific user phrases to your agent.