Agent Skills¶

Agent Skills — это папки с инструкциями, скриптами и ресурсами, которые агенты могут обнаруживать и использовать для более точной и эффективной работы.

Зачем нужны Agent Skills?¶

Агенты становятся всё более способными, но часто им не хватает контекста для надёжного выполнения реальных задач. Skills решают эту проблему, предоставляя агентам доступ к процедурным знаниям и контексту, специфичному для компании, команды и пользователя, который они могут загружать по запросу. Агенты с доступом к набору навыков могут расширять свои возможности в зависимости от выполняемой задачи.

Для авторов навыков: создавайте возможности один раз и развёртывайте их в нескольких агентских продуктах.

Для совместимых агентов: поддержка навыков позволяет конечным пользователям предоставлять агентам новые возможности прямо из коробки.

Для команд и предприятий: фиксируйте организационные знания в портативных пакетах с контролем версий.

Что могут обеспечить Agent Skills?¶

Экспертиза в предметной области: упаковывайте специализированные знания в переиспользуемые инструкции — от процессов юридической проверки до конвейеров анализа данных.
Новые возможности: предоставляйте агентам новые способности (например, создание презентаций, построение MCP-серверов, анализ наборов данных).
Повторяемые рабочие процессы: превращайте многоэтапные задачи в согласованные и проверяемые процессы.
Интероперабельность: используйте один и тот же навык в разных продуктах, совместимых со стандартом Skills.

Внедрение¶

Agent Skills поддерживаются ведущими инструментами разработки на основе ИИ.

Открытая разработка¶

Формат Agent Skills был первоначально разработан компанией Anthropic, выпущен как открытый стандарт и принят растущим числом агентских продуктов. Стандарт открыт для вклада со стороны широкого сообщества.

Смотреть на GitHub

Что такое навыки?¶

По своей сути навык — это папка, содержащая файл SKILL.md. Этот файл включает метаданные (как минимум name и description) и инструкции, которые сообщают агенту, как выполнять конкретную задачу. Навыки также могут содержать скрипты, шаблоны и справочные материалы.

my-skill/
├── SKILL.md          # Обязательно: инструкции + метаданные
├── scripts/          # Необязательно: исполняемый код
├── references/       # Необязательно: документация
└── assets/           # Необязательно: шаблоны, ресурсы

Как работают навыки¶

Навыки используют прогрессивное раскрытие для эффективного управления контекстом:

Обнаружение: при запуске агенты загружают только имя и описание каждого доступного навыка — ровно столько, чтобы понять, когда он может быть полезен.
Активация: когда задача соответствует описанию навыка, агент считывает полные инструкции из SKILL.md в контекст.
Выполнение: агент следует инструкциям, при необходимости загружая указанные файлы или выполняя встроенный код.

Такой подход сохраняет быстродействие агентов, предоставляя им доступ к дополнительному контексту по запросу.

Файл SKILL.md¶

Каждый навык начинается с файла SKILL.md, содержащего YAML-метаданные (frontmatter) и инструкции в формате Markdown:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
---

# PDF Processing

### When to use this skill

Use this skill when the user needs to work with PDF files...

### How to extract text

1. Use pdfplumber for text extraction...

### How to fill forms

...

В начале файла SKILL.md обязательно должны присутствовать следующие метаданные:

name: короткий идентификатор
description: когда использовать этот навык

Тело в формате Markdown содержит собственно инструкции и не имеет ограничений по структуре или содержанию.

Этот простой формат имеет ряд ключевых преимуществ:

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

Следующие шаги¶

Ознакомьтесь со спецификацией, чтобы понять полный формат.
Добавьте поддержку навыков в вашего агента, чтобы создать совместимый клиент.
Посмотрите примеры навыков на GitHub.
Прочитайте лучшие практики создания навыков для написания эффективных навыков.
Используйте справочную библиотеку для валидации навыков и генерации XML-промптов.

Спецификация¶

Этот документ определяет формат Agent Skills.

Структура каталога¶

Навык — это каталог, содержащий как минимум файл SKILL.md:

1 2	`skill-name/ └── SKILL.md # Обязательно`

Вы можете дополнительно включить необязательные каталоги, такие как scripts/, references/ и assets/, для поддержки вашего навыка.

Формат SKILL.md¶

Файл SKILL.md должен содержать YAML-метаданные (frontmatter), за которыми следует содержимое в формате Markdown.

