> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-patchr-1773857969-df0cef9.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Skills

> Learn how to extend your deep agent's capabilities with skills

Skills are reusable agent capabilities that provide specialized workflows and domain knowledge.

You can use [Agent Skills](https://agentskills.io/) to provide your deep agent with new capabilities and expertise.

Deep agent skills follow the [Agent Skills specification](https://agentskills.io/specification).

## What are skills

Skills are a directory of folders, where each folder has one or more files that contain context the agent can use:

* A `SKILL.md` file containing instructions and metadata about the skill
* Additional scripts (optional)
* Additional reference info, such as docs (optional)
* Additional assets, such as templates and other resources (optional)

<Note>
  Any additional assets (scripts, docs, templates, or other resources) must be referenced in the `SKILL.md` file with information on what the file contains and how to use it so the agent can decide when to use them.
</Note>

## How skills work

When you create a deep agent, you can pass in a list of directories containing skills. As the agent starts, it reads through the frontmatter of each `SKILL.md` file.

When the agent receives a prompt, the agent checks if it can use any skills while fulfilling the prompt. If it finds a matching prompt, it then reviews the rest of the skill files. This pattern of only reviewing the skill information when needed is called *progressive disclosure*.

## Example

You might have a skills folder that contains a skill to use a docs site in a certain way, as well as another skill to search the arXiv preprint repository of research papers:

```plaintext theme={null}
    skills/
    ├── langgraph-docs
    │   └── SKILL.md
    └── arxiv_search
        ├── SKILL.md
        └── arxiv_search.py # code for searching arXiv
```

The `SKILL.md` file always follows the same pattern, starting with metadata in the frontmatter and followed by the instructions for the skill.

The following example shows a skill that gives instructions on how to provide relevant langgraph docs when prompted:

```md theme={null}
---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
---

# langgraph-docs

## Overview

This skill explains how to access LangGraph Python documentation to help answer questions and guide implementation.

## Instructions

### 1. Fetch the Documentation Index

Use the fetch_url tool to read the following URL:
https://docs.langchain.com/llms.txt

This provides a structured list of all available documentation with descriptions.

### 2. Select Relevant Documentation

Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:

- Specific how-to guides for implementation questions
- Core concept pages for understanding questions
- Tutorials for end-to-end examples
- Reference docs for API details

### 3. Fetch Selected Documentation

Use the fetch_url tool to read the selected documentation URLs.

### 4. Provide Accurate Guidance

After reading the documentation, complete the user's request.
```

For more example skills, see [Deep Agent example skills](https://github.com/langchain-ai/deepagents/tree/main/libs/cli/examples/skills).

<Warning>
  **Important**

  Refer to the full [Agent Skills Specification](https://agentskills.io/specification) for information on constraints and best practices when authoring skill files. Notably:

  * The `description` field is truncated to 1024 characters if it exceeds that length.
  * In Deep Agents, `SKILL.md` files must be under 10 MB. Files exceeding this limit are skipped during skill loading.
</Warning>

### Full example

The following example shows a `SKILL.md` file using all available frontmatter fields:

```md expandable theme={null}
---
name: langgraph-docs
description: Use this skill for requests related to LangGraph in order to fetch relevant documentation to provide accurate, up-to-date guidance.
license: MIT
compatibility: Requires internet access for fetching documentation URLs
metadata:
  author: langchain
  version: "1.0"
allowed-tools: fetch_url
---

# langgraph-docs

## Overview

This skill explains how to access LangGraph Python documentation to help answer questions and guide implementation.

## Instructions

### 1. Fetch the documentation index

Use the fetch_url tool to read the following URL:
https://docs.langchain.com/llms.txt

This provides a structured list of all available documentation with descriptions.

### 2. Select relevant documentation

Based on the question, identify 2-4 most relevant documentation URLs from the index. Prioritize:

- Specific how-to guides for implementation questions
- Core concept pages for understanding questions
- Tutorials for end-to-end examples
- Reference docs for API details

### 3. Fetch selected documentation

Use the fetch_url tool to read the selected documentation URLs.

### 4. Provide accurate guidance

After reading the documentation, complete the user's request.
```

## Usage

Pass the skills directory when creating your deep agent:

<Tabs>
  <Tab title="StateBackend">
    ```python theme={null}
    from urllib.request import urlopen
    from deepagents import create_deep_agent
    from deepagents.backends.utils import create_file_data
    from langgraph.checkpoint.memory import MemorySaver

    checkpointer = MemorySaver()

    skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
    with urlopen(skill_url) as response:
        skill_content = response.read().decode('utf-8')

    skills_files = {
        "/skills/langgraph-docs/SKILL.md": create_file_data(skill_content)
    }

    agent = create_deep_agent(
        skills=["/skills/"],
        checkpointer=checkpointer,
    )

    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "What is langgraph?",
                }
            ],
            # Seed the default StateBackend's in-state filesystem (virtual paths must start with "/").
            "files": skills_files
        },
        config={"configurable": {"thread_id": "12345"}},
    )
    ```
  </Tab>

  <Tab title="StoreBackend">
    ```python theme={null}
    from urllib.request import urlopen
    from deepagents import create_deep_agent
    from deepagents.backends import StoreBackend
    from deepagents.backends.utils import create_file_data
    from langgraph.store.memory import InMemoryStore


    store = InMemoryStore()

    skill_url = "https://raw.githubusercontent.com/langchain-ai/deepagents/refs/heads/main/libs/cli/examples/skills/langgraph-docs/SKILL.md"
    with urlopen(skill_url) as response:
        skill_content = response.read().decode('utf-8')

    store.put(
        namespace=("filesystem",),
        key="/skills/langgraph-docs/SKILL.md",
        value=create_file_data(skill_content)
    )

    agent = create_deep_agent(
        backend=(lambda rt: StoreBackend(rt)),
        store=store,
        skills=["/skills/"]
    )

    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "What is langgraph?",
                }
            ]
        },
        config={"configurable": {"thread_id": "12345"}},
    )
    ```
  </Tab>

  <Tab title="FilesystemBackend">
    ```python theme={null}
    from deepagents import create_deep_agent
    from langgraph.checkpoint.memory import MemorySaver
    from deepagents.backends.filesystem import FilesystemBackend

    # Checkpointer is REQUIRED for human-in-the-loop
    checkpointer = MemorySaver()

    agent = create_deep_agent(
        backend=FilesystemBackend(root_dir="/Users/user/{project}"),
        skills=["/Users/user/{project}/skills/"],
        interrupt_on={
            "write_file": True,  # Default: approve, edit, reject
            "read_file": False,  # No interrupts needed
            "edit_file": True    # Default: approve, edit, reject
        },
        checkpointer=checkpointer,  # Required!
    )

    result = agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": "What is langgraph?",
                }
            ]
        },
        config={"configurable": {"thread_id": "12345"}},
    )
    ```
  </Tab>
</Tabs>

<ParamField body="skills" type="list[str]" optional>
  List of skill source paths.

  Paths must be specified using forward slashes and are relative to the backend's root.

  * If omitted, no skills are loaded.
  * When using `StateBackend` (default), provide skill files with `invoke(files={...})`. Use `create_file_data()` from `deepagents.backends.utils` to format file contents; raw strings are not supported.
  * With `FilesystemBackend`, skills are loaded from disk relative to the backend's `root_dir`.

  Later sources override earlier ones for skills with the same name (last one wins).
</ParamField>

<Note>
  The SDK only loads the sources you pass in `skills`. It does not automatically scan CLI directories such as `~/.deepagents/...` or `~/.agents/...`.

  For CLI storage conventions, see [App data](/oss/python/deepagents/data-locations).

  <Accordion title="Emulating CLI source order in SDK">
    If you want CLI-style layering in SDK code, pass all desired sources explicitly in lowest-to-highest precedence order:

    ```text theme={null}
    [
    "<user-home>/.deepagents/{agent}/skills/",
    "<user-home>/.agents/skills/",
    "<project-root>/.deepagents/skills/",
    "<project-root>/.agents/skills/",
    ]
    ```

    Then pass that ordered list as `skills` when creating your agent.
  </Accordion>
</Note>

## Source precedence

When multiple skill sources contain a skill with the same name, the skill from the source listed later in the `skills` array takes precedence (last one wins). This lets you layer skills from different origins.

```python theme={null}
# If both sources contain a skill named "web-search",
# the one from "/skills/project/" wins (loaded last).
agent = create_deep_agent(
    skills=["/skills/user/", "/skills/project/"],
    ...
)
```

## Skills for subagents

When you use [subagents](/oss/python/deepagents/subagents), you can configure which skills each type has access to:

* **General-purpose subagent**: Automatically inherits skills from the main agent when you pass `skills` to `create_deep_agent`. No additional configuration is needed.
* **Custom subagents**: Do not inherit the main agent's skills. Add a `skills` parameter to each subagent definition with that subagent's skill source paths.

Skill state is fully isolated: the main agent's skills are not visible to subagents, and subagent skills are not visible to the main agent.

```python theme={null}
from deepagents import create_deep_agent

research_subagent = {
    "name": "researcher",
    "description": "Research assistant with specialized skills",
    "system_prompt": "You are a researcher.",
    "tools": [web_search],
    "skills": ["/skills/research/", "/skills/web-search/"],  # Subagent-specific skills
}

agent = create_deep_agent(
    model="claude-sonnet-4-6",
    skills=["/skills/main/"],  # Main agent and GP subagent get these
    subagents=[research_subagent],  # Researcher gets only its own skills
)
```

For more information on subagent configuration and skills inheritance, see [Subagents](/oss/python/deepagents/subagents).

## What the agent sees

When skills are configured, a "Skills System" section is injected into the agent's system prompt. The agent uses this information to follow a three-step process:

1. **Match**—When a user prompt arrives, the agent checks whether any skill's description matches the task.
2. **Read**—If a skill applies, the agent reads the full `SKILL.md` file using the path shown in its skills list.
3. **Execute**—The agent follows the skill's instructions and accesses any supporting files (scripts, templates, reference docs) as needed.

<Tip>
  Write clear, specific descriptions in your `SKILL.md` frontmatter. The agent decides whether to use a skill based on the description alone—detailed descriptions lead to better skill matching.
</Tip>

## Skills vs. memory

Skills and [memory](/oss/python/deepagents/customization#memory) (`AGENTS.md` files) serve different purposes:

|              | Skills                                                           | Memory                                                        |
| ------------ | ---------------------------------------------------------------- | ------------------------------------------------------------- |
| **Purpose**  | On-demand capabilities discovered through progressive disclosure | Persistent context always loaded at startup                   |
| **Loading**  | Read only when the agent determines relevance                    | Always injected into system prompt                            |
| **Format**   | `SKILL.md` in named directories                                  | `AGENTS.md` files                                             |
| **Layering** | User → project (last wins)                                       | User → project (combined)                                     |
| **Use when** | Instructions are task-specific and potentially large             | Context is always relevant (project conventions, preferences) |

## When to use skills and tools

These are a few general guidelines for using tools and skills:

* Use skills when there is a lot of context to reduce the number of tokens in the system prompt.
* Use skills to bundle capabilities together into larger actions and provide additional context beyond single tool descriptions.
* Use tools if the agent does not have access to the file system.

***

<div className="source-links">
  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/skills.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>

  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>
</div>