Skip to main content

Skill Token Analysis

Skill Token Analysis ranks skills by estimated token size. Skills are loaded into AI conversations as context, so oversized skills increase the baseline cost of every session where they apply.

Open Monitor > Tokens, then select Skills Context, Skill Token Analysis, or View all from the Skills Context card.

Skill Token Analysis page showing skills ranked by estimated tokens with Optimize actions

How to read the page​

AreaDescription
How skill tokens workExplains that skills are loaded into conversations and that references can move detail out of always-loaded content.
Est. TokensEstimated skill token size.
ContentTokens from the main skill content.
ScriptsScript content included with the skill, if any.
RefsNumber of references attached to the skill.
StatusWhether the skill is active.
OptimizeOpens the optimization flow for that skill.

The UI guidance recommends keeping skills under 2.0K tokens. Skills above 4.0K tokens should usually be optimized by extracting content into references.

Optimize a skill​

The Optimize Skill modal uses your own AI provider to analyze skill content and suggest references. This is off until you enable Bring Your Own AI under Settings › AI Settings; the default gateway does not power it. The token rankings above work without it.

  1. Find a high-token skill.
  2. Select Optimize.
  3. Select Analyze skill content.
  4. Review the suggested references. Each one shows its token size and a summary of what it contains. Select Re-analyze to run the analysis again.
  5. Clear the checkbox on any reference that should stay in the main skill content, then select Add References. The button shows how many are selected.
  6. After saving, remove or shorten the extracted sections in the main skill content.
Optimize Skill modal showing suggested references to extract from an oversized skill

References are fetched only when needed. Use them for long examples, detailed procedures, catalogs, background documentation, and other content the agent does not need in every conversation.

What to extract​

Good reference candidates include:

  • long before-and-after examples
  • detailed policy or style catalogs
  • setup procedures used only in specific cases
  • troubleshooting sections
  • source material the agent should consult only on demand

Keep the main skill focused on the always-needed instructions: what the skill is for, when to use it, and the shortest rules the agent needs before it can decide whether to fetch a reference.

On this page