在《认识Agent skill》一文中，我们学习到skill的结构如下；

目录结构

skill必须至少包含一个文件：SKILL.md

my-skill/
├── SKILL.md          # 必填: 元数据(name、description) + 技能描述
├── scripts/          # 可选: 可执行的代码脚本
├── references/       # 可选: 参考文档
├── assets/           # 可选: 模板、资源文件
└── ...               

下面我们来学习和了解skill的格式规范

skill格式

SKILL.md文件必须是YAML格式的前置内容，以及markdown格式的正文描述

前置内容

最小化样例

name: 技能名称
description: 描述这个技能能做什么，什么时候需要用这个技能

带有可选项的样例

name: PDF文件处理
description: 提取PDF文本、填写表单、合并文件。在处理 PDF 时使用
license: Apache-2.0
metadata:
  author: 示例组织
  version: "1.0"

可以看到SKILL.md文件中含有多个字段，有的是必选，有的是可选，那么下面我们就来逐条讲解

name字段

在SKILL.md文件中，name字段扮演着“唯一身份标识符”的核心角色，是Agent识别和调用特定 Skill的唯一凭证。Agent在底层处理时，依靠这个字段来区分不同的技能模块，确保在执行任务时能够精准定位到正确的指令集。
在Agent启动时，它会采用“渐进式披露”机制，仅预加载所有已安装Skill的元数据（即 name和description）。name就像是Skill的“名片”，Agent首先通过它来建立索引，知道“我拥有这个能力”，随后再结合description判断当前任务是否需要激活该Skill。

下面是官方对name字段的格式输入要求：

• 必须是1到64个字符
• 仅包含Unicode小写字母、数字字符a-z,0-9和连字符-
• 不得以连字符开头或结尾 （-)
• 不得包含连续的连字符（--)
• 必须与父目录名称匹配

编写name的实战技巧

为了确保 Agent 能够稳定识别，同时方便开发者后期维护，编写name时建议遵循以下规范：

1. 遵循命名格式规范
   设计应遵循简洁明了的原则，强烈建议使用小写字母和连字符。例如，使用pdf-editor或brand-guidelines，而不是PdfEditor或pdf editor。
2. 保持语义清晰与原子性
   名称应能直观反映该Skill的核心功能，且尽量保持单一职责。例如，处理PDF表单填写的技能可以命名为pdf-form-filler，而不是笼统地命名为pdf-tool。
3. 严格注意大小写与文件匹配
   在实际工程规范中，Agent对大小写非常敏感。确保name字段中的名称与文件夹名称、引用路径保持严格一致。同时，要特别注意核心文件名必须严格写成SKILL.md（大小写完全一致），避免因命名错误导致Agent无法读取或上传失败。