okooo澳客app 怎样写出好的 Skill ？拆解 skill

Datawhale干货

作家：王大鹏，Datawhale成员

什么是 Skill？怎样写好 Skill？沿着 skill-creator的筹商想路，找到谜底。

一、什么是 Skill？1.1 界说

Skill 是一个文献夹，内部装着指示文档、参考贵府、可奉行剧本等资源。AI 拿到它，就能胜任一项底本不会的特定职责。

比如一个 pdf-editor手段文献夹里，可能有一份"怎样处理 PDF"的操作指示、一个旋转 PDF 的 Python 剧本、一份 API 参考文档——AI 不需要从外部再找任何东西，这个文献夹里全有了。

伸开剩余98%

这个主见不限于某一个家具。不管是 Codex、Claude 照旧其他 AI Agent，skill 的骨子齐一样。你可以把它交融为 AI 的一个智商插件——插上去，AI 就多了一项专长；拔掉，AI 照旧原来阿谁通用助手。

1.2 最小形态

一个 skill 最少只需要一个文献：

SKILL.md的结构很约略——上半部分告诉 AI"什么时候用我"，下半部分告诉 AI"具体怎样作念"：

上半部分叫 frontmatter（ ---之间的 YAML），包含 name和 deion两个字段。AI 在每次对话脱手时齐会扫描扫数已安设手段的 frontmatter，靠 deion 来判断"这个手段和刻下苦求有关吗"——这是手段的独一触发点。

下半部分叫 body（Markdown 正文），是手段被激活之后才加载的操作指示。要是手段没被触发，AI 永远不会读到这里。

1.3 竣工结构

当一个手段变复杂时，单靠一个 SKILL.md 就不够了。

比如你要作念一个"PDF 处理"手段：SKILL.md 里写了处理经过，但旋转 PDF 的代码每次齐一样，每次让 AI 重写既失掉期间又可能出错——不如平直放一个写好的 Python 剧本。再比如"前端项陌生成器"手段：每次齐要一套 HTML/React 的样板文献，不如平直放一个模板目次让 AI 拷贝出来改。

是以竣工的 skill 目次可以包含这些东西：

逐一诠释：

SKILL.md— 独一必需的文献，前边也曾先容过

s/— 写好的范例，AI 不需要读懂它，平直调用 shell 奉行就行。比如s/rotate_pdf.py，AI 只消跑python rotate_pdf.py input.pdf 90就能旋转 PDF，不必每次重新写旋转逻辑。恰当那些断绝必须精确、不可让 AI 解放发达的操作

references/— AI 在职责过程中需要查阅的参考贵府。比如一个"BigQuery 查询"手段，AI 要知谈公司有哪些表、每个表有什么字段，这些信息放在references/schema.md里，AI 需要时再读取。和 s 的区别是：references 是给 AI 读的，s 是给 AI 奉行的

assets/— 不是给 AI 看的，而是平直用在最终产出里的文献。比如一个"前端项陌生成器"手段，assets/frontend-template/里放着一套 HTML/React 样板代码，AI 平直把这套模板拷贝出来，在上头修改。再比如assets/logo.png是公司 logo，AI 生成网页时平直援用它。AI 不需要"读懂"一张 logo 图片，只需要知谈它在哪、什么时候放进去

agents/openai.yaml— 手段的"柬帖"。好多 AI 家具会在界面上展示一个手段列表，让用户接管或搜索。这个文献里存的即是列表中泄露的称号、简介、图标等信息。它不影响 AI 的行动，纯粹是给家具界面用的

SKILL.md— 独一必需的文献，前边也曾先容过

知谈了 skill 是什么，下一步即是写一个。但大无数东谈主第一次写出来的 skill 齐有肃清个问题。

看一个例子。假定要作念一个"代码审查"手段，你可能会这样写：

# Code Review Skill

## 配景本手段基于团队多年的代码审查教训总结而成，旨在莳植代码质料和团队配合成果。

## 审查原则-保握专科、建设性的语气 -关注代码质料而非个东谈主立场 -均衡严格性和生动性

