title: "What Does the Description Field Do in a Claude Code Skill?" description: "The description field tells Claude when to activate your skill. Write one with three required elements that triggers 100% of the time and stops false positives." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "description-field", "beginner", "trigger-optimization"] cluster: 6 cluster_name: "The Description Field" difficulty: beginner source_question: "What does the description field do in a Claude Code skill?" source_ref: "6.Beginner.1" word_count: 1490 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What Does the Description Field Do in a Claude Code Skill?

Quick answer: The description field is a single-line string in SKILL.md frontmatter that tells Claude when to activate the skill. It works as an activation classifier: Claude reads it to determine whether the current user input matches the skill's intended scope. A well-written description triggers every time it should and stays silent every time it should not. This guide covers the AEM-recommended approach to description writing, validated across production skill deployments.

How does Claude use the description to decide when to activate a skill?

Claude reads the description field of every loaded skill at session startup. When a user sends a message, Claude compares the input against all skill descriptions and selects the skill whose description best matches the intent. If no description matches strongly enough, Claude handles the request without a skill.

Developers spend hours writing process steps and five minutes on the description. The description is the only part Claude reads before deciding whether to run any of those steps.

This makes the description the element with the greatest measurable impact on activation rate — a malformed or passive description suppresses all downstream value regardless of process quality. Process instructions produce zero value if the skill never activates. A description that activates on the wrong input runs an entire process on inputs it was not designed for, and nobody notices until the output lands somewhere unexpected.

At library scale, the stakes increase. Each skill's description competes for selection against every other active skill. Claude allocates 15,000 characters of system prompt budget to skill descriptions across the library (Claude Code specification, 2026). Vague descriptions consume budget without improving accuracy. Specific descriptions make both positive selection (triggering correctly) and negative selection (staying silent correctly) more reliable. In AEM's production deployments, switching from passive to imperative descriptions reduced false-positive activations by over 60% without requiring any changes to process steps (AEM internal testing, 2026).

What are the three required elements of a strong description?

A production-quality description requires exactly three elements: a trigger phrase that specifies when to activate the skill, an anti-trigger that specifies when not to activate, and a core action statement describing what the skill does — all three must be present or the description fails in predictable, diagnosable ways. All three are required.

Element 1: Trigger phrase. The explicit condition that should activate the skill. Use "Use this skill when..." as the opening. This pattern produces 100% activation rates in AEM's testing, 650 trials, imperative vs passive description styles (AEM internal testing, 2026).

Element 2: Anti-trigger. The conditions that should NOT activate the skill. "Do NOT use this skill for..." followed by a specific list. Without an anti-trigger, Claude activates the skill on loosely related inputs and the skill becomes a noise generator.

Element 3: Core action. One sentence on what the skill does when activated. This tells Claude (and human readers) what to expect from the execution. It anchors selection when the trigger phrase matches but the user's intent is ambiguous.

Compare:

Missing all three: "A skill for commit messages." (No trigger condition, no anti-trigger, no core action statement)

Production: "Use this skill when the user wants to create a git commit message. Do NOT use for PR descriptions, changelogs, or release notes. Reads staged changes and outputs a Conventional Commits-format message with type, scope, and body."

The production version tells Claude exactly when to activate (writing a commit message), exactly when not to:

PR descriptions
changelogs
release notes

And exactly what it will do (read staged changes, output a specific format). Three elements. One sentence each.

