生产级Skill开发指南：从踩坑到最佳实践
我写了几十个生产级Skill，踩了不少坑，也总结出了一些经验。看完这篇文章，你应该能写出真正能用、能落地、按你预期执行的Skill。
先避坑：90%的人写Skill都会犯的6个错误
这些坑我都踩过，每一个都花了不少时间才找到原因。你避开了就能少走半年弯路。
1. description写太模糊，永远触发不了
很多人写description就一句话：description: 处理数据库问题。这种写法AI根本不知道什么时候该触发。
错误写法：
description: 数据分析正确写法：
description: 当用户询问MySQL查询、数据统计、员工薪资分析、部门报表、数据库优化时自动触发，所有数据库相关操作必须使用本Skill技巧：description写得越具体越好，把所有触发关键词都列出来。加上"必须使用本Skill"的强制要求，AI触发的概率能提升90%。
2. allowed-tools权限给太大，容易出事故
很多人为了省事，直接写allowed-tools: *，允许AI用所有工具。结果AI执行了rm -rf /、drop database这类危险命令，哭都来不及。
错误写法：
allowed-tools: Bash, Write, Read允许执行所有bash命令，太危险。
正确写法：
allowed-tools: Read, Bash(python:*, mysql:-e SELECT*), Write(*.md, *.sql)只允许执行python和mysql查询命令，只允许写md和sql文件。
技巧：权限最小化原则。能限制到命令级别就不要给整个工具权限，能限制文件后缀就不要给所有写权限。
3. 流程写太死，没有灵活性
很多人把Skill的流程写得像代码一样，一步都不能改，稍微变点需求就用不了。
错误写法：
1. 必须先读a.md，再读b.md，然后生成报告保存到c.md正确写法：
1. 优先读取a.md和b.md获取背景信息，如有缺失可自主搜索补充
2. 生成报告默认保存到c.md，可根据用户要求调整路径技巧：给AI留足够的灵活度。只规定核心规则和流程，不要限制死每一步的操作。
4. 内容写太长，浪费上下文窗口
很多人把所有参考文档、示例代码全写在SKILL.md里，每次调用Skill都要带几千字的内容，占掉一半上下文窗口。
错误写法：
把100条SQL生成规则全写在SKILL.md正文里。
正确写法：
SQL生成规则见[reference.md](reference.md)，如有疑问再读取用渐进式披露，只有需要的时候AI才会读参考文件。
技巧：核心规则写在正文，详细规则、示例、脚本全放到子文件里用链接引用，能节省80%的上下文占用。
5. 没有容错机制，一出错就崩溃
很多人写Skill只考虑正常流程，不考虑出错的情况。执行命令失败、文件不存在、API调用超时，AI就不知道怎么办了。
推荐写法：
如果执行SQL查询失败，先检查SQL语法是否正确，再检查数据库连接是否正常，最多重试2次，依然失败则告知用户错误原因技巧：每个可能出错的步骤都要加上容错处理规则，告诉AI出错了该怎么处理。
6. 没有输出规范，结果五花八门
很多人只告诉AI要做什么，不告诉AI要输出什么格式。每次返回的结果都不一样，没法自动化处理。
推荐写法：
输出必须包含3部分：
1. SQL语句
2. 查询结果表格
3. 分析结论
禁止输出多余的解释性内容技巧：明确规定输出格式，最好给个示例。AI返回的结果就会完全符合你的预期。
生产级Skill开发5步标准流程
按照这个流程写，你写出来的Skill可用性至少提升3倍。
第一步：需求分析，明确边界
先想清楚3个问题：
触发场景：这个Skill什么时候用？有哪些关键词？什么情况下绝对不能用？
能力边界：这个Skill能做什么？不能做什么？比如数据分析Skill只能做查询，不能改数据。
输出要求：最终要输出什么内容？什么格式？给谁用？
输出一份100字以内的需求说明，越明确越好。
第二步：元数据设计，精准控制
元数据是Skill的灵魂，决定了Skill能不能触发、安不安全、用什么模型跑。
必填字段要写准：
name：全小写，用连字符，见名知意。比如mysql-nl2sql、wechat-publish
description：按"触发场景+强制要求"的格式写。比如：description: 当用户要求发布公众号文章、推送草稿、生成封面时自动触发，所有公众号相关操作必须使用本Skill
可选字段按需加：
allowed-tools：按最小权限原则写，限制到命令和文件级别
model：复杂任务用大模型，简单任务用小模型，节省成本
context: fork：危险操作放在隔离上下文里跑，不污染主对话
disable-model-invocation: true：只能手动调用，避免误触发
第三步：内容编写，清晰灵活
内容结构按这个顺序来：
参数接收：第一行就写用户需求：$ARGUMENTS，明确拿到用户输入
背景信息：告诉AI相关的上下文，比如数据库地址、接口文档位置、内部规范
核心流程：分步骤写清楚要做什么，只写核心规则，不要限制死操作
禁止规则：明确告诉AI什么不能做，比如禁止生成DELETE、UPDATE语句
输出规范：明确输出格式和要求
参考资料：详细内容放子文件，用链接引用
第四步：测试验证，确保可用
写完之后一定要做这3个测试：
触发测试：说不同的关键词，看AI能不能正确触发Skill，会不会误触发
流程测试：给不同的需求，看AI能不能按流程正确执行，会不会出错
安全测试：故意让AI执行危险操作，看会不会被权限限制住
至少测试5个不同的场景，确保所有情况都覆盖到了。
第五步：上线迭代，持续优化
上线后要记录使用数据：
触发频率：每天被调用多少次？
成功率：多少次正常完成？多少次出错？
用户反馈：有没有不符合预期的地方？
根据反馈持续优化description、流程、权限。用得越多越好用。
3个生产级Skill完整实战案例
直接给你现成的代码，改一改就能用。
案例1：运维领域-线上故障排查Skill
适用场景：自动排查线上服务故障，不用每次都查手册。
---
name: online-troubleshooting
description: 当用户反馈线上服务故障、报错、卡顿、5xx错误时自动触发，所有线上故障排查必须使用本Skill
allowed-tools: Bash(curl:*, kubectl:*, tail:*, grep:*), Read
model: sonnet
context: fork
---
# 线上故障排查Skill
## 故障描述：$ARGUMENTS
## 排查流程
1. 先检查服务状态：
kubectl get pods | grep $service-name
2. 查看最近500行日志：
tail -n 500 /var/log/service.log | grep ERROR
3. 检查CPU/内存使用率：
top -b -n 1 | grep java
4. 检查数据库连接：
curl http://localhost:8080/health
5. 按照下面的格式输出排查报告
## 禁止操作
- 禁止执行任何修改配置、重启服务、删除文件的命令
- 禁止泄露任何敏感信息（密码、密钥、用户数据）
## 输出格式
故障原因：[明确的原因]
临时解决方案：[可立即执行的命令]
根本解决建议：[长期修复方案]
## 参考文档
常见故障排查手册见 troubleshooting-manual.md落地效果：原来排查故障要30分钟，现在AI自动排查5分钟出结果，新人也能排查80%的常见故障。
案例2：内容领域-公众号发布Skill
适用场景：自动完成公众号文章从排版到推草稿的全流程。
---
name: wechat-publish
description: 当用户要求发布公众号文章、推送草稿、生成封面、排版文章时自动触发，所有公众号相关操作必须使用本Skill
allowed-tools: Read, Write, Bash(node:*, pandoc:*)
model: claude-4-opus
---
# 公众号发布Skill
## 文章路径/内容：$ARGUMENTS
## 执行流程
1. 读取文章内容，检查是否有敏感词、违规内容
2. 自动排版：短段落、重点加粗、代码块指定语言
3. 生成适配公众号的HTML：
pandoc -s $md-path -o $html-path
4. 生成封面图：调用生图脚本生成16:9无版权封面
5. 推送到公众号草稿箱：
node scripts/publish_with_cover.js --article $md-path --html $html-path
6. 返回草稿ID和预览链接
## 排版规范
- 每段不超过3行，多留白
- 核心观点加粗，不用斜体
- 代码块添加左侧蓝色边框
- 所有图片自动上传到微信CDN
## 禁止规则
- 禁止发布包含敏感词、政治内容、违规素材的文章
- 禁止使用有版权的图片、素材落地效果：原来发布一篇文章要30分钟，现在2分钟自动完成，排版还比人工规范。
案例3：开发领域-代码审查Skill
适用场景：自动审查PR代码，检查规范、漏洞、性能问题。
---
name: code-review
description: 当用户要求审查代码、PR、MR时自动触发，所有代码审查必须使用本Skill
allowed-tools: Read, Bash(gh:*, grep:*), Write
model: sonnet
---
# 代码审查Skill
## PR编号：$ARGUMENTS
## 执行流程
1. 拉取PR代码：
gh pr view $ARGUMENTS --json title,body,files
2. 检查代码规范：是否符合团队编码规范，有没有语法错误
3. 检查安全漏洞：有没有SQL注入、XSS、敏感信息泄露等问题
4. 检查性能问题：有没有慢查询、内存泄漏、无效循环等问题
5. 输出审查报告，给出修改建议
## 审查标准
- 代码必须有注释，关键逻辑必须说明
- 必须有单元测试，覆盖率不低于80%
- 不能有硬编码的密码、密钥
- 接口必须有参数校验
## 输出格式
总体评分：[1-10分]
存在问题：
- [严重] xxx问题，位置：xxx，建议：xxx
- [一般] xxx问题，位置：xxx，建议：xxx
- [建议] xxx优化点，位置：xxx，建议：xxx落地效果：原来人工审查PR要1小时，现在AI自动审查10分钟出结果，能发现80%的低级问题。
Skill进阶玩法
学会这些玩法，Skill能给你创造更大的价值。
Skill组合调用：多个Skill可以组合使用。比如写公众号文章的时候，先调用content-write Skill写初稿，再调用wechat-publish Skill发布。全流程自动化，不用人工干预。
团队Skill共享：把团队的最佳实践、踩坑经验都做成Skill，放在项目的.claude/skills/目录下，提交到Git。所有团队成员都能直接用，新人入职不用再反复问老人。
Skill版本管理：每个Skill都加上版本号，迭代的时候保留旧版本，出问题可以快速回滚。比如mysql-nl2sql@v1、mysql-nl2sql@v2。
Skill数据埋点：给Skill加上埋点，统计调用次数、成功率、平均耗时、错误原因。根据数据持续优化Skill，越用越好用。
Skill商业化：把垂直领域的Skill做成可售卖的产品，比如电商售后Skill、教育行业学习Skill、企业运维Skill。现在很多企业愿意为能直接提效的Skill付费，客单价从几千到几万不等。
最后说几句
Skill本质上是把人的经验、知识、流程固化成AI可以理解、可以执行的标准化操作。它是人和AI协作的最佳接口。
你不用写复杂的代码，会写Markdown就能做Skill。把你多年的经验变成可复用、可售卖的资产，这才是AI时代普通人最大的机会。
本文内容仅供个人学习、研究或参考使用，不构成任何形式的决策建议、专业指导或法律依据。未经授权，禁止任何单位或个人以商业售卖、虚假宣传、侵权传播等非学习研究目的使用本文内容。如需分享或转载，请保留原文来源信息，不得篡改、删减内容或侵犯相关权益。感谢您的理解与支持！
