Claude Agent Skills Not Triggering? The Problem is in Your Description: Complete Design Pattern Guide¶

Target Audience

Developers who have placed Skills in .claude/skills or within projects but aren't seeing expected triggers

Key Points¶

The role of description (what+when / third-person perspective) Design patterns and templates to improve trigger rates Troubleshooting for Japanese input and voice dictation

Introduction: Scope of This Guide¶

This article is a complete guide to designing descriptions for Anthropic Platform's Agent Skills (SKILL.md).

In Agent Skills, each Skill is managed as a directory with SKILL.md as the entry point. The YAML frontmatter requires name and description, with description having constraints like non-empty / max 1024 characters / no XML tags.

This description is not just explanatory text. As the official best practices emphasize, it serves as discovery metadata for Claude to determine "when to use this Skill", requiring what (capabilities) + when (trigger conditions) + specific trigger terms.

Note

Claude app's Custom Skills UI has different constraints (200 character limit for description). This article focuses on Platform Agent Skills (1024 character limit), with differences covered in the appendix.

The Role of Description: what + when + Third-Person¶

Three Elements Required by Official Documentation¶

Description is not explanatory text—it's an index. Official documentation requires these elements:

What (capability) - Artifacts and formats the Skill produces
When (trigger conditions) - Situations and trigger terms for activation
Third-person perspective - Avoids viewpoint conflicts when injected into system prompts

✅ Good: "Processes Excel files and generates reports"
❌ Avoid: "I can help you process Excel files"
❌ Avoid: "You can use this to process Excel files"

Why Third-Person?

Descriptions are injected into system prompts. When "I/you" are mixed in, viewpoint conflicts occur in Claude's discovery process, degrading search quality—as officially stated.

Gateway to Progressive Disclosure¶

Skills are designed with progressive disclosure. At startup, only metadata (name/description) is loaded, with body content and additional resources accessed only when needed.

The practical principle derived from this design is simple:

description = trigger conditions (when) + capability declaration (what) + search vocabulary (keywords)body (SKILL.md body) = implementation, procedures, examples, dictionaries (synonyms, typos)

Clarify "when and what" in description, leave details to body. Without this separation, Skills either don't trigger or mis-trigger.

Specification: Description Constraints¶

Validation Rules (Violations Cause Errors)¶

Item	Constraint
Empty	Not allowed (must be non-empty)
Length	Max 1024 characters
XML tags	Prohibited
name	Max 64 characters, lowercase/digits/hyphens only

