如何写好 Skill：一份终极实战经验手册

用户4242

6月8日修改

🔗 原文链接： https://mp.weixin.qq.com/s/SZv3pDXP...

原创 腾讯程序员 腾讯程序员 腾讯技术工程2026年6月5日 17:36  广东​

作者：jackjchou

这篇文章把我们写 Skill 踩过的坑、总结出的经验，再加上 Anthropic 官方的一些好做法，整理到了一起。希望能帮你少走弯路，把团队积累的知识真正"喂"给 AI，让它干活更靠谱。 本文示例以 Go 语言为主，兼顾 Python、Java 等语言，所有原则和技巧适用于任何编程语言。​

阅读建议

文章比较长，不同背景的读者可以按需跳读：

你的情况	推荐阅读路径
从没写过 Skill，想快速上手	一 → 二（重点看 2.5 Quick Start）→ 三 → 八
写过但效果不好，想提升质量	三 → 五 → 十二（反模式）→ 十三（检查清单）
负责团队 Skill 规范和管理	四 → 七 → 十一 → 十二
想了解 MCP 和外部服务集成	六
Skill 跑不通，想排查问题	九 → 十

一、先搞清楚 Skill 是什么

1.1 Skill 到底是啥

说白了，Skill 就是给 AI 编程助手（Claude Code、CodeBuddy 等）"加装"的能力包。本质上，它是一种 结构化的 Prompt Engineering ——通过标准的文件格式，把分散在人脑中的领域知识、操作流程和最佳实践，转化为 AI 可理解、可执行的指令集。​

物理上看，它就是一个文件夹，里面放一个 SKILL.md 文件，再加上一些可选的脚本和参考资料。核心就三样东西：​

•
指令（Instructions） ：告诉 AI 该怎么干活，按什么步骤来​

•
上下文（Context） ：给 AI 补课，告诉它你的项目背景、团队规范这些它不可能凭空知道的东西​

•
工具（Tools） ：一些辅助脚本、配置模板，AI 可以直接拿来用​

打个比方：裸着的 AI 就像一个刚入职的新人，啥都得问；装了 Skill 之后，就像拿到了老员工整理的操作手册，照着就能干。​

1.2 为什么要写 Skill

做过项目的人都有体会，以下这些问题经常遇到：

痛点	实际表现	Skill 怎么解决
知识太散	经验藏在 TAPD、Wiki、代码注释、甚至某个人的脑子里	全部整理进 Skill，将知识结构化封装为标准技能包
重复搬砖	同样的活反复干，每次都要手动来一遍	写成 Skill 让 AI 自动跑
做出来的东西不统一	张三做一个样，李四做另一个样	用 Skill 固定流程，谁来做都一个标准
新人上手慢	来个新人得教半天，对方还不一定记得住	Skill 本身就是最好的培训材料
人走知识也走	核心成员一离职，很多"部落知识"就没了	把经验沉淀进 Skill，知识完整留存

1.3 Skill 怎么运作的

⚠️ 以下加载机制以 Claude Code 为参考。不同 AI 编程工具（CodeBuddy、Cursor 等）的 Skill 加载策略可能有差异，请以各平台官方文档为准。​

Anthropic 设计了一个"渐进式加载"机制，分成三层：

代码块

Level 1: 元数据（name + description）    → 始终驻留在 AI 上下文中​
Level 2: SKILL.md 主体                  → Skill 被匹配触发时加载​
Level 3: 附带的脚本和参考资料              → 执行过程中按需引用​

各层的作用和约束：

层级	加载时机	内容要求	Token 成本参考
Level 1	常驻（每次对话都在）	name + description，控制在 100 字以内	约 50-150 Token / 个 Skill
Level 2	匹配触发时一次性加载	SKILL.md 正文，建议不超过 500 行	约 2,000-5,000 Token
Level 3	执行中按需读取	脚本、参考文档、模板等	按实际引用大小计算

为什么要关注 Token 成本？因为 Skill 不是免费的 ——每加载一个 Skill 都会占用上下文窗口。假设你装了 20 个 Skill，光 Level 1 就要吃掉 1,000-3,000 Token；如果 AI 一次触发了 2 个 Skill，Level 2 又要再加 4,000-10,000 Token。上下文越满，AI 的注意力越分散，回答质量反而可能下降。​

如何估算 Skill 的 Token 消耗：

可以用以下方式粗略估算 SKILL.md 的 Token 数：

•
英文：约 1 Token / 4 字符​

•
中文：约 1 Token / 1.5-2 字符​

如何写好 Skill：一份终极实战经验手册​

如何写好 Skill：一份终极实战经验手册