Writing Effective Descriptions
The description field is THE routing key. Claude reads descriptions to decide whether to invoke an agent or skill. Poor descriptions = artifacts that never trigger.
The Formula
{Role/expertise}. Use [PROACTIVELY] when {specific trigger conditions}.
- Role/expertise: What the agent/skill does (third person for skills)
- PROACTIVELY: Include if Claude should invoke without being asked
- Trigger conditions: Specific situations that warrant invocation
Agent Description Examples
By Category
| Category |
Description |
| Debugging |
"Docker troubleshooter. Use PROACTIVELY when containers fail to start, crash, or behave unexpectedly." |
| Code Review |
"Security-focused code reviewer. Use PROACTIVELY when reviewing authentication, authorization, or data handling code." |
| Testing |
"Test generation specialist. Use when asked to add tests or improve test coverage for existing code." |
| Infrastructure |
"Kubernetes deployment expert. Use PROACTIVELY when working with k8s manifests, helm charts, or cluster issues." |
| API Design |
"REST API designer. Use when creating new endpoints, designing request/response schemas, or documenting APIs." |
| Performance |
"Performance optimization specialist. Use when profiling, optimizing queries, or reducing latency." |
| Database |
"PostgreSQL query optimizer. Use PROACTIVELY when queries are slow or EXPLAIN shows sequential scans." |
| Frontend |
"React component architect. Use when building complex UI components or refactoring component hierarchies." |
Good vs Bad
| Bad |
Why It Fails |
Better |
| "Helps with Docker" |
Too vague, no triggers |
"Docker troubleshooter for container failures" |
| "General coding assistant" |
No specificity |
"Python async specialist for concurrent code" |
| "Does database stuff" |
Unclear scope |
"PostgreSQL query optimizer for slow queries" |
| "Useful for many things" |
No routing signal |
"Git workflow automator for branching and merging" |
| "I help you with tests" |
Wrong person (first) |
"Test generator for untested functions" |
Skill Description Examples
By Category
| Category |
Example Description |
| Document Processing |
"Comprehensive document creation, editing, and analysis with tracked changes support. Use when working with .docx files for creating, modifying, or extracting content." |
| Data Analysis |
"Analyzes Excel spreadsheets, creates pivot tables, generates charts. Use when analyzing .xlsx files, spreadsheets, or tabular data." |
| API Integration |
"Creates MCP servers for external API integration using TypeScript or Python. Use when building Model Context Protocol servers or LLM tool integrations." |
| Creative/Design |
"Creates distinctive production-grade frontend interfaces. Use when building web components, landing pages, dashboards, or styling any web UI." |
| Workflow Automation |
"Guides users through structured document co-authoring. Use when writing documentation, proposals, technical specs, or decision docs." |
| Testing |
"Tests local web applications using Playwright. Use when verifying frontend functionality, debugging UI, or capturing browser screenshots." |
| PDF Processing |
"Extracts text and tables from PDFs, fills forms, merges documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction." |
| Presentations |
"Creates and modifies PowerPoint presentations with consistent styling. Use when building slide decks, adding charts, or formatting presentations." |
Skills: Third Person Requirement
Skills must use third person voice:
# Good (third person)
description: Extracts text from PDFs and fills form fields.
# Bad (first person)
description: I help you process PDFs.
# Bad (second person)
description: Helps you extract PDF text.
Proactive vs On-Demand
Use PROACTIVELY when:
- The situation is detectable from context (error messages, file types)
- Waiting for explicit request would delay the user
- The agent/skill is highly specialized
# Proactive - Claude should invoke without being asked
"Docker troubleshooter. Use PROACTIVELY when containers fail to start..."
"Security reviewer. Use PROACTIVELY when reviewing auth code..."
On-demand (no PROACTIVELY) when:
- User should explicitly request the capability
- Multiple valid approaches exist
- The action has significant side effects
# On-demand - wait for user request
"Test generator. Use when asked to add tests..."
"Database migrator. Use when user requests schema changes..."
Trigger Specificity
More specific triggers = more reliable invocation:
| Vague Trigger |
Specific Trigger |
| "when needed" |
"when containers fail to start or exit unexpectedly" |
| "for code review" |
"when reviewing authentication, authorization, or session code" |
| "for testing" |
"when test coverage is below 80% or user asks for tests" |
| "for performance" |
"when queries exceed 100ms or EXPLAIN shows sequential scans" |
Combining Multiple Triggers
Use "or" to list multiple valid triggers:
"PDF processor. Use when working with PDF files, filling forms,
extracting tables, or merging documents."
Use commas for related triggers:
"Kubernetes expert. Use PROACTIVELY when working with pods,
deployments, services, or ingress configurations."
1---2name: writing-descriptions3description: Examples and patterns for writing effective agent and skill descriptions. Use when crafting descriptions that serve as routing keys for Claude's invocation decisions.4---5
6# Writing Effective Descriptions
7
8The `description` field is THE routing key. Claude reads descriptions to decide whether to invoke an agent or skill. Poor descriptions = artifacts that never trigger.
9
10## The Formula
11
12```
13{Role/expertise}. Use [PROACTIVELY] when {specific trigger conditions}.
14```
15
16- **Role/expertise**: What the agent/skill does (third person for skills)
17- **PROACTIVELY**: Include if Claude should invoke without being asked
18- **Trigger conditions**: Specific situations that warrant invocation
19
20## Agent Description Examples
21
22### By Category
23
24| Category | Description |
25|----------|-------------|
26| **Debugging** | "Docker troubleshooter. Use PROACTIVELY when containers fail to start, crash, or behave unexpectedly." |
27| **Code Review** | "Security-focused code reviewer. Use PROACTIVELY when reviewing authentication, authorization, or data handling code." |
28| **Testing** | "Test generation specialist. Use when asked to add tests or improve test coverage for existing code." |
29| **Infrastructure** | "Kubernetes deployment expert. Use PROACTIVELY when working with k8s manifests, helm charts, or cluster issues." |
30| **API Design** | "REST API designer. Use when creating new endpoints, designing request/response schemas, or documenting APIs." |
31| **Performance** | "Performance optimization specialist. Use when profiling, optimizing queries, or reducing latency." |
32| **Database** | "PostgreSQL query optimizer. Use PROACTIVELY when queries are slow or EXPLAIN shows sequential scans." |
33| **Frontend** | "React component architect. Use when building complex UI components or refactoring component hierarchies." |
34
35### Good vs Bad
36
37| Bad | Why It Fails | Better |
38|-----|--------------|--------|
39| "Helps with Docker" | Too vague, no triggers | "Docker troubleshooter for container failures" |
40| "General coding assistant" | No specificity | "Python async specialist for concurrent code" |
41| "Does database stuff" | Unclear scope | "PostgreSQL query optimizer for slow queries" |
42| "Useful for many things" | No routing signal | "Git workflow automator for branching and merging" |
43| "I help you with tests" | Wrong person (first) | "Test generator for untested functions" |
44
45## Skill Description Examples
46
47### By Category
48
49| Category | Example Description |
50|----------|---------------------|
51| **Document Processing** | "Comprehensive document creation, editing, and analysis with tracked changes support. Use when working with .docx files for creating, modifying, or extracting content." |
52| **Data Analysis** | "Analyzes Excel spreadsheets, creates pivot tables, generates charts. Use when analyzing .xlsx files, spreadsheets, or tabular data." |
53| **API Integration** | "Creates MCP servers for external API integration using TypeScript or Python. Use when building Model Context Protocol servers or LLM tool integrations." |
54| **Creative/Design** | "Creates distinctive production-grade frontend interfaces. Use when building web components, landing pages, dashboards, or styling any web UI." |
55| **Workflow Automation** | "Guides users through structured document co-authoring. Use when writing documentation, proposals, technical specs, or decision docs." |
56| **Testing** | "Tests local web applications using Playwright. Use when verifying frontend functionality, debugging UI, or capturing browser screenshots." |
57| **PDF Processing** | "Extracts text and tables from PDFs, fills forms, merges documents. Use when working with PDF files or when user mentions PDFs, forms, or document extraction." |
58| **Presentations** | "Creates and modifies PowerPoint presentations with consistent styling. Use when building slide decks, adding charts, or formatting presentations." |
59
60### Skills: Third Person Requirement
61
62Skills must use third person voice:
63
64```yaml
65# Good (third person)
66description: Extracts text from PDFs and fills form fields.
67
68# Bad (first person)
69description: I help you process PDFs.
70
71# Bad (second person)
72description: Helps you extract PDF text.
73```
74
75## Proactive vs On-Demand
76
77### Use PROACTIVELY when:
78- The situation is detectable from context (error messages, file types)
79- Waiting for explicit request would delay the user
80- The agent/skill is highly specialized
81
82```
83# Proactive - Claude should invoke without being asked
84"Docker troubleshooter. Use PROACTIVELY when containers fail to start..."
85"Security reviewer. Use PROACTIVELY when reviewing auth code..."
86```
87
88### On-demand (no PROACTIVELY) when:
89- User should explicitly request the capability
90- Multiple valid approaches exist
91- The action has significant side effects
92
93```
94# On-demand - wait for user request
95"Test generator. Use when asked to add tests..."
96"Database migrator. Use when user requests schema changes..."
97```
98
99## Trigger Specificity
100
101More specific triggers = more reliable invocation:
102
103| Vague Trigger | Specific Trigger |
104|---------------|------------------|
105| "when needed" | "when containers fail to start or exit unexpectedly" |
106| "for code review" | "when reviewing authentication, authorization, or session code" |
107| "for testing" | "when test coverage is below 80% or user asks for tests" |
108| "for performance" | "when queries exceed 100ms or EXPLAIN shows sequential scans" |
109
110## Combining Multiple Triggers
111
112Use "or" to list multiple valid triggers:
113
114```
115"PDF processor. Use when working with PDF files, filling forms,
116extracting tables, or merging documents."
117```
118
119Use commas for related triggers:
120
121```
122"Kubernetes expert. Use PROACTIVELY when working with pods,
123deployments, services, or ingress configurations."
124```
majiayu000