SKILL.md是Anthropic Skills标准的核心文件，采用“YAML前置元数据+Markdown正文指令”的结构，以---分隔元数据与正文，实现技能的可发现、可复用与渐进式加载，适配Claude、GitHub Copilot等多平台。
一、基础结构与核心格式
SKILL.md由两部分组成，整体框架如下：
---
# YAML前置元数据（frontmatter），用---包裹
name: skill-id
description: 技能功能与触发场景描述
# 可选元数据字段
---
# Markdown正文指令（L2层核心内容）
[结构化的任务流程、操作步骤、示例等]
二、YAML前置元数据（必填+可选字段）
元数据用于技能的识别、匹配与权限控制，字段规范如下：
| 字段 | 必填 | 格式要求 | 说明 |
|---|---|---|---|
| name | ✅ | 小写字母、数字、连字符，≤64字符，与目录名一致 | 技能唯一ID，如“financial-report-generator” |
| description | ✅ | ≤1024字符，清晰说明功能与使用场景 | 用于模型判断何时触发技能，如“生成月度财务报表，含数据核对与可视化” |
| allowed-tools | ❌ | 工具ID列表（逗号分隔或YAML列表） | 限制技能可调用的工具，如“pdfplumber,openai-api” |
| compatibility | ❌ | 兼容模型标识，如“claude-4,codex-2026” | 指定适配的模型版本 |
| license | ❌ | 开源协议标识，如“Apache-2.0” | 技能的授权说明 |
| metadata | ❌ | 嵌套字典，如version:1.0, author:team | 自定义扩展信息 |
三、Markdown正文指令（推荐结构）
正文采用“渐进式披露”设计，建议控制在500行内，核心模块如下：
- 技能概述：# 技能名称，简要定位技能角色与价值
- 触发条件：## When to use this skill，明确适用场景与边界
- 操作步骤：## Step-by-step workflow，分点列出任务执行流程（如“1. 调用MCP读取ERP数据→2. 执行scripts/数据校验脚本→3. 生成报表”）
- 工具调用规范：## Tool usage guidelines，说明MCP工具的调用参数、权限要求、异常处理
- 输入输出示例：## Examples，提供标准输入格式与预期输出样例
- 边界案例处理：## Edge cases，说明异常场景（如数据缺失、工具调用失败）的应对策略
- 引用资源：## References，链接scripts/、assets/等目录下的脚本与模板文件
四、完整示例（财务报表生成技能）
---
name: financial-report-generator
description: 生成月度财务报表，含ERP数据读取、校验、可视化与钉钉推送
allowed-tools: erp-mcp, bi-tool, dingtalk-api
compatibility: claude-4
metadata:
version: 1.0
author: finance-team
---
# 财务报表生成器
你是财务报表生成专家，按以下流程完成月度报表任务。
## When to use this skill
当用户需要生成月度财务报表（含利润表、资产负债表）并推送至钉钉群时触发。
## Step-by-step workflow
1. 通过erp-mcp获取当月销售、成本数据
2. 调用scripts/validate_data.py脚本校验数据完整性
3. 使用bi-tool生成可视化图表
4. 按assets/report_template.md格式化报表
5. 通过dingtalk-api推送报表至财务群
## Tool usage guidelines
- erp-mcp：请求参数为month（格式YYYY-MM），返回JSON数据
- bi-tool：输入数据需包含销售总额、成本总额字段
- 工具调用失败时，自动重试2次，仍失败则发送告警至邮箱
## Examples
输入：生成2026-01月度财务报表
输出：[报表markdown内容，含图表链接]
## Edge cases
- 数据缺失：标记缺失字段并生成“待补充数据”报表
- 工具调用失败：记录日志并触发人工审核流程
五、最佳实践
- 元数据精准：description字段明确触发条件，帮助模型快速匹配任务
- 流程标准化：操作步骤使用编号列表，减少歧义
- 资源分离：复杂脚本、模板放入scripts/、assets/目录，正文通过链接引用，降低Token消耗
- 版本管理：通过metadata中的version字段跟踪技能迭代，便于团队协作
总结
SKILL.md的核心价值在于标准化技能的元数据与执行流程，通过YAML元数据实现技能的快速发现，通过Markdown正文封装专业流程，配合MCP、RAG等组件，让AI智能体高效完成复杂任务。掌握该格式是构建可复用、可扩展AI技能库的基础。
