Chapter 10 of 14 · Create · 5 min read

Adding scripts, templates and reference files to a skill

AI Tool Garage editors·Updated 2026-10-29

Many skills are a single SKILL.md, and that’s often enough. But some jobs need more: a long style guide, a document template, a list of error codes, or a fiddly step that should be done exactly the same way every time. Skills handle this with extra files in the folder, loaded only when needed. This chapter covers the three kinds of supporting file, when each is worth adding, and how to write them so the agent uses them well.

Three kinds of supporting file

Kind	What it holds	How the agent uses it	Add one when
Reference	Detailed knowledge: style guides, API notes, schemas, policies	Reads it when the instructions say it’s relevant	SKILL.md is getting long with detail only some tasks need
Template	A skeleton output to fill in: a report, a config, a document	Copies and completes it	The output should have a fixed structure every time
Script	Code that does a deterministic step: parse, validate, convert, fetch	Runs it and reads the output	A step is error-prone when improvised, or needs exact results

A worked example

Here is a skill that produces a weekly analytics summary from a CSV export. It uses all three kinds of file.

weekly-metrics/

weekly-metrics/
├── SKILL.md
├── template.md              # the report skeleton
├── reference/
│   ├── metric-definitions.md   # what each metric means, how to read it
│   └── house-style.md          # tone and formatting rules
└── scripts/
    └── summarise_csv.py        # computes totals and week-on-week changes

weekly-metrics/SKILL.md

---
name: weekly-metrics
description: Turn a weekly analytics CSV export into a one-page summary with totals, week-on-week changes and notable movements. Use when the user shares a metrics or analytics CSV and asks for a weekly report or summary.
---

# Weekly metrics summary

1. Run the summary script on the CSV the user provided:
   `python scripts/summarise_csv.py <path-to-csv>`
   It prints totals and week-on-week changes as JSON. Use these numbers;
   don't recalculate them yourself.
2. If the script reports missing columns, tell the user which ones and stop.
3. For any metric you're unsure how to interpret, read
   reference/metric-definitions.md.
4. Copy template.md and fill in every section. Leave none blank: write
   "No notable change" where that's true.
5. Follow reference/house-style.md for tone and number formatting.

Notice how SKILL.md stays short. It names each file, says when to use it and what it’s for, and leaves the detail in the files themselves. The agent reads the metric definitions only if it hits a metric it’s unsure about, so on most runs that file costs nothing.

Reference files

Point to each file from SKILL.md with a relative path and a reason: “For error codes, see reference/errors.md.”
Keep references one level deep. If a reference points to another reference, the agent may only read part of the chain.
Give long references a short contents list at the top so the agent can find the relevant section quickly.
Split by topic rather than writing one giant file, so the agent can load only what it needs.

Templates

Templates are the simplest way to get consistent structure. Use headings for each section and short placeholder notes saying what goes there.

weekly-metrics/template.md

# Weekly metrics: <week starting date>

## Headline
<One sentence: the single most important change this week.>

## Totals
| Metric | This week | Last week | Change |
|---|---|---|---|
<one row per metric from the script output>

## Notable movements
<Two to four bullets. Explain likely causes only if the data supports them.>

## Watch next week
<One or two bullets.>

Scripts

Scripts are the most powerful addition. Language models are good at judgement and writing, but less reliable at exact, repetitive work such as arithmetic over many rows, strict format validation or transforming files. A script does that part perfectly every time, and because the agent only reads the output, a long script costs almost no context.

weekly-metrics/scripts/summarise_csv.py

"""Summarise a weekly metrics CSV.

Usage: python summarise_csv.py <file.csv>
Expects columns: metric, this_week, last_week
Prints JSON to stdout. Exits with code 1 and a clear message on bad input.
"""
import csv, json, sys

REQUIRED = {"metric", "this_week", "last_week"}

def main(path):
    with open(path, newline="", encoding="utf-8") as f:
        rows = list(csv.DictReader(f))
    if not rows:
        sys.exit("Error: the CSV is empty.")
    missing = REQUIRED - set(rows[0].keys())
    if missing:
        sys.exit(f"Error: missing columns: {', '.join(sorted(missing))}")
    out = []
    for r in rows:
        now, before = float(r["this_week"]), float(r["last_week"])
        change = None if before == 0 else round((now - before) / before * 100, 1)
        out.append({"metric": r["metric"], "this_week": now,
                    "last_week": before, "change_pct": change})
    print(json.dumps(out, indent=2))

if __name__ == "__main__":
    if len(sys.argv) != 2:
        sys.exit("Usage: python summarise_csv.py <file.csv>")
    main(sys.argv[1])

Writing scripts agents can use well

Put usage instructions at the top and in SKILL.md, with the exact command to run.
Fail loudly and clearly. A message like “missing columns: last_week” lets the agent fix the problem or tell the user.
Print structured output, such as JSON or a simple table, so it’s easy to read and quote.
Use the standard library or well-known, pinned dependencies, and say in SKILL.md what needs installing.
Keep each script to one job. Several small scripts are easier to review than one that does everything.
Say whether the agent should run the script or read it. Usually you want it run, not studied.

Scripts run with the agent’s permissions on the user’s machine or in a sandbox. Keep them local and predictable: no network calls unless the skill’s purpose requires them, no reading outside the working files, no deleting or overwriting without an explicit instruction. Never hard-code API keys; read them from environment variables and never print them.

Where the script runs

In Claude Code, scripts run on your machine through the agent’s normal shell tool, subject to its permission prompts. In the Claude apps and through the API, skills with scripts rely on a code execution environment, which is a sandbox with its own limits, and network access may be restricted. If your skill needs a particular package or network access, say so in SKILL.md and test it in each place you plan to use it.

PDF Reader and BuilderAgent skillA skill that leans on scripts for exact PDF handling.Agent skill · Apache-2.0

Build MCP Server GuideAgent skillA larger skill that uses reference files well.Agent skill · Apache-2.0 CClaude skill packaging guidePromptCheck your folder layout before you share it.In a pack

Key takeaways

Keep SKILL.md for what every run needs; move occasional detail into reference files.
Use templates for fixed structure and scripts for exact, repeatable steps.
Point to every file from SKILL.md with a path and a reason, one level deep.
Write scripts that are small, clear, local and loud about errors.

Put it into practice

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Written by the AI Tool Garage editors. Tool details link to their catalogue pages, which are refreshed weekly; spotted something out of date? Tell us.