Autonomous Telegram-bot QA skill for Claude Code: Telethon-driven E2E dialogs, reply/keyboard snapshot testing, LLM-generated self-healing specs, Mini App bridge to web-qa
tg-qa defines 8 tools with complete input schemas and descriptions. Naming is action-verb-based (tg_send, tg_click, tg_history) and clear. Descriptions are present and contextual (avg ~120 chars), explaining WHAT each tool does and WHEN to use it. However, descriptions lack explicit guidance on error recovery, prerequisites, and dependencies between tools. Parameter descriptions are adequate but sparse, e.g., 'wait' lacks guidance on timeout behavior or retry semantics. Output schemas are partially documented in descriptions but not formally declared. No tool annotations (readOnlyHint/destructiveHint) despite clear risk levels (READ_ONLY vs WRITE). Error handling is implicit, no guidance on what to do if a message send fails or a media download times out. Composition is sound: tools chain naturally (send → click → history), and responses include IDs needed for follow-up calls. Security: role parameter enables multi-session isolation, but no explicit permission gates or audit trail documentation.
The bot's declared command menu (BotFather/setMyCommands) — a free seed for the bot map.
Click an inline button by message id + caption. Returns new replies AND the in-place edit of the clicked message if the bot updated it.
Download media from a bot message; returns the saved path (or null).
Recent dialog with the bot, oldest first — what the user actually sees.
Who the acting Telegram session is logged in as (sanity/auth check).
Send a text message to the bot under test and return its replies (each reply: id, text, buttons, media_type).
No tool annotations (readOnlyHint/destructiveHint/idempotentHint) despite explicit risk levels. tg_send, tg_click, tg_send_media are WRITE operations; tg_me, tg_history, tg_download_media, tg_bot_commands are READ_ONLY. Agents cannot distinguish safe from destructive calls without annotations.
Output schemas not formally documented. Descriptions mention return structure (e.g., 'each reply: id, text, buttons, media_type') but no JSON Schema definition. LLMs cannot reliably parse or chain results without explicit output type declarations.
Error handling guidance missing. No documentation of what happens on timeout (wait parameter), network failure, auth failure, or invalid button click. Descriptions lack recovery hints like 'If message not found, call tg_history() first.'
| Scored | Grade | Overall | Spec posture | Rubric |
|---|---|---|---|---|
| 2026-09-23 | D | 59 | 2026-07-28+ | v2 |
Send media of any kind and return the bot's replies. kind = photo | document | voice (гс, .ogg) | video_note (кружок, square .mp4) | sticker (.webp/.tgs) | video | audio | gif | auto (infer from the file).
Resolve a Mini App URL with LIVE tgWebAppData (initData) for the web-qa bridge. Experimental.
Parameter 'kind' in tg_send_media accepts free-form string with enum values listed in description only ('photo | document | voice | ...'). Should be declared as JSON Schema enum to prevent hallucinated values.
tg_webview_url marked 'Experimental' but no guidance on failure modes, expected response format, or when to use it vs other tools. Description too brief (60 chars) to guide LLM selection.