Table of contents
Open Table of contents
1.skill简介
skill是一种轻量级开放格式，可复用按需加载，用于扩展AI智能体的能力，使其能够执行特定的任务，类似于说明书，agent可以直接调用。skill分为项目skill和全局skill，全局skill会在每个项目中调用，项目skill，尽在当前项目调用。和prompt区别，prompt是agent需要根据用户输入的指令，自己去执行的任务，而skill是agent已经准备好的任务，用户直接调用即可。非常适合重复且规范的工作。
比如说处理客户投诉，prompt需要每次输入
提取核心问题-判定情绪等级-匹配对应的安抚话术-以 JSON 格式输出 但是封装成skill的话直接调用即可，不需要每次输入。
调用【客户投诉分析技能】，处理内容：【快递延误 3 天，客服联系不上】和memory区别，memory主要是记录使用者的信息，比如偏好、历史记录等。和agents.md区别，agents.md是项目级行为说明文件，通常只绑定特定代码仓库或目录。主要涉及项目规范、架构说明、约定。
2.skill格式
2.1 skill结构
一项技能是一个目录，目录内至少包含一份 SKILL.md 文件：
skill-name/
├── SKILL.md # Required: metadata + instructions
├── scripts/ # Optional: executable code
├── references/ # Optional: documentation
├── assets/ # Optional: templates, resources
└── ... # Any additional files or directoriesSKILL.md 文件必须包含 YAML 前置元数据（在’---‘之间填写，frontmatter），后跟 Markdown 正文内容(body content)，body content 是该技能的具体实现，包括步骤、示例、常见问题等。
frontmatter
| Field | Required | Constraints |
|---|---|---|
| name | Yes | 最大 64 字符。仅允许小写字母、数字、连字符 -；不能以 - 开头、不能以 - 结尾。 |
| description | Yes | 最大 1024 字符，不能为空。描述该技能的功能、适用场景。 |
| license | No | 许可证名称，或者指向配套许可证文件。 |
| compatibility | No | 最大 500 字符。说明运行环境要求：目标产品、依赖系统软件、是否需要网络等。（现大多数skill不需要） |
| metadata | No | 自定义键值对，用来存放额外扩展信息（字符串键 → 字符串值） |
| allowed-tools | No | 使用空格分隔字符串，填写该技能允许调用的工具列表（功能尚处于实验阶段）。 |
最小必填示例：
---
name: skill-name
description: A description of what this skill does and when to use it.
---选填字段示例：
---
name: pdf-processing
description: Extract PDF text, fill forms, merge files. Use when handling PDFs.
license: Apache-2.0
metadata:
author: example-org
version: "1.0"
---2.2 name description详细说明
name field
- 长度：1–64 个字符
- 允许字符：仅支持 Unicode 小写字母数字 a-z, 0-9 和连字符 -
- 首尾限制：不能以 - 开头，不能以 - 结尾
- 连字符限制：不能出现连续连字符 —
- 关联校验：
必须和父目录名称保持一致
关联校验
比如说要做一个skill，创建了一个名叫mj-skill的文件夹，里面skill.md文档的name字段必须也是mj-skill。
description field
- 长度：1 ~ 1024 字符，不能为空
- 内容：需说明技能功能与适用场景，并包含专用关键词，便于智能体匹配对应任务。
- 建议：
内容尽量详细，避免使用模糊的描述。
good example:
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.
bad example:
description: Helps with PDFs.2.3 body content
刚刚讲的name，description这些是frontmatter，接下来讲一下body content.
body content位于前置元数据（frontmatter）之后，用markdown编写技能指令，格式无限制，可以撰写任何能够帮助智能代理高效完成任务的内容。
推荐包含以下板块：
- Step-by-step instructions
- Examples of inputs and outputs
- Common edge cases
如果 SKILL.md 内容篇幅较长，建议拆分至外部引用文件中。
name和description建议一共 100 tokens左右，body content建议不超过5000 tokens，主文件 SKILL.md 建议控制在 500 行以内。详尽的参考资料请拆分至独立文件存放。
3.子目录
技能目录除必需的 SKILL.md 文件外，可存放任意文件与子目录。
scripts/
存放可供agent执行的可运行代码。脚本应当满足以下要求：
- 具备独立运行能力，或清晰写明依赖项
- 输出具备参考价值的错误提示信息
- 妥善处理各类边界场景
支持的编程语言取决于agent的具体实现，常用语言包括 Python、Bash、JavaScript。
references/
存放agent可按需读取的补充文档：
- REFERENCE.md — 详细技术参考文档
- FORMS.md — 表单模板或结构化数据格式说明
- 业务领域专用文档（finance.md、legal.md 等）
单个参考文档内容尽量聚焦单一主题。agent按需加载这类文件，文档体量越小，上下文资源占用越低。
assets/
用于存放静态资源：
- 模板文件（文档模板、配置模板）
- 图片资源（示意图、案例附图）
- 数据文件（查询对照表、数据结构定义）
在技能内引用其他文件时，请使用相对于技能根目录的相对路径。文件引用尽量仅为一级层级（相对于 SKILL.md），避免多层嵌套的链式引用。
总结
一个skill.md文件包含两部分，frontmatter和body content。frontmatter里面包含name，description，license等字段，其中name和description是必填项；body content内容太多时，建议将body content拆分成多个文件，每个文件对应一个功能模块。
参考
https://www.runoob.com/vibe-coding/skills-agent.html
https://agentskills.io/specification