Expand description
Skills: named procedures the user writes and the model loads on demand.
A skill is a directory holding a SKILL.md — frontmatter naming it and
saying when to use it, then a markdown body that is the procedure. The
shape is the Agent Skills standard, and the reason to take a standard here
rather than invent a format is that the procedures worth writing are
portable: this repository already carries two of them, written for the
other side of it.
§Progressive disclosure is the whole point
| Level | Loaded | Cost |
|---|---|---|
| 1 · metadata | always, in the system prompt | ~100 tokens per skill |
| 2 · body | when the model calls skill | the body, once |
| 3 · bundled files | when the body points at one | nothing until read |
So a mailbox full of skills costs almost nothing until one is relevant,
which is what makes this the pressure valve for the learned-rule cap:
MAX_ACTIVE_RULES_PER_DOMAIN is small because the always-on prefix is
finite, and a procedure like how to answer a rec-letter request is too
long for a rule, too specific to be worth a slot, and irrelevant on almost
every run. Skills do not loosen that cap — they make it affordable.
§Why this is allowed to be liberal where learning is strict
A skill is user-authored, and there is deliberately no way for it not to
be. No mecha skill install, no registry client, no remote body, and
nothing here is ever written by a model or derived from a session. That is
the whole safety argument, and it is why loading a skill arms no taint: a
skill body is the user’s own words, exactly like the system prompt and the
*.user.toml rules, and treating it as third-party content would be a
category error in the direction that makes the model invent explanations
for its own harness.
The absence of an install verb is the feature rather than an omission.
Snyk scanned 3,984 published skills and found 36.8% carrying at least one
security flaw, 13.4% a critical one, and 76 confirmed malicious payloads —
and Datadog’s finding is the sharper one for a harness: a cloned
repository can bring skills into a trusted session even if the developer
never installed one from a marketplace. mecha already refuses that shape
for triggers, in writing. It refuses it here for the same reason: the
store is global only, and a project’s mecha.toml may narrow the set
by name but can never author a skill or add one. See
crate::config::SkillsConfig.
§The frontmatter is YAML, and that is not ours to change
Every other file mecha reads is TOML, and this one is not, because the
Agent Skills standard fixes YAML and roughly forty implementations read it.
A skill written here should load in any of them and one written for any of
them should load here; inventing a dialect would spend that for internal
consistency, which is the trade docs/SKILLS-RESEARCH.md §9 lists under
what not to build.
Unknown keys are ignored rather than refused, for the same reason: a
skill carrying a field some other harness understands must not fail to
load here. What is refused is a key mecha knows and cannot use — a
description that is a list, a tools that is empty — because that is an
authoring mistake rather than a portability one.
Structs§
- Skill
- One skill, as read off the disk.
- Skill
Error - A skill directory that would not load, kept so startup can say so.
- Skill
Store - Every skill on the machine, in a stable order.
Functions§
- prompt_
block - The level-1 block: what every run carries about skills it has not loaded.