agentskills-agentframework

Microsoft Agent Framework integration for the Agent Skills SDK - turn a skill registry into Agent Framework tools.

Generates a set of Microsoft Agent Framework FunctionTool instances from a SkillRegistry, ready to be passed to any Agent Framework agent.

Installation

pip install agentskills-agentframework

Requires Python 3.12 or newer. Installs agentskills-core and agent-framework as dependencies.

Note: agent-framework is currently a pre-release dependency (>=1.0.0rc3). The constraint will be updated once a stable release is published.

Usage

Context Provider (recommended)

The simplest way to integrate is via AgentSkillsContextProvider. It plugs into the Agent Framework lifecycle and automatically injects the skill catalog and tools on every agent.run() call — no manual system-prompt assembly required.

from pathlib import Path

from agent_framework import Agent
from agentskills_core import SkillRegistry
from agentskills_fs import LocalFileSystemSkillProvider
from agentskills_agentframework import AgentSkillsContextProvider

# Set up registry
provider = LocalFileSystemSkillProvider(Path("./skills"))
registry = SkillRegistry()
await registry.register("incident-response", provider)

# Create context provider
skills_context_provider = AgentSkillsContextProvider(registry)

# Pass it to the agent — catalog + tools are injected automatically
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?")

See examples/agent-framework/ for full working demos including client setup.

Manual Tools

For full control over system-prompt construction, use get_tools() directly:

from pathlib import Path

from agent_framework import Agent
from agentskills_core import SkillRegistry
from agentskills_fs import LocalFileSystemSkillProvider
from agentskills_agentframework import get_tools, get_tools_usage_instructions

# Set up registry
provider = LocalFileSystemSkillProvider(Path("./skills"))
registry = SkillRegistry()
await registry.register("incident-response", provider)

# Build tools + system prompt
tools = get_tools(registry)
catalog = await registry.get_skills_catalog(format="xml")
instructions = get_tools_usage_instructions()

# Pass to agent
agent = Agent(
    client=client,  # any Agent Framework chat client
    name="SREAssistant",
    instructions=f"{catalog}\n\n{instructions}",
    tools=tools,
)

The catalog tells the agent what skills exist; the usage instructions tell it how to use the tools.

See examples/agent-framework/ for full working demos including client setup.

Generated Tools

All tools are async-compatible (FunctionTool with @tool decorator).

list_skill_resources returns a JSON object keyed by resource kind. Not every backend can enumerate resources — a plain static HTTP host cannot. Rather than surfacing an exception, the tool returns {"supported": false, "note": "..."} in that case: "this cannot be listed" is something the model can act on by falling back to the names in the skill body, not an error worth retrying.

API

AgentSkillsContextProvider(registry, *, skills_instruction_prompt=None, skills_catalog_format="xml", source_id=None)

A ContextProvider that injects skill catalog + tools into the agent session automatically via before_run(). Skips injection when the registry has no skills.

get_tools(registry: SkillRegistry, *, max_inline_binary_bytes: int = 65536) -> list[FunctionTool]

Returns a list of Agent Framework function tools bound to the given registry.

get_tools_usage_instructions() -> str

Returns a markdown string explaining the progressive-disclosure workflow - read metadata, then body, then fetch resources on demand. Designed for system-prompt injection alongside the skill catalog.

Comparison with Agent Framework's built-in provider

Agent Framework ships its own FileAgentSkillsProvider. Both plug into the same lifecycle, but they solve different problems:

If all you need is skills in a local folder, the built-in provider is already installed and is the simpler choice. Reach for this package when skills come from somewhere other than disk, when you need several sources in one catalog, or when you want the agent to distinguish a script from a reference document.

Example

See examples/agent-framework/ for full working demos.

Error Handling

All exceptions inherit from AgentSkillsError (from agentskills-core).

Binary Resources

Skill resources may be arbitrary files. Valid UTF-8 is returned as-is; anything else is returned as a JSON envelope, so a binary payload is never silently mangled into replacement characters:

{
  "name": "architecture.png",
  "media_type": "image/png",
  "size_bytes": 20481,
  "encoding": "base64",
  "content": "iVBORw0KGgo..."
}

Base64 costs roughly 1.37 characters per byte, so binaries above 64 KiB are described rather than inlined - "encoding": "none" plus a note explaining the omission. Adjust the ceiling with:

tools = get_tools(registry, max_inline_binary_bytes=256 * 1024)

License

MIT