Skills: SKILL.md loaded on demand

A skill is a folder with a SKILL.md file of instructions for one kind of job; the agent sees only each skill's name and description at the start and reads the full file when a request matches it.

Last updated: 29 Sep, 2026 · Deep Agents 0.7

Skills as on-demand expertise

The video defines skills as on-demand expertise with progressive disclosure: capability modules loaded only when a request needs them. Memory is always in the prompt; a skill is not. A Python-expert skill loads when you ask for Python code, an AWS skill when you ask about EC2, a LangGraph skill for graphs. The rule: do not load everything all the time, load the right skill for the task. Memory holds small, global rules; skills hold large, detailed, situational guidance.

The video has Claude Code write four skills (LangGraph, Python, AWS, report writer), each a folder with SKILL.md, instructions and examples. It seeds the SKILL.md files into state, creates the agent with skills=["/skills/"], and in this clip asks "How do I build a LangGraph graph with conditional routing and memory?": the first tool calls read /skills/langgraph/SKILL.md, with the report-writer skill alongside it. An EC2 question reads the AWS skill. "Give an example of oops in Python" did not load the Python skill; a clearer request, "write me Python code to do binary search", did.

Shown as it ran in the video, not run here: the four skills come from the video's repository. The trip planner gets a small packing skill below.

The skills= syntax

SKILL.md:
---
name: packing-list
description: Use when the traveller asks what to pack.   # what the agent matches on
---
# instructions the agent reads when the skill is used

agent = create_deep_agent(model=model, skills=["/skills/"])   # a folder of skill folders
agent.invoke({"messages": [...], "files": {"/skills/packing-list/SKILL.md": create_file_data(text)}})

A packing-list skill

Start trip.py with search_travel, the catalog tool from Tools: a travel search the agent can call. Everything below goes in the same file, under it.

from langchain.tools import tool

CATALOG = {
    "paris": {
        "flight": ["Return flight Delhi to Paris: 42,000 rupees"],
        "hotel": ["Seine Budget Inn, Latin Quarter: 5,200 rupees a night",
                  "Hotel Lumiere, Montmartre: 7,500 rupees a night",
                  "Le Grand Opera Hotel: 16,000 rupees a night"],
        "sight": ["Eiffel Tower summit: 3,100 rupees", "Louvre Museum: 2,000 rupees",
                  "Seine river cruise: 1,500 rupees", "Versailles day trip: 2,600 rupees",
                  "Montmartre walking tour: free"],
        "food": ["Cafe breakfast and bistro dinner: 3,000 rupees a day"],
    },
}


@tool
def search_travel(city: str, kind: str) -> str:
    """Search the travel catalog. kind is "flight", "hotel", "sight" or "food". Prices are in rupees."""
    entries = CATALOG.get(city.lower(), {}).get(kind)
    return "\n".join(entries) if entries else f"The catalog has no {kind} entries for {city}."

from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

model = init_chat_model("groq:openai/gpt-oss-120b", temperature=0, max_retries=6)
from deepagents.backends.utils import create_file_data

SKILL_MD = """---
name: packing-list
description: Use when the traveller asks what to pack or bring on a trip.
---
# Packing list
Write three headings: Documents, Clothes, Gadgets. Put at most three items under each.
"""

An agent with a skills folder

agent = create_deep_agent(
    model=model,
    tools=[search_travel],
    skills=["/skills/"],                         # a folder of skill folders
    system_prompt="You are a travel planner. Use only prices from search_travel. Keep replies short.",
)
skill_files = {"/skills/packing-list/SKILL.md": create_file_data(SKILL_MD)}

One question that needs the skill, one that does not

for question in ["What should I pack for Paris in December?", "What is the cheapest hotel in Paris?"]:
    result = agent.invoke({"messages": [{"role": "user", "content": question}], "files": skill_files})
    reads = [c["args"]["file_path"] for m in result["messages"] for c in getattr(m, "tool_calls", []) if c["name"] == "read_file"]
    print("Q:", question)
    print("files read:", reads)
    print(result["messages"][-1].text, "\n")

Q: What should I pack for Paris in December?
files read: ['/skills/packing-list/SKILL.md']
**Documents**  
- Passport / ID  
- Travel insurance & itinerary  
- Metro/transport pass  

**Clothes**  
- Warm coat or trench coat  
- Sweaters & scarves  
- Comfortable waterproof boots  

**Gadgets**  
- Smartphone & charger  
- Portable power bank  
- Universal travel adapter 

Q: What is the cheapest hotel in Paris?
files read: []
The cheapest hotel in Paris is **Seine Budget Inn** in the Latin Quarter at **5,200 rupees per night**. 

When the skill was read

• The packing question matched the description, so the agent read /skills/packing-list/SKILL.md and answered with the three headings and at most three items each.
• The hotel question did not match; the agent answered from the catalog without reading the skill.
• At startup only the name and description were in the prompt. The instructions cost tokens only on the run that needed them.

Skills vs memory

Where skills fit

• Checklists and formats for a kind of task: a packing list, a report, a code review.
• Domain know-how an agent needs sometimes: cloud setup, a library's API.
• Sharing one skill folder between several agents.

Related

• Previous: Memory: AGENTS.md loaded with memory=
• Next: ToolRuntime and runtime context: who is asking
• Reference: Deep Agents skills