Skip to content

Stop wasting tokens with "When to Use" sections in your OpenCode skills

Here's a gotcha I keep seeing my colleagues run into, and that I myself tripped over when I first started writing my first SKILL.md files for OpenCode:

Sections detailing "when to use/load/activate/etc" in a SKILL.md are a waste of tokens and potential sources of context pollution!

(It doesn't help that the official OpenCode docs replicate this anti-pattern...)

Explanation

When an agent is initially loaded, OpenCode passes it a chunk of text including the system prompt, available tools, skills, other agents, as well as any custom prompt configured for the specific agent being loaded. For skill in particular, this "initial context" contains an XML table with the following structure

<available_skills>
  <skill>
    <name>skill-name</name>
    <description>
      `description` key from the skill front-matter
    </description>
    <location>path/to/skill.md</location>
  </skill>
  ...
</available_skills>

as well as additional guidance:

Skills provide specialized instructions and workflows for specific tasks. Use the skill tool to load a skill when a task matches its description.

Nowhere in the initial context are the bodies (i.e. the contents of SKILL.md) of skills. The only information about skills made initially available to agents are names, descriptions, and locations, and agents are supposed to determine whether or not to load a skill exclusively based on this information.

From this, we conclude that:

  1. description keys should ideally be terse and, above all, actionable, in order for agents to reliably load skills when appropriate. In practical terms, skill descriptions should probably include explicit guidance on when to load/use the skill. I tend to begin all my skill descriptions with an imperative "Load this skill when...".
  2. Sections in the skill body describing "when to load" or "when to use" it are basically a waste of tokens (and potentially a source of context bloat and pollution), as they are only ever read after the agent has already decided to load and use the skill.

Conclusion

So please, just stop adding unnecessary "when to use" sections in your skills. Best case, you're wasting tokens. Worst case, you're actively hampering the performance and reliability of your agents and skills by introducing sources of context pollution and noise. Just focus on writing terse, compact, and actionable description front-matter keys, and keep the skill bodies direct and lean.