Что именно делает description в SKILL.md?
Description служит краткой карточкой навыка до его активации. Агент сопоставляет описание с текущей задачей и решает, стоит ли читать полный SKILL.md. Поэтому поле должно отвечать на два вопроса: что skill делает и когда его следует применять.
Открытая спецификация Agent Skills требует непустое описание длиной до 1024 символов и советует включать конкретные слова, по которым можно распознать подходящую задачу. Anthropic отдельно указывает, что описание участвует в выборе среди множества skills.
Пошаговый процесс, ограничения выполнения и подробные примеры оставляйте в теле SKILL.md. Поле description отвечает за обнаружение и не заменяет инструкцию целиком.
Если формат пока незнаком, начните с материала что такое Agent Skills. Здесь мы работаем только с одним полем метаданных.
Из каких частей собрать рабочее описание?
Начните с результата, добавьте условия применения и при необходимости обозначьте ближайшую границу. Этого достаточно, чтобы агент отличил skill от общего помощника и от соседнего навыка с похожей тематикой.
| Часть | Что написать | Контрольный вопрос |
|---|---|---|
| Действие | Главный глагол skill | Что он делает? |
| Результат | Наблюдаемый итог | Что получит пользователь или процесс? |
| Условия | Объекты, форматы и формулировки запроса | Когда выбирать этот skill? |
| Граница | Ближайший похожий случай | Когда оставить skill выключенным? |
Последняя часть не обязательна по спецификации. Добавляйте её, когда два описания реально конкурируют, и оставляйте только после проверки на живых запросах.
Как назвать результат без расплывчатых обещаний?
Используйте глагол и проверяемый итог. Формулировка «проверяет ссылки и возвращает список битых URL» полезнее, чем «помогает с качеством сайта», потому что агент видит действие, объект и формат результата.
| Слабая формулировка | Точная формулировка |
|---|---|
| Helps with documents. | Extracts text and tables from PDF files and returns structured Markdown. Use when the user provides a PDF or asks to extract document content. |
| Helps with website quality. | Checks internal links and returns broken URLs with their source pages. Use when auditing site navigation or validating a release. |
Не вписывайте оценки без проверки вроде «делает лучший отчёт» или «гарантирует точность». Назовите то, что можно увидеть в результате: файл, таблицу, список замечаний, исправленный фрагмент или отчёт проверки.
Какие условия применения добавить в description?
Перечислите сигналы задачи, а не набор абстрактных существительных. Полезны тип входа, действие пользователя, ожидаемый результат, формат файла и характерные формулировки запроса.
- 1. Назовите вход
Укажите файл, объект или данные, с которыми работает skill: например, .xlsx, готовый черновик или журнал ошибок.
- 2. Назовите действие
Используйте глагол из реального запроса: проверить качество данных, найти пропуски, собрать сводку.
- 3. Назовите итог
Зафиксируйте результат: таблица ошибок, профиль полей, исправленная редакция или отчёт.
- 4. Уберите облако ключей
Фраза «Excel, CSV, data, tables, reports» хуже предложения, где видна связь между объектом, действием и результатом.
Когда нужны отрицательные границы?
Граница нужна при реальном пересечении с соседним skill. Укажите ближайший случай, который выглядит похожим, но требует другого процесса. Не составляйте длинный список всех задач мира, для которых навык не предназначен.
Эта граница разделяет проверку готового текста и создание нового. Она не обещает юридическую оценку и не расширяет полномочия skill.
Если вы выбираете между постоянной инструкцией, skill и внешним инструментом, сверьтесь со статьёй AGENTS.md, CLAUDE.md, SKILL.md и MCP: что выбрать.
Как развести два skills с похожими темами?
Сравните skills по результату, входу и моменту применения. Соседние descriptions должны различаться хотя бы по двум из этих признаков. Если различие нельзя объяснить одной фразой, skills, возможно, стоит объединить или сузить.
| Skill | Вход | Результат | Момент применения |
|---|---|---|---|
| article-research | Тема и требования к источникам | Проверенная исследовательская записка | До написания текста |
| article-editing | Готовый черновик | Список правок и новая редакция | После появления черновика |
Слово article есть в обоих описаниях, но оно не должно быть единственным сигналом. Первый skill ищет источники до черновика, второй правит уже существующий текст. Эти признаки и нужно вынести в description.
Как проверить срабатывание после правки?
Подготовьте три набора по три-пять запросов: skill должен сработать, не должен сработать и попадает в пограничный случай. До запуска запишите ожидаемое поведение, затем проверяйте навык рядом с реальной коллекцией, а не только в изоляции.
| Набор | Запрос | Ожидание |
|---|---|---|
| Прямой | Собери первичные источники для статьи про MCP | Skill срабатывает |
| Нерелевантный | Исправь опечатки в готовой статье | Skill не срабатывает |
| Пограничный | Проверь факты в этом черновике и найди источники | Ожидание фиксируется заранее |
Не называйте skill в каждом тестовом запросе: так вы проверите ручной вызов, а не обнаружение по смыслу. После одиночного теста подключите ближайшие соседние skills и повторите набор.
Более широкий A/B-тест пользы, стабильности и затрат описан отдельно в материале как оценить эффективность Agent Skill. Он начинается после того, как выбор skill уже работает достаточно устойчиво.
Что делать, если skill срабатывает слишком часто или редко?
При ложных срабатываниях сузьте условия и добавьте ближайшую границу. При пропусках добавьте реальные формулировки пользователей и недостающие типы входа. Меняйте одну часть description за итерацию и повторяйте тот же набор запросов.
| Симптом | Что проверить |
|---|---|
| Срабатывает слишком часто | Общие слова без действия, отсутствие типа входа, дублирование соседнего skill |
| Пропускает нужные задачи | Реальные формулировки пользователей, форматы входа, внутренние термины, которых нет в запросах |
Не меняйте одновременно описание, модель и коллекцию skills. Иначе причина улучшения или нового конфликта останется неизвестной.
Как проверить формат SKILL.md отдельно от поведения?
Сначала проверьте YAML и обязательные поля валидатором, затем проведите живой тест обнаружения. Синтаксическая проверка ловит пустое поле, неверное имя и ошибку frontmatter, но не показывает, выберет ли агент skill для нужного запроса.
После успешной проверки установите skill в тестовый контур по инструкции для Codex и Claude Code и прогоните три набора запросов.
Дополнительные поля и ограничения проверяйте по документации того клиента, где skill будет работать.
Частые вопросы о description в SKILL.md
Держите description кратким, конкретным и проверяемым. Лимит спецификации служит техническим потолком, а не целевым объёмом. Язык поля и отрицательные границы выбирайте по реальным запросам и поведению нужного клиента.
| Вопрос | Ответ |
|---|---|
| Нужно ли писать description на английском? | Спецификация не задаёт обязательный язык. Выберите язык рабочих запросов и проверьте его в нужном клиенте. |
| Нужно ли перечислять все команды skill? | Нет. Назовите главный результат и условия применения, а детали оставьте в теле SKILL.md. |
| Чем description отличается от name? | Name служит идентификатором, description объясняет назначение и условия выбора. |
| Гарантирует ли описание автоматический выбор? | Нет. На выбор влияют клиент, модель, запрос, другие инструкции и соседние skills. |
| Нужно ли повторять тест после правки? | Да. Прогоните прежний набор и проверьте пропуски, ложные срабатывания и конфликты. |
Где сверить требования и рекомендации?
Проверяйте обязательные поля по открытой спецификации Agent Skills, редакционные рекомендации - по документации Anthropic, а продуктовые особенности - по документации того клиента, где skill будет установлен.
- Agent Skills specificationОбязательные поля, ограничения description, progressive disclosure и валидация.
- Skill authoring best practicesРекомендации по точным описаниям и условиям выбора.
- Skills for enterpriseПроверки срабатывания, пограничных случаев и конфликтов.
- Build skillsSkills для ChatGPT и Codex на открытом стандарте.
- Extend Claude with skillsПродуктовые поля и поведение skills в Claude Code.