OpenClaw Skills: как расширять агента через SKILL.md и ClawHub

OpenClaw Skills — это папки с инструкцией `SKILL.md`, которые учат agent выполнять конкретные типы задач: работать с инструментом, сервисом, форматом файла, локальной процедурой или внутренним процессом. Skill делает ассистента полезнее, но расширяет его рабочую поверхность, поэтому каждый новый skill нужно читать и проверять до включения.

Что такое skill в OpenClaw

Skill — это не “магическая способность”, а структурированная инструкция. Внутри обычно лежит `SKILL.md`: когда использовать skill, какие шаги выполнить, какие ограничения соблюдать, какие файлы читать, какие команды разрешены и где находятся справочные материалы. Дополнительно в папке могут быть templates, references, scripts или assets.

Когда agent получает задачу, OpenClaw может добавить подходящие skills в доступный контекст. Если запрос совпадает с описанием skill, agent применяет эту процедуру. Поэтому качество `description` в frontmatter влияет на то, будет ли skill вызван вовремя или будет лежать без дела.

skills/
└── report-builder/
    ├── SKILL.md
    ├── templates/
    └── references/

Зачем нужны OpenClaw Skills

Без skills agent каждый раз опирается на общие инструкции, память сессии и доступные tools. Skill добавляет повторяемую процедуру. Например, “как проверять статью перед публикацией”, “как собирать отчет из таблицы”, “как работать с конкретным API”, “как создавать документ по шаблону”, “как не трогать защищенные страницы”.

• Процедуры: чеклист действий, который должен повторяться одинаково.
• Ограничения: что нельзя делать, какие команды опасны, какие файлы защищены.
• Форматы: правила для Markdown, WordPress blocks, JSON, CSV, DOCX или другого результата.
• Ссылки на справку: где agent берет локальные references без поиска наугад.
• Проектная память: как команда хочет выполнять конкретный тип задач.

Мы получаем пользу только тогда, когда skill конкретен. Формулировка “помогай писать лучше” почти не работает. Формулировка “при подготовке OpenClaw-статьи не использовать шаблонный заголовок блока вопросов, добавлять CII-блок и проверять команды по official docs” уже дает agent рабочую инструкцию.

Где OpenClaw ищет skills

OpenClaw может видеть skills из нескольких мест. Порядок важен: ближний к workspace skill обычно должен переопределять общий. Так можно держать личные skills отдельно, а для конкретного проекта задавать свои правила.

Источник	Путь	Когда использовать
Workspace skills	`<workspace>/skills`	Процедуры конкретного проекта или агента
Project agent skills	`<workspace>/.agents/skills`	Общие правила внутри workspace
Personal agent skills	`~/.agents/skills`	Личные навыки пользователя на машине
Managed/local skills	`~/.openclaw/skills`	Локальные общие overrides
Bundled skills	Внутри установки OpenClaw	Базовые навыки, поставляемые с проектом
Extra dirs	`skills.load.extraDirs`	Дополнительные корни с низким приоритетом
Plugin skills	Папки, указанные в plugin config	Инструкции, которые идут вместе с plugin

Если skill с одинаковым именем найден в нескольких местах, проверяйте приоритет. Проектный skill может намеренно перекрывать bundled-версию. Это удобно, когда у команды есть свои правила публикации, безопасности или проверки результата.

Как установить skill через ClawHub

ClawHub — публичный реестр skills для OpenClaw. Для обычной установки сейчас лучше использовать native-команды `openclaw skills`, а отдельный `clawhub` CLI оставлять для publish/sync-сценариев. Важная деталь: `openclaw skills install` скачивает skill в активный workspace `skills/`.

openclaw skills install <skill-slug>
openclaw skills update --all

Перед установкой найдите страницу skill в реестре, прочитайте описание, проверьте автора, зависимости и файлы. После установки откройте `SKILL.md` руками. Я не включаю третий skill в рабочий workspace, пока не понимаю, какие команды он предлагает agent.

Для publish/sync-процессов может понадобиться отдельный `clawhub` CLI. Например, синхронизация всех локальных изменений с реестром описана как `clawhub sync —all`. Это не то же самое, что установка skill обычным пользователем.

clawhub sync --all

Как устроен SKILL.md

`SKILL.md` должен быть коротким входом в процедуру. Он не обязан содержать всю книгу внутри одного файла, но должен объяснять agent, когда применять skill и где лежат дополнительные материалы. Формат совместим с AgentSkills-подходом: frontmatter с `name` и `description`, затем инструкции.

---
name: editorial-openclaw
description: Use when preparing OpenClaw articles for the AI rubric with WordPress blocks, safety checks, CII links, and official-doc command verification.
---

Use this skill when writing or editing OpenClaw articles.

Rules:
- Do not use generic question-section headings.
- Use "Ответы на эти вопросы могут быть для вас полезными".
- Verify commands against docs.openclaw.ai.
- Add one OpenClaw CII internal link block.
- Keep tokens and pairing codes out of screenshots and examples.

В `description` лучше писать не красивые слова, а триггер использования. Agent должен понять: “эту инструкцию применяют при подготовке статей OpenClaw”. Если description расплывчатый, skill будет вызываться реже или не к месту.

Что класть рядом со SKILL.md

Сама инструкция должна быть компактной. Большие справочники, шаблоны и примеры лучше вынести в соседние папки. Тогда agent читает только нужное, а не тащит в контекст все подряд.

