3.2 Description and triggers

🎯 Description as the sole trigger

The field description in the SKILL.md frontmatter is the only signal the agent uses to decide whether to activate a skill. It’s your "announcement" to the agent—write it as if you had to convince someone in 5 seconds.

What makes a description effective

1 Summary sentence — what the skill does in one line, using concrete action verbs

2 TRIGGER when — list of explicit activation scenarios

3 SKIP — cases where it should NOT trigger, even with thematic overlap

Semantic match

not literal

Only signal

before activating

3 parts

summary+trigger+skip

Lazy loading

body read later

⚡ Writing strong trigger phrases

Trigger phrases are the clauses TRIGGER when in the description. They explicitly list the activation contexts, covering multiple ways the user might express the same request.

Real example: claude-api skill (TRIGGER + SKIP) YAML description

description: |-
  Build, debug, and optimize Claude API / Anthropic SDK apps.
  Apps built with this skill should include prompt caching.
  Also handles migrating existing Claude API code between
  Claude model versions.
  
  TRIGGER when: code imports `anthropic`/`@anthropic-ai/sdk`;
  user asks for the Claude API, Anthropic SDK, or Managed
  Agents; user adds/modifies/tunes a Claude feature (caching,
  thinking, tool use, batch) or model (Opus/Sonnet/Haiku).
  
  SKIP: file imports `openai`/other-provider SDK, filename
  like `*-openai.py`, provider-neutral code, general
  programming/ML.

✓ Strong triggers

✓Explicit "TRIGGER when:" or "Use when:" prefixes
✓Covers multiple phrasings of the same request
✓Includes synonyms and domain variations
✓Mentions concrete artifacts (imports, files)
✓Testable: "if it says X, should it trigger?"

✗ Weak triggers

✗No prefix — there's no clear separation from the summary
✗Covers only 1 phrasing ("create a course")
✗Generic keywords ("code", "web")
✗Too technical for the user (“processes tokens”)
✗Without SKIP — triggers in the wrong contexts

💡 Technique: 5 test questions

Before publishing the skill, test the description with 5 real questions the user might ask. For each one, check:

1. Should the skill trigger? (yes/no)
2. Is it clear from the description alone whether the answer is yes or no?
3. Could another skill compete for this trigger?
4. Does SKIP eliminate false positives?
5. Would someone without context understand the description?

TRIGGER when:

default prefix

Multiple ways

covers variations

Testable

5 questions

Artifacts

imports, files

🚫 SKIP Clauses: Preventing False Triggers

SKIP defines the anti-cases: situations where the skill should NOT trigger, even if there is thematic overlap with the trigger. This is the boundary that separates the skill from its neighbors.

📊 Why SKIP matters

Imagine you have claude-api and a generic "Python code" skill. Without SKIP, any Python script that mentions an API could trigger the wrong skill. SKIP creates clear boundaries:

claude-api → active when:

• import anthropic
• Claude API / SDK
• Opus, Sonnet, Haiku

claude-api → SKIP when:

• import openai
• provider-neutral code
• Generic ML without an SDK

How to refine SKIP in practice

Identify false positives

Use the skill for 1 week. Make a note every time it triggers when it shouldn’t — those are your false positives.

Find the pattern

What do the false positives have in common? Is it a library? A file type? A specific context?

Add to SKIP

Add the pattern to the SKIP clause in the description. Re-test with the original false positives.

✓ Well-written SKIP

✓Explicit uppercase "SKIP:" prefix
✓Lists non-use cases with concrete examples
✓Complements the TRIGGER without contradicting it
✓Refined using real false positives

✗ SKIP pitfalls

✗SKIP so broad that it blocks valid cases
✗Contradicts the TRIGGER ("Use when X... SKIP: X")
✗Missing SKIP in a broad-scope skill
✗SKIP too generic ("SKIP: general code")

SKIP:

required prefix

Anti-cases

skill boundary

Refinement

with real-world use

Complementary

not contradictory

🔤 kebab-case Name

The folder and field name name in the frontmatter follow a single convention: kebab-case.

