20  Equipping Agents for the Real World with Agent Skills

20.1 The Problem with Monolithic Agents

As agents moved from demos to production in 2026, a familiar problem emerged. An agent that can do everything needs to know everything — and stuffing all that knowledge into a system prompt doesn’t scale. System prompts grew to thousands of words, mixing high-level behavioral guidelines with low-level API details, formatting conventions, and domain-specific jargon. Performance degraded. Maintenance became a nightmare. And every team that wanted to add a capability had to edit the same shared prompt.

Agent Skills solves this problem by taking a page from human expertise: specialize, organize, and load on demand.

20.2 What Are Agent Skills?

Agent Skills are organized folders of instructions, scripts, and resources that teach an agent how to perform a specific task. They are the modular, reusable building blocks of agent capability.

A skill is not a tool (though it may contain tools). A skill is not a prompt (though it contains instructions). A skill is a self-contained package of expertise that an agent can discover, understand, and apply when the situation calls for it.

skills/
├── pdf-generation/
│   ├── SKILL.md              # Instructions for the agent
│   ├── templates/
│   │   ├── report.html
│   │   └── invoice.html
│   └── scripts/
│       └── html_to_pdf.py
├── sql-optimization/
│   ├── SKILL.md
│   ├── references/
│   │   ├── postgres-tuning.md
│   │   └── query-plans.md
│   └── scripts/
│       └── explain_analyzer.py
└── incident-response/
    ├── SKILL.md
    ├── runbooks/
    │   ├── high-cpu.md
    │   └── disk-full.md
    └── scripts/
        └── escalate.py

20.2.1 The SKILL.md File

Every skill has a SKILL.md file at its root. This is the manifest — the thing the agent reads to decide whether and how to use the skill.

---
name: pdf-generation
description: >
  Generate professionally styled PDF documents from HTML
  templates. Use when the user asks to create a PDF report,
  invoice, or letter.
version: 1.2.0
triggers:
  - "create a PDF"
  - "generate a report"
  - "export to PDF"
tools_required:
  - bash
---

# PDF Generation Skill

## When to Use

Use this skill when the user asks to create a PDF document.
This includes reports, invoices, letters, and any structured
document that needs professional formatting.

## How to Use

1. Select the appropriate template from `templates/`.
2. Fill in the template variables.
3. Run `scripts/html_to_pdf.py` to generate the PDF.
4. Verify the output by checking the file size and page count.

## Templates

- `report.html` — Multi-section report with table of contents
- `invoice.html` — Standard invoice with line items
- `letter.html` — Business letter format

## Pitfalls

- Do not use Chromium headless for large documents (> 100 pages).
  Use the `--batch` flag instead.
- Always specify `--print-background` to preserve styling.

20.2.2 Dynamic Discovery and Loading

The key innovation is that skills are dynamically discovered and loaded. The agent doesn’t start with all skills in its context. Instead:

1. At the start of a session, the agent receives a skill index — a lightweight list of available skills with their names and one-line descriptions.
2. When the user’s request matches a skill’s triggers, the agent reads the full SKILL.md.
3. If the skill references scripts or templates, those are loaded on demand.
4. When the task is complete, the skill’s full content can be evicted from context.

This means an agent can have access to hundreds of skills without any of them consuming context until they’re needed.

Note

Dynamic discovery is what makes skills fundamentally different from system prompt injection. A 500-word skill description in the index costs almost nothing. The full 2000-word skill body is only loaded when relevant. This is lazy evaluation for agent expertise.

20.3 Cross-Platform Support

Agent Skills are designed to work everywhere Claude operates. A skill written once runs across:

Surface	How Skills Are Used
Claude.ai	User-uploaded skills for personal assistants
Claude Code	Project-level and user-level skills for coding
Agent SDK	Programmatic skill loading for custom agents
Developer Platform	Organization-managed skills for production agents

This is a deliberate design choice. Anthropic published Agent Skills as an open standard, meaning other AI platforms can implement the same format. A skill written for Claude Code can be used by any agent that understands the SKILL.md format.

# A skill that works everywhere
name: git-conflict-resolution
description: >
  Resolve Git merge conflicts intelligently. Understands
  common conflict patterns and suggests resolutions based
  on the context of both branches.
