telegram-doctor - SKILL.md Agent Skill

name: telegram-doctor description: "Diagnose Telegram configuration and connectivity issues. Use when user reports problems with Telegram sync, connection errors, or wants to troubleshoot."

Telegram Doctor

Diagnose configuration and connectivity issues with Telegram integration.

When to Use

User says "Telegram not working" or "diagnose Telegram"
User reports connection or authentication errors
User says "check Telegram setup" or "troubleshoot Telegram"
Before asking for help with Telegram issues
When sync or other Telegram commands fail unexpectedly

How to Execute

python ${CLAUDE_PLUGIN_ROOT}/tools/telegram_doctor.py

What It Checks

Environment file - .env exists in cwd
API ID - TELEGRAM_API_ID is set and numeric
API hash - TELEGRAM_API_HASH is set
Session string - TELEGRAM_SESSION is set and valid length
Authentication - Credentials can connect to Telegram API
Config file - config/agents.yaml exists and is valid YAML
Group configured - A default group is selected
Data directory - data/ is writable

Output

Displays results with:

✓ for passed checks
✗ for failed checks

For each failure, provides a suggested fix that the user can run manually.

Important: This tool only diagnoses issues - it does not modify any files.

Example Output

telegram-doctor results:

  ✓ Environment file (.env found)
  ✓ API ID (12345678)
  ✓ API hash (abc123...xyz9)
  ✗ Session string (Session appears too short)
  ✗ Config file (config/agents.yaml not found)
  ✗ Group configured (No default group set)
  ✓ Data directory (./data)

Some checks failed. Suggested fixes:

  • Session string:
    Generate a fresh session: python scripts/generate_session.py

  • Config file:
    Run telegram-init to create the config file

  • Group configured:
    Run telegram-init to select a group

(Run these steps manually - doctor does not modify files)

Next Steps

After fixing issues:

Run telegram-init to reconfigure if needed
Run telegram-sync to test connectivity