К основному содержанию
скилл CX Codex

interactive-bot — скилл для Claude Code: Telegram-бот для Gmail

Скилл interactive-bot объясняет устройство Telegram-бота Gmail Commander: слэш-команды для почты, ИИ-роутинг свободного текста через MCP, сессии compose/reply.

MIT 114 установок ★ 3 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code
Открыть на GitHub

Что делает interactive-bot

Скилл документирует Telegram-бота, который даёт доступ к почте через команды /inbox, /search, /read, /compose, /reply и через свободные сообщения. Детерминистические команды вызывают Gmail CLI напрямую, свободный текст проходит через агента с четырьмя MCP-инструментами. Бот работает на приватном Restate-тенанте, импортирует buildBot() из scripts/bot.ts.

Внутри: scripts/lib/commands.ts с хендлерами команд, scripts/lib/agent-router.ts с MCP-роутингом, scripts/lib/callbacks.ts с inline-клавиатурами и хранилищем сессий, scripts/lib/telegram-format.ts с рендерингом писем. Защита: мьютекс на одновременный запрос агента, таймаут AGENT_TIMEOUT_MS (по умолчанию 2 минуты), circuit breaker на три сбоя подряд отключает агента на 10 минут, детекция загрязнения скилла в ответах агента.

Тестировать scripts/bot.ts с продакшен-токеном нельзя: Telegram разрешает один getUpdates-поллер на токен, второй вызовет 409 Conflict и сломает развёрнутый бот. Для теста используй отдельный токен или импортируй buildBot().

Какие задачи решает

  • объяснить, как устроен Telegram-бот для Gmail
  • показать, где лежат команды, MCP-роутинг и хендлеры клавиатур
  • предупредить о конфликте getUpdates при тестировании с продакшен-токеном
  • описать защиту агента: мьютекс, таймаут, circuit breaker

Примеры запросов агенту

  • Открой scripts/bot.ts и покажи, где buildBot() инициализирует grammY
  • Где в коде обрабатывается команда /compose?
  • Покажи, как агент-роутер вызывает MCP-инструменты в scripts/lib/agent-router.ts

Как установить interactive-bot

1Через Skills CLI (Vercel)

npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code

2Вручную: положить файлы

~/.claude/skills/interactive-bot/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/interactive-bot/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы об interactive-bot

Как установить interactive-bot в Claude Code?

Выполни npx skills add terrylica/cc-skills --skill interactive-bot -a claude-code, затем открой ~/.claude/skills/interactive-bot/SKILL.md.

Что делает interactive-bot?

Скилл документирует Telegram-бота Gmail Commander: слэш-команды для inbox, search, compose, reply и ИИ-роутинг свободного текста через MCP.

Почему нельзя тестировать scripts/bot.ts с продакшен-токеном?

Telegram разрешает один getUpdates-поллер на токен. Второй поллер вызовет 409 Conflict и сломает развёрнутый бот.

Исходный текст

SKILL.md · MIT
---
name: interactive-bot
description: Gmail Commander Telegram bot - slash commands, inline keyboards, compose and reply flow, AI free-text routing. Built by buildBot() in this plugin and run by a private Restate deployment. TRIGGERS - telegram bot, bot commands, inbox bot
allowed-tools: Read, Bash, Grep, Glob
---

# Interactive Bot

Gmail Commander Telegram bot — slash commands for email access + AI-powered free-text routing. This skill explains what the bot does and where its code lives; operating the running bot is covered by [bot-process-control](../bot-process-control/SKILL.md).

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Where it runs

The bot runs in a **private Restate tenant on an always-on Mac mini**. The tenant imports `buildBot()` from `scripts/bot.ts`, owns its own durable Telegram `getUpdates` chain, and feeds each update into the returned grammY bot through `bot.handleUpdate()`. There is no workstation daemon; the laptop launchd job was retired on 2026-09-24.

Do **not** start `scripts/bot.ts` directly with the production bot token to "test" it. Telegram allows one `getUpdates` consumer per token, so a second poller breaks the deployed bot with `409 Conflict`. Test against a separate bot token, or exercise the code by importing `buildBot()`.

## Mandatory Preflight

### Step 1: Check the bot code exists and still exports `buildBot`

```bash
PLUGIN="$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-commander"
ls -la "$PLUGIN/scripts/bot.ts" 2>/dev/null || echo "SCRIPT_NOT_FOUND"
grep -n "export async function buildBot" "$PLUGIN/scripts/bot.ts" || echo "buildBot EXPORT MISSING — the deployment depends on it"
```

## Bot Commands (Sidebar Menu)

