创建skill的主要工作就是写md文件------创建一个能用的 Skill 核心确实是写 SKILL.md，但要让它稳定触发、精准执行 ，必须结合工作流结构化 和渐进式披露设计 。下面用 PDF 提取器 的实战案例拆解：
一、最小可行 Skill：仅需 SKILL.md（80% 场景适用）
✅ 正确写法（直接可用）
markdown
---
name: pdf-extractor
description: 从 PDF 中提取结构化文本。当用户要求"分析 PDF"、"提取合同条款"、"总结文档内容"时使用。
---
## 执行流程
1. **调用工具**：使用 `pdf_parser` 解析上传的 PDF 二进制文件
2. **清理格式**：删除页眉/页脚/页码，保留段落换行
3. **输出规则**：
- 按页面分段，标记页码：`[P.1] 内容...`
- 禁止修改原文措辞
- 遇到扫描件时返回：`[ERROR] 含扫描图像，请提供可选中文本的 PDF`❌ 错误写法（几乎必失效）
markdown
---
name: pdf-skill
description: 帮助用户处理 PDF
---
这里写 PDF 处理逻辑...| 对比维度 | 正确写法（左） | 错误写法（右） |
|---|---|---|
| 触发精准度 | ✅ 包含 3 个明确触发词 | ❌ 模糊描述无法被模型识别 |
| 执行确定性 | ✅ 步骤 1-3 无歧义 | ❌ 未定义工具/错误处理 |
| 边界清晰度 | ✅ 明确拒绝扫描件场景 | ❌ 无边界导致胡乱执行 |
⚠️ 90% 的 Skill 失败源于
description未命中 或 步骤模糊 ------这本质是工作流未结构化，而非"写 MD 简单"。
二、进阶 Skill：何时需要额外文件？（20% 复杂场景）
当你的 Skill 需要确定性输出时，仅靠 MD 不够：
| 场景 | 仅 MD 的缺陷 | 必需文件 | 实例说明 |
|---|---|---|---|
| 需精确计算 | 模型可能算错数字 | scripts/calc.py |
税务计算 Skill |
| 需保留原始格式 | 模型会重写内容 | assets/template.docx |
合同生成 Skill |
| 需复杂条件判断 | 模型易漏判边界条件 | references/rules.md |
合规审查 Skill |
案例：Excel 公式校验 Skill
diff
my-skill/
├── SKILL.md # 声明：调用 scripts/validate.py
+ ├── scripts/validate.py # 用 Python 精确校验公式逻辑
+ └── references/formula-specs.md # Excel 函数官方文档摘录✨ 关键原则：让模型做推理，让代码做确定性操作 。
模型不该负责"15% 税率的 10000 元税后是多少"------这类计算必须交给
scripts/中的脚本。
三、创建 Skill 的本质：不是"写 MD"，而是"封装工作流"
1. 先梳理你的人工操作流程
以 "写周报" Skill 为例：
人工流程：
1. 打开钉钉查本周日程
2. 翻看企业微信的讨论记录
3. 汇总完成事项 → 用"动词+成果"格式写
4. 未完成项 → 标注阻塞原因2. 转换为 Skill 可执行结构
markdown
---
name: weekly-report
description: 生成结构化周报。当用户说"写周报"、"总结本周工作"时触发。
---
## 执行步骤
1. **收集数据**：调用 `calendar_tool` 获取本周日程
2. **提取重点**：用 `message_search` 扫描企业微信关键词 `#周报`
3. **输出格式**：
### ✅ 本周完成
- [动词] [成果]（例：**优化** API 响应速度 → **提升** 40%）
### ⚠️ 待推进
- [阻塞原因]（例：**等待** 设计稿 → **UI 评审未通过**）💡 你会发现：写 SKILL.md 的过程 = 把你的经验沉淀为可复用的 SOP，这才是核心价值。
四、避坑指南：为什么你的 Skill 总不触发？
3 大高频失效原因（附解决方案）
| 问题现象 | 根本原因 | 修复操作 |
|---|---|---|
| Skill 不激活 | description 缺少触发词 |
加入用户原话：当用户说"帮我写周报" |
| 输出不一致 | 步骤未定义边界条件 | 补充：遇到扫描 PDF 时返回错误 |
| Token 消耗高 | 正文超 500 行 | 拆分到 references/ 子文件 |
五、终极结论
- 基础场景 ：是的，写好
SKILL.md就能用（但需严格遵循 元数据规范 + 步骤结构化）。 - 生产场景 ：必须将 工作流拆解 为：
SKILL.md（触发逻辑） + scripts/（确定性操作） + references/（知识库）
把 Skill 当作你的数字分身 ------你不会教同事"随便处理 PDF"，而是说"用这个工具提取，按这个规则清理"。Skill 的成败不在格式，而在工作流是否可精准复现。
现在，打开你的 SKILL.md，检查：
description里是否有 用户原话级触发词？- 步骤是否 无歧义、可执行？
- 是否 拒绝了不该处理的场景 ？
------如果 3 个答案都是 Yes，你的 Skill 已超越 90% 的公开 Skill。