Thirty SKILL.md files cost about 3,000 tokens until one of them activates

The description field is the whole trigger surface. It is the only text Claude sees before deciding whether to activate a skill, and a vague one means the skill never fires ^[10]. In that case the workflow underneath it is never read. Thomas Tartrau's commit-push skill therefore lists its trigger phrases in the frontmatter in both English and French ^[13]. He wrote that had he described the skill only as committing and pushing changes, it would have triggered on commit and push but not on pousse ca or commit tout ^[14].

Thirty skills at the stated discovery cost of roughly 100 tokens each is 3,000 tokens injected at the start of every session, about 1.5 percent of the 200K window ^[5][6][18]. One body at the Level 2 cap of 5,000 tokens costs as much as the discovery metadata for fifty skills ^[7][19]. Detail past the cap goes in references/, which the agent opens by name only when the body tells it to, and Tartrau describes a blog skill with 20 reference files of which two or three load per run ^[8][9].

Markdown in a folder diffs cleanly, so a skill can go through code review like any other file. The format gives the reviewer nothing to assert that "pousse ca" routes to commit-push. You read a description, form a view about what it will match, and find out at runtime.

Two constraints deserve a schema check in CI. Invalid YAML prevents loading with no error message at all; the skill simply disappears ^[12]. And name must be lowercase with hyphens, 1 to 64 characters, and must match the parent folder name exactly ^[11]. Rename the directory in a pull request without editing the field and the two stop matching, while the diff still looks clean. A frontmatter linter costs less than the ten minutes you will spend asking an agent why it ignored you.

Portability is the claim a team would plan around, and it rests on one practitioner writing up months of iteration ^[17]. Tartrau's article points to the official documentation for installation and basic syntax ^[21]. It gives no spec version, and no list of which frontmatter fields Cursor reads ^[20]. Two fields travelling between tools, name and description, is a smaller guarantee than a folder with scripts/ in it travelling.

His lint-check example is the part worth copying. Six numbered steps: cargo fmt --check, cargo fmt if formatting is off, cargo clippy with warnings as errors, fix clippy issues one by one, cargo check, then stop and report if errors remain after three fix attempts ^[15]. A table sets out what to do when each command fails ^[15]. The file is 30 lines ^[16].