本文通过一个真实案例，阐述了开发AI Skill时常见的错误：将写给人看的文档当作给AI的指令。文章详细介绍了Skill的基本概念、文件结构（SKILL.md、scripts、references等），并强调Skill设计应遵循简洁至上原则，区分写给人与写给AI的不同需求。此外，文章还提出了Skill设计的核心架构（三级渐进式加载）和决策原则（自由度匹配），最后以六步流程指导读者如何实际创建一个Skill。掌握这些方法，开发者可高效创建出精准执行的能力插件，让AI在特定领域发挥专业作用。

引言：一个真实的故事

上周，我的朋友小李第一次尝试为 Claude 创建一个 Skill。

满怀信心，他写了一个 3000 字的文档——背景、原则、使用方式，甚至还附上了版本记录。结果呢？AI 根本不会用。小李困惑了：“我写得这么详细，为什么 AI 还是不理解？”

问题的根源很简单：他写的不是给 AI 看的指令，而是给人看的说明书。

这个错误，几乎所有 Skill 新手都会犯。今天，我们就来聊聊如何真正写好一个 Skill——不是写一份漂亮的文档，而是创建一个让 AI 能够精准执行的能力插件。

一、Skill 到底是什么？

最简单的理解

想象你刚买了一台新手机。

拆开盒子时，它只能打电话、发短信——这是"基础能力"。但装了微信、抖音、淘宝后，它就多了聊天、刷视频、购物这些"专项能力"。

Skill 就是 AI 的 App。

没装 Skill 的 AI，像一个通用的智能助手——什么都能聊，但遇到专业任务就抓瞎。装了 Skill 之后，它在特定领域变得专业，比如处理 PDF、分析 Excel、生成前端项目。

更准确地说，Skill 是一个文件夹。里面装着让 AI 完成某项特定工作所需的所有资源。AI 拿到这个文件夹，就能胜任一项原本不会的工作。

最小形态：只需要一个文件

一个 Skill 最少只需要一个文件：SKILL.md

这个文件分上下两部分。

上半部分叫 frontmatter：

--- 
name: pdf-rotator 
description: 旋转 PDF 文件。当用户说"旋转这个 PDF"或"把这个 PDF 转90度"时使用。 
---
 

就两个字段：name（技能名称）和 description（技能描述）。AI 在每次对话开始时，都会扫描所有已安装技能的 description，用它来判断"这个技能和当前请求相关吗"。

这是技能的唯一触发点。

下半部分叫 body：

## 使用方式 
1. 检测用户提供的 PDF 文件路径 
2. 询问旋转角度（默认90度） 
3. 运行：python scripts/rotate.py [文件路径] [角度] 
 

这是技能被激活后才加载的操作指令。没触发？AI 永远不会读到这里。

完整结构：当简单不够用时

技能变复杂时，单靠一个 SKILL.md 就不够了。

这时需要更完整的目录结构：

my-skill/ 
├── SKILL.md          # 必需，操作指令 
├── scripts/          # 可选，可执行脚本 
├── references/       # 可选，参考文档 
├── assets/           # 可选，输出素材 
└── agents/ 
    └── openai.yaml   # 可选，UI展示信息 
 

这四种资源有本质区别，理解它们是掌握 Skill 设计的关键：

• scripts/：让 AI 执行的代码。比如 rotate_pdf.py，AI 直接调用，不用读懂
• references/：让 AI 阅读的文档。比如数据库 schema、API 规范
• assets/：让 AI 使用的素材。比如模板、图片、字体，直接用在输出里
• agents/openai.yaml：让 UI展示的信息。名称、图标、简介，AI 不读

二、最常见的错误：写给人 vs 写给 AI

一个反面教材

假设要创建一个"邮件撰写助手"技能，大多数人会这样写：

--- 
name: email-writer 
description: 邮件撰写技能 
---
 
# Email Writer Skill 
 
## 背景 
本技能基于商务沟通的最佳实践，帮助用户撰写得体的邮件。 
 
## 核心原则 
- 保持专业、礼貌的语气 
- 语言简洁，重点突出 
- 适应不同场景和收件人 
 
## 使用方式 
当用户需要写邮件时，根据需求撰写合适的邮件内容。 
 
## 版本记录 
- v1.0: 初始版本 
- v1.1: 增加了对中文邮件的支持 
 

看起来很专业，对吧？

但如果读者是 AI，问题就来了。

“基于商务沟通的最佳实践”——AI 不关心你怎么来的，它只需要知道现在该怎么做。

“保持专业、礼貌的语气”——"专业"和"礼貌"能展开成无数种组合，每次输出都不一样。

“适应不同场景和收件人”——AI 没有这个直觉，这句话等于没说。

“根据需求撰写合适的邮件内容”——AI 需要的是：什么样的邮件结构？开头怎么写？结尾怎么写？

“版本记录”——AI 每次被唤醒都是全新的，v1.0 还是 v1.1 对它没有意义。

最关键的是，description 只写了"邮件撰写技能"五个字——用户说"帮我回个邮件"要触发吗？"写个请假条"要触发吗？

每一条单独看都没问题，但它们都是写给人看的。

关键区别：读者是谁？

写给人看的文档，需要背景介绍。写给 AI 看的 Skill，不需要——直接说怎么做。

写给人看的文档，用形容词描述原则。写给 AI 看的 Skill，用具体指令规定行为。

写给人看的文档，期望读者有"直觉"。写给 AI 看的 Skill，不能假设任何直觉。

写给人看的文档，需要版本记录。写给 AI 看的 Skill，每次都是全新对话。

写给人看的文档，description 简要概括就行。写给 AI 看的 Skill，description 必须精确描述触发条件。

写 Skill 不是写团队文档，是写操作手册。

每一句话都要能转化为具体行动。

三、核心原则：简洁至上

为什么简洁这么重要？

AI 的上下文窗口就像一张工作台——同一时间能摊开的资料是有限的。

这张工作台上已经放着：系统规则、对话历史、所有已安装技能的元数据。你的 Skill 一旦被激活，它的内容也要摊上去。

工作台就这么大，你占得越多，留给其他东西的空间就越少。

所以第一条原则是：每一句话都要值得它占用的 token。

怎么判断一段内容该不该放进去？问自己两个问题：

1. AI 是不是已经知道这个了？比如"Python 的 for 循环怎么写"，AI 当然知道，不用教。
2. 这段内容值不值得占用工作台上的空间？一段 200 字的解释，能不能用一个 10 行的代码示例替代？

什么不该放进去？

明确列出的禁止清单：

❌ README.md
❌ INSTALLATION_GUIDE.md
❌ QUICK_REFERENCE.md
❌ CHANGELOG.md

原因很简单：Skill 的读者是 AI，不是人类开发者。AI 不需要安装指南、更新日志、快速参考这些"人类辅助文档"。

每一个多余的文件都是噪音。

"不做什么"比"做什么"更精确

当你想约束 AI 的行为时，"不做什么"往往比"做什么"更有效。

举个例子。你要创建一个写作风格技能，不要写：

请用温暖、克制、有洞察力的语气写作。 
 

这种正面描述对 AI 来说全是模糊空间。要写反模式清单：

## 不要这样做 
 
| 症状 | 怎么改 | 
|------|--------| 
| 角色堆砌 | 保留一个冲突场景，补抽象提炼 | 
| 只有鸡汤没有动作 | 改为今天可做的一小步 | 
| 直接大道理 | 先铺生活场景 | 
| 收尾太猛 | 换成"慢慢来""就好" | 
| 过度绝对化 | 加限定词"多数时候""往往" | 
 

每一条都是具体的、可检测的、有明确修正方案的。

背后原理很简单：

"做什么"描述的是一个无限大的可行域，AI 在里面随机游走。

"不做什么"是在可行域上画边界，AI 的行为空间被收窄到你想要的范围。

统一使用祈使语气

Skill 的正文要统一使用祈使语气。

❌ “你应该检查文件的格式”
✅ “检查文件格式”

❌ “AI 可以根据情况决定”
✅ “根据具体情况决定”

这不是美学偏好，而是为了减少歧义——祈使句天然就是指令。

四、核心架构：三级渐进式加载

信息应该放在哪里？

不是所有信息都需要一开始就加载。

Skill 设计了一个三级分层架构：

L1（元数据）  → 始终在上下文中   → ~100 词 
L2（body）    → 触发后才加载     → <5k 词 
L3（资源）    → 按需使用         → 无上限 
 

L1 是过滤器——从几十个已安装技能中筛选出当前需要的那一个。description 不精确，就会误触发或漏触发。

L2 是操作手册——触发后告诉 AI 该怎么做。太长？注意力被稀释。建议控制在 500 行以内。

L3 是工具箱——只在需要时打开。其中 scripts/ 最高效，执行而不读入，零 token 成本。

Frontmatter：触发机制的全部来源

