skill-tg: an engineering toolkit for Telegram bots

The same tasks kept coming up in my Telegram projects: a catalogue, entering a quantity, payment, a channel subscription, a mailing and returning to the menu. I collected these solutions into skill-tg, an installable Claude Code plugin plus a set of references that other coding agents can use too.

From experience to a reusable process

The main SKILL.md sets the order of work and points to the materials for a specific task. For a shop that means a minimal working scenario and interface rules, for payment it means invoices and webhooks, and for free text input it means dialogue states. Detailed schemas and examples live in separate reference files. This helps move from a user’s request to implementation and testing without loading every reference at once.

The set covers Python with aiogram 3 and Go with telebot: commands and deep links, RU/EN localisation, closed channels, mass mailings, group topics, message formatting, payments and operations. You can read them directly in the repository.

One scenario from catalogue to purchase

The minimal shop shows the whole path: /start → catalogue → card → choosing a quantity → an invoice in Telegram Stars → handling a successful payment.

The quantity on the buttons and the total in the text update together. The value for a button counter is passed in the callback, while a separate state is needed when the user types a number or a promo code. The FSM reference covers clearing state on completion and on going back, so the next plain text does not fall into an unfinished step.

Delivery in the minimal example is tied to a unique payment identifier. A repeat payment notification has to be recognised as an event already processed. This is a concrete pattern for handling repeats that can be checked separately from the interface.

Text and buttons are part of the product too

The instructions fix a heading, a short explanation and a clear primary action. Navigation sits in the last row, and names of repeated actions match between screens. An error or empty state has to offer a next step.

An important technical detail is keeping your own HTML template separate from inserted values. Names, user input and product titles are escaped, while the template markup keeps its formatting. Custom emoji have a fallback to regular characters until real identifiers and the required account features are set up.

The render() fragment from the minimal shop shows this order right in the code:

def render(tmpl, **v):
    return premiumize(
        tmpl.format(**{k: html.escape(str(x)) for k, x in v.items()}),
        config.PREMIUM_EMOJI,
    )

Values are inserted safely first, and emoji formatting is added after that.

How it relates to TelegramShop

TelegramShop is a separate public shop implementation on aiogram, SQLite and aiohttp. It shows onboarding with language selection, a catalogue, invoices, payment handlers and a single delivery function by purchase type.

External payment providers have their own confirmation handlers. The shop’s code verifies CryptoBot and xRocket signatures before parsing a notification. Catalogue and integration data in the template is configured per project.

Installation and result

In Claude Code the plugin is added from its own marketplace:

/plugin marketplace add suspectuso/skill-tg
/plugin install skill-tg@skill-tg

Another agent can use the skill folder with SKILL.md and the references. The repository has validators for structure and links, plus scenarios that check which requests the skill should trigger on. The references treat testing pure logic and testing in a real Telegram client separately: a correct object in code still needs its message, buttons and transitions checked on the user’s side.

The result is an open set of instructions, concrete examples and checks that carries experience from one bot to the next. It can be adapted to your stack and extended with any solution you keep repeating.

skill-tg code and installation · TelegramShop implementation