Skills

Skills are reusable agent capabilities that provide specialized workflows and domain knowledge. You can use Agent Skills to provide your deep agent with new capabilities and expertise. Deep agent skills follow the Agent Skills 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)

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.

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:

    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:

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

ImportantRefer to the full Agent Skills 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.

Full example

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

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

StateBackend
StoreBackend
FilesystemBackend

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"}},
)

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"}},
)

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"}},
)

skills

list[str]

List of skill source paths.Paths must be specified using forward slashes and are relative to the backend’s root.

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

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.

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

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-5-20250929",
    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.

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:

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

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.

Skills vs. memory

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

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Get started

Core capabilities

Protocols

Command line interface

What are skills

How skills work

Example

Full example

Usage

Source precedence

Skills for subagents

What the agent sees

Skills vs. memory

When to use skills and tools

Get started

Core capabilities

Protocols

Command line interface

​What are skills

​How skills work

​Example

​Full example

​Usage

​Source precedence

​Skills for subagents

​What the agent sees

​Skills vs. memory

​When to use skills and tools

What are skills

How skills work

Example

Full example

Usage

Source precedence

Skills for subagents

What the agent sees

Skills vs. memory

When to use skills and tools