概述

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 and domain knowledge.

{skills_locations}

**Available Skills:**

{skills_list}

**How to Use Skills (Progressive Disclosure):**

Skills follow a **progressive disclosure** pattern - you see their name and description above, but only read full instructions when needed:

1. **Recognize when a skill applies**: Check if the user's task matches a skill's description
2. **Read the skill's full instructions**: Use the path shown in the skill list above
3. **Follow the skill's instructions**: SKILL.md contains step-by-step workflows, best practices, and examples
4. **Access supporting files**: Skills may include helper scripts, configs, or reference docs - use absolute paths

**When to Use Skills:**
- User's request matches a skill's domain (e.g., "research X" -> web-research skill)
- You need specialized knowledge or structured workflows
- A skill provides proven patterns for complex tasks

**Executing Skill Scripts:**
Skills may contain Python scripts or other executable files. Always use absolute paths from the skill list.

**Example Workflow:**

User: "Can you research the latest developments in quantum computing?"

1. Check available skills -> See "web-research" skill with its path
2. Read the skill using the path shown
3. Follow the skill's research workflow (search -> organize -> synthesize)
4. Use any helper scripts with absolute paths

Remember: Skills make you more capable and consistent. When in doubt, check if a skill exists for the task!

技能名称验证规则

根据 Agent Skills 规范：
最多64个字符
仅限小写字母数字和连字符（a-z, 0-9, -）
不能以连字符开头或结尾
不能有连续连字符
必须与父目录名称匹配

安全限制

SKILL.md 文件最大大小：10MB（防止 DoS 攻击）
技能名称最大长度：64字符
描述最大长度：1024字符

路径约定

所有路径使用 POSIX 约定（正斜杠）通过 PurePosixPath：

后端路径：”/skills/user/web-research/SKILL.md”
虚拟、平台无关
后端根据需要处理平台特定的转换

渐进式披露模式

技能遵循渐进式披露模式：
首先看到名称和描述
仅在需要时读取完整指令

SKILL.md 包含分步工作流程、最佳实践和示例
可使用绝对路径访问支持文件