ai-agents-skill-organization-when-organizing-a-skill-that-exceeds-500-lines-or--e8993cc3

THEN Use progressive disclosure: keep SKILL.md under 500 lines. If approaching the limit, add hierarchy with clear pointers. Reference large files from SKILL.md with guidance on when to read them. For large reference files (>300 lines), include a table of contents. For multi‑domain skills, organize by variant with a selection workflow in SKILL.md and separate reference files (e.g., cloud-deploy/references/aws.md, gcp.md, azure.md). Claude reads only the relevant reference file.

```
cloud-deploy/
├── SKILL.md (workflow + selection)
└── references/
    ├── aws.md
    ├── gcp.md
    └── azure.md
```