stark-ai-de/agent-skills / plugins/stark-ai-developer/skills/telegram-serverless
telegram-serverless
VerifiedBuild, review, deploy, and troubleshoot bots and Mini Apps on Telegram Serverless using tgcloud, its JavaScript SDK, and built-in database. Use when working on Telegram-hosted projects, handlers, endpoints, schema changes, or tgcloud operations; not generic Telegram bots hosted elsewhere or unrelated serverless platforms.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.7 KB |
| agents/openai.yaml | config | 530 B |
| assets/openai-icon.png | binary | 7.7 KB |
| assets/openai-icon.svg | other | 708 B |
| references/database.md | markdown | 6.2 KB |
| references/mini-apps.md | markdown | 6.4 KB |
| references/operations.md | markdown | 7.4 KB |
| references/runtime-sdk.md | markdown | 4.4 KB |
| references/setup.md | markdown | 3.8 KB |
| references/sources.md | markdown | 13.1 KB |
references/setup.md
View on GitHub# Setup and authentication
Read for route 2, or for a prerequisite/layout problem in route 8. Authoritative sources: [getting started](https://core.telegram.org/bots/serverless#getting-started), [authentication](https://core.telegram.org/bots/serverless#authentication), [BotFather](https://core.telegram.org/bots/serverless#on-the-go-with-botfather).
## Preflight
Identify the target folder, its Git state, existing instructions, package manager, installed Node.js, and installed `@tgcloud/cli` version. Use the package's actual engine constraint; the documented minimum is not a recommendation to replace a maintained local toolchain. Check the existing local binary/package metadata before invoking `npx`, which may install a missing package.
The bot owner must enable Serverless in BotFather. The skill does not infer this from a local package or automatically operate the owner's Telegram account.
## Create or adopt a project
The official creator is `npm create @tgcloud/bot <folder>`; the installed CLI also provides `tgcloud init` in the target root. Respect project package-management rules. These commands write project files and can install dependencies; use them only for authorized setup.
For an existing frontend, add Serverless in that frontend's root. The creator/init preserves existing files, adds the backend and docs, and may add a build-then-push deploy script if one is absent. Inspect the resulting diff and actual scripts; do not assume an existing `deploy` script has the expected behavior.
Expected backend layout:
```text
tgcloud/
schema.js
handlers/message.js
endpoints/getProfile.js
lib/format.js
tgcloud.jsonc
```
Handlers and endpoints are flat. Only lib may be nested. The scaffold also provides an SDK guide and project instructions; preserve existing instructions. Init refuses nested projects and can fill missing files when repeated at the same root.
Use `tgcloud add handlers/<update_type>`, `endpoints/<identifier>`, or `lib/<path>` for a new module. It refuses overwrite; the active default export becomes live after deployment. Use the CLI's advertised handler types rather than a frozen list.
A legacy layout has schema/lib/handlers at the root. Inspect `tgcloud upgrade --dry-run`, then use the authorized upgrade only after preserving local work. Do not manually move CLI state.
## Link the bot without exposing credentials
The Serverless CLI access token from BotFather → bot → Serverless → CLI Access is distinct from the Bot API token. The owner enters it in their interactive terminal using the installed `tgcloud login`. Do not ask them to paste it into chat or run it through a recorded argument.
For CI, use an already authorized secret injection to populate `TGCLOUD_TOKEN`. It takes precedence over saved login credentials. Never display the value while diagnosing which source is in use. The CLI owns `.tgcloud/`; verify it is ignored without opening its credentials.
Login validates the token and synchronizes local CLI state. Missing or invalid credentials require an explicit login path; do not invent a token flag or manually patch state. Authentication does not establish authority to deploy or migrate.
The CLI token authenticates the local developer tool. It is not a documented credential mechanism inside backend modules. Never put it in the frontend.
## BotFather and local clients
BotFather exposes handlers, endpoints, libraries, schema/database changes, static files, and CLI access for the same cloud project. Changes made there can cause local/cloud divergence. Inspect before synchronizing; local presence is not evidence of current deployment.
Shell completion is optional. The documented completion command prints bash/zsh/fish setup for a bare `tgcloud` binary; it does not hook into `npx`. Do not install a global CLI or rewrite shell configuration solely to add completion unless requested.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |