Directory structure¶

As your skill grows, you can bundle additional content into separate files, which your Coding Agent will only load when necessary. For example, if you specify in your SKILLS.md file that the description for email validation is located in ./email-validation.md, then this will only be taken into account in that context.

The complete directory structure might then look like this:

rest-api/
├── SKILL.md               # Main instructions, loaded when triggered
├── email-validation.md    # Only loaded for Email validation
├── reference.md           # API reference (loaded as needed)
└── scripts/
    ├── utility.py         # Utility script (executed, not loaded)
    └── validate_email.py  # Validation script

Warning

Deeply nested references should be avoided, as they may not be read in at all, or only partially, when required.

Reference files

For reference files longer than 100 lines, include a table of contents at the top. This ensures that your coding agent can recognise the full scope of the available information, for example:

# API Reference

## Contents
- Setup
- Authentication
- Core methods (create, read, update, delete)
- Error handling

## Setup
…

## Authentication
…

scripts

When writing scripts for skills, handle their error states yourself and do not pass them on to your coding agents.