## 使用方式当用户提嘱咐码时，对代码进行全面审查，给出转换提议。细心保握友好和饱读舞的立场。

## 版块记载-v1.0: 运行版块 -v1.1: 加多了对 Python 的解救

要是这是一份给东谈主看的团队文档，它写得可以——有配景、有原则、有使用方式，致使还有版块记载。

但 skill 的读者是 AI。用这个视角重新注视：

"基于团队多年教训总结"— AI 不见谅这个手段是怎样来的，它只需要知谈当今该怎样作念

"保握专科、建设性的语气"— 东谈主类读了能 get 到一个能够的嗅觉，但 AI 会把"专科"和"建设性"伸开成无数种组合，每次输出齐不一样

"均衡严格性和生动性"— 东谈主类教训丰富的审查者知谈什么时候严格什么时候生动，但 AI 莫得这个直观，这句话等于没说

"全面审查，给出转换提议"— 这是对东谈主类审查者的欲望，但 AI 需要的是：先查验什么？再查验什么？什么问题必须指出？什么问题可以忽略？

"版块记载"— AI 每次被叫醒齐是全新的，v1.0 照旧 v1.1 对它莫得爱慕

deion 只写了"代码审查手段"— AI 靠 deion 判断是否触发，"代码审查手段"五个字太朦胧：用户说"帮我望望这段代码"要触发吗？"这个函数性能怎样样"要触发吗？

"基于团队多年教训总结"— AI 不见谅这个手段是怎样来的，它只需要知谈当今该怎样作念

"保握专科、建设性的语气"— 东谈主类读了能 get 到一个能够的嗅觉，但 AI 会把"专科"和"建设性"伸开成无数种组合，每次输出齐不一样

"均衡严格性和生动性"— 东谈主类教训丰富的审查者知谈什么时候严格什么时候生动，但 AI 莫得这个直观，这句话等于没说

"全面审查，给出转换提议"— 这是对东谈主类审查者的欲望，但 AI 需要的是：先查验什么？再查验什么？什么问题必须指出？什么问题可以忽略？

"版块记载"— AI 每次被叫醒齐是全新的，v1.0 照旧 v1.1 对它莫得爱慕

每一条单独看齐没啥问题，但它们齐是写给东谈主看的。问题不在于写得不够多，而在于写错了对象。

那正确的写法是什么样的？咱们来看一个现成的谜底——codex的skill-creator。它是一个"创建 skill 的 skill"，它我方的 SKILL.md 即是一份对于"怎样给 AI 写指示"的最好实践。

三、skill-creator 的举座框架

绽放 skill-creator 的 SKILL.md（约 370 行），在深远任何细节之前，咱们先建立对它的举座理解。

skill-creator 要贬责的问题唯有一个：怎样在有限的高下文窗口里，给 AI 最灵验的指示？

围绕这个问题，它给出了一套竣工的筹商体系，可以用三个档次来交融。

第一层：压根敛迹——爽气

AI 的高下文窗口是有限的，而况是分享的（系统教唆、对话历史、扫数已安设手段的元数据齐在内部）。你的 skill 占得越多，留给其他用途的就越少。是以 skill-creator 的第一原则即是：每一句话齐要值得它占用的 token。

第二层：两个筹商维度

在"爽气"这个敛迹下，写 skill 时面对两个中枢决策：

维度一：信息放在那儿？

不是扫数信息齐需要一脱手就加载。skill-creator 筹商了一个三级分层架构，让不同的信息在不同的时机插足高下文：

L1（元数据）：永远在高下文中，约 100 词——AI 靠它判断要不要激活这个手段

L2（SKILL.md body）：触发后才加载，适度在 5k 词以内——操作指示

L3（s/references/assets）：按需使用，无上限——其中 s 奉行而不读入，零 token 资本

这贬责了"怎样用最少的 token 承载最多的信息"。

维度二：给 AI 多大解放度？

不是扫数任务齐恰当让 AI 解放发达。

