Skip to main content
Guide8 min read·Updated October 12, 2026
🧩

Claude Skill Folders: scripts/, references/, assets/ (2026)

B

A. Frans

Published October 12, 2026

Claude CodeAgent SkillsSKILL.mdSkill AuthoringProgressive Disclosure

A SKILL.md file can carry three optional folders: scripts/, references/ and assets/. Most first-time skill authors ignore all three and pour everything into one long Markdown file. That works until the file passes a few hundred lines, Claude starts skimming it, and the same 40-line helper function gets rewritten from scratch every time the skill runs.

Each folder solves a different problem. Scripts hold code Claude should run, not rewrite. References hold knowledge Claude only needs sometimes. Assets hold files that end up in the output. Putting content in the right one makes a skill cheaper to run and more consistent in what it produces.

The anatomy, at a glance

Anthropic's Skill Creator lays out the structure like this:

my-skill/
├── SKILL.md          (required: frontmatter + instructions)
├── scripts/          (executable code for deterministic or repetitive tasks)
├── references/       (docs loaded into context as needed)
└── assets/           (files used in output: templates, icons, fonts)
FolderWhat goes in itDoes Claude read it into context?Use it when
scripts/Python, bash, Node filesNo, only the script's outputThe task has one right way to do it
references/Extra .md docs, schemas, API notesYes, when the skill points it thereThe knowledge is only needed for some requests
assets/Templates, logos, fonts, HTML shellsUsually no, it copies or fills themThe file appears in the final output
That middle column is the whole economic argument. A 300-line Python script in scripts/ costs nothing in context when Claude runs it. The same logic written out as instructions in SKILL.md costs tokens every single time the skill fires, and Claude still has to regenerate the code.

scripts/: code Claude should run, not reinvent

The clearest signal you need a script comes from watching Claude use your skill. Skill Creator's own guide describes it: if every test run ends with Claude writing a similar create_docx.py or build_chart.py, the skill should bundle that script once and tell Claude to use it.

Good candidates for scripts/:

  • File format work with fiddly rules: filling PDF forms, writing Excel formulas, parsing a proprietary export.
  • Validation: "check that this JSON matches our schema" should be a script that exits non-zero, not a paragraph Claude interprets.
  • Anything where two runs must produce identical results.

Here's a minimal example. A skill that turns a CSV of expenses into a monthly summary:

expense-report/
├── SKILL.md
└── scripts/
    └── summarize.py
---
name: expense-report
description: Summarize an expenses CSV into monthly totals by category. Use when the user shares an expenses or transactions CSV and asks for a summary, report or breakdown.
---

# Expense report

1. Run `python scripts/summarize.py <path-to-csv>`.
2. The script prints a Markdown table of totals per month and category.
3. Show the table, then point out the two largest categories and any month
   that's more than 25% above the average.

Don't recalculate the totals yourself. If the script errors, show the error
and ask the user about the CSV's column names.

Notice what the instructions don't contain: the parsing logic. Claude handles the judgment ("point out the two largest categories"), and the script handles the arithmetic. That split is the pattern worth copying.

Two rules for scripts. First, make errors loud and specific, because Claude reads the output and decides what to do next. "Column 'amount' not found; columns are: date, desc, value" lets Claude recover. A Python traceback through pandas internals doesn't. Second, keep dependencies minimal and document them in SKILL.md, since the user's machine may not have them. If you're publishing for Windows users too, our Windows skills guide covers the python vs python3 and encoding issues that break scripts there.

Scripts are also where security risk lives. A Markdown instruction can't delete your files by itself; a script can. When you install someone else's skill, read every file in scripts/ before the first run. Our audit checklist walks through it.

references/: knowledge for some requests, not all

SKILL.md loads every time the skill triggers. Skill Creator recommends keeping it under 500 lines, and the shorter it is, the more of it Claude follows. Anything that's only relevant to some requests belongs in references/.

The best use is splitting by variant. Skill Creator's example is a deploy skill:

cloud-deploy/
├── SKILL.md
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md

SKILL.md holds the shared workflow and a line like "For AWS deployments, read references/aws.md." A user deploying to GCP never pays for the AWS details.

Other good fits: a full API reference when SKILL.md only needs the five common calls, a style guide with 200 examples, a JSON schema, a glossary of company terms.

Three habits keep references working:

1. Link each reference directly from SKILL.md and say when to read it. A reference file that's only mentioned inside another reference file may be skimmed rather than read. 2. Give long references (300+ lines) a table of contents at the top so Claude can jump to the relevant section. 3. Name files for what's in them. references/stripe-webhooks.md beats references/notes2.md, because Claude decides what to open partly from the filename.

