# Loading and Context Cost

Course: [Agent Skills](https://www.devtutorials.ai/learn/agent-skills) · Section: Skill Runtime
Source: https://www.devtutorials.ai/learn/agent-skills/runtime/progressive-disclosure

> How agents load skills in three levels (catalog, one SKILL.md body, extra files on demand), and how to keep each level small: short descriptions, a minimum reliable workflow, and pointers to files.

## The Agent Reads Only What It Needs

**Progressive disclosure** = loading skill information a little at a time, only when it is needed. In this lesson, you will learn the three loading levels. You will also learn to keep each level small.

Your team may install many skills.

But the agent does not read them all at once.

It reads in three levels:

- **Catalog:** one short line per skill, always.
- **SKILL.md body:** one skill, when a request matches it.
- **Extra files:** one file, when a step points to it.

Every token the agent reads costs time and money.

It also takes space away from your own code.

### What Is the Context Window?

**Context window** = the agent's working memory for one chat.

- Everything the agent reads goes into it: your request, your code, chat history and skills.
- It has a fixed size, measured in **tokens** (small pieces of words).
- When it fills up, the agent starts to forget earlier details, or gets slower and costs more.

That is why token counts matter in this lesson. Every skill line you load takes a seat that your code could use.

**Simple lesson:** load only what this request needs.

### A Real-World Example

You pack a day bag for a hike.

- Water, a map and a jacket go in the bag. You need them every time.
- The tent and the stove stay in the car. You get them only if you stay the night.

A skill works the same way. SKILL.md is the day bag. Extra files wait in the car.

Click the button and open the **Activation** tab.

- **Show the catalog text:** this short list is all the agent knows at start-up.
- **Disclosure meter:** it shows the tokens loaded right now.

**Simple lesson:** until a skill fires, the agent knows only its name and description.

## What You Will Learn

In this lesson, you will learn:

1. The three loading levels.
2. Why the catalog must stay short.
3. What belongs in SKILL.md, and what does not.
4. How extra files load only when a step needs them.
5. How to slim a skill that is too big.
6. How to check what the agent loaded.

**About this lesson's Skill Lab**

- The **Activation** tab has a disclosure meter.
- The **Library** tab shows about how many tokens the open file costs.
- Later, you will slim the `api-doc-reviewer` skill in the Library.

## Three Levels of Loading

| Level | What loads | When | Typical size |
| --- | --- | --- | --- |
| **1. Catalog** | `name` and `description` of every skill | Always, in every chat | 20 to 100 tokens per skill |
| **2. SKILL.md body** | The steps of one skill | When the skill fires | A few hundred tokens |
| **3. Extra files** | Files in `references/`, `templates/`, `examples/`, and script output | When a step points to them | Any size |

Watch one morning of work. Look at what each request adds:

Three requests, and only two skill bodies loaded. The other skills stayed closed.

**Simple lesson:** each level is bigger, but used less often.

## Level 1: Keep the Catalog Short

The catalog loads in **every** chat.

That is true even when no skill is used.

So every word in every description is paid for again and again.

Watch the catalog grow:

Long descriptions made the catalog bigger in every chat. Nothing else changed.

**Important:**

- Keep each description to one or two sentences.
- Say what the skill does, and when to use it.
- Put the details in the body. The body loads only when needed.

**Simple lesson:** a short description is cheap, and easier to match.

## Level 2: Keep the Body to the Minimum

When a skill fires, its whole SKILL.md body loads.

It stays in the chat for the rest of the task.

So the body should hold the **minimum reliable workflow**.

**Minimum reliable workflow** = the smallest set of steps that gives a correct result every time.

Test each line with one question: "If this line were missing, would a normal request go wrong?"

Keep in SKILL.md:

- **When to use** and **Do not use**.
- The **Inputs** to gather.
- The numbered **Workflow** steps.
- The **Output format**.
- The **Final checks**.
- **Pointers** to extra files.

Move out or delete:

- Long guides and tables used in one step: move to `references/`.
- Exact yes or no rules: move to a script in `scripts/`.
- Long sample inputs and outputs: move to `examples/`.
- History, background and "please be careful": delete.

Watch a bloated skill get slimmed:

The rules were not deleted. They moved to a file that loads only in step 2.

Click the button and open the **Library** tab.

- **Token count:** look under the editor before you change anything.
- **Your fix:** delete the background, and move the rules to `references/style-guide.md`.
- **Check:** press **Save**, and see the count drop.

**Simple lesson:** if a line is not needed every time, it does not belong in SKILL.md.

## Level 3: Open Files Only When Needed

Files in `references/`, `templates/` and `examples/` do not load when a skill fires.

The agent opens a file only when a step tells it to.

So the body works like a map.

Example:

- "For wording, follow references/style-guide.md."
- "Before publishing, run scripts/check_notes.py."

If the task is small, the agent may never reach those steps. Then those files never load.

**Scripts are the cheapest resource**

- The script's code never enters the chat.
- Only its output does, often one short line like "OK".
- So move exact checks into scripts when you can.

### Write Pointers That Say When

A pointer must say **which file**, and **when** to use it.

Weak pointers:

- "See references/ for more info."
- "There is a script."

Strong pointers:

- "For wording rules, follow references/style-guide.md."
- "Before replying, run scripts/check_notes.py. Fix anything it reports."

Click the button and open the **Activation** tab.

- **Tick a file** in the disclosure meter.
- **Loaded now:** the total goes up only for the files you tick.
- **Paste everything:** compare it with the cost of loading every skill.

**Simple lesson:** a file with no pointer is never opened.

**A big body skips level 3**

- A SKILL.md that pastes a 300-line guide loads it every time.
- Even a two-line change pays for all of it.
- Long text can also push your real code out of focus.

## Check What Was Loaded

When a skill acts strangely, first check what loaded.

Ways to check:

- **Ask the agent:** "Which skills did you use? Which files did you open?"
- **Use the skill list:** many tools have a command like `/skills`.
- **Read the log:** some tools show each file read and each script run.

What it tells you:

- The skill never loaded: the problem is the description or the folder.
- The skill loaded, but a file did not: the pointer is missing or unclear.

**Simple lesson:** check what loaded before you change anything.

## Common Mistakes

| Mistake | Wrong idea | Correct idea | What goes wrong |
| --- | --- | --- | --- |
| Long descriptions | More words help the agent choose | One or two clear sentences | The catalog costs more in every chat |
| Everything in SKILL.md | Safer to paste the whole guide | Move it to `references/` with a pointer | Every run pays for text it rarely needs |
| Keeping background stories | History helps the agent | Delete lines that change nothing | Wasted tokens, weaker focus |
| Files with no pointer | The agent will find the file | Name the file in a step | The file is never opened |
| Pointers without "when" | "See references/" is enough | Say which file, and when | The agent opens it too often, or never |
| Slimming by deleting rules | Shorter is always better | Move rules, do not lose them | The skill misses checks it needed |
| Scripts with long output | Print everything | Print a short result, like "OK" | The output fills the chat |

## Check Your Understanding

## Exercises

## What to Remember

- **Context window** = the agent's working memory for one chat. Everything loaded shares it.
- Skills load in three levels: **catalog**, **SKILL.md body**, **extra files**.
- The **catalog** loads in every chat. Keep descriptions short.
- The **body** loads when a skill fires. Keep only the minimum reliable workflow.
- **Extra files** load only when a step points to them. Say which file, and when.
- **Scripts** cost only their output. Use them for exact checks.
- Slim a skill by moving text out, not by losing rules.
- Check **what loaded** before you change anything.

Next: **Activation and Descriptions**. You will see how the agent picks a skill, and how to call one by name.