Add a Helper Script to a Skill

When a step must be exact (compute a contrast ratio, validate a schema, transform a file), prose instructions re-derive it every time, with room to drift. A bundled script makes that step deterministic: the agent runs your code and reads the result.

The recipe

1. Write the script in a scripts/ folder inside the skill, standard library only. A dependency the user does not have is a silent failure waiting.
2. Make the output machine-readable and unambiguous: print the answer, not a paragraph around it.
3. Run it yourself first, from a clean directory, with the exact command you will put in the skill.
4. In SKILL.md, name the script, the exact invocation, and WHEN to run it. State that the script is the source of truth for that step.

.claude/skills/contrast/
  SKILL.md
  scripts/contrast.py

# in SKILL.md:
# To check a color pairing, run:
#   python scripts/contrast.py <fg-hex> <bg-hex>
# and read the ratio from the output. Never eyeball contrast.

What belongs in a script vs. the body

• Script: anything with one right answer (calculations, format validation, deterministic transforms, checks against a spec).
• Body: anything needing judgment (what to do with the result, how to phrase output, when the rule has exceptions).