alekseiul/agent-builder

🤖 Agent Builder — Создатель Persistent Agent-ов

Когда использовать

Пользователь говорит:

• "Создай агента X"
• "Новый агент для Y"
• "Сделай persistent agent Z"
• Описывает задачу агента который должен:
  • Помнить контекст между разговорами
  • Вести структурированные записи
  • Иметь специализированную экспертизу

Не использовать

• Простые одноразовые скиллы без памяти
• Skills.sh скиллы (brainstorming, debugging и т.д.)
• Субагенты для параллелизации (это другое)

Процесс создания

1. Собери требования

Спроси владельца:

Обязательные:

• Имя агента (slug-format, напр. auto-mechanic)
• Роль/экспертиза (напр. "Автомеханик для Mazda CX-5")
• Триггеры (слова активации, напр. "машина", "масло", "ТО")

Опциональные:

• Кого/что обслуживает (напр. "Mazda CX-5 2019, 120K км")
• Какие данные хранить (напр. "журнал ТО", "пробег", "замены")
• Стиль общения (напр. "технический", "дружелюбный")
• Референсы (примеры ответов, стиль письма)

2. Создай структуру

~/.claude/skills/<agent-name>/
├── SKILL.md                    # триггеры + инструкции
├── data/
│   ├── profile.md             # статический профиль (кто/что)
│   └── events/
│       └── log.md             # хронология событий
└── references/                # примеры, стиль (опционально)
    └── examples.md

3. Сгенерируй SKILL.md

Шаблон:

---
name: <agent-name>
trigger:
  - <trigger1>
  - <trigger2>
  - ...
description: >
  <краткое описание: кто, для кого, что делает>
---

# <Emoji> <Agent Title>

## Активация

При триггере:
1. Прочитай профиль: `data/profile.md`
2. Прочитай последние события: `data/events/log.md` (последние 10 записей)
3. Ответь как <роль>

## Роль

Ты — **<Agent Name>**, <детальное описание экспертизы>.

<Стандарты работы, если нужны>

Язык: русский. Тон: <стиль общения>.

## Профиль

Полная информация в `data/profile.md`.

## Автофиксация (ОБЯЗАТЕЛЬНО)

После КАЖДОГО взаимодействия с пользователем:

1. **Проверь чеклист:**
   - ✅ Новая информация требующая записи? (диагноз, событие, дата, замена, покупка)
   - ✅ Изменение существующих данных? (вес, пробег, статус, прогресс)
   - ❌ Простой вопрос без новой информации

2. **Если ✅ → ОБЯЗАТЕЛЬНО запиши:**
   - В `data/events/log.md` (хронология событий)
   - Обнови `data/profile.md` (если изменились постоянные данные)

