Design discovery and activation
Understand progressive disclosure
Structure a skill so agents discover a small description first and load detailed instructions and resources only when needed.
10 minute lesson
An agent may have access to many skills. Loading every instruction file at startup would waste context and make unrelated rules compete for attention.
Agent Skills use progressive disclosure. The agent first sees the skill name and description. If the current task matches, it loads the complete SKILL.md. Scripts, references, and assets stay on disk until the instructions tell the agent to use them.
This changes how you write. The description must carry enough signal for discovery. The main file must contain the procedure and critical gotchas needed on every run. A detailed command matrix can live in references/checks.md. A reusable report can live in assets/report-template.md. A deterministic validator can live in scripts/validate-report.mjs.
The portable structure is small:
release-readiness/
├── SKILL.md
├── scripts/
├── references/
└── assets/Do not create empty folders to make the skill look complete. Every file must earn its context and maintenance cost.
Sketch the final release-readiness tree. Beside each file, write when the agent should load or run it. If your answer is “always,” consider whether that content belongs in SKILL.md. If your answer is “never clearly,” remove the file.
Lesson completed