Файл SKILL.md

SKILL.md — это основной файл Agent Skills.

В этом разделе подробно рассматривается полная структура SKILL.md и все доступные поля.


Базовая структура

Файл SKILL.md состоит из двух основных частей:

  1. YAML Frontmatter (область метаданных)
  2. Содержимое Markdown (область инструкций)

Полный пример

---
name
: my-skill
description
: Описание навыка, указывающее, когда его использовать
license
: Apache-2.0
compatibility
: Требуется Python3.10+
metadata
:
  author
: your-name
  version
: "1.0"
---

# Название навыка

Здесь приведены подробные инструкции для навыка...

## Шаг 1

Конкретные шаги выполнения...

## Шаг 2

Дополнительные шаги операции...

Пояснение полей метаданных

Ниже перечислены все поля метаданных, поддерживаемые SKILL.md:

Поле Обязательный Ограничения
name Да До 64 символов, допускаются только строчные буквы, цифры и дефисы; не может начинаться или заканчиваться дефисом
description Да До 1024 символов, описывает функцию навыка и сценарии использования
license нет Название лицензии или ссылка на прилагаемый файл лицензии
совместимость нет До 500 символов, указывает требования к окружению (целевой продукт, системные пакеты, доступ к сети и т. д.)
metadata нет Произвольные пары ключ-значение для хранения дополнительных метаданных
allowed-tools нет Список предварительно одобренных инструментов, разделённых пробелами (экспериментальная функция)

Пояснение поля name

Поле name — это идентификатор навыка, и оно должно соответствовать следующим правилам:

  • Длина: 1-64 символа
  • Ограничение символов: можно использовать только строчные буквы Unicode (a-z) и дефисы (-)
  • Начало/конец: нельзя начинать или заканчивать дефисом
  • Последовательные символы: нельзя содержать последовательные дефисы (--)
  • Требование соответствия: должно совпадать с именем родительского каталога

Допустимые примеры:

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

Недопустимые примеры:

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

Поле description: объяснение

Поле description — одно из самых важных полей; оно сообщает агенту, когда следует активировать этот навык.

Хорошее описание должно:

  • Описывать, что делает навык (что он делает)
  • Объяснять сценарии использования (когда его использовать)
  • Включать ключевые слова, помогающие агенту определять соответствующие задачи

Пример хорошего описания:

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

Пример плохого описания:

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

Совет: поле description загружается в начале разговора. Убедитесь, что оно содержит достаточно ключевых слов, чтобы агент мог правильно определить, когда активировать навык.


Поле license: объяснение

Поле license используется для указания лицензии навыка. Это необязательное поле.

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

Поле compatibility: объяснение

Поле compatibility используется для указания требований к окружению навыка. Его нужно добавлять только тогда, когда у навыка есть особые требования к окружению.

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

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

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

Примечание: большинству навыков не нужно поле compatibility. Добавляйте его только тогда, когда у навыка действительно есть особые требования к окружению.


Поле metadata: объяснение

Поле metadata может хранить произвольную информацию в виде пар ключ-значение. Клиенты могут использовать его для хранения дополнительных свойств, не определённых в спецификации.

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

Совет: рекомендуется использовать относительно уникальные имена ключей, чтобы избежать конфликтов с другими навыками.


Поле allowed-tools: объяснение

allowed-tools — экспериментальное поле, используемое для указания предварительно одобренных инструментов, которые может использовать навык.

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

Примечание: это экспериментальная функция; различные реализации агентов могут иметь разный уровень поддержки.


Раздел инструкций: пояснение

Содержимое Markdown после области метаданных — это часть навыка с инструкциями. Здесь нет ограничений на формат; можно писать всё, что нужно.

Рекомендуется включить следующее:

  • Пошаговые инструкции
  • Примеры ввода/вывода
  • Обработка распространённых граничных случаев
# 技能名称

## 功能说明

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

## 操作步骤

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

## 示例

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

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

## 注意事项

- 注意点 1
- 注意点 2

Примечание: после активации навыка весь файл SKILL.md загружается в контекст. Рекомендуется, чтобы основные инструкции укладывались в 500 строк и менее 5000 токенов. Подробные справочные материалы выносите в отдельные файлы.

Другие расширения