SKILL.md File

SKILL.md is the core file of Agent Skills.

This section will delve into the complete structure of SKILL.md and all available fields.

Basic Structure

A SKILL.md file contains two main parts:

1. YAML Frontmatter (metadata area)
2. Markdown content (instructions area)

Metadata Fields Explained

The following are all metadata fields supported by SKILL.md:

name Field Explained

The name field is the skill's identifier and must follow these rules:

• Length: 1-64 characters
• Character restriction: only Unicode lowercase letters (a-z) and hyphens (-) can be used
• Start/end: cannot start or end with a hyphen
• Consecutive characters: cannot contain consecutive hyphens (--)
• Matching requirement: must match the parent directory name

Valid examples:

name: pdf-processing
name: data-analysis
name: code-review

Invalid examples:

name: PDF-Processing   # 错误：不能使用大写字母
name: -pdf           # 错误：不能以连字符开头
name: pdf--processing  # 错误：不能包含连续连字符

description Field Explained

The description field is one of the most important fields; it tells the agent when it should activate this skill.

A good description should:

• Describe what the skill does (what it does)
• Explain usage scenarios (when to use it)
• Include keywords to help the agent identify relevant tasks

Example of a good description:

description: 从 PDF 文件中提取文本和表格，填写 PDF 表单，合并多个 PDF。处理 PDF 文档或用户提及 PDF、表单或文档提取时使用。

Example of a bad description:

description: 帮助处理 PDF 文件。  # 太笼统，代理无法判断何时使用

Tip: The description field is loaded at the beginning of the conversation. Make sure it contains enough keywords so that the agent can correctly identify when to activate the skill.

license Field Explained

The license field is used to specify the skill's license. This is an optional field.

license: Apache-2.0
# 或者引用 bundled 的许可证文件
license: Proprietary. LICENSE.txt has complete terms

compatibility Field Explained

The compatibility field is used to specify the skill's environment requirements. It only needs to be added when the skill has special environment requirements.

# 指定目标产品
compatibility: Designed for Claude Code

# 指定系统依赖
compatibility: Requires git, docker, jq, and access to the internet

# 指定编程语言版本
compatibility: Requires Python 3.14+ and uv

Note: Most skills do not need the compatibility field. Only add it when the skill truly has specific environment requirements.

metadata Field Explained

The metadata field can store arbitrary key-value pair information. Clients can use it to store additional properties not defined in the specification.

metadata:
  author: example-org
  version: "1.0"
  tags:
    - pdf
    - document
    - extraction

Tip: It is recommended to use relatively unique key names to avoid conflicts with other skills.

allowed-tools Field Explained

allowed-tools is an experimental field used to specify the pre-approved tools that a skill can use.

allowed-tools: Bash(git:*) Bash(jq:*) Read

Note: This is an experimental feature; different agent implementations may have varying levels of support.

Instructions Section Explained

The Markdown content after the metadata area is the instruction part of the skill. There are no format restrictions here; you can write anything as needed.

It is recommended to include the following:

• Step-by-step instructions
• Input/output examples
• Handling common edge cases

# 技能名称

## 功能说明

简要描述这个技能做什么。

## 操作步骤

1. 第一步：执行某个操作
2. 第二步：执行另一个操作
3. 第三步：完成最终操作

## 示例

### 输入示例
描述输入是什么...

### 输出示例
描述输出是什么...

## 注意事项

- 注意点 1
- 注意点 2

Note: Once a skill is activated, the entire SKILL.md file is loaded into the context. It is recommended to keep the main instructions within 500 lines and under 5000 tokens. Move detailed reference material to separate files.