Agent Skills

Agent Skills are the modular building blocks of capable AI agents. Rather than hardcoding every capability into a single monolithic agent, skills let you package a discrete capability — a workflow, a set of instructions, supporting scripts, and any required resources — into a self-contained unit that any compatible agent can load and use.

Think of skills like plugins for an agent: the agent knows what skills are available, picks the one relevant to the task, loads its instructions, and executes accordingly. The underlying model doesn’t change — only the context it operates within does.

The SKILL.md Format

The dominant convention for defining agent skills is a SKILL.md file — a Markdown document with a YAML frontmatter header and a natural-language body:

---
name: competitor-research
description: Researches a named competitor and produces a structured brief covering pricing, positioning, and recent news.
version: 1.0.0
tools: [web_search, file_write]
---

Followed by the instruction body in Markdown — step-by-step guidance the agent follows when this skill is invoked.

The format was introduced by Anthropic in October 2025 and published as an open standard in December 2025, designed for cross-platform portability across different agent runtimes.

Skills vs. Tools

These two terms are often confused but operate at different levels of abstraction:

A skill typically orchestrates multiple tool calls as part of achieving its objective. The skill defines the what and how; the tools do the atomic work.

Anatomy of a Skill

A well-structured skill package typically contains:

• SKILL.md — the primary instruction file with frontmatter metadata and natural-language steps
• Supporting scripts — optional code files (Python, shell) the agent can run as part of the skill
• Resource files — templates, schemas, or reference data the skill needs
• README.md — human-readable documentation for skill authors and reviewers

The agent runtime reads the frontmatter to understand the skill’s name, description, required tools, and version, then injects the Markdown body into its context when the skill is activated.

How Agents Discover and Load Skills

The skill selection flow works as follows:

1. Discovery: The agent has access to a skill registry — a directory of available SKILL.md files, either local or remote.
2. Selection: Given a user goal, the LLM reads skill descriptions and selects the most relevant one (or the orchestrator routes to it explicitly).
3. Loading: The skill’s instructions are injected into the agent’s context window, along with any supporting resources.
4. Execution: The agent follows the skill’s steps, calling the tools specified in the frontmatter as needed.
5. Completion: The agent returns the skill’s output and unloads the skill context.

Why Skills Matter

Separation of concerns: Capability authors write skills; agent platform authors write the runtime. Neither needs to understand the other’s domain deeply.

Composability: Complex workflows are built by chaining skills. An “onboard new client” workflow might invoke a CRM-update skill, a document-generation skill, and a notification skill in sequence.

Version control: Skills are files — they live in git, get reviewed in PRs, and roll back cleanly. Capability changes are auditable.

Portability: A skill written for Claude Code can run in a compatible agent runtime on a different platform, as long as both implement the open standard.

No retraining: Adding a new capability is a file write, not a model training run. Teams can expand agent behaviour in hours rather than weeks.

Skills in Production

By 2026, agent skills are in use across:

• Developer tools — Claude Code ships with built-in skills (like /review, /security-review) that agents load on demand
• Enterprise automation — teams maintain internal skill libraries for domain-specific workflows (contract review, lead enrichment, incident response)
• Open-source ecosystems — public skill repositories (similar to npm or PyPI) let teams share and reuse community-built capabilities

import json
import anthropic

client = anthropic.Anthropic()

# Define skills as tools Claude can invoke
tools = [
    {
        "name": "web_search",
        "description": "Search the web for current information on a topic.",
        "input_schema": {
            "type": "object",
            "properties": {
                "query": {"type": "string", "description": "The search query."},
            },
            "required": ["query"],
        },
    },
    {
        "name": "calculator",
        "description": "Evaluate a mathematical expression and return the result.",
        "input_schema": {
            "type": "object",
            "properties": {
                "expression": {"type": "string", "description": "A valid Python math expression."},
            },
            "required": ["expression"],
        },
    },
]

def run_tool(name: str, inputs: dict) -> str:
    if name == "web_search":
        return f"[Mock result for '{inputs['query']}'] Claude 4 was released in 2025."
    if name == "calculator":
        return str(eval(inputs["expression"]))  # noqa: S307 (demo only)
    return "Unknown tool"

# Agentic loop — Claude calls tools until it has a final answer
messages = [{"role": "user", "content": "What is 1234 * 5678, and who made Claude?"}]

while True:
    response = client.messages.create(
        model="claude-opus-4-8",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )

    messages.append({"role": "assistant", "content": response.content})

    if response.stop_reason == "end_turn":
        final = next(b.text for b in response.content if hasattr(b, "text"))
        print("Answer:", final)
        break

    # Execute all tool calls and feed results back
    tool_results = []
    for block in response.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })

    messages.append({"role": "user", "content": tool_results})