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/operations.md
View on GitHub# Operations
Read for routes 6–8 and deployment/migration handoffs. Source: [CLI reference](https://core.telegram.org/bots/serverless#command-line-interface). Commands below mean the already installed project-local CLI, normally `npx tgcloud` or the project's documented equivalent.
## Effects and state
| Command | Main effect |
| ------------ | -------------------------------------------------------------------------------------------------- |
| diff | Offline comparison against the last synchronized cloud snapshot |
| status | Compare the snapshot and, when credentials exist, query live webhook state |
| fetch | Read deployed state and refresh local CLI metadata; preserve working source files |
| run | Upload local modules and execute remotely; application/API/database effects are possible |
| push | Change deployed modules/static files |
| migrate | Inspect and potentially change the live database; dry-run applies nothing |
| pull | Replace working modules with deployed versions; preserve the static build folder |
| reset | Discard working module edits in favor of the last known snapshot; preserve the static build folder |
| webhook | Inspect live webhook state |
| webhook sync | Change routing and allowed_updates; drop-pending also discards queued updates |
| upgrade | Move legacy local layout; dry-run previews moves |
`status` is not an offline-only command: CLI 0.2.0 calls authenticated `GET /webhook` when a saved token or `TGCLOUD_TOKEN` is available. It silently ignores webhook lookup failures; a successful status command does not prove that no network request was attempted. See the [CLI 0.2.0 implementation](https://registry.npmjs.org/@tgcloud/cli/-/cli-0.2.0.tgz) and recheck the installed CLI before relying on a different version's behavior.
Init/add/login/completion are covered in [setup](setup.md). Do not label fetch as having no local effects: it updates CLI-owned metadata. Never edit that state manually.
## Validate and test
Start with the requested evidence level. An offline-only request prohibits status, login, fetch, webhook queries, remote run, push, and migrations. Use diff against the cached snapshot or inspect local files instead; do not remove credentials or change CLI state to make status appear offline. Do not silently install a CLI to inspect a project.
Check module layout, imports, syntax, schema usage, ownership predicates, frontend scripts/output, and sensitive-file exclusion. Node syntax checks can check JS parsing but do not execute the platform SDK. Mocks can prove application decisions, not Telegram authentication, schema enforcement, or service behavior.
For authorized remote tests, identify the bot, data/API effects, and test input before running. A dedicated disposable bot is preferable when effects need isolation; don't assume run creates one.
Examples of invocation shape, not instructions to execute during a review:
```sh
npx tgcloud run handlers/message '{ chat: { id: 123 }, text: "/start" }'
npx tgcloud run handlers/message '{}' --ctx '{ update: { update_id: 10 } }'
npx tgcloud run endpoints/getNote '{ noteId: 1 }' --ctx '{ initData: { user: { id: 123 } } }'
```
Replace synthetic IDs with an authorized target only for an actual test. Inputs and context must be objects, not arrays/null/scalars. A bare runnable name is ambiguous if both handlers and endpoints define it; use its qualified path. The platform executes the local module set, including local libraries, without publishing it.
Do not include secrets in JSON arguments or logs. Capture actual return/log/error evidence. Supplying an arbitrary user through run context tests application logic, not the platform's init-data verification.
## Deploy
1. Inspect working changes, intended module/static scope, and known cloud revision. If current remote state is needed and authorized, fetch and inspect the divergence before publishing.
2. For an existing bot, preserve remote modules not part of the task. A new/minimal local directory is not sufficient evidence that a full push is safe.
3. Build the frontend first when static files are in scope. Review the output folder and config, including accidental removal or stale artifacts.
4. Show the concrete change and effects. Reuse existing deployment authority for this exact target/scope; otherwise obtain it after preparing the change.
5. Use a full push only for an intended full-project mirror. A targeted push changes only named modules and does not delete unrelated modules. Static-only push targets the configured build folder.
6. Record the successful revision/result. Inspect pending schema changes separately; pushing schema is not a migration.
7. Inspect webhook/static behavior when the authorized task requires live verification. Report checks not performed.
A schema-only push, authorized migration, then dependent handlers/endpoints can avoid activating code before an additive schema is ready. See [database](database.md) for destructive/manual cases.
## Concurrency and recovery
The platform checks cloud revisions. A rejected push is evidence of divergence, not permission for force. Fetch refreshes the comparison base; that does not itself merge remote changes into local source or make a subsequent full push safe.
Preserve local changes and compare both sides before a pull or manual reconciliation. Pull writes source; reset restores the cached snapshot and is not a fresh cloud fetch. Never use either as an automatic conflict resolver. Stop after a rejected operation to inspect its cause instead of retrying with weaker safeguards.
To roll back code, review the previously known-good module/static content against the current cloud state and deploy the authorized rollback scope. A local reset alone does not roll back the cloud. Code rollback cannot restore database deletions; require a verified data recovery plan for that operation.
## Webhook diagnosis
Inspect the platform-managed webhook's URL, allowed_updates, pending count, last delivery error, and sync state. Confirm handler existence/content and the required update type. Do not set a custom webhook URL for this platform.
Adding/removing handlers can require webhook sync. Its normal path retains pending updates; `--drop-pending` intentionally discards them and needs specific authority. A diagnosis-only request reports the repair without executing it.
## Legacy upgrade
Inspect the actual installed CLI and layout. For pre-tgcloud projects, preview `upgrade --dry-run`, preserve local work, and apply only an authorized move. The documented upgrade retains the bot link and does not require redeployment. Inspect the resulting tree and diff; do not turn a local layout upgrade into a push.
## Outcome
Record actual local, remote-run, deploy, migration, webhook, and static results independently. Most failures are nonzero, but migration can exit successfully while manual/skipped work remains. Missing live evidence remains unverified. Do not invent a production log command, backup operation, quota, or recovery API.
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 |