举个例子：让AI 写一篇时候博客，十个东谈主写出十种立场齐可以——你只需要给场地，具体怎样写让 AI 我方决定。这即是高解放度。

但让 AI 生成一个 YAML 建设文献就不一样了。比如 skill-creator 要生成的 openai.yaml，内部有个short_deion字段，要求 25-64 个字符、首字母大写、不可有引号。AI 写成 65 个字符？不行，家具界面会截断。写成 24 个字符？不行，校验欠亨过。漏了首字母大写？界面泄露不一致。这种任务差一个字符就出问题，你不可让 AI 解放发达，必须用剧本来锁死阵势——这即是低解放度。这类任务叫"脆弱操作"：不是说它复杂，而是说它作念对唯有一种方式，作念错有一百种方式。

这贬责了"怎样在 AI 的生动性和输出的可靠性之间赢得均衡"。

第三层：落地经过

有了原则和架构，skill-creator 终末给出了一个六步创建经过，把筹商想想变成可奉行的操作设施：

交融→推测→运行化→剪辑→校验→迭代。其中剧本代码流畅经过，酿成战胜性的保险：

框架总览

三个档次的商量：

接下来的每一章齐在这个框架内伸开。

四、压根敛迹：爽气

框架位置：第一层

4.1 中枢敛迹

AI 的高下文窗口就像一张职责台——它肃清期间能摊开的贵府是有限的。而这张职责台上也曾放着不少东西了：系统我方的限定、用户之前说过的话、扫数已安设手段的简介。你的 skill 一朝被激活，它的内容也要摊上去。职责台就这样大，你占得越多，留给其他东西的空间就越少。

是以 skill-creator 把这一丝写成了第一条原则：

The context window is a public good. Skills share the context window with everything else Codex needs: system prompt， conversation history， other Skills' metadata， and the actual user request.

既然职责台空间有限，那写 skill 时怎样判断一段内容该不该放进去？skill-creator 给了一个前提假定：AI 自己也曾很忠良了，你只需要补充它不知谈的东西。

Default assumption: Codex is already very smart. Only add context Codex doesn't already have.

基于这个假定，每写一段内容之前问我方两个问题：

"AI 是不是也曾知谈这个了？" — 比如"Python 的 for 轮回怎样写"，AI 自然知谈，okooo澳客不必教

"这段内容值不值得占用职责台上的空间？" — 一段 200 字的讲授，能不可用一个 10 行的代码示例替代？

"AI 是不是也曾知谈这个了？" — 比如"Python 的 for 轮回怎样写"，AI 自然知谈，不必教

"这段内容值不值得占用职责台上的空间？" — 一段 200 字的讲授，能不可用一个 10 行的代码示例替代？

实操推行：用爽气的示例代替冗长的讲授。一个好的代码示例胜过三段笔墨刻画。

4.2 什么不该放进 Skill？

Skill-creator 明确列出了不容清单：

A skill should only contain essential files that directly support its functionality. Do NOT create extraneous documentation or auxiliary files.

不该有的文献：

README.md

INSTALLATION_GUIDE.md

QUICK_REFERENCE.md

CHANGELOG.md

README.md

INSTALLATION_GUIDE.md

QUICK_REFERENCE.md

CHANGELOG.md

原因很约略：skill 的读者是 AI，不是东谈主类开拓者。AI 不需要安设指南、更新日记、快速参考这些"东谈主类扶助文档"。每一个饱胀的文献齐是杂音。

4.3 写敛迹时，"不作念什么"比"作念什么"更精确

爽气不仅仅"少写"，还包括"写对"。看一个例子。

当 skill-creator 创建 laotou-thought-style（一种写稿立场手段）时，它莫得写：

这种正面刻画看起来通晓，但对 AI 来说，"慈悲"的进度、"克制"和"有瞻念察力"之间的均衡——全是朦胧空间。

它作念的是写了一份反模式清单（references/anti-patterns.md）：

每一条齐是具体的、可检测的、有明确修正决策的。

背后的旨趣：