3. **Формат записи в log.md:**
   ```markdown
   ## YYYY-MM-DD — [Субъект]: [Событие]
   - **Что:** краткое описание
   - **Детали:** конкретика (пробег, вес, дата, стоимость)
   - **Действия:** что было сделано/рекомендовано

4. Используй Edit tool:
   • НЕ используй Write (перезапишет файл целиком)
   • Используй Edit для дописывания в конец:

   Edit data/events/log.md
   old_string: (последняя строка файла)
   new_string: (последняя строка + \n\n## YYYY-MM-DD — [Субъект]: [Событие]\n- **Что:** ...)
   

Это НЕ опционально. Если информация соответствует чеклисту - запись ОБЯЗАТЕЛЬНА.

Примеры работы

Вопрос

"Когда менять масло?"

Процесс

1. Read data/profile.md → узнаю интервал замены (10K км)
2. Read data/events/log.md → последняя замена 115K км
3. Текущий пробег из профиля → 120K км
4. Ответ: "Пора менять! Последняя замена была 5K км назад"

Запись события

Пользователь: "Поменял масло сегодня, пробег 120500"

Дописываю в data/events/log.md:

## 2026-03-01
- **Замена масла**: 120500 км, Castrol Edge 5W-40, 4.5 л
- Стоимость: 80 GEL

Автоматическая запись

Используй Edit tool:

Edit data/events/log.md
old_string: (последняя строка файла)
new_string: (последняя строка + \n\n## YYYY-MM-DD\n- **Событие**: детали)

Не используй Write (перезапишет файл целиком).

---

Workflow создания агента

Когда Пользователь говорит "создай агента X":

Шаг 1: Собери информацию

Спроси через AskUserQuestion:

questions: [
  {
    question: "Как назвать агента? (slug-format, напр. auto-mechanic)",
    header: "Agent Name",
    options: [
      { label: "auto-mechanic", description: "Автомеханик" },
      { label: "tax-advisor", description: "Налоговый советник" },
      { label: "recipe-keeper", description: "Хранитель рецептов" },
      { label: "Другое", description: "Свой вариант" }
    ]
  },
  {
    question: "Какая роль/экспертиза?",
    header: "Role",
    options: [
      { label: "Эксперт", description: "Технический эксперт" },
      { label: "Советник", description: "Дружелюбный советник" },
      { label: "Журналист", description: "Фиксирует факты" }
    ]
  },
  {
    question: "Какие данные хранить?",
    header: "Data",
    multiSelect: true,
    options: [
      { label: "Профиль объекта", description: "Характеристики (машина, человек и т.д.)" },
      { label: "Журнал событий", description: "Хронология (ТО, покупки, изменения)" },
      { label: "Примеры/референсы", description: "Образцы текстов, стиль" }
    ]
  }
]

Шаг 2: Создай структуру

mkdir -p ~/.claude/skills/<agent-name>/data/events
mkdir -p ~/.claude/skills/<agent-name>/references

Шаг 3: Сгенерируй файлы

SKILL.md — используй шаблон выше, подставь:

• <agent-name>
• Триггеры (попроси у владельца или предложи 5-7 релевантных)
• Роль и экспертизу
• ОБЯЗАТЕЛЬНО блок "Автофиксация (ОБЯЗАТЕЛЬНО)" со специфичным чеклистом для агента
• Инструкции по data-файлам

data/profile.md — создай заготовку:

# <Agent Title> — Профиль

## Основная информация
- **Название**: <объект>
- **Характеристики**: <детали>

## <Специфичные разделы>
(зависит от типа агента)

data/events/log.md — пустой файл с заголовком:

# Журнал событий — <Agent Name>

(События будут добавляться автоматически)

references/examples.md (опционально):

# Примеры и референсы

## Стиль общения
<примеры ответов>

## Образцы текстов
<если нужно>

Шаг 4: Подтверди создание

Покажи владельцу структуру:

✅ Создан агент: <name>
📁 Структура:
   ~/.claude/skills/<name>/
   ├── SKILL.md (триггеры, инструкции)
   ├── data/
   │   ├── profile.md (заполни вручную)
   │   └── events/log.md (автозапись)
   └── references/ (опционально)

🎯 Активация: <триггеры>
📝 Заполни profile.md вручную или дай мне информацию

Шаг 5: Первое наполнение

Если Пользователь даёт информацию сразу:

• Заполни profile.md структурированно
• Если есть первое событие → запиши в log.md

---

Примеры агентов

AutoMechanic (Автомеханик)

Чеклист автофиксации для AutoMechanic:

✅ Записывать:
- Пробег на дату обслуживания
- Замена масла/фильтров/резины
- Ремонт (что сломалось, что заменили, стоимость)
- Покупка запчастей
- Визит на СТО

❌ НЕ записывать:
- "Когда менять масло?" (общий вопрос)
- "Что входит в ТО-2?" (справка)

Профиль (data/profile.md):

# 🚗 Автомобиль

- **Марка/Модель**: Mazda CX-5 2019
- **VIN**: JMXXXXXXXXXXXXXXX
- **Пробег текущий**: 120500 км (на 01.03.2026)
- **Двигатель**: 2.5L SKYACTIV-G
- **Коробка**: 6AT

## Регламент ТО
- Масло: каждые 10K км (Castrol Edge 5W-40, 4.5 л)
- Фильтр воздушный: каждые 20K км
- Тормозная жидкость: каждые 2 года
...

События (data/events/log.md):

## 2026-03-01 — Mazda CX-5: Замена масла
- **Что:** Плановое ТО
- **Детали:** 120500 км, Castrol Edge 5W-40, 4.5 л
- **Действия:** Замена масла и масляного фильтра, стоимость 80 GEL

## 2025-12-15 — Mazda CX-5: Замена аккумулятора
- **Что:** Аварийная замена
- **Детали:** Varta Blue 70Ah, старый 5 лет, не держал заряд зимой
- **Действия:** Замена аккумулятора, стоимость 180 GEL

## 2025-10-20 — Mazda CX-5: Замена масла
- **Что:** Плановое ТО
- **Детали:** 110200 км, Castrol Edge 5W-40, 4.5 л
- **Действия:** Замена масла и масляного фильтра, стоимость 75 GEL

CopywriterStyle (Стиль копирайтера)

Профиль (data/profile.md):

# ✍️ Стиль владельца

## Принципы
- Короткие предложения
- Без воды и лишних слов
- Прямо в суть
- Живой разговорный язык
- Мат приветствуется

Примеры (references/examples.md):

## Пример поста (хороший)
<текст поста>

## Пример поста (плохой)
<что НЕ делать>

---

Интеграция с memory.sqlite

Агент работает гибридно:

1. MD-файлы = структурированное хранение (профиль, события)
2. memory.sqlite = быстрый поиск по всем разговорам

Когда записываешь событие:

// 1. Дописать в MD
Edit("data/events/log.md", ...)

// 2. Сохранить в память
storeMemory("Замена масла 120500 км, 01.03.2026", "episodic", "auto-mechanic")

Это даёт:

• ✅ Хронологию в MD (читабельно, структурировано)
• ✅ Поиск в SQLite (быстро, semantic search)
• ✅ Лучшее из двух миров