Skip to content
Skills Library
Personal productivity · Tool integration

send-message

/send-message

Use when the user wants to send a Telegram text message as their personal account via MTProto, to a contact by username, phone number or chat ID.

Repository
cc-skills ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user wants to send a Telegram text message as their personal account via MTProto, to a contact by username, phone number or chat ID.

Original author description

Use when the user wants to send a Telegram text message as their personal account via MTProto, to a contact by username, phone number or chat ID.

How it works

  1. Preflight
  2. Supergroup-First Methodology
  3. Auto-split for long messages
  4. Session-reference footer (automatic — project policy)
  5. Usage: tg-cli.ts (when session is valid)
  6. Telegram HTML Formatting Reference
  7. Profiles
  8. Known Group Chat IDs
  9. Topic Registry (Bruntwork Supergroup)
  10. Anti-Patterns (NEVER DO)
Original SKILL.md headings · 225 lines, 1,965 words
SKILL.md preview
---
name: send-message
description: "Use when the user wants to send a Telegram text message as their personal account via MTProto, to a contact by username, phone number or chat ID."
allowed-tools: Bash, Read, Grep, Glob
---

# Send Telegram Message

Send a message from your personal Telegram account (not a bot) via MTProto.

> **Self-Evolving Skill**: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

## Preflight

Before sending, verify the session is **authorized** (not just that the file exists):

```bash
bun "$SCRIPT" check-auth
```

If `EXPIRED`, run `/tlg:setup` first (uses 3-step non-interactive auth pattern).

## Supergroup-First Methodology

The Bruntwork group (`-1003958083153`) is a **supergroup with Topics**. All messages to this group MUST target a specific topic — never post to the bare supergroup without a topic target.

**Why supergroup over basic chat:**

- **Server-global message IDs.** Every member sees the same `id=N` for each message. Both sides' Claude Code resolves citations identically — no viewer-qualifier needed, no cross-boundary ambiguity.
- **Topic namespaces.** Policies don't get buried between daily check-ins. Each subject has its own searchable thread with independent pins.
- **AI-agent addressability.** Claude Code can target reads/writes to specific topics via `reply_to_msg_id`, enabling precise routing: "post this bug report to Bug Reports" or "search Policies for the carve-out decision."
- **Emoji reactions as acknowledgment signals.** Reactions are programmatically readable via `message.reactions.results` — enables lightweight ACK checking without requiring a text reply.

**Topic selection discipline:** When composing a message, select the most specific topic from the Topic Registry below. Use General only as a fallback. Never cross-post the same message to multiple topics.

**Citation convention:** Bare `id=N` citations resolve identically for every member. When referencing a prior message, cite its ID. Claude Code on both sides can look it up autonomously via `client.get_messages(supergroup_id, ids=N)`.

**Sending to a topic via tg-cli.ts:** use the `--reply-to` flag with the topic's root_msg_id. See the Topic Registry section below for root_msg_id values.

```bash
bun "$SCRIPT" send --html --reply-to 5 -1003958083153 "<b>Policy update</b> ..."
```

## Auto-split for long messages

Telegram's hard limit is 4096 post-parsing chars per message. **tg-cli.ts `send` and `draft` both auto-split** messages exceeding ~3900 plain chars into multiple sequential posts, preserving HTML formatting and section structure.

**Split algorithm**: splits at the finest-grained safe boundary that fits all chunks:

1. `\n\n━━━━━━━━━━━━━━\n\n` (major section separator, preferred)
2. `\n━━━━━━━━━━━━━━\n` (section separator)
3. `\n\n` (paragraph break)
4. `\n` (line break)
5. Hard character split (last resort — prints warning; may break tags)

Each continuation chunk gets a `<i>(Part N/M)</i>` header prepended so recipients see the sequence clearly. All parts share the same `--reply-to` target so a multi-part post stays in one topic thread.

**You do NOT need to manually split messages anymore.** Compose the full HTML as one string, pass to `send`, and the splitter handles it.

**Size-aware authoring guidance**: prefer messages that fit in one post (≤ 3900 plain chars) — splits add visual overhead with part headers. If a message is naturally larger (e.g., a pinned reference), let the splitter do its job. Structure with `━━━━━━━━━━━━━━` separators so split boundaries land cleanly between logical sections.

## Session-reference footer (automatic — project policy)

Every `send` (and every `send-file` caption and `draft`) automatically gets a session-reference footer appended, so the Telegram history doubles as a provenance trail. You do not add it by hand. It applies to all recipients, and rides the last chunk of a split message. Format:

```
------
via Claude Code | session <uuid> | <context> | <timestamp>
```

- `<uuid>` is `CLAUDE_CODE_SESSION_ID` (dropped if unset); `<context>` is included only when you pass `--context` (never auto-filled from the working directory, which would disclose a folder name to recipients).
- **`--context "<label>"`** adds an optional context label (e.g. `--context "project / contact"`).
- **`--no-footer`** opts out — use it for an external or sensitive chat, or a message whose provenance must not travel (e.g. relaying a one-time code).
- Content already carrying a Claude Code footer (e.g. piped straight from `draft-park get`, whose marker reads `Parked by Claude Code …`) is **not** re-stamped, so its own marker survives.

