skills

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.

Architecture

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):

SkillsMiddleware(backend=StateBackend(), ...)

Skill Structure

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
...

Skill Metadata (SkillMetadata)

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 file
• Optional: license, compatibility, metadata, allowed_tools

Sources

Sources 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/"
]

Path Conventions

All paths use POSIX conventions (forward slashes) via PurePosixPath:

• Backend paths: "/skills/user/web-research/SKILL.md"
• Virtual, platform-independent
• Backends handle platform-specific conversions as needed

Usage

from deepagents.backends.state import StateBackend
from deepagents.middleware.skills import SkillsMiddleware

middleware = SkillsMiddleware(
    backend=my_backend,
    sources=[
        "/skills/base/",
        "/skills/user/",
        "/skills/project/",
    ],
)