SKILL.md 文件结构
每个 Skill 的核心是一个名为 SKILL.md 的文件。这个文件由两部分组成：Frontmatter 元数据和 Markdown 指令。

Frontmatter 元数据位于文件开头，采用 YAML 格式，定义了技能的名称、描述等关键信息。其中，description 字段尤为重要，它直接决定了 Agent 能否在正确的时机找到并使用该技能。一个好的描述应该简洁明确，并包含触发条件，让 Agent 一看就知道"什么场景下该用我"。

Markdown 指令部分则是技能的具体内容，告诉 Agent 拿到这个技能之后该怎么做、按什么步骤执行、有哪些注意事项。这部分内容会被注入到 Agent 的上下文中，指导它完成任务。

---
name: code-review
description: 审查代码质量、检查常见问题。当用户要求代码审查时使用。
---
 
# 代码审查
 
审查代码文件，检查以下问题：
- 语法错误和潜在 Bug
- 代码风格和规范
- 性能问题
- 安全漏洞
 
## 使用方法
 
当用户要求审查代码时，执行：
 
```bash
python /skills/code-review/scripts/review.py <file_path>
```
 
## 输出格式
 
按严重程度分类：
- 🔴 严重问题（必须修复）
- 🟡 警告（建议改进）
- 🟢 提示（可选优化）

Skills 的执行流程
理解了文件结构，再来看 Skill 是如何运作的。整个执行流程可以分为三个阶段：扫描匹配、加载注入、执行反馈。

当用户输入一个请求时，Agent 首先扫描 skills 目录下所有 SKILL.md 的前置元数据，提取各技能的名称与描述，生成可用技能清单。然后，Agent 将用户请求与清单中的描述进行语义匹配。一旦找到合适的技能，就调用 load_skill 方法将该技能的完整提示指令加载到对话上下文中。最后，Agent 按照加载的指令执行任务，并将结果返回给用户。

这个过程对用户来说是透明的。用户只需要表达意图，Agent 会自动找到并使用合适的技能完成任务。

 实践：集成代码审查 Skill

理论讲完了，接下来通过一个完整的示例来演示如何将 Skill 集成到 Agent 中。我们已经创建好了一个代码审查 Skill，现在要让它工作起来。

首先需要安装 deepagents 开发包。

pip install deepagents

需要注意的是，deepagents 目前不支持通过 init_chat_model 构造的模型 对象，因此需要调整模型的初始化方式。

最关键的是 create_deep_agent 的调用，其中 skills 参数指定了技能目录。

create_deep_agent 默认使用内存后端 StateBackend，无法读取本地文件系统。如果要加载磁盘上的 Skill 文件，必须显式传入 FilesystemBackend。这是一个容易忽略的配置点。

import os
from dotenv import load_dotenv
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model
from langchain_core.tools import BaseTool
from langchain_community.tools import WriteFileTool, ReadFileTool, ListDirectoryTool
from deepagents.backends import FilesystemBackend
 
load_dotenv()
 
# 使用 configurable_fields 创建可配置模型
# model = init_chat_model(
#     model_provider="openai",
#     configurable_fields=["model", "api_key", "base_url"],
#     config_prefix="QWEN"
# ).with_config({
#     "configurable": {
#         "QWEN_model": os.getenv("QWEN_MODEL"),
#         "QWEN_api_key": os.getenv("QWEN_API_KEY"),
#         "QWEN_base_url": os.getenv("QWEN_BASE_URL")
#     }
# })
 
os.environ["OPENAI_API_KEY"] = os.getenv("QWEN_API_KEY")
os.environ["OPENAI_BASE_URL"] = os.getenv("QWEN_BASE_URL")
model = f"openai:{os.getenv('QWEN_MODEL')}"
 
 
class CalculateTool(BaseTool):
    name: str = "calculate"
    description: str = "计算数学表达式的值"
 
    def _run(self, expression: str) -> str:
        try:
            return f"计算结果: {eval(expression)}"
        except Exception as e:
            return f"计算错误: {str(e)}"
 
    async def _arun(self, expression: str) -> str:
        return self._run(expression)
 
 
# ========== 初始化工具 ==========
 
calculate = CalculateTool()
write_file = WriteFileTool()
read_file = ReadFileTool()
list_dir = ListDirectoryTool()
 
 
 
# ========== 创建 Deep Agent ==========
agent = create_deep_agent(
    model=model,
    tools=[calculate, write_file, read_file, list_dir],
    system_prompt="你是一个助手，会用工具计算、读写文件、列出目录。",
    skills=["skills"],
    backend=FilesystemBackend(root_dir=os.getcwd()),
    debug=True
)
 
queries = [
    "审查 mcp_weather.py 代码",
    "计算 2024*12+500，然后把结果保存到 result.txt",
    "读取 result.txt 的内容",
    "列出当前目录文件"
]
 
for q in queries:
    print(f"\n问：{q}")
    result = agent.invoke({"messages": [{"role": "user", "content": q}]})
    print(f"答：{result['messages'][-1].content}")