Add a script to an agent skill when a recurring step has a stable rule, a defined input and an output you can check independently. Use the SKILL.md instructions to explain when that step is appropriate, how to supply the input and what the assistant must do with success or failure. Moving a vague business instruction into code does not make the rule correct; it makes the chosen rule executable.
For teams building reusable AI workflows, the decision is not whether a package looks more advanced with a scripts/ folder. It is whether a specific calculation, conversion or validation should be implemented once and reviewed as software instead of being reconstructed during each conversation.
This guide proposes a boundary between instructions, code and interpretation using a fictional training-attendance summary. It is a design example, not an installed skill or an independently tested assistant workflow.
The format allows code without guaranteeing execution
The Agent Skills specification defines a directory with a required SKILL.md file and optional supporting content, including executable scripts. Its compatibility field can describe environment requirements. This is a format contract: a valid package does not establish that a particular assistant can access the files, run the required runtime or return the result correctly.
Anthropic’s October 2025 engineering account introducing Agent Skills describes Claude executing a bundled PDF-processing script rather than generating the procedure each time. That is a vendor’s implementation account, not independent proof of reliability across products. Its useful design distinction is between running a helper and merely reading code as reference material.
Our introduction to SKILL.md workflows uses a drafting task that does not need a script. Code is more useful where the recurring requirement is exact: validate permitted status values, count records under an agreed rule, or produce a required file structure. It adds maintenance obligations and should solve an identified problem.
Define the business rule before choosing the implementation
Imagine a fictional learning team preparing attendance summaries from a registration export. For this example only, each registration has a unique reference and one status: completed, absent or cancelled. The invented reporting rule includes completed and absent registrations in the denominator and excludes cancelled registrations. Only completed registrations count in the numerator.
Those choices are not universal training-reporting standards. The team responsible for the report must decide what a real metric means. If the organization instead counts people across multiple sessions, a registration-level calculation would answer the wrong question even if the arithmetic were flawless.
Write the agreed rule in a versioned reference that the developer and reviewer can inspect. Define whether duplicate references are rejected, which statuses are valid, how an empty eligible set is represented and where rounding occurs. A sentence such as “calculate the completion rate fairly” is insufficient for implementation or acceptance review.
Separate the reporting definition from the policy decision it might inform. Attendance or a recorded completion status does not establish that someone learned a skill. Our workplace AI training guide addresses that different measurement question. A script should not convert an administrative status into an unsupported assessment of competence.
Use a small example to expose the denominator
The following records and rules are entirely fictional. They illustrate what a developer and business owner could use to discuss the intended calculation before implementation.
| Registration | Status | In denominator? | In numerator? |
|---|---|---|---|
| R01 | completed | Yes | Yes |
| R02 | completed | Yes | Yes |
| R03 | absent | Yes | No |
| R04 | cancelled | No | No |
The expected result is two completed registrations out of three eligible registrations: 66.7% when rounded to one decimal place. Dividing by all four records would produce 50%, which is valid arithmetic for a different definition. This is why a script’s tests need the intended business rule as well as plausible sample data.
Keep counts in the result alongside any formatted percentage. A proposed output could contain eligible_registrations: 3, completed_registrations: 2, the reporting-rule version and the display percentage. The assistant should be able to state the denominator without reconstructing it from a rounded figure.
If an input contains an unrecognized status such as “pending,” our proposed example should reject the file for clarification. Silently treating that status as absent would change the rule. Likewise, conflicting duplicate registration references should remain an error to resolve rather than an invitation for the assistant to choose the more convenient row.
Give the helper an interface the assistant can follow
The Agent Skills guide to using scripts recommends non-interactive inputs, concise usage help, structured output, separate diagnostics and meaningful exit codes. It also recommends stating prerequisites and pinning tool versions where relevant. These are authoring practices, not evidence that every helper following them is correct.
For the fictional summary, specify the expected file encoding and fields, permitted status values, uniqueness rule and output destination. Document whether processing is read-only and what files it may create. Include a clear failure for missing fields rather than letting a generated narrative proceed from incomplete data.
Design the result so it is straightforward to validate. A successful exit should accompany the required result fields and a known schema version. Failure should identify the relevant category, such as invalid status or duplicate registration reference, without unnecessarily exposing personal data in logs. Avoid returning a plausible partial percentage as though it were the completed report.
The instructions must also describe the next step. An illustrative workflow could tell the assistant to run a bundled attendance helper, validate its result and draft a short summary only after success. On invalid input, it should explain the issue and request a corrected source through the approved process. This is a proposed workflow description, not a command tested in a named assistant.
Keep the assistant from silently replacing the agreed method
Decide what happens when execution is unavailable. If the task requires the reviewed helper, the assistant should report that it could not run it. It should not silently improvise a different calculation and label that result as generated by the skill’s approved method.
This boundary should be explicit in SKILL.md: identify the helper’s purpose, its input and output expectations, and the stop conditions. Keep detailed field definitions in a supporting reference when that improves readability, but ensure the main workflow points to it. Document which environment the package requires, including runtime and dependencies, and verify that environment in the intended product.
Do not let adding a script expand the task’s authority. The fictional helper needs to read an approved export and write a local summary. It does not need to email participants, change training records or retrieve unrelated employee information. Review those boundaries separately from whether the script produces the right number.
An executable helper also needs an owner. Someone must maintain it when the export changes, the reporting definition is revised or a dependency becomes unsuitable. If nobody can review those changes, the package may turn an informal workaround into a persistent source of error.
Research supports evaluation, not a universal script prescription
The June 2026 revision of SkillsBench evaluates curated skill packages against no-skill conditions using terminal-based tasks and programmatic verifiers. Its trajectory audit identifies executable helpers among several useful authoring patterns. That observation does not isolate scripts as the cause of package-level gains or establish that adding code improves every workflow.
The paper also notes limits in generalization from containerized tasks and changing model–harness integrations. Treat it as motivation to inspect actual execution and outputs, not as a forecast of business productivity. Its benchmark results cannot validate our fictional attendance package, which has not been implemented or tested here.
Check the helper and the surrounding workflow separately
First, ask the developer to verify the script against independently specified expected results. For the example, include the four-record case, a zero eligible denominator, an unknown status, conflicting duplicate references and a changed input-column name. Establish the expected response to each case before running it.
Then evaluate the assistant in the intended environment. Does it choose the correct input, invoke the helper, inspect failure status and preserve the denominator in its final explanation? Can it distinguish “no eligible registrations” from “zero completions among eligible registrations”? Does it stop if required execution is unavailable?
These are proposed acceptance checks; we have not run them against an assistant for this article. They separate a correct calculation from correct orchestration. A sound helper can still be applied to the wrong file, and a successful script run can still be followed by an unsupported interpretation.
Start with one stable transformation, retain its rule version and known examples, and record the actual environment in which it was checked. Keep policy choices with accountable people, exact transformations in reviewed code where useful, and explanations grounded in the result the helper actually returned.