Базовая структура Skills
Основная суть навыков — предоставлять ИИ операционные руководства, определяющие стандартизированные процессы выполнения. После написания эти правила можно многократно вызывать и напрямую переиспользовать, как программные функции.
Навыки хранятся в виде текста Markdown и сами напрямую не выполняют функции.
Навыки поддерживают загрузку по требованию и прогрессивный вызов, эффективно накапливая рабочий опыт и обеспечивая быстрое повторное использование и точную передачу возможностей.
Основная структура навыка
Ядро навыков — это:одна папка + один файл SKILL.md。
Файл SKILL.md содержит:
- Метаданные (как минимум имя и описание)
- Инструкции, сообщающие ИИ, как выполнить конкретную задачу

Навык — это, по сути, файл Markdown (с фиксированным именем файла SKILL.md)
my-skill/ └── SKILL.md (唯一必需)
Базовый шаблон SKILL.md:
--- name: your-skill-name description: 一句话描述该 Skill 的功能和使用场景 --- # Skill 名称 ## 使用指引 [给 AI 的分步骤行为指引] ## 示例 [该 Skill 的具体使用示例]
Весь SKILL.md делится на две части: часть, обёрнутая с помощью------, — это YAML frontmatter (конфигурация заголовка), а часть ниже — это тело Markdown (инструкции по выполнению).
| Поле | Обязательный | Описание | Пример |
|---|---|---|---|
name | Да | Уникальный идентификатор навыка, именуемый в kebab-case. На него ссылаются /-команды, и это ключевое поле для идентификации навыка системой. | web-design-guidelines |
description | Да | Описание функциональности и сценариев срабатывания в одном предложении. Чем конкретнее содержание, тем точнее срабатывание. | UI/UX design review for web pages |
Далее разберём каждую часть:

Frontmatter: два обязательных поля
Frontmatter — это блок конфигурации YAML, обёрнутый с помощью --- в верхней части SKILL.md и служащий идентификационной информацией всего навыка.
Официальная спецификация требует только два поля:
Поле 1: name (имя навыка)
Поле name имеет длину до 64 символов и может содержать только строчные буквы, цифры и дефисы.
name: processing-pdfs # 好:动名词形式,清晰描述功能 name: analyzing-spreadsheets # 好:一眼知道用途 name: my-brand-guidelines # 好:组织专属知识 name: helper # 差:太模糊 name: MySkill # 差:包含大写字母(不合规) name: data files # 差:包含空格(不合规)
Для именования рекомендуется использовать форму герундия (глагол + -ing), например processing-pdfs, analyzing-spreadsheets, чтобы чётко описать действие или возможность, которые предоставляет навык.
| Рекомендуется | Не рекомендуется | Причина |
|---|---|---|
code-reviewer | CodeReviewer | Используйте единообразные строчные буквы и дефисы, чтобы избежать проблем совместимости между платформами |
sql-optimizer | sql_optimizer | kebab-case — это общепринятый формат; сохраняйте его согласованность с именем каталога |
deploy-check | deploy-check-tool-v2 | Имя должно быть коротким; информация о версии указывается во внутреннем описании файла |
Поле 2: description (описание условия срабатывания)
Это самое важное поле. При запуске система предварительно загружает в системный промпт только имя и описание всех Skills.
Только когда ИИ определит, что описание релевантно текущей задаче, он прочитает полное содержимое SKILL.md.
Описание должно содержать две части:Что делает этот Skill и когда Claude должен его использовать.
description: | Use when the user needs to create, read, edit, or generate Word documents (.docx). Triggers include: 'Word doc', 'word document', '.docx', 'report', 'letter', 'memo', or any request to produce a formatted document for sharing or printing.
Тело Markdown: внутренняя структура инструкций по выполнению
| Рекомендуется | Не рекомендуется | Причина |
|---|---|---|
| "Сканируйте код Python на предмет рисков SQL-инъекций и давайте рекомендации по исправлению" | "Инструмент безопасности" | Описание слишком расплывчато, чтобы точно срабатывать |
| "Преобразуйте Markdown в HTML-письма, соответствующие руководству по бренду" | "Преобразование форматов файлов" | Не хватает конкретных сценариев, и он может ошибочно срабатывать в других задачах |
После Frontmatter находится тело Markdown, которое точно указывает ИИ, как выполнять действия.
Он содержит как минимум два раздела:
Примеры SKILL.md
Базовый шаблон SKILL.md:
--- name: pdf-processing description: 从 PDF 中提取文本和表格,填写表单,并合并文档 --- # PDF 处理 ## 使用场景 当需要对 PDF 文件进行操作时使用,例如: - 提取 PDF 文本或表格数据 - 填写 PDF 表单 - 合并多个 PDF 文件 ## 提取文本 - 使用 `pdfplumber` 提取文本型 PDF 内容 - 扫描版 PDF 需配合 OCR 工具 ## 填写表单 - 读取 PDF 表单字段 - 按输入数据填充并生成新文件
Минимальный обязательный пример:
--- name: skill-name description: 说明该 Skill 的功能以及适用场景 ---
Пример с необязательными полями:
--- name: pdf-processing description: 从 PDF 中提取文本和表格,填写表单,并合并文档 license: Apache-2.0 metadata: author: example-org version: "1.0" ---
Описания полей:
| Поле | Обязательный | Описание |
|---|---|---|
| name | Да | Имя навыка, до 64 символов; может содержать только строчные буквы, цифры и дефисы-, и не должно-начинаться или заканчиваться дефисом |
| description | Да | Описание функциональности и сценариев использования, до 1024 символов, не может быть пустым |
| license | нет | Название лицензии или указатель на файл лицензии, прилагаемый к навыку |
| совместимость | нет | Описание окружения и зависимостей (продукты, системные пакеты, сетевые разрешения и т. д.), до 500 символов |
| metadata | нет | Пользовательские пары ключ-значение для расширения метаданных (например, автор, версия) |
| allowed-tools | нет | Список разрешённых инструментов (разделённые пробелами, экспериментальная функция) |
Структура каталогов файлов навыка
Навык — это папка, которая содержит как минимум один файл SKILL.md и может также содержать другие каталоги и файлы по мере необходимости.
Чтобы избежать раздувания контекста:
- Основные правила →
SKILL.md - Подробные материалы → отдельные файлы
- Практическая логика → выполнение скрипта (не загружается)
Рекомендуемая структура:
my-skill/
├── SKILL.md # 必需:元数据 + 指令
├── scripts/ # 可选:可执行代码
└── helper.py
├── references/ # 可选:参考文档
├── assets/ # 可选:模板、资源
└── ... # 其他文件或目录
Назначение каждого каталога следующее:
- SKILL.md: обязательный файл, содержащий метаданные навыка и инструкции по выполнению.
- scripts/: необязательный каталог, содержащий исполняемый код, который агент может запускать.
- references/: необязательный каталог, содержащий подробные справочные материалы.
- assets/: необязательный каталог, содержащий статические ресурсы, такие как шаблоны, изображения и т. д.
Другие расширения