## 1. 什么是 Skills

Skills 是 LangChain 官方在 multi-agent 架构中提出的**以 Prompt 为核心的专业化能力模块**，灵感来自 Claude Code 的 skills 设计。
核心思想是 **Progressive Disclosure（渐进式信息披露）**：不把所有专业知识一次性塞进 system prompt，而是让 Agent 在需要时按需加载对应领域的专家 prompt，从而节省 context window。
### 核心特征


|特征|说明|
|:-:|:-:|
|Prompt 驱动|Skill 的本质是一段专业领域的 prompt，而非代码逻辑|
|按需加载|Agent 根据用户问题判断需要哪个 Skill，再动态加载|
|自动发现|SkillMiddleware 自动把所有 Skill 的简短描述注入 system prompt|
|团队解耦|不同团队可以独立开发和维护各自的 Skill（只需新建 .md 文件）|
|数据注入|需要案件数据的 Skill 在加载时自动注入相关数据|
### 工作流程

```bash
启动时：SkillMiddleware 扫描 skills/ 目录
        → 把所有 Skill 的 name + description 注入 system prompt
              ↓
用户提问 → Agent 看到 system prompt 里的 Skill 列表
        → 判断需要哪个 Skill
        → 调用 load_skill("skill_name")
        → 获得完整 prompt + 自动注入的案件数据
        → 基于专业知识回答
```

----
## 2. Skills vs Tools 的区别

>**Tools = 执行动作（调 API、查数据库）；Skills = 加载专业知识（注入专家 prompt）**


|对比维度|Tools|Skills|
|:-:|:-:|:-:|
|本质|可执行的函数|专业领域的 prompt|
|用途|与外部系统交互|注入领域专业知识|
|输出|数据、操作结果|专家指导原则和上下文|
|典型场景|搜索网页、执行 SQL|成为 SQL 专家、审查专家|
Skills 在技术实现上也是一个 Tool（`load_skill`），只不过它的返回值是 prompt 文本。


----
## 3. 项目结构

```bash
langchain-skills/
├── skills/
│   ├── __init__.py
│   ├── base.py                    # Skill TypedDict + 自动扫描加载
│   ├── sql_expert.md              # SQL 专家 Skill
│   ├── code_review.md             # 代码审查 Skill
│   └── order_support.md           # 订单支持 Skill（示例）
├── docs/
│   └── tutorial.md                # 本文档
├── agent.py                       # Agent 创建（create_agent + SkillMiddleware）
├── skill_loader.py                # load_skill tool + SkillMiddleware
├── merge_case_infos.py            # 数据合并脚本（JSON → Markdown 表格）
├── main.py                        # 交互式命令行入口
├── merged_case_infos.md           # 合并后的数据（Markdown 表格格式）
├── pyproject.toml                 # uv 项目配置
├── uv.lock                        # 依赖锁定文件
└── .env                           # 环境变量
```

----
## 4. 环境搭建

