🪜 The 3 loading levels
The secret of skills is progressive disclosure: information is revealed in layers, as the agent needs it. Instead of putting everything into the context at once, the skill exposes only the metadata first, then the body, and finally the heavy resources.
The core idea
The higher the level, the less context it costs and the more often it loads. The lower the level, the more content it can hold—but it only comes in when truly needed. That’s what lets huge skills work without wasting context.
① Level 1 — metadata
Level 1 is just the name + description — about 100 words that remain ALWAYS in context from the agent, along with the metadata for all the other installed skills. It's the showcase: the agent uses it to decide whether it's worth loading the rest.
What stays loaded all the time (Level 1):
name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill...
💡 Tip
Because Level 1 is always on, every word costs context multiplied across ALL skills. Keep it to ~100 words: descriptive enough to trigger, concise enough to stay lightweight.
② Level 2 — SKILL.md body
When the description matches the situation, the agent loads the SKILL.md body — the complete instructions. The canonical recommendation is to keep the body under 500 lines. It only enters the context when triggered, not before.
The description triggers
The agent recognizes that the current situation fits Level 1.
The body is loaded
The Markdown instructions enter the context and start guiding the response.
The agent acts
Follow the body and, if needed, fetch Level 3 resources.
Why <500 lines
Long bodies dilute the agent’s attention and waste context every time they trigger. If the content grows too large, move details to references/ (Level 3) and keep the body to essentials and pointers.
③ Level 3 — bundled resources
Level 3 consists of bundled resources: files in scripts/, references/ e assets/. Size unlimited, loaded on demand. The powerful detail: scripts run without loading the code into context — the agent receives only the result.
✗ Everything in the body
- ✗Huge tables and entire docs in SKILL.md
- ✗Code pasted into Markdown for the agent to “read and run mentally”
- ✗Context overflow with every trigger
✓ Level 3 resources
- ✓Long docs in references/, read only when needed
- ✓Scripts in scripts/ that actually run, without taking up context
- ✓Lean body that points to the resources
In the body, point to the resource (don’t paste its contents):
Para converter o arquivo, execute: python scripts/convert.py <input> Detalhes de configuração estão em references/config.md — leia se necessário.
💡 Tip
Whenever a task is deterministic (same input → same output), prefer a Level 3 script over instructions in the body. It’s more reliable, cheaper, and the code doesn’t even need to enter the context.
🎯 Writing a description that triggers
Here’s the subtlest point in the entire anatomy: Claude tends to UNDERTRIGGER skills. By default, it’s conservative and won’t activate when in doubt. The fix is to write a slightly more "pushy" — be assertive in the triggers, making it clear when to use it.
✗ Timid (under-triggers)
"Can help with tests."
"Can" and no trigger. The agent will rarely activate.
✓ Pushy (fires)
"Writes and reviews tests. ALWAYS use when the user asks for tests, mentions TDD, coverage, or a bug to reproduce."
What + when + explicit triggers.
The description formula that triggers it:
description: [WHAT it does] + [WHEN to use it — "Use this skill when..."] + [CONCRETE TRIGGERS — examples, keywords]
Calibrate with near misses
To fine-tune, think of queries that should trigger and on near-misses that no should. If the skill ignores obvious cases, make it more pushy; if it triggers in the wrong situations, narrow the triggers. This fine-tuning is at the heart of the Trilha 4 creation loop.
🗂️ Organization by Domain
When a skill covers multiple domains, split the references by file — references/aws.md, gcp.md, azure.md — for the agent to read only what's relevant. And in any file with more than 300 lines, add a table of contents at the top.
References split by domain:
references/ ├── aws.md # só lido em tarefas AWS ├── gcp.md # só lido em tarefas GCP └── azure.md # só lido em tarefas Azure
Table of contents at the top of a file >300 lines:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc)
Why this saves context
- •A single 900-line file forces the agent to load everything. Three 300-line files let it pick just one.
- •The table of contents lets the agent navigate to the right section without rereading the entire file.
- •Separate domains also make maintenance easier: you can edit azure.md without touching the rest.
💡 Final tip
The three levels + organization by domain form a system: a pushy description at Level 1 to trigger it, a lean body at Level 2, and resources split by domain at Level 3. This is how skills like azure-ai (358k installs) scale without losing precision.
✅ Module Summary
Next:
Module 3.3 — ⭐ Best Structures to Imitate: dissect the SKILL.md files of top-performing skills and see what to copy from each one.