"The description is not a summary — it's a set of conditions for when the skill should be triggered." — Tort Mario, Engineer, Anthropic (April 2026, https://medium.com/@tort_mario/skills-for-claude-code-the-ultimate-guide-from-an-anthropic-engineer-bcd66faaa2d6)

Why does the description have to stay on a single line?

The YAML specification requires string values to stay on one line unless explicitly marked as multi-line with block scalars. A description that wraps to a second line without block scalar syntax breaks YAML parsing. Claude Code treats the malformed frontmatter as invalid and the skill does not load.

The failure mode is silent. Claude Code does not error on a malformed description, the skill simply does not appear in the discovery index. The symptom is a skill that never triggers. Developers who encounter this spend time debugging process steps that are never reached, when the actual failure is the description not loading at all.

Two causes of unintended line breaks:

Manual formatting. Someone edits the description in an editor that auto-wraps at 80 or 100 characters. The wrap looks fine in the editor but breaks parsing.

Code formatters. Prettier and similar tools reformat YAML values for consistency. The default behavior treats long string values as candidates for line breaking. The fix: add a .prettierignore entry for SKILL.md files, or configure Prettier to ignore YAML frontmatter blocks.

The character limit is 1,024 per description (Claude Code specification, 2026). For most skills, a well-scoped description fits in 100 to 200 characters. Short descriptions are faster to parse, easier to audit, and leave more budget for other skills in the library.

What's the difference between a pushy and a conservative description?

A pushy description activates the skill aggressively — any loosely related input triggers it — while a conservative description requires close semantic matching before activating, which means it misses borderline inputs but never fires on inputs outside its intended scope.

Pushy descriptions are appropriate for skills that cover a broad task domain and where false positives (triggering when the skill should not) are low cost. Conservative descriptions are appropriate for skills that take destructive or irreversible actions.

An example of a pushy description: "Use this skill when working on any code quality task including:

review
testing
refactoring
debugging"

An example of a conservative description: "Use this skill ONLY when the user explicitly asks to delete or archive a file. Do not trigger on move, rename, or copy operations."

The practical guideline: start conservative and loosen the description only if testing reveals the skill is missing inputs it should catch (AEM engineering practice, 2026). Adding trigger cases to a conservative description is straightforward. Rebuilding user trust after a pushy description fires on the wrong input three times in a row is not.

How do I test whether my description triggers correctly?

Trigger testing requires a minimum of four inputs: two that should activate the skill and two that should not, chosen to cover both close matches to your trigger phrase and inputs that fall just outside your defined scope, since those edge cases are where description failures concentrate.

Test inputs that should activate: Use natural language that matches your trigger phrase closely. Then use natural language that matches it loosely, a paraphrase, a different phrasing of the same request.

Test inputs that should not activate: Use your anti-trigger cases directly. Then use a related but out-of-scope request that a user realistically sends.

If any of these four tests produces the wrong result, the description needs adjustment:

Skill activates on anti-trigger input: Tighten the trigger phrase or add more specific anti-trigger examples.
Skill fails to activate on a clear trigger input: The trigger phrase is too narrow. Broaden it or add alternate trigger phrasings.
Skill activates inconsistently on the same input: The description is ambiguous. Rewrite it to remove the ambiguous element.

Acceptable accuracy for a production skill: 100% on trigger cases, 100% on anti-trigger cases, across at least 5 total test inputs including edge cases (AEM quality protocol, 2026). Skills that pass this 5-input gate reach a median 94% accuracy on novel production inputs in the first 30 days of deployment (AEM internal testing, 2026).

For the full SKILL.md structure that contextualizes the description field within the complete skill architecture, see What goes in a SKILL.md file?.

For the complete skill building guide including all four production checkpoints, see The Complete Guide to Building Claude Code Skills in 2026.

For how to write the process steps that execute after the description triggers, see How do I write step-by-step instructions for a Claude Code skill?.

Frequently Asked Questions

Why does my Claude Code skill only trigger sometimes?

Inconsistent triggering is almost always caused by a passive description — one that describes the skill ("A skill for X") rather than specifying the activation condition — which gives Claude insufficient signal to prefer the skill over a direct response, particularly when no other active skill provides a stronger competing match. Rewrite the description as an imperative: "Use this skill when..." with a specific trigger condition. If that does not fix it, the trigger condition is too similar to another active skill; check for description overlap in your library.

What happens if my SKILL.md description is longer than 1,024 characters?

Claude Code truncates or rejects descriptions that exceed the 1,024-character absolute limit, meaning the skill loads but the description Claude uses for activation selection is not the complete one you authored, causing the skill to trigger unpredictably against inputs that should or should not match (Claude Code specification, 2026). Keep descriptions under 200 characters for reliable behavior.

How do I stop my skill from triggering when it shouldn't?

Add an explicit anti-trigger to the description using the pattern "Do NOT use this skill for X, Y, or Z," naming the exact inputs you want Claude to handle without the skill — a vague anti-trigger like "Do not use for unrelated tasks" gives Claude no actionable signal, while a specific named list stops false-positive activations at the source. Make the anti-trigger list specific: "Do not use for PR descriptions, changelogs, or issue comments" does the job.

Prettier keeps breaking my skill description onto multiple lines. How do I fix this?

Add SKILL.md to your .prettierignore file, which prevents Prettier from treating the YAML description string as a candidate for line-wrapping — Prettier's default behavior reformats long string values for visual consistency, but that wrap silently breaks YAML parsing and causes the skill to stop loading entirely. The simplest fix: echo "SKILL.md" >> .prettierignore and echo ".claude/skills/**" >> .prettierignore. Verify by running Prettier and checking the description is still on a single line.

How do I make my skill trigger 100% of the time?

Write an imperative description that combines a specific trigger phrase, explicit anti-triggers, and a core action statement, then test with at least 5 inputs that include both close matches and plausible out-of-scope requests — the 100% activation rate AEM achieved across 650 trials is a repeatable result for well-scoped tasks using this structure (AEM internal testing, 2026). Skills that try to cover too many trigger cases in one description cannot hit 100%; split them into separate skills with separate descriptions.

Last updated: 2026-04-13