How to Create and Register Custom Skills with the SkillsMiddleware in DeepAgents

The DeepAgents SDK loads reusable capability bundles called skills by scanning directories containing SKILL.md files and injecting their metadata into the system prompt via the SkillsMiddleware.

The langchain-ai/deepagents repository provides a modular middleware system that enables agents to discover and utilize external capabilities. Creating and registering custom skills with the SkillsMiddleware involves scaffolding a directory with required metadata, configuring the middleware with source paths, and attaching it to your agent runtime.

Understanding the SkillsMiddleware Architecture

The SkillsMiddleware (libs/deepagents/deepagents/middleware/skills.py) acts as a capability discovery layer between your file system and the agent's context window. It scans designated source directories for skill bundles, validates their metadata, and formats a concise skills list that is automatically appended to the system prompt.

Skills follow a progressive disclosure pattern: the agent initially receives only the skill name and description, then requests the full SKILL.md content on demand when it decides to use a specific capability.

Skill Directory Structure Requirements

A valid skill is a directory that must contain a SKILL.md file with specific YAML front-matter, and may include optional subdirectories for implementation assets.

Required Components

Every skill directory must include:

• SKILL.md – A markdown file containing YAML front-matter with name and description fields, followed by documentation detailing the skill's usage, parameters, and examples.

Optional Subdirectories

You may include these standard subdirectories to organize skill resources:

• scripts/ – Helper scripts or executable code that the skill can reference
• references/ – API documentation, schema definitions, or external reference materials
• assets/ – Static files such as templates, sample data, or configuration files

Step-by-Step: Creating and Registering Custom Skills

1. Scaffold the Skill Directory

Use the provided CLI helper to generate a properly structured skill template. This ensures the required front-matter and directory layout are created correctly.

# From the repository root

python -m libs.cli.examples.skills.skill-creator.scripts.init_skill \
    my-data-analyzer --path ~/.deepagents/agent/skills

This command creates ~/.deepagents/agent/skills/my-data-analyzer/ containing the SKILL.md file and empty scripts/, references/, and assets/ directories. The initialization script is defined in libs/cli/examples/skills/skill-creator/scripts/init_skill.py.

2. Configure the SKILL.md Metadata

Edit the generated SKILL.md to define your skill's interface:

---
name: my-data-analyzer
description: Analyzes CSV files for statistical anomalies and generates summary reports
---

# My Data Analyzer

Use this skill when the user needs to process tabular data for outliers.

## Parameters

- `file_path`: Path to the CSV file
- `threshold`: Z-score threshold for anomaly detection (default: 2.5)

## Example Usage

...

The middleware parses this front-matter to build the skills registry. Validation logic ensures both name and description fields are present before inclusion in the system prompt.

3. Register Skills with the Middleware

Instantiate SkillsMiddleware with a FilesystemBackend and configure the sources list to include your skill directories. The middleware processes sources in order, with later sources overriding earlier ones if name collisions occur.

from pathlib import Path
from deepagents.backends.filesystem import FilesystemBackend
from deepagents.middleware.skills import SkillsMiddleware

# Backend points to the parent directory containing skill sources

backend = FilesystemBackend(root_dir=str(Path.home() / ".deepagents/agent/skills"))

middleware = SkillsMiddleware(
    backend=backend,
    sources=[
        "/skills/base/",      # built-in base skills (lowest priority)

        "/skills/user/",      # user-level overrides

        "/skills/project/",   # project-specific skills (highest priority)

    ],
)

The sources parameter accepts a list of paths relative to the backend root. According to the implementation in libs/deepagents/deepagents/middleware/skills.py, the middleware scans each source directory recursively, parsing every SKILL.md encountered and building an internal registry.

Integrating with LangChain Runnables

Attach the configured middleware to your Agent to enable automatic skill injection:

from deepagents.deepagents import Agent

agent = Agent(
    middleware=[middleware],
    # ...other agent configuration...

)

# The system prompt now includes a formatted "Skills" section

response = agent.invoke({"input": "Analyze the quarterly sales data for anomalies"})

The middleware hooks into the agent lifecycle via abefore_agent (validated in tests/unit_tests/middleware/test_skills_middleware_async.py) to modify the system message before the LLM receives the input. Helper utilities in libs/deepagents/middleware/_utils.py handle the actual text appending to ensure proper message formatting.

Understanding Source Precedence (Last-One-Wins)

When multiple sources contain skills with identical names, SkillsMiddleware applies a last-one-wins resolution strategy. If /skills/base/data-utils and /skills/project/data-utils both exist, the project-specific version shadows the base version.

This behavior enables powerful customization patterns:

• Base layers provide generic, widely-applicable capabilities
• User layers contain personal workflow optimizations
• Project layers override with domain-specific implementations

Unit tests in tests/unit_tests/middleware/test_skills_middleware.py verify this override behavior ensures predictable skill resolution.

Summary

• SkillsMiddleware (libs/deepagents/deepagents/middleware/skills.py) automatically discovers capabilities by scanning directories for SKILL.md files and injecting metadata into system prompts.
• Create skills using the init_skill.py helper or manually构造 a directory with SKILL.md containing name and description YAML front-matter.
• Register skills by providing source directories to the sources parameter; later sources override earlier ones when names collide.
• The middleware supports progressive disclosure, sending only skill summaries initially and providing full documentation on agent request.

Frequently Asked Questions

What file format does the SkillsMiddleware require for skill definitions?

The middleware requires a SKILL.md file in each skill directory with YAML front-matter containing at minimum the name and description fields. The file follows standard markdown syntax after the front-matter block, allowing rich documentation that the agent can request on demand.

How does the SkillsMiddleware handle duplicate skill names across different sources?

When identical skill names exist in multiple sources, the middleware applies a last-one-wins override policy based on the order of the sources list. Skills discovered in later array indices shadow those found in earlier indices, enabling project-specific skills to override generic base implementations.

Can I use the SkillsMiddleware without the provided init_skill.py script?

Yes. While libs/cli/examples/skills/skill-creator/scripts/init_skill.py provides a convenient template generator, you can manually create the directory structure. Ensure you include a SKILL.md file with valid YAML front-matter containing name and description keys, and place it within a directory scanned by your FilesystemBackend configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}