AgentForge 🔧

Создание и улучшение скиллов и агентов OpenClaw. Лучшие практики + боевой опыт с десятками скиллов и агентов. Агенты: от базового (5 мин) до полноценного рабочего (с памятью, автоулучшением, командой).

Шаблоны файлов агента: references/agent-templates.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 -p ~/.openclaw/agents/<id>/agent + AGENTS.md с ролью
3. Перезапустить gateway (через config.patch или openclaw gateway restart)

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

---

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

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

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

Шаг 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 принципов:

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 "ваше-имя\|ваш-ник\|ваш-город\|ваш-id\|Desktop/ваша-папка" SKILL-public.md

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

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

Шаг 9. Тест

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

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

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

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

• владелец поправил → записать что не так
• 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[])

Замени <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. Связи

"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 - самоописание агента

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

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. Не дублирует, только новое.

Пример крона 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. Тест

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 других агентов (добавить нового в таблицу команды)

---

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

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