Chapter 05 · Skills and progressive disclosure

Skills are directories containing SKILL.md. At startup the agent reads only frontmatter summaries and reads full content when relevant. Use them for project-specific domain knowledge instead of cramming everything into the system prompt.

Mechanics and design choices

create_deep_agent’s skills= accepts a list of paths; same-named skills override earlier ones (last wins). Skills fit “split by domain” — one skill, one capability pack, rather than putting all instructions in one file.

Example

import os
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
    model=os.environ["MODEL_ID"],
    api_key=os.environ["DEEPAGENT_API_KEY"],
    base_url=os.environ.get("DEEPAGENT_BASE_URL", "https://api.openai.com/v1"),
)

import pathlib, shutil, tempfile
from deepagents import create_deep_agent

root = tempfile.mkdtemp(prefix="deepagents-skills-")
try:
    skill_dir = pathlib.Path(root) / "skills" / "code-review"
    skill_dir.mkdir(parents=True)
    (skill_dir / "SKILL.md").write_text(
        "---\nname: code-review\ndescription: Review code for correctness, style, and testing gaps.\n---\n\n"
        "When reviewing code, call out: (1) missing tests, (2) unsafe shell usage, (3) duplicated logic.\n"
    )
    agent = create_deep_agent(
        model=model,
        skills=[str(skill_dir.parent)],
        system_prompt="Use the code-review skill when the user asks for a review.",
    )
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "Review a script that runs rm -rf /."}]},
        {"configurable": {"thread_id": "ch05"}},
    )
    print(result["messages"][-1].content)
finally:
    shutil.rmtree(root, ignore_errors=True)

Run and verify

API key required. The answer should reflect the three skill items: missing tests, unsafe shell usage, duplicated logic.

Pitfalls

Skills are instruction packs, not safety policies. Refuse dangerous actions through permissions, tool validation, or approval gates; do not rely on a skill saying “do not delete /”.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. How much is loaded at startup?

2. What is the same-name rule?

3. Can skills enforce security?

4. What granularity fits skills?

Hands-on exercises

1. Add a second skill and observe that only summaries load at startup.
2. Create two same-named skill directories and verify last wins.
3. Add a reference script to the skill and verify on-demand reads.

Official references

• skills
• context-engineering

Verified on 2026-09-17 with Deep Agents 0.7.15.