Examples of valid vs. invalid names

✓ VALID

formato-curso

ads-skill

n8n-code-python

claude-api

deep-research

✗ INVALID

formatoCurso (camelCase)

formato_curso (underscore)

Course Format (spaces)

FORMATO-CURSO (uppercase)

fc (ambiguous abbreviation)

💡 Why kebab-case works

URL-safe
works as a slug without encoding

Terminal-safe
without needing quotes in the shell

Readable
instantly scannable

lowercase

no uppercase letters

hyphen

single separator

2–4 words

descriptive name

folder = name

full consistency

✅ Real examples of effective descriptions

Analysis of descriptions for real skills in production. What makes them effective and why.

Skill: formato-curso — actual description

description: |-
  Template e padrões de design para criar páginas HTML de cursos
  no formato INEMA.CLUB.
  
  Use esta skill SEMPRE que o usuário pedir para criar, editar ou
  revisar páginas HTML de curso — incluindo index de trilhas,
  páginas de módulos, componentes como navegação, cards, tópicos
  expansíveis, modais e slides.
  Acione também quando o usuário mencionar trilhas, módulos,
  tópicos, INEMA.CLUB, ou quando pedir para seguir o
  "formato de curso" ou "template de curso".
  
  Nao deixe de usar esta skill se o usuário mencionar qualquer
  coisa relacionada a páginas HTML de cursos ou ao projeto skillx.

Why this description works

①Clear summary sentence: "Template and design standards for creating HTML course pages in the INEMA.CLUB format" — specific, with output format and context

②Broad TRIGGER: covers creating, editing, and reviewing; lists specific components (modals, slides, cards); mentions domain synonyms (INEMA.CLUB, skillx)

③Imperative tone: "EVERY time the user asks," "Also trigger" — no ambiguity about when to use it

④Negative reinforcement: "Make sure to use" — explicit instruction not to ignore it, anticipating edge cases

Specific

context + format

Comprehensive

multiple formulations

Imperative

unambiguous

Synonyms

domain vocabulary

❌ Description anti-patterns

Poor descriptions are invisible (the skill never triggers), overbroad (it triggers for everything), or confusing (it triggers when it shouldn't). The 4 most common anti-patterns:

✗ Anti-pattern 1: Too vague

description: "Helps with code"

Problem: "code" is everything. Every dev skill will compete. None will win predictably.

✗ Anti-pattern 2: Circular

description: "Use when you need AI"

Problem: all skills "use AI." The description needs to differentiate, not generalize.

✗ Anti-pattern 3: Too technical

description: "Processes tokens via REST API and manages the context window"

Problem: users don’t think in terms of "tokens" and "context window" — they think, "I need an answer."

✗ Anti-pattern 4: No anchors

description: "Skill for working with external APIs"

Problem: which API? REST? GraphQL? Anthropic? OpenAI? Without a specific anchor, the match will be wrong.

💡 The one-sentence test

Show the description to someone who has never seen the skill. Ask: "In what situation would you use this?" If the answer is vague or wrong, the description failed. The test takes 30 seconds and saves hours of debugging.

Vague

doesn’t distinguish

Circular

generalizes

Technical

incorrect vocabulary

No anchor

missing context

🎯 Module Summary

✓

Description = single trigger — the only signal the agent evaluates before activating; lazily loads the body

✓

Ideal structure — summary sentence + TRIGGER when: + SKIP: in 3-6 lines

✓

Strong TRIGGER — explicit prefix, multiple formulations, concrete artifacts (imports, files), testable

✓

SKIP delimiter — defines boundaries, refined by eliminating real false positives, complementary to TRIGGER

✓

Kebab-case — lowercase + hyphens; folder and frontmatter name must match; URL-safe and terminal-safe

✓

Anti-patterns — vague, circular, too technical, without an anchor; use the 1-sentence test to validate

Next Module:

3.3 — Scripts and supporting references: how to structure scripts/, references/, .env.example, and apply progressive disclosure

← Module 3.1 Next: Scripts and references →