Frontmatter 只有两个必需字段，但 description 的写法至关重要。

错误写法：

description: 代码审查技能 
 

五个字太模糊。用户说"帮我看看这段代码"要触发吗？"这个函数性能怎么样"要触发吗？完全不清楚。

正确写法：

description: >
  审查代码质量，识别潜在问题并提供改进建议。
  当用户说"审查这段代码""检查代码质量""这段代码有什么问题"
  或提交代码请求审查时使用。
 

关键规则：

把所有"when to use"信息放在 description 里，不要放在 body 里。body 是触发后才加载的，那时候 AI 已经决定用了，"什么时候用"的信息已经迟了。

渐进式披露的三种实战模式

模式一：高层指南 + 参考文件

# PDF Processing 
 
## Quick start 
Extract text with pdfplumber: 
[代码示例] 
 
## Advanced features 
- 表单填充：见 references/FORMS.md 
- API 参考：见 references/REFERENCE.md 
- 常见模式：见 references/EXAMPLES.md 
 

AI 只在需要时才加载这些参考文件。

模式二：按领域组织

适用于多领域或多变体技能：

bigquery-skill/ 
├── SKILL.md (概览和导航) 
└── references/ 
    ├── finance.md (收入、计费指标) 
    ├── sales.md (商机、管道) 
    ├── product.md (API 使用、功能) 
    └── marketing.md (营销活动) 
 

用户问销售指标时，AI 只读 sales.md，不会加载其他领域的内容。

模式三：条件性细节

# DOCX Processing 
 
## 创建文档 
使用 docx-js 创建新文档。见 references/DOCX-JS.md。 
 
## 编辑文档 
简单编辑可直接修改 XML。 
 
**追踪修订**：见 references/REDLINING.md 
**OOXML 细节**：见 references/OOXML.md 
 

常见的层错位

触发条件放在 body 里？body 是触发后才加载的，晚了——放 frontmatter description。

参考细节塞进 SKILL.md？body 膨胀，信息密度下降——拆到 references/。

确定性操作写成文字指令？AI 每次重新理解，可能出错——封装成 scripts/。

references 互相引用？AI 需要多跳获取信息——所有 references 从 SKILL.md 直接链接。

SKILL.md 和 references 内容重复？浪费 token，更新时可能不一致——信息只在一处存在。

五、核心决策：给 AI 多大自由度？

任务的不同性质

不是所有任务都适合让 AI 自由发挥。

高自由度任务：

写一篇技术博客——十个人写出十种风格都可以。设计一个用户界面——多种方案都合理。生成创意文案——创意本就没有标准答案。

低自由度任务：

生成 YAML 配置——某个字段要求 25-64 个字符，差一个都不行。命名转换——hyphen-case、Title Case，格式必须精确。文件验证——要么通过要么不通过，没有中间地带。

这类低自由度任务叫**“脆弱操作”。不是说它复杂，而是说它做对只有一种方式，做错有一百种方式**。

自由度光谱

高自由度          中自由度          低自由度 
   │                │                │ 
文字引导       伪代码/带参数脚本    具体脚本 
   │                │                │ 
多种方法都可行   有最佳实践但允许变通   必须遵循特定序列 
决策依赖上下文   配置影响行为        一致性至关重要 
 

核心逻辑：

任务越脆弱（容易出错）→ 自由度越低 → 用脚本锁死

任务越灵活（多种方案都对）→ 自由度越高 → 用文字引导

两个方向的错误

错误一：给脆弱任务太多自由度

# 错误 
请生成一个 openai.yaml 文件，包含 display_name 和 short_description。 
 
# 后果 
short_description 可能超过 64 字符限制，大小写可能不一致
 

正确做法： 用脚本锁死格式。AI 只提供参数值，脚本保证输出合规。

错误二：给创造性任务太多约束

# 错误 
第一段必须以"昨天"开头，第二段必须包含"本质上"，最后一段以"慢慢来"结尾。 
 
# 后果 
生成的文本像填词游戏 
 

正确做法： 给结构比例，但不锁定具体用词。

什么该封装成脚本？

