Skill 拆解
区分 Skill 的通用格式、可选资源与平台扩展。
一个 Skill 是一个文件夹。核心文件 SKILL.md 写用途和做法；其他文件按任务需要添加。
Skill 的完整结构
my-skill/
├── SKILL.md # 必需：名称、描述和正文
├── scripts/ # 可选：可执行脚本
├── references/ # 可选：详细参考
├── assets/ # 可选：模板和输出资源
└── agents/
└── openai.yaml # 可选：OpenAI 平台元数据SKILL.md 详解
Frontmatter（元数据）
通用格式要求 name 和 description：
---
name: article-adapter
description: 将已有文章适配成公众号和小红书版本，保留原文事实与口吻。用户提供文章并要求多平台适配时使用。
---| 字段 | 共同规范 |
|---|---|
name | 必需，1–64 字符；小写字母、数字和连字符，与目录名一致；不能以连字符开头或结尾，也不能连续使用连字符。 |
description | 必需，1–1024 字符；同时说明做什么、什么时候用。 |
license | 可选，许可证名称或许可文件引用。 |
compatibility | 可选，说明运行环境和依赖。 |
metadata | 可选，用字符串键值保存附加信息。 |
allowed-tools | 可选、实验性，客户端支持情况不同。 |
完整限制见 Agent Skills 规范。工具开放哪些权限，要遵守它自身的配置；在文件里写一个工具名不等于已经取得访问权限。
描述怎么写
写清实际任务和适用边界，不需要罗列大量同义词。
description: 处理需要统计建模、回归或聚类的 CSV 数据分析任务。仅查看列名或做一次简单汇总时不使用。描述太宽，会在无关任务里被选中；太窄，会漏掉相关任务。用真实提问检查这两种情况，见 创建 Skill。
主体内容
正文写核心流程、输出与失败处理。长资料可以链接到参考文件。
# 文章适配
## 输入
原始文章、目标平台、需要保留的标题和口吻。
## 步骤
1. 检查原文是否完整；缺少材料时指出缺什么。
2. 按目标平台调整标题、段落和排版，不新增事实或经历。
3. 每个平台输出独立文件，说明修改了哪些地方。
## 检查
确认原文观点保留，数字和引用一致，输出文件可打开。
## 失败处理
没有正文时说明缺少输入，不凭标题编写原文。scripts/ 目录
适合确定性步骤：格式转换、计算、文件处理、API 请求或验证。脚本需要列出依赖、输入输出和错误处理。
scripts/
├── convert.py
└── validate.py在正文中说明何时运行、用什么参数以及如何判断结果。路径从 Skill 目录解析，不能假设用户当前工作目录就是脚本所在位置。
脚本本身也可能失败。文件损坏、依赖缺失、网络或账户权限不足时，应给出具体原因，不能把一个退出成功码当作业务结果正确的全部证据。
references/ 目录
放较长的 API 说明、领域知识和特殊情况。主文件保留核心路径，详细资料按需读取。
处理普通输入按上面的步骤执行。
复杂格式参考 [格式说明](references/formats.md)。保持主文件精简、尽量少于 500 行是编写建议，不是格式解析的硬限制。名称和描述用于发现 Skill，正文在被选中后加载，资源再按需要读取；实际加载由客户端实现。
assets/ 目录
放输出时需要的模板、图片、字体或配置，例如公司的报告模板、幻灯片主题、导出样式。正文说明如何使用它们，不要只放资源却没有入口。
agents/openai.yaml
这是 OpenAI 平台的可选扩展，用于展示、默认提示、调用策略和工具依赖。核心任务仍写在 SKILL.md。
interface:
display_name: "Article Adapter"
short_description: "Adapt articles for different platforms"
default_prompt: "Use $article-adapter to adapt this article."
policy:
allow_implicit_invocation: falseallow_implicit_invocation: false 表示不通过语义匹配自动调用，仍可明确使用 $article-adapter。需要 MCP 等工具时，也可用 dependencies.tools 声明；是否连接、认证以及工具能否使用，还要看客户端实际配置。
字段详解：OpenAI Build skills。
Claude Code 扩展
Claude Code 还支持 when_to_use、disable-model-invocation、context: fork 等字段。当前客户端允许省略 name，但共同规范和通用安装器仍要求名称。
Claude 的描述列表还会合并 description 与 when_to_use 并做显示截断；它不是共同规范的字符上限。要让 Skill 便于跨工具安装，核心声明遵守共同规范，平台专用行为另按 Claude Code 文档 配置。