Keep the skill file short and put fixed steps in scripts

How to do it

The full SKILL.md loads into context when the skill runs, while scripts run without being read. Both the Agent Skills format and Claude Code advise under 500 lines. A script gives the same answer every time, costs no tokens and can be tested. Put scripts in scripts/ and reference text in references/, linked one level deep. Have each script print a short result the agent can act on, and exit non-zero on failure. The skill then holds the judgement, such as which findings matter and what to fix first. Give those scripts tests, as Test each skill and keep it current says.

Examples

Using these examples: they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

Markdown example

## 1. Find the slow pages
Run `node scripts/slow-pages.mjs --top 10`. It prints one page per line with its load time.

## 2. Decide what to fix
Read each page. Fix the largest image or script first. Skip pages that are slow only on the first visit.

JavaScript example

// scripts/slow-pages.mjs
const top = Number(process.argv[process.argv.indexOf('--top') + 1] || 10);
const rows = await (await fetch('https://example.com/metrics/pages.json')).json();
for (const page of rows.sort((a, b) => b.loadMs - a.loadMs).slice(0, top)) console.log(`${page.loadMs} ms ${page.url}`);

Python example

# scripts/slow_pages.py, the same step for a Python project
import json, sys, urllib.request
top = int(sys.argv[sys.argv.index("--top") + 1]) if "--top" in sys.argv else 10
rows = json.load(urllib.request.urlopen("https://example.com/metrics/pages.json"))
for page in sorted(rows, key=lambda r: r["loadMs"], reverse=True)[:top]:
    print(f'{page["loadMs"]} ms {page["url"]}')

How to check

A script fails when a SKILL.md has 500 lines or more. Each command the skill runs has a test or a dry run that passes in CI.

Sources

• Agent Skills specification
• Claude Code skills

Related rules

• Test each skill and keep it current in AI development