Skills for AI Agents

Chapter 2. Skills: Designing for the Context Window

A Note for Early Release Readers

With Early Release ebooks, you get books in their earliest form—the author’s raw and unedited content as they write—so you can take advantage of these technologies long before the official release of these titles.

This will be the 2nd chapter of the final book. Please note that the GitHub repo will be made active later on.

If you’d like to be actively involved in reviewing and commenting on this draft, please reach out to the editor at [e-mail].

The reason skills work is not that the SKILL.md file is made of magic, but because it’s the first agent-native form factor designed from the ground up to operate within the constraints of an agent.

In this chapter, I’ll walk you through the anatomy of a skill, starting with the all-important SKILL.md file — the instructional heart of a skill. From there, you’ll examine the core constraint of the context window and how progressive disclosure allows you to scale expertise without flooding the agent with unnecessary details. Beyond the primary instructions, you’ll look at optional scaffolding, exploring how expertise is further packaged into specialized subfolders. Finally, you’ll look at the hidden tax of context, understanding that there can be too much of a good thing.

The Anatomy of a Skill: Packaging Expertise

At its core, a skill is a folder that contains a SKILL.md and three optional folders:

scripts/ for executable code (Python, Bash, ...