Skill 系统实现对比分析文档

May 16, 2026

xiwang

全栈开发者

本文档深入分析DeerFlow系统中Skill功能的实现机制，并与官方Claude Code的Skill系统实现进行对比，总结两者的异同点及背后的设计考量。

一、DeerFlow 系统 Skill 实现分析

1.1 系统定位

DeerFlow的Skill系统是一套可扩展的技能机制，允许用户安装、管理和使用预定义的工作流模板，每个Skill包含最佳实践、操作框架和相关资源，为AI Agent提供特定任务的标准化执行流程。

1.2 定义格式

每个Skill以独立目录形式存在，核心文件为SKILL.md，采用Markdown + YAML Frontmatter格式：

必填字段: name（技能名称，短横线命名法）、description（技能描述）
可选字段: license、allowed-tools、metadata、compatibility、version、author
正文内容: 技能的具体执行流程、使用说明、参考资源等

1.3 存储结构

skills/
├── public/          # 公共技能，随代码库提交
│   └── [skill-name]/
│       ├── SKILL.md
│       └── 其他资源文件
└── custom/          # 用户自定义安装的技能，git忽略
    └── [skill-name]/
        └── SKILL.md

1.4 加载流程

扫描: loader.py的load_skills()函数递归扫描public和custom目录，查找所有SKILL.md文件
解析: parser.py的parse_skill_file()提取YAML Frontmatter，解析为Skill数据对象
状态同步: 从extensions_config.json读取技能启用状态，更新Skill.enabled属性
返回: 按名称排序的Skill列表

1.5 调用与执行逻辑

注入: 已启用的技能会在Agent启动时以XML格式注入到系统提示词中，包含技能名称、描述和文件路径
触发: 当用户请求匹配技能使用场景时，Agent自动调用read_file读取技能内容
执行: Agent按照技能定义的步骤执行任务，按需加载技能目录下的其他参考资源

1.6 安全机制

安装安全：压缩包路径校验，防止目录穿越攻击，自动跳过符号链接，总大小限制512MB
内容校验：严格验证SKILL.md Frontmatter格式和字段合法性
权限控制：自定义技能与公共技能隔离，技能在容器内以只读方式挂载

1.7 核心模块与文件

模块	文件路径	功能说明
类型定义	`/backend/packages/harness/deerflow/skills/types.py`	Skill数据类定义
加载逻辑	`/backend/packages/harness/deerflow/skills/loader.py`	技能扫描、加载逻辑
解析逻辑	`/backend/packages/harness/deerflow/skills/parser.py`	SKILL.md文件解析
安装逻辑	`/backend/packages/harness/deerflow/skills/installer.py`	技能安装、安全校验
API路由	`/backend/app/gateway/routers/skills.py`	技能管理API接口
运行时注入	`/backend/packages/harness/deerflow/agents/lead_agent/prompt.py`	技能注入Agent系统提示词

二、官方 Claude Code Skill 实现分析

2.1 系统定位

Skills是Claude Code的模块化扩展组件，用于为Claude提供特定领域的专业知识、标准化工作流、工具集成能力和业务逻辑，将通用AI代理转变为面向特定任务的专业化代理。

2.2 定义格式

每个Skill完全自包含，核心文件为SKILL.md：

YAML Frontmatter必填字段: name（技能名称）、description（触发条件/使用场景描述）
可选字段: version、author、license、allowed-tools
正文内容: 技能的系统提示、执行规则、工作流步骤、工具使用规范等
面向Agent类型的Skill还支持JSON格式定义，包含identifier、whenToUse、systemPrompt字段

2.3 存储结构

skill-name/
├── SKILL.md          # 核心技能定义文件（必选）
├── references/       # 参考文档资源（可选）
├── examples/         # 示例代码/配置（可选）
└── scripts/          # 配套执行脚本（可选）

所有Skill统一存放在插件的skills/目录下的独立子目录中。

2.4 加载流程

采用三级渐进式加载机制：

启动扫描阶段: Claude Code启动时自动扫描所有插件的skills/目录，仅加载元数据（name/description/version）到常驻内存
触发加载阶段: 当用户查询或任务上下文匹配到技能的description描述时，加载对应技能的SKILL.md正文内容到当前会话上下文
按需加载阶段: 技能执行过程中需要参考文档、示例、脚本等资源时，动态加载对应目录下的资源文件

