skill-telegram

Единственный Telegram-скилл, который нужен вашему AI-агенту.

Читай сообщения. Парси каналы. Скачивай голосовые заметки. Одна сессия, никаких ботов.

Зачем это нужно

Ваш AI-агент не умеет читать Telegram. Он не может проверить сохранённые сообщения, спарсить отраслевые каналы или обработать голосовые заметки, записанные на ходу. Этот скилл даёт ему прямой доступ через Telegram User API — так же, как вы сами используете Telegram, а не через ограниченного бота.

Один файл сессии. Все ваши чаты. JSON-вывод, который подключается к чему угодно.

Возможности

• Чтение любого чата — Избранное, личные переписки, группы, публичные каналы → JSON-строки
• Парсинг каналов в масштабе — несколько каналов, фильтрация по дате, очищенный вывод с защитой от инъекций
• Скачивание голосовых заметок — аудиофайлы + метаданные, готовы к транскрибации
• Встроенная диагностика — одна команда проверяет переменные окружения, сессию, зависимости и подключение
• Портативность — работает из любой директории. Сессия обнаруживается автоматически или указывается явно

Быстрая установка

Claude Code (рекомендуется):

Вручную:

# Скопируйте скилл в ваш проект
git clone https://github.com/awrshift/skill-telegram.git
cp -r skill-telegram .claude/skills/telegram

Настройка (5 минут)

Шаг 1: Получите учётные данные Telegram API

1. Перейдите на https://my.telegram.org/apps
2. Войдите с номером телефона
3. Создайте приложение (любое название и описание)
4. Скопируйте api_id и api_hash

Шаг 2: Настройте окружение

Добавьте в файл .env:

TG_API_ID=12345678
TG_API_HASH=your_api_hash_here

Шаг 3: Установите зависимость

Шаг 4: Авторизуйтесь

Введите номер телефона → получите код в Telegram → введите код. Готово. Файл сессии создаётся автоматически.

Шаг 5: Проверьте установку

Все проверки должны показать [ OK ].

Использование

Формат вывода

Все скрипты выводят JSON-строки (один JSON-объект на строку):

{"id": 265894, "date": "2026-03-19T09:42:48+00:00", "text": "Message content here", "has_voice": false, "has_photo": false}

Парсер каналов добавляет санитизацию:

{"channel": "SEOBAZA", "id": 1546, "date": "2026-03-19T03:29:34+00:00", "text": "Original", "text_sanitized": "Cleaned", "links": ["https://..."], "hash": "64e9a72207ed56d4", "views": 1403}

Скрипты

Итого: 770 строк. Никаких фреймворков, никаких тяжёлых зависимостей. Только Telethon + stdlib.

Поиск файла сессии

Скилл находит файл сессии автоматически по следующему приоритету:

1. --session /path/to/file (флаг CLI, наивысший приоритет)
2. Переменная окружения TG_SESSION
3. .claude/data/telegram/tg_session.session (уровень проекта)
4. ~/.telegram/tg_session.session (глобальный)

Безопасность

• User API — вы авторизуетесь как пользователь, а не как бот
• Файл сессии = ваша личность — храните его как пароль
• Только чтение — скилл никогда не отправляет сообщения
• Санитизация — парсер каналов удаляет невидимые символы, инъекции через бэктики, избыточные эмодзи
• Без хранения данных — вывод в stdout/файл, никаких баз данных и облака

Важные нюансы

• Первая авторизация интерактивна — нужно один раз ввести телефон и код
• Одна сессия одновременно — не запускайте два скрипта с одной сессией параллельно
• Ограничения частоты запросов — Telegram замедляет интенсивное использование (обрабатывается автоматически с задержками)
• Скачивание голосовых ≠ транскрибация — скилл скачивает аудио. Используйте Whisper/mlx-whisper для транскрибации
• User API ≠ Bot API — используется ваш аккаунт, видно то, что видите вы

Совместимость

Часть экосистемы AWRSHIFT

• skill-awrshift — фреймворк адаптивного принятия решений
• skill-brainstorm — состязательный брейншторм Claude × Gemini в 3 раунда
• ClawClaw Soul — протокол постоянной идентичности для AI-агентов

Участие в разработке

1. Сделайте форк репозитория
2. Создайте ветку с новой функциональностью
3. Отправьте pull request

Лицензия

MIT — подробности в файле LICENSE.