Best Practices (Violations Don't Break but Degrade Quality)¶

Include what + when - State what it does and when to use it
Write in third person - Avoid I/you
Include specific trigger terms - Words users naturally use

Design Patterns to Improve Trigger Rates¶

The Golden Pattern: "what → when → do-not"¶

Effective descriptions need three elements:

What: What the Skill does (including output format)
When: When to use it (trigger terms + situations)
Do-not: What it doesn't do (prevents mis-triggering)

Template: Specification Documents¶

description: Produces software specification documents in Markdown: purpose, scope,
  assumptions, functional/non-functional requirements, interfaces, constraints,
  and acceptance criteria. Use when user requests "仕様書", "要件定義", "スペック",
  "requirements", "spec", provides business goal, user stories, constraints,
  or asks to formalize ambiguous ideas. Do NOT use for casual explanations
  or long-form essays; prefer this only when a structured spec artifact is needed.

Breakdown

What: Produces software specification documents in Markdown: purpose, scope, assumptions, functional/non-functional requirements, interfaces, constraints, and acceptance criteria
When: "仕様書", "要件定義", "スペック", "requirements", "spec", business goal, user stories
Do-not: Do NOT use for casual explanations or long-form essays

Template: Meeting Minutes¶

description: Produces meeting minutes in Markdown with attendees, decisions,
  and action items including owner and due date. Use when user requests "議事録",
  "minutes", "meeting summary", or uploads a meeting transcript.
  Do NOT use for long-form reports or general document creation.

Template: Data Analysis¶

description: Analyzes CSV/Excel files to produce summary statistics, trends,
  outliers, and charts. Use when user requests "分析", "sales report",
  mentions CSV/Excel, "前月比", "推移グラフ", or uploads tabular data files.
  Do NOT use for document writing or general explanations.

Japanese Input and English Description Matching¶

What Official Documentation Guarantees¶

Include what + when + key terms in description so Claude knows when to use it
Claude has strong multilingual support

What Official Documentation Doesn't Specify¶

The matching algorithm (e.g., cross-language search via embeddings) for "Japanese input matching English description semantically" is not documented.

Practical Conclusion¶

If users input in Japanese, including Japanese trigger terms in description is the robust approach. This simply applies the official guidance of "include keywords users naturally use" to Japanese operations—no contradiction.

Recommended Practice

Include top 5 terms in both JP/EN in description
Put synonyms, spelling variations, and typos in body (SKILL.md) or reference files

Speech Input (STT) Converting "仕様書" to "使用書"¶

Dictation vs Voice Mode¶

Claude mobile app has two voice features:

Feature	Japanese Support	Description
Dictation	Supported	Voice is converted to text and sent
Voice Mode	English only	Real-time voice conversation

Dictation supports 12 languages including Japanese. Since triggering is evaluated on the final generated text, testing can validate it.

STT Misconversion Countermeasures¶

For misconversions (e.g., 仕様書→使用書), design becomes more robust in this order:

Include 1-2 representative misconversions in description
Put normalization rules in body (SKILL.md) (comprehensive coverage goes to body)

# Example in description
description: Draft specs in Markdown. Use for 仕様書/使用書/要件/spec.
  Not for general Q&A.

"使用書" is included as a representative misconversion. Comprehensive dictionaries go in the body.

Testing Methodology: should trigger / should not trigger¶

Official documentation explicitly states to iterate and test descriptions. Fixing test inputs as text makes regression testing after changes easier.

Minimal Test Set Example (Spec Skill)¶

should triggershould NOT trigger

「仕様書を作成して」
"Create a spec for X"
「要件定義をお願い」
(STT expected) 「使用書を作成して」

「仕様書って何？」(definition question)
「文章をいい感じに直して」(general proofreading)
「このコードを説明して」(code explanation)

Testing Observation Points¶

Official best practices recommend observing how Skills are used and improving them. Points to observe:

Unexpected trigger paths - Unintended inputs causing triggers
Misses - Cases where expected triggers didn't fire
Over-reliance - Specific sections being read disproportionately

Anti-Patterns: Characteristics of Non-Triggering Descriptions¶

Vague Verbs and Nouns¶

# ❌ Bad Example
description: Helps with documents

# ✅ Good Example
description: Creates software specification documents in Markdown with scope,
  requirements, and acceptance criteria

Vague verbs like "Helps with," "Processes," "Handles" don't tell Claude when to use the Skill.

Missing Trigger Terms¶

# ❌ Bad Example
description: Generates meeting notes

# ✅ Good Example
description: Produces meeting minutes in Markdown. Use when user requests
  "議事録", "minutes", "meeting summary", or uploads a transcript

Without including words users actually use (including Japanese), triggers won't fire.

Missing do-not¶

# ❌ Bad Example
description: Analyzes data and creates reports

# ✅ Good Example
description: Analyzes CSV/Excel files for statistics and trends.
  Do NOT use for document writing or general explanations

Without specifying "what not to do," mis-triggering becomes likely.

Common Troubles and Solutions¶

Symptom	Cause	Solution
Not triggering	what+when is vague	Specify concrete outputs and trigger terms
Mis-triggering	No do-not clause	Add "Do NOT use for..." to clarify boundaries
Not triggering on Japanese	No Japanese trigger terms	Include keywords in both JP/EN
Multiple Skills conflicting	Unclear boundaries	Use do-not in each Skill to clarify scope

Summary¶

Description is an index. Optimally distribute what + when + trigger + do-not within 1024 characters
Write in third person. Avoid I/you to prevent viewpoint conflicts with system prompts
For Japanese operations, include Japanese triggers. Since matching algorithms are undocumented, validate through testing
Test with should trigger / should not trigger. Practice the iterative refinement recommended by official docs

Reference Links (Official Primary Sources)¶

Appendix: UI (Custom Skills) and Claude Code Differences¶

Claude App UI (Custom Skills)¶

Custom Skills uploaded via Claude app UI have a 200 character description limit.

# 200-character version (for Custom Skills UI)
description: Draft specs in Markdown (scope, requirements, acceptance).
  Use for 仕様書/要件/spec. Not for Q&A.

With 200 characters, you can't include details, so minimize trigger terms and put details in the body.

Claude Code Character Budget¶

In Claude Code, skill descriptions are loaded into context, but content exceeding the character budget (default 15,000 characters) gets excluded.

Diagnostic Steps:

Run /context to check for exclusion warnings
If too many, adjust SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable
If still failing, shorten descriptions or split Skills

Number of Skills	Recommended Description Length
60+	130 characters or less
40-60	150 characters or less
Under 40	200 characters is fine