Как написать навык для ИИ-агента: Agent Skills и SKILL.md на практике
Коротко. Навык (Agent Skill) — это обычная папка с файлом SKILL.md: YAML-шапка из двух обязательных полей, name и description, плюс markdown-инструкция под ней. При старте агент читает только имя и описание каждого навыка — примерно сто токенов на навык, — а полный текст подгружает лишь тогда, когда задача совпала с описанием. Формат открытый и одинаковый у всех: одну и ту же папку понимают OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Codex, VS Code, Goose и ещё несколько десятков клиентов. В OpenClaw навык кладут в ~/.openclaw/workspace/skills/<имя>/SKILL.md и проверяют командой openclaw skills list; в Hermes Agent — в ~/.hermes/skills/<имя>/SKILL.md, проверка hermes skills list. Ниже — разбор всех полей спецификации, рабочий пример от пустой папки до вызова, разница между навыком и MCP-сервером и то, что стоит выключить, прежде чем ставить к себе чужой навык.
На чём это проверено
Спецификация сверена с первоисточником — agentskills.io/specification и репозиторием стандарта github.com/agentskills/agentskills — 4 сентября 2026 года. Команды и пути OpenClaw взяты из документации самого проекта (docs/tools/skills.md и docs/tools/creating-skills.md в github.com/openclaw/openclaw) на ту же дату; в реестре npm на 4 сентября канал latest — версия 2026.9.1 (релиз 3 сентября 2026), канал extended-stable — 2026.6.34. Для Hermes Agent проверялась документация hermes-agent.nousresearch.com и последний на тот момент релиз v0.21.0 (v2026.8.31) от 31 августа 2026.
Оба проекта выпускают релизы часто, а стандарт ещё дорабатывается — одно поле в нём прямо помечено как экспериментальное. Поэтому перед тем как копировать что-то в боевую конфигурацию, откройте документацию своей версии. Всё, что не удалось подтвердить по первоисточнику, в статью не попало — например, у ClawHub нет описанного механизма подписи навыков, и мы про подпись ничего не пишем.
Статья предполагает, что агент у вас уже поднят и отвечает. Если нет — начните с материалов первичная настройка OpenClaw или установка Hermes Agent.
Навык — это не промпт и не плагин
Разница проще, чем кажется. Промпт вы пишете каждый раз заново, и он живёт ровно одну сессию. Плагин — это код, который вы устанавливаете в систему. Навык находится посередине: это процедурное знание, оформленное как файл. «Вот как в нашей компании считают просроченную дебиторку», «вот в каком порядке мы согласовываем договор», «вот что означают колонки в выгрузке из учётной системы». Такой файл лежит в репозитории, у него есть история изменений, его можно ревьюить и откатывать.
Формально навык — это директория, в которой обязателен ровно один файл. Всё остальное опционально:
my-skill/
├── SKILL.md # обязательно: метаданные + инструкция
├── scripts/ # опционально: исполняемый код
├── references/ # опционально: справочные материалы
├── assets/ # опционально: шаблоны, ресурсы
└── ... # любые другие файлы и папкиФормат разработан в Anthropic и опубликован как открытый стандарт: репозиторий спецификации создан 16 декабря 2025 года, к 4 сентября 2026 у него 25 026 звёзд на GitHub. Именно поэтому навык переносим — вы пишете папку один раз, а работает она и в терминальном агенте, и в мессенджере, и в IDE, если клиент поддерживает формат.
Практический смысл для бизнеса ровно один: навык — это способ перестать объяснять агенту одно и то же. Пока регламент живёт в голове сотрудника, агент будет каждый раз выдавать «примерно правильный» результат. Как только регламент лежит в SKILL.md с точными шагами и явными запретами — результат становится воспроизводимым, а расхождения видно в диффе.
Анатомия SKILL.md: все поля спецификации
Шапка — это YAML между двумя строками ---. Обязательных полей два, остальные четыре нужны редко.
| Поле | Обязательное | Ограничения |
|---|---|---|
name | да | 1–64 символа; только строчные буквы, цифры и дефис; не начинается и не заканчивается дефисом; без двойных дефисов; должно совпадать с именем родительской папки |
description | да | 1–1024 символа, непустое; описывает что навык делает и когда его применять |
license | нет | название лицензии или ссылка на вложенный файл лицензии |
compatibility | нет | до 500 символов; требования к окружению — нужный продукт, системные пакеты, доступ в сеть |
metadata | нет | произвольная карта «строка → строка» для того, чего нет в стандарте |
allowed-tools | нет | строка с перечнем предодобренных инструментов через пробел. Помечено как экспериментальное — поддержка отличается от клиента к клиенту |
Минимальный валидный файл выглядит так:
---
name: skill-name
description: A description of what this skill does and when to use it.
---Главное поле здесь — description, и оно же чаще всего написано плохо. Именно по описанию агент решает, доставать навык из ящика или нет: полный текст инструкции он в этот момент ещё не видел. «Помогает с PDF» — описание, которое не сработает. «Извлекает текст и таблицы из PDF, заполняет формы и склеивает файлы. Использовать при работе с PDF-документами или когда пользователь упоминает PDF, формы или извлечение данных из документов» — сработает, потому что содержит слова, которые пользователь произнесёт сам. Спецификация прямо рекомендует закладывать в описание ключевые слова-триггеры.
Ограничение в 1024 символа — это потолок стандарта, а не рекомендация. У конкретных клиентов свои привычки: документация OpenClaw просит держать описание в одну строку и короче 160 символов, потому что оно показывается в списке слэш-команд. Разумный компромисс — два-три предложения.
Синтаксис тут — самая простая часть. Настоящая работа начинается там, где нужно решить, что агент должен видеть всегда, что подгружать по требованию, а что ему вообще нельзя показывать: это уже проектирование контекста, а не заполнение YAML. Если разбираться с этим с нуля некогда — спроектируем контекст агента: какие инструкции он видит и в какой момент.
Прогрессивное раскрытие: почему навыков может быть много
Ключевая идея формата — агент никогда не держит в контексте все навыки целиком. Загрузка идёт тремя ступенями:
- Обнаружение. При старте подтягиваются только
nameиdescriptionвсех доступных навыков — по спецификации это порядка 100 токенов на навык. Достаточно, чтобы понять, что навык вообще существует. - Активация. Задача совпала с описанием — агент читает тело
SKILL.mdцеликом. Рекомендованный потолок — менее 5000 токенов и не более 500 строк. - Исполнение. Файлы из
scripts/,references/иassets/подгружаются только тогда, когда инструкция реально до них дошла.
Отсюда прямое следствие для практики: длинный SKILL.md — это ошибка проектирования. Если инструкция разрослась, выносите подробности в references/ и ссылайтесь на них относительным путём от корня навыка:
См. [справочник по формату выгрузки](references/REFERENCE.md).
Запусти скрипт: scripts/extract.pyСпецификация советует держать такие ссылки на один уровень от SKILL.md и не строить длинных цепочек «файл ссылается на файл, который ссылается на файл». Причина та же — каждая ступень стоит контекста и времени.
Пишем первый навык: от пустой папки до вызова
Возьмём задачу, которая встречается почти в любой компании: собрать сводку по просроченной дебиторке из выгрузки в CSV. Ручной промпт тут работает плохо — модель начинает «прикидывать» суммы. Навык это чинит: считает скрипт, модель только комментирует.
Шаг 1. Создать папку
mkdir -p ~/.openclaw/workspace/skills/overdue-report/scriptsИмя папки должно совпадать с полем name — это требование спецификации. В OpenClaw навыки можно группировать по подпапкам (skills/finance/overdue-report/), имя всё равно берётся из шапки, а не из пути.
Шаг 2. Написать SKILL.md
---
name: overdue-report
description: Сводка по просроченной дебиторке из CSV-выгрузки. Использовать, когда просят отчёт по долгам, просрочке или дебиторке.
license: MIT
metadata:
author: acme
version: "1.0"
---
# Отчёт по просроченной дебиторке
## Когда применять
Пользователь просит сводку по долгам, просрочке, дебиторке
или спрашивает «кто нам должен».
## Что нужно на входе
Выгрузка из учётной системы в CSV с разделителем `;` и колонками
`client;amount;due_date`, где `due_date` — дата в формате `YYYY-MM-DD`.
## Порядок действий
1. Если путь к файлу не назван — спроси его, не угадывай.
2. Запусти `scripts/overdue.py <путь-к-файлу>`.
3. Верни вывод скрипта как есть, а под ним — три строки выводов:
сколько всего просрочено, кто в топе, что делать в первую очередь.
4. Если просроченных строк нет — скажи об этом прямо.
## Чего не делать
- Не пересчитывай суммы «на глаз» — только скриптом.
- Не отправляй результат никуда, кроме текущего чата,
пока об этом не попросили явно.Обратите внимание на секцию «Чего не делать». Это не украшение: навык — единственное место, где запрет живёт постоянно. В разовом промпте вы про него забудете.
Шаг 3. Положить скрипт
Файл scripts/overdue.py:
#!/usr/bin/env python3
"""Считает просроченную дебиторку из выгрузки CSV."""
import csv
import sys
from datetime import date
rows = []
with open(sys.argv[1], newline="", encoding="utf-8") as f:
for r in csv.DictReader(f, delimiter=";"):
overdue_days = (date.today() - date.fromisoformat(r["due_date"])).days
if overdue_days > 0:
rows.append((overdue_days, r["client"], float(r["amount"])))
rows.sort(reverse=True)
print(f"Просрочено счетов: {len(rows)} на сумму {sum(a for _, _, a in rows):,.2f}")
for days, client, amount in rows[:10]:
print(f"{days:>4} дн. {client:<30} {amount:>12,.2f}")Скрипт намеренно короткий и без зависимостей — только стандартная библиотека. Спецификация советует делать вложенные скрипты самодостаточными либо явно документировать зависимости, а язык зависит от клиента: обычно это Python, Bash или JavaScript.
Шаг 4. Проверить синтаксис валидатором
В репозитории стандарта лежит эталонная библиотека skills-ref. Она ставится из исходников:
git clone https://github.com/agentskills/agentskills.git
cd agentskills/skills-ref
python -m venv .venv && source .venv/bin/activate
pip install -e .
skills-ref validate ~/.openclaw/workspace/skills/overdue-reportВалидатор проверяет шапку и правила именования — то есть ловит ровно те ошибки, из-за которых навык молча не появляется в списке. Тридцать секунд, которые экономят полчаса недоумения.
Подключение в OpenClaw
OpenClaw ищет навыки в шести местах, и при совпадении имён выигрывает то, что выше:
| Приоритет | Источник | Путь |
|---|---|---|
| 1 — высший | навыки рабочей области | <workspace>/skills |
| 2 | проектные навыки агента | <workspace>/.agents/skills |
| 3 | личные навыки агента | ~/.agents/skills (только состояние по умолчанию) |
| 4 | управляемые / локальные | <state-dir>/skills |
| 5 | встроенные | поставляются с установкой |
| 6 — низший | дополнительные директории | skills.load.extraDirs и навыки плагинов |
Навык находится, если SKILL.md лежит где угодно внутри корня — до 6 уровней вложенности. Имя берётся из поля name, а если его нет — из имени папки.
Проверяем, что файл подхватился:
openclaw skills listПо умолчанию OpenClaw следит за файлами SKILL.md (ключ skills.load.watch). Если наблюдатель выключен или вы продолжаете старую сессию — начните новую командой /new в чате либо перезапустите шлюз: openclaw gateway restart. Затем пробуем:
openclaw agent --message "собери отчёт по просрочке из ~/vygruzka.csv"Явный вызов по имени — /skill overdue-report.
Полезные необязательные ключи шапки
Помимо полей стандарта OpenClaw читает свои:
user-invocable(по умолчаниюtrue) — показывать навык как слэш-команду;disable-model-invocation(false) — убрать навык из системного промпта; он останется доступен через/skill, но модель не будет выбирать его сама. Полезно для редких и дорогих процедур;command-dispatch: toolвместе сcommand-tool— отправить слэш-команду прямо в инструмент, минуя модель;homepage— ссылка, которая показывается как «Website» в интерфейсе на macOS.
Внутри инструкции удобно ссылаться на файлы навыка через {baseDir} — агент подставит путь к папке самого навыка, и переносить его между машинами станет безопасно:
Запусти вспомогательный скрипт `{baseDir}/scripts/overdue.py`.Условная загрузка и ключи API
Навык, которому нужна внешняя утилита, лучше загружать только там, где она есть. За это отвечает гейтинг в metadata.openclaw:
---
name: gemini-search
description: Search using Gemini CLI.
metadata: { "openclaw": { "requires": { "bins": ["gemini"] }, "primaryEnv": "GEMINI_API_KEY" } }
---Доступные условия: requires.bins (все бинарники должны быть в PATH), requires.anyBins (хотя бы один), requires.env (переменные окружения), requires.config (истинное значение по пути в openclaw.json), os — фильтр платформы ["darwin"], ["linux"], ["win32"], и always — включать на совместимой ОС даже если проверки не прошли.
Ключ API привязывается к навыку в openclaw.json:
{
skills: {
entries: {
"gemini-search": {
enabled: true,
apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
},
},
},
}Важная деталь из документации: ключ инжектится в хост-процесс только на один ход агента и в песочницу не попадает. Это ровно то поведение, которое нужно, если навык ходит во внешний сервис, а сам агент вы держите изолированным.
Лимиты, о которые спотыкаются
- новая сессия выбирает до 64 включённых навыков из библиотеки;
- одно сообщение может сослаться максимум на восемь разных навыков;
- управляемый бандл ограничен 256 файлами, 1 MiB на файл и 8 MiB суммарно.
Готовые навыки ищут и ставят из каталога ClawHub: openclaw skills search "calendar", затем openclaw skills install @openclaw/demo; флаг --global ставит навык для всех локальных агентов, openclaw skills update --all обновляет установленные. Список разрешённых навыков для агента задаётся ключами agents.defaults.skills и agents.entries.<agent>.skills, а отдельный навык включается и выключается через skills.entries.<имя>.enabled.
Подключение в Hermes Agent
Логика та же, пути другие. Основная директория и «источник истины» — ~/.hermes/skills/. Внутри git-репозитория Hermes дополнительно смотрит в <project-root>/.hermes/skills/ и <project-root>/.agents/skills/. Дополнительные каталоги перечисляются ключом skills.external_dirs в ~/.hermes/config.yaml.
mkdir -p ~/.hermes/skills/overdue-report/scripts
# кладём тот же SKILL.md и тот же scripts/overdue.py
hermes skills listШапка в примерах документации Hermes выглядит так — поля стандарта плюс собственные внутри metadata.hermes:
---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]
metadata:
hermes:
tags: [python, automation]
category: devops
---Проверить навык в работе можно одной командой, не заходя в интерактивный чат:
hermes chat --toolsets skills -q "Use the overdue-report skill to summarise ~/vygruzka.csv"Вызов слэш-командой — /overdue-report. Готовые навыки: hermes skills browse для просмотра, hermes skills install <identifier> для установки, hermes skills tap add <owner/repo> — чтобы подписаться на сторонний реестр. Опубликовать свой: hermes skills publish skills/my-skill --to github --repo owner/repo.
Раскрытие у Hermes тоже трёхступенчатое, только реализовано через инструменты: сначала агент видит список навыков, затем открывает конкретный навык целиком, и только потом — отдельный вложенный файл.
Навык и MCP-сервер — разные слои, а не конкуренты
Путаница здесь стоит дорого, поэтому коротко и прямо. MCP-сервер даёт агенту доступ — к базе, к CRM, к почте, к файловому хранилищу. Навык даёт агенту знание, как этим доступом пользоваться — в каком порядке, с какими проверками, что считать нормой, а что поводом остановиться.
Навык без инструментов упирается в потолок: инструкция описывает процедуру, но выполнить её нечем. Инструмент без навыка тоже работает плохо — агент видит двадцать эндпоинтов и выбирает не тот. Рабочая конфигурация — это оба слоя: доступ через MCP, регламент через навыки. Если первый слой у вас ещё не собран — подключим MCP-серверы к вашему агенту, чтобы навыкам было чем работать.
Безопасность: чужой навык — это чужой код
Про это стоит сказать прямо, потому что формат провоцирует беспечность. Навык выглядит как markdown-файл, но по спецификации папка scripts/ содержит исполняемый код, который агент может запускать. Установка чужого навыка — это запуск чужого кода на вашей машине, с правами вашего агента. Плюс сам markdown попадает прямо в контекст модели, а значит текст навыка — это ещё и канал для инъекции инструкций.
Минимальная гигиена, которая доступна из коробки:
- Читайте
SKILL.mdи содержимоеscripts/перед установкой. Навык компактен по замыслу — это пять минут чтения, а не аудит библиотеки на сто тысяч строк. - Ограничьте список навыков явно. В OpenClaw это
agents.defaults.skillsиagents.entries.<agent>.skills: белый список надёжнее, чем «включено всё, что нашлось в папке». - Разделяйте агентов. Навыку с доступом к боевой базе не место в том же агенте, который читает входящую почту.
- В Hermes включите ревью изменений. Ключ
write_approvalв~/.hermes/config.yamlтребует человеческого подтверждения, когда агент правит навыки сам, аproject_discoveryпозволяет вовсе отключить подхват навыков из проектных папок. Проектные навыки Hermes к тому же сканирует перед загрузкой и помещает в карантин те, что признаны опасными. - Не кладите секреты в текст навыка. Для этого есть
skills.entries.<имя>.apiKeyв OpenClaw иrequired_environment_variablesв Hermes — ключ подставляется в момент выполнения и не лежит в репозитории.
Отдельно про allowed-tools: поле выглядит как готовое решение — перечислил разрешённые инструменты, и всё. Но в спецификации оно помечено экспериментальным, и поддержка отличается от клиента к клиенту. Полагаться на него как на границу безопасности пока рано; настоящая граница — это права процесса и песочница, а не строка в YAML.
Когда не стоит писать навыки самому
Один навык на компанию — это вечер работы, и делать его самому совершенно нормально. Сложность растёт не от количества строк, а от количества стыков.
Считайте по-честному. Первый навык — вечер. Пять навыков, которые не должны срабатывать друг вместо друга, — это уже неделя: описания приходится разводить так, чтобы агент не путал «отчёт по дебиторке» с «отчётом по продажам», а каждое изменение регламента нужно прогонять по всем пяти. Добавьте доступ к боевым системам — и появляется контур с правами, белыми списками и разделением агентов, который проектируют отдельно. Добавьте несколько сотрудников, которые правят навыки, — нужен ревью и откат.
Практическая развилка простая: если навык читает файл и печатает текст — пишите сами, по этой инструкции хватит. Если навык ходит в учётную систему, меняет данные или им пользуется больше двух человек — закладывайте не вечер, а проект, и заранее решите, кто будет его сопровождать при следующем обновлении агента. Состав подписки и актуальные цены на сопровождение — на странице тарифов; отдельно про рычаги производительности и стоимости мы писали в материале тюнинг OpenClaw.
Частые вопросы
Навык работает только в одном агенте или во всех?
Во всех, кто поддерживает формат. Одна и та же папка с SKILL.md подхватывается OpenClaw, Hermes Agent, Claude Code, Gemini CLI, Codex, VS Code, Goose и другими клиентами из списка на agentskills.io. Отличаются только пути на диске и необязательные поля в metadata — их посторонний клиент просто игнорирует.
Сколько навыков можно держать одновременно?
Технически много: при старте агент читает только имя и описание, около ста токенов на навык. Практический потолок задаёт клиент — OpenClaw выбирает до 64 включённых навыков на новую сессию и позволяет сослаться максимум на восемь в одном сообщении. Гораздо раньше упрётесь в другое: если описания похожи, агент начнёт выбирать не тот навык.
Нужно ли программировать, чтобы написать навык?
Нет, если навык — это только инструкция. Обязательный минимум — текстовый файл с шапкой из двух полей. Код нужен там, где нужны точные вычисления или обращение к внешней системе: тогда добавляется папка scripts/.
Почему навык не появился в списке?
Три причины по частоте: имя папки не совпадает с полем name; ошибка в YAML-шапке (проверяется командой skills-ref validate); навык добавлен в уже идущую сессию — начните новую или перезапустите агента. Реже — навык отфильтрован гейтингом, потому что нужного бинарника нет в PATH.
Чем навык отличается от MCP-сервера?
MCP-сервер даёт доступ к системе, навык — знание, как этим доступом пользоваться. Это дополняющие слои: доступ без регламента приводит к неверным действиям, регламент без доступа не выполняется.
Итог
Навык — самый дешёвый способ сделать поведение агента воспроизводимым: папка, файл, две обязательные строки в шапке. Начните с одной процедуры, которую в компании объясняют чаще всего, опишите её точными шагами и явными запретами, проверьте валидатором и посмотрите, как агент выберет её сам. Дальше добавляйте по одному навыку — и разводите описания, чтобы они не спорили между собой.
Если проще передать эту часть работы: автоматизируем бизнес-процессы через навыки агента — от разбора регламента до готовой папки в вашем репозитории.