Skip to main content
Tools decide what an expert can do. Skills decide how well it does it. A skill is a structured document telling the expert how work of a certain kind should be done, usually alongside executable scripts, templates, and references. The same model with the same tools produces wildly different quality depending on its skills — the difference is whether someone wrote the method down.

​
What a skill looks like

The entry point is a SKILL.md with YAML frontmatter:
description matters most: it is the only thing the expert uses to decide whether to activate the skill. “Used for analysis” is far weaker than “the user asks to compare multiple products” — the latter states a trigger. A skill directory can also hold:
Scripts are black boxes: the expert is explicitly told not to read their source, only to call them and read the output. That lets skill authors encapsulate complex logic without worrying that the model will “read it once and rewrite a broken version.”

​
Progressive disclosure: why everything is not in context

The platform ships roughly 57 built-in skills. Injecting all of them in full would exhaust the context budget on turn one. The real flow has three stages:
1

discover — names and descriptions only

The expert receives lines of - **qualified-name** [tags]: description, which costs almost nothing. Tag filtering is available.
2

activate — read the full text

Only after choosing does the full SKILL.md load, along with any references marked for auto-loading in frontmatter.
3

execute — run scripts or read references

Scripts and reference documents inside the skill directory are invoked on demand.
The point of this chain: you do not pay full text just so the expert knows a skill exists — you pay only when it is actually used.

​
Three ownership tracks

The skills available in one conversation are the union of three sources, never overriding one another: Name collisions are fine: builtin/pptx, user/pptx, and expert/pptx can coexist. The expert sees qualified names and must activate by the full name — a bare name with multiple matches is rejected rather than guessed. Write paths are strictly separated by ownership:
Asking an expert to “save this method as a skill” in a free chat fails. Skill creation requires expert context, which free chats and IM channels do not have — the tool then points you at the UI to save it into your global library instead. That is not a bug but an ownership constraint: with no expert, the skill has no owner.

​
Skills versus plugins

The pair most often confused: Many built-in plugins come as pairs: the plugin brings tools, the skill brings method. The PDF plugin, for instance, carries both builtin/pdf (processing) and builtin/kami (typeset authoring).

​
Context cost

Every activated skill occupies context. Three rules of thumb:
  1. Your global library is not a bookmark folder. Thirty installed skills means thirty description lines in every discover call. Keep the ones you actually use.
  2. Longer skill bodies cost more to activate. The evolution system has a dedicated dimension watching skill length (computed by code, not self-scored by the model) precisely to stop skills from bloating with every improvement.
  3. Read references on demand; do not auto-load everything. Auto-loaded references enter the context in full at activation.

​
For creators

Expert-scoped skills are your core differentiating asset — everyone has the same models and tools; the method is yours. Three practical rules for writing them:
  • Write triggers, not feature lists. The description is what the expert judges against.
  • Constraints are worth more than steps. “Do not do X” usually raises the floor more than “do Y.”
  • Push determinism into scripts. Anything code can guarantee (format conversion, coordinate math, validation) should not depend on the model getting it right each time.
The evolution system proposes skill improvements from real run data, and a dual ratchet guarantees an accepted improvement never lowers quality while strictly raising efficiency — see self-evolution.

​
Failures and what to do

​
Keep reading

Skill catalog

Every built-in skill

Plugins

The tool layer: what an expert can do

Self-evolution

How skills get improved automatically

Configure your expert

Skill management on the creator side