How to use the Telegram Channel Setup agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file that gives an agent instructions for a specific task. When a request matches the skill's description, the agent follows those instructions. This skill's folder contains a single file, SKILL.md.

This skill handles the Telegram channel. When you paste a bot token from BotFather, the agent saves it to a local .env file and locks that file so only your user can read it. It then reviews the access list, shows who is allowed to message the bot, explains any pending pairing codes and checks channel status.

• Saves the bot token to <state-dir>/.env, updating only the TELEGRAM_BOT_TOKEN line and keeping other keys.
• Runs chmod 600 on the .env file, since the token is a credential.
• Reads access.json and reports the DM policy, allowed senders and pending pairings.
• Recommends switching to an allowlist so only known Telegram user IDs can reach the assistant.
• Can clear the saved token when you ask it to.

Install the configure skill

Download the ZIP for this skill from this page. Then install it using one of the two methods below.

For Claude Code, unzip the file into ~/.claude/skills/ to make it available in all your projects, or into a project's .claude/skills/ folder to limit it to that project. For the Claude apps, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into the project's .claude/skills/ folder
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Get a bot token from BotFather

You need a Telegram account and a bot token. Create the bot with BotFather in Telegram, which gives you a token. BotFather tokens look like 123456789:AAH followed by a long string, with a numeric prefix, a colon and then the rest.

The skill also needs Claude Code or another agent runtime that supports the Telegram channel plugin.

Trigger the skill with natural requests

You do not need a special command. The skill activates when you paste a Telegram bot token, ask to configure Telegram, ask how to set this up, ask who can reach you, or ask to check channel status.

The skill also responds to the slash form /telegram:configure. Pass the token after it to save the token, or run it with no arguments to see status.

• "Here is my Telegram bot token: 123456789:AAH..."
• "How do I set up Telegram?"
• "Who can reach me through the bot?"
• "Check whether my Telegram channel is configured."
• "Clear the saved Telegram token."

Review status and lock down access

With no arguments, the skill reads the token status and access.json. If no file exists, it treats the channel as not configured, which is not an error. It then gives one next step based on state: save a token, DM your bot to get a pairing code, or start using the bot.

The skill's stated goal is an allowlist with a defined list of Telegram user IDs. Pairing is a temporary way to capture IDs you do not know yet. Once everyone who should have access is listed, the skill offers to switch the policy to allowlist. To add someone later, you can briefly switch to pairing, have them DM the bot, approve them and switch back.

• Pairing: the bot replies to a DM with a code. Approve it with /telegram:access pair <code>.
• Allowlist: only the listed numeric Telegram user IDs can reach the assistant.
• Ask a new user for their numeric ID by having them message @userinfobot.

Know the restart and safety rules

The server reads .env once at boot. After you save or change a token, restart the session or run /reload-plugins. The skill tells you this after saving.

access.json is re-read on every inbound message, so policy changes made with /telegram:access take effect immediately without a restart.

The bot token is stored in plain text in .env. The only protection is file permissions, so do not use this skill if you do not trust a local file to hold a credential. The skill does not run scripts and does not use the network. Its allowed tools are Read, Write, and limited Bash commands for ls, mkdir, echo and chmod.

• The state directory defaults to ~/.claude/channels/telegram but can be overridden with TELEGRAM_STATE_DIR or CLAUDE_CONFIG_DIR.
• Do not share the .env file or paste the full token into places others can see.