Skills middleware for loading and exposing agent skills to the system prompt.
This module implements Anthropic's agent skills pattern with progressive disclosure, loading skills from backend storage via configurable sources.
Skills are loaded from one or more sources - paths in a backend where skills are organized. Sources are loaded in order, with later sources overriding earlier ones when skills have the same name (last one wins). This enables layering: base -> user -> project -> team skills.
The middleware uses backend APIs exclusively (no direct filesystem access), making it portable across different storage backends (filesystem, state, remote storage, etc.).
For StateBackend (ephemeral/in-memory), use a factory function:
SkillsMiddleware(backend=lambda rt: StateBackend(rt), ...)Each skill is a directory containing a SKILL.md file with YAML frontmatter:
/skills/user/web-research/
├── SKILL.md # Required: YAML frontmatter + markdown instructions
└── helper.py # Optional: supporting files
SKILL.md format:
---
name: web-research
description: Structured approach to conducting thorough web research
license: MIT
---
# Web Research Skill
## When to Use
- User asks you to research a topic
...
Parsed from YAML frontmatter per Agent Skills specification:
name: Skill identifier (max 64 chars, lowercase alphanumeric and hyphens)description: What the skill does (max 1024 chars)path: Backend path to the SKILL.md filelicense, compatibility, metadata, allowed_toolsSources are simply paths to skill directories in the backend. The source name is derived from the last component of the path (e.g., "/skills/user/" -> "user").
Example sources:
[
"/skills/user/",
"/skills/project/"
]All paths use POSIX conventions (forward slashes) via PurePosixPath:
from deepagents.backends.state import StateBackend
from deepagents.middleware.skills import SkillsMiddleware
middleware = SkillsMiddleware(
backend=my_backend,
sources=[
"/skills/base/",
"/skills/user/",
"/skills/project/",
],
)Protocol for pluggable memory backends (single, unified).
Backends can store files in different locations (state, filesystem, database, etc.) and provide a uniform interface for file operations.
All file data is represented as dicts with the following structure: { "content": list[str], # Lines of text content "created_at": str, # ISO format timestamp "modified_at": str, # ISO format timestamp }
Metadata for a skill per Agent Skills specification (https://agentskills.io/specification).
State for the skills middleware.
State update for the skills middleware.
Middleware for loading and exposing agent skills to the system prompt.
Loads skills from backend sources and injects them into the system prompt using progressive disclosure (metadata first, full content on demand).
Skills are loaded in source order with later sources overriding earlier ones.