本项目使用 [uv](https://docs.astral.sh/uv/) 作为包管理工具。
### 安装 uv

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### 安装依赖

```bash
# 根据 uv.lock 安装精确版本
uv sync
```
### 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY（使用本地 vllm 则无需配置）
```
### 运行

```bash
uv run main.py
```
### 常用 uv 命令

```bash
uv add <package>     # 添加依赖
uv remove <package>  # 移除依赖
uv sync              # 同步环境
uv run <script.py>   # 在虚拟环境中运行脚本
```

----
## 5. 核心模块详解

### 5.1 Skill 数据结构（`skills/base.py`）

遵循官方的 `TypedDict` 定义，三个字段职责分明：
```python
from typing import TypedDict

class Skill(TypedDict):
    name: str         # 唯一标识，对应 .md 文件名（不含扩展名）
    description: str  # 1-2句简短描述 → 注入 system prompt，供 LLM 发现
    content: str      # 完整专家 prompt → 仅在 load_skill 调用时加载
```
`description` 和 `content` 的分离是 Progressive Disclosure 的关键：
- LLM 启动时只看到轻量的 `description`，知道有哪些技能
- 只有真正需要时才通过 `load_skill` 加载完整的 `content`

**自动扫描加载**：
```bash
def load_skills_from_dir(skills_dir: Path) -> list[Skill]:
    """扫描目录，自动把所有 .md 文件加载为 Skill"""
    skills = []
    for md_file in sorted(skills_dir.glob("*.md")):
        text = md_file.read_text(encoding="utf-8")
        description = text.splitlines()[0].lstrip("# ").strip()  # 取第一行标题
        skills.append(Skill(name=md_file.stem, description=description, content=text))
    return skills
```
新增 Skill 只需新建 `.md` 文件，无需修改任何代码。
### 5.2 load_skill Tool（`skill_loader.py`）

```python
@tool
def load_skill(skill_name: str) -> str:
    """Load the full content of a skill into the agent's context."""
    for skill in SKILLS:
        if skill["name"] == skill_name:
            content = skill["content"]
            # 自动注入该 skill 所需的案件数据
            sources = SKILL_DATA_SOURCES.get(skill_name, [])
            if sources:
                case_data = _fetch_case_data(sources)
                if case_data:
                    content += f"\n\n---\n## 案件データ\n\n{case_data}"
            return f"Loaded skill: {skill_name}\n\n{content}"

    available = ", ".join(s["name"] for s in SKILLS)
    return f"Skill '{skill_name}' not found. Available skills: {available}"
```
**数据自动注入**：通过 `SKILL_DATA_SOURCES` 字典声明每个 Skill 需要哪些数据源，加载时自动从 `merged_case_infos.md` 中过滤并附加，LLM 不需要自己决定读什么数据：
```python
SKILL_DATA_SOURCES: dict[str, list[str]] = {    "order_support": ["订单信息", "用户信息"],    # 新增 skill 需要数据时，在这里声明即可}
```
### 5.3 SkillMiddleware（`skill_loader.py`）

这是与旧版最大的架构差异。官方通过 Middleware 在每次模型调用前自动把 Skill 列表注入 system prompt：
```python
class SkillMiddleware(AgentMiddleware):
    tools = [load_skill]  # 注册 load_skill tool

    def __init__(self):
        # 构建轻量的 skills 描述列表
        skills_list = [f"- **{s['name']}**: {s['description']}" for s in SKILLS]
        self.skills_prompt = "\n".join(skills_list)

    def wrap_model_call(self, request, handler):
        # 在 system prompt 末尾追加 skills 列表
        skills_addendum = (
            f"\n\n## Available Skills\n\n{self.skills_prompt}\n\n"
            "Use the `load_skill` tool when you need detailed knowledge "
            "for a specific domain."
        )
        new_content = list(request.system_message.content_blocks) + [
            {"type": "text", "text": skills_addendum}
        ]
        modified_request = request.override(
            system_message=SystemMessage(content=new_content)
        )
        return handler(modified_request)
```
LLM 每次调用时看到的 system prompt 末尾会自动追加：
```markdown
## Available Skills
​
- **sql_expert**: SQL Expert Skill
- **code_review**: Code Review Skill
- **order_support**: 订单查询与售后支持专家
​
Use the `load_skill` tool when you need detailed knowledge for a specific domain.
```
### 5.4 Agent 创建（`agent.py`）

使用官方的 `create_agent` + `SkillMiddleware`，并配置 `InMemorySaver` 支持多轮对话记忆：
```python
from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver

def create_skills_agent(...):
    llm = QwenThinkingChatOpenAI(...)  # 或普通 ChatOpenAI

    agent = create_agent(
        llm,
        system_prompt="你是一个智能助手，可以借助专业技能回答各类问题。",
        middleware=[SkillMiddleware()],
        checkpointer=InMemorySaver(),   # 多轮对话记忆
    )
    return agent
```
**与旧版对比**：

|旧版|新版（官方方式）|
|:-:|:-:|
|Skill 定义|`.md` 文件 + 分离字典|`TypedDict(name, description, content)`|
|Skill 发现|手写在 system prompt|`SkillMiddleware` 自动注入|
|`list_skills` tool|需要|不需要（已删除）|
|对话记忆|无|`InMemorySaver` checkpointer|
|Agent 创建|`create_react_agent`|`create_agent` + `middleware`|


----
## 6. 案件数据处理

### 6.1 为什么用 Markdown 表格而不是 JSON

案件数据原始格式是 JSON，但传给 LLM 时 JSON 的结构符号（`{}`、`[]`、`""`）会消耗大量 token。
各格式 token 对比（240条数据）：

|格式|大约字符数|相对JSON|
|:-:|:-:|:-:|
|JSON|~15,500|基准|
|YAML|~11,000|-29%|
|Markdown 表格|~10,000|-35%|
|CSV|~9,000|-42%|
选择 Markdown 表格的原因：
- token 比 JSON 少约 35%
- LLM 对表格格式理解最自然
- value 里有冒号、换行等特殊符号时不会破坏结构（CSV 需要额外处理引号）

### 6.2 合并脚本（`merge_case_infos.py`）

从原始 JSON 数据中递归提取所有 `case_infos`，去重后输出为 Markdown 表格：
```python
def merge_case_infos(input_file: str, output_file: str = "merged_case_infos.md"):
    # 递归收集所有 case_infos，用 (source, item_name, values) 去重
    ...
    # 输出 Markdown 表格，竖线符号自动转义
    lines = ["| source | item_name | value |", "|--------|-----------|-------|"]
    for item in merged:
        v_escaped = str(v).replace("|", "\\|")  # 转义 | 防止破坏表格
        lines.append(f"| {source} | {item_name} | {v_escaped} |")
```
运行方式：
```bash
python merge_case_infos.py
# 输入: data.json
# 输出: merged_case_infos.md
```
### 6.3 数据过滤注入

`_fetch_case_data` 从 `merged_case_infos.md` 中按 source 过滤，只取 Skill 需要的行：
```python
def _fetch_case_data(sources: list[str]) -> str:
    all_lines = CASE_DATA_FILE.read_text(encoding="utf-8").splitlines()
    header = all_lines[:2]   # 保留表头
    data_rows = all_lines[2:]
    # 按 source 过滤，只取相关行
    filtered = [row for row in data_rows if any(f"| {s} |" in row for s in sources)]
    return "\n".join(header + filtered)
```
这样 `order_support` 只会拿到 `订单信息` 和 `用户信息` 的数据，而不是全量数据。


----
## 7. 运行与使用

### 启动

```bash
uv run main.py
```
### 交互示例

```bash
=== LangChain Skills Agent ===
输入 'quit' 退出

你: 帮我写一个查询最近30天销售额的 SQL
Agent 思考中...

Agent: 我来加载 SQL 专家技能为你解答。

```sql
-- 查询最近 30 天的销售总额
SELECT
    DATE(order_date) AS date,
    SUM(amount)      AS daily_revenue
FROM orders
WHERE order_date >= CURRENT_DATE - INTERVAL '30 days'
  AND status = 'completed'
GROUP BY DATE(order_date)
ORDER BY date DESC;
```
性能说明：建议在 order_date 和 status 上建立复合索引。
```bash
​
### Agent 内部执行流程
```
```markdown
system prompt（启动时由 SkillMiddleware 注入）:   你是一个智能助手...
## Available Skills

- sql_expert: SQL Expert Skill
- code_review: Code Review Skill
- order_support: 订单查询与售后支持专家 ...

用户: 帮我写一个查询最近30天销售额的 SQL   ↓ Agent 识别需要 sql_expert   ↓ 调用 load_skill("sql_expert")   ↓ 返回: SQL 专家完整 prompt   ↓ Agent 基于专业知识输出 SQL 及说明
```
​
---
​
## 8. 扩展新 Skill
​
只需一步：在 `skills/` 目录下新建 `.md` 文件。
​
### 示例：新增订单支持 Skill
​
新建 `skills/order_support.md`：
​
```markdown
# 订单查询与售后支持专家
​
你是电商平台的订单支持专家。
​
## 处理范围
- 订单状态查询
- 退换货申请
- 物流异常处理
- 发票开具
​
## 处理原则
- 签收后 7 天内支持无理由退货
- 商品质量问题支持 30 天退换
- 退款到账时间：原路退回 3-5 个工作日
​
## 输出格式
1. 问题确认
2. 处理方案
3. 预计时效
```
完成。下次启动时 `SkillMiddleware` 自动扫描到这个文件，LLM 就能发现并使用它。
### 如果新 Skill 需要外部数据

在 `skill_loader.py` 的 `SKILL_DATA_SOURCES` 里声明需要的 source：
```python
SKILL_DATA_SOURCES: dict[str, list[str]] = {
    "order_support": ["订单信息", "用户信息"],
    "inventory_check": ["库存信息"],   # 新增这一行
}

```

----
## 9. 适配本地 vllm 模型（Qwen3）

使用本地 vllm 部署的 Qwen3 模型时，有两个兼容性问题需要处理。
### 9.1 问题一：content 为空

Qwen3 默认开启 thinking 模式，把输出放在 `reasoning_content` 字段，`content` 为 `null`。
原始 vllm 响应：
```json
{
  "choices": [{
    "message": {
      "content": null,
      "reasoning_content": "你好！有什么可以帮你的吗？"
    }
  }]
}
```
### 9.2 问题二：tool_calls 为空

vllm 的 Qwen3 部署不走标准的 function calling，而是把 tool call 也放在 `reasoning_content` 里：
```json
{
  "message": {
    "content": null,
    "tool_calls": [],
    "reasoning_content": "<tool_call>\n{\"name\": \"load_skill\", \"arguments\": {\"skill_name\": \"sql_expert\"}}\n</tool_call>"
  }
}
```
### 9.3 解决方案：QwenThinkingChatOpenAI

继承 `ChatOpenAI`，重写 `_create_chat_result`，统一处理两种情况：
```python
class QwenThinkingChatOpenAI(ChatOpenAI):

    def _create_chat_result(self, response, generation_info=None) -> ChatResult:
        result = super()._create_chat_result(response, generation_info)
        fixed = []
        for gen in result.generations:
            msg = gen.message
            # 取 reasoning_content
            reasoning = getattr(response.choices[0].message, "reasoning_content", "") or ""

            if reasoning and "<tool_call>" in reasoning:
                # 情况1：reasoning_content 里有 tool call → 解析为 tool_calls
                parsed_calls = _parse_tool_calls_from_text(reasoning)
                msg = AIMessage(content="", tool_calls=parsed_calls, ...)
            elif not msg.content and reasoning:
                # 情况2：普通回答放在 reasoning_content → 映射到 content
                msg = AIMessage(content=reasoning, tool_calls=[], ...)

            fixed.append(ChatGeneration(message=msg))
        return ChatResult(generations=fixed, llm_output=result.llm_output)
```
`_parse_tool_calls_from_text` 用正则解析 `<tool_call>` 标签：
```python
def _parse_tool_calls_from_text(text: str) -> list[dict]:
    pattern = r"<tool_call>\s*(\{.*?\})\s*</tool_call>"
    matches = re.findall(pattern, text, re.DOTALL)
    return [
        {"name": p["name"], "args": p.get("arguments", {}), "id": f"call_{i}", "type": "tool_call"}
        for i, m in enumerate(matches)
        if (p := json.loads(m))
    ]
```
### 9.4 配置方式

```python
llm = QwenThinkingChatOpenAI(
    model="Qwen3-30B-A3B-Instruct-2507-FP8",
    temperature=0.1,
    base_url="http://your-vllm-host:8008/v1",
    api_key="vllm",                          # vllm 不校验 key，随便填
    extra_body={"enable_thinking": False},   # 尝试关闭 thinking 模式
)
```
>`QwenThinkingChatOpenAI` 作为兜底，无论 `enable_thinking` 是否生效都能正确处理响应。


----
## 10. 常见问题排查

### Q1: Agent 响应为空

检查 `AIMessage.content` 是否为空但 `output_tokens > 0`，说明是 Qwen3 thinking 模式问题，参考第 9 节。
调试方法：
```python
result = agent.invoke({"messages": [("user", user_input)]}, config)
for msg in result["messages"]:
    print(type(msg).__name__, repr(msg.content), getattr(msg, "tool_calls", None))
```
### Q2: `create_agent() got unexpected keyword arguments`

LangChain 版本迭代较快，查看当前支持的参数：
```bash
uv run python -c "import inspect; from langchain.agents import create_agent; print(inspect.signature(create_agent))"
```
### Q3: 超出 token 限制

- 检查 `SKILL_DATA_SOURCES` 是否过滤了正确的 source，避免注入全量数据
- 重新运行数据合并脚本确认输出是 Markdown 表格格式（而非 JSON）
- 精简 Skill 的 `content`，去掉冗余说明

### Q4: 新建的 Skill 没有被发现

确认 `.md` 文件放在 `skills/` 目录下，且文件名不含空格。重启 `main.py` 后生效（启动时扫描）。


----
## 11. 进阶扩展方向

### 11.1 异步 Middleware

```python
class SkillMiddleware(AgentMiddleware):
    async def awrap_model_call(self, request, handler):
        # 异步版本，适合高并发场景
        ...
```
### 11.2 层级 Skills（技能树）

在 Skill content 里声明子技能，实现按需深入加载：
```markdown
# Data Science Skill

数据科学父技能。子技能：
- pandas_expert: Pandas 数据处理
- visualization: 数据可视化

需要时用 load_skill 加载对应子技能。。
```
### 11.3 持久化对话历史

将 `InMemorySaver` 替换为数据库存储：
```python
from langgraph.checkpoint.postgres import PostgresSaver

checkpointer = PostgresSaver.from_conn_string("postgresql://...")
agent = create_agent(..., checkpointer=checkpointer)
```
### 11.4 多用户隔离

每个用户使用独立的 `thread_id`：
```python
config = {"configurable": {"thread_id": f"user_{user_id}"}}
agent.invoke({"messages": [...]}, config)
```

----
## 依赖版本参考

```yaml
[project]
name = "langchain-skills"
version = "0.1.0"
requires-python = ">=3.13"
dependencies = [
    "langchain>=1.2.15",
    "langchain-openai>=1.1.12",
    "langgraph>=1.1.6",
    "python-dotenv>=1.2.2",
]
```

----
参考资料：[LangChain 官方 Skills 文档](https://docs.langchain.com/oss/python/langchain/multi-agent/skills-sql-assistant)

Skills 是 LangChain 官方在 multi-agent 架构中提出的以 Prompt 为核心的专业化能力模块，灵感来自 Claude Code 的 skills 设计。核心思想是 Progressive Disclosure（渐进式信息披露）：不把所有专业知识一次性塞进 system prompt，而是让 Agent 在需要时按需加载对应领域的专家 prompt，从而节省 context window。

LangChain Skills 框架教学文档

Skills 是 LangChain 官方在 multi-agent 架构中提出的以 Prompt 为核心的专业化能力模块，灵感来自 Claude Code 的 skills 设计。核心思想是 Progressive Disclosure（渐进式信息披露）：不把所有专业知识一次性塞进 system prompt，而是让 Agent 在需要时按需加载对应领域的专家 prompt，从而节省 conte

测试开发工程师

LangChain Skills是一种基于Prompt的专业化能力模块，采用渐进式信息披露设计，按需加载专家Prompt以节省上下文窗口。与Tools不同，Skills专注于注入领域知识而非执行动作。项目支持自动发现、团队解耦和数据注入，通过SkillMiddleware实现动态加载。使用Markdown表格优化数据token消耗，支持本地vllm模型适配，是构建高效AI代理的理想解决方案。

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云AI代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

功能1上新10个字符

功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符功能2描述100个字符。

功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符功能2上新100个字符。

功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符功能5描述100个字符

功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符功能5上新100个字符

功能4上新

文章&问答评论现已支持表情

全新交互，全新视觉，新增快捷键、悬浮工具栏、高亮块等功能并同时优化现有功能，全面提升创作效率和体验

社区富文本编辑器全新改版！诚邀体验～ 

精选全网热门MCP server，让你的AI更好用 🚀

💥开发者 MCP广场重磅上线！

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

LangChain Skills是一种基于Prompt的专业化能力模块，采用渐进式信息披露设计，按需加载专家Prompt以节省上下文窗口。与Tools不同，Skills专注于注入领域知识而非执行动作。项目支持自动发现、团队解耦和数据注入，通过SkillMiddleware实现动态加载。使用Markdown表格优化数据t...

LangChain Skills 框架教学文档-腾讯云开发者社区-腾讯云

LangChain Skills 框架教学文档

LangChain Skills 框架教学文档

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