Agent Skills Specification

计算机原理
  目录
  1. 1. Specification
    1. 1.1. Directory structure
    2. 1.2. SKILL.md format
      1. 1.2.1. Frontmatter
        1. 1.2.1.1. name field
        2. 1.2.1.2. description field
        3. 1.2.1.3. license field
        4. 1.2.1.4. compatibility field
        5. 1.2.1.5. metadata field
        6. 1.2.1.6. allowed-tools field
      2. 1.2.2. Body content
    3. 1.3. Optional directories
      1. 1.3.1. scripts/
      2. 1.3.2. references/
      3. 1.3.3. assets/
    4. 1.4. Progressive disclosure
    5. 1.5. File references
    6. 1.6. Validation
  2. 2. 总结
    1. 2.1. 参考
    2. 2.2. Skills library

智能体技能的定义规则

Specification

The complete format specification for Agent Skills.

Directory structure

A skill is a directory containing, at minimum, a SKILL.md file:
(技能是一个目录，至少包含一个文件：SKILL.md)

1
2
3
4
5
6
skill-name/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: documentation
├── assets/           # Optional: templates, resources
└── ...               # Any additional files or directories

SKILL.md format

The SKILL.md file must contain YAML frontmatter followed by Markdown content.
(SKILL.md文件必须包含 YAML 前言，后面是 Markdown 内容。)

Frontmatter

Field Required Constraints
name Yes Max 64 characters. Lowercase letters, numbers, and hyphens only. Must not start or end with a hyphen.
description Yes Max 1024 characters. Non-empty. Describes what the skill does and when to use it.
license No License name or reference to a bundled license file.
compatibility No Max 500 characters. Indicates environment requirements (intended product, system packages, network access, etc.).
metadata No Arbitrary key-value mapping for additional metadata.
allowed-tools No Space-delimited list of pre-approved tools the skill may use. (Experimental)

Minimal example:
(简略的例子)

SKILL.md 
1
2
3
4
---
name: skill-name
description: A description of what this skill does and when to use it.
---


Example with optional fields:
(带有可选字段的示例)

SKILL.md 
1
2
3
4
5
6
7
8
---
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"
---

name field

The required name field:

  • Must be 1-64 characters
  • May only contain unicode lowercase alphanumeric characters (a-z) and hyphens (-)
  • Must not start or end with a hyphen (-)
  • Must not contain consecutive hyphens (--)
  • Must match the parent directory name

Valid examples:
(有效的例子)

1
name: pdf-processing


1
name: data-analysis


1
name: code-review


Invalid examples:
(无效示例)

1
name: PDF-Processing  # uppercase not allowed


1
name: -pdf  # cannot start with hyphen


1
name: pdf--processing  # consecutive hyphens not allowed

description field

The required description field:

  • Must be 1-1024 characters(字符必须是1到1024个字符)
  • Should describe both what the skill does and when to use it(应该能描述技能的作用以及何时使用)
  • Should include specific keywords that help agents identify relevant tasks(应包含具体关键词，帮助智能体识别相关任务)

Good example:
(举个好例子)

1
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.


Poor example:
(举个不好的例子)

1
description: Helps with PDFs.

license field

The optional license field:
(可选字段)

  • Specifies the license applied to the skill(指定适用于该技能的许可)
  • We recommend keeping it short (either the name of a license or the name of a bundled license file)(我们建议简短（无论是许可证名称还是捆绑许可证文件名称）)

Example:

1
license: Proprietary. LICENSE.txt has complete terms

compatibility field

The optional compatibility field:
(可选字段)

  • Must be 1-500 characters if provided(如果提供了，必须为1-500字符)
  • Should only be included if your skill has specific environment requirements(只有在你的技能有特定环境要求时才应该包含)
  • Can indicate intended product, required system packages, network access needs, etc.(可以说明预期产品、所需系统包、网络访问需求等)

Examples:

1
compatibility: Designed for Claude Code (or similar products)


1
compatibility: Requires git, docker, jq, and access to the internet


1
compatibility: Requires Python 3.14+ and uv
Most skills do not need the compatibility field.
(大多数技能不需要compatibility字段)

metadata field