2.5 调用与执行逻辑

触发方式:
- 隐式触发：任务上下文和技能description中的触发描述匹配时自动激活
- 显式触发：用户执行/skill <skill-name> [args]命令主动调用
执行流程:
- 技能激活后，系统将技能定义的规则、工作流、系统提示词注入当前会话上下文
- Claude按照技能定义的逻辑和约束执行任务，可调用技能配套的脚本、工具和资源
结果处理: 技能执行结果直接返回会话上下文，可作为后续任务的输入

2.6 架构设计

插件化架构: Skill是Claude Code插件系统的核心组件之一，与commands、agents、hooks、MCP工具等组件并行
分层披露设计: 三级加载机制避免不必要的上下文占用，平衡性能和功能完整性
完全自包含设计: 每个Skill独立打包、分发、安装，无外部依赖
无侵入集成: 技能不需要编译或打包，直接以纯文本格式分发

三、异同点对比

3.1 相同点

维度	共性描述
定义格式	都采用`SKILL.md`作为核心定义文件，使用YAML Frontmatter + Markdown正文格式，必填字段都包含`name`和`description`
存储结构	都采用独立目录存储每个Skill，支持配套资源文件（参考文档、示例、脚本等）
核心目标	都是为了提供标准化的工作流模板，扩展Agent的专业能力，处理特定领域的复杂任务
执行逻辑	都是将技能内容注入到Agent的上下文，让Agent按照技能定义的规则执行任务
扩展性	都支持用户自定义技能，无需修改核心代码即可扩展功能
安全性	都有严格的安全校验机制，防止恶意技能注入和攻击

3.2 不同点

维度	DeerFlow Skill系统	官方Claude Code Skill系统
加载机制	一次性加载所有已启用技能的元数据和路径信息到Agent系统提示	采用三级渐进式加载，仅在匹配到触发条件时才加载技能正文，按需加载资源
触发方式	仅支持隐式触发，依赖Agent自动识别匹配场景	支持隐式自动触发和显式命令触发（`/skill`命令）
架构定位	是DeerFlow系统的内置核心功能，与Agent系统深度集成	是Claude Code插件系统的一部分，与其他插件组件（commands、agents等）并行
技能分类	明确分为`public`（内置公共技能）和`custom`（用户自定义技能）两类	无明确分类，由插件目录结构自然区分
状态管理	有完整的启用/禁用状态管理，通过`extensions_config.json`配置，支持动态修改	依赖插件的启用/禁用机制，无单独的技能状态管理
资源加载	Agent需要主动调用`read_file`读取技能内容	系统自动加载匹配的技能内容到上下文，无需Agent主动读取
参数支持	无显式参数传递机制，参数从会话上下文提取	支持通过`Skill`工具的`args`参数显式传递参数

四、设计考量分析

4.1 DeerFlow 设计考量

深度集成优先: DeerFlow作为专门的Agent协作平台，需要技能系统与核心Agent流程深度耦合，因此采用一次性注入所有技能信息的方式，确保Agent可以随时访问所有可用技能
集中管理优先: 明确的技能分类和状态管理机制，方便平台管理员统一管控可用技能，适合企业级部署场景
安全性优先: 严格的容器隔离和只读挂载机制，保障多租户环境下的技能使用安全

4.2 官方 Claude Code 设计考量

性能优先: 三级渐进式加载机制最大限度减少不必要的上下文占用，提升会话响应速度，适合轻量级客户端场景
灵活性优先: 支持显式命令调用和参数传递，用户可以更灵活地控制技能的使用时机和方式
扩展性优先: 作为插件系统的一部分，技能可以与其他插件组件无缝协作，方便第三方开发者扩展功能

4.3 借鉴与优化方向

DeerFlow的Skill系统可以从官方实现中借鉴以下优化点：

引入渐进式加载机制，减少系统提示词长度，提升Agent响应效率
增加显式/skill命令调用支持，让用户可以主动触发特定技能
支持技能参数显式传递，提升技能使用的灵活性
优化技能匹配算法，提升隐式触发的准确率