Your AI Coding Assistant Skills Never Trigger? Debug the Description Field

When you extend the capabilities of your AI coding assistant (your AI coding assistant, code agent), almost every developer hits the same wall. You spend an hour carefully polishing the instructions in the skill file, and you’re sure everything is ready. Then you send a prompt that should clearly trigger the skill, and the assistant ignores it completely. It just runs its default logic, as if the skill didn’t exist. In the end, you can only force it on by typing /skill-name every time.

This isn’t an occasional fluke. It’s a systemic design bottleneck.

Here’s a typical example. A developer writes a “product review” skill for the assistant and agonizes over the wording in the description field. Then the developer runs 20 different prompts that should all trigger the skill: “Help me do a product review,” “Give me a go/no-go recommendation,” “Find the flaws in this product strategy.” How often does the skill trigger? Zero times. Twenty queries, and the skill is never activated once.

If you’ve run into something similar, you can almost certainly trace the cause to one place. It isn’t the instructions in the skill body. It’s the description field. This article takes a deep look at that field: how it works under the hood, why most descriptions are ineffective, and how to fix them.

1. The Real Role of the Description Field

To write a good description, you first need to understand exactly what job it does in the system. Most misunderstandings come from having a fuzzy view of that job.

1.1 Where the Description Lives

In mainstream “progressive disclosure” architectures, the skill tool embeds a list of available skills in its definition. This list is assembled from the metadata (frontmatter) of all registered skills. It is then injected into the model’s system prompt.

Here’s a key fact: when the model runs, it does not read the full body of each skill file. It only sees each skill’s name and description. Together, these usually amount to only about 100 tokens of information. The model relies entirely on this compact metadata to decide which skill to call, even when there could be a hundred or more to choose from.

In short, the information flow works like this:

• Full skill text: stored in the file system or other storage. It does not take up space in the context window.
• name + description: injected into the system prompt. They are always available for the model to see.
• The body of the selected skill: loaded into the context only when needed.

1.2 Why This Design Is Both Elegant and a Bottleneck

The design is elegant. Whether you have 5 skills or 100, the constant context overhead scales only with the metadata. The size of the skill bodies is kept completely out of the context window, which makes it possible to add capabilities on a large scale.

The same design also creates a bottleneck. The information the model uses to make its decision is compressed to the extreme. The model has to make a yes-or-no choice among up to a hundred candidates while reading only about 100 tokens. Every clever instruction you put in the skill body plays no part in this decision at all.

If the description is well written, the skill comes to life. If it’s poorly written, the skill is dead code that never runs.

2. Why Most Descriptions Are Ineffective

Once you realize that the description is the only thing the model uses to decide, the reasons for failure become clear. Here are the most common and most damaging anti-patterns.

2.1 The Description Says What the Skill Is, Not When to Use It

This is the number-one mistake. Many people write descriptions like this:

description: A skill for product review that outputs a structured review report.

This accurately states what the skill is and what it does. But it never answers the question the model cares about most: when should I be chosen? When the model receives user input, it looks for a match. It doesn’t read an intent specification. Without trigger conditions, the model has no way to judge whether the skill is relevant, so naturally it doesn’t pick it.

2.2 The Description Uses the Skill’s Perspective Instead of the User’s

Effective matching happens between the words users use and the keywords in the description. If a user says “find the flaws in the strategy” but your description only contains abstract terms like “completeness review” and “compliance assessment,” there is no overlap in vocabulary. The chance of the skill triggering drops sharply. Your description needs to cover the many different ways users might actually phrase their requests. That includes casual language, abbreviations, and near-synonyms.

2.3 The Trigger Surface Is Too Narrow or Too Wide

• Too narrow: the description maps to one exact phrasing, and anything even slightly different doesn’t match.
• Too wide: a description like “handles all kinds of programming tasks” competes with every general-purpose skill. As a result, it gets watered down, or it triggers when it shouldn’t.

Either way, the skill’s triggering behavior becomes unpredictable.

2.4 No Clear Boundaries from Neighboring Skills

When several skill descriptions overlap heavily, the model struggles to choose between them. It often picks neither, or picks the wrong one. The description should make clear what the skill is for and how it differs in responsibility from similar capabilities.

3. How to Write Descriptions That Trigger Precisely

3.1 Use a “When + What” Structure

A description with a high hit rate usually has two parts:

---
name: product-review
description: >-
  Use when the user asks to review a product strategy, evaluate a
  product plan, make a go/no-go decision, or find gaps and risks in
  a product direction. Produces a structured review report covering
  goals, assumptions, risks, and recommendations.
---

• First part (trigger conditions): clearly state when to use the skill. List as many of the ways users might phrase their requests as you can.
• Second part (capability): briefly describe what the skill does and produces. This helps the model choose between candidates.

3.2 Write Your Trigger Words Thickly

Actively list the ways users are likely to phrase their requests, instead of relying on the model to make connections for you. For the product review skill above, the trigger words should include:

• “review a product strategy”
• “go/no-go decision”
• “find gaps in the plan”
• “评估产品方向的风险”

It’s better to include several synonymous phrasings than to assume the model can infer what you have in mind but haven’t said.

3.3 Add Negative Boundaries as Fences

State in the description which scenarios don’t belong to this skill, so it triggers incorrectly less often:

description: >-
  Use for reviewing product strategy and go/no-go decisions.
  Do NOT use for code review, UI design critique, or market pricing analysis.

This “do not use” statement matters most when multiple skills coexist. It can significantly improve the model’s accuracy in choosing a skill.

3.4 Keep the Metadata Token Budget in Check

Because the metadata is always in the context, keep the name and description concise. The goal isn’t to write a lot. It’s to pack as much useful information as possible into a small number of tokens. Put the entire budget into trigger conditions and discriminating keywords, not filler adjectives.

4. Testing and Iterating: Rely on Data, Not Gut Feel

You can’t tell whether a description works just by thinking “this looks good to me.” You need a repeatable testing process:

1. Build a test set: list 15 to 20 realistic prompts written the way actual users would phrase them. Include typical phrasings, edge cases, and counter-examples (scenarios that should not trigger the skill).
2. Measure the hit rate: run every prompt and record two kinds of errors: cases that should have triggered the skill but didn’t, and cases that shouldn’t have triggered it but did.
3. Trace problems back to the description: if the hit rate is low, look at the description first. Are trigger words missing? Are the boundaries unclear? Does the skill overlap with a neighboring one?
4. Iterate one change at a time: change only one piece of wording per round, rerun the full test set, and see how the hit rate changes. If you change several things at once, you won’t know which change made the difference.
5. Run regression checks: after adding new trigger words, test again to make sure they don’t cause the skill to trigger incorrectly.

Conclusion

In most cases, when a skill doesn’t trigger, the model isn’t “disobeying” you. The description field simply doesn’t give the model enough accurate information to decide. Remember the core principle: the model reads only the metadata to choose a skill, so a skill comes to life only when its description is well written.

Rewrite your descriptions from “introducing myself” to “telling the model when to choose me.” Fill those roughly 100 tokens with a “when + what” structure, rich trigger words, and clear negative boundaries. Then keep iterating with a quantifiable test set. Your skill will go from dead code that never runs to a reliable capability that is loaded into the context at exactly the right moment.