How Skill Description Routing Affects AI Coding Assistants—and How to Fix It

Many teams encounter a similar problem: a skill contains detailed procedures, constraints, and examples, but an AI coding assistant almost never loads it during real conversations. Users must manually invoke the skill before they can use it.

The usual response is to keep expanding the skill body with more explanations, validation checks, and longer workflows. Yet the trigger rate remains close to zero.

In many cases, the problem is not in the skill body. It is decided earlier, before the skill is discovered. Whether a model loads a skill depends primarily on the metadata injected into the system prompt, especially the skill name and description.

In one extreme case, a product review skill had a zero first-turn hit rate across 20 prompts that clearly should have triggered it. This behavior is not mysterious. Skill discovery is essentially a routing decision between answering directly and loading a specific skill. The description acts as the routing protocol. If it does not provide enough trigger signals, even an excellent skill body will never enter the model’s candidate path.

1. Why the Description Is Critical to Skill Discovery

Skills commonly use progressive disclosure. The system prompt contains only a list of available skills. This list is generated from metadata such as each skill’s name, description, and source. The full skill body is added to the context only after the model decides to load that skill.

This design saves context budget, but it also concentrates the decision about whether to use a skill into a small amount of metadata.

The information flow can be represented as follows:

User request
  ↓
Available skill list injected into the system prompt
  ├─ Skill A: name + description + source
  ├─ Skill B: name + description + source
  └─ Skill C: name + description + source
  ↓
Model decides: answer directly or load a skill?
  ↓
If loaded, read the full skill body

Within this flow, the description has three responsibilities:

1. Explain what problem the skill can solve.
2. Indicate which requests should trigger it.
3. Clarify which requests should not trigger it, preventing conflicts with general capabilities or other skills.

Most ineffective descriptions satisfy only the first responsibility. Some merely say, “This skill is used for product reviews,” without explaining what users might say or what task signals should cause the skill to load.

The model sees a functional summary rather than an executable routing condition.

When dozens or hundreds of skills are available, candidates compete with one another. A description that is abstract, generic, or missing task-oriented verbs can easily be ignored. Models do not naturally prefer loading a skill. Directly answering is usually the more conservative and lower-cost choice.

The description must therefore reduce the model’s decision cost.

2. Seven Common Reasons a Skill Does Not Trigger

1. The Description Is a Feature Summary Instead of a Trigger Condition

Descriptions such as “used for product reviews,” “helps with code review,” or “supports requirements analysis” only identify a general capability. They do not describe the situations in which the skill should be used.

In real conversations, users rarely say, “Please use the product review skill.” They are more likely to say:

• “This proposal is scheduled to launch next week. Can you review the risks?”
• “Is this feature worth building? Give me a recommendation.”
• “What could block the release?”

If the description does not cover this type of user language and task signal, the model may fail to associate the request with the skill.

2. The Description Lacks Task Verbs and Input Signals

Trigger signals generally consist of verbs, objects, and constraints.

For example:

• Verbs: review, investigate, compare, create a migration plan
• Objects: product proposal, API change, abnormal logs
• Constraints: before launch, across multiple teams, high risk

If a description contains only a collection of nouns, without action verbs or input signals, the model cannot determine when to invoke it.

3. The Skill Overlaps with General Capabilities

Many skill descriptions overlap heavily with what the model can already do, using phrases such as “help write code,” “analyze problems,” or “provide recommendations.”

In such cases, the model may conclude that it can answer directly without loading a skill.

The description should explain the skill’s unique value. For example, it may provide a structured checklist, a required output format, mandatory constraints, domain-specific knowledge, or a reusable workflow. It should not merely claim to “help” with a broad category of tasks.

4. The Description Is Too Narrow

Some descriptions cover only one fixed expression, such as “Use when the user requests a pre-release check.”

Users may express the same intent in many ways:

• “What risks should we consider before publishing?”
• “Is this version ready to ship?”
• “List the blocking issues.”

If the description does not include synonyms, related scenarios, and alternative ways of expressing the same intent, the trigger rate can fall significantly.

The description should cover the underlying task intent rather than a single phrase.

5. Multiple Skills Have Nearly Identical Descriptions

When several skills all say they are “for code review” or “for quality checks,” the model cannot easily distinguish them.

As the number of skills increases, this kind of duplication becomes more damaging. The solution is not necessarily to make every description longer. Instead, each skill should have a clear and relatively exclusive scope.

For example:

• One skill handles security reviews.
• Another handles performance reviews.
• A third focuses on maintainability.

Each description should specify its own trigger signals and exclusion conditions.

6. The Model Prefers to Answer Directly When Uncertain

When the correct action is unclear, a model tends to answer directly instead of loading a skill.

