1. OpenDeepWiki Agent Skills 机制概述
OpenDeepWiki 的 Agent Skills 机制是一套创新的 AI 工具扩展体系,它通过标准化的文件结构和 YAML 元数据定义,实现了 AI 能力的模块化扩展。这套机制的核心思想是将每个功能单元封装为一个独立的 Skill,让开发者可以通过简单的文件上传方式,为 AI Agent 注入新的能力。
在技术实现上,一个 Skill 本质上是一个包含特定结构的文件夹,其中必须包含一个名为 SKILL.md 的核心文件。这个文件采用 YAML frontmatter 定义元数据,正文部分则是给 AI 的 prompt 指令。当用户上传 Skill 压缩包后,系统会自动解析这个文件结构,将其转换为 AI Agent 可调用的工具。
这种设计有几个显著优势:
- 标准化:遵循 agentskills.io 开放标准,确保不同来源的 Skill 可以无缝集成
- 轻量化:仅需一个 Markdown 文件即可定义完整功能,降低开发门槛
- 可扩展:支持附加脚本、参考资料和静态资源,满足复杂场景需求
- 易管理:通过数据库持久化元数据,同时保持文件系统的灵活性
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. SKILL.md 文件结构与解析机制
2.1 文件结构规范
一个完整的 Skill 文件夹通常包含以下内容:
code复制code-review/
├── SKILL.md # 核心文件,包含 YAML frontmatter 和 prompt 指令
├── scripts/ # 可选,存放辅助执行的脚本文件
├── references/ # 可选,存放参考文档或示例
└── assets/ # 可选,存放图片等静态资源
SKILL.md 的文件格式严格遵循以下规范:
markdown复制---
name: code-review
description: 对代码进行深度审查,发现潜在问题和改进建议
license: MIT
compatibility: "gpt-4, claude-3"
allowed-tools: "read_file search_code"
metadata:
author: token
version: 1.0.0
---
你是一个代码审查专家。当用户请求代码审查时,请按以下步骤执行:
1. 先通读目标文件,理解整体结构
2. 检查常见问题:空指针、资源泄漏、并发安全...
3. 给出具体的改进建议,附带代码示例
2.2 YAML frontmatter 解析
OpenDeepWiki 使用 YamlDotNet 库解析 SKILL.md 中的 YAML frontmatter,关键解析逻辑如下:
csharp复制private static (Dictionary<string, object?> frontmatter, string body) ParseSkillMd(string content)
{
var frontmatter = new Dictionary<string, object?>();
var body = content;
if (content.StartsWith("---"))
{
var endIndex = content.IndexOf("---", 3);
if (endIndex > 0)
{
var yamlContent = content[3..endIndex].Trim();
body = content[(endIndex + 3)..].Trim();
try
{
var deserializer = new DeserializerBuilder()
.WithNamingConvention(HyphenatedNamingConvention.Instance)
.Build();
frontmatter = deserializer.Deserialize<Dictionary<string, object?>>(yamlContent) ?? new();
}
catch { }
}
}
return (frontmatter, body);
}
解析过程中的几个关键点:
- 使用
HyphenatedNamingConvention处理 kebab-case 格式的键名(如 allowed-tools) - 通过字符串操作准确分割 frontmatter 和正文部分
- 解析失败时静默返回空字典,不影响后续处理
- 正文部分保持原样返回,不进行额外处理
2.3 元数据校验规则
上传 Skill 时,系统会对 frontmatter 中的元数据进行严格校验:
csharp复制// 校验必填字段
if (!frontmatter.TryGetValue("name", out var nameObj) || string.IsNullOrEmpty(nameObj?.ToString()))
throw new InvalidOperationException("SKILL.md 缺少 name 字段");
var name = nameObj.ToString()!;
if (!Regex.IsMatch(name, @"^[a-z0-9]+(