Метаданные (обязательные)¶

---
name: skill-name
description: A description of what this skill does and when to use it.
---

С необязательными полями:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents.
license: Apache-2.0
metadata:
    author: example-org
    version: '1.0'
---

Поле	Обязательно	Ограничения
`name`	Да	Макс. 64 символа. Только строчные буквы, цифры и дефисы. Не должно начинаться или заканчиваться дефисом.
`description`	Да	Макс. 1024 символа. Непустое. Описывает, что делает навык и когда его использовать.
`license`	Нет	Название лицензии или ссылка на прилагаемый файл лицензии.
`compatibility`	Нет	Макс. 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:

Должно содержать от 1 до 1024 символов
Должно описывать как то, что делает навык, так и когда его использовать
Должно включать конкретные ключевые слова, помогающие агентам определить релевантные задачи

Хороший пример:

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.

Плохой пример:

description: Helps with PDFs.

Поле `license`¶

Необязательное поле license:

Указывает лицензию, применяемую к навыку
Рекомендуется делать его кратким (либо название лицензии, либо имя прилагаемого файла лицензии)

Пример:

license: Proprietary. LICENSE.txt has complete terms

Поле `compatibility`¶

Необязательное поле compatibility:

Должно содержать от 1 до 500 символов, если указано
Следует включать только в том случае, если ваш навык имеет специфические требования к среде
Может указывать целевой продукт, необходимые системные пакеты, потребность в доступе к сети и т. д.

Примеры:

compatibility: Designed for Claude Code (or similar products)

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

Большинству навыков поле compatibility не требуется.

Поле `metadata`¶

Необязательное поле metadata:

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

Пример:

metadata:
    author: example-org
    version: '1.0'

Поле `allowed-tools`¶

Необязательное поле allowed-tools:

Список инструментов, предварительно одобренных для запуска, разделённый пробелами
Экспериментальное. Поддержка этого поля может различаться в разных реализациях агентов

Пример:

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

Содержимое тела¶

Тело в формате Markdown после метаданных содержит инструкции навыка. Ограничений по формату нет. Пишите всё, что помогает агентам эффективно выполнять задачу.

Рекомендуемые разделы:

Пошаговые инструкции
Примеры входных и выходных данных
Типичные крайние случаи

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

Необязательные каталоги¶

`scripts/`¶

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

Быть самодостаточными или чётко документировать зависимости
Включать полезные сообщения об ошибках
Корректно обрабатывать крайние случаи

Поддерживаемые языки зависят от реализации агента. Распространённые варианты включают Python, Bash и JavaScript.

`references/`¶

Содержит дополнительную документацию, которую агенты могут читать при необходимости:

REFERENCE.md — подробный технический справочник
FORMS.md — шаблоны форм или форматы структурированных данных
Предметно-ориентированные файлы (finance.md, legal.md и т. д.)

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

`assets/`¶

Содержит статические ресурсы:

Шаблоны (шаблоны документов, шаблоны конфигурации)
Изображения (диаграммы, примеры)
Файлы данных (таблицы подстановки, схемы)

Прогрессивное раскрытие¶

Навыки должны быть структурированы для эффективного использования контекста:

Метаданные (~100 токенов): поля name и description загружаются при запуске для всех навыков
Инструкции (рекомендуется < 5000 токенов): полное тело SKILL.md загружается при активации навыка
Ресурсы (по мере необходимости): файлы (например, из scripts/, references/ или assets/) загружаются только при необходимости

Держите основной файл SKILL.md в пределах 500 строк. Переносите подробные справочные материалы в отдельные файлы.

Ссылки на файлы¶

При ссылке на другие файлы в вашем навыке используйте относительные пути от корня навыка:

See [the reference guide](references/REFERENCE.md) for details.

Run the extraction script:
scripts/extract.py

Держите ссылки на файлы на одном уровне вложенности от SKILL.md. Избегайте глубоко вложенных цепочек ссылок.

Валидация¶

Используйте справочную библиотеку skills-ref для валидации ваших навыков:

1	`skills-ref validate ./my-skill`

Это проверяет, что метаданные вашего SKILL.md валидны и соответствуют всем соглашениям об именовании.

Интеграция навыков в вашего агента¶

Это руководство объясняет, как добавить поддержку навыков в ИИ-агента или инструмент разработки.

Подходы к интеграции¶

Два основных подхода к интеграции навыков:

Агенты на основе файловой системы работают в компьютерной среде (bash/unix) и представляют собой наиболее функциональный вариант. Навыки активируются, когда модели выполняют команды оболочки, такие как cat /path/to/my-skill/SKILL.md. Встроенные ресурсы доступны через команды оболочки.

Агенты на основе инструментов функционируют без выделенной компьютерной среды. Вместо этого они реализуют инструменты, позволяющие моделям запускать навыки и получать доступ к встроенным ресурсам. Конкретная реализация инструментов остаётся на усмотрение разработчика.

Совместимый с навыками агент должен:

Обнаруживать навыки в настроенных каталогах
Загружать метаданные (имя и описание) при запуске
Сопоставлять задачи пользователя с релевантными навыками
Активировать навыки, загружая полные инструкции
Выполнять скрипты и получать доступ к ресурсам по мере необходимости

Обнаружение навыков¶

Навыки — это папки, содержащие файл SKILL.md. Ваш агент должен сканировать настроенные каталоги в поисках допустимых навыков.

Загрузка метаданных¶

При запуске разбирайте только метаданные (frontmatter) каждого файла SKILL.md. Это сохраняет низкое начальное использование контекста.

Разбор метаданных¶

function parseMetadata(skillPath):
    content = readFile(skillPath + "/SKILL.md")
    frontmatter = extractYAMLFrontmatter(content)

    return {
        name: frontmatter.name,
        description: frontmatter.description,
        path: skillPath
    }

Внедрение в контекст¶

Включите метаданные навыков в системный промпт, чтобы модель знала, какие навыки доступны.

Следуйте рекомендациям вашей платформы по обновлению системных промптов. Например, для моделей Claude рекомендуемый формат использует XML:

<available_skills>
  <skill>
    <name>pdf-processing</name>
    <description>Extracts text and tables from PDF files, fills forms, merges documents.</description>
    <location>/path/to/skills/pdf-processing/SKILL.md</location>
  </skill>
  <skill>
    <name>data-analysis</name>
    <description>Analyzes datasets, generates charts, and creates summary reports.</description>
    <location>/path/to/skills/data-analysis/SKILL.md</location>
  </skill>
</available_skills>

Для агентов на основе файловой системы включите поле location с абсолютным путём к файлу SKILL.md. Для агентов на основе инструментов поле location можно опустить.

Сохраняйте метаданные лаконичными. Каждый навык должен добавлять примерно 50–100 токенов к контексту.

Вопросы безопасности¶

Выполнение скриптов несёт риски безопасности. Рекомендуется учитывать:

Изоляция (sandboxing): запускайте скрипты в изолированных средах
Белые списки (allowlisting): выполняйте только скрипты из доверенных навыков
Подтверждение: запрашивайте у пользователей разрешение перед выполнением потенциально опасных операций
Логирование: записывайте все выполнения скриптов для аудита

Эталонная реализация¶

Библиотека skills-ref предоставляет утилиты на Python и CLI для работы с навыками.

Например:

Валидация каталога навыка:

1	`skills-ref validate <path>`

Генерация XML <available_skills> для промптов агента:

1	`skills-ref to-prompt <path>...`

Используйте исходный код библиотеки в качестве эталонной реализации.

Источник — https://agentskills.io/

Agent Skills¶

Зачем нужны Agent Skills?¶

Что могут обеспечить Agent Skills?¶

Внедрение¶

Открытая разработка¶

Что такое навыки?¶

Как работают навыки¶

Файл SKILL.md¶

Следующие шаги¶

Спецификация¶

Структура каталога¶

Формат SKILL.md¶

Метаданные (обязательные)¶

Поле name¶

Поле description¶

Поле license¶

Поле compatibility¶

Поле metadata¶

Поле allowed-tools¶

Содержимое тела¶

Необязательные каталоги¶

scripts/¶

references/¶

assets/¶

Прогрессивное раскрытие¶

Ссылки на файлы¶

Валидация¶

Интеграция навыков в вашего агента¶

Подходы к интеграции¶

Обнаружение навыков¶

Загрузка метаданных¶

Разбор метаданных¶

Внедрение в контекст¶

Вопросы безопасности¶

Эталонная реализация¶

Поле `name`¶

Поле `description`¶

Поле `license`¶

Поле `compatibility`¶

Поле `metadata`¶

Поле `allowed-tools`¶

`scripts/`¶

`references/`¶

`assets/`¶