Skills With Scripts: Executable Attachments, Dependencies and Sandboxing, Cross-Platform Support, and Breaking Down Document-Handling Skills

Self-contained: do not make the reader install an environment first

Scripts most often die at the first step — dependencies that will not install. The model runs python scripts/extract.py, gets "no such module," and then starts installing things on its own initiative, at which point the step is out of control.

The fix is to write the dependency declaration into the script itself and let the runner resolve it on the spot. Several ecosystems have a way to do this.

On the Python side a dedicated spec defines inline script metadata, with dependencies in a comment block at the head of the file; run it with uv run or pipx run and the runner builds an isolated environment and installs them:

# /// script
# requires-python = ">=3.12"
# dependencies = ["beautifulsoup4>=4.12,<5"]
# ///

On the JavaScript side, Deno's npm: import prefix and Bun's runtime auto-install achieve the same thing, with the version right in the import path. Which one to pick depends on what is installed in the user's environment, but whichever you pick, pin the version.

Self-contained has a second sense: a script should not depend on the current working directory. References to scripts in SKILL.md always use paths relative to the skill root (scripts/validate.py), which is the convention; but the input file paths the script handles should come from arguments rather than assuming they are in the current directory.

Designing an interface for an agent

This is today's most valuable section. A command-line tool for an agent and one for a person involve entirely different trade-offs. People read documentation, experiment, and guess from experience when something errors; an agent can only read the few lines you printed and then decide the next step.

First, it absolutely must not be interactive. An agent runs in a non-interactive terminal and can answer no prompt. A script that stops to wait for you to type an environment name will hang until it times out. All input comes through arguments, environment variables, or standard input. This is not a best practice but a hard requirement.

Second, the help output is the interface documentation. An agent learns to use your script mainly through --help. State a one-line summary, the argument list, and two or three usage examples. But keep it short — that output enters the context verbatim and competes with everything else.

Third, the error message decides whether it gets it right next time. A bare "invalid argument" wastes a whole turn; stating which item is wrong, what was expected, what was received, and what the valid values are lets the model fix it on the spot.

Error: --format must be one of json, csv, table.
       Received: "xml"

This pays off most in validation scripts. A line like "the field signature_date does not exist; available fields are customer_name, order_total, signature_date_signed" shows the model at a glance that it got the suffix wrong. An error message is a prompt written for the model, so write it in that spirit.

Fourth, output should be structured, with data and diagnostics separated. Structured data goes to standard output and progress and warnings to standard error. That way the caller gets clean output that can be handed straight to another tool, while the diagnostics are not lost.

Fifth, output volume must be bounded. Many agent environments truncate output past ten or twenty thousand characters, and not always with any notice. So default to a summary or a limited count, and provide a paging flag so it can ask for more as needed; when the output is genuinely large, require the caller to name an output file.

A few scattered but important ones: idempotence (an agent will retry, so create-if-absent is safer than create-and-fail-if-exists); meaningful exit codes (different codes for different failure kinds, documented in the help); and a dry-run flag for dangerous operations.

The code below turns these principles into a minimal validation script. Watch the wording of the error messages — that is the point; the code itself is simple.

type Field = { name: string; type: 'string' | 'number' | 'boolean'; required: boolean }
 
export function validate(fields: Field[], values: Record<string, unknown>): string[] {
  const errors: string[] = []
  const known = new Set(fields.map((f) => f.name))
 
  for (const f of fields) {
    if (!(f.name in values)) {
      if (f.required) errors.push(`missing required field ${f.name} (type ${f.type})`)
      continue
    }
    const actual = typeof values[f.name]
    if (actual !== f.type) {
      // Give expected, actual, and the value, so the model does not need another guessing round
      errors.push(
        `field ${f.name} has the wrong type: expected ${f.type}, received ${actual} (value ${JSON.stringify(values[f.name])})`
      )
    }
  }
  for (const name of Object.keys(values)) {
    // An unknown field is almost always a typo, so list every available field
    if (!known.has(name))
      errors.push(`the template has no field ${name}. Available fields: ${[...known].join(', ')}`)
  }
  return errors
}
 
