Skill & Agent Creator 🔧

Создание и улучшение скиллов и агентов OpenClaw. Лучшие практики + боевой опыт с 42 скиллами и 7 агентами. Агенты: от базового (5 мин) до полноценного рабочего в команде (Board-First, конституция, ОТК, автоулучшение, defrost). Режим B создаёт агента идентичного по архитектуре боевым агентам продакшена (10 шагов).

Подробный ресёрч: references/research-best-practices.md Чеклист: references/checklist.md Конкурентный анализ: references/competitive-analysis.md

Быстрый старт

Скилл за 5 минут:

1. mkdir skills/<имя>/ → создать SKILL.md с frontmatter (name, description) + алгоритм + 2 примера
2. Готово. Скилл подхватится автоматически (hot-reload)

Агент за 5 минут (базовый):

1. Добавить в agents.list[] в openclaw.json (id, name, model, workspace, tools.deny)
2. mkdir workspace + AGENTS.md с ролью
3. launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

Полноценный агент в команде (10 шагов):

Режим B ниже. Создаёт агента с Board-First Protocol, конституцией, BOOTSTRAP, briefing pattern, ОТК и defrost. Идентичен боевым агентам продакшена.

Нужно по шагам? Читай дальше.

Режим A: СКИЛЛ

Шаг 1. Онбординг (2-4 вопроса, по одному)

1. Что скилл должен делать? Конкретный пример использования
2. Когда активировать? (триггерные фразы)
3. Нужны ли скрипты, данные, внешние API?
4. Публичный (для подписчиков) или внутренний?

Шаг 2. Определи тип скилла

Workflow (пошаговый процесс) - если задача = последовательность действий. → Пример: deep-research-pro (5 шагов: уточнение → поиск → синтез → отчёт)

Role (экспертная роль) - если задача = "отвечай как специалист X". → Пример: copywriter (пиши как {{OWNER_NAME}}, вот стиль, вот примеры)

Data-driven (работа с данными) - если нужны конкретные факты/профили. → Пример: auto-mechanic (профиль машины в data/, логика диагностики в SKILL.md)

Гибрид - комбинация. Пример: family-doctor = Role + Data (роль врача + медпрофили в data/).

Шаг 3. Планирование структуры

В зависимости от типа (шаг 2):

• Workflow → обычно хватит одного SKILL.md (вся логика помещается в core)
• Role → SKILL.md + references/ (словарь стиля, примеры голоса, правила)
• Data-driven → SKILL.md + data/ (профили, базы, справочники)
• Гибрид → SKILL.md + references/ + data/ (по необходимости)

Также могут понадобиться:

• scripts/ - Python/Bash для повторяемых операций
• assets/ - шаблоны, изображения

Пропорции:

• SKILL.md: 100-300 строк (мета-скиллы и сложные workflow до 350)
• Примеры: 2-3 конкретных
• Данные в data/, НЕ в memory/!

Шаг 4. Инициализация

Новый скилл с нуля (опционально):

python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/init_skill.py <name> --path {{WORKSPACE_PATH}}skills/

Или просто создать папку и SKILL.md вручную - оба варианта ок.

Шаг 5. Написание SKILL.md

Frontmatter (обязательно):

---
name: имя-скилла
description: "Что делает + когда использовать. Triggers: 'фраза1', 'фраза2'."
---

Допустимые поля: name, description, allowed-tools, license, metadata. Поле version НЕ поддерживается!

5 принципов:

1. Только уникальное - не пиши то, что модель и так знает
2. Примеры > теория - один пример лучше абзаца объяснений
3. Детали отдельно - основное в SKILL.md, подробности в references/
4. Триггеры в description - body грузится ПОСЛЕ триггера, "когда использовать" пиши в frontmatter
5. Императив - "Найди", "Отправь", не "Можно найти"

Шаблон body (выбери по типу из шага 2):

Workflow:

