怎么写好一个 Skill

从 ecomfe/tempad-dev 仓库的 figma-design-to-code skill(版本 v4.3)逆向分析,提炼出的可复用方法论。源文件:单文件 SKILL.md,393 行 / 17.5KB,纯指令型,不含任何可执行代码。

一、样本 skill 速览

一句话定性:这是一份纯指令型 skill —— 不含任何可执行代码,全部能力编码在一份 393 行的 SKILL.md 里;真正"干活"的是它依赖的 TemPad Dev MCP,skill 本身只规定怎么取证据、怎么把证据转成代码、什么时候该停。版本号 4.3,说明迭代过多轮,写法成熟。

三个支柱:

支柱	内容
三层真理来源	项目文件 = 实现真理;TemPad 输出 = 设计真理;用户 = 决策真理。三者冲突时按优先级收敛,不许脑补
认识论边界	用"can prove / cannot prove"给设计证据画红线——可见结构/间距/颜色/token 能证明;隐藏态/响应式/行为/工程惯例不能证明。预封幻觉入口
五步线性工作流	读本地证据 → 拉顶层快照(`get_code`)→ 消解不完整/冲突证据 → 按项目风格实现 → 项目检查与契约式收尾

约束体系:3 条硬规则(不输出 hint / 不编造未证据化细节 / 高级输出视为有意)+ 8 条停止条件(宁可停也不交)+ 契约式收尾(强制结构化报告,阻塞时最多给 3 条下一步)。

设计哲学浓缩:用证据约束替代自由发挥,用停止点替代过度自信。 它不是"教模型干活",而是"管住模型别乱干"。

二、写好 Skill 的方法论(10 条)

按"从 0 到 1"的顺序组织。

0. 先定性:你的 skill 是哪一类

写之前先想清楚,这决定了整份文档的骨架:

类型	特征	适合
指令型(纯 prompt)	没有代码,只有约束/方法论	把一个成熟流程固定下来。本例就是
工具型(带脚本)	提供模型本来做不到的能力	解析特定格式、跑本地命令、调用内部 API
混合型	prompt + 辅助脚本/references	既有流程约束,又有专用工具

最常见的误判:以为 skill 必须"能干活"。其实很多好 skill 是"约束模型怎么干活"。这个 figma skill 一行可执行代码都没有,但它有效——因为它把一个容易出错的领域(Figma 转码)的行为规范钉死了。

1. frontmatter 是触发器,不是装饰

yaml

name: <kebab-case-id>
description: ...
metadata:
  version: 'x.y'

description 决定 skill 何时被加载进上下文。这是 skill 的命门——写糊了就永远不被触发,或到处乱触发。
必须写清两件事:何时用 + 何时不用。这个 skill 的 description 明确列了 Do not use for design critique, product invention, generic code review...,这种"反向边界"能有效防止误触发。
version 别省,skill 是要迭代的,版本号是演进的主线。

2. 用"证据/置信度框架"替代"命令清单"

这是这份 skill 给出的最重要启示,也是业余写法和专业写法的分水岭。

坏写法:列 50 条"做 X / 别做 Y"。总有漏网场景,模型遇到没列到的情形就放飞。
好写法:建立一套置信度体系——什么算真相(source of truth)、什么算推断(inference)、什么算猜测(guess)——让模型在新场景下也能自洽决策。

落地动作:给领域画一条"能证明 / 不能证明"的边界。比如这个 skill 明确说 TemPad"不能证明隐藏态、响应式、行为、工程惯例"。这条边界一旦画清,模型在这些方向上的脑补就被预先堵住了,不需要逐一列举。

3. 抽象规则必须落到"症状 + 对策"

原则性的话谁都会写,难的是可执行。每条规则问自己:模型遇到这个具体情形,下一步动作是什么?

抽象(不可执行)	落地(可执行)
"遇到错误不要瞎重试"	"`depth-cap` → 保留返回的父级作为布局真相,用 `data-hint-id` 挑更窄子树重取"
"证据不全就缩小范围"	"budget overflow / shell 响应 → 保留父级 shell,把省略的子树单独取回填进已知 shell;选能保留共享布局的最小父容器"
"MCP 不可用就停"	"请用户去 TemPad Dev Preferences > Agent integration 启用,或用 MCP badge 激活正确的 Figma 标签页"

给每个常见错误/警告配一段"分类 + 对策",比写十句"要小心"有用得多。

4. 预设停止点,而非成功路径

业余 skill 满篇"如何一路绿灯",专业 skill 大篇幅写"何时停、何时问"。

这是反"过度自信"的设计:宁可中断让用户决策,也不让模型硬编下去。
具体做法:单独列一节 Stop conditions,清单化。这个 skill 列了 8 条(MCP 不可用、证据冲突、父级不可恢复、需新依赖未确认……)。
同时配套一条提问纪律:"只在答案会实质改变实现、且无法从证据得出时才问用户",并列出典型阻塞类型。避免模型要么不问、要么问个没完。

5. 工作流要线性,每步有明确产出

骨架必须是有序的、可验证的,而不是"视情况灵活处理"。

这个 skill 的五步,每步开头是动词、产出可验证:

1. Read local evidence first      → 产出:框架/样式/token/资源管线 已建立
2. Fetch top-level snapshot       → 产出:code/lang/warnings/assets/tokens/codegen 已记录
3. Resolve incomplete evidence    → 产出:冲突已消解 or 已 stop
4. Implement in project style     → 产出:符合项目约定的代码
5. Project checks and handoff     → 产出:检查状态 + 契约式报告