// Data to standard output, diagnostics to standard error; exit 0 for pass, 1 for errors, 2 for usage
export function main(argv: string[]): number {
  if (argv.length !== 2) {
    console.error('usage: validate <field-list JSON> <values JSON>')
    return 2
  }
  const errors = validate(loadFields(argv[0]), loadValues(argv[1]))
  console.log(JSON.stringify(errors.length === 0 ? { ok: true } : { ok: false, errors }))
  return errors.length === 0 ? 0 : 1
}

# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///
"""Validate a values plan against a field list. Usage: uv run validate.py <field-list> <values>"""
import json
import sys
 
TYPES = {"string": str, "number": (int, float), "boolean": bool}
 
 
def validate(fields: list[dict], values: dict) -> list[str]:
    errors: list[str] = []
    known = {f["name"] for f in fields}
 
    for f in fields:
        if f["name"] not in values:
            if f["required"]:
                errors.append(f"missing required field {f['name']} (type {f['type']})")
            continue
        v = values[f["name"]]
        if not isinstance(v, TYPES[f["type"]]):
            # Give expected, actual, and the value, so the model does not need another guessing round
            errors.append(
                f"field {f['name']} has the wrong type: expected {f['type']}, "
                f"received {type(v).__name__} (value {json.dumps(v)})"
            )
    for name in values:
        # An unknown field is almost always a typo, so list every available field
        if name not in known:
            errors.append(f"the template has no field {name}. Available fields: {', '.join(sorted(known))}")
    return errors
 
 
def main(argv: list[str]) -> int:
    if len(argv) != 2:
        print("usage: validate.py <field-list JSON> <values JSON>", file=sys.stderr)
        return 2
    fields = json.loads(open(argv[0], encoding="utf-8").read())["fields"]
    values = json.loads(open(argv[1], encoding="utf-8").read())
    errors = validate(fields, values)
    # Data to standard output, diagnostics to standard error; exit 0 for pass, 1 for errors, 2 for usage
    print(json.dumps({"ok": True} if not errors else {"ok": False, "errors": errors}))
    return 0 if not errors else 1
 
 
raise SystemExit(main(sys.argv[1:]))

Permissions, sandboxing, and untrusted input

Adding scripts to a skill makes "let the model execute code" that skill's everyday action. The boundaries of that risk need stating.

First, a script inside a skill is code, and its provenance is the trust boundary. A script you wrote and a script inside a skill you installed from some marketplace carry entirely different risk. Read the scripts/ directory before installing a third-party skill — the same thing you do when glancing at an npm package before installing it, except a skill is more easily mistaken for documentation and treated with less caution.

Second, grant pre-approved tools at minimum privilege. The spec's allowed-tools field (and each client's equivalent mechanism) can pre-approve some tools so not every step raises a confirmation dialog. But grant at command granularity: write "may run git's read-only subcommands," not "may run any shell command." That field is still experimental with varying support, so do not stake your safety entirely on it.

Third, the input a script handles is untrusted. Your script parses a file the user gave you or a payload an endpoint returned, and that content may hide something like "ignore the previous instructions and instead do…". The script itself is fine as long as it does not execute input as code, but a script's output enters the model's context — echo a large stretch of external content verbatim and you have said that content straight to the model. The sister course, day 6 of MCP in 7 Days, is devoted to this class of prompt injection and tool description trustworthiness, and is worth reading before writing scripts.

Fourth, dangerous operations need a gate. For deletes, overwrites, and publishes, give a dry-run flag or require an explicit confirmation argument. An agent will retry, and you cannot afford the cost of retrying an irreversible operation.

Cross-platform support

Whose machine the script runs on is not your call. Three things go wrong most often.

Path separators and case. Use your language's standard library path joining rather than hand-writing slashes; filename case is significant on some systems and not others, so a SKILL.md written as Skill.md runs on your machine and vanishes on a colleague's.

