导读
在企业级 AI 智能体体系里，Skill 是能力载体，而 SKILL.md 就是 Skill 的灵魂与契约。
如果没有统一、严谨、可解析、可维护的 SKILL.md 规范，你的 AI 能力会变得混乱、不可控、难复用、难审计、难上线。
尤其在金融、政务、医疗这类强合规、强专业场景，SKILL.md 不只是一份提示词文档，它是业务说明书、执行流程、权限边界、合规依据、评估标准。
本文基于生产级 AI 智能体金融项目，完整讲解：
SKILL.md 到底是什么、怎么设计、怎么写、怎么解析、怎么加载、怎么落地工程化。
全文包含大量可直接复制的规范、模板、正则解析代码、加载逻辑、最佳实践。
一、为什么必须用 SKILL.md 做技能标准化？
在很多团队里，AI 提示词还处于 “野生状态”：
散落在代码里、配置里、接口里
格式不统一、没人维护
无法版本管理、无法审核、无法共享
大模型理解不稳定、容易跑偏
上线后无法追踪、无法复盘、无法优化
这在 ToC 娱乐产品里或许能忍，但在金融、风控、投资、合规场景里，完全不可接受。
SKILL.md 就是为了解决这些问题而生，它具备 7 个不可替代的价值：
结构化：YAML + Markdown，机器可解析、人可阅读
标准化：全公司统一格式，统一字段，统一流程
可审计：每一行指令都可追溯、可审核、可留痕
可复用：一次编写，多 Agent 复用
可插拔：随启随停，支持热更新
可组合：多技能组合完成复杂业务
合规安全：可约束工具、输出、风险、话术
一句话：
SKILL.md 让 AI 能力从 “玄学提示词” 变成 “工程化能力资产”。
二、SKILL.md 整体结构设计（企业级标准）
2.1 标准文件结构
一个合法的 Skill 目录如下：
skill-name（短横线命名）
├── SKILL.md 必须：技能描述 + 指令 + 约束
├── scripts/ 可选：Python 计算脚本
├── references/ 可选：参考文档、数据模板
└── assets/ 可选：图标、配置、资源
2.2 SKILL.md 两段式结构
SKILL.md 由两部分组成：
YAML frontmatter（头部元数据）
给机器看：技能名称、描述、版本、工具权限、作者、分类等。
Markdown 指令体（正文）
给大模型看：执行步骤、输入输出、异常处理、合规约束、示例。
格式固定如下：
---
name: 技能唯一标识
description: 功能描述 + 触发意图
version: 1.0.0
license: MIT
allowed-tools: 工具白名单
metadata:
author: 作者
category: 分类
---
# 技能标题
## Instructions
执行步骤
输入要求
输出格式
约束条件
风险提示
## Example
输入示例
输出示例
三、YAML 元数据字段详解（生产级）
3.1 必写字段
name
必须与目录名一致
小写、短横线分隔，如：dcf-valuation
全局唯一，用于索引、加载、调用
description
功能描述 + 典型触发词
大模型靠它匹配用户意图
必须清晰、具体、可识别
示例：
description: 现金流折现估值，用于股票内在价值计算，用户问估值、价值、合理价格时触发
3.2 可选但推荐字段
version
语义化版本：1.0.0、1.0.1、2.0.0
方便回滚、升级、对比。
allowed-tools
技能可调用的工具白名单，金融安全核心。
allowed-tools: calculateDcf,calculateTechnicalIndicators
metadata
扩展信息：作者、分类、场景、等级、部门。
metadata:
author: sk-tech
category: 投资分析
level: 专业
scope: 股票
四、Markdown 指令体怎么写（决定 AI 专业度）
指令体是大模型真正执行的 “工作手册”，必须遵循以下原则：
4.1 单一职责
一个技能只做一件事。
不要把估值、风控、图表、资讯写在一起
越简单，AI 调用越稳定
4.2 步骤化
用 1/2/3/4 列清楚执行流程。
## Instructions
1. 检查用户输入是否包含现金流、折现率、永续增长率、总股本
2. 缺失参数则反问用户补充
3. 调用 calculateDcf 工具执行计算
4. 按固定格式输出结果
5. 必须附带风险提示
4.3 输入明确
告诉 AI 必须要什么参数、格式是什么。
## Input
cashFlows：数组，未来 5 年现金流
discountRate：小数，如 0.1 代表 10%
terminalGrowth：小数，如 0.03 代表 3%
sharesOutstanding：亿股
4.4 输出固定
强制输出结构，避免乱回答。
## Output
- 股票内在价值：xx 元
- 估值结论：xxx
- 风险提示：市场有风险，估值仅供参考，不构成投资建议
4.5 异常处理
必须写失败路径：
参数缺失怎么办
计算失败怎么办
超出范围怎么办
4.6 合规与风险（金融必备）
## 合规约束
1. 不承诺收益
2. 不提供具体买卖建议
3. 必须输出风险提示
4. 无法回答则转人工
五、SKILL.md 完整可复制模板（企业直接用）
---
name: dcf-valuation
description: 现金流折现估值，用于股票内在价值计算，用户问估值、价值、合理价格时触发
version: 1.0.0
license: MIT
allowed-tools: calculateDcf
metadata:
author: sk-finance
category: 投资分析
---
# DCF 估值技能
## Instructions
1. 首先检查用户输入是否包含：现金流、折现率、永续增长率、总股本。
2. 缺少任何参数，反问用户补充。
3. 调用 calculateDcf 工具进行精确计算。
4. 输出必须包含：内在价值、估值结论、风险提示。
5. 不提供投资建议，不预测涨跌。
## 输入参数
cashFlows：未来现金流数组
discountRate：折现率
terminalGrowth：永续增长率
sharesOutstanding：总股本（亿股）
## 输出格式
- 内在价值：XX 元/股
- 结论：XXX
- 风险提示：市场有风险，估值基于假设，仅供参考
## 异常处理
参数不足 → 引导补充
计算异常 → 告知无法计算并建议检查数据
六、SKILL.md 解析器代码实现（核心工程）
6.1 解析思路
使用正则表达式一次性匹配：
YAML 中的 name
YAML 中的 description
分隔线以下的全部指令
6.2 正则表达式
private static final Pattern SKILL_PATTERN = Pattern.compile(
"^---\\s*[\\r\\n]+name:\\s*(.+?)\\s*[\\r\\n]+description:\\s*(.+?)\\s*[\\r\\n]+---\\s*[\\r\\n]+(.*)$",
Pattern.DOTALL
);
6.3 完整解析器代码
@Slf4j
public class SkillParser {
private static final Pattern SKILL_PATTERN = Pattern.compile(
"^---\\s*[\\r\\n]+name:\\s*(.+?)\\s*[\\r\\n]+description:\\s*(.+?)\\s*[\\r\\n]+---\\s*[\\r\\n]+(.*)$",
Pattern.DOTALL
);
/**
* 解析 SKILL.md 内容为 Skill 对象
*/
public static Skill parse(String content) {
if (content == null || content.isBlank()) {
log.warn("技能内容为空");
return null;
}
Matcher matcher = SKILL_PATTERN.matcher(content);
if (matcher.find()) {
String name = matcher.group(1).trim();
String description = matcher.group(2).trim();
String instructions = matcher.group(3).trim();
return Skill.builder()
.name(name)
.description(description)
.instructions(instructions)
.fullContent(content)
.build();
}
log.warn("SKILL.md 格式不匹配，解析失败");
return null;
}
}
6.4 Skill 领域实体
@Data
@Builder
public class Skill {
private String name;
private String description;
private String instructions;
private String fullContent;
}
七、SKILL.md 加载流程（工程化落地）
7.1 双层加载路径
classpath:skills/**/SKILL.md → 内置只读技能
file:data/skills/**/SKILL.md → 外部可写技能
7.2 并行加载（高性能）
public int loadFromPath(String pathPattern) {
try {
Resource[] resources = resolver.getResources(pathPattern);
List<Skill> skills = Arrays.stream(resources)
.parallel()
.map(resource -> {
try {
String content = StreamUtils.copyToString(
resource.getInputStream(),
StandardCharsets.UTF_8
);
return SkillParser.parse(content);
} catch (Exception e) {
log.warn("解析失败：{}", resource.getFilename());
return null;
}
})
.filter(Objects::nonNull)
.collect(Collectors.toList());
skills.forEach(skillRepository::save);
return skills.size();
} catch (Exception e) {
log.error("加载技能失败", e);
return 0;
}
}
7.3 启动自动加载
@Service
@RequiredArgsConstructor
public class SkillLoaderService {
private final FileSystemSkillRepository repository;
private static final String CLASSPATH_SKILLS = "classpath:skills/**/SKILL.md";
private static final String FILE_SKILLS = "file:data/skills/**/SKILL.md";
@PostConstruct
public void loadAllSkills() {
// 加载内置技能
int innerCount = repository.loadFromPath(CLASSPATH_SKILLS);
// 加载外部覆盖技能
int outerCount = 0;
File dir = new File("data/skills");
if (dir.exists()) {
outerCount = repository.loadFromPath(FILE_SKILLS);
}
log.info("技能加载完成：内置{}个，外部{}个", innerCount, outerCount);
}
}
八、SKILL.md 热更新实现（企业必备）
8.1 更新逻辑
接收新的 SKILL.md 内容
重新解析
更新内存缓存
持久化到外部目录
立即生效，无需重启
8.2 热更新代码
@Override
public synchronized void update(String name, String newContent) {
Skill skill = SkillParser.parse(newContent);
if (skill == null) {
throw new RuntimeException("技能格式错误，更新失败");
}
// 更新缓存
skillCache.put(name, skill);
// 持久化到外部目录
try {
Path path = Paths.get(DYNAMIC_SKILLS_PATH, name, "SKILL.md");
Files.createDirectories(path.getParent());
Files.writeString(path, newContent, StandardCharsets.UTF_8);
log.info("技能热更新成功：{}", name);
} catch (IOException e) {
log.error("技能持久化失败", e);
}
}
九、SKILL.md 常见错误与避坑指南
9.1 格式错误
YAML 缩进不对
没有 --- 开始结束线
name 包含大写、空格、特殊字符
9.2 指令错误
步骤混乱、逻辑复杂
没有异常处理
没有风险提示
9.3 安全问题
allowed-tools 不设置，导致越权调用
输出不做合规约束
可执行指令未限制
9.4 工程问题
文件名不是 SKILL.md（大写）
目录结构不规范
多个技能同名导致覆盖
十、SKILL.md 工程化最佳实践总结
统一格式：全公司只用一套 SKILL.md 规范
目录规范：严格按目录存放，自动扫描
双层存储：内置只读保安全，外部可写保迭代
并行加载：启动更快、占用更低
热更新：业务实时生效，不中断服务
权限白名单：allowed-tools 必须配置
全量审计：每次调用都记录技能、日志、评估
版本管理：每次更新保留版本，方便回溯
审核上线：金融场景必须先审核再上线
持续优化：根据失败日志迭代指令
十一、结语
SKILL.md 看似只是一个 Markdown 文件，
但它是企业 AI 能力平台的基石。
它把模糊、混乱、不可控的提示词，
变成可管理、可复用、可审核、可追溯、可优化的标准化资产。
在金融、政务、医疗等强合规行业，
SKILL.md 不仅是开发规范，更是合规底线、安全边界、专业保障。
如果你正在搭建 AI 智能体平台、大模型应用平台、企业能力中心，
本文的 SKILL.md 工程化方案可以直接落地、直接上线、直接过审。
