Module 4 · Skills

Dynamic Context

This is the idea that lets a skill carry hundreds of pages of reference material while costing almost nothing until the moment it's used.

8 min read

Lesson 4.1

The three tiers

Remember the budget from Module 1. Dynamic Context is how a skill keeps it as lean as possible, loading in three tiers, each only when the previous one proves relevant.

Dynamic Context
context window ~0.3k tokens

  1. Skill Names and Definitions

    At startup, only the name and description enter context. Across a hundred skills, that's a tiny, fixed cost. It's just enough for the agent to know what exists.

  2. The body: loaded when relevant

    When the description matches the task, the agent reads the entire SKILL.md in the skills folder.

  3. Bundled files: loaded on demand

    References, examples, and scripts the SKILL.md body points to are opened (or executed) only when the specific step needs them. A 40-page API reference costs nothing until the one moment it's consulted.

Tier 1 · metadata: every skill

design-guide: Apply the house visual system…

pdf-tools: Fill & extract PDF form fields…

git-workflow: Branch, commit, PR for a story…

test-data: Seed an org with sample records…

+ 96 more · name + description only

Tier 2 · design-guide/SKILL.md: body
# Design Guide 1. Establish the layout grid. 2. Pull colors from templates/template-1.md. 3. Compose from templates/template-2.md. 4. Run scripts/check_contrast.sh.
Tier 3 · templates/template-1.md: opened on demand
--bg #ffffff --text #1d1d1f --accent #bf5a3c …40 pages of tokens & components
The consequence

Keep the SKILL.md body short (think a few hundred lines at most) and push additional information into files it can reach for based on the task it is trying to perform. The body stays in context once loaded, so every line there is a recurring cost; a reference file is a one-time cost paid only if it's opened.

Lesson 4.2

Structure of the skill folder

Our design-guide skill is growing. It now needs a set of templates to reference and a component catalog, dozens of lines each. Inlining them would bloat every turn. Instead, we split:

design-guide/
├── SKILL.md
├── templates/
│   ├── template-1.md
│   └── template-2.md
└── scripts/
    └── check_contrast.sh

↑ Tap the numbered lines.

1
The skill folder, still one self-contained unit you can drop anywhere.
2
The body stays lean. It describes the workflow and points to the detail files rather than containing them.
3
templates/ holds Tier-3 knowledge: the token values and component catalog. Keep templates one level deep: deeply nested files get skimmed or missed.
4
scripts/ holds runnable helpers. A script is executed, so it costs only its output, not its source, in context.

The body then references those files with intent that tells the agent how to use each one:

# in the body...
2. Pull colors and spacing from templates/template-1.md.
3. Compose from the catalog in templates/template-2.md.
4. Run scripts/check_contrast.sh to flag any AA failures.

Check

Check your understanding

At startup, before any task is chosen, what has the agent loaded from a skill?

Why is a 900-line SKILL.md body a problem even if it's all accurate?

Takeaways

1. Three tiers: Skill Name and Description (always) → Skill Body (when relevant) → bundled files (on demand).
2. Keep the body short; push depth into sub folders like templates/ and scripts/.

Tiers make sense?

Next: make sure the agent actually reaches for your skill.