--- name: agent-forge description: "Создание, улучшение и аудит скиллов и агентов OpenClaw. Три режима: создание скилла (11 шагов), создание агента (9 шагов, с памятью и автоулучшением), улучшение существующего (5 шагов). Triggers: 'создай скилл', 'новый скилл', 'создай агента', 'новый агент', 'улучши скилл', 'skill creator', 'agent creator', 'скиллмейкер'." --- # 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//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 вручную: ```bash mkdir -p skills/<имя>/ ``` Если установлен скилл skill-creator, можно автоматически: `python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/init_skill.py --path ~/skills/` ### Шаг 5. Написание SKILL.md **Frontmatter (обязательно):** ```yaml --- 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. Проверка качества ```bash python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/quick_validate.py skills/<имя>/ ``` Ручная проверка: - [ ] Работает без внешних знаний (self-contained) - [ ] Примеры реалистичные - [ ] Нет TODO, заглушек - [ ] Размер адекватный задаче - [ ] Триггеры покрывают варианты обращения ### Шаг 8. Аудит безопасности (для публичных) ```bash 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[]) Замени `` на id своего агента (латиница, без пробелов, например: `marketer`, `dev-lead`, `coach`). ```json { "id": "", "name": "Имя Агента", "model": "anthropic/claude-sonnet-4-6", "workspace": "~/.openclaw/agents//agent", "agentDir": "~/.openclaw/agents//agent", "memorySearch": { "enabled": true }, "heartbeat": { "every": "0" }, "tools": { "deny": ["gateway"] } } ``` - `model`: ПОЛНОЕ имя, не алиас - `memorySearch`: true для рабочих агентов (накапливают контекст) - `tools.deny`: `gateway` ВСЕГДА; `cron`, `exec` по ситуации - `heartbeat.every`: "0" если не нужен мониторинг ### Шаг 3. Связи ```json # В openclaw.json → секция "tools" (НЕ в agents!): "tools": { "agentToAgent": { "enabled": true, "allow": ["main", ""] } } ``` `sessions_send` ВСЕГДА с `timeoutSeconds=0`. ### Шаг 4. Binding (Telegram) ```json { "agentId": "", "match": { "channel": "telegram", "accountId": "" } } ``` Для топика в группе: ```json "accounts": { "": { "botToken": "...", "groups": { "": { "topics": { "": { "requireMention": false } } } } } } ``` ### Шаг 5. Workspace - структура файлов ```bash mkdir -p ~/.openclaw/agents//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" текущего разговора | 🟡 Рекомендуется | **Симлинк на общие скиллы (если нужны):** ```bash ln -s ~/skills ~/.openclaw/agents//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//sessions/` - удалять >30 дней - SQLite общая база - чистка кроновых чанков уже работает для всех Если используется `night-cleanup.sh` с wildcard `~/.openclaw/agents/*/sessions/` - новый агент подхватится автоматически. ### Шаг 6b. Автоматическая память (для рабочих агентов) Если агент ведёт длинные сессии с владельцем — добавь автоматическое сохранение контекста. Без этого при компактификации теряется 30-50% текущего разговора. **BOOTSTRAP.md** — кладётся в workspace, грузится автоматически: ```markdown # BOOTSTRAP.md После старта/компактификации: 1. read memory/handoff.md — текущий контекст ("save game") 2. read memory/YYYY-MM-DD.md — дневник дня 3. Если оба пустые: sessions_history(sessionKey="agent::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::main', limit=30). Если есть свежие сообщения — перезапиши memory/handoff.md (тема, решения, TODO, контекст). Если неактивна — NO_REPLY.", "timeoutSeconds": 120 }, "delivery": {"mode": "none"} }) ``` **Когда добавлять:** если агент общается с владельцем >1 часа в день и теряет контекст при обрезке. Для агентов с короткими задачами — не нужно, хватит `memory/lessons.md`. ### Шаг 7. Перезапуск **Перед перезапуском - проверь конфиг:** ```bash openclaw status ``` **Бэкап:** ```bash cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak ``` **Перезапуск:** `openclaw gateway restart` из терминала, или через gateway tool (config.patch автоматически рестартит). ⚠️ Если агент сам перезапустит gateway — он убьёт свою сессию. Перезапуск только из терминала или через координатора. **Если не поднялся - откат:** ```bash 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) Конфиг: ```json { "id": "dev-lead", "name": "Team Lead", "model": "anthropic/claude-opus-4-6", "workspace": "~/.openclaw/agents//agent", "agentDir": "~/.openclaw/agents//agent", "memorySearch": { "enabled": true }, "heartbeat": { "every": "0" }, "tools": { "deny": ["gateway"] } } ``` Полная структура workspace: ``` ~/.openclaw/agents//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: Специализированный агент (коуч целей) ```json { "id": "coach", "model": "anthropic/claude-sonnet-4-6", "workspace": "~/.openclaw/agents/coach/agent", "memorySearch": { "enabled": false } } ``` Другая архитектура - живёт в Obsidian vault. Память = сам vault (daily notes, [[wikilinks]], граф). Скиллы не нужны - работает с целями и привычками. Sonnet (дешевле) - для ежедневных чекинов достаточно. ### Пример 6: Изолированный агент (Копирайтер - маска) ```json { "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 шагов, память, автоулучшение, команда)*