---
slug: "agentskills-sdk"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/pratikxpanda/agentskills-sdk@main/README.md"
repo: "https://github.com/pratikxpanda/agentskills-sdk"
source_file: "README.md"
branch: "main"
---
# Agent Skills SDK

[![CI](https://github.com/pratikxpanda/agentskills-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/pratikxpanda/agentskills-sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.12 | 3.13](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)

> A Python SDK for discovering, retrieving, and serving [Agent Skills](https://agentskills.io) to LLM agents.

**Agent Skills** is an [open format](https://agentskills.io/specification) for giving AI agents new capabilities and expertise. Originally developed by Anthropic, the format is now supported by Claude Code, Cursor, GitHub, VS Code, Gemini CLI, and many others.

This project helps you **integrate skills into your own agents**. Retrieve skills from any source - filesystem, database, API - validate them against the spec, and expose them to LLM agents through a progressive-disclosure API.

> **Note:** Python 3.12 and 3.13 are supported. Python 3.14 is not yet supported due to upstream dependency limitations.

---

## Packages

| Package | Description | Install |
| --- | --- | --- |
| [`agentskills-core`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/core/agentskills-core/README.md) | Core abstractions - `SkillProvider`, `Skill`, `SkillRegistry`, validation | `pip install agentskills-core` |
| [`agentskills-fs`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/providers/agentskills-fs/README.md) | Load skills from the local filesystem - `LocalFileSystemSkillProvider` | `pip install agentskills-fs` |
| [`agentskills-http`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/providers/agentskills-http/README.md) | Load skills from a static HTTP server - `HTTPStaticFileSkillProvider` | `pip install agentskills-http` |
| [`agentskills-langchain`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/integrations/agentskills-langchain/README.md) | Integrate skills with LangChain agents - `get_tools`, `get_tools_usage_instructions` | `pip install agentskills-langchain` |
| [`agentskills-agentframework`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/integrations/agentskills-agentframework/README.md) | Integrate skills with Microsoft Agent Framework agents - `AgentSkillsContextProvider`, `get_tools`, `get_tools_usage_instructions` | `pip install agentskills-agentframework` |
| [`agentskills-mcp-server`](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/packages/integrations/agentskills-mcp-server/README.md) | Expose skills over the Model Context Protocol (MCP) - `create_mcp_server`, `AgentSkillsMcpContextProvider` | `pip install agentskills-mcp-server` |

## How It Works

The SDK uses **progressive disclosure** to deliver skill content efficiently - each step only fetches what's needed:

1. **Register** skills from any source (filesystem, HTTP, database, etc.)
2. **Inject** the skills catalog and tool usage instructions into the system prompt
3. **Disclose on demand** - the agent uses tools (`get_skill_body`, `get_skill_reference`, etc.) to retrieve content as needed

The system prompt tells the agent *what* skills exist and *how* to use the tools. The tools themselves are the progressive-disclosure API - the agent fetches metadata, then the full body, then individual references, scripts, or assets, only when needed.

## Quick Start

```python
import asyncio
from pathlib import Path
from agentskills_core import SkillRegistry
from agentskills_fs import LocalFileSystemSkillProvider

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

    # Discover
    for skill in registry.list_skills():
        print(skill.get_id())                  # 'incident-response'

    # Retrieve
    skill = registry.get_skill("incident-response")
    meta = await skill.get_metadata()
    print(meta["description"])                 # SOPs for production incident management...
    print(await skill.get_body())              # Full markdown instructions

asyncio.run(main())
```

### With LangChain

```python
from langchain.agents import create_agent
from langchain_openai import AzureChatOpenAI
from agentskills_langchain import get_tools, get_tools_usage_instructions

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

llm = AzureChatOpenAI(
    azure_deployment=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    api_version=os.environ["AZURE_OPENAI_API_VERSION"],
    temperature=0,
)
agent = create_agent(
    llm,
    tools,
    system_prompt=f"{skills_catalog}\n\n{tools_usage_instructions}",
)
```

The skill catalog tells the agent *what* skills exist, and the usage instructions tell it *how* to use the tools (`get_skill_body`, `get_skill_reference`, etc.).

See [examples/langchain/](https://github.com/pratikxpanda/agentskills-sdk/tree/HEAD/examples/langchain/) for full working demos with filesystem and HTTP providers.

### With Microsoft Agent Framework

**Context provider (recommended)** — plug into the agent lifecycle so skills are injected automatically:

```python
from agent_framework import Agent
from agentskills_agentframework import AgentSkillsContextProvider

skills_context_provider = AgentSkillsContextProvider(registry)

agent = Agent(
    client=client,  # any Agent Framework chat client
    name="SREAssistant",
    instructions="You are an SRE assistant.",
    context_providers=[skills_context_provider],
)
response = await agent.run("What severity is a full DB outage?")
```

**Manual tools** — build the system prompt yourself for full control:

```python
from agent_framework import Agent
from agentskills_agentframework import get_tools, get_tools_usage_instructions

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

agent = Agent(
    client=client,  # any Agent Framework chat client
    name="SREAssistant",
    instructions=f"{skills_catalog}\n\n{tools_usage_instructions}",
    tools=tools,
)
```

See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/HEAD/examples/agent-framework/) for full working demos including client setup.

### With MCP

#### Config-driven server (CLI)

Create a `server.json` config file and run the built-in MCP server directly - any MCP-compatible client (Claude Desktop, VS Code, Cursor, etc.) can connect to it:

```json
{
    "name": "My Skills Server",
    "skills": [
        {
            "id": "incident-response",
            "provider": "fs",
            "options": { "root": "./skills" }
        },
        {
            "id": "cloud-runbooks",
            "provider": "http",
            "options": {
                "base_url": "https://cdn.example.com/skills",
                "headers": { "Authorization": "Bearer ${API_TOKEN}" }
            }
        }
    ]
}
```

> **Environment variables** - String values may contain `${VAR}` placeholders that are resolved from environment variables at load time. This keeps secrets out of the config file.

```bash
# stdio transport (default - used by most MCP clients)
python -m agentskills_mcp_server --config server.json

# streamable-http transport
python -m agentskills_mcp_server --config server.json --transport streamable-http
```

Point your MCP client at the server:

```json
{
    "command": "python",
    "args": ["-m", "agentskills_mcp_server", "--config", "server.json"]
}
```

#### Programmatic server

For custom setups, create the server in code:

```python
from agentskills_mcp_server import create_mcp_server

server = create_mcp_server(registry, name="My Agent")
server.run()  # stdio by default
```

Both approaches expose the same tools (`get_skill_metadata`, `get_skill_body`, etc.) and resources (`skills://catalog/xml`, `skills://catalog/markdown`, `skills://tools-usage-instructions`).

#### Agent Framework + MCP context provider

If you're using Agent Framework with an MCP-based skill server, `AgentSkillsMcpContextProvider` bridges the MCP session into the agent lifecycle — skills are injected automatically on every `agent.run()` call:

```bash
pip install agentskills-mcp-server[agentframework]
```

```python
from agent_framework import Agent, MCPStdioTool
from agentskills_mcp_server import AgentSkillsMcpContextProvider

mcp_skills = MCPStdioTool(
    name="skills",
    command="python",
    args=["-m", "agentskills_mcp_server", "--config", "server.json"],
)

async with mcp_skills:
    skills_context = AgentSkillsMcpContextProvider(session=mcp_skills.session)
    agent = Agent(
        client=client,
        name="SREAssistant",
        instructions="You are an SRE assistant.",
        tools=mcp_skills,
        context_providers=[skills_context],
    )
    response = await agent.run("What severity is a full DB outage?")
```

See [examples/agent-framework/](https://github.com/pratikxpanda/agentskills-sdk/tree/HEAD/examples/agent-framework/) for full working demos.

## Custom Providers

The `SkillProvider` ABC is storage-agnostic. Implement it to back skills with any source:

```python
from agentskills_core import SkillProvider

class DatabaseSkillProvider(SkillProvider):
    async def get_metadata(self, skill_id: str) -> dict: ...
    async def get_body(self, skill_id: str) -> str: ...
    async def get_script(self, skill_id: str, name: str) -> bytes: ...
    async def get_asset(self, skill_id: str, name: str) -> bytes: ...
    async def get_reference(self, skill_id: str, name: str) -> bytes: ...
```

Register a custom provider:

```python
registry = SkillRegistry()
await registry.register("customer-onboarding", DatabaseSkillProvider(conn))
```

Register multiple providers at once:

```python
registry = SkillRegistry()
await registry.register([
    ("customer-onboarding", DatabaseSkillProvider(conn)),
    ("incident-response", LocalFileSystemSkillProvider(path)),
])
```

Batch registration is atomic - if any skill fails validation, none are registered.

## Development

See [docs/DEVELOPMENT.md](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/docs/DEVELOPMENT.md) for setup, testing, linting, CI, releasing, and project structure.

## Related Resources

- [Agent Skills specification](https://agentskills.io/specification)
- [What are skills?](https://agentskills.io/what-are-skills)
- [Integrate skills into your agent](https://agentskills.io/integrate-skills)
- [Agent Skills Directory](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/docs/SKILLS-DIRECTORY.md)

## Security

Agent Skills are **equivalent to executable code** - skill content is injected into an LLM agent's context verbatim. **Only load skills from sources you trust.**

The SDK includes built-in protections: input validation, TLS enforcement options, response size limits, path-traversal guards, and safe XML generation. See each package's README for provider-specific security controls.

To report a vulnerability, see [SECURITY.md](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/SECURITY.md).

## Contributing

Contributions are welcome! See [CONTRIBUTING.md](https://github.com/pratikxpanda/agentskills-sdk/blob/HEAD/CONTRIBUTING.md) for guidelines on setup, code style, testing, and pull requests.

## License

MIT