triggers:
  - "merge conflict"
  - "resolve conflict"
  - "rebase conflict"

Tip

When writing skills, keep the SKILL.md platform-agnostic. Put platform-specific behavior in scripts that detect the environment at runtime. This maximizes portability across Claude surfaces and third-party platforms.

20.4 Skills vs. MCP Servers

Agent Skills and MCP servers are complementary, not competing. Understanding the distinction helps you choose the right tool for each job.

Dimension	Agent Skills	MCP Servers
What they provide	Instructions, knowledge, scripts, templates	Tools, resources, live data connections
State	Static (files on disk)	Dynamic (running process)
When loaded	On demand, by the agent	At session start
Best for	Teaching how to do something	Providing access to something
Example	“How to write a SQL migration”	“Connect to the production database”

A typical agent uses both. An MCP server provides the database connection. A skill teaches the agent the team’s migration conventions. Together, they enable the agent to not just access the database, but to work with it correctly.

from claude_agent_sdk import Agent

agent = Agent(
    model="claude-sonnet-4-6",
    # MCP provides the connection
    mcp_servers=[
        {"name": "postgres", "command": "mcp-server-postgres"},
    ],
    # Skills provide the expertise
    skills_dir="./skills",
    tools=["bash", "file_read", "file_write"],
)

20.5 Building Effective Skills

20.5.1 1. Keep Skills Focused

A skill should do one thing well. If you find yourself adding “and also…” to a skill description, it’s probably two skills.

# Bad: too broad
name: data-work
description: Do data analysis, visualization, and pipeline management.

# Good: focused
name: data-visualization
description: >
  Create publication-quality charts and plots from data files.
  Supports matplotlib, seaborn, and plotly.

20.5.2 2. Include Triggers

Triggers help the agent know when to load a skill. They should cover the common ways users might phrase the request.

triggers:
  - "create a chart"
  - "plot this data"
  - "visualize"
  - "make a graph"
  - "generate a figure"

20.5.3 3. Provide Scripts, Not Just Instructions

The most effective skills include executable scripts that handle the mechanical parts of the task. The agent reads the instructions to understand what to do, then uses the scripts to do it.

# skills/data-visualization/scripts/create_chart.py
#!/usr/bin/env python3
"""Create a chart from a CSV file."""
import argparse
import pandas as pd
import matplotlib.pyplot as plt

parser = argparse.ArgumentParser()
parser.add_argument("input", help="CSV file path")
parser.add_argument("--x", required=True, help="X-axis column")
parser.add_argument("--y", required=True, help="Y-axis column")
parser.add_argument("--type", default="line", choices=["line", "bar", "scatter"])
parser.add_argument("--output", default="chart.png")
args = parser.parse_args()

df = pd.read_csv(args.input)
fig, ax = plt.subplots(figsize=(10, 6))

if args.type == "line":
    ax.plot(df[args.x], df[args.y])
elif args.type == "bar":
    ax.bar(df[args.x], df[args.y])
elif args.type == "scatter":
    ax.scatter(df[args.x], df[args.y])

ax.set_xlabel(args.x)
ax.set_ylabel(args.y)
plt.tight_layout()
plt.savefig(args.output, dpi=150)
print(f"Chart saved to {args.output}")

20.5.4 4. Document Pitfalls

Skills should include a “Pitfalls” or “Common Mistakes” section. This is where you encode the hard-won knowledge from production experience.

## Pitfalls

- **Memory limits**: Matplotlib can OOM on datasets with > 1M points.
  Downsample first with `df.sample(100000)`.
- **Font rendering**: Custom fonts must be installed system-wide.
  Use `matplotlib.font_manager` to register them.
- **DPI for print**: Use `dpi=300` for print-quality output,
  `dpi=150` for screen. Higher DPI dramatically increases file size.

20.5.5 5. Version Your Skills

As skills evolve, version them. This is especially important in team settings where multiple people might depend on a skill’s behavior.

name: pdf-generation
version: 2.0.0
breaking_changes:
  - "v2.0: Template variable syntax changed from {{var}} to ${var}"
  - "v1.5: Added support for multi-language documents"

