Skills 结构规范

Skills 核心结构

每个 Skill 都是一个自包含的文件夹。最小结构只需要一个 SKILL.md 文件，复杂的 skill 可以包含脚本、参考文档、模板、和子 agent 定义。

Each Skill is a self-contained folder. The minimal structure requires only a SKILL.md file; complex skills can include scripts, reference docs, templates, and sub-agent definitions.

目录结构标准

以下是官方的推荐目录结构。只有 SKILL.md 是必需的，其他都是可选的。

Below is the recommended directory structure. Only SKILL.md is required; everything else is optional.

my-skill
- SKILL.md 必需 · 主入口 · YAML frontmatter + Markdown 指令
- LICENSE.txt 可选 · 许可证文件
- scripts 可选 · 脚本目录
  - main.py Python 脚本示例
  - requirements.txt Python 依赖声明
- references 可选 · 参考文档
  - api-docs.md API 参考文档
- templates 可选 · 模板文件
  - template.html HTML 模板
- agents 可选 · 子 Agent 定义
  - reviewer.md 评审 agent 指令
- examples 可选 · 示例文件
  - example-input.json 输入示例

SKILL.md 规范

每个 SKILL.md 文件包含两部分：YAML frontmatter（元数据）和 Markdown body（指令内容）。

Each SKILL.md file has two parts: YAML frontmatter (metadata) and Markdown body (instruction content).

YAML Frontmatter 字段详解

字段	必需	说明
`name`	是	唯一标识符，小写 + 连字符，如 `my-skill`
`description`	是	完整描述 skill 做什么以及何时触发。这是主要的触发机制——要包含"何时使用"的信息
`license`	否	许可证信息
`compatibility`	否	所需工具或依赖声明（很少需要）

Field	Required	Description
`name`	Yes	Unique identifier, lowercase with hyphens, e.g. `my-skill`
`description`	Yes	Complete description of what the skill does and when to trigger. Include "when to use" context.
`license`	No	License information
`compatibility`	No	Required tools/dependencies (rarely needed)

description 字段编写技巧

description 是最关键的字段——它决定了 Claude 何时触发这个 skill。一个好的 description 应该：

描述 skill 做什么（功能）
明确何时触发（场景/关键词）
稍微”主动”一些——宁可多触发也不要被漏掉

示例对比：

❌ 太弱：“帮助你创建 dashboard。”

✅ 推荐：“创建用于展示内部数据的快速 dashboard。当用户提到 dashboard、数据可视化、内部指标、或想要展示任何公司数据时使用此 skill，即使用户没有明确说’dashboard’这个词。”

description is the most critical field — it determines when Claude triggers this skill. A good description should:

Describe what the skill does (function)
Specify when to trigger (scenarios/keywords)
Be slightly “pushy” — better to over-trigger than be missed

Comparison:

❌ Too weak: “Helps you create dashboards.”

✅ Recommended: “Create quick dashboards for displaying internal data. Use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any company data, even if they don’t explicitly say ‘dashboard.’”

三种 Skill 设计模式

模式	特征	典型 Skill
纯指令型	只有 SKILL.md，纯粹靠 Markdown 指令驱动	doc-coauthoring, brand-guidelines
脚本驱动型	SKILL.md + scripts/，核心逻辑在脚本中	pdf, skill-creator, mcp-builder
模板型	SKILL.md + templates/ + assets/，包含大量模板资源	theme-factory, canvas-design

Pattern	Characteristics	Example Skills
Instruction-Only	Only SKILL.md, purely driven by Markdown instructions	doc-coauthoring, brand-guidelines
Script-Driven	SKILL.md + scripts/, core logic in scripts	pdf, skill-creator, mcp-builder
Template-Based	SKILL.md + templates/ + assets/, rich template resources	theme-factory, canvas-design