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."