skill-tg: инженерный набор для Telegram-ботов
Плагин для разработки Telegram-ботов: платежи, подписки, рассылки и безопасные интеграции.
В Telegram-проектах регулярно повторялись одни и те же задачи: каталог, ввод количества, оплата, подписка на канал, рассылка и возврат в меню. Я собрал эти решения в skill-tg — устанавливаемый плагин для Claude Code и набор справочников, которыми могут пользоваться другие агенты разработки.
Из опыта в переиспользуемый процесс
Основной SKILL.md задаёт порядок работы и направляет к материалам конкретной задачи. Для магазина это минимальный рабочий сценарий и правила интерфейса; для оплаты — счета и вебхуки; для свободного ввода — состояния диалога. Подробные схемы и примеры хранятся в отдельных reference-файлах. Такой порядок помогает перейти от запроса пользователя к реализации и проверке, не загружая все справки одновременно.
В наборе есть решения для Python с aiogram 3 и Go с telebot: команды и deep links, RU/EN-локализация, закрытые каналы, массовые рассылки, темы групп, форматирование сообщений, платежи и эксплуатация. Их можно прочитать непосредственно в репозитории.
Один сценарий от каталога до покупки
Минимальный магазин показывает целый путь: /start → каталог → карточка → выбор количества → счёт в Telegram Stars → обработка успешной оплаты.
Количество в кнопках и сумма в тексте обновляются вместе. Значение для кнопочного счётчика передаётся в callback; отдельное состояние нужно для сценария, где пользователь сам вводит число или промокод. Справка по FSM разбирает очистку состояния при завершении и возврате, чтобы следующий обычный текст не попадал в незаконченный шаг.
Выдача в минимальном примере привязана к уникальному идентификатору платежа. Повторное уведомление об оплате должно распознаваться как уже обработанное событие. Это конкретный образец обработки повторов, который можно проверить отдельно от интерфейса.
Текст и кнопки тоже часть продукта
В инструкции зафиксированы заголовок, короткое объяснение и понятное главное действие. Навигация находится в последнем ряду, названия повторяющихся действий согласованы между экранами. Для ошибки и пустого состояния нужен следующий доступный шаг.
Важная техническая деталь — разделение собственного HTML-шаблона и вставляемых значений. Имена, пользовательский ввод и названия товаров экранируются; разметка шаблона сохраняет оформление. Для custom emoji предусмотрен вариант с обычными символами, пока реальные идентификаторы и необходимые возможности аккаунта не настроены.
Фрагмент render() из минимального магазина показывает этот порядок прямо в коде:
1
2
3
4
5
def render(tmpl, **v):
return premiumize(
tmpl.format(**{k: html.escape(str(x)) for k, x in v.items()}),
config.PREMIUM_EMOJI,
)
Сначала безопасно подставляются значения, затем добавляется оформление emoji.
Как это связано с TelegramShop
TelegramShop — отдельная публичная реализация магазина на aiogram, SQLite и aiohttp. В ней можно посмотреть onboarding с выбором языка, каталог, счета, платежные обработчики и единую функцию выдачи по виду покупки.
У внешних платежных провайдеров свои обработчики подтверждения. В коде магазина видна проверка подписей CryptoBot и xRocket перед разбором уведомления. Данные каталога и интеграций в шаблоне настраиваются под конкретный проект.
Подключение и результат
В Claude Code плагин подключается из собственного marketplace:
1
2
/plugin marketplace add suspectuso/skill-tg
/plugin install skill-tg@skill-tg
Для другого агента можно использовать папку навыка с SKILL.md и справками. В репозитории есть валидаторы структуры и ссылок, а также сценарии проверки того, на какие запросы навык должен срабатывать. Проверку чистой логики и проверку в настоящем Telegram-клиенте справочники рассматривают отдельно: корректный объект в коде ещё требует проверки сообщения, кнопок и переходов у пользователя.
Результат — открытый набор инструкций, конкретных примеров и проверок, который переносит опыт между ботами. Его можно адаптировать под свой стек и дополнить повторяющимся решением.