| name | agent-forge |
| description | Создание, улучшение и аудит скиллов и агентов OpenClaw. Три режима: создание скилла (11 шагов), создание агента (9 шагов, с памятью и автоулучшением), улучшение существующего (5 шагов). Triggers: 'создай скилл', 'новый скилл', 'создай агента', 'новый агент', 'улучши скилл', 'skill creator', 'agent creator', 'скиллмейкер'. |
AgentForge 🔧
Создание и улучшение скиллов и агентов OpenClaw. Лучшие практики + боевой опыт с десятками скиллов и агентов. Агенты: от базового (5 мин) до полноценного рабочего (с памятью, автоулучшением, командой).
Шаблоны файлов агента: references/agent-templates.md
Быстрый старт
Скилл за 5 минут:
mkdir skills/<имя>/ → создать SKILL.md с frontmatter (name, description) + алгоритм + 2 примера- Готово. Скилл подхватится автоматически (hot-reload)
Агент за 5 минут:
- Добавить в
agents.list[] в openclaw.json (id, name, model, workspace, tools.deny)
mkdir -p ~/.openclaw/agents/<id>/agent + AGENTS.md с ролью- Перезапустить gateway (через config.patch или
openclaw gateway restart)
Нужно по шагам? Читай дальше.
Режим A: СКИЛЛ
Шаг 1. Онбординг (2-4 вопроса, по одному)
- Что скилл должен делать? Конкретный пример использования
- Когда активировать? (триггерные фразы)
- Нужны ли скрипты, данные, внешние API?
- Публичный (для подписчиков) или внутренний?
Шаг 2. Определи тип скилла
Workflow (пошаговый процесс) - если задача = последовательность действий.
→ Пример: deep-research-pro (5 шагов: уточнение → поиск → синтез → отчёт)
Role (экспертная роль) - если задача = "отвечай как специалист X".
→ Пример: copywriter (пиши как владелец, вот стиль, вот примеры)
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. Инициализация
Просто создай папку и SKILL.md вручную:
mkdir -p skills/<имя>/
Если установлен скилл skill-creator, можно автоматически: python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/init_skill.py <name> --path ~/skills/
Шаг 5. Написание SKILL.md
Frontmatter (обязательно):
---
name: имя-скилла
description: "Что делает + когда использовать. Triggers: 'фраза1', 'фраза2'."
---
Допустимые поля: name, description, allowed-tools, license, metadata. Поле version НЕ поддерживается!
5 принципов:
- Только уникальное - не пиши то, что модель и так знает
- Примеры > теория - один пример лучше абзаца объяснений
- Детали отдельно - основное в SKILL.md, подробности в
references/
- Триггеры в description - body грузится ПОСЛЕ триггера, "когда использовать" пиши в frontmatter
- Императив - "Найди", "Отправь", не "Можно найти"
Шаблон 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/<имя>/
Ручная проверка:
Шаг 8. Аудит безопасности (для публичных)
grep -ri "ваше-имя\|ваш-ник\|ваш-город\|ваш-id\|Desktop/ваша-папка" SKILL-public.md
Результат = 0 строк.
Чеклист: нет личных данных, нет локальных путей, нет внутренних названий, нет ключей/токенов, model-agnostic.
Шаг 9. Тест
- Вызвать скилл с реальным запросом
- Edge cases: пустой ввод, нестандартный запрос
- Если контент - проверить стиль
- Если команды - проверить зависимости
Шаг 10. Публичная версия (если нужна)
SKILL.md → SKILL-public.md → убрать личное → аудит повторно.
Шаг 11. Итерация
- владелец поправил → записать что не так
- 3+ повтора проблемы → добавить в скилл
- Хирургические правки, не переписывать всё
Режим B: АГЕНТ
Шаг 1. Онбординг (5 вопросов, по одному)
- Роль/задача агента? (маркетолог, тимлид, коуч...)
- Какие tools нужны? Какие запретить?
- Нужна ли векторная память (memorySearch)?
- Связь с другими агентами?
- Привязка: Telegram топик, отдельный бот, API?
Шаг 1a. Определи тип агента
Полноценный рабочий - свой бот, своя память, свои скиллы, система автоулучшения. Для долгосрочных ролей: тимлид, маркетолог, аналитик.
→ Все 9 шагов. Чеклист из 12 файлов. memorySearch: true.
Специализированный - своя экосистема (Obsidian, отдельная база). Для уникальных задач: коуч целей, трекер привычек.
→ Шаги 1-4 + 7-8. Workspace = своя среда. Файлы адаптировать.
Маска (топик-роль) - нет своего бота, работает через systemPrompt основного. Для экспертных ролей: врач, астролог, механик.
→ Только systemPrompt в конфиге группы/топика. Минимум файлов. tools.deny максимальный.
Шаг 2. Конфиг (openclaw.json → agents.list[])
Замени <agent-id> на id своего агента (латиница, без пробелов, например: marketer, dev-lead, coach).
{
"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=0.
Шаг 4. Binding (Telegram)
{ "agentId": "<agent-id>", "match": { "channel": "telegram", "accountId": "<agent-id>" } }
Для топика в группе:
"accounts": {
"<agent-id>": {
"botToken": "...",
"groups": { "<group-id>": { "topics": { "<topic-id>": { "requireMention": false } } } }
}
}
Шаг 5. Workspace - структура файлов
mkdir -p ~/.openclaw/agents/<agent-id>/agent/memory
Обязательные файлы (чеклист):
| Файл | Назначение | Обязательность |
|---|
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 | Самоописание агента (конфиг, связи, уровни памяти) | 🟡 Рекомендуется |
HEARTBEAT.md | Инструкции по heartbeat | 🟡 Если heartbeat включён |
BOOTSTRAP.md | Восстановление контекста после компактификации | 🟡 Рекомендуется |
memory/handoff.md | "Save game" текущего разговора | 🟡 Рекомендуется |
Симлинк на общие скиллы (если нужны):
ln -s ~/skills ~/.openclaw/agents/<agent-id>/agent/skills
Шаг 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 - самоописание агента
Ключевые принципы (знать без шаблонов):
- AGENTS.md - главный файл. Порядок секций: прозрачность → кто я → команда → скиллы → проекты → связи → память → инструменты → стиль
- USER.md - адаптировать под роль! Маркетологу - каналы и аудитория. Тимлиду - GitHub и стек. Личные данные - только если реально нужны
- SOUL.md - не копипаста. Каждый агент = своя личность. Принципы вытекают из роли
- Память - 4 уровня: контекстная → файловая → векторная → identity. Автоулучшение: ошибка → паттерн → 3 повтора → правило
- Длинные проекты - создавать
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. Не дублирует, только новое.
Пример крона Auto Handoff:
cron(action="add", job={
"name": "Auto Handoff",
"schedule": {"kind": "cron", "expr": "30 9-23 * * *", "tz": "ваша/таймзона"},
"sessionTarget": "isolated",
"payload": {
"kind": "agentTurn",
"model": "anthropic/claude-sonnet-4-6",
"message": "Прочитай sessions_history(sessionKey='agent:<id>:main', limit=30). Если есть свежие сообщения — перезапиши memory/handoff.md (тема, решения, TODO, контекст). Если неактивна — NO_REPLY.",
"timeoutSeconds": 120
},
"delivery": {"mode": "none"}
})
Когда добавлять: если агент общается с владельцем >1 часа в день и теряет контекст при обрезке. Для агентов с короткими задачами — не нужно, хватит memory/lessons.md.
Шаг 7. Перезапуск
Перед перезапуском - проверь конфиг:
openclaw status
Бэкап:
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
Перезапуск: openclaw gateway restart из терминала, или через gateway tool (config.patch автоматически рестартит).
⚠️ Если агент сам перезапустит gateway — он убьёт свою сессию. Перезапуск только из терминала или через координатора.
Если не поднялся - откат:
cp ~/.openclaw/openclaw.json.bak ~/.openclaw/openclaw.json
openclaw gateway restart
Шаг 8. Тест
- Отправь сообщение → получи ответ
- Проверь изоляцию: tools.deny работает? memorySearch только своё?
- Проверь связи: sessions_send доходит?
- Проверь прозрачность: пишет уведомления?
- Проверь память: при старте читает lessons/patterns/projects-log?
- Проверь скиллы: перед задачей читает SKILL.md?
Шаг 9. Выравнивание с командой
Если есть другие агенты - убедись что новый на том же уровне:
Режим C: УЛУЧШЕНИЕ СУЩЕСТВУЮЩЕГО
- Прочитай текущий SKILL.md - пойми что есть, какой тип, какая структура
- Определи проблему - конкретно: "нет примеров", "устарел алгоритм", "владелец поправил результат"
- Хирургическая правка - меняй только то, что сломано. Не переписывай весь скилл
- Проверь - валидация (шаг 7) + тест (шаг 9)
- Обнови публичную версию - если есть SKILL-public.md, синхронизируй
Когда улучшать: владелец поправил результат, 3+ повтора одной проблемы, появилась новая возможность/инструмент.
⛔ Когда НЕ создавать
Скилл не нужен если: задача одноразовая, нет повторяемости, модель и так знает.
Агент не нужен если: хватит маски (systemPrompt в топике), не нужна своя память, никто не будет пользоваться регулярно.
Миграция маска → полноценный агент:
Если маска начала: накапливать контекст между сессиями, нуждаться в своих файлах, требовать tools - пора переводить. Пройди все 9 шагов для полноценного агента.
⚠️ Грабли
Скиллы
| # | Проблема | Решение |
|---|
| 1 | Данные в memory/ | В skills/<имя>/data/ - крон не тронет |
| 2 | YAML без --- | Скилл молча игнорируется |
| 3 | Относительный путь к references | Полный: skills/<имя>/references/ |
| 4 | SKILL.md >500 строк | Детали в references/ |
| 5 | Нет триггеров | Агент не знает когда активировать |
| 6 | Утечка в публичной версии | grep перед публикацией |
| 7 | Зависимость от модели | Model-agnostic |
| 8 | Нет примеров | Бесполезен после компактификации |
Агенты
| # | Проблема | Решение |
|---|
| 1 | sessions_send с таймаутом | Всегда timeoutSeconds=0 |
| 2 | Нет в agentToAgent.allow | Связь молча фейлит |
| 3 | Алиас модели | Только полное имя |
| 4 | Workspace не создан | Агент падает |
| 5 | Нет tools.deny | Может рестартнуть gateway |
| 6 | Не перезапустил gateway | Старый конфиг |
| 7 | Binding без topicId | Ловит все сообщения |
| 8 | USER.md пустой шаблон | Агент не знает владельца - заполнить под роль |
| 9 | Нет MEMORY.md | Стартует вслепую каждую сессию |
| 10 | Нет memory/*.md файлов | Нет системы автоулучшения - не учится |
| 11 | Нет прозрачности | Владелец не видит что агент делает |
| 12 | Агент не знает команду | Не может делегировать/спросить коллегу |
| 13 | Описание привязано к проекту | Агент = член команды, не фрилансер на проект |
| 14 | Нет маршрутизации по скиллам | Работает "из головы" вместо скиллов |
Примеры из нашей системы
Пример 1: Простой скилл (копирайтер)
Структура:
skills/copywriter/
├── SKILL.md # 150 строк: роль + правила + примеры
└── references/
└── voice-dictionary.md # Словарь стиля
SKILL.md содержит: роль (пиши как владелец), правила стиля (без канцелярита, дефис вместо тире), 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 # Профиль автомобиль
Данные (VIN, одометр, история ТО) в data/ - крон не тронет. В SKILL.md только логика работы.
Пример 4: Полноценный рабочий агент (Team Lead)
Конфиг:
{ "id": "dev-lead", "name": "Team Lead", "model": "anthropic/claude-opus-4-6",
"workspace": "~/.openclaw/agents/<agent-id>/agent",
"agentDir": "~/.openclaw/agents/<agent-id>/agent",
"memorySearch": { "enabled": true },
"heartbeat": { "every": "0" },
"tools": { "deny": ["gateway"] } }
Полная структура workspace:
~/.openclaw/agents/<agent-id>/agent/
├── AGENTS.md # Роль + прозрачность + скиллы + память + команда
├── SOUL.md # Личность
├── USER.md # Профиль владельца (GitHub, стек, стиль)
├── IDENTITY.md # Имя и краткое описание
├── MEMORY.md # Сводка фактов (проекты, инструменты)
├── TOOLS.md # Реальные команды и пути
├── skills -> ~/skills # Симлинк на общие скиллы
└── memory/
├── lessons.md # Уроки и правила
├── patterns.md # Паттерны правок
├── projects-log.md # История задач
└── architecture.md # Самоописание
memorySearch включён - накапливает контекст между сессиями. Скиллы через симлинк. Система автоулучшения: ошибка → паттерн → правило.
Пример 5: Специализированный агент (коуч целей)
{ "id": "coach", "model": "anthropic/claude-sonnet-4-6",
"workspace": "~/.openclaw/agents/coach/agent", "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, нет памяти. Только текст. Подходит для простых экспертных ролей в топиках. Если нужна ещё проще маска без agents.list — используй systemPrompt прямо в конфиге группы/топика.
Материалы
references/agent-templates.md - готовые шаблоны всех файлов агента (AGENTS.md, SOUL.md, USER.md, BOOTSTRAP.md, handoff.md, memory/*.md)
07.03.2026, обновлено 09.03.2026 (добавлен полный пайплайн агентов: 9 шагов, память, автоулучшение, команда)
