Control context, dependencies, and paths

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

The specification recommends keeping the main file under 500 lines and about 5,000 tokens. This is a ceiling, not a target. Move detailed conditional material out, but keep critical safety gotchas in the main file so the agent sees them before acting.

Use paths relative to the skill root. Write scripts/validate-report.mjs and references/npm.md. Do not embed your own home directory. Keep references one level deep so the agent does not follow a maze.

Compatibility belongs in metadata when it matters. Our validator requires Node.js, while the core workflow needs Git and a host capable of running local commands. State that directly. If a host cannot execute the script, the skill can still tell the agent to perform the equivalent structural check manually, but it should record that the validator did not run.

Measure the current SKILL.md. Remove generic explanations of Git, testing, and Markdown. Keep project-specific command discovery, stop conditions, evidence rules, and resource-routing instructions.

Finally, move the entire skill folder to a different temporary path. Run the validator and open every linked resource. Portability bugs often hide behind absolute paths and assumptions about the author’s machine.