如何写一个 skill
Skill 是什么#
skill 可以理解成一组可复用的能力说明。
它通常包含一份主文档 SKILL.md，再按需要带上脚本、参考资料和素材文件。
它适合解决这几类问题：
- 某类任务有固定流程
- 某些操作容易出错，最好约束做法
- 有一批上下文知识，每次重复解释太浪费
- 需要配套脚本、模板或资源文件
不适合做这几类东西：
- 一次性方案
- 项目私有约定
- 纯靠代码校验就能解决的问题
- 大而空的“方法论文档”
一个 skill 的最小结构#
my-skill/
├── SKILL.md
├── agents/
│ └── openai.yaml
├── scripts/
├── references/
└── assets/说明：
SKILL.md是必须的agents/openai.yaml建议加，方便在界面里展示scripts/放脚本references/放长文档、规范、接口说明assets/放模板、图标、字体、样例文件
不是每个 skill 都要把这些目录建全。
没有就不要建。
写之前先把边界定清楚#
先回答四个问题：
- 这个 skill 到底解决什么问题
- 什么情况下应该触发它
- 什么情况下不该触发它
- 它需要哪些配套资源
如果这四个问题说不清，先别写正文。
SKILL.md 怎么写#
1. Frontmatter 只放必要信息#
最少保留两个字段：
---
name: editor-studio-ui
description: Use when designing or refining editor-style content studio interfaces, including workspace layout, panels, toolbars, editing flows, and implementation details.
---要求很简单：
name用小写加连字符description重点写“什么时候用”- 不要把完整流程塞进
description - 让它覆盖真实会出现的任务词、场景词、文件词
description 决定这个 skill 会不会被选中。
这部分比正文更重要。
2. 正文别写成废话#
正文建议写成下面这种结构：
# Editor Studio UI
## Overview
用于设计和实现编辑器工作台类界面，重点处理布局、信息层级、主操作区和侧边面板。
## Workflow
1. 先看现有产品结构，不要直接推翻。
2. 先定主区域、侧栏、工具条，再谈视觉。
3. 优先保证操作路径清楚，再补细节交互。
4. 对桌面端和移动端分别给出布局策略。
## Rules
- 不要做成通用后台面板样式
- 不要把主操作和次要信息混在一个层级
- 不要为了“高级感”牺牲可读性
- 需要保留现有设计体系时，优先沿用已有模式
## Resources
- 需要布局参考时，读取 `references/layout-patterns.md`
- 需要脚手架或检查脚本时，使用 `scripts/`写正文时注意几件事：
- 写动作，不写空话
- 写判断标准，不写口号
- 写例外情况，不写泛泛原则
- 需要长说明就拆到
references/ - 需要重复执行的逻辑就放到
scripts/
一个能直接参考的 SKILL.md 示例#
---
name: editor-studio-ui
description: Use when designing or refining editor-style content studio interfaces, including workspace layout, panels, toolbars, editing flows, and production-ready frontend implementation details.
---
# Editor Studio UI
## Overview
用于编辑器工作台类页面的设计与实现，覆盖布局组织、操作区划分、面板关系和交互优先级。
## Workflow
1. 先识别主任务区域。
2. 再区分主操作、辅助信息和状态反馈。
3. 先确定布局和层级，再处理视觉样式。
4. 兼顾桌面端与移动端的使用路径。
## Layout Rules
- 主编辑区必须保持视觉中心
- 侧边栏只承载辅助信息，不抢主操作
- 顶部工具栏保留高频动作
- 二级操作尽量下沉，避免界面噪音
## Implementation Notes
- 优先复用现有设计系统
- 没有明确要求时，不引入复杂状态管理
- 样式命名和组件拆分保持可维护性
- 交互动效只服务于信息层级和操作反馈
## Resources
- 需要布局范式时读取 `references/layout-patterns.md`
- 需要模板或资源时查看 `assets/`
- 需要可执行辅助逻辑时使用 `scripts/`初始化一个 skill#
如果当前环境带有初始化脚本，可以直接生成骨架：
python init_skill.py editor-studio-ui --path "$CODEX_HOME/skills" --resources scripts,references,assets如果没有这类脚本，也可以手动创建目录和文件。
关键不是脚本，而是目录结构和内容质量。
openai.yaml 要不要写#
如果你希望它在界面里显示得更完整，建议写。
示例：
interface:
display_name: "Editor Studio UI"
short_description: "Editor workspace design and implementation"
default_prompt: "Use $editor-studio-ui to design a production-ready editor workspace."注意：
- 字段内容给人看，不要写成内部说明
default_prompt最好短一点default_prompt里明确写出$skill-name
资源文件怎么分#
scripts/#
适合放这些东西：
- 初始化脚本
- 转换脚本
- 校验脚本
- 可重复执行的小工具
references/#
适合放这些东西：
- 接口说明
- 数据结构
- 设计规范
- 业务规则
- 长篇流程文档
assets/#
适合放这些东西：
- 模板
- 图标
- 字体
- 示例文件
- 可直接复用的素材
原则只有一个：
能执行的放脚本，太长的放参考，最终产物要用的放素材。
怎么判断这个 skill 写得行不行#
看三点：
- 别人第一次打开，能看懂它什么时候该用
- 真碰到任务时，它能提供具体帮助
- 不需要加载一堆无关内容
如果一个 skill 写完之后，正文大半都是“提高效率”“保持一致性”“确保质量”这种话，基本就该重写。