skill-creator 自身也遵照了这个原则——它的 SKILL.md 用了很大篇幅说"什么不该写"（What to Not Include in a Skill），而不是鄙俚地说"写好内容"。

当你写完 SKILL.md，作念一次"回转测试"：每一条正面带领，能不可改写成"不要作念X"的表情？要是可以，改写后时常更精确。

4.4 调处使用祈使语气

skill-creator 要求 SKILL.md 的正文调处使用祈使语气/不定式（Always use imperative/infinitive form）。这不是好意思学偏好，而是为了减少歧义——祈使句自然即是指示。

五、筹商维度一：信息放在那儿？

框架位置：第二层 — 维度一

在第三章的框架总览中，咱们也曾看到了三级分层架构的全貌。这一章伸开讲它的细节。

5.1 三级渐进式加载

skill-creator 原文对三个层级的界说：

1. Metadata (name + deion)- Always in context (~100 words)

2. SKILL.md body- When skill triggers (<5k words)

3. Bundled resources- As needed by Codex (Unlimited because s can be executed without reading into context window)

1. Metadata (name + deion)- Always in context (~100 words)

2. SKILL.md body- When skill triggers (<5k words)

3. Bundled resources- As needed by Codex (Unlimited because s can be executed without reading into context window)

这骨子上是一个信息熵管制系统：

L1 是过滤器— 从几十个已安设手段中筛选出刻下需要的那一个。deion 不精确 → 误触发或漏触发

L2 是操作手册— 触发后告诉 AI 该怎样作念。太长 → 细心力被稀释。body 适度在 500 行以内

L3 是器具箱— 只在需要时绽放。其中 s/ 最高效—— 奉行而不读入，零 token 资本

L1 是过滤器— 从几十个已安设手段中筛选出刻下需要的那一个。deion 不精确 → 误触发或漏触发

L2 是操作手册— 触发后告诉 AI 该怎样作念。太长 → 细心力被稀释。body 适度在 500 行以内

L3 是器具箱— 只在需要时绽放。其中 s/ 最高效—— 奉行而不读入，零 token 资本

Frontmatter 唯有两个必需字段：name和deion。但 deion 的写法至关紧迫：

This is the primary triggering mechanism for your skill， and helps Codex understand when to use the skill.

skill-creator 我方的 deion 是这样写的：

它不单说"作念什么"（creating effective skills），还说"什么时候用"（when users want to create a new skill or update an existing skill）。

重要限定：

把扫数"when to use"信息放在 deion 里，不要放在 body 里。body 是触发后才加载的，当时候 Codex 也曾决定用了，"什么时候用"的信息也曾迟了

不要在 frontmatter 中放 name和deion除外的字段（license、allowed-tools、metadata除外）

把扫数"when to use"信息放在 deion 里，不要放在 body 里。body 是触发后才加载的，当时候 Codex 也曾决定用了，"什么时候用"的信息也曾迟了

不要在 frontmatter 中放 name和deion除外的字段（license、allowed-tools、metadata除外）

一个好的 deion 示例（docx 手段）：

5.3 四种系结资源的骨子区别

交融这四种资源的区别，是交融通盘 skill 系统的重要：

s（s/）

可奉行代码（Python/Bash 等），用于需要战胜性可靠性或反复重写的任务。

什么时候需要：不异的代码每次齐要重新写，或者需要战胜性的可靠输出

例如：s/rotate_pdf.py用于 PDF 旋转任务

中枢上风：token 高效、战胜性、可以奉行而不读入高下文窗口

细心：剧本或然仍需要被 Codex 读取，用于修补或环境适配

什么时候需要：不异的代码每次齐要重新写，或者需要战胜性的可靠输出

例如：s/rotate_pdf.py用于 PDF 旋转任务

中枢上风：token 高效、战胜性、可以奉行而不读入高下文窗口

细心：剧本或然仍需要被 Codex 读取，用于修补或环境适配

References（references/）

文档和参考材料，在需要时加载到高下文中，扶助 Codex 的想考过程。

什么时候需要：Codex 在职责时需要参考的详备文档

