Telegram Skills — 15 навыков, чтобы AI-агент научился работать с Telegram

· 6 мин чтения
telegram ai-agents skills bots bot-api
📂 Исходный код на GitHub

Набор из 15 навыков для AI-агентов: отправка rich-сообщений с таблицами и медиа, стриминг ответов LLM, опросы, HTML-виджеты, стикерпаки, запуск Mini App с проверкой пользователя и продажа товаров за Stars. Каждый навык работает с Bot API по обычному HTTP.

Telegram Skills — 15 навыков, чтобы AI-агент научился работать с Telegram

Навык для агента (Agent Skills) — это папка с файлом SKILL.md, которая учит AI-агента делать одну конкретную работу. Проект Telegram Skills — библиотека таких навыков, собранная вокруг одного домена: Telegram. Внутри 15 навыков. Они научат агента отправлять сообщения с таблицами и галереями, стримить ответы модели в чат, запускать опросы, выпускать стикерпаки, собирать Mini App и принимать оплату за Stars. Все навыки работают с Bot API через обычный HTTP, поэтому бот-фреймворк не нужен.

Идея простая. Обычно для бота вы пишете код: библиотека, обработчики, экранирование разметки, загрузка файлов. Здесь вместо кода агенту дают справочник. Агент сам читает нужный навык, сам собирает HTTP-запрос к Bot API и сам соблюдает лимиты Telegram.

Навыки подходят любому агенту, который умеет читать SKILL.md: Claude Code, Codex CLI, Cursor и другим.

Что такое rich-сообщения

Основа библиотеки — новая возможность самого Telegram. Обычное сообщение бота — это текст с простой разметкой. Rich-сообщение собирается из блоков, как документ: внутри могут быть таблицы, галереи, карты и сворачиваемые секции.

Появились такие сообщения в Bot API 10.1 (11 июня 2026). Тогда же бот научился стримить ответы AI в чат с блоком «мышления». Дальше формат рос:

  • Bot API 10.2 (14 июля 2026) — JSON-описание блоков и явная привязка медиа: Telegram file_id, ссылки по HTTP, загрузка файлов на лету.
  • Bot API 10.3 (24 августа 2026) — нативные кнопки в rich-сообщениях и компактные таблицы. Кнопки красятся в стили primary, success и danger.
  • Опросы (Bot API 9.1–10.1) — до 12 вариантов и описание до 1024 символов с медиа, поэтому пост и опрос к нему помещаются в одно сообщение.

Библиотека собирает эти возможности в готовые рецепты: что писать агенту, какие лимиты соблюдать и как проверять сообщение перед отправкой. Проверка перед отправкой (preflight) описана в базовом навыке tg-rich-messages: там же — разметка, JSON блоков, привязка и загрузка медиа, лимиты и сама отправка запроса по HTTP. Это ядро библиотеки, остальные навыки на него опираются.

Пятнадцать навыков

Сообщения

tg-rich-messages — базовый справочник по rich-сообщениям: разметка, JSON блоков, привязка и загрузка медиа, проверка перед отправкой, лимиты. С него стоит начинать.

tg-markdown-to-rich — превращает обычный Markdown в rich-сообщение и подключает к нему медиа.

tg-classic-messages — обычные сообщения бота: лимиты, экранирование HTML и MarkdownV2, цитаты, превью ссылок, подписи, альбомы, размеры загрузок, редактирование и удаление. Плюс руководство, когда вместо классики лучше взять rich.

tg-rich-streaming — стримит ответ LLM в чат как живой текст: обычные и rich-черновики, блок «мышления», кнопка остановки, обязательная финализация в конце.

tg-rich-digest — шаблоны дайджестов и статей для каналов: плоская вёрстка, короткое превью со свёрнутой полной версией, медиа как доказательство.

tg-reply-rewrite — переписывает сырой ответ агента для человека без технических знаний, который читает с телефона: что случилось и насколько срочно, что это значит, готовая фраза для ответа. Каждый факт остаётся без изменений.

