Файл SKILL.md
SKILL.md — это основной файл Agent Skills.
В этом разделе подробно рассматривается полная структура SKILL.md и все доступные поля.
Базовая структура
Файл SKILL.md состоит из двух основных частей:
- YAML Frontmatter (область метаданных)
- Содержимое 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 токенов. Подробные справочные материалы выносите в отдельные файлы.