例如：references/finance.md（财务 schema）、references/api_docs.md（API 表率）、references/policies.md（公司策略）

用途：数据库 schema、API 文档、领域常识、公司策略、详备职责流指南

中枢上风：保握 SKILL.md 高超，只在 Codex 判断需要时才加载

最好实践：要是文献很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式

幸免重叠：信息应该只存在于 SKILL.md 或references 文献中，不可双方齐有。详备信息优先放 references，SKILL.md 只保留中枢经过指示和职责流带领

什么时候需要：Codex 在职责时需要参考的详备文档

例如：references/finance.md（财务 schema）、references/api_docs.md（API 表率）、references/policies.md（公司策略）

用途：数据库 schema、API 文档、领域常识、公司策略、详备职责流指南

中枢上风：保握 SKILL.md 高超，只在 Codex 判断需要时才加载

最好实践：要是文献很大（>10k 词），在 SKILL.md 中包含 grep 搜索模式

幸免重叠：信息应该只存在于 SKILL.md 或references 文献中，不可双方齐有。详备信息优先放 references，SKILL.md 只保留中枢经过指示和职责流带领

Assets（assets/）

不是用来加载到高下文中的文献，而是平直用在 Codex 产出物中的资源。

什么时候需要：手段需要在最终输出中使用的文献

例如：assets/logo.png（品牌素材）、assets/slides.pptx（PPT 模板）、assets/frontend-template/（HTML/React 样板）、assets/font.ttf（字体）

用途：模板、图片、图标、样板代码、字体、示例文档——这些会被复制或修改

中枢上风：将输出资源与文档分辩，Codex 可以使用它们而无需读入高下文

什么时候需要：手段需要在最终输出中使用的文献

例如：assets/logo.png（品牌素材）、assets/slides.pptx（PPT 模板）、assets/frontend-template/（HTML/React 样板）、assets/font.ttf（字体）

用途：模板、图片、图标、样板代码、字体、示例文档——这些会被复制或修改

中枢上风：将输出资源与文档分辩，Codex 可以使用它们而无需读入高下文

Agents 元数据（agents/openai.yaml）（推选）

面向 UI 的元数据，不给 AI 读，给家具前端读：

包含 display_name、short_deion、default_prompt等字段

通过剧本generate_openai_yaml.py战胜性生成，而不是手写

更新 SKILL.md 后要查验agents/openai.yaml是否还匹配，逾期了就重新生成

详备字段界说见references/openai_yaml.md

包含 display_name、short_deion、default_prompt等字段

通过剧本generate_openai_yaml.py战胜性生成，而不是手写

更新 SKILL.md 后要查验agents/openai.yaml是否还匹配，逾期了就重新生成

详备字段界说见references/openai_yaml.md

Skill-creator 给出了三种把内容拆分到 references 的具体模式：

Pattern 1：高层指南 + 参考文献

## Quick startExtract text with pdfplumber:[code example]

## Advanced features-**Form filling**: See [FORMS.md](FORMS.md) for complete guide-**API reference**: See [REFERENCE.md](REFERENCE.md) for all methods-**Examples**: See [EXAMPLES.md](EXAMPLES.md) for common patterns

Codex 只在需要时才加载 FORMS.md、REFERENCE.md 或 EXAMPLES.md。

Pattern 2：按领域组织

多领域/多变体手段，按领域拆分幸免加载无关内容：

用户问销售办法时，Codex 只读 sales.md

不异适用于多框架/多变体场景：

Pattern 3：条目性细节

基础功能平直展示，高等功能按需相连：

# # Creating documentsUse docx-js for new documents. See [DOCX-JS.md](DOCX-JS.md).

# # Editing documentsFor simple edits， modify the XML directly.

**For tracked changes**: See [REDLINING.md](REDLINING.md)**For OOXML details**: See [OOXML.md](OOXML.md)

5.5 两条紧迫的避坑指南

幸免深层嵌套援用— 扫数 reference 文献应该从 SKILL.md 平直相连，不要 A → B → C 式嵌套

