在 AI Agent 生态中，Skill（技能）是决定 AI 能力边界的核心 —— 它就像 AI 的 “能力插件”，插上就能解锁新专长。但多数人初次开发的 Skill 要么 “写给人看”，要么冗余低效，无法被 AI 高效理解和执行。而 Codex 推出的 skill-creator（一个 “创建 Skill 的 Skill”），用 370 行 SKILL.md 定义了 AI 技能开发的黄金标准，其背后的 “简洁约束 + 双设计维度 + 六步流程” 体系，让 Skill 开发从 “凭感觉写” 变成 “按规则造”，新手也能快速打造高质量 AI 技能。
一、先搞懂：Skill 到底是什么？
Skill 本质是 AI 的 “专属工具箱”—— 一个包含指令文档、可执行脚本、参考资料等资源的文件夹，AI 拿到后就能胜任原本不会的特定工作，且不依赖外部资源。
1. 最小形态：一个文件就能跑
一个合格的 Skill 最少只需 1 个文件SKILL.md，结构清晰分为两部分：
-
Frontmatter（元数据）：YAML 格式，包含
name（技能名）和description（触发条件），AI 每次对话都会扫描这部分，判断是否激活技能（唯一触发点）； -
Body（操作指令）：Markdown 正文，仅在技能被激活后加载，告诉 AI 具体怎么做。
示例（最小化 PDF 旋转 Skill）：
markdown
---
name: pdf-rotate
description: 用于旋转PDF文件，支持90/180/270度旋转，当用户要求"旋转PDF"“调整PDF方向”时激活。
---
# PDF旋转操作步骤
1. 接收用户上传的PDF文件路径和旋转角度（仅支持90/180/270）；
2. 调用脚本`scripts/rotate_pdf.py`，执行命令：`python rotate_pdf.py {file_path} {angle}`；
3. 返回旋转后的PDF文件给用户。
2. 完整结构：复杂技能的资源组织
当技能涉及重复代码、参考资料或产出模板时，需扩展为完整目录结构，核心包含 5 类资源，各司其职不冗余：
表格
| 资源类型 | 作用 | 适用场景 | 示例 |
|---|---|---|---|
SKILL.md |
必需入口文件，含触发条件和核心操作流程 | 所有技能 | 定义 PDF 旋转的触发规则和步骤 |
scripts/ |
可执行脚本（Python/Bash 等），AI 直接调用 | 结果需精确、重复执行的操作 | rotate_pdf.py（旋转 PDF 代码） |
references/ |
AI 工作时需查阅的参考资料 | 需要领域知识、API 文档、数据库 schema 的场景 | schema.md（BigQuery 表结构） |
assets/ |
直接用于最终产出的资源 | 需要模板、图片、样板代码的场景 | frontend-template/（前端样板） |
agents/openai.yaml |
技能 “名片”，给产品 UI 展示 | 需在技能市场展示的场景 | 技能名称、图标、简介等 |
关键区别：scripts是给 AI “执行” 的，references是给 AI “阅读” 的，assets是给 AI “使用” 的，三者互不替代。
二、核心误区：你是在给人写指令，还是给 AI？
多数人开发 Skill 的最大问题是 “对象错位”—— 把给人看的文档当成给 AI 的指令，导致 AI 无法理解或执行低效。
反例（错误的代码审查 Skill）：
markdown
---
name: code-review
description: 代码审查技能
---
## 背景
本技能基于团队多年经验总结，旨在提升代码质量。
## 审查原则
- 保持专业、建设性语气
- 平衡严格性和灵活性
## 使用方式
对用户提交的代码全面审查，给出改进建议。
问题分析：
-
“基于团队多年经验”“平衡严格性和灵活性”：人类能理解，但 AI 无法转化为具体操作，属于无效信息；
-
“全面审查”：模糊无边界，AI 不知道先查什么、后查什么，哪些问题必须指出；
-
description仅写 “代码审查技能”：触发条件模糊，用户说 “帮我看看代码”“优化函数性能” 时，AI 无法判断是否激活。
正例（基于 skill-creator 规范改写）：
markdown
---
name: code-review-python
description: 审查Python代码的语法错误、性能问题和规范合规性，支持函数优化、代码简化，当用户要求“审查Python代码”“优化Python函数”“检查代码语法”时激活。
---
# Python代码审查步骤
1. 接收用户提交的Python代码片段或文件路径；
2. 按以下顺序审查（优先级从高到低）：
- 语法错误：检查缩进、括号匹配、变量未定义等基础问题；
- 性能问题：识别循环冗余、重复计算、未使用的变量；
- 规范合规：参考PEP8规范，检查命名风格、注释完整性；
3. 对每个问题给出具体修改建议和示例代码；
4. 生成审查报告，分“必须修复”“建议优化”两类呈现。
三、skill-creator 的黄金框架：1 个约束 + 2 个维度 + 6 步流程
skill-creator 的核心价值，是用一套标准化体系解决 “如何在有限上下文窗口里，给 AI 最有效指令” 的问题，分为三个层次：
1. 根本约束：简洁（每句话都要值对应的 Token）
AI 的上下文窗口是 “公共资源”，要同时容纳系统提示、对话历史、其他技能元数据，因此 Skill 必须遵循 “极简原则”：
-
前提假设：AI 本身足够聪明，只补充它不知道的信息（如 “Python for 循环写法” 无需教）；
-
实操推论：用代码示例替代冗长解释（一个 10 行示例胜过三段文字）；
-
禁止清单：不添加
README.md“INSTALLATION_GUIDE.md` 等人类辅助文档，每一个多余文件都是噪音； -
精确约束：写 “不做什么” 比 “做什么” 更有效（如不说 “用温暖语气”，而说 “不使用绝对化词汇”“不出现连续对白”）；
-
语气要求：统一使用祈使句（如 “调用脚本”“检查语法”），减少歧义。
2. 两个设计维度：让 Skill 高效又可靠
在 “简洁” 约束下，开发 Skill 需解决两个核心决策：信息放哪里？给 AI 多大自由度？
维度一：信息分层 —— 三级加载，省 Token 不浪费
skill-creator 设计了三级加载架构，不同信息在不同时机进入上下文，最大化利用窗口空间：
表格
| 层级 | 内容 | 加载时机 | Token 成本 | 核心作用 |
|---|---|---|---|---|
| L1 | Frontmatter（元数据） | 始终在上下文 | ~100 词 | 技能过滤器，判断是否激活 |
| L2 | SKILL.md Body | 技能触发后 | <5k 词（500 行内） | 操作手册，指导 AI 执行步骤 |
| L3 | scripts/references/assets | 按需加载 | 无上限（脚本零成本） | 工具箱，提供辅助资源 |
避坑指南：常见层错位及修正
-
把触发条件写在 Body 里→移到
description（Body 触发后才加载，为时已晚）； -
参考细节塞进 SKILL.md→拆到
references/，Body 仅留引用链接； -
确定性操作（如格式转换）写成文字指令→封装成
scripts/，执行不读入上下文。
维度二：自由度分配 —— 按任务脆弱性定边界
AI 擅长创造性工作，但不擅长精确格式控制、命名规范等 “脆弱操作”（做错只有一种方式，做对有一百种）。skill-creator 将自由度分为三档，精准匹配任务类型：
-
高自由度（文字指令）：多种方案都可行，依赖上下文判断，如技术博客写作、创意方案生成，用启发式引导（如 “场景层≤30%，原理层 30-40%”）；
-
中自由度（模板 / 伪代码）：有最佳实践但允许变通，如技能结构规划、数据可视化样式选择，用模板 + 参数配置约束；
-
低自由度（脚本锁死）：操作脆弱易出错，一致性至关重要，如生成 YAML 配置、命名规范转换，用脚本封装（零 Token 成本 + 100% 确定性）。
判断标准：
-
做错后果越严重→自由度越低；
-
正确做法越多→自由度越高。
3. 六步落地流程：从想法到 Skill 的标准化路径
skill-creator 将设计思想转化为可执行的六步流程，脚本贯穿全程，确保起点正确、终点合规：
Step 1：理解技能 —— 用具体例子建立共识
先明确技能的核心场景和触发场景，避免模糊化。可通过提问收集信息：
-
“这个技能要解决什么问题？用户会说什么话触发？”
-
“能给 3 个具体使用例子吗？”
完成标志：清晰界定技能的功能边界和触发条件。
Step 2：规划资源 —— 提取可复用内容
分析每个使用例子，拆分 “重复使用的部分”，封装为对应资源：
-
重复代码→
scripts/（如 PDF 旋转的 Python 脚本）； -
参考资料→
references/（如数据库表结构、API 文档）； -
产出模板→
assets/（如前端样板代码、PPT 模板）。
Step 3：初始化技能 —— 用脚本生成骨架
必须使用init_skill.py脚本初始化（而非手写目录），避免格式错误：
bash
运行
# 示例：创建PDF处理技能，包含scripts和references资源
scripts/init_skill.py pdf-processor --path skills/public --resources scripts,references
脚本会自动生成标准化目录、带 TODO 的SKILL.md模板，还会调用generate_openai_yaml.py生成技能 “名片”，确保符合规范。
Step 4：编辑技能 —— 先资源后指令
-
阶段一：实现
scripts/“references/“assets/资源，脚本需实际运行测试，确保无 Bug； -
阶段二：更新
SKILL.md，Frontmatter 写清 “做什么 + 什么时候用”，Body 用祈使句写操作步骤，不冗余、不模糊。
Step 5：校验技能 —— 用脚本做 “质检”
运行quick_validate.py脚本校验，不通过则修复：
bash
运行
scripts/quick_validate.py skills/public/pdf-processor
校验核心内容：
-
name是否为 hyphen-case（如pdf-processor），≤64 字符； -
description是否存在，≤1024 字符，无尖括号； -
Frontmatter 仅包含
name“description”“license” 等 5 个允许字段。
Step 6：迭代优化 —— 在实战中打磨
将 Skill 投入真实任务，观察 AI 执行效果，优化方向包括：
-
触发不精准→细化
description的触发条件； -
执行出错→完善 Body 的步骤或修复脚本；
-
冗余低效→拆分或合并资源，精简 Body 指令。
四、进阶技巧：让 Skill 更高效、更灵活
1. 参考资料的三种披露模式
复杂技能的参考资料需按需加载，避免占用过多 Token，skill-creator 推荐三种模式：
-
高层指南 + 参考文件：核心流程写在 Body，高级功能链接到参考文件（如 PDF 填充功能链接
FORMS.md）； -
按领域组织：多领域技能按领域拆分参考资料（如 BigQuery 技能分
finance.md“sales.md”），避免加载无关内容； -
条件性细节：基础功能直接写在 Body，高级细节链接参考文件（如 DOCX 编辑技能，复杂格式处理链接
OOXML.md）。
2. 三个核心脚本：低自由度任务的最佳实践
skill-creator 内置三个脚本，覆盖 “输入 - 格式 - 输出” 全流程的脆弱操作，是高质量 Skill 的必备工具：
-
init_skill.py（398 行）：输入保障，标准化命名（自动转为 hyphen-case）、创建目录结构、生成模板； -
generate_openai_yaml.py（226 行）：格式保障，自动生成技能 “名片”，确保short_description25-64 字符、首字母大写； -
quick_validate.py（102 行）：输出保障，校验 Frontmatter 格式、命名规范等，避免低级错误。
3. 命名规范：让 AI 一眼看懂
-
格式：仅用小写字母、数字和连字符，标准化为 hyphen-case（如 “Plan Mode”→
plan-mode）； -
长度：≤64 字符；
-
风格：动词开头，清晰描述动作（如
pdf-rotate“code-review-python”）； -
命名空间：工具相关技能加前缀（如
gh-address-comments“linear-address-issue”）。
五、总结：Skill 开发的核心心法
skill-creator 的本质，是用 “最少的 Token，在正确的层级，给 AI 最精准的约束”—— 它不限制 AI 的创造性，而是通过 “简洁约束” 减少冗余，通过 “分层加载” 优化 Token 使用，通过 “自由度分配” 平衡灵活与可靠，通过 “六步流程” 保证标准化。
记住三个核心原则：
-
始终明确：Skill 是写给 AI 看的，不是给人看的，每句话都要让 AI 能直接执行；
-
冗余即原罪：多余的文件、模糊的描述、重复的信息，都会降低 AI 执行效率；
-
脚本优先：脆弱操作（格式控制、重复代码）优先用脚本封装，零 Token 成本且 100% 可靠。
按照这套体系开发，无论是简单的 PDF 处理技能，还是复杂的前端项目生成技能，都能让 AI 高效理解、精准执行，真正发挥 Skill 的 “能力插件” 价值。