SSoT for the logic: `scripts/session-footer.ts` (unit tests in `scripts/session-footer.test.ts`).

## Usage: tg-cli.ts (when session is valid)

> **When in doubt, USE `--html`.** If your message contains ANY of: `<b>`, `<i>`, `<code>`, `<pre>`, `<a href>`, bold headers, inline code, or markdown-style `**bold**` / `` `code` ``, you MUST either pass `--html` (and translate markdown → HTML tags first) or strip the decoration. Sending Telegram-style markdown without `--html` renders the asterisks and backticks literally to the recipient. For multi-section messages with headers, separators, and code spans — **always** use `--html`.
>
> Recovery pattern when you've already sent a mangled message: send a follow-up prefixed `Correction — earlier message rendered as raw text, corrected version below:` then the correctly-HTML-formatted content. Do NOT silently edit if the message has been read (see "Editing Discipline" below).

```bash
/usr/bin/env bash << 'SEND_EOF'
ROOT="$(cc-plugin-root tlg)"
SCRIPT="$ROOT/scripts/tg-cli.ts"

# Default: plain text (use only for single-line unformatted messages)
bun "$SCRIPT" send @username "Hello"

# HTML formatting — the recommended default for any structured message
bun "$SCRIPT" send --html -1003958083153 "<b>Bold header</b>

Body with <code>inline code</code> and <a href='https://example.com'>a link</a>."

# By chat ID (groups use negative IDs)
bun "$SCRIPT" send -1003958083153 "Hello group"

# Specific profile
bun "$SCRIPT" -p personal send @username "Hello"

# Edit a message by ID
bun "$SCRIPT" edit -1003958083153 12345 "<b>Updated text</b>"

# Delete a message by ID
bun "$SCRIPT" delete -1003958083153 12345
SEND_EOF
```

**Long HTML messages**: `tg-cli.ts send --html` auto-splits at the 3900-plain-char threshold. Compose the full HTML as one string and let the splitter handle it. See "Auto-split for long messages" above.

### Editing Discipline — unread vs. read

**The core principle**: edit silently only when you are confident the recipient has NOT read the message yet. Once someone has seen a message, editing it risks creating a false record and confusing them (they remember the original text; the chat now shows different text).

| Situation                                                                                                          | Action                                                                  |
| ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- |
| You sent a message <30s ago in an active async chat and nobody has touched Telegram since                          | **Edit is safe** — iterate freely                                       |
| You just sent a message with a typo or factual error and the recipient has not responded                           | **Edit is safe** — they likely have not read it yet                     |
| The recipient has replied to your message                                                                          | **Do NOT edit silently** — send a supplement                            |
| The recipient has read the message but not yet replied (you see read receipts or their typing indicator came/went) | **Do NOT edit silently** — send a supplement                            |
| You're not sure whether the recipient has read it                                                                  | **Default to supplement** — safer than confusing them                   |
| The message has been cited or quoted by others in the chat                                                         | **Do NOT edit** — the citation is now stale context; supplement instead |

**Supplement pattern** (when edit is unsafe):

```
Correction on my previous message: <specific change>
```

or

```
Update to what I said above: <new info that supersedes>
```

Make the supplement self-contained so a reader scrolling back understands without having to cross-reference.

**Why this matters**: silent edits of read messages are one of the most confusing UX anti-patterns in chat systems. The recipient remembers "Terry told me X", sees "X'" now, and wonders if their memory is wrong or if they're being gaslit. Edits are a privilege to use before observation, not to rewrite history.

**How to tell if it's been read**: Telegram's MTProto exposes read receipts in 1:1 and small group chats via `messages.readHistoryOutbox` updates, but in large groups this is unreliable. The safest heuristic is time + activity: if more than ~60 seconds have elapsed and/or the recipient has been active in the chat, assume they saw it.

## Telegram HTML Formatting Reference

GramJS uses HTML, not Markdown:

| Tag                             | Renders As        |
| ------------------------------- | ----------------- |
| `<b>text</b>`                   | **Bold**          |
| `<i>text</i>`                   | _Italic_          |
| `<u>text</u>`                   | Underline         |
| `<s>text</s>`                   | ~~Strikethrough~~ |
| `<code>text</code>`             | `Inline code`     |
| `<pre>text</pre>`               | Code block        |
| `<a href="url">text</a>`        | Hyperlink         |
| `<tg-spoiler>text</tg-spoiler>` | Spoiler           |

### Horizontal separator rules (enforced convention)

Use `━` (U+2501) for horizontal rules between sections in long messages.

**Length rule**: **14 characters preferred, 22 characters absolute maximum.**