每次执行结果必须一样？`脚本。

涉及精确格式或长度约束？脚本。

涉及命名规范转换？脚本。

需要校验规则匹配？脚本。

同样的代码每次都要重新写？脚本。

需要理解上下文？文字指令。

有多种合理做法？文字指令。

需要创造性判断？文字指令。

脚本的定义是执行。虽然有时仍需要被 AI 读取（用于修补或环境适配），但大多数时候它们是"执行而不读入"的——零 token 成本。

这就是为什么要把命名转换、长度约束、格式校验这些细碎但脆弱的操作全部交给脚本代码。

六、落地流程：六步创建 Skill

有了原则和架构，接下来是可执行的操作步骤。

Step 0：命名规范

开始之前，先确定命名：

只用小写字母、数字和连字符。名称不超过 64 字符。优先用简短的、动词开头的短语。技能文件夹名与技能名完全一致。

示例：

• code-reviewer ✅
• Code Review ❌
• pdf_editor ❌（用连字符不用下划线）

Step 1：理解技能——用具体例子建立共识

要创建有效的 Skill，必须先清楚理解具体的使用例子。

以构建 image-editor 技能为例，可以问：

这个技能应该支持什么功能？编辑、旋转，还有其他吗？能给一些使用这个技能的例子吗？我能想到用户会说"去掉这张照片的红眼"或"旋转这张图片"，还有其他使用方式吗？用户会说什么话来触发这个技能？

完成标志： 对技能应该支持的功能有了清晰的认识。

Step 2：规划可复用的技能内容

对每个具体例子做两个分析：

1. 如果从零开始做这件事，需要什么？
2. 其中哪些会被反复使用？

反复使用的东西，封装成 scripts/references/assets。

案例分析：

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

旋转 PDF 每次都要重写同样的代码。封装为 scripts/rotate_pdf.py。

案例 2：frontend-webapp-builder 技能（用户问"帮我做一个 todo app"）

写前端 webapp 每次都需要同样的 HTML/React 样板代码。封装为 assets/hello-world/ 模板目录。

案例 3：big-query 技能（用户问"今天有多少用户登录了？"）

查询 BigQuery 每次都要重新发现表的 schema 和关系。封装为 references/schema.md。

完成标志： 列出了所有要包含的可复用资源清单。

Step 3：初始化技能目录

创建标准的目录结构：

mkdir -p my-skill/{scripts,references,assets,agents} 
touch my-skill/SKILL.md 
 

或者使用初始化脚本（如果有的话）：

scripts/init_skill.py my-skill --path skills/public 
 

初始化是低自由度操作——用脚本消除出错可能。

Step 4：编辑技能内容

阶段一：先实现可复用资源

从 Step 2 规划的资源开始：实现 scripts/、references/、assets/ 文件。

注意：新增的脚本必须通过实际运行来测试。如果有很多类似的脚本，只需测试代表性样本。只创建真正需要的资源目录。

阶段二：更新 SKILL.md

Frontmatter 写法：

--- 
name: skill-name 
description: >
  描述技能做什么 + 具体什么时候用。
  把所有 "when to use" 信息放这里，不要放在 body 里。
---
 

Body 写法：

写给另一个 AI 实例的操作指令。包含对 AI 有帮助但不显而易见的信息：程序性知识、领域细节、可复用资源的使用方式。

统一使用祈使语气。

Step 5：校验技能

使用校验脚本检查：

scripts/quick_validate.py path/to/skill-folder 
 

校验内容：SKILL.md 是否存在、YAML frontmatter 格式是否合法、name 是否为 hyphen-case 且不超过 64 字符、description 是否存在且不超过 1024 字符、只允许特定 frontmatter 键。

不通过？修复后重新运行。

Step 6：迭代优化

好的 Skill 不是一次写成的。

迭代工作流：

在真实任务上使用技能。发现吃力或低效的地方。找出 SKILL.md 或捆绑资源该如何更新。实施变更并重新测试。

七、常见问题与解答

Q1：Skill 和 Prompt 有什么区别？

Prompt是一次性指令，每次对话都要重新说。

Skill是持久化能力，安装后 AI 就一直有这个技能。

打个比方：

Prompt 像是每次做菜都要告诉厨师"先放油、再放盐"。Skill 像是给厨师一本食谱，他随时可以查阅。

Q2：什么时候该创建 Skill？

当你发现同样的任务重复出现、每次都要重新描述相同的要求、AI 在某个领域的表现不稳定，就可以考虑创建一个 Skill。

Q3：Skill 的 body 应该多长？

建议控制在 500 行以内。

如果更长，说明信息层级没有划分好：把详细的参考资料拆到 references/，把可执行的代码封装到 scripts/，把触发条件描述放在 description。

Q4：脚本一定要写吗？

不一定。简单的 Skill 可以只有 SKILL.md。

脚本的价值在于：确定性——每次执行结果完全一样。效率——执行而不读入，零 token 成本。可靠性——避免 AI 自由发挥时的随机性。

如果你的任务是脆弱操作，就需要脚本。

总结：写好 Skill 的核心心法

回到最初的问题：怎么写出好的 Skill？

一句话总结：用最少的 token，在正确的层级，给 AI 最精准的约束，让它在边界内自由发挥。

展开来说：

读者意识——你是在给 AI 写指令，不是给人写文档。

简洁至上——每一句话都要值得它占用的 token。

层级清晰——L1 过滤、L2 操作、L3 工具箱。

自由度匹配——脆弱任务用脚本锁死，灵活任务用文字引导。

迭代优化——好的 Skill 是用出来的，不是写出来的。

掌握了这些原则，你就能创建出让 AI 真正"听懂"并精准执行的 Skill。

从此，你不再需要每次都重新描述需求——安装一次，AI 就永远有了这项能力。

这就是 AI 时代的"一次编写，永久受益"。

如何学习大模型 AI ？

由于新岗位的生产效率，要优于被取代岗位的生产效率，所以实际上整个社会的生产效率是提升的。

但是具体到个人，只能说是：

“最先掌握AI的人，将会比较晚掌握AI的人有竞争优势”。

这句话，放在计算机、互联网、移动互联网的开局时期，都是一样的道理。

我在一线科技企业深耕十二载，见证过太多因技术卡位而跃迁的案例。那些率先拥抱 AI 的同事，早已在效率与薪资上形成代际优势，我意识到有很多经验和知识值得分享给大家，也可以通过我们的能力和经验解答大家在大模型的学习中的很多困惑。我们整理出这套 AI 大模型突围资料包：

• ✅ 从零到一的 AI 学习路径图
• ✅ 大模型调优实战手册（附医疗/金融等大厂真实案例）
• ✅ 百度/阿里专家闭门录播课
• ✅ 大模型当下最新行业报告
• ✅ 真实大厂面试真题
• ✅ 2026 最新岗位需求图谱

所有资料 ⚡️ ，朋友们如果有需要 《AI大模型入门+进阶学习资源包》，下方扫码获取~

① 全套AI大模型应用开发视频教程

（包含提示工程、RAG、LangChain、Agent、模型微调与部署、DeepSeek等技术点）

② 大模型系统化学习路线

作为学习AI大模型技术的新手，方向至关重要。 正确的学习路线可以为你节省时间，少走弯路；方向不对，努力白费。这里我给大家准备了一份最科学最系统的学习成长路线图和学习规划，带你从零基础入门到精通！

③ 大模型学习书籍&文档

学习AI大模型离不开书籍文档，我精选了一系列大模型技术的书籍和学习文档（电子版），它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。

④ AI大模型最新行业报告

2025最新行业报告，针对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

⑤ 大模型项目实战&配套源码

学以致用，在项目实战中检验和巩固你所学到的知识，同时为你找工作就业和职业发展打下坚实的基础。

⑥ 大模型大厂面试真题

面试不仅是技术的较量，更需要充分的准备。在你已经掌握了大模型技术之后，就需要开始准备面试，我精心整理了一份大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

以上资料如何领取？

为什么大家都在学大模型？

最近科技巨头英特尔宣布裁员2万人，传统岗位不断缩减，但AI相关技术岗疯狂扩招，有3-5年经验，大厂薪资就能给到50K*20薪！

不出1年，“有AI项目经验”将成为投递简历的门槛。

风口之下，与其像“温水煮青蛙”一样坐等被行业淘汰，不如先人一步，掌握AI大模型原理+应用技术+项目实操经验，“顺风”翻盘！

这些资料真的有用吗？

这份资料由我和鲁为民博士(北京清华大学学士和美国加州理工学院博士)共同整理，现任上海殷泊信息科技CEO，其创立的MoPaaS云平台获Forrester全球’强劲表现者’认证，服务航天科工、国家电网等1000+企业，以第一作者在IEEE Transactions发表论文50+篇，获NASA JPL火星探测系统强化学习专利等35项中美专利。本套AI大模型课程由清华大学-加州理工双料博士、吴文俊人工智能奖得主鲁为民教授领衔研发。

资料内容涵盖了从入门到进阶的各类视频教程和实战项目，无论你是小白还是有些技术基础的技术人员，这份资料都绝对能帮助你提升薪资待遇，转行大模型岗位。

以上全套大模型资料如何领取？