Skip to content

Agent Skills

Skills are reusable instruction packages that extend an agent's capabilities without permanently consuming context. Skills solve a fundamental tension in agent design: agents need access to detailed domain knowledge, but context windows have finite capacity.

Context Window Limits

An agent with access to fifty specialized workflows faces a choice:

  1. Load everything upfront. This consumes most of the context window before the user asks anything.
  2. Load nothing, requiring users to explicitly request capabilities. This loses the benefit of agent autonomy.
  3. Load selectively based on demonstrated need.

Skills implement the third approach through progressive disclosure.

Progressive Disclosure

Progressive disclosure is an information architecture pattern where content is revealed in layers based on need. In skills, this means three distinct levels:

Level 1: Metadata (~100 tokens)
    ↓ Agent decides relevance
Level 2: Main Instructions (~3-5K tokens)
    ↓ Task requires specialization
Level 3: Supporting Resources (unlimited)

At system startup, only skill metadata loads - a name and description for each skill. When the agent determines a skill is relevant to the current task, it reads the main instructions. If those instructions reference specialized documentation or scripts, the agent loads them on demand.

This creates an economic model where:

  • Base cost stays constant regardless of how many skills exist (startup scales with metadata only)
  • Active cost is proportional to need. Complex tasks load more resources; simple tasks stay lean.
  • Maximum capability is unbounded since the filesystem acts as an extension of context

Skills vs Commands

Both skills and commands package instructions, but they differ in invocation:

Aspect Skills Commands
Invocation Agent-initiated based on context User-initiated via slash syntax
Discovery Agent scans metadata automatically User must know command exists
Timing Loaded when agent deems relevant Loaded when user requests

A skill activates when the agent recognizes its description matches the current task. A command activates when the user types /command-name. The same underlying instruction package can serve both purposes.

Filesystem as Memory

Without skills, the context window is the boundary of agent knowledge. Skills treat it as working memory backed by persistent storage.

When an agent encounters a task requiring specialized knowledge:

  1. It recognizes the need from skill metadata (already in context)
  2. It reads the relevant SKILL.md from the filesystem
  3. If deeper detail is needed, it reads supporting files
  4. If code execution is needed, it runs scripts and receives only the output

The filesystem becomes navigable documentation. The agent starts with an index, drills into relevant sections, and executes tools as needed.

Information Flow

┌─────────────────────────────────────┐
│         User Query                   │
└──────────────┬──────────────────────┘
               ↓
┌─────────────────────────────────────┐
│  System Prompt + Skill Metadata      │
│  (Always loaded, ~100 tokens/skill)  │
└──────────────┬──────────────────────┘
               ↓
        Agent evaluates relevance
               ↓
┌─────────────────────────────────────┐
│  Load SKILL.md                       │
│  (On-demand, ~3-5K tokens)           │
└──────────────┬──────────────────────┘
               ↓
        Task needs specialization?
               ↓
┌─────────────────────────────────────┐
│  Load Supporting Files / Run Scripts │
│  (On-demand, variable size)          │
└─────────────────────────────────────┘

Scaling Benefits

Without progressive disclosure, skill systems face scaling limits. Ten skills might fit comfortably in context; fifty would crowd out the actual task. With progressive disclosure, the number of available skills becomes a metadata indexing problem rather than a context capacity problem.

This enables:

  • Specialization without bloat. Deep expertise stays available without constant overhead.
  • Autonomous capability selection, where the agent chooses relevant skills without user direction
  • Composable knowledge (skills can reference other skills or shared resources)
  • Maintainable organization since each skill is a self-contained unit

Further Reading

External Resources