SkillsMiddleware解析
SkillsMiddleware-中间件形式让平台集成skill能力
概述
SkillsMiddleware 是 DeepAgents 框架中用于加载和暴露 agent 技能到系统提示的中间件。它实现了 Anthropic 的 agent skills 模式，支持渐进式披露（progressive disclosure），从可配置的后端存储源加载技能。
架构设计
技能加载机制
技能从一个或多个源（sources）加载 – 后端中组织技能的路径。源按顺序加载，当技能名称相同时，后面的源会覆盖前面的源（last one wins）。这支持分层架构：base -> user -> project -> team skills。
中间件完全使用后端 API（不直接访问文件系统），使其可移植到不同的存储后端（文件系统、状态、远程存储等）。
技能结构
每个技能是一个包含 SKILL.md 文件的目录：
/skills/user/web-research/
├── SKILL.md # 必需：YAML前置数据 + markdown指令
└── helper.py # 可选：支持文件
SKILL.md 格式
---
name: web-research
description: Structured approach to conducting thorough web research
license: MIT
---
# Web Research Skill
## When to Use
- User asks you to research a topic
…
核心组件
SkillMetadata
从 YAML 前置数据解析的技能元数据：
字段 类型 说明
name str 技能标识符（最多64字符，小写字母数字和连字符）
description str 技能功能描述（最多1024字符）
path str SKILL.md 文件的后端路径
license str | None 许可证名称或捆绑许可证文件引用
compatibility str | None 环境要求（最多500字符）
metadata dict 附加元数据的键值映射
allowed_tools list 预批准工具列表（实验性）
SkillsState
技能中间件的状态定义：
class SkillsState(AgentState):
skills_metadata: NotRequired[Annotated[list[SkillMetadata], PrivateStateAttr]]
SkillsMiddleware
主要的中间件类，继承自 AgentMiddleware。
初始化参数
参数 类型 说明
backend BACKEND_TYPES 后端实例或工厂函数
sources list[str] 技能源路径列表
核心方法
before_agent(state, runtime, config) – 同步版本，在 agent 执行前加载技能元数据
abefore_agent(state, runtime, config) – 异步版本
wrap_model_call(request, handler) – 同步版本，将技能文档注入系统提示
awrap_model_call(request, handler) – 异步版本
modify_request(request) – 将技能文档注入模型请求的系统消息
使用示例
from deepagents.backends.state import StateBackend
from deepagents.middleware.skills import SkillsMiddleware
# 使用后端实例
middleware = SkillsMiddleware(
backend=my_backend,
sources=[
"/skills/base/",
"/skills/user/",
"/skills/project/",
],
)
# 使用工厂函数（适用于 StateBackend）
middleware = SkillsMiddleware(
backend=lambda rt: StateBackend(rt),
sources=["/skills/user/"],
)
系统提示模板
中间件会将以下内容注入系统提示：
## Skills System
You have access to a skills library that provides specialized capabilities...
**Available Skills:**
- **web-research**: Structured approach to conducting thorough web research
-> Read `/skills/user/web-research/SKILL.md` for full instructions
**How to Use Skills (Progressive Disclosure):**
1. Recognize when a skill applies
2. Read the skill's full instructions
3. Follow the skill's instructions
4. Access supporting files
技能名称验证规则
根据 Agent Skills 规范：
最多64个字符
仅限小写字母数字和连字符（a-z, 0-9, -）
不能以连字符开头或结尾
不能有连续连字符
必须与父目录名称匹配
安全限制
SKILL.md 文件最大大小：10MB（防止 DoS 攻击）
技能名称最大长度：64字符
描述最大长度：1024字符
路径约定
所有路径使用 POSIX 约定（正斜杠）通过 PurePosixPath：
后端路径：”/skills/user/web-research/SKILL.md”
虚拟、平台无关
后端根据需要处理平台特定的转换
渐进式披露模式
技能遵循渐进式披露模式：
首先看到名称和描述
仅在需要时读取完整指令
SKILL.md 包含分步工作流程、最佳实践和示例
可使用绝对路径访问支持文件
