Skill 最佳实践笔记 - 自用
好的Skill是怎样的
读了三篇如何写Skill的文章
Github文章-如何写出好的 Skill
Claude文章-Skill 编写最佳实践
Trae文章-如何写好一个 Skill：从创建到迭代的最佳实践
这里做一个学习笔记
首先
一个SKILL最少需要一个SKILL.md
SKILL.md中包含frontmatter以及body
frontmatter格式
name:
description:
name则是唯一标识符
description描述的是Skill在什么情况下应该被触发
name规范
- 词与词之间应用-连接。
- 推荐动名词。
- 长度不超过64字符。
description规范
- 使用第三人称，从AI视角描述。
- 包含核心功能与触发时机的关键词。
- 长度不超过 1024 个字符。
body格式
body的内容是Skill被激活之后才加载的操作指令。
如果技能没被触发，AI 永远不会读到这里。
到这里我们已经完成了一个简单的Skill
Skill可以很简单也可以很复杂
AI执行的自由度分级
比如我们让AI做读取本地文件。
高自由度——给方向
具体怎么做让 AI 自己决定。
在这个自由度，AI可以自己选择技术栈C#，Rust，Python等。
中自由度——给框架
AI可以在框架内选择怎么做。
在这个自由度，我们指定了技术栈，但不管代码实现。
低自由度——给代码
让AI直接调用。
在这个自由度，我们直接把能读取本地文件的Rust代码给AI。
自由度越低意味着犯错的可能越低，而我们对不同的命令犯错的接受度不同，所以要合理选择不同自由度的命令。
简洁
三篇文章同时提到了，给AI的文字要简洁 为什么呢？因为上下文是非常珍贵的有限资源，Skill越简洁，占用的上下文就越少。
这里我看看Claude官方给出的例子
渐进式披露
从单一文件 → 多个参考文件和脚本组成的结构。通过渐进式披露，AI能快速抓住核心信息，再深入了解细节。 这里引出了Skill的其他部分如reference，scripts，assets。
skill-name/
├── SKILL.md # [必需] 入口文件：frontmatter + body
├── agents/
│ └── openai.yaml # [推荐] 技能的"名片"
├── scripts/ # [可选] 可执行脚本
├── references/ # [可选] 参考文档
└── assets/ # [可选] 产出物模板
模式1-引用指南
**Form filling**: See [FORMS.md](reference/FORMS.md) for complete guide
这里我们将这样可能被用到的外部资料引用，既保持了body的整洁，又让AI在需要时能快速找到。
模式2-按领域组织
## Available datasets
**Finance**: Revenue, ARR, billing → See [reference/finance.md](reference/finance.md)
**Sales**: Opportunities, pipeline, accounts → See [reference/sales.md](reference/sales.md)
**Product**: API usage, features, adoption → See [reference/product.md](reference/product.md)
**Marketing**: Campaigns, attribution, email → See [reference/marketing.md](reference/marketing.md)
模式3-条件性细节
## Editing documents
For simple edits, modify the XML directly.
**For tracked changes**: See [REDLINING.md](REDLINING.md)
**For OOXML details**: See [OOXML.md](OOXML.md)
仅在用户需要这些功能时才读取 REDLINING.md 或 OOXML.md。
这里解释一下与模式1的区别
模式1指 按知识类型划分
模式3指 按任务场景划分
用户说：「帮我修改 Word 文档中的一段文字。」
Agent 读取 SKILL.md 后，发现只需直接修改 XML，就没有必要读取 REDLINING.md。
但如果用户说：「帮我修改 Word 文档，并保留修订记录。」
这时满足了 Tracked Changes 条件，Agent 才需要进一步读取 REDLINING.md。
避免 Windows 风格的路径
这里你可能注意到了上面出现的路径统一使用“正斜杠”，这是因为Unix 风格的路径在所有平台上都有效，而 Windows 风格的路径在 Unix 系统上会导致错误。
避免深层嵌套引用
保持引用距离 SKILL.md 只有一层深度。
为较长的参考文件添加目录
对于超过 100 行的参考文件，请在顶部包含目录。这可以确保 Claude 即使在通过部分读取进行预览时也能看到可用信息的完整范围。
不要把AI当傻X
一定要假设： AI 已经非常聪明
只添加 AI 没掌握的知识。对每条信息提出质疑：
"AI 真的需要这个解释吗？"
"我可以假设 AI 知道这一点吗？"
"这一段值得它的词元成本吗？"
工作流和反馈循环
对复杂任务使用工作流
将复杂操作分解为清晰、有序的步骤。对于特别复杂的工作流，提供一个清单，AI 可以将其复制到响应中并在推进过程中逐项勾选。
实现反馈循环
运行验证器 → 修复错误 → 重复
也就是不断的“修复+回归测试”
内容指南
时效性
正面示例
## Current method
Use the v2 API endpoint: `api.example.com/v2/messages`
## Old patterns
<details>
<summary>Legacy v1 API (deprecated 2025-08)</summary>
The v1 API used: `api.example.com/v1/messages`
This endpoint is no longer supported.
</details>
反面示例：有时效性
If you're doing this before August 2025, use the old API.
After August 2025, use the new API.
统一术语
比如：始终使用 "API endpoint"，而不是混用 "API endpoint"、"URL"、"API route"、"path"
常见模式
模板模式
为输出格式提供模板。使严格程度与需求相匹配。 你可以让AI严格按照格式输出，也可以留给它一定的自由发挥空间。
示例模式
对于输出质量依赖于查看示例的 Skills，请像常规提示一样提供输入/输出对。
条件工作流模式
很像代码中的case()
## Document modification workflow
1. Determine the modification type:
**Creating new content?** → Follow "Creation workflow" below
**Editing existing content?** → Follow "Editing workflow" below
2. Creation workflow:
- Use docx-js library
- Build document from scratch
- Export to .docx format
3. Editing workflow:
- Unpack existing document
- Modify XML directly
- Validate after each change
- Repack when complete
高级：包含可执行代码的 Skills
提供预制菜（代码）
实用脚本的好处：
比生成的代码更可靠
节省词元（无需在上下文中包含代码）
节省时间（无需生成代码）
确保各次使用之间的一致性
使用视觉分析
有时图片比文字来得更直观 当输入可以渲染为图像时
## Form layout analysis
1. Convert PDF to images:
bash
python scripts/pdf_to_images.py form.pdf
2. Analyze each page image to identify form fields
3. Claude can see field locations and types visually
创建可验证的中间输出
当 Claude 执行复杂、开放式的任务时，它可能会犯错。"计划-验证-执行"模式通过让 Claude 首先以结构化格式创建计划，然后在执行之前用脚本验证该计划，从而及早发现错误。
MCP 工具引用
如果 Skill 使用 MCP（Model Context Protocol）工具，始终使用完全限定的工具名称以避免"找不到工具"错误。
示例：
Use the BigQuery:bigquery_schema tool to retrieve table schemas.
Use the GitHub:create_issue tool to create issues.
避免假设工具已安装
**Bad example: Assumes installation**:
"Use the pdf library to process the file."
**Good example: Explicit about dependencies**:
"Install required package: `pip install pypdf`
Then use it:
python
from pypdf import PdfReader
reader = PdfReader("file.pdf")
高效 Skills 清单
核心质量
描述具体并包含关键术语
描述同时包含 Skill 的功能以及何时使用它
SKILL.md 正文在 500 行以内
其他详细信息放在单独的文件中（如果需要）
没有时效性信息（或放在"旧模式"部分）
全文术语一致
示例具体，而非抽象
文件引用只有一层深度
适当使用渐进式披露
工作流有清晰的步骤
代码和脚本
脚本解决问题，而不是推给 Claude
错误处理明确且有帮助
没有"巫术常量"（所有值都有依据）
所需的包已在指令中列出并验证可用
脚本有清晰的文档
没有 Windows 风格的路径（全部使用正斜杠）
关键操作有验证/核实步骤
对质量关键型任务包含反馈循环
测试
至少创建了三个评估
已使用 三种不同水平的模型 测试
已使用真实使用场景测试
已吸收团队反馈（如适用）
封面拍摄于日本-东京-秋叶原
评论
使用 GitHub 账号登录后即可参与讨论。若评论区未能加载，可前往 GitHub Discussions。