How I structure agent skill folders

When I first started building agent skills, everything lived in a single SKILL.md file. That works fine for simple ones. But once a skill handles a multi-step process, a single file turns into a wall of text that's hard to maintain and hard for the agent to parse efficiently.

Here's the folder structure I've settled on for any skill with real complexity:

my-skill/
  SKILL.md
  steps/
    step-1-do-the-thing.md
    step-2-do-the-next-thing.md
  references/
    credentials.md
    voice-training.md
    examples.md
  scripts/
    deploy.py
    sync.sh

SKILL.md is the index. It describes what the skill does, lists the steps in order, and points to each step file. The agent reads this first to understand the full process, then reads each step file as it gets there.

steps/ holds one markdown file per step. Each file contains the complete instructions for that part of the process — what to do, what API calls to make, what to watch for. The agent reads each step file only when it reaches that step, so it doesn't need the whole pipeline in context at once.

references/ holds supporting material the skill needs — API credentials, voice training docs, example files, brand guidelines. These get read when a step references them, not upfront.

scripts/ holds any code the agent might need to execute — Python scripts, shell scripts, utilities. Some skills don't need this at all.

The payoff is the same as modular code. I can reorder steps, skip steps, run a single step in isolation, or add new steps without touching anything else. When something breaks, I know exactly which file to open. And the agent doesn't carry the entire process in its context window — it reads what it needs when it needs it.

If your skill file is getting long and unwieldy, that's the signal. Break it up.

Keep building,