Folder Layout and Loading Rules

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.

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.

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.

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

Quick check: How does Claude know when to open a reference file?

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