Папка	Что хранить	Проверка
`templates/`	Шаблоны статей, отчетов, писем, JSON-структур	Есть пример заполнения
`references/`	Локальные правила, справочные таблицы, карты полей	Нет секретов и лишних логов
`scripts/`	Небольшие вспомогательные команды	Понятно, что они меняют
`assets/`	Заготовки, изображения, CSS-фрагменты	Права и источники проверены

Если script внутри skill меняет файлы, это должно быть явно описано. Хороший skill не прячет побочные действия. Он говорит: какие файлы читает, какие пишет, какие команды запускает, где остановиться и что показать пользователю.

Безопасность skills

Третий skill надо считать недоверенным кодом и недоверенной инструкцией. Даже если внутри нет исполняемого файла, текст может направить agent к опасным действиям: раскрыть секрет, удалить директорию, загрузить чужой скрипт, отключить проверки или отправить данные во внешний сервис.

• Читайте `SKILL.md`: перед первым использованием и после обновления.
• Проверяйте scripts: ищите сетевые вызовы, удаления, запись в домашние директории и работу с секретами.
• Не храните ключи в skill: используйте переменные окружения или настройки, которые не уходят в промпт.
• Ограничивайте workspace: skill для проекта должен жить в проектном `skills/`, а не в глобальном месте без причины.
• Используйте sandbox: для непроверенных входных данных и рискованных tools.
• Смотрите обновления: `openclaw skills update —all` полезен, но после него нужно понимать, что изменилось.

Официальные docs отдельно предупреждают: значения `skills.entries.*.env` и `skills.entries.*.apiKey` попадают в host process для хода агента, а не в sandbox. Это значит, что секреты нельзя вставлять в промпты, логи и учебные примеры.

Как написать свой skill

Начинайте с одной повторяемой процедуры. Не пытайтесь сделать “skill для всего отдела”. Лучше написать узкую инструкцию: “как публиковать OpenClaw-материал”, “как проверять Docker-статью”, “как собирать weekly report из таблицы”.

1. Создайте папку внутри `/skills`.
2. Добавьте `SKILL.md` с `name` и точным `description`.
3. Опишите, когда skill использовать.
4. Укажите разрешенные и запрещенные действия.
5. Добавьте критерии готовности результата.
6. Вынесите большие примеры в `references/`.
7. Проверьте skill на одной реальной задаче.

Критерий качества простой: после чтения skill agent должен выполнить задачу ближе к вашему стандарту, а не просто получить еще один длинный текст. Если skill не меняет результат, его нужно переписать короче и точнее.

Skill Workshop: когда использовать

В OpenClaw описан экспериментальный Skill Workshop plugin. Он может создавать или обновлять workspace skills на основе повторяемых процедур, которые появились во время работы. По смыслу это удобно для командных поправок: “в следующий раз всегда проверяй атрибуцию изображений” или “для нашей рубрики добавляй CII-блок”.

Для рабочего проекта я бы начинал с pending approval: plugin предлагает изменение, человек просматривает, потом одобряет. Автоматическую запись стоит включать только в доверенном workspace, где понятны правила, owner и последствия.

Чеклист перед включением skill

• Понятно, для какой задачи нужен skill.
• `description` срабатывает на конкретный сценарий, а не на любую просьбу.
• `SKILL.md` не просит раскрывать токены, cookies, pairing codes или приватные файлы.
• Scripts прочитаны, нет скрытых удалений и непонятных сетевых отправок.
• References не содержат секретов и персональных данных.
• Skill лежит в правильном уровне: workspace, project, personal или managed.
• Есть критерий результата: файл создан, статья проверена, отчет построен, команда прошла.

Если хотя бы один пункт неясен, skill лучше не добавлять в рабочий Gateway. Можно протестировать его в отдельном workspace без реальных секретов и только потом переносить.

Как обновлять skills без хаоса

Обновление skill — это не механическое “получить новую версию”. Skill меняет инструкцию, которую читает agent, а значит может поменять поведение в реальной задаче. Перед `openclaw skills update —all` зафиксируйте, какие skills стоят в workspace, какие из них реально используются и какие файлы могут быть затронуты их scripts.

1. Сохраните список текущих skills и версий, если registry показывает version.
2. Обновите skills в тестовом workspace или на копии проекта.
3. Прочитайте изменившийся `SKILL.md` и связанные scripts.
4. Запустите одну типовую задачу, для которой skill нужен.
5. Сравните результат с прежним стандартом.
6. Только после этого обновляйте рабочий workspace.

Для критичных правил я предпочитаю project skill внутри `/skills`, а не глобальное обновление. Так редакционные, безопасностные или публикационные правила проекта не меняются внезапно из-за обновления общего набора skills.

Источники для сверки

• OpenClaw Skills
• ClawHub skills registry
• ClawHub guide
• OpenClaw Security

Ответы на эти вопросы могут быть для вас полезными

Можно ли поставить skill глобально для всех проектов?

Можно, но не всегда нужно. Для проектных правил лучше использовать `/skills`, чтобы инструкция не влияла на другие задачи. Глобальные skills оставляйте для личных процедур, которые действительно повторяются в разных workspaces.

ClawHub и openclaw skills install — это одно и то же?

ClawHub — реестр. `openclaw skills install <skill-slug>` — native-команда установки skill из этого реестра в активный workspace. Отдельный `clawhub` CLI нужен для publish/sync-потоков.

Skill может быть опасным без кода?

Да. Текстовая инструкция может направить agent к небезопасному действию. Поэтому читают не только scripts, но и сам `SKILL.md`: что он просит делать, какие данные открывать, какие проверки пропускать.