Descriptions that use weak language such as “can,” “optional,” or “may apply in some cases” reduce the likelihood of triggering even further.

Use explicit routing language instead:

• “Use when the user asks for…”
• “Prioritize loading when the input includes…”
• “Must be used when the request involves…”

This does not exaggerate the skill’s capabilities. It makes the intended routing conditions explicit.

7. The Metadata Budget Is Limited

A description usually has a budget of roughly a hundred tokens, so it cannot contain the full skill body.

An effective description should pack in the following information:

• A one-sentence capability statement
• Two or three trigger scenarios
• Several input signals
• One sentence describing the output value
• One exclusion boundary

Avoid background stories, repeated workflow steps, and excessive adjectives. The goal of the description is to be selected, not to explain every detail of the skill.

3. A Practical Method: Write the Description as a Routing Protocol

A method that has proved effective across hundreds of controlled comparisons is to transform the description from an explanatory summary into a routing protocol.

A recommended structure is:

Capability: One sentence describing the skill's unique output.
Trigger scenarios: Two to four user intents and common phrasings.
Input signals: Task objects, constraints, risk indicators, and data types.
Output value: What structured result the user receives after loading the skill.
Exclusions: Situations where the skill should not be used.

For example:

name: product-review
description: >
  Use when the user requests a pre-launch product review, risk inventory,
  feasibility assessment, or review conclusion.
  Trigger signals include product proposals, target users, scope constraints,
  launch plans, risk questions, and requests for blocking issues.
  Outputs structured review findings, risk levels, blockers, and recommendations.
  Do not use for copy editing, isolated code debugging, or general consultation
  unrelated to product decisions.

This description does not depend on a specific platform interface, command, or API. It places the key routing information within the available metadata:

• When to use the skill
• What inputs indicate that it is relevant
• What output it provides
• When it should not be used

That makes it easier for the model to make a routing decision.

1. Build Positive and Negative Test Sets

Do not revise descriptions based only on intuition.

Start with 20 to 50 positive examples: user prompts that should clearly trigger the skill. Include formal wording, conversational wording, synonymous rewrites, and mixed-language prompts where relevant.

Then create near-negative examples. These should look similar but should not trigger the skill, such as:

• Simple questions that need only a general answer
• Tasks assigned to another skill
• Requests outside the skill’s intended scope

You can also add hard-negative examples specifically designed to test whether the exclusion boundaries work.

2. Measure First-Turn Trigger and False-Positive Rates

The key question is not whether the model understands what the skill is. The important metrics are:

• Whether the skill loads on the first turn
• Whether false triggers remain controlled
• Whether users must manually invoke the skill as a fallback

After every description change, run the same test set and record the results.

If positive examples fail to trigger, first add more trigger scenarios and input signals. If negative examples trigger incorrectly, strengthen the exclusion boundaries or revise the skill name.

3. Design the Name and Description Together

The name is a strong signal, while the description provides context.

A name should clearly identify the task domain without being too broad or too narrow. The description should add the synonyms and related scenarios that the name cannot express on its own.

The two must remain consistent. For example, if a skill is named release-review but its description mainly discusses requirements analysis, the model may become uncertain about its purpose.

4. Control Length and Information Density

A description is not necessarily better because it is longer. Excessive length can dilute the most important trigger terms, while an overly short description may omit the conditions needed for routing.

Use short sentences and list-like semantics. Place the most important task verbs and objects near the beginning.

Background explanations, complete procedures, and extensive examples belong in the skill body. Progressive disclosure can provide them after the skill has been loaded.

5. Create Mutually Exclusive Boundaries Among Skills

As the number of skills grows, description conflicts require active management.

Possible approaches include:

• Using name prefixes to indicate domains
• Defining what each skill is responsible for and what it is not responsible for
• Stating priority conditions for high-priority skills
• Periodically reviewing the full skill inventory
• Merging highly similar skills
• Removing skills that have no trigger activity and provide no value through explicit invocation

For important skills, retain a manual invocation path as a fallback. However, manual invocation should not be treated as the primary triggering mechanism.

4. Conclusion: Fix the Routing Before Expanding the Skill Body

When a skill does not trigger, the problem is often not that the skill body needs more content. The description has failed to perform its routing function.

The description sits between the system prompt and skill loading, making it one of the most important metadata signals in the model’s selection process. A functional summary tells the model only that the skill exists. A description that specifies trigger conditions, input signals, output value, and exclusion boundaries helps the model determine whether the skill should be used now.

The recommended repair sequence is:

1. Build a test set.
2. Restructure the description.
3. Run regression tests.
4. Optimize the skill body only after the trigger path is stable.

A skill description is a routing protocol, not a user manual. Only when that protocol is clear, mutually distinguishable, and testable does the full skill body have a reliable chance of entering the context at the right time.