告别上下文爆炸：LangChain Agent Skills 完全实战指南

发表于最近更新于最近

作者 KennethCheng

609~783 分钟 阅读

当你的 AI Agent 需要接入十几个工具，每个工具的"使用说明"都塞进 prompt 里时，模型会发出这样的哀嚎："我上下文已经爆炸了，怎么干活啊？？"

这篇文章会带你深入理解 Agent Skills 这套由 Anthropic 提出的开放标准，并通过 LangChain DeepAgent 完成从环境搭建到实战的完整流程。

一、为什么需要 Agent Skills？

设想一个"全能 Agent"，它需要同时调用：数据库查询工具、代码执行工具、网络浏览工具、URL 解析工具…… 每个工具都得在 system prompt 里塞一段「用法与职责」说明：

随着工具数量增长，prompt 越来越长，模型越来越"挤"。这正是所谓的 上下文危机。

1.1 Agent Skills 的核心思想

Agent Skills 是一个开放的格式标准，本质上就是"文件夹"，里面包含了指令、脚本和资源。AI Agent 可以发现并加载这些文件夹，从而获得执行特定任务的能力。

把工具说明从 prompt 里"卸载"到文件系统中，Agent 只在需要时才加载——这就是 Skills 的精髓。

1.2 三大核心价值

价值	痛点	解决方式
🚨 上下文危机	通用 Agent 需要强大的多功能，但持久的多功能上下文造成了无法想象的上下文压力	将职责说明从 prompt 卸载到文件系统
♻️ 避免重复造轮子	不需要为每个 Agent 框架都重写"如何连接数据库"或"如何审查代码"	一次编写，多次复用
🔌 互操作性	企业内部隐性知识难以传承	转化为可移植、版本控制的"技能包"

二、Agent Skill 的构成

2.1 核心思路

将职责与工具卸载到文件系统，按需加载。

Agent Skill 就是一个文件夹。每个文件夹里：

一个 SKILL.md（包含 YAML 前置元数据 + Markdown 详细说明）
可选的脚本、文档、资源文件夹

2.2 文件夹结构

2.3 SKILL.md 文件格式

① 元数据 (YAML Frontmatter) —— 始终持有

---
# 必填字段
name: pdf-processing           # 技能名称（小写字母、数字、连字符）
description: 描述 skill 的功能以及何时使用（这对 Agent 决策至关重要！）

# 可选字段
license: Apache-2.0
compatibility: python>=3.10
metadata:
  author: your-name
  version: 1.0.0
allowed_tools: [read_file, shell]
---

字段	是否必填	说明
`name`	✅ 必填	技能名称（小写字母、数字、连字符，如 `pdf-processing`）
`description`	✅ 必填	描述 Skill 的功能以及何时使用——Agent 决策的关键依据
`license`	⭕ 可选	开源许可证
`compatibility`	⭕ 可选	兼容的环境/版本要求
`metadata`	⭕ 可选	作者、版本等附加信息
`allowed_tools`	⭕ 可选	允许调用的工具列表

② 正文 (Markdown Body) —— 按需加载

格式没有严格限制，但建议包含：

📋 逐步操作指南
🔢 输入/输出示例
⚠️ 边缘情况处理
🛠️ 对辅助资源或脚本的调用指令与说明

📏 建议主文件 < 500 行（超出部分拆分到 references/）

③ 辅助资源 —— 按需调用（shell）

文件夹	用途	注意事项
`scripts/`	脚本文件	应包含错误处理，且尽量独立执行
`references/`	详细文档	存放详细文档，避免 `SKILL.md` 主文件过长
`assets/`	资源/数据源	可能使用到的资源或数据源

2.4 运行逻辑：三步加载机制

这是 Skill 最精妙的设计——始终轻量、按需加载：

阶段	触发时机	加载内容	设计意图
① 扫描	Agent 启动时	仅 YAML 元数据（`name` + `description`）	极低成本建立 Skill 索引
② 激活	任务与 Skill 匹配时	完整的 `SKILL.md`	仅在需要时才加载详细说明
③ 执行	需要执行操作时	调用脚本或读取参考文档	真正干活时才用资源

三、LangChain DeepAgent 实战

💡 deepagent-CLI 是一款开源编码助手，可以使用您的本地文件系统。LangChain 为 deepagent-CLI 兼容了 Skill，使得庞大且不断增长的公共技能库成为可能。

3.1 完整安装流程

步骤 ① —— 下载 Python 3.12

# 添加 Python 官方 PPA
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# 安装 Python 3.12
sudo apt install -y python3.12 python3.12-venv python3.12-dev

步骤 ② —— 克隆项目

