home / skills / terrylica / cc-skills / interactive-bot

interactive-bot skill

safe

/plugins/gmail-commander/skills/interactive-bot

This skill lets you manage Gmail via Telegram with slash commands and AI routing for fast inbox access and email composing.

npx playbooks add skill terrylica/cc-skills --skill interactive-bot

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.5 KB

---
name: interactive-bot
description: Gmail Commander Telegram bot with slash commands, inline keyboards, and AI routing. TRIGGERS - telegram bot, bot commands, inbox bot, email bot, start bot, stop bot, compose email via telegram.
allowed-tools: Read, Bash, Grep, Glob
---

# Interactive Bot

Gmail Commander Telegram bot — slash commands for email access + AI-powered free-text routing.

## Mandatory Preflight

### Step 1: Check Bot Script Exists

```bash
ls -la "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-commander/scripts/bot.ts" 2>/dev/null || echo "SCRIPT_NOT_FOUND"
```

### Step 2: Verify Environment

```bash
echo "TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN:+SET}"
echo "TELEGRAM_CHAT_ID: ${TELEGRAM_CHAT_ID:-NOT_SET}"
echo "GMAIL_OP_UUID: ${GMAIL_OP_UUID:-NOT_SET}"
echo "HAIKU_MODEL: ${HAIKU_MODEL:-NOT_SET}"
```

## Bot Commands (Sidebar Menu)

| Command  | Description                        |
| -------- | ---------------------------------- |
| /inbox   | Show recent inbox emails           |
| /search  | Search emails (Gmail query syntax) |
| /read    | Read email by ID                   |
| /compose | Compose a new email                |
| /reply   | Reply to an email                  |
| /drafts  | List draft emails                  |
| /digest  | Run email digest now               |
| /status  | Bot status and stats               |
| /help    | Show all commands                  |

## Two-Tier Command System

**Tier 1 — Deterministic**: Slash commands call Gmail CLI directly.

**Tier 2 — Intelligent**: Free-text messages route through Agent SDK (Haiku) with 4 Gmail MCP tools (list, search, read, draft).

## Safety Controls

- **Mutex**: 1 agent query at a time
- **Timeout**: 2-minute maximum per query
- **Circuit Breaker**: 3 failures in a row disables agent for 10 minutes
- **Anti-contamination**: Skill contamination detection on all agent responses
- **Auth Guard**: Only responds to authorized TELEGRAM_CHAT_ID

## Running Manually

```bash
cd ~/own/amonic && bun run "$HOME/.claude/plugins/marketplaces/cc-skills/plugins/gmail-commander/scripts/bot.ts"
```

## References

- [command-reference.md](./references/command-reference.md) — All commands with examples
- [compose-flow.md](./references/compose-flow.md) — Multi-step compose/reply state machine
- [display-patterns.md](./references/display-patterns.md) — Email rendering rules

## Post-Change Checklist

- [ ] YAML frontmatter valid (no colons in description)
- [ ] Trigger keywords current
- [ ] Path patterns use $HOME not hardcoded paths

Overview

This skill provides a Gmail Commander Telegram bot that exposes slash commands, inline keyboards, and AI-powered free-text routing to manage Gmail from Telegram. It combines deterministic CLI commands for fast operations with an intelligent agent layer for natural-language requests and routing. Built for secure, single-chat operation with safety controls to prevent misuse.

How this skill works

The bot exposes a set of slash commands (inbox, search, read, compose, reply, drafts, digest, status, help) that call Gmail tools directly for predictable results. Free-text messages are routed through an agent SDK (Haiku) which can call Gmail MCP tools (list, search, read, draft) and return structured responses. Built-in guards enforce single-agent mutex, per-query timeouts, circuit breaking, contamination detection, and chat-ID-based authorization.

When to use it

Quickly view recent inbox items and drafts from Telegram
Search Gmail with Gmail query syntax without leaving chat
Read or reply to specific messages using message IDs
Compose new emails via a guided multi-step flow
Use natural-language requests to summarize, search, or route emails via the AI agent

Best practices

Ensure TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are set before starting the bot
Use slash commands for deterministic tasks and free-text for summaries or complex routing
Keep the authorized TELEGRAM_CHAT_ID restricted to trusted accounts
Monitor circuit-breaker and agent failure logs to avoid unexpected downtime
Run the mandatory preflight checks and validate environment variables before launch

Example use cases

/inbox to scan the latest messages when away from desktop
Type “summarize my unread messages” to have the agent produce a digest
/search "label:project from:alice" to find project emails quickly
/compose to start a multi-step guided email creation and send flow
/read <message-id> to display a specific email with consistent rendering rules

FAQ

How does authorization work?

The bot verifies TELEGRAM_CHAT_ID and only responds to that ID; keep that variable set to your trusted chat to prevent unauthorized access.

What happens if the agent fails repeatedly?

A circuit breaker disables the agent for 10 minutes after three consecutive failures; deterministic slash commands remain available during that period.