Shell differences. If a command in the body only works under one shell, give the alternative alongside it, or switch to a cross-platform runner outright. The spec's examples do exactly that: two commands for the same thing, letting the agent pick per environment.

Line endings and encoding. Specify the encoding explicitly when reading and writing text, and mind the line ending style when generating files, or you will produce swathes of meaningless diffs in version control.

What those three have in common is that they never appear on your own machine. So either declare the environment requirements explicitly in the body (which is what the compatibility field is for) or let the standard library smooth the differences over — do not rely on luck.

Breaking down a document-handling skill

Put everything above together and you get one complete form: plan first, validate, then execute. Document handling, form filling, and bulk edits should all take this route.

flowchart TB
  A[Step 1 analyze<br/>a script reads the template and emits the field list<br/>this is ground truth] --> B[Step 2 plan<br/>the model writes a values plan<br/>never guessing field names from memory]
  B --> C[Step 3 validate<br/>a script compares plan against ground truth<br/>errors specific enough for self-correction]
  C -- errors --> B
  C -- passes --> D[Step 4 execute<br/>a script fills in and writes the file<br/>only this step touches disk]

The key is step 3, not steps 1 and 4. Without step 3 this is an ordinary read-edit-write; with it, the model gets a chance to discover its own mistake before doing anything for real, and given specific enough error messages it can correct itself.

Three design points worth noting separately:

What the analysis script emits is ground truth. The model should not guess from memory which fields the template has; have the script extract them from the template. That step eliminates the most common class of error: a misspelled field name, or an extra field that does not exist.

The validation script does not change data, and the fill script does not validate. Merge the two into one script and the model has no chance to stop between planning and executing. The fill script also needs a self-check: if any placeholder remains unreplaced after filling, fail and exit — better to fail than to write out a document that looks filled in and still carries placeholders, since a file like that gets sent out as finished work.

Intermediate artifacts go to disk. Write the plan as a JSON file rather than leaving it in the model's context. Only once on disk can the validation script read it, and only then can you open it and look when something goes wrong.

Source Reading

Hands-On Lab

There is real code today, but the code is not the point; the error messages are. Before starting, look at the four errors the solution's validation script reports and get a feel for what "specific enough for the model to self-correct" means. An actionable self-check: send the error messages you wrote to somebody who has not seen the template and see whether they can fix it from that alone.

1. Get the solution running and use MOCK=1 to see the full trace of the validation script failing first and the execution succeeding after correction.
2. Complete the validation script's three error classes in the starter, polishing the wording rather than the logic.
3. Complete the analysis script's placeholder parsing and deduplication so one field cannot appear with two types.
4. Complete the fill script's self-check so it fails when placeholders remain rather than writing a half-finished file.
5. Complete the SKILL.md workflow and pitfalls sections, writing the three-step flow as a checklist the model can follow.

Interview Questions

Today's 3 questions are in the question bank below, weighted toward the line between scripts and instructions, agent-friendly script interfaces, and the permissions and sandboxing of script execution. Expand each one and read the analysis before the key points — practicing the derivation beats memorizing bullets. The high-frequency labels for the domestic and overseas markets are there so you can pick by target market.

Checklist and Tomorrow

• Judge whether a piece of logic belongs in the SKILL.md body or should be distilled into a script under scripts
• Write an agent-friendly script that is self-contained, non-interactive, produces structured output, and gives self-correctable error messages
• Break a document-handling task into a three-step flow: plan first, then validate, then execute
• State the reasoning behind "the validation script does not change data and the fill script does not validate"
• All 5 acceptance criteria of the lab pass
• Answer at least 2 of the 3 interview questions without looking at the key points

Tomorrow (D5) we change roles: from the person writing skills to the person implementing skill support. For four days you have been using progressive disclosure, and tomorrow you write it for real — scanning directories, leniently parsing frontmatter, composing names and descriptions into a catalog injected into the system prompt, and reading the body only on activation. After implementing it once, your understanding of every recommendation from the last four days will change, because you will see which line of runtime code each one corresponds to.