# Folder Layout and Loading Rules — Claude Code Skills & SKILL.md

Source: https://www.geekswithgeeks.com/en/claude-code-skills/f-layout

> Organise supporting files so they load only when needed.

## Point to files from SKILL.md

A common layout is: `SKILL.md` (the entry point), `scripts/` (executable helpers), `references/` (longer documentation, schemas, style guides), and `templates/` or `assets/` (output templates, boilerplate, images). The key rule: **Claude only opens a file if SKILL.md tells it to** or the task obviously needs it, so reference every supporting file **by relative path and say when to read it** ("For the API error codes, read `references/errors.md`. Only read it if a request fails."). Keep references **one level deep** (SKILL.md links straight to each file) so nothing is hidden behind a chain of links, give long reference files a **table of contents** at the top, and avoid duplicating the same facts in several places. Use forward slashes in paths and names that say what the file contains.

## The folder around SKILL.md

Scripts do exact work, references hold detail, templates fix the output shape, and SKILL.md ties them together.

![Four kinds of files: script, reference, template, asset.](assets/figures/claude-code-skills/section-3-map.svg) — Figure 3.1 — Script, reference, template and asset.

## A skill folder as a tree, run

I ran this with plain Python 3 (standard library only). The script builds a sample skill folder in a temporary directory and prints it: `SKILL.md` at the top, then `references/`, `scripts/` and `templates/` with one file each.

```python
import os, tempfile

LAYOUT = {
    "release-notes/SKILL.md": "---\nname: release-notes\ndescription: Draft release notes. Use when asked for a changelog.\n---\n# release-notes\n",
    "release-notes/scripts/prs_since_tag.py": "print('...')\n",
    "release-notes/references/style-guide.md": "# Style guide\n",
    "release-notes/templates/notes.md": "## {version}\n",
}
def tree(root):
    out = []
    for dirpath, dirs, files in sorted(os.walk(root)):
        dirs.sort()
        depth = os.path.relpath(dirpath, root).count(os.sep) if dirpath != root else -1
        if dirpath != root: out.append("  " * depth + os.path.basename(dirpath) + "/")
        for f in sorted(files): out.append("  " * (depth + 1) + f)
    return "\n".join(out)

with tempfile.TemporaryDirectory() as root:
    for rel, text in LAYOUT.items():
        path = os.path.join(root, rel); os.makedirs(os.path.dirname(path), exist_ok=True)
        open(path, "w").write(text)
    print(tree(root))

```

Output:

```
release-notes/
  SKILL.md
  references/
    style-guide.md
  scripts/
    prs_since_tag.py
  templates/
    notes.md
```

## Referencing files from SKILL.md

Say exactly when each file is needed so it is loaded only then. Illustrative; not run here.

```markdown
## Files
- To list merged PRs, run `python scripts/prs_since_tag.py` (prints JSON).
- For wording rules, read `references/style-guide.md` before writing entries.
- Fill in `templates/notes.md` for the final output.
- If the GitHub CLI fails with an auth error, read `references/troubleshooting.md`.
```

## One level deep

Link every supporting file directly from SKILL.md instead of from other reference files.

**Quiz:** How does Claude know when to open a reference file?

- [ ] Files open themselves
- [ ] It always opens every file
- [x] SKILL.md tells it which file to read and when
- [ ] It never opens extra files

*Answer:* SKILL.md tells it which file to read and when. Clear pointers make progressive disclosure work.