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