Claude Code Skill Description Engineering

The description field in a skill’s YAML frontmatter is the only input Claude uses to decide whether to activate the skill for a given request. A vague description means unpredictable activation. A precise description — with specific keywords, clear boundaries, and explicit exclusions — improves activation reliability. This is a form of context engineering: structuring what the AI knows so it can make better decisions.

Why the Description Matters

Claude Code’s skill activation works through keyword matching against the YAML frontmatter. At startup, Claude loads every skill’s name and description. When you make a request, it checks for overlaps between your words and those loaded descriptions.

This means the description isn’t documentation for humans. It’s a machine-readable activation trigger. Writing it like a README — “This skill contains utilities for working with dbt documentation” — optimizes for the wrong audience. Writing it like a search index — with specific terms a user might actually say — optimizes for actual activation.

The Specificity Principle

Generic descriptions produce generic (or zero) activation. Specific descriptions produce targeted activation.

Generic (low activation):

description: Documentation utilities for dbt projects

This description contains three useful keywords: “documentation,” “dbt,” and “projects.” But “documentation” is broad enough to match almost anything, “dbt” matches everything in a dbt project, and “projects” is noise. Claude has no reliable signal about when this skill is relevant versus irrelevant.

Specific (higher activation):

description: Generate data lineage documentation and Mermaid diagrams.
  Use when user asks about lineage, dependencies, upstream models,
  or documentation for model relationships. Do NOT use for general
  dbt questions unrelated to lineage.

This description does three things the generic one doesn’t:

1. Names the outputs. “Lineage documentation” and “Mermaid diagrams” are concrete artifacts. When you ask Claude to “create a lineage diagram,” the word “diagram” matches directly.

2. Lists trigger phrases. “Lineage,” “dependencies,” “upstream models,” “model relationships” — these are the actual words users type when they want this skill’s content. Each phrase is a potential activation path.

3. Draws a negative boundary. “Do NOT use for general dbt questions unrelated to lineage” tells Claude when not to activate. Without this, any dbt-related question might weakly match, leading to false activations that dilute the skill’s usefulness.

Anatomy of a Good Description

A well-engineered skill description has four components:

1. Primary Action Statement

Start with what the skill does, using the most specific terms possible.

description: Audit dbt models for documentation coverage, test presence,
  and naming convention compliance.

“Audit,” “documentation coverage,” “test presence,” “naming convention compliance” — each phrase maps to a concrete request a user might make.

2. Trigger Phrase List

Enumerate the ways someone might ask for this skill’s functionality. Think of it like SEO keywords for an internal search engine.

  Use when user asks to audit a model, check documentation,
  verify test coverage, review naming conventions, or validate
  a model against project standards.

The more synonyms and phrasings you include, the more activation paths exist. “Audit” and “check” and “verify” and “review” and “validate” all mean roughly the same thing — but a user might use any of them.

3. Negative Boundaries

Explicitly state when the skill should not activate. This prevents false positives that erode trust in the skill system.

  Do NOT use for writing new models, generating tests, or creating
  documentation from scratch. This skill evaluates existing models only.

Without negative boundaries, a request like “create documentation for this model” might activate an audit skill — because “documentation” appears in both the request and the description. The negative boundary prevents this by explicitly excluding creation tasks.

4. Context Hints

If the skill depends on specific project structure or file locations, include those as context hints so Claude knows where to look when the skill activates.

  Expects models in models/{base,intermediate,marts}/ with
  corresponding schema.yml files. Naming convention: base__, int__, mrt__ prefixes.

These hints serve double duty: they improve activation (matching against project-specific terms like “base__” or “mrt__”) and they give Claude operational context when the skill fires.

A Complete Example

Putting all four components together:

---
name: dbt-model-audit
description: >
  Audit dbt models for documentation coverage, test presence, and naming
  convention compliance. Use when user asks to audit a model, check
  documentation completeness, verify test coverage, review naming
  conventions, or validate a model against project standards. Do NOT use
  for writing new models, generating tests, or creating documentation
  from scratch — this skill evaluates existing models only. Expects models
  in models/{base,intermediate,marts}/ with corresponding schema.yml files.
  Naming convention: base__, int__, mrt__ prefixes.
---

Notice the description is longer than what most people write. That’s intentional. Each additional phrase is another keyword that might match a user’s request. The cost of a longer description (slightly more context consumed at startup) is far outweighed by the benefit of more reliable activation.

Common Description Anti-Patterns

The one-liner. description: dbt audit skill gives Claude almost nothing to match against. Three words, one of which (“skill”) is meta-language that no user will include in a prompt.

The implementation description. description: Reads schema.yml and checks for missing descriptions describes how the skill works, not when it should activate. Users don’t ask Claude to “read schema.yml.” They ask it to “check if this model is documented.”

The everything skill. description: Use for all dbt-related tasks including modeling, testing, documentation, and deployment matches everything, which means it competes with every other skill and with Claude’s default behavior. A skill that activates for everything is as useless as one that activates for nothing.

Missing negative boundaries. Without explicit exclusions, skills with overlapping vocabulary interfere with each other. If you have both a “documentation generation” skill and a “documentation audit” skill, both have “documentation” in their descriptions. Negative boundaries (“Do NOT use for auditing existing docs” / “Do NOT use for generating new docs”) disambiguate them.

The Honest Assessment

Even with perfectly engineered descriptions, skills won’t activate 100% of the time. The keyword matching mechanism has inherent limitations — you can’t anticipate every phrasing a user (including yourself) might use.

Description engineering improves the activation rate from roughly 20% to something meaningfully higher — maybe 40-60% for well-described skills in focused domains. That’s a real improvement, but it’s still not reliable enough for critical workflows. For anything where consistency matters, a command remains the right choice.

Where description engineering pays off most is for the skills you keep as background knowledge — warehouse quirks, conventions, reference material. These skills don’t need to activate every time. They need to activate often enough that Claude’s output is generally informed by your project context. Moving from 20% to 50% activation on a background knowledge skill makes a noticeable difference in output quality without requiring you to explicitly invoke anything.

Relationship to CLAUDE.md

CLAUDE.md doesn’t have an activation problem — it loads unconditionally, every time. If a piece of context is important enough that it should always influence Claude’s behavior, it belongs in CLAUDE.md, not in a skill with a description you hope triggers correctly.

Skills are for context that’s relevant sometimes. CLAUDE.md is for context that’s relevant always. Description engineering helps skills activate more reliably in the “sometimes” cases, but it can’t turn a sometimes-mechanism into an always-mechanism. Know which one you need before deciding where to put your context.