writing-descriptions

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

Good vs Bad

Skill Description Examples

By Category

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:

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