We explain the loading mechanics in more depth in how Claude Code skills load.

assets/: files that end up in the output

Assets aren't instructions and aren't code. They're raw material: a branded PowerPoint template, a logo PNG, a font, an HTML shell with your CSS already in it, a boilerplate README that every new project starts from.

The instruction pattern is "copy, then fill":

To create the weekly report, copy `assets/report-template.docx` to the
output folder, then fill the sections marked {{SUMMARY}} and {{METRICS}}.
Don't change the styles or the header.

Without the asset, Claude would build the document from scratch each time, and the fonts, margins and logo placement would drift between runs. With it, every report starts from the same file. Anthropic's document skills for Word, PowerPoint and Excel are worth studying here, since consistent output formatting is the whole job.

Keep assets small where you can. A skill that ships a 40 MB video in assets/ is painful to clone and share with a team.

What stays in SKILL.md

After moving code to scripts, optional knowledge to references and templates to assets, SKILL.md should contain:

  • Frontmatter with a name and a description that says what the skill does and when to use it. That description is how Claude decides to trigger the skill at all. See the frontmatter fields explained.
  • The workflow: the steps, in order, in plain language.
  • The judgment calls: what to do when the script fails, what to check before showing results, what the user usually cares about.
  • Pointers: which script to run for what, which reference to read when.

If a section of SKILL.md is a block of code you expect Claude to type out, it belongs in scripts/. If it's a long table Claude only needs for one case in five, it belongs in references/.

A before-and-after

Picture a skill that generates title cards for videos. The overgrown version keeps the full Python drawing code in SKILL.md as a code block, spells out every color value, font size and pixel offset in prose, and ends with a long troubleshooting section.

Here's where each piece moves:

ContentBeforeAfter
Drawing codeCode block in SKILL.mdscripts/make_card.py
Colors, fonts, sizesProse in SKILL.mdConstants inside the script
Font fileFetched or guessed each runassets/
TroubleshootingBottom of SKILL.mdreferences/troubleshooting.md
What's left in SKILL.mdEverythingWorkflow, judgment calls, pointers
The bigger gain isn't tokens. In the first version, Claude retypes the drawing code from the instructions on every run, and any retyped value can drift, so two cards from the same session might not match. In the second, every card comes out of the same script.

Common mistakes

Bundling a script and then explaining its internals in SKILL.md. Claude doesn't need to know how summarize.py works, only what it takes and what it returns.

Using references/ for content every request needs. If Claude has to read it every time, it's part of the instructions; put it back in SKILL.md.

Hard-coding absolute paths. A script that reads /Users/alex/data breaks for everyone else. Use paths relative to the skill folder or take them as arguments.

Forgetting to test from a fresh session. Skills often work in the session where you wrote them because Claude still remembers the context. Start a new session and run the skill cold. If you're stuck, our field guide to debugging custom skills covers the common failure patterns.

Install a reference example

The fastest way to learn the layout is to read a skill that uses all three folders. Skill Creator does. The copy we have installed ships scripts/ (eval and packaging tools), references/ (a schema doc) and assets/ (an HTML review template). Clone Anthropic's skills repo and look:

git clone https://github.com/anthropics/skills.git
ls skills/skills/skill-creator

To install it, copy that folder to ~/.claude/skills/skill-creator/ and start a new Claude Code session. Then ask it to help you restructure your own skill, and it'll suggest the same split described here. Developers building skills for a team can find more tooling on our full list for developers.

FAQ

What is the scripts folder in a Claude skill for?

It holds executable code (Python, bash, Node) that Claude runs instead of writing the logic itself. Only the script's output enters Claude's context, so large scripts don't cost tokens, and every run produces consistent results.

What's the difference between references and assets in a skill?

References are documents Claude reads when it needs the knowledge, such as an API guide or style rules. Assets are files used in the output, such as templates, logos or fonts, which Claude copies or fills rather than reads.

How long should SKILL.md be?

Anthropic's Skill Creator recommends keeping it under 500 lines. Move code into scripts/ and request-specific material into references/, and link each file from SKILL.md with a note on when to use it.

Are scripts in skills safe?

Only as safe as the code itself. A script can do anything your user account can do, so read every file in a third-party skill's scripts/ folder before running it, and prefer skills from authors you can identify.

Do I need all three folders?

No. All three are optional. Many good skills are a single SKILL.md. Add a folder when you hit the problem it solves: repeated code, an overlong SKILL.md, or output that drifts between runs.

Share this article

📬

Get More AI Tool Guides

New comparisons and guides every week. Join thousands of professionals staying ahead of the AI curve.