| Command  | Description                             |
| -------- | --------------------------------------- |
| /inbox   | Show recent inbox emails                |
| /search  | Search emails (Gmail query syntax)      |
| /read    | Read email by ID                        |
| /compose | Compose a new email                     |
| /reply   | Reply to an email                       |
| /abort   | Cancel current compose/reply action     |
| /drafts  | List draft emails                       |
| /digest  | Triage the last N hours now (default 6) |
| /status  | Bot status and stats                    |
| /help    | Show all commands                       |

## Two-Tier Command System

**Tier 1 — Deterministic**: Slash commands call the Gmail CLI directly (through `scripts/lib/gmail-client.ts`, which runs the binary named by `GMAIL_CLI_BIN`).

**Tier 2 — Intelligent**: Free-text messages route through the Agent SDK (`HAIKU_MODEL`) with 4 Gmail MCP tools (list, search, read, draft).

## Safety Controls

- **Mutex**: 1 agent query at a time
- **Timeout**: `AGENT_TIMEOUT_MS` per query (2-minute default)
- **Circuit Breaker**: 3 failures in a row disables the agent for 10 minutes
- **Anti-contamination**: Skill contamination detection on all agent responses
- **Auth Guard**: Only responds to the authorized `TELEGRAM_CHAT_ID`

## Source Map

| Concern                                  | File                                                                     |
| ---------------------------------------- | ------------------------------------------------------------------------ |
| Wiring, compose/reply session flow       | [`scripts/bot.ts`](../../scripts/bot.ts) (`buildBot()`)                  |
| Command list and handlers                | [`scripts/lib/commands.ts`](../../scripts/lib/commands.ts)               |
| Inline-keyboard callbacks, session store | [`scripts/lib/callbacks.ts`](../../scripts/lib/callbacks.ts)             |
| Free-text routing, MCP tools             | [`scripts/lib/agent-router.ts`](../../scripts/lib/agent-router.ts)       |
| Email rendering, HTML escaping           | [`scripts/lib/telegram-format.ts`](../../scripts/lib/telegram-format.ts) |
| Message chunking (4096-char limit)       | [`scripts/lib/telegram-chunk.ts`](../../scripts/lib/telegram-chunk.ts)   |

## Post-Change Checklist

- [ ] YAML frontmatter valid (no colons in description)
- [ ] Trigger keywords current
- [ ] Path patterns use $HOME not hardcoded paths
- [ ] `buildBot()` still starts no transport and takes no PID lock on import

## Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. **Locate yourself.** — Find this SKILL.md's canonical path before editing.
1. **What failed?** — Fix the instruction that caused it.
2. **What worked better than expected?** — Promote to recommended practice.
3. **What drifted?** — Fix any script, reference, or dependency that no longer matches reality.
4. **Log it.** — Evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind.

© terrylica · MIT · terrylica/cc-skills

Похожие скиллы

Все скиллы по теме «Telegram-боты» →

Из того же набора79

Весь набор →
project-directory-migration Скилл project-directory-migration переносит сессии, историю и контекст Claude Code, когда вы переименовываете или перемещаете папку проекта. Работает в интерактивном режиме с dry-run проверкой и откатом. CX Codex +1 119установок infra-deploy Скилл infra-deploy разворачивает self-hosted Cal.com в GCP Cloud Run с базой Supabase PostgreSQL или поднимает его локально через Docker Compose. CX Codex +1 119установок email-triage Скилл email-triage для Claude Code сортирует недавние письма Gmail по трём категориям и уровням срочности. Разбирает входящие по запросу через команду бота /digest. CX Codex +1 117установок bot-process-control Скилл bot-process-control регламентирует мониторинг процессов Gmail Commander и защищает от запуска конфликтующих локальных поллеров Telegram на рабочей станции. CX Codex +1 117установок symmetric-dogfooding Скилл symmetric-dogfooding организует двустороннее интеграционное тестирование между двумя репозиториями перед релизом без использования моков. CX Codex +1 112установок calcom-access Скилл calcom-access для Claude Code и пяти других платформ даёт агенту доступ к Cal.com API для работы с бронированиями, типами событий, расписаниями и доступностью слотов. Ключ API берётся из 1Password через CALCOM_OP_UUID. CX Codex +1 107установок claude-code-proxy-patterns Скилл claude-code-proxy-patterns описывает схемы прокси для маршрутизации моделей Claude Code к разным провайдерам. Пригодится при настройке OAuth и разборе ошибок авторизации. CX Codex +1 106установок summarize Скилл summarize разбирает многогигабайтные текстовые файлы и записи сессий пошагово, не загружая их целиком в контекст. Помогает понять, что произошло в длинной сессии разработки, когда файл слишком большой для обычного чтения. CX Codex +1 103установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой