第 05 章 · Skills 与渐进披露

Skills 是带 SKILL.md 的目录：启动时只读 frontmatter 摘要，任务相关时才读全文。用它承载项目内领域知识，避免把所有说明塞进 system prompt。

机制与设计选择

create_deep_agent 的 skills= 接受路径列表；同名 skill 后写的覆盖先写的（last wins）。Skills 适合“按领域拆”——一个 skill 一个能力包，而不是把所有指令写进一个文件。

示例

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)

运行与验收

需要 API Key。验收：回答应体现 skill 列出的三类关注点（缺失测试、不安全 shell、重复逻辑）。

容易踩的坑

skill 不是安全策略，只是指令包。危险动作的拒绝要由权限、工具校验或审批节点完成；不要把“不要删 /”只写在 skill 里。

🧪 随堂测验

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

1. 启动时 skill 加载多少？

2. 同名 skill 规则？

3. skill 能强制安全吗？

4. skill 适合什么粒度？

动手实践

1. 加第二个 skill，观察启动时只加载摘要。
2. 建两个同名 skill 目录，验证 last wins。
3. 给 skill 加一个参考脚本文件，验证按需读取。

官方参考

• skills
• context-engineering

核验日期：2026-09-17，运行环境：Deep Agents 0.7.15。