为什么使用 Skills（上）：SKILL.md 文件格式详解
本文独立分析声明：本文基于吴恩达与 Anthropic 在 DeepLearning.AI 合作课程 Agent Skills with Anthropic L1 章节独立撰写。内容包含课程未覆盖的独立扩展：Skill description 写法实测、命名陷阱、与 MCP/Subagent 的组合方式、国内开发者常见踩坑。推荐先观看原课程（免费）再读本文。
Skills 是包含指令的文件夹，用于把重复性工作流、专业知识或新能力打包给 Agent。如果你发现自己在不同对话中反复输入相同的 Prompt，就应该考虑把它转化为一个 Skill。
场景演示：没有 Skill 的工作流
假设你每周都要分析营销活动数据。CSV 包含日期、活动名称、展示量、点击量、转化量等字段。
第一步：数据质量检查与漏斗分析
你需要在 Prompt 中写明：
- 输入数据的格式说明
- 要求检查数据质量（缺失值、异常值）
- 漏斗分析的基准指标（点击率、转化率等）
- 期望的输出格式
Claude 会读取 CSV，执行数据质量检查和漏斗分析，返回活动表现报告：总记录数、缺失数据、数据异常、各渠道与基准的对比等。
第二步：效率指标计算
接着你要求 Claude 计算更多效率指标：
- 广告投资回报率（ROAS）
- 获客成本（CPA）
- 净利润
同样需要指定输出格式。Claude 返回效率分析结果、组合表现和总净利润。
第三步：预算重分配
最后，你引入一份预算重分配规则文档——里面定义了何时增加、维持或减少预算的决策框架。Claude 根据规则给出各渠道的预算调整建议。
问题在哪？
这个流程有两个核心痛点：
- 重复劳动 —— 每周都要复制粘贴同样的 Prompt、附上同样的参考文档
- 上下文浪费 —— 所有指令和文档一次性塞进上下文窗口，即使你接下来想聊别的话题，这些内容依然占据空间
用 Skill 打包工作流
解决方案是把这些指令打包成一个 Skill——一个独立的文件夹，包含执行任务所需的全部指令。
SKILL.md 文件
每个 Skill 的核心是 SKILL.md 文件。它包含与之前 Prompt 非常相似的信息：
- 输入要求
- 数据质量检查规则
- 漏斗分析与基准指标
- 效率分析指标
- 输出格式要求
关键区别在于 预算重分配 部分——SKILL.md 中只写了一句引用：
当用户询问预算重分配时，参考
references/budget_reallocation_rules.md
这意味着只有用户主动询问预算时，Claude 才会加载这份文档。这就是渐进式披露的体现。
YAML 前置元数据
SKILL.md 文件的开头必须包含 YAML 格式的元数据：
---
name: analyzing-marketing-campaign
description: Analyzes weekly marketing campaign performance data, performs quality checks, funnel analysis, efficiency metrics, and budget reallocation recommendations.
---- name —— Skill 的标识名称，用于 UI 展示和引用
- description —— 告诉模型何时应该使用这个 Skill
这两个字段是必填项，缺一不可。
文件夹结构
一个完整的 Skill 文件夹结构如下：
analyzing-marketing-campaign/
├── SKILL.md # 核心指令文件（必需）
└── references/ # 引用资料文件夹
└── budget_reallocation_rules.md # 预算重分配规则命名规则：
- 使用小写字母
- 单词之间用短横线（
-）连接 - 不要使用保留关键字（如
claude、anthropic）
Skill 可以引用其他文件（Markdown、脚本、模板、图片等），只要它们都在同一个父文件夹内。references 是开放标准中指定的外部引用文件夹名称。
上传与使用 Skill
在 Claude.ai 中上传
- 将 Skill 文件夹打包为 ZIP 文件
- 进入 Settings → Capabilities → Skills
- 点击 Add，上传 ZIP 文件
- 上传后可以看到 Skill 的名称和描述
实际使用
上传完成后，开始新对话，附上 CSV 数据并询问分析：
- Claude 通过 Skill 的 名称和描述 识别到这是一个营销数据分析任务
- 自动读取
SKILL.md中的完整指令 - 因为用户提到了预算重分配，Claude 进一步加载
references/budget_reallocation_rules.md - 执行分析并返回结果
关键改进：
- 不再需要手动输入冗长的 Prompt
- 上下文窗口更高效——只在需要时加载相关文件
- Skill 可以分享给团队成员
- 可以随时编辑和迭代
Skill 的组合能力
在演示中，Claude 还利用了内置的 Excel Skill 来生成电子表格报告——包含执行摘要、漏斗分析、效率分析等 Sheet，并支持颜色编码。
这展示了 Skills 的组合能力：你的自定义 Skill 负责分析数据，内置 Skill 负责生成文件格式，两者协作完成完整工作流。
如何体验 Skills？
- Claude 订阅用户：直接在 Claude.ai 的 Settings → Capabilities → Skills 中上传使用
- 免费用户：Skills 同样可用（支持 Sonnet 4.5 或 Haiku 4.5）
- 其他平台：Skills 是开放标准，兼容 Codex、Gemini CLI 等支持 Skills 的 AI 应用
如何扩展 analyzing-marketing-campaign Skill？
你可以在 references 文件夹中添加更多参考文件：
- 数据质量问题的分析与修复指南
- 所有你关心的营销指标计算方法
- 额外的分析维度（时间趋势、A/B 测试等）
- 当没有 CSV 时，从数据库查询数据的指令
思考练习
- 你有没有反复让 Agent 执行的工作流？能否打包成 Skill？
- 你希望 Agent 在特定任务中始终遵循的规范有哪些？
- 哪些参考文档可以放在
references中按需加载，而不是每次都塞进上下文？
所有课程中展示的 Skills 均为教学目的。每个 Skill 都有进一步优化和迭代的空间。
课程资料
本站独家：国内开发者常见踩坑
踩坑 1：description 写成”功能说明”而不是”触发条件”
❌ 错误写法：description: 这是一个分析营销数据的 Skill，包含漏斗分析、效率指标、预算重分配等功能。
✅ 正确写法：description: 当用户提供 CSV 格式的营销活动数据并要求分析时使用。处理展示量、点击量、转化量，输出漏斗分析、ROAS/CPA、预算建议。
前者是”这个 Skill 是什么”，后者是”什么时候该调用这个 Skill”——Agent 路由靠的是后者。
踩坑 2：把敏感凭据放进 Skill 文件夹
Skill 文件夹通常会上传到云端（Claude.ai）或共享给团队。千万不要在 scripts/ 里硬编码 API Key、数据库密码。正确做法是让 scripts 从环境变量读取，在 SKILL.md 里说明”运行前确保已设置 XXX 环境变量”。
踩坑 3：Skill 和 MCP 重复实现
有开发者看到 Skill 支持 scripts/ 调用外部 API，就把 HTTP 请求逻辑全写进 Skill。结果同一个 API 被 3 个不同 Skill 各实现一遍。
正确分层：
- MCP Server — 封装一次外部 API 调用（例如
github-mcp） - Skill — 业务流程编排（例如
weekly-engineering-report，调用 MCP 拿 GitHub 数据后编排生成报告）
踩坑 4：上传 ZIP 包含 macOS 隐藏文件
在 macOS 下用”压缩”命令打包 Skill 文件夹，会包含 __MACOSX/ 和 .DS_Store，Claude.ai 可能拒绝或显示额外文件。推荐用命令行：
cd my-skill-parent/
zip -r my-skill.zip my-skill/ -x "*.DS_Store" -x "__MACOSX/*"下一课预告
L2：为什么使用 Skills（下） 会深入渐进式披露机制的上下文管理细节——三层加载的实际 token 消耗测算、Skill 冲突时的优先级规则、Agent 如何决定”够不够用”从而停止加载更深层资产。