Базовая структура 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-reviewerCodeReviewerИспользуйте единообразные строчные буквы и дефисы, чтобы избежать проблем совместимости между платформами
sql-optimizersql_optimizerkebab-case — это общепринятый формат; сохраняйте его согласованность с именем каталога
deploy-checkdeploy-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/: необязательный каталог, содержащий статические ресурсы, такие как шаблоны, изображения и т. д.
Другие расширения