Giving Your AI Agents Reliable Skills with the Agent Skills SDK

Microsoft

Mar 03, 2026

AI agents are becoming increasingly capable, but they often do not have the context they need to do real work reliably. Your agent can reason well, but it does not actually know how to do the specific things your team needs it to do. For example, it cannot follow your company's incident response playbook, it does not know your escalation policy, and it has no idea how to page the on-call engineer at 3 AM.

There are many ways to close this gap, from RAG to custom tool implementations. Agent Skills is one approach that stands out because it is designed around portability and progressive disclosure, keeping context window usage minimal while giving agents access to deep expertise on demand.

What is Agent Skills?

Agent Skills is an open format for giving agents new capabilities and expertise. The format was originally developed by Anthropic and released as an open standard. It is now supported by a growing list of agent products including Claude Code, VS Code, GitHub, OpenAI Codex, Cursor, Gemini CLI, and many others.

As defined in the spec, a skill is a folder on disk containing a SKILL.md file with metadata and instructions, plus optional scripts, references, and assets:

incident-response/
    SKILL.md              # Required: instructions + metadata
    references/           # Optional: additional documentation
        severity-levels.md
        escalation-policy.md
    scripts/              # Optional: executable code
        page-oncall.sh
    assets/               # Optional: templates, diagrams, data files

The SKILL.md file has YAML frontmatter with a name and description (so agents know when the skill is relevant), followed by markdown instructions that tell the agent how to perform the task. The format is intentionally simple: self-documenting, extensible, and portable.

What makes this design practical is progressive disclosure. The spec is built around the idea that agents should not load everything at once. It works in three stages:

Discovery: At startup, agents load only the name and description of each available skill, just enough to know when it might be relevant.
Activation: When a task matches a skill's description, the agent reads the full SKILL.md instructions into context.
Execution: The agent follows the instructions, optionally loading referenced files or executing bundled scripts as needed.

This keeps agents fast while giving them access to deep context on demand.

The format is well-designed and widely adopted, but if you want to use skills from your own agents, there is a gap between the spec and a working implementation.

The Agent Skills SDK

Conceptually, a skill is more than a folder. It is a unit of expertise: a name, a description, a body of instructions, and a set of supporting resources. The file layout is one way to represent that, but there is nothing about the concept that requires a filesystem.

The Agent Skills SDK is an open-source Python library built around that idea, treating skills as abstract units of expertise that can be stored anywhere and consumed by any agent framework. It does this by addressing two challenges that come up when you try to use the format from your own agents.

The first is where skills live. The spec defines skills as folders on disk, and the tools that support the format today all assume skills are local files. Files are inherently portable, and that is one of the format's strengths. But in the real world, not every team can or wants to serve skills from the filesystem. Maybe your team keeps them in an S3 bucket. Maybe they are in Azure Blob Storage behind your CDN. Maybe they live in a database alongside the rest of your application data. At the moment, if your skills are not on the local filesystem, you are on your own. The SDK changes where skills are served from, not how they are authored. The content and format stay the same regardless of the storage backend, so skills remain portable across providers.

The second is how agents consume them. The spec defines the progressive disclosure pattern but actually implementing it in your agent requires real work. You need to figure out how to validate skills against the spec, generate a catalog for the system prompt, expose the right tools for on-demand content retrieval, and handle the back-and-forth of the agent requesting metadata, then the body, then individual references or scripts. That is a lot of plumbing regardless of where the skills are stored, and the work multiplies if you want to support more than one agent framework.

The SDK solves both by separating where skills come from (providers) from how agents use them (integrations), so you can mix and match freely. Load skills from the filesystem today, move them to an HTTP server tomorrow, swap in a custom database provider next month, and your agent code does not change at all.

How the SDK works

The SDK is a set of Python packages organized around two ideas: storage-agnostic providers and progressive disclosure.

The provider abstraction means your skills can live anywhere. The SDK ships with providers for the local filesystem and static HTTP servers, but the SkillProvider interface is simple enough that you can write your own in a few methods. A Cosmos DB provider, a Git provider, a SharePoint provider, whatever makes sense for your team. The rest of the SDK does not care where the data comes from.