tg-operator-cards — карточки, которые бот шлёт своему оператору о событиях: платёж, заказ, запись на услугу. Итог и имя человека в первой строке, один факт в строке, предупреждение на месте проблемной строки, в конце — что нужно решить.

Интерактив

tg-polls — опросы и квизы от имени бота или обычного аккаунта: текст и опрос в одном сообщении через описание, до 12 вариантов, все настройки опросов, чтение результатов.

tg-widgets — интерактивные HTML-виджеты прямо в сообщении: как писать их по документации Telegram, лимиты, ввод данных, состояние, в какие чаты виджет дойдёт в продакшене.

tg-sticker-pack — выпуск стикерпаков из кадра мема или видео: вырезание фигуры, подпись сверху, офлайн-проверка формата, публикация через @Stickers или через createNewStickerSet.

tg-miniapp-launch-auth — открытие Mini App и проверка пользователя: пути запуска, startapp, проверка initData через HMAC и Ed25519, ограничение по версии клиента, защита по origin, тестовое окружение.

tg-miniapp-ui — интерфейс Mini App: тема, безопасные зоны, полноэкранный режим, нижние кнопки, хаптика, производительность и известные баги клиента на каждой платформе.

Деньги и эксплуатация

tg-stars-payments — продажа цифровых товаров за Stars из бота или Mini App: инвойсы, подтверждение перед оплатой, выдача товара с защитой от двойной выдачи, возвраты, подписки, платные медиа.

tg-capability-map — карта возможностей: что умеет бот, что живёт только в клиенте или MTProto и что обещать пользователю нельзя. Каждая строка датирована.

tg-bot-ops — эксплуатация бота: webhook или polling, фильтр allowed_updates, секретный токен, лимиты 429 и retry_after, повторные отправки файлов, потерянные обновления и обновления, из-за которых обработка падает, сбои t.me, локальный сервер Bot API.

Типичные сценарии

Навыки комбинируются между собой. Несколько примеров из описаний самой библиотеки:

  • Агент закончил работу и сам отправил отчёт в ваш Telegram-канал как rich-сообщение — с таблицей результатов и свёрнутой подробной частью.
  • Канал с дайджестом: короткое превью сверху, полная версия спрятана под сворачиваемую секцию, медиа служат доказательствами.
  • Бот-магазин: клиент платит за Stars, бот выдает товар ровно один раз, а оператору уходит карточка о заказе — итог в первой строке.
  • Поддержка: агент отвечает стримом как живой текст, с блоком «мышления» и кнопкой остановки. В конце сырой ответ переписывается для клиента простыми словами.

Отдельная забота библиотеки — не обещать лишнего. Навык tg-capability-map прямо перечисляет, что бот умеет, а что доступно только самому клиенту Telegram. Это помогает агенту честно отвечать на вопросы о возможностях.

Установка

Универсальный способ — через npx:

npx skills add serejaris/telegram-skills

Один навык отдельно:

npx skills add serejaris/telegram-skills --skill tg-rich-messages

Claude Code — через встроенный маркетплейс:

/plugin marketplace add serejaris/telegram-skills
/plugin install telegram-skills@telegram-skills

Ручное копирование:

# Claude Code
cp -r skills/* ~/.claude/skills/

# Codex CLI and other agents
cp -r skills/* ~/.agents/skills/

# Per-project
cp -r skills/* your-project/.claude/skills/
cp -r skills/* your-project/.agents/skills/

Отдельная деталь: внутри клона этого репозитория навыки подхватываются автоматически — они лежат в каталоге .agents/skills/.

После установки достаточно попросить агента обычными словами: «отправь этот отчёт в мой Telegram-канал как rich-сообщение».

Дополнительно

Лицензия — MIT.

Источник: https://github.com/serejaris/telegram-skills