# Название → Алгоритм (шаги) → Примеры → Ограничения

Role:

# Название → Роль (кто ты) → Правила стиля → Примеры ответов → Чего НЕ делать

Data-driven:

# Название → Где данные → Алгоритм работы с данными → Как обновлять → Примеры

Шаг 6. Черновик → одобрение

Покажи черновик владельцу ПЕРЕД финализацией. Формат:

📝 Черновик скилла: [имя]
Тип: [workflow/role/data-driven/гибрид]
Что делает: [2-3 предложения]
Структура: SKILL.md + [references/ | data/ | scripts/]
Пример вызова: "[фраза]" → [что получится]

Дождись "ок" или правок. Лучше поправить черновик за 2 минуты, чем переделывать готовый скилл.

Шаг 7. Проверка качества

python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/quick_validate.py skills/<имя>/

Ручная проверка:

• Работает без внешних знаний (self-contained)
• Примеры реалистичные
• Нет TODO, заглушек
• Размер адекватный задаче
• Триггеры покрывают варианты обращения

Шаг 8. Аудит безопасности (для публичных)

grep -ri "{{OWNER_NAME}}\|{{TELEGRAM_CHANNEL}}\|{{AGENT_NICKNAME}}\|{{OWNER_TELEGRAM_ID}}\|{{CITY}}\|{{OWNER_SURNAME}}" SKILL-public.md

Результат = 0 строк.

Чеклист: нет личных данных, нет локальных путей, нет внутренних названий, нет ключей/токенов, model-agnostic.

Шаг 9. Тест

1. Вызвать скилл с реальным запросом
2. Edge cases: пустой ввод, нестандартный запрос
3. Если контент - проверить стиль
4. Если команды - проверить зависимости

Шаг 10. Публичная версия (если нужна)

SKILL.md → SKILL-public.md → убрать личное → аудит повторно.

Шаг 11. Итерация

• {{OWNER_NAME}} поправил → записать что не так
• 3+ повтора проблемы → добавить в скилл
• Хирургические правки, не переписывать всё

Режим B: АГЕНТ

Шаг 1. Онбординг (5 вопросов, по одному)

1. Роль/задача агента? (маркетолог, тимлид, коуч...)
2. Какие tools нужны? Какие запретить?
3. Нужна ли векторная память (memorySearch)?
4. Связь с другими агентами?
5. Привязка: Telegram топик, отдельный бот, API?

Шаг 1a. Определи тип агента

Полноценный рабочий - свой бот, своя память, свои скиллы, система автоулучшения. Для долгосрочных ролей: тимлид, маркетолог, аналитик. → Все 9 шагов. Чеклист из 12 файлов. memorySearch: true.

Специализированный - своя экосистема (Obsidian, отдельная база). Для уникальных задач: коуч целей, трекер привычек. → Шаги 1-4 + 7-8. Workspace = своя среда. Файлы адаптировать.

Маска (топик-роль) - нет своего бота, работает через systemPrompt основного. Для экспертных ролей: врач, астролог, механик. → Только systemPrompt в конфиге группы/топика. Минимум файлов. tools.deny максимальный.

Шаг 2. Конфиг (openclaw.json → agents.list[])

{
  "id": "<agent-id>",
  "name": "Имя Агента",
  "model": "anthropic/claude-sonnet-4-6",
  "workspace": "~/.openclaw/agents/<agent-id>/agent",
  "agentDir": "~/.openclaw/agents/<agent-id>/agent",
  "memorySearch": { "enabled": true },
  "heartbeat": { "every": "0" },
  "tools": { "deny": ["gateway"] }
}

• model: ПОЛНОЕ имя, не алиас
• memorySearch: true для рабочих агентов (накапливают контекст)
• tools.deny: gateway ВСЕГДА; cron, exec по ситуации
• heartbeat.every: "0" если не нужен мониторинг

Шаг 3. Связи