On top of that, the SDK implements the progressive disclosure pattern from the spec as a set of tools that any LLM agent can use. At startup, the SDK generates a skills catalog containing each skill's name and description. Your agent injects this catalog into its system prompt so it knows what is available. Then, during a conversation, the agent calls tools to retrieve content on demand, following the same discovery-activation-execution flow the spec describes.

Here is the flow in practice:

You register skills from any source (local files, an HTTP server, your own database).
The SDK generates a catalog and tool usage instructions, which you inject into the system prompt.
The agent calls tools to retrieve content on demand.

This matters because context windows are finite. An incident response skill might have a main body, three reference documents, two scripts, and a flowchart. The agent should not load all of that upfront. It should read the body first, then pull the escalation policy only when the conversation actually gets to escalation.

A quick example

Here is what it looks like in practice. Start by loading a skill from the filesystem:

from pathlib import Path
from agentskills_core import SkillRegistry
from agentskills_fs import LocalFileSystemSkillProvider

provider = LocalFileSystemSkillProvider(Path("my-skills"))
registry = SkillRegistry()
await registry.register("incident-response", provider)

Now wire it into a LangChain agent:

from langchain.agents import create_agent
from agentskills_langchain import get_tools, get_tools_usage_instructions

tools = get_tools(registry)
skills_catalog = await registry.get_skills_catalog(format="xml")
tool_usage_instructions = get_tools_usage_instructions()

system_prompt = (
    "You are an SRE assistant. Use the available skill tools to look up "
    "incident response procedures, severity definitions, and escalation "
    "policies. Always cite which reference document you used.\n\n"
    f"{skills_catalog}\n\n"
    f"{tool_usage_instructions}"
)

agent = create_agent(
    llm,
    tools,
    system_prompt=system_prompt,
)

That is it. The agent now knows what skills are available and has tools to fetch their content. When a user asks "How do I handle a SEV1 incident?", the agent will call get_skill_body to read the instructions, then get_skill_reference to pull the severity levels document, all without you writing any of that retrieval logic.

The same pattern works with Microsoft Agent Framework:

from agentskills_agentframework import get_tools, get_tools_usage_instructions

tools = get_tools(registry)
skills_catalog = await registry.get_skills_catalog(format="xml")
tool_usage_instructions = get_tools_usage_instructions()

system_prompt = (
    "You are an SRE assistant. Use the available skill tools to look up "
    "incident response procedures, severity definitions, and escalation "
    "policies. Always cite which reference document you used.\n\n"
    f"{skills_catalog}\n\n"
    f"{tool_usage_instructions}"
)

agent = Agent(
    client=client,
    instructions=system_prompt,
    tools=tools,
)

What is in the SDK

The SDK is split into small, composable packages so you only install what you need:

agentskills-core handles registration, validation, the skills catalog, and the progressive disclosure API. It also defines the SkillProvider interface that all providers implement.
agentskills-fs and agentskills-http are the two built-in providers. The filesystem provider loads skills from local directories. The HTTP provider loads them from any static file host: S3, Azure Blob Storage, GitHub Pages, a CDN, or anything that serves files over HTTP.
agentskills-langchain and agentskills-agentframework generate framework-native tools and tool usage instructions from a skill registry.
agentskills-mcp-server spins up an MCP server that exposes skill tool access and usage as tools and resources, so any MCP-compatible client can use them.

Because providers and integrations are separate packages, you can combine them however you want. Use the filesystem provider during development, switch to the HTTP provider in production, or write a custom provider that reads skills from your own database. The integration layer does not need to know or care.

Where to go from here

The full source, working examples, and detailed API docs are on GitHub:

github.com/pratikxpanda/agentskills-sdk

The repo includes end-to-end examples for both LangChain and Microsoft Agent Framework, covering filesystem providers, HTTP providers, and MCP. There is also a sample incident-response skill you can use to try things out.

A proposal to contribute this SDK to the official agentskills repository has been submitted. If you find it useful, feel free to show your support on the GitHub issue.

To learn more about the Agent Skills format itself: