如何从零开始写好一个Skill？保姆级教程+实战案例来了！

一、全文速览图

二、如何写出一个 Skill

‍‍‍‍‍‍首先我个人是不推荐完全从 0-1 手搓 Skill 的，耗费时间且门槛较高。想要快速起步，可以直接在 Trae 或 Claude Code 这类 AI Coding 产品中输入指令：“我需要你帮我做一个 Skill…”

只要你的指令完整得当，就能让 AI 快速完成 Skill 的初版撰写，搭建基础框架，让你把精力放在后续的检验和调优上。怎样才算得上是一份好的 Skill 撰写指令呢？至少先要包括以下 5 点：

1. 写 Skill 的 AI 身份（比如让 AI 站在设计专家 / 产品专家的视角来撰写这个 Skill）
2. Skill 的用途（比如 Skill 的调用方式、功能、用途等等）
3. Skill 的内容（比如产出物的内容层级、引用内容等等）
4. Skill 的交付要求（比如 Skill 输出内容的格式、注释的样式等等）
5. 禁用事项或规则（比如不要擅自添加功能或内容信息等等）

举个实际的例子，假如我想让 Claude Code 帮我把我在 Figma 中做好的业务组件库做成一个 Skill，方便我在设计转代码的过程中随时调用，给 Claude Code 的指令就可以是：

你现在是一位资深的 Figma 设计系统及组件库专家，帮我编写一份可用于 AI Agent 设计工作流的 Figma 组件库专用 Skill，要求如下：
1. Skill 用途：
当我提到做 XXX 业务设计时，能够自动调用这个 Skill，用于一键生成使用 Figma 业务组件库（业务组件库文档链接）搭建的产品页面，保持页面的基本可用性和统一性。
2. 产出规范：
- 先给出 Skill 整体能力说明，再给出关键组件的使用规范说明；
- 组件嵌套合理，颜色、文字、阴影等样式全部绑定样式变量；
- 每条规则清晰、可执行、可被 AI 直接理解并落地到设计稿。
3. 交付要求：
- 用结构化的格式输出，分章节、条款清晰；
- 关键的规则加粗标注，便于阅读；
- 补充 Skill 的使用说明、注意事项和后续迭代扩展方向。
4. 禁止事项：
- 不要自行设计或增加无关的业务组件；
- 不要擅自修改基础变量的数值。

把以上内容发给 Claude Code，如果你有足够的耐心，还可以在指令里再加一句：“如果有不明确的内容，你还可以再问我”，你还会收获 AI 更多的反馈，比如 AI 会反问你另一些你想不到的边界问题从而帮助自己更好的理解这个 Skill，确保 Skill 符合你的预期。

初版生成后，你也可以先用 AI 进行初步校验，比如你可以直接把这个 Skill 包里的 markdown 内容发给另外几个 AI 工具（豆包或者 Gemini），让 AI 先帮我们初步检验 Skill 的可用性，找出语法错误、逻辑漏洞，做基础的查漏补缺。

当然，以上所有的内容都只是 Skill 生成的基础步骤，想要让 Skill 真正落地可用、稳定输出，后期的质量检验和人工调优必不可少，这一步目前还无法被 AI 完全替代，必须由人类亲自把控。

三、人工调优的经验

想要持续优化和打磨你的 Skill，让它更加好用，可以从以下三个维度来思考和操作：

1. 明确使用场景和触发条件

在动手优化或编写 Skill 前，能够精准定位使用人群、使用场景和典型输入，是 Skill 能被正常激活的前提。你在日常工作中调用 Skill 的描述内容和指令是 Claude Code 判断是否触发 Skill 的核心依据。所以你对于 Skill 用途的描述字段中必须包含以下这个问题的答案：什么情况下 AI 应该自动使用这个 Skill？

举个例子：

❌ 错误写法：实现 Figma 设计稿转代码的技能。

✅ 正确写法：当用户需要将 Figma 设计稿进行高质量前端代码转换时触发。

只有把触发条件写清楚，AI 才能精准识别，避免出现该触发不触发、不该触发乱触发的问题。

2. 了解 Skill 的结构和原理

Skill 不是一个简单的 markdown 文件，而是一个完整的文件夹，一个 Skill 至少包括 4 个部分：

 1）Skill.md 核心定义

这是 Skill 的核心 “大脑”，是整个 Skill 系统的 CPU，负责意图识别和指令分发，里面包含触发条件、角色定义、核心工作流等等。Skill.md 采用的就是 Markdown 格式，这是一种结构化数据格式，用于给纯文本增加语义和结构，让人和机器都能理解。Markdown不是编程语言，其本质是对信息进行约束，把零散的自然语言，转化为机器能精准理解的结构化内容。

你可以这么理解：假如我们日常对话的语言是散文，那 Markdown 就是把散文改写成的一种机器较好理解的比较严谨的议论文。如果你担心输出的内容跑偏，可在这个文件里补充更多精准的描述。

 2）References 参考规范

这是 AI 通过 Skill 输出内容的强约束模块，比如设计原则、命名规则、格式规范、参考文档等，都可以放在这里。

References 的核心价值其实是“易错点”，你可以这么理解：把 AI 经常出错的地方给它记下来，整理成 “错题本”，持续更新补充到其中，Skill 就会渐渐学会避坑，输出的质量也会越来越高。很多 Claude Code 官方的优质 Skills 也都是从几行文字经过日积月累的不断叠加这些易错点，慢慢迭代完善的。

3）Assets 物料资源

这是按需调用的物料资源，用来存放字数多、无需每次都放入提示词的固定知识，比如图片、缩略图、模板、配置文件、现成素材等。AI 在需要用到内容时，会通过命令去读取和调用它。

对于 References 和 Assets 来说，核心逻辑都是“渐进式披露”，你可以这么理解：就是不要把所有内容都堆在一个文件里面。比如你可以把详细的 API 说明放到 references/api.md 里面或者放在 assets/ 目录里面。在 Skill.md 的主文件标注出来告诉 AI ：“这些文件分别在这里和那里”，AI 会在需要的时候主动去分类阅读，这样准确率会更高，也会更节省资源。

 4）Scripts 自动化脚本

这是能够让 AI 在这个 Skill 中自动化执行某些任务的脚本。你可以理解为：针对确定性高的重复性任务，比如格式检查、版本校验、文件批量处理、组件更新后自动同步等任务，可以编写到这个自动化脚本中，让 Skill 实现自主操作和更新，减少人工干预。

只有了解了 Skill 的结构原理，你才知道每个文件内该放什么、不能放什么，才能锁住 AI 行为，严格按你的设计规范为你干活。

3. 合理拆解任务和进行约束

AI 不是人，无法完全贴合人类的灵活思维，完全放任会导致输出质量不稳定，过度约束又会限制它的能力。所以在调优 Skill 时既要给 AI 留出判断空间，又要把控住核心任务标准，把自己的思考链路拆解成 AI 能理解的步骤。这里分享三个技巧：

 1）写法清晰

编排线性执行步骤时，可以使用清晰的 1、2、3 序号，为 AI 建立先后执行顺序。举个例子：

1. 寻找参考： 先规定去哪个文档里读取标准 Token 或组件库规范。
2. 进行决策： 再规定遇到 A 情况用什么布局，遇到 B 情况用什么布局。
3. 输出内容： 最后规定按照什么骨架和格式输出最终的组件代码或文档。

2）有效描述

不要陈述显而易见的内容，而是多描述哪些 AI 不知道的非客观规则，举个例子：

Claude Code 本身对编程已经非常熟悉，所以你不需要去教它“什么是 Vue/React 等主流框架”，而是去补充它默认机制里没有的关键信息，比如 “不要用 PingFang 字体”，“不要用红色渐变色”等等。

3）异常阻断

设定异常阻断机制，在工作流中埋入风险控制的兜底的逻辑，举个例子，可以添加类似的描述：

“如果用户的需求在现有组件库中无法找到对应模式，必须停止生成并向用户提问，绝对禁止自行硬编码。”

Skill 搭建从来不是 “一锤子买卖”，也不是单纯靠 AI 生成就能完成的工作。我们可以借助 AI 快速完成初版搭建，节省前期时间，但核心的场景定义、任务拆解、结构搭建、易错点沉淀，必须由人工把控。只有明确使用逻辑、遵循编写原则、完善文件结构、持续迭代优化，才能打造出真正适配自己工作流的稳定好用的 Skills。

欢迎关注作者微信公众号：「长弓小子」