git clone https://github.com/langchain-ai/deepagents deepagents-demo
cd deepagents-demo

步骤 ③ —— 修改版本依赖

编辑 libs/deepagents-cli/pyproject.toml：

dependencies = [
    "deepagents>=0.2.8",          # 原本是 ==0.2.8
    "langchain>=1.2.3,<2.0.0",
    "langchain-openai>=1.1.7,<2.0.0",
    "langgraph-checkpoint-sqlite>=2.0.0,<3.0.0",
    "requests",
    "rich>=13.0.0",
]

步骤 ④ —— 创建虚拟环境

python3.12 -m venv langchain-py312
source langchain-py312/bin/activate
python --version   # 验证版本

步骤 ⑤ —— 安装依赖

pip install -e libs/deepagents
pip install -e libs/deepagents-cli
pip install langchain-openai

# 验证版本
pip show deepagents         # deepagents >= 0.3.5
pip show deepagents-cli     # deepagents-cli >= 0.1.2

步骤 ⑥ —— 设置环境变量

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=lsv2_xxx
export OPENAI_BASE_URL=https://...
export OPENAI_API_KEY=sk-xxx
export TAVILY_API_KEY=tvly-xxx

步骤 ⑦ —— 下载官方示例 Skills

mkdir -p .deepagents
cp -r libs/deepagents-cli/examples/skills .deepagents/skills/

3.2 Skills 目录结构

3.3 启动 DeepAgent

deepagents --model gpt-5

启动后进入 DEEP AGENTS v0.0.12 交互界面：

DEEP AGENTS  v0.0.12
Ready to code! What would you like to build?
Enter send • Ctrl+J newline • @ files • / commands
auto | shift+tab to cycle    Ready    8.1K tokens

四、Skill 安全提醒

在使用任何 Skill 之前，请务必记住以下三点：

认真查看"跳转操作"与"敏感读取" —— 阅读 SKILL.md 中涉及删除、修改、读取敏感数据的部分
sandbox 沙箱运行，相对路径 —— 避免污染主目录或越权访问
保证 API-KEY 只读，且合理设置白名单域名 —— 防止 Key 泄露与非法调用

五、实战案例：arxiv-search Skill

5.1 任务

在 arxiv 中，寻找名为《Chain-of-Thought Prompting Elicits Reasoning in Large Language Models》的机器学习领域论文原文，并将其摘要内容翻译为中文。

5.2 完整执行流程

Step 1 —— Agent 自动读取完整的 SKILL.md：

Tool: read_file(.deepagents/skills/arxiv-search/SKILL.md)
✓ Success
---
name: arxiv-search
description: Search arXiv preprint repository for papers in physics, mathematics, ...

💬 Agent 自述：「我已经查看完整的 arxiv-search 技能说明，可以直接用该技能的 Python 脚本搜索你想要的论文。接下来这篇机器学习领域的论文，获取其摘要并翻译为中文。」

Step 2 —— Agent 调用脚本执行搜索：

Tool: shell("python3 /root/Lesson_17/deepagents-demo/.deepagents/skills/arxiv-search/arxiv_search.py")
✓ Success
Title: Making Large Language Models Better Reasoners with Alignment
Summary: Reasoning is a cognitive process of using evidence to reach a sound conclusion...

整个过程完美验证了 Agent Skill 的三步运行逻辑：扫描 → 激活 → 执行。

六、知识地图总览

七、关键记忆点

#	要点	一句话总结
1️⃣	Skills 本质	Skills = 文件夹 = 指令 + 脚本 + 资源
2️⃣	核心字段	`description` 是 Agent 决策依据，务必写清"何时使用"
3️⃣	加载策略	元数据始终加载、正文按需加载、辅助资源按需调用
4️⃣	环境要求	WSL Ubuntu + Python 3.12 + venv
5️⃣	关键依赖	`deepagents >= 0.2.8`，需修改 `pyproject.toml`
6️⃣	安全原则	沙箱运行 + 相对路径 + API-KEY 只读 + 白名单域名

八、写在最后

Agent Skills 提供了一个优雅的解法：

它把工具的"使用说明"从 prompt 中剥离出来，以文件系统作为载体，让 Agent 像加载 App 一样按需加载技能。这不仅解决了上下文危机，更让企业的隐性知识得以版本化、可移植、可复用。

如果你也在为 Agent 的工具管理头疼，不妨试试 LangChain DeepAgent + Agent Skills 的组合。

📚 参考资料

Anthropic: Introducing Agent Skills

LangChain DeepAgents GitHub

DeepAgent-CLI 官方示例

Ai, LangChain

许可协议: CC BY 4.0