# В openclaw.json → секция "tools" (НЕ в agents!):
"tools": {
  "agentToAgent": { "enabled": true, "allow": ["main", "<agent-id>"] }
}

sessions_send ВСЕГДА с timeoutSeconds=120 (синхронный, ждёт ответ).

Шаг 4. Binding (Telegram)

⚠️ КРИТИЧНО: Без binding DM через бота падает в agent:main!

Две вещи нужны чтобы бот отвечал как свой агент:

A. Account в channels.telegram.accounts:

"accounts": {
  "<agent-id>": {
    "botToken": "...",
    "commands": {"nativeSkills": false},
    "dmPolicy": "allowlist",
    "groupPolicy": "disabled",
    "allowFrom": ["<owner-telegram-id>"],
    "streaming": "partial",
    "reactionLevel": "minimal"
  }
}

B. Binding в top-level bindings (ОБЯЗАТЕЛЬНО!):

"bindings": [
  {
    "agentId": "<agent-id>",
    "match": {"channel": "telegram", "accountId": "<agent-id>"}
  }
]

Без binding (B) — DM через любого бота уходит в fallback → agent:main. Account name (A) ≠ binding. Нужны ОБА.

Проверка: openclaw agents list --bindings

Для топика в группе:
```json
"accounts": {
  "<agent-id>": {
    "botToken": "...",
    "groups": { "<group-id>": { "topics": { "<topic-id>": { "requireMention": false } } } }
  }
}

После добавления бота: проверь что в ~/.openclaw/agents/main/sessions/ НЕ создалась сессия с accountId нового бота. Если создалась - удали .jsonl и запись из sessions.json.

Шаг 5. Workspace - структура файлов

mkdir -p ~/.openclaw/agents/<agent-id>/agent/memory

Обязательные файлы (чеклист):

Симлинки (КРИТИЧНО для командной работы):

# Скиллы
ln -s {{WORKSPACE_PATH}}skills ~/.openclaw/agents/<agent-id>/agent/skills

# USER.md — СИМЛИНК, не копия! Единый источник правды
ln -sf {{WORKSPACE_PATH}}USER.md ~/.openclaw/agents/<agent-id>/agent/USER.md

# References — конституция, доска, проекты
mkdir -p ~/.openclaw/agents/<agent-id>/agent/references
bash {{WORKSPACE_PATH}}scripts/sync-agent-references.sh

Почему симлинки, не копии:

• USER.md обновился → все агенты видят сразу (без ручной синхронизации)
• Конституция изменилась → все читают актуальную версию
• Крон sync-agent-references.sh (ежедневно 06:00) создаёт симлинки на новые файлы в references/

Обязательные симлинки для командных агентов:

Шаг 5a-5c. Шаблоны файлов

Все шаблоны с примерами: references/agent-templates.md

Содержит готовые к копированию шаблоны:

• AGENTS.md - прозрачность, роль, команда, скиллы, память, автоулучшение
• SOUL.md - личность, принципы, стиль, границы
• USER.md - профиль владельца адаптированный под роль агента
• IDENTITY.md - имя, роль, краткое описание
• MEMORY.md - сводка фактов
• TOOLS.md - инструменты с командами
• memory/lessons.md - уроки и правила
• memory/patterns.md - паттерны автоулучшения
• memory/projects-log.md - история задач
• memory/architecture.md - самоописание агента

Ключевые принципы (знать без шаблонов):

1. AGENTS.md - главный файл. Порядок секций: прозрачность → кто я → команда → скиллы → проекты → связи → память → инструменты → стиль
2. USER.md - адаптировать под роль! Маркетологу - каналы и аудитория. Тимлиду - GitHub и стек. Личные данные - только если реально нужны
3. SOUL.md - не копипаста. Каждый агент = своя личность. Принципы вытекают из роли
4. Память - 4 уровня: контекстная → файловая → векторная → identity. Автоулучшение: ошибка → паттерн → 3 повтора → правило
5. Длинные проекты - создавать status.md как save-game. При обрыве сессии продолжить с него

Шаг 6. Гигиена

Убедиться что ночная чистка покрывает нового агента:

• .jsonl сессии в ~/.openclaw/agents/<id>/sessions/ - удалять >30 дней
• SQLite общая база - чистка кроновых чанков уже работает для всех

Если используется night-cleanup.sh с wildcard ~/.openclaw/agents/*/sessions/ - новый агент подхватится автоматически.

Шаг 6b. Автоматическая память (для рабочих агентов)

Если агент ведёт длинные сессии с владельцем — добавь автоматическое сохранение контекста. Без этого при компактификации теряется 30-50% текущего разговора.

BOOTSTRAP.md — кладётся в workspace, грузится автоматически:

# BOOTSTRAP.md
После старта/компактификации:
1. read memory/handoff.md — текущий контекст ("save game")
2. read memory/YYYY-MM-DD.md — дневник дня
3. Если оба пустые: sessions_history(sessionKey="agent:<id>:main", limit=20)

Auto Handoff (крон, каждый час) — Sonnet субагент читает sessions_history агента и перезаписывает memory/handoff.md актуальным снимком: текущая тема, решения, TODO, критичный контекст. Если сессия неактивна — не трогает файл.

Auto Diary (крон, каждые 4 часа) — Sonnet субагент дописывает ключевые темы и решения в memory/YYYY-MM-DD.md. Не дублирует, только новое.

Когда добавлять: если агент общается с владельцем >1 часа в день и теряет контекст при обрезке. Для агентов с короткими задачами — не нужно, хватит memory/lessons.md.

Шаг 7. Перезапуск

Перед перезапуском - проверь конфиг:

openclaw status

Бэкап:

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

Перезапуск через gateway tool (config.patch автоматически рестартит). ⚠️ НЕ openclaw gateway restart из сессии агента!

Если не поднялся - откат:

cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw gateway restart

Шаг 8. Тест

1. Отправь сообщение → получи ответ
2. Проверь изоляцию: tools.deny работает? memorySearch только своё?
3. Проверь связи: sessions_send доходит?
4. Проверь прозрачность: пишет уведомления?
5. Проверь память: при старте читает lessons/patterns/projects-log?
6. Проверь скиллы: перед задачей читает SKILL.md?

Шаг 9. Выравнивание с командой

Если есть другие агенты - убедись что новый на том же уровне:

• Все файлы из чеклиста (шаг 5) на месте
• USER.md заполнен под его роль
• Маршрутизация по скиллам в AGENTS.md
• Знает про команду (таблица агентов)
• Ночная чистка покрывает его сессии
• Обновить AGENTS.md других агентов (добавить нового в таблицу команды)

Шаг 10. Командная архитектура (КРИТИЧНО для рабочих агентов!)

Если агент работает В КОМАНДЕ с другими — обязательно настроить:

A. Конституция команды: Если есть файл references/team-constitution.md — добавить ссылку в TOOLS.md агента:

## ⭐ КОНСТИТУЦИЯ КОМАНДЫ (ЧИТАТЬ ПЕРВОЙ!)
Файл: `references/team-constitution.md` — единственный источник правды.

Если конституции нет — создать. Минимум: цепочка задач, роли, правила файлов, запреты.

B. Board-First Protocol (координация через файлы):

• Все данные (задачи, результаты, статусы) — в файлах (team-board.md, briefing.md, result.md)
• sessions_send — ТОЛЬКО будильник (1 строка: "Готово, смотри board")
• НЕ передавать детали задачи через sessions_send (потеряется при компактификации)

Добавить в TOOLS.md агента секцию "При завершении — BOARD-FIRST PROTOCOL" (шаблон в references/agent-templates.md).

C. Smart session trash: Перед каждой задачей агенту — сбрасывать сессию если >50K токенов:

# scripts/trash-agent-session.sh <agent-id>
# Проверяет размер сессии, сбрасывает если >50K
# --force для безусловного сброса

⚠️ ОБЯЗАТЕЛЬНО sleep 5 после сброса перед sessions_send (race condition).

D. Briefing pattern: Для каждой задачи создавать projects/НАЗВАНИЕ/briefing.md:

• Что сделать
• Источники/референсы
• Путь для результата
• Стандарты (стиль, формат)
• Ответ: макс 3 строки (статус, файл, проблемы)

Агент читает briefing → делает → кладёт результат → обновляет board.

E. ОТК (проверка качества): Определить кто проверяет результат перед доставкой владельцу:

• Координатор проверяет сам (скилл quality-check) → доставляет владельцу
• Или: агент → координатор → владелец (двухступенчатая цепочка)

F. Plan + "Погнали": Для больших задач координатор ОБЯЗАН прислать владельцу план с кнопкой "Погнали 🚀". Без подтверждения — НЕ НАЧИНАТЬ.

G. Defrost protocol (антизависание): Если агент не отвечает >3 минут:

1. Ping через sessions_send (timeout=60)
2. Если молчит → trash session + повторный briefing
3. Если снова молчит → эскалация владельцу

H. BOOTSTRAP.md (автовосстановление): Создать файл в workspace агента (шаблон в references/agent-templates.md). Читается автоматически при старте/компактификации. Восстанавливает контекст из handoff + дневника.

Чеклист командной архитектуры:

• Конституция подключена в TOOLS.md
• Board-First Protocol прописан в TOOLS.md
• Briefing pattern описан
• BOOTSTRAP.md создан
• Агент добавлен в agentToAgent allow list (если нужен синхронный вызов)
• Trash script покрывает нового агента
• Active-projects.md обновлён (если есть)
• USER.md = симлинк (НЕ копия!)
• references/ симлинки: constitution, board, active-projects
• bash scripts/sync-agent-references.sh выполнен
• timeoutSeconds=120 в TOOLS.md и AGENTS.md (НЕ 0!)
• Данные под роль в data/ (конкуренты для маркетолога, API для финансиста и т.д.)
• Секция "📂 Общие файлы (references/)" в TOOLS.md
• bash scripts/agent-health-check.sh — 0 проблем после создания

Режим C: УЛУЧШЕНИЕ СУЩЕСТВУЮЩЕГО

1. Прочитай текущий SKILL.md - пойми что есть, какой тип, какая структура
2. Определи проблему - конкретно: "нет примеров", "устарел алгоритм", "{{OWNER_NAME}} поправил результат"
3. Хирургическая правка - меняй только то, что сломано. Не переписывай весь скилл
4. Проверь - валидация (шаг 7) + тест (шаг 9)
5. Обнови публичную версию - если есть SKILL-public.md, синхронизируй

Когда улучшать: {{OWNER_NAME}} поправил результат, 3+ повтора одной проблемы, появилась новая возможность/инструмент.

⛔ Когда НЕ создавать

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

Агент не нужен если: хватит маски (systemPrompt в топике), не нужна своя память, никто не будет пользоваться регулярно.

Миграция маска → полноценный агент: Если маска начала: накапливать контекст между сессиями, нуждаться в своих файлах, требовать tools - пора переводить. Пройди все 9 шагов для полноценного агента.

⚠️ Грабли

Скиллы

Агенты

Примеры из нашей системы

Пример 1: Простой скилл (копирайтер)

Структура:

skills/copywriter/
├── SKILL.md                          # 150 строк: роль + правила + примеры
└── references/
    └── voice-dictionary.md           # Словарь оборотов {{OWNER_NAME}}

SKILL.md содержит: роль (пиши как {{OWNER_NAME}}), правила стиля (без канцелярита, дефис вместо тире), 3 примера постов. Детали (словарь из 50+ фраз) - в references/.

Триггер в description: "напиши пост", "пост для телеграм", "копирайтер".

Пример 2: Сложный скилл (deep-research-pro)

Структура:

skills/deep-research-pro/
└── SKILL.md                          # 130 строк: workflow из 5 шагов

Без references/ - весь workflow помещается в core. 5 шагов: уточнение → планирование → мультиисточниковый поиск → синтез → отчёт. Каждый шаг с конкретными командами.

Пример 3: Скилл с данными (auto-mechanic)

Структура:

skills/auto-mechanic/
├── SKILL.md                          # Роль + алгоритм диагностики
└── data/
    └── car-profile.md                # Профиль {{CAR_MODEL}}

Данные (VIN, одометр, история ТО) в data/ - крон не тронет. В SKILL.md только логика работы.

Пример 4: Полноценный рабочий агент (Team Lead)

Конфиг:

{ "id": "teamlead", "name": "Team Lead", "model": { "primary": "anthropic/claude-opus-4-6" },
  "workspace": "~/.openclaw/agents/teamlead/agent",
  "agentDir": "~/.openclaw/agents/teamlead/agent",
  "memorySearch": { "enabled": true },
  "heartbeat": { "every": "0" },
  "tools": { "deny": ["gateway"] } }

Полная структура workspace:

~/.openclaw/agents/teamlead/agent/
├── AGENTS.md          # Роль + прозрачность + скиллы + память + команда
├── SOUL.md            # Личность
├── USER.md            # Профиль владельца (GitHub, стек, стиль)
├── IDENTITY.md        # Имя и краткое описание
├── MEMORY.md          # Сводка фактов (проекты, инструменты)
├── TOOLS.md           # Реальные команды и пути
├── skills -> {{WORKSPACE_PATH}}skills  # Симлинк на общие скиллы
└── memory/
    ├── lessons.md         # Уроки и правила
    ├── patterns.md        # Паттерны правок
    ├── projects-log.md    # История задач
    └── architecture.md    # Самоописание

memorySearch включён - накапливает контекст между сессиями. Скиллы через симлинк. Система автоулучшения: ошибка → паттерн → правило.

Пример 5: Специализированный агент (Кайдзен - коуч)

{ "id": "kaizen", "model": "anthropic/claude-sonnet-4-6",
  "workspace": "obsidian/", "memorySearch": { "enabled": false } }

Другая архитектура - живёт в Obsidian vault. Память = сам vault (daily notes, [[wikilinks]], граф). Скиллы не нужны - работает с целями и привычками. Sonnet (дешевле) - для ежедневных чекинов достаточно.

Пример 6: Изолированный агент (Копирайтер - маска)

{ "id": "copywriter", "model": "anthropic/claude-sonnet-4-6",
  "memorySearch": { "enabled": false },
  "tools": { "deny": ["gateway", "cron", "exec"] } }

Максимально изолирован: нет exec, нет cron, нет gateway, нет памяти. Только текст. Подходит для ролей-масок в топиках (не полноценный агент, а роль через systemPrompt).

Материалы

• references/research-best-practices.md - ресёрч 10 платформ, 30+ скиллов
• references/checklist.md - подробные чеклисты
• references/competitive-analysis.md - сравнение с конкурентами

Поддержка после создания

Еженедельный Health Check

Скрипт: bash scripts/agent-health-check.sh Чеклист: references/weekly-health-checklist.md Крон: воскресенье 12:00 — автоматическая + ручная проверка.

Проверяет: файлы, симлинки, timeouts, пути, противоречия, вес контекста, данные под роль.

Автосинхронизация references/

Скрипт: bash scripts/sync-agent-references.sh Крон: ежедневно 06:00 — создаёт симлинки на новые файлы, удаляет битые.

07.03.2026, обновлено 15.03.2026 (симлинки USER.md/references, timeoutSeconds=120, health check, sync, данные под роль)