Every token in SKILL.md competes with the user’s request, the repository, and any other active instructions. Spend those tokens on knowledge the agent would otherwise miss.

The size ceiling

The specification recommends keeping SKILL.md under 500 lines and around 5,000 tokens. Treat that as a ceiling, not a target. A 120-line skill that says everything it needs to is better than a 480-line one.

Move conditional detail out to references. But keep the critical safety gotchas in the main file. The agent must see “never push during preflight” before it acts, not after it happens to open a reference.

Relative paths only

Write paths relative to the skill root:

scripts/validate-report.mjs
references/npm.md
assets/release-report.md

Never embed your home directory. /Users/flavio/skills/release-readiness/scripts/validate-report.mjs works on exactly one machine. Keep references one level deep so the agent never follows a chain.

State compatibility when it matters

Our validator needs Node.js. The core workflow needs Git and a host that can run local commands. Say that plainly in the compatibility field:

compatibility: Requires Git and a host that can run local shell commands. The bundled validator requires Node.js.

If a host can’t run the script, the skill should still work. Tell the agent to do the structural check by hand, and to write in the report that the validator did not run. Degrade honestly instead of failing silently.

Measure and cut

Open your current SKILL.md and count the lines. Then read it with one question in mind: would the agent know this anyway?

Cut generic explanations of Git, testing, and Markdown. The agent knows what git status does. Keep what’s specific to this skill: how to discover the project’s commands, the stop conditions, the evidence rules, and which resource to load when.

Expect the file to shrink by a lot. Most first drafts are half explanation the agent didn’t need.

The portability test

Finally, move the whole folder somewhere else and run it from there:

cp -r release-readiness /tmp/rr-portability-test
cd /tmp/rr-portability-test
node scripts/validate-report.mjs assets/release-report.md

Then open every path mentioned in SKILL.md from that new location. If the validator fails or a link points at nothing, you found a portability bug. They hide behind absolute paths and assumptions about the author’s machine.

A skill that only works from its original checkout isn’t a skill yet. It’s a personal script with a fancy folder.

Control context, dependencies, and paths