The optional metadata field:

  • A map from string keys to string values(字符串键到字符串值的映射)
  • Clients can use this to store additional properties not defined by the Agent Skills spec(客户端可以利用它存储Agent Skills规范中未定义的额外属性)
  • We recommend making your key names reasonably unique to avoid accidental conflicts(我们建议让你的关键名称保持相对独特，以避免意外冲突)

Example:

1
2
3
metadata:
  author: example-org
  version: "1.0"

allowed-tools field

The optional allowed-tools field:

  • A space-delimited list of tools that are pre-approved to run(一份预先批准运行的工具空间限定列表)
  • Experimental. Support for this field may vary between agent implementations(实验性质。该领域的支持因代理实现而异)

Example:

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

Body content

(主题内容)

The Markdown body after the frontmatter contains the skill instructions. There are no format restrictions. Write whatever helps agents perform the task effectively.(前言后的Markdown主体包含技能指令。没有格式限制。写任何帮助智能体有效完成任务的内容。)

Recommended sections:
(推荐章节)

  • Step-by-step instructions(逐步说明)
  • Examples of inputs and outputs(输入和输出的例子)
  • Common edge cases(常见的边缘情况)

Note that the agent will load this entire file once it’s decided to activate a skill. Consider splitting longer SKILL.md content into referenced files.(注意，一旦决定激活技能，智能体会加载整个文件。考虑将较长的内容拆分为引用文件)

Optional directories

(可选目录)

scripts/

Contains executable code that agents can run. Scripts should:(包含智能体可以运行的可执行代码。脚本应当:)

  • Be self-contained or clearly document dependencies(要是自包含的，或者明确记录依赖关系)
  • Include helpful error messages(包含有用的错误信息)
  • Handle edge cases gracefully(优雅地处理边缘情况)

Supported languages depend on the agent implementation. Common options include Python, Bash, and JavaScript.
(支持的语言取决于智能体实现。常见选项包括 Python、Bash 和 JavaScript。)

references/

Contains additional documentation that agents can read when needed:
(包含智能体在需要时可阅读的额外文件：)

  • REFERENCE.md - Detailed technical reference(REFERENCE.md- 详细技术参考)
  • FORMS.md - Form templates or structured data formats(FORMS.md- 表单模板或结构化数据格式)
  • Domain-specific files (finance.md, legal.md, etc.)(域特定文件)

Keep individual reference files focused. Agents load these on demand, so smaller files mean less use of context.
(保持个人参考文件专注。智能体按需加载这些文件，因此文件越小，上下文的使用越少。)

assets/

Contains static resources:
(包含静态资源：)

  • Templates (document templates, configuration templates)(模板（文档模板、配置模板）)
  • Images (diagrams, examples)(图片（图示、示例）)
  • Data files (lookup tables, schemas)(数据文件（查找表，模式）)

Progressive disclosure

(渐进式展示)

Skills should be structured for efficient use of context:
(技能应结构化以高效利用上下文：)

  1. Metadata (~100 tokens): The name and description fields are loaded at startup for all skills(元数据（~100个词元）：所有技能的和字段在启动时加载name和description)
  2. Instructions (\< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated(说明（建议<5000词元）：技能激活时加载SKILL.md主体)
  3. Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required(资源（视需要）：文件（例如位于scripts/,references/,assets/）仅在需要时加载)

Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
(让你的主SKILL.md保持在500行以内。把详细的参考资料移到单独的文件里。)

File references

(文件引用)

When referencing other files in your skill, use relative paths from the skill root:
(在引用技能中的其他文件时，使用技能根的相对路径：)

SKILL.md 
1
2
3
4
See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Keep file references one level deep from SKILL.md. Avoid deeply nested reference chains.
(文件引用只能从 SKILL.md 往下一级，避免多层嵌套的引用链。)

Validation

(校验检查)

Use the skills-ref reference library to validate your skills:
(使用 skills-ref 参考库 来校验 / 验证你的技能文档：)

1
skills-ref validate ./my-skill

This checks that your SKILL.md frontmatter is valid and follows all naming conventions.
(它会检查你的 SKILL.md 头部元信息（frontmatter）是否合法，以及是否遵守所有命名规范。)

总结

参考

Agent Skills

Skills library

Anthropic Skills
claude-code-skills

  AI