适用人群：

一定代码基础和相关理论基础

阅读目的：

快速、有效地理解如何将已有的代码工具封装成skill。在实操过程中，遇到的细节问题还是需要通过更加详实的文档进行理解。

内容：

1、definition - 记住核心概念就行，防止实操时“偏题”

A skill is a set of instructions - packaged as a simple folder - that teaches AI how to handle specific tasks or workflows.

2、structure - 必须记住

逐个说明：

• skill-name — Use kebab-case

•  SKILL.md — 唯一必需的文件，且文件名固定。

description structure：

[What it does] + [When to use it] + [Key capabilities]

• scripts/ — 写好的程序，AI 不需要读懂它，直接调用 shell 执行就行。比如 scripts/rotate_pdf.py，AI 只要跑 python rotate_pdf.py input.pdf 90 就能旋转 PDF，不用每次重新写旋转逻辑。适合那些结果必须精确、不能让 AI 自由发挥的操作

• references/ — AI 在工作过程中需要查阅的参考资料。比如一个"BigQuery 查询"技能，AI 要知道公司有哪些表、每个表有什么字段，这些信息放在 references/schema.md 里，AI 需要时再读取。和 scripts 的区别是：references 是给 AI 读的，scripts 是给 AI 执行的

        需要注意的是，这里的“参考资料”不是像人类阅读的辅助文档，而是实际且具体的补充信息。

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

• agents/openai.yaml — 技能的"名片"。很多 AI 产品会在界面上展示一个技能列表，让用户选择或搜索。这个文件里存的就是列表中显示的名称、简介、图标等信息。它不影响 AI 的行为，纯粹是给产品界面用的

3、notes - 必须记住，且保持更新

• 核心约束：简洁。跟prompt相比，skill需要你有更强的概括和描述能力。

具体的字数限制：

L1（元数据）：始终在上下文中，约 100 词——AI 靠它判断要不要激活这个技能

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

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

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.

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

•  什么不该放进 Skill？

不该有的文件：

• README.md

• INSTALLATION_GUIDE.md

• QUICK_REFERENCE.md

• CHANGELOG.md

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

• 写约束时，"不做什么"比"做什么"更精确

记住，本条仅限写约束条件（constrains）时，应该明确告诉AI"不应该做什么"（What not to do）。而写技能指令(instructions)时，应该明确告诉AI"应该做什么"（What to do）

• 统一使用祈使语气
•  自由度的把控

4、example - 用于理解以上内容

关于description的bad case与good case对比：

good cases:

bad cases:

参考资料：

https://claude.com/skills

https://code.claude.com/docs/zh-CN/skills

如何写出好的 Skill？拆解 skill-creator 背后的设计

https://resources.anthropic.com/hubfs/The-Complete-Guide-to-Building-Skill-for-Claude.pdf