长文献加目次— 跨越 100 行的 reference 文献要在顶部加 TOC，浮浅 Codex 预览全貌

幸免深层嵌套援用— 扫数 reference 文献应该从 SKILL.md 平直相连，不要 A → B → C 式嵌套

长文献加目次— 跨越 100 行的 reference 文献要在顶部加 TOC，浮浅 Codex 预览全貌

六、筹商维度二：给 AI 多大解放度？

框架位置：第二层 — 维度二

知谈了信息该放在那儿、该怎样敛迹，下一个问题是：AI 作念什么，剧本作念什么？

AI 相当擅长交融语义、生成文本、作念创造性职责。但它不擅长精确阵势适度、长度敛迹、定名表率——这些"脆弱操作"。

6.1 三个解放度档位

Skill-creator 用一个解放度光谱来处理这种不均匀性（见第三章框架图）：

Think of Codex as exploring a path: a narrow bridge with cliffs needs specific guardrails (low freedom)， while an open field allows many routes (high freedom).

高解放度（笔墨指示）：多种设施齐可行时，决策依赖高下文，用启发式指点。

中解放度（伪代码/带参数的剧本）：有最好实践但允许变通，建设影响行动。

低解放度（具体剧本，小数参数）：操作脆弱容易出错，一致性至关紧迫，必须遵照特定序列。

中枢逻辑：

6.2 skill-creator 自身的解放度分拨

6.3 两个场地的失误

失误 1：给脆弱任务太多解放度

# 后果：short_deion 可能跨越 64 字符断绝，大小写可能不一致

Skill-creator 的作念法：用 generate_openai_yaml.py剧本锁死阵势。AI 只提供参数值，剧本保证输出合规。

失误 2：给创造性任务太多敛迹

# 后果：生成的文本像填词游戏

Skill-creator 的作念法：给结构比例（场景层 ≤30%，旨趣层 30-40%），但不锁定具体用词。

6.4 判断模范

两个问题：

作念错了后果多严重？— 越严重 → 越低解放度

有些许种"正确"的作念法？— 越多 → 越高解放度

作念错了后果多严重？— 越严重 → 越低解放度

有些许种"正确"的作念法？— 越多 → 越高解放度

交融了解放度光谱，就能交融 skill-creator 为什么有三个剧本——它们即是"低解放度"的具体终了（剧本间的交互商量见第三章框架图）。

init_skill.py（输入保险，398 行）

运行化生人段目次的脚手架器具，雷同 create-react-app之于 React 名堂：

中枢功能：

创建手段目次

生成带 TODO 占位符的 SKILL.md 模板（TODO 是给 Codex 看的"填空题"）

调用 generate_openai_yaml.py生成agents/openai.yaml（通过--interface key=value传入 AI 生成的 display_name、short_deion、default_prompt）

可选创建 s/、references/、assets/子目次

可选添加示例文献（--examples）

内置 normalize_skill_name自动把纵情用户输入模范化为 hyphen-case

创建手段目次

生成带 TODO 占位符的 SKILL.md 模板（TODO 是给 Codex 看的"填空题"）

调用 generate_openai_yaml.py生成agents/openai.yaml（通过--interface key=value传入 AI 生成的 display_name、short_deion、default_prompt）

可选创建 s/、references/、assets/子目次

可选添加示例文献（--examples）

内置 normalize_skill_name自动把纵情用户输入模范化为 hyphen-case

使用示例：

generate_openai_yaml.py（阵势保险，226 行）

额外庄新生成和更新 agents/openai.yaml：

从 SKILL.md 的 frontmatter 读取手段名

自动将 hyphen-case 转为 Title Case（my-cool-skill→My Cool Skill）

内置缩写辞书（GH、MCP、API 等保握大写）和品牌辞书（openai → OpenAI）

自动生成25-64 字符的short_deion

解救 --interface key=value阴事纵情字段

从 SKILL.md 的 frontmatter 读取手段名

自动将 hyphen-case 转为 Title Case（my-cool-skill→My Cool Skill）

内置缩写辞书（GH、MCP、API 等保握大写）和品牌辞书（openai → OpenAI）

