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

> Learn how to create and register custom skills with DeepAgents SkillsMiddleware. Scan skill directories and inject metadata into system prompts for enhanced capabilities.

- Repository: [LangChain/deepagents](https://github.com/langchain-ai/deepagents)
- Tags: how-to-guide
- Published: 2026-03-17

---

**The DeepAgents SDK loads reusable capability bundles called skills by scanning directories containing [`SKILL.md`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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.

```bash

# 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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/libs/cli/examples/skills/skill-creator/scripts/init_skill.py).

### 2. Configure the SKILL.md Metadata

Edit the generated [`SKILL.md`](https://github.com/langchain-ai/deepagents/blob/main/SKILL.md) to define your skill's interface:

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

```python
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`](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py), the middleware scans each source directory recursively, parsing every [`SKILL.md`](https://github.com/langchain-ai/deepagents/blob/main/SKILL.md) encountered and building an internal registry.

## Integrating with LangChain Runnables

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

```python
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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/tests/unit_tests/middleware/test_skills_middleware.py) verify this override behavior ensures predictable skill resolution.

## Summary

- **SkillsMiddleware** ([`libs/deepagents/deepagents/middleware/skills.py`](https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/skills.py)) automatically discovers capabilities by scanning directories for [`SKILL.md`](https://github.com/langchain-ai/deepagents/blob/main/SKILL.md) files and injecting metadata into system prompts.
- Create skills using the [`init_skill.py`](https://github.com/langchain-ai/deepagents/blob/main/init_skill.py) helper or manually构造 a directory with [`SKILL.md`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/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`](https://github.com/langchain-ai/deepagents/blob/main/SKILL.md) file with valid YAML front-matter containing `name` and `description` keys, and place it within a directory scanned by your `FilesystemBackend` configuration.