20.6 The Vision: Self-Improving Skills

The long-term vision for Agent Skills is the most exciting part. Anthropic’s roadmap includes agents that can create, edit, and evaluate their own Skills.

Here’s what this looks like in practice:

1. Creation: An agent encounters a task it doesn’t have a skill for. It performs the task manually, figures out the steps, and creates a new SKILL.md with scripts to automate those steps in the future.

2. Editing: An agent uses a skill and discovers a pitfall not documented in the “Pitfalls” section. It updates the skill to include the new knowledge.

3. Evaluation: An agent periodically reviews its skills, identifying ones that are outdated, redundant, or rarely used. It proposes cleanups and consolidations.

# A meta-agent that manages skills
skill_manager = Agent(
    model="claude-opus-4-6",
    system_prompt="""You are a skill curator.
1. Review the skills directory.
2. Identify skills that are outdated or redundant.
3. Propose improvements based on recent usage logs.
4. Create new skills for tasks that are frequently performed manually.""",
    tools=["file_read", "file_write", "bash"],
    skills_dir="./meta-skills",  # Skills about managing skills
)

Tip

Self-improving skills represent a form of organizational learning. Every time an agent discovers a better way to do something, that knowledge is captured in a skill that benefits all future sessions. Over time, the skill library becomes a repository of the team’s accumulated expertise.

20.7 Skills as an Open Standard

Anthropic has published the Agent Skills specification as an open standard. This means:

• Any AI platform can implement skill discovery and loading.
• Skill authors can write once and deploy across platforms.
• Organizations can build internal skill marketplaces that work with any agent framework.
• The community can share skills openly, accelerating collective capability.

The specification covers:

• Directory structure: SKILL.md at the root, with scripts/, templates/, and references/ subdirectories.
• Metadata format: YAML frontmatter with name, description, version, triggers, and tools_required.
• Discovery protocol: How agents index available skills and match them to requests.
• Loading semantics: When and how skill content enters the agent’s context.

20.8 A Practical Skill Library

Here is an example of a well-organized skill library for a software engineering team:

skills/
├── code-review/
│   ├── SKILL.md
│   └── checklists/
│       ├── security.md
│       ├── performance.md
│       └── api-design.md
├── database-migration/
│   ├── SKILL.md
│   ├── templates/
│   │   ├── up.sql
│   │   └── down.sql
│   └── scripts/
│       └── validate_migration.py
├── api-documentation/
│   ├── SKILL.md
│   ├── templates/
│   │   └── openapi.yaml
│   └── scripts/
│       └── validate_openapi.py
├── deployment/
│   ├── SKILL.md
│   ├── runbooks/
│   │   ├── blue-green.md
│   │   └── canary.md
│   └── scripts/
│       ├── health_check.sh
│       └── rollback.sh
└── incident-postmortem/
    ├── SKILL.md
    └── templates/
        └── postmortem.md

Each skill is independently versioned, tested, and maintained. New team members get the full benefit of accumulated expertise on day one.

Tip

A well-maintained skill library is a competitive advantage. It encodes not just “what we know” but “how we work” in a form that makes every agent on the team smarter. Invest in curating it the way you would invest in any core infrastructure.

20.9 Key Takeaways

• Agent Skills are organized folders of instructions, scripts, and resources that teach agents how to perform specific tasks — the modular building blocks of agent capability.
• Skills are dynamically discovered and loaded: the agent sees a lightweight index at session start and loads full skill content only when relevant, keeping context lean.
• Skills work across all Claude surfaces — Claude.ai, Claude Code, Agent SDK, and Developer Platform — and are published as an open standard for cross-platform portability.
• Skills complement MCP servers: MCP provides connections and live data; Skills provide expertise and instructions on how to work with that data.
• Effective skills are focused, triggered, scripted, and documented — one job per skill, clear triggers, executable scripts, and a pitfalls section.
• The long-term vision is self-improving skills: agents that create, edit, and evaluate their own skills, turning individual discoveries into organizational learning.
• Anthropic has published the Agent Skills specification as an open standard, enabling any AI platform to implement skill discovery and loading.