写工作流时,每步自问:这一步结束,我手里多了什么可验证的东西?

6. 职责边界清晰,不越权立法

这个 skill 反复强调:与 Figma 转码无关的事,听 AGENTS.md,skill 不另立政策。检查矩阵、代码规范、lint 命令全部外置给项目。

好处:

skill 框架无关(React/Vue/原生都适用,因为它不假设你用什么)。
不和项目既定指令打架。
可移植到不同项目。

反面教训:很多 skill 失败在"什么都想管"——又定代码规范、又定检查命令、又定文件结构,结果换个项目就失效,还和项目自己的配置冲突。管好自己那一亩三分地。

7. 钉死工具调用的默认参数

如果 skill 要调 MCP / CLI / 工具,把该传的参数写死默认值,并注明哪个返回字段才是权威。

这个 skill 的做法:

resolveTokens: false(默认)
nodeId 仅在用户提供时传
preferredLang 对齐项目,但返回的 lang 才是权威(插件可能覆盖 preferredLang)
codegen.config.{cssUnit,rootFontSize,scale} 是单位换算的唯一权威

模型对"该传什么参数、信哪个返回值"是有自由发挥空间的——把这些钉死,等于堵掉一类系统性错误。

8. 契约式收尾:强制结构化输出

这是反"含糊交付"的关键一招。skill 结尾规定:交付时必须按清单报告:

实现了什么、放在哪
证据警告 / 是否用了 shell 恢复或子树缝合
资源处理(本地存储 or 仍依赖外部 URL)
token 处理(映射了哪些 / 保留引用 / 回退显式值)
依赖说明(是否新增、是否获批)
检查状态(跑了什么、过没过、什么仍 unverified)
残留视觉风险 + 用户仍需做的确认
被阻塞时,最多给用户 3 条具体下一步

模型天然倾向说"我做完了",这份契约逼它把"做完了"拆成可追责的事实陈述。你的 skill 也该有一份交付清单。

9. 反幻觉的几个具体抓手

从这份 skill 直接可抄的几条:

不输出内部 hint 属性(data-hint-*)——推理用的中间态绝不进产物。
不编造未证据化的细节——颜色/间距/圆角/隐藏态/响应式/交互,凡证据没给的,不许脑补。
高级/罕见输出视为有意——别擅自"简化"成你以为的常规写法。
小事不打断,大事才停——微小且不阻塞的缺口,带"明确声明的推断"继续;会实质改变实现的缺口,才停或问。
不做开放式调参循环——没有新证据就别无限调样式,剩余差异说不清就警告 + 停。

10. 好 skill 是迭代出来的

v4.3 不是一次写成的。从规则密度看,它的演进主线很清楚:把零散的"做/不做"逐步抽象成证据原则。

第一版可以糙,但一定要有可验证的产出契约(见第 8 条),这样你才能 loop 改进——跑一遍,看模型在哪放飞,加一条约束,再跑。
每次迭代问自己:这次模型犯错,是因为缺规则,还是缺原则?缺规则补一条"症状+对策";缺原则补一段"证据边界"。

三、最小可用骨架

按这个骨架填,再按第 10 条迭代,基本就能写出一份不掉链子的 skill。

markdown

---
name: my-skill
description: <何时用>. Do not use for <何时不用的反向边界>.
metadata:
  version: '1.0'
---

# <Skill 标题>

## 真理来源
- <来源A> = <角色>
- <来源B> = <角色>
- <来源C> = <角色>
画清"能证明 / 不能证明"的边界。

## 工作流
1. <动词>... → 产出:<可验证物>
2. <动词>... → 产出:<可验证物>
3. <动词>... → 产出:<可验证物>

## 停止条件
- <情形1> → 停
- <情形2> → 停

## 交付契约
结束时必须报告:<清单>。被阻塞最多给 3 条下一步。

附:样本 skill 的结构复盘

figma-design-to-code/
└── SKILL.md   # 唯一文件,17.5KB / 393 行

SKILL.md 内部章节:

Evidence model(三层证据通道)
What TemPad Dev can and cannot prove(认识论边界)
Default operating rules(3 条硬规则 + 提问纪律)
Workflow(五步,第 3 步含错误分类对策 + 重试策略)
Assets / Tokens / Semantics & accessibility(三大子主题细则)
Stop conditions(8 条)
Output contract(契约式收尾)
Examples(3 个典型场景)

怎么写好一个 Skill ​

一、样本 skill 速览 ​

二、写好 Skill 的方法论(10 条) ​

0. 先定性:你的 skill 是哪一类 ​

1. frontmatter 是触发器,不是装饰 ​

2. 用"证据/置信度框架"替代"命令清单" ​

3. 抽象规则必须落到"症状 + 对策" ​

4. 预设停止点,而非成功路径 ​

5. 工作流要线性,每步有明确产出 ​

6. 职责边界清晰,不越权立法 ​

7. 钉死工具调用的默认参数 ​

8. 契约式收尾:强制结构化输出 ​

9. 反幻觉的几个具体抓手 ​

10. 好 skill 是迭代出来的 ​

三、最小可用骨架 ​

附:样本 skill 的结构复盘 ​