Chapter 2: Agent Skill (Progressive Disclosure)

In the previous chapter, Context Engineering, we learned that the AI's "Context Window" is like a carpenter's workbench. If we clutter it with too much junk, the agent gets confused and performs poorly.

But what if our agent needs to do everything? What if it needs to be a coder, a writer, a financial analyst, and a calendar manager? We can't fit the instructions for all those jobs on the workbench at the same time.

This brings us to the core innovation of this framework: Agent Skills via Progressive Disclosure.

The Problem: The Heavy Backpack

Imagine you are going on a hike. You might need a tent, a kayak, snowshoes, and a swimsuit.

• The Naive Approach: You try to stuff all of them into your backpack "just in case." You can't move. You fall over.
• The Smart Approach: You look at a map. You see a lake? You grab the kayak. You see snow? You grab the snowshoes.

Most AI agents try to carry the kayak and the snowshoes at the same time. They load every possible tool definition and instruction into the system prompt at the start.

The Solution: The Library Card Catalog

We solve this using Progressive Disclosure.

Think of your agent as a student in a massive library.

1. The Card Catalog (Metadata): The student looks at a small index card. It says: "Advanced Calculus: Good for solving integrals."
2. The Book (Instructions): Only if the student actually needs to solve an integral do they walk to the shelf, pull the book, and read the chapters.

In our system, an Agent Skill is that book. The agent doesn't hold the book; it just holds the index card until it's time to work.

Anatomy of a Skill

An Agent Skill isn't a complex plugin. It is simply a Folder containing a specific file named SKILL.md.

Let's build a skill called social-media-manager.

1. The Folder Structure

We keep it simple. The file system is the memory structure.

skills/
└── social-media-manager/
    └── SKILL.md  <-- The Magic File

2. The Card Catalog (YAML Frontmatter)

At the very top of SKILL.md, we write the "Index Card." This is the only part the agent sees initially.

---
name: social-media-manager
description: Writes engaging posts for Twitter/X and LinkedIn. Use when the user asks to "draft a tweet" or "announce a launch."
---

• Name: How the system identifies it.
• Description: This is crucial. This is how the agent decides if it needs this skill. It connects the user's intent ("draft a tweet") to the skill.

3. The Book (Markdown Body)

Below the metadata, we write the actual instructions. The agent does not see this yet. It only loads this text when it decides to activate the skill.

# Social Media Manager

## Guidelines
1. Be punchy and concise.
2. Use emojis sparingly.
3. No hashtags in the middle of sentences.

## Twitter Format
- Max 280 characters.
- Start with a hook.

How It Works: The Flow

How does the agent go from "I see a description" to "I am reading the instructions"?

Implementation: Under the Hood

Let's write the Python code that powers this logic. We need two functions: one to build the catalog, and one to read the book.

Step 1: Building the "Card Catalog"

We need to scan our folder and get just the descriptions. We don't want to load the whole file!

import frontmatter # We use a library to parse the YAML top

def get_skill_catalog(skill_path):
    """Reads only the top part (metadata) of the skill."""
    # Load the file
    post = frontmatter.load(skill_path)
    
    # Return just the small index card
    return {
        "name": post["name"],
        "description": post["description"],
        "path": skill_path
    }

Explanation: We parse the file, but we discard the body content for now. We only keep the name and description. This keeps our RAM and Context Window empty.

Step 2: Injecting the Catalog

We present these options to the Agent in the System Prompt.

def create_system_prompt(catalog_list):
    prompt = "You are a helpful assistant.\n\nAVAILABLE SKILLS:\n"
    
    for skill in catalog_list:
        # We format it so the LLM understands what it can do
        prompt += f"- Name: {skill['name']}\n"
        prompt += f"  Description: {skill['description']}\n"
        prompt += f"  Location: {skill['path']}\n\n"
        
    return prompt

Explanation: The Agent now knows that social-media-manager exists and what it does, but it hasn't read the guidelines yet.

Step 3: Opening the Book (Progressive Disclosure)

When the agent realizes it needs the skill, it uses a tool (which we will discuss in the next chapter) to read the file.

def read_skill_content(file_path):
    """The agent calls this when it wants the full instructions."""
    with open(file_path, 'r') as f:
        return f.read()

Explanation: This effectively "loads the book onto the workbench." Now, and only now, does the Context Window fill up with the specific rules about hashtags and character limits.

Why This Matters

By using Progressive Disclosure, we achieve three things:

1. Scalability: You can have 1,000 skills (Coding, Cooking, Law, Medicine). The agent only "carries the weight" of the 1,000 descriptions, not the 1,000 text books.
2. Focus: When the agent is writing code, it isn't distracted by instructions on how to bake a cake. The context remains pure.
3. Cost: You don't pay for tokens you aren't using.

Summary

In this chapter, we learned:

1. The Backpack Problem: You can't carry everything at once.
2. The Solution: Use a "Card Catalog" (Metadata) to find what you need, then load the "Book" (Instructions) on demand.
3. The Structure: A Skill is just a Markdown file with YAML frontmatter.

Now that our agent can find the instructions, it needs a standardized way to actually do things—like reading that file or running a script. We need to agree on how the Agent interacts with the outside world.

Next Chapter: Tool Design (The Contract)

Generated by Code IQ