A preflight script: fail once, with every missing thing listed
A skill that fails on one missing tool, then the next, then the next, wastes an afternoon. A preflight check lists every missing requirement at once.
The worst first run is serial failure: missing tool, install it, rerun, missing config, fix it, rerun, wrong version. A preflight script turns that into one message.
The shape
missing = []
if not which("node"): missing.append("Node.js 20+: https://nodejs.org")
if not exists("package.json"): missing.append("Run this from your project root")
if missing:
print("Before this skill can run:")
for m in missing: print(" -", m)
raise SystemExit(1)Call it first
The first line of the skill's workflow in SKILL.md runs the preflight and stops on failure. Claude reads the list and can explain it to the user, which is a far better experience than a stack trace three steps in.
It pairs with keeping dependencies minimal, covered in testing scripts inside skills, and with running the whole thing somewhere clean in a Docker harness.
Questions
What does a preflight script check?
Every tool, version, file and setting the skill needs, before any real work starts, and it reports all failures together.
When should the preflight run?
At the start of the skill's workflow, called from SKILL.md, before any step that depends on the environment.
What should it print when things are missing?
Each missing item with the exact command or link to fix it, and a single clear line at the end saying the skill cannot continue until they are fixed.