How to Write Skill Descriptions: Use Trigger Keywords Instead of Feature Documentation

A Widely Misunderstood Design Detail

When working with LLM Skill systems, many developers make a seemingly trivial but deeply impactful mistake: writing the skill's "description" as if it were a detailed explanation of the skill's functionality.

This seems perfectly natural—of course a description should explain what the skill does. But in reality, this intuition runs counter to how the Skill mechanism actually works. As one experienced practitioner pointed out: You should think of a skill's description as "trigger keywords" rather than an actual description of the skill's functionality.

This sounds counterintuitive at first, but once you understand how Skill descriptions actually function within the model's context, you'll see why this approach is correct.

Skill Descriptions Are Always Injected into Context

The key insight is this: The skill's description text is always inserted into the model's context, regardless of whether the skill ends up being invoked.

In other words, the description isn't a supporting document that gets loaded only after the model "decides to use a skill." It's always present in the context from the start. Its core mission is to help the model determine "when should this skill be pulled in and used."

This means every single character in the description consumes precious context space while simultaneously influencing the model's routing decisions. If you write a lengthy feature explanation in the description, you're not only wasting tokens but also risking that the trigger signal gets buried in verbose text.

Context Cost Is Invisible

For scenarios with only one or two skills, a verbose description might not cause much harm. But when the skill library scales to dozens or even hundreds, each skill's description accumulates in the context. At that point, the cost of lengthy descriptions multiplies—both in terms of direct token overhead and in the declining accuracy of the model's matching decisions across numerous descriptions.

The Paradox of Over-Detailed Descriptions: Skills That Never Get Called

Even more interesting is a phenomenon that repeatedly surfaces in practice: Some skill descriptions are so thorough that the description itself contains all the information needed to complete the task, so the model never actually needs to invoke that skill.

This is a classic case of "trying too hard and defeating the purpose." Developers intended to make the description clearer, but ended up stuffing the skill's complete logic, parameters, and even examples into it. After reading the description, the model realizes "I already know how to do this" and skips the skill invocation entirely.

This creates two problems:

• The properly encapsulated logic inside the skill (which may include more rigorous workflows, tool calls, or data processing) gets bypassed;
• What should be a concise description becomes a bloated manual, needlessly occupying context space.

The Right Approach: Treat Skill Descriptions as Triggers

So what should a good skill description look like? The core principle can be summarized in one sentence: The description should contain "magic keywords" that tell the model when to pull in this skill.

Focus on Trigger Scenarios, Not Implementation Details

Instead of writing "This skill parses user-provided CSV files, performs data cleaning, deduplication, format conversion, and outputs statistical summaries…" focus on the trigger signals—explicitly stating keywords like "process CSV/tabular data," "data cleaning," and "statistical summary" that are likely to appear in user requests.

The description's job isn't to explain "how" the skill works, but to help the model accurately identify "what kind of user intent should activate it." The actual implementation details belong in the content loaded after the skill is invoked, not in the always-present description.

Separation of Concerns Between Description and Skill Body

This is essentially a separation of concerns:

• Description layer: Lightweight, keyword-focused, serving routing and trigger decisions;
• Skill body: Carries the complete execution logic and detailed instructions, entering the context only when invoked.

Following this division of labor reduces always-on context overhead, improves the accuracy of skill selection, and ensures the rigorous logic inside skills actually gets executed rather than being "short-circuited" by an overly detailed description.

Practical Advice for Developers

For developers building or maintaining Skill systems, this insight is worth keeping in mind:

1. Audit your existing skill descriptions—Are they describing functionality, or providing trigger signals? If they read like product documentation, they probably need rewriting.
2. Keep descriptions short—The shorter the description and the more precise the keywords, the more accurate the routing decisions tend to be, and the lower the context cost.
3. Save the details for the skill body—Complete execution instructions belong inside the skill, not in the always-present context description.
4. Watch out for the "description as answer" trap—If the description alone enables the model to complete the task, you've leaked logic that should be encapsulated into the wrong layer.

Ultimately, a Skill's description is an elegant trigger mechanism, not documentation. Understanding this distinction will yield tangible improvements in your skill system's accuracy, cost efficiency, and maintainability.