agent-forge

Category: Tools & Productivity | Uploader: AlekseiUL | Downloads: 0 | Version: v1.0（Latest）
Создание, улучшение и аудит скиллов и агентов OpenClaw. Три режима: создание скилла (11 шагов), создание агента (9 шагов, с памятью и автоулучшением), улучшение существующего (5 шагов). Triggers: 'создай скилл', 'новый скилл', 'создай агента', 'новый агент', 'улучши скилл', 'skill creator', 'agent creator', 'скиллмейкер'.
Changelog: Source: GitHub https://github.com/AlekseiUL/agentforge-openclaw
Directory Structure

Current level: Root
📁 examples/
- 📁 code-reviewer/
  - 📄 SKILL.md 3.1 KB
- 📁 content-planner/
  - 📁 references/
    
    📄 style-guide.md 1.7 KB
  - 📄 SKILL.md 3.5 KB
- 📁 meeting-prep/
  - 📄 SKILL.md 3.3 KB
- 📁 task-tracker/
  - 📁 data/
    
    📄 tasks.md 367 B
  - 📄 SKILL.md 2.5 KB
- 📁 weather-bot/
  - 📄 SKILL.md 1.6 KB
📁 references/
- 📄 agent-templates.md 13.1 KB
📄 banner.jpg 122.7 KB
📄 LICENSE 290 B
📄 README.md 5.5 KB
📄 SKILL.md 27.7 KB
SKILL.md

---
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/<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 вручную:
```bash
mkdir -p skills/<имя>/
```
Если установлен скилл skill-creator, можно автоматически: `python3 $(npm root -g)/openclaw/skills/skill-creator/scripts/init_skill.py <name> --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[])

Замени `<agent-id>` на id своего агента (латиница, без пробелов, например: `marketer`, `dev-lead`, `coach`).

```json
{
  "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. Связи

```json
"agentToAgent": { "enabled": true, "allow": ["main", "<agent-id>"] }
```
`sessions_send` ВСЕГДА с `timeoutSeconds=0`.

### Шаг 4. Binding (Telegram)

```json
{ "agentId": "<agent-id>", "match": { "channel": "telegram", "accountId": "<agent-id>" } }
```

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

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

```bash
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" текущего разговора | 🟡 Рекомендуется |

**Симлинк на общие скиллы (если нужны):**
```bash
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, грузится автоматически:
```markdown
# 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. Перезапуск

**Перед перезапуском - проверь конфиг:**
```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-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: Специализированный агент (коуч целей)

```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 шагов, память, автоулучшение, команда)*
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
agent-forge

Directory Structure

SKILL.md

Report

Notice