- **Preferred**: `━━━━━━━━━━━━━━` (14 × `━`)
- **Acceptable ceiling**: `━━━━━━━━━━━━━━━━━━━━━━` (22 × `━`, = 14 + 8)
- **Never exceed** 22 characters — longer separators look visually unbalanced on mobile clients and push body content off-screen.

Rationale: Telegram's mobile client reflows body text but does NOT wrap separator lines of box-drawing characters. A 28-char separator forces horizontal scrolling on narrow phones; 14 char fits cleanly in every viewport and still reads as a clear section break. If you need more visual weight, use a heading (`<b>...</b>`) above the separator rather than making the separator longer.

Emojis are supported but user may prefer decorations without emojis — use `<pre>` blocks and box-drawing characters instead.

## Profiles

| Profile          | Account            | User ID   |
| ---------------- | ------------------ | --------- |
| `work` (default) | @ExampleOpsAccount | <user-id> |
| `personal`       | @personal_account  | <user-id> |

## Known Group Chat IDs

| Group                  | Chat ID        | Type                                                           |
| ---------------------- | -------------- | -------------------------------------------------------------- |
| Terry & MD (Bruntwork) | -1003958083153 | Supergroup                                                     |
| Terry & MD (Bruntwork) | -1003958083153 | Legacy basic chat (pre-2026-04-16, read-only for old messages) |

## Topic Registry (Bruntwork Supergroup)

To send a message to a specific topic, pass `reply_to=<root_msg_id>` in `send_message()` or use `--reply-to` in tg-cli.ts.

| Topic                      | root_msg_id | Scope                                                  |
| -------------------------- | ----------- | ------------------------------------------------------ |
| General                    | 1           | Catch-all, quick questions                             |
| Assignments & Deliverables | 2           | Task definitions, PR reviews, Block check-ins          |
| Daily Operations           | 3           | Commencement/disembarkation, shift status              |
| Onboarding & Access        | 4           | Repo access, SSH/Tailscale, tool provisioning          |
| Policy & Standards         | 5           | cc-skills carve-out, conventions, discipline           |
| Bug Reports & Incidents    | 6           | Merge conflicts, hook bugs, pipeline breaks            |
| Tool Setup & Config        | 7           | example-service, example-app, example-pipeline         |
| Knowledge Base & Learning  | 8           | KB pages, research material, skill references          |
| HR & Scheduling            | 9           | Shift hours, Bruntwork coordination                    |
| Session Monitor            | 185         | Real-time Claude Code session summaries (CC Nasim Bot) |

## Anti-Patterns (NEVER DO)

| Anti-Pattern                                        | Why It Fails                                                         |
| --------------------------------------------------- | -------------------------------------------------------------------- |
| Running `bun "$SCRIPT"` without checking auth first | If session expired, auth will fail                                   |
| Checking only session file existence in preflight   | Session file can exist but be expired — must check with `check-auth` |
| Using plain text for formatted messages             | GramJS uses HTML, not Markdown. Use `--html` flag for formatting     |

## Error Handling

| Error                     | Cause                   | Fix                                                         |
| ------------------------- | ----------------------- | ----------------------------------------------------------- |
| `Unknown profile`         | Invalid `-p` value      | Use `work` or `personal`                                    |
| `Cannot find any entity`  | Bad username/ID         | Verify with `dialogs` command or use `find-user` to resolve |
| `message cannot be empty` | Empty string passed     | Provide message text                                        |
| `Session expired`         | Session no longer valid | Run `/tlg:setup` to re-authenticate non-interactively       |

## Post-Execution Reflection

After this skill completes, check before closing:

1. **Did the command succeed?** — If not, fix the instruction or error table that caused the failure.
2. **Did parameters or output change?** — If tg-cli.ts's interface drifted, update Usage examples and Parameters table to match.
3. **Was a workaround needed?** — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Versions

The database has no other skills named send-message.

Database snapshot: 13.11.2026 · package version c55a5950f1ca (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100send-media
    Use when user wants to send or upload a file, photo, video, voice note, or document on Telegram via their personal account.
  • 100telegram
    This skill should be used when the user asks to send a file, artifact, image, document, PDF, video, audio, or text message to their Telegram chat. Triggers include "use asun:telegram to send …", "send this to telegram", "telegram this file", "post to telegram", "share via…
  • 95tg-cli
    Set up Telegram and read or send messages in the owner's personal account through tg. Use when asked to install or connect Telegram, find a chat or person, read a conversation, or send a message.
  • 100send-sms-textbelt
    Send SMS text messages to phone numbers. Use when the user asks to send a text, send an SMS, text someone, message a phone number, or send a notification via text message.
  • 100telegram
    Full personal Telegram control over MTProto (Telethon) with the user's own account — list/search chats, read & summarize history, see unread, look up contacts & chat info, list a forum group's topics, download media, and send / reply / forward / edit / delete / react / send…
  • 100tlgr
    Read and act on a personal Telegram account from the terminal with the tlgr CLI (MTProto user account, not a bot). Use when the user wants to check unread Telegram chats, read or search message history, send, reply to, edit, forward or schedule messages, manage chats, groups,…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.