自动生成25-64 字符的short_deion

解救 --interface key=value阴事纵情字段

generate_openai_yaml.py（输出保险，102 行）

手段创建后的"质检"：

校验内容：

SKILL.md 是否存在

YAML frontmatter 阵势是否正当

name：是否为 hyphen-case，≤ 64 字符，无一语气/首尾连字符

deion：是否存在，无尖括号，≤ 1024 字符

只允许name、deion、license、allowed-tools、metadata这 5 个 frontmatter 键

SKILL.md 是否存在

YAML frontmatter 阵势是否正当

name：是否为 hyphen-case，≤ 64 字符，无一语气/首尾连字符

deion：是否存在，无尖括号，≤ 1024 字符

只允许name、deion、license、allowed-tools、metadata这 5 个 frontmatter 键

三个剧本酿成了一条职责流链路，夹住中间的创造性设施：

剧本是"奉行而不读入"的——零 token 资本。你可以把纵情复杂的战胜性逻辑封装进剧本，而不必惦记它占用高下文。这即是为什么 skill-creator 把定名调节（缩写辞书、品牌辞书）、长度敛迹（25-64 字符）、阵势校验这些细碎但脆弱的操作全部交给了剧本代码。

6.7 什么该封装成剧本？

需要交融高下文 → 笔墨指示有多种合理作念法 → 笔墨指示需要创造性判断 → 笔墨指示

剧本的界说是奉行，诚然或然仍需要被 Codex 读取（用于修补或环境适配），但大无数时候它们是"奉行而不读入"的。

七、落地：六步创建经过

框架位置：第三层

有了前边的原则和架构，skill-creator 终末给出了一个六步创建经过，把筹商想想变成可奉行的操作设施（见第三章框架图）。

7.0 定名表率

在脱手之前，先战胜定名：

只用小写字母、数字和连字符；把用户提供的称号模范化为 hyphen-case（如 "Plan Mode" → plan-mode）

称号 ≤ 64 字符

优先用简陋的、动词着手的短语来刻画当作

需要时用器具名作念定名空间（如 gh-address-comments、linear-address-issue）

只用小写字母、数字和连字符；把用户提供的称号模范化为 hyphen-case（如 "Plan Mode" → plan-mode）

称号 ≤ 64 字符

优先用简陋的、动词着手的短语来刻画当作

需要时用器具名作念定名空间（如 gh-address-comments、linear-address-issue）

手段文献夹名与手段名透顶一致

Skip this step only when the skill's usage patterns are already clearly understood.

要创建一个灵验的 skill，必须先明晰交融具体的使用例子。这些交融可以来私用户提供的例子，也可以来自生成的、经用户考证的例子。

以构建 image-editor 手段为例，可以问用户：

"image-editor 手段应该解救什么功能？剪辑、旋转，还有其他吗？"

"能给一些使用这个手段的例子吗？"

"我能猜度用户会说'去掉这张相片的红眼'或'旋转这张图片'。还有其他使用方式吗？"

"用户会说什么话来触发这个手段？"

"image-editor 手段应该解救什么功能？剪辑、旋转，还有其他吗？"

"能给一些使用这个手段的例子吗？"

"我能猜度用户会说'去掉这张相片的红眼'或'旋转这张图片'。还有其他使用方式吗？"

"用户会说什么话来触发这个手段？"

细心：不要一次问太多问题。先问最紧迫的，然后凭证需要跟进。

完成象征：敌手段应该解救的功能有了通晓的意志。

7.2 Step 2：推测可复用的手段内容

对每个具体例子作念两个分析：

要是从零脱手作念这件事，需要什么？

其中哪些会被反复使用？

要是从零脱手作念这件事，需要什么？

其中哪些会被反复使用？

反复使用的东西 → 封装成 s/references/assets。

skill-creator 给了三个典型分析案例：

{jz:field.toptypename/}

案例 1：pdf-editor手段（用户问"帮我旋转这个 PDF"）

旋转 PDF 每次齐要重写不异的代码

→ 封装为 s/rotate_pdf.py

旋转 PDF 每次齐要重写不异的代码

→ 封装为 s/rotate_pdf.py

案例 2：frontend-webapp-builder手段（用户问"帮我作念一个 todo app"或"作念一个步数跟踪神态盘"）

写前端 webapp 每次齐需要不异的 HTML/React 样板代码

→ 封装为 assets/hello-world/模板目次

写前端 webapp 每次齐需要不异的 HTML/React 样板代码

→ 封装为 assets/hello-world/模板目次

案例 3：big-query手段（用户问"今天有些许用户登录了？"）

查询 BigQuery 每次齐要重新发现表的 schema 和商量

→ 封装为 references/schema.md

查询 BigQuery 每次齐要重新发现表的 schema 和商量

→ 封装为 references/schema.md

完成象征：列出了扫数要包含的可复用资源清单（s、references、assets）。

7.3 Step 3：运行化手段

When creating a new skill from scratch， always run the init_skill.py.

这里用的是"always"——不是"提议"，是"老是"。原因：

剧本生成的目次结构保证稳健表率

模板中的 TODO 提醒确保不遗漏必需字段

agents/openai.yaml的阵势敛迹（字段长度、引号限定）靠手写容易出错

剧本生成的目次结构保证稳健表率

模板中的 TODO 提醒确保不遗漏必需字段

agents/openai.yaml的阵势敛迹（字段长度、引号限定）靠手写容易出错

这是低解放度原则的平直期骗：运行化是一个脆弱操作，用剧本放手出错可能。

运行化后：

定制 SKILL.md 并凭证需要添加资源

要是用了 --examples，替换或删除占位符文献

定制 SKILL.md 并凭证需要添加资源

要是用了 --examples，替换或删除占位符文献

这是最中枢的设施，分两阶段：

阶段一：先终了可复用资源

从 Step 2 推测的资源脱手：终了 s/、references/、assets/文献。

细心：

这一步可能需要用户输入（比如 brand-guidelines手段需要用户提供品牌素材）

新增的剧本必须通过实验运行来测试，确保无 bug 且输出稳健预期

要是有好多雷同的剧本，只需测试代表性样本来建立信心

要是用了 --examples，删除不需要的占位符文献。只创建着实需要的资源目次

这一步可能需要用户输入（比如 brand-guidelines手段需要用户提供品牌素材）

新增的剧本必须通过实验运行来测试，确保无 bug 且输出稳健预期

要是有好多雷同的剧本，只需测试代表性样本来建立信心

要是用了 --examples，删除不需要的占位符文献。只创建着实需要的资源目次

阶段二：更新 SKILL.md

Frontmatter 写法：

Body 写法：

写给另一个 Codex 实例的操作指示。包含对 Codex 有匡助但不可想而知的信息：范例性常识、领域细节、可复用资源的使用方式。

调处使用祈使语气/不定式。

7.5 Step 5：校验手段

校验 YAML frontmatter 阵势、必需字段、定名限定。欠亨过就缔造后重新运行。

7.6 Step 6：迭代

After testing the skill， users may request improvements. Often this happens right after using the skill， with fresh context of how the skill performed.

迭代职责流：

在确切任务上使用手段

发现用功或低效的地方

找出 SKILL.md 或系结资源该怎样更新

实施变更并重新测试

在确切任务上使用手段

发现用功或低效的地方

找出 SKILL.md 或系结资源该怎样更新

实施变更并重新测试

好的 skill 不是一次写成的。skill-creator 创建的 laotou-thought-style 手段，在第一次生成后就迭代了 openai.yaml的short_deion和default_prompt——从鄙俚的刻画变为更精确的操作指示。

八、总结

回到率先的问题：怎样写出好的 skill？

追思通盘框架：

起始明确 Skill 是给 AI 写指示，而不是给东谈主，Skill 骨子是：用最少的 token，在正确的层级，给 AI 最精确的敛迹，让它在领域内解放发达。

全部“ 点赞 ” 三连 ↓

发布于：浙江省