---
title: "Keep the skill file short and put fixed · Agent Wranglers"
url: https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-scripts
updated: 2026-10-21
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Keep the skill file short and put fixed steps in scripts

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers). Updated 2026-10-21.

For AI agents: [llms.txt](https://agentwranglers.se/llms.txt) is a short guide that sends you to the rules your problem needs, and [rules.json](https://agentwranglers.se/playbook/ai-assisted-development/rules.json) holds every rule of this playbook as JSON.

- Level: Recommended
- Chapter: [Agent skills](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills)
- Rule: Keep each `SKILL.md` under 500 lines. Move every step that needs no judgement into a script the skill runs, and long reference text into files it links.
- How: 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](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills) says.
- 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.

## 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

```markdown
## 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

```js
// 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

```python
# 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"]}')
```

## Sources

- [Agent Skills specification](https://agentskills.io/specification)
- [Claude Code skills](https://code.claude.com/docs/en/skills)

## Related rules

- [Test each skill and keep it current](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/test-and-maintain-skills) in AI development

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-scripts">Agent Wranglers AI development playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Write a description that says when to use the skill](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/skill-description)
- Next: [Keep project skills in the repository and review them like code](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills/project-skills-in-repo)
- [Agent skills](https://agentwranglers.se/playbook/ai-assisted-development/agent-skills)