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