Telegram user

Skill bgevorkian/agent-skills/skills/telegram-user

Reusable open-source Agent Skills for Pi and compatible agent systems

Install

npx -y skills add bgevorkian/agent-skills --skill telegram-user

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

13 days oldThe repository was created 13 days ago. New is not bad, but a brand new repository carrying a familiar-sounding name is the shape a typosquat arrives in, and there has been no time for anyone else to find a problem with it.
0 stars0 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Use Telethon against a user's own Telegram account through a UTF-8 JSON CLI for login, status, profile, dialogs, messages, search, saved messages, folders, contacts, and guarded mutations. Configure only with TELEGRAM_API_ID, TELEGRAM_API_HASH, and TELEGRAM_SESSION_FILE.

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

3.5 KB, as published. Nobody here has run it

Telegram User

Generic Telegram user-account skill built on Telethon. It uses only environment-based configuration, prints UTF-8 JSON, keeps login explicit and interactive, and blocks writes unless both gates are enabled.

Configuration

Variable	Required	Default
`TELEGRAM_API_ID`	for all network commands	none
`TELEGRAM_API_HASH`	for all network commands	none
`TELEGRAM_SESSION_FILE`	no	platform user-data path
`TELEGRAM_ALLOW_WRITE`	no	`false`

Default session path:

Windows: %APPDATA%/telegram-user/telethon.session
Linux/macOS: $XDG_DATA_HOME/telegram-user/telethon.session or ~/.local/share/telegram-user/telethon.session

Never commit session files or secrets.

Secret setup

Before configuring API credentials, ask which secret manager and local profile the user wants. Follow Secure secret profiles. Do not invent or publish profile names or secret references. Treat the Telethon session as a separate credential file with private permissions. If the user asks for the author's method, use process-scoped pass-cli run for environment credentials. Never request or display resolved values or session contents.

Run

From this skill directory:

uv run --python 3.13 --with telethon python scripts/tg.py status
uv run --python 3.13 --with telethon python scripts/tg.py login
uv run --python 3.13 --with telethon python scripts/tg.py me
uv run --python 3.13 --with telethon python scripts/tg.py dialogs --limit 50
uv run --python 3.13 --with telethon python scripts/tg.py messages me --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py search "invoice" --chat me --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py saved messages --limit 20
uv run --python 3.13 --with telethon python scripts/tg.py folders list
uv run --python 3.13 --with telethon python scripts/tg.py contacts list --limit 100
uv run --python 3.13 --with telethon python scripts/tg.py raw messages.GetDialogFiltersRequest '{}'

Optional wrapper:

uv run --python 3.13 --with telethon python scripts/login.py

Use --help on the root command or any subcommand.

Write gate

These commands mutate Telegram state and require both:

TELEGRAM_ALLOW_WRITE=true
--confirm-write

Guarded operations:

send, edit, delete
saved send
folders add-peers, folders remove-peers, folders set-title
contacts add, contacts delete
raw when the method is not confidently read-only

Read commands do not require the gate.

Notes

Login never prints codes, API hashes, session bytes, or secrets.
Prompts are written to stderr so stdout stays machine-readable JSON.
raw accepts inline JSON, @file.json, or - for stdin.
Complex raw arguments may use Telethon-style type objects such as {"_":"InputPeerSelf"}.

Tests

uv run --python 3.13 --with telethon python tests/test_tg.py