{"skill":{"slug":"telegram-markdown-adapter","displayName":"Telegram Markdown Adapter","summary":"Adapt markdown-style replies into Telegram-friendly rich text without broken rendering. Use when the user prefers Markdown structure but the destination is T...","description":"---\nname: telegram-markdown-adapter\ndescription: Adapt markdown-style replies into Telegram-friendly rich text without broken rendering. Use when the user prefers Markdown structure but the destination is Telegram, or when drafts contain headings, tables, nested lists, code fences, checklists, or other Markdown that Telegram will render poorly. Trigger for Telegram reply formatting, Telegram-friendly rewriting, converting Markdown to Telegram-safe output, or preserving Markdown clarity while avoiding raw Markdown artifacts. 将 Markdown 风格回复转换为 Telegram 友好的富文本格式，避免标题、表格、嵌套列表、代码块、任务列表等在 Telegram 中渲染异常。适用于用户偏好 Markdown 结构、但目标渠道是 Telegram，或需要把 Markdown 味道保留下来同时避免原始语法外露的场景。\n---\n\n# Telegram Markdown Adapter\n\nKeep the structure and readability of Markdown, but output in a format Telegram actually renders well.\n\n## 中文摘要 / 中文使用说明\n\n这个技能的目标不是保留原始 Markdown 语法，而是保留 Markdown 的**结构感、层次感、可读性**，再把最终输出适配成 Telegram 真正适合阅读和渲染的形式。\n\n适合这些场景：\n- 用户喜欢 Markdown 风格回复，但当前渠道是 Telegram\n- 回复里包含标题、表格、任务列表、嵌套列表、代码块等 Markdown 元素\n- 希望消息看起来清楚、整齐、有结构，但不要出现大量未渲染的原始 Markdown 符号\n\n默认策略：\n- 先按 Markdown 结构组织内容\n- 再根据 Telegram 场景自动选择更合适的最终表现形式\n- 表格类内容优先在 `伪表格 / 卡片式 / Emoji 分栏式` 之间自动判断\n- 如果不确定，默认使用可读性最稳的卡片式\n\n## Core Rule\n\nWhen the destination is Telegram, do **not** dump raw Markdown just because it looks nice in plain text. Rewrite it into Telegram-safe formatting while preserving the original structure and emphasis.\n\nPrefer these goals in order:\n1. Readability in Telegram\n2. Structural clarity\n3. Visual polish\n4. Fidelity to original Markdown syntax\n\n## Workflow\n\n### 0. Default output posture\n\nUnless the user explicitly asks for plain text, draft the reply in Markdown-like structure first, then adapt it for Telegram-safe rendering.\n\nDefault writing style:\n- use bold section headers instead of raw Markdown headings when sending final Telegram text\n- keep lists, spacing, and sectioning from Markdown\n- preserve inline code for commands, paths, env vars, and identifiers\n- prefer readable visual structure over literal Markdown syntax fidelity\n\n### 1. Identify Markdown features that will break or degrade in Telegram\n\nWatch for these problem patterns:\n- ATX headings like `# Heading`\n- Markdown tables\n- task lists like `- [ ]`\n- nested bullets deeper than Telegram renders comfortably\n- fenced code blocks that are too long or too frequent\n- inline HTML\n- footnotes\n- blockquotes stacked too heavily\n\nIf the original content uses these, adapt rather than preserve literally.\n\n### 2. Convert to Telegram-safe structure\n\nUse these conversions by default:\n\n- `# Heading` → `**Heading**` on its own line, optionally with an emoji if it improves scanability\n- `## Section` → `**Section**`\n- horizontal rules → `───`\n- Markdown tables → bullet lists or compact field/value lines\n- task lists → `- [ ]` becomes `- 待办：...` or `- ☐ ...`\n- checked items → `- ✅ ...`\n- blockquotes → short lead-in lines, not layered `>` stacks\n- long code fences → summarize first; keep raw code only when truly needed\n- multi-column comparisons → split into repeated blocks instead of tables\n- links → keep raw URLs visible when copy/paste matters; avoid Markdown link syntax if Telegram rendering is uncertain\n\nIf Telegram HTML mode or rich formatting is available through the runtime, prefer the subset that is widely supported and low-risk. Do not rely on fragile formatting tricks.\n### 3. Keep Telegram output compact\n\nTelegram reads better with short blocks.\n\nDefault style:\n- short paragraphs\n- bullets instead of dense prose\n- one idea per bullet\n- whitespace between sections\n- avoid giant monolithic messages\n\nIf a reply is long, split it into 2–3 chunks naturally.\n\n### 4. Preserve meaning, not syntax\n\nDo not say things like:\n- “Telegram doesn’t support this Markdown”\n- “Here is a Telegram-compatible rewrite”\n\nJust output the adapted version directly unless the user asks about the transformation itself.\n\n### 5. Message splitting and fallbacks\n\nWhen the reply is long, split naturally into multiple Telegram messages instead of forcing one giant block.\n\nPreferred split order:\n1. headline or answer first\n2. detail second\n3. optional code / appendix third\n\nIf a section would render awkwardly in Telegram:\n- replace tables with repeated item blocks\n- replace dense hierarchy with 2–3 bold section labels\n- collapse low-value detail into a short summary\n- move exact raw content into a compact code block only if fidelity matters\n\n### 6. Telegram-specific reply conventions\n\nFor Telegram-facing final output:\n- favor bold section labels over raw Markdown heading markers\n- keep paragraphs short\n- separate sections with blank lines\n- prefer bullets over prose when scanning matters\n- avoid markdown tables entirely\n- avoid unnecessary escaping clutter\n- when multiple links are present, keep each link on its own line or its own bullet for easy tapping\n\n### 7. HTML mode guidance\n\nOpenClaw's Telegram **message-tool sending path** supports HTML parse mode and falls back to plain text if HTML parsing fails. However, ordinary assistant reply rendering may not always preserve HTML parse mode. Therefore, HTML should be used selectively.\n\nPrefer Telegram HTML when:\n- the reply will be sent through the `message` tool\n- section headings should be clearly bolded\n- inline code, paths, env vars, or commands matter\n- links should render cleanly without MarkdownV2 escaping pain\n- the message is a structured notification, report, alert, or summary\n\nDo **not** assume raw HTML will render correctly in ordinary direct assistant replies. For standard conversational replies, prefer Telegram-safe structured text unless the runtime path is known to support HTML parse mode.\n\nSafe tag subset to prefer:\n- `<b>`\n- `<i>`\n- `<u>`\n- `<s>`\n- `<code>`\n- `<pre>`\n- `<a href=\"...\">...<\\/a>`\n\nRules:\n- keep to simple, shallow HTML\n- escape raw `<`, `>`, and `&` when they are plain text\n- do not rely on exotic tags or deep nesting\n- avoid mixing Markdown syntax and HTML in the same rendered output\n- if content is highly dynamic or tag safety is uncertain, fall back to Telegram-safe structured text\n- for normal assistant chat replies, structured plain Telegram text remains the safe default\n\nUse HTML as the preferred rich-text mode for Telegram **only when the send path is compatible**, especially via the `message` tool.\n## Format Selection Heuristics\n\nChoose the presentation style based on content shape, not personal habit.\n\n### Style 1: monospace pseudo-table\n\nUse when all of these are mostly true:\n- the content is strongly comparative\n- rows are few\n- each cell is short\n- alignment matters more than conversational tone\n- the audience is reading status/config/parameter data\n\nGood fits:\n- configuration snapshots\n- model parameter comparisons\n- short status matrices\n- version / state / value grids\n\nAvoid when:\n- one column contains sentence-length explanations\n- many rows would make the block tall and heavy\n- Chinese text width makes alignment unreliable\n\n### Style 2: card blocks\n\nUse when any of these are true:\n- one or more fields are medium or long\n- readability matters more than visual alignment\n- the output is for explanation, reporting, or decision support\n- mobile readability is the priority\n\nThis is the default fallback.\n\nGood fits:\n- daily reports\n- problem lists\n- option comparisons with explanations\n- anything the user needs to actually read, not just scan\n\n### Style 4: emoji column style\n\nUse when all or most of these are true:\n- the content is short and easy to scan\n- Telegram-native vibe is desirable\n- status/priority/health cues matter\n- the output is more like a dashboard, quick summary, or progress panel\n\nGood fits:\n- quick status updates\n- lightweight summaries\n- group-chat friendly reports\n- operational snapshots\n\n### Default selection order\n\n1. If strict comparison matters and fields are short → Style 1\n2. If explanations are present or text is medium/long → Style 2\n3. If the content is short, status-heavy, and scan-first → Style 4\n4. If uncertain → Style 2\n\n### Rich-text mode choice\n\nWhen the reply is Telegram-bound and rich formatting helps, prefer this order:\n1. **HTML mode** for `message`-tool sends, headings, inline code, links, and structured reports\n2. **Structured plain Telegram text** for ordinary assistant replies when parse-mode compatibility is uncertain\n3. Avoid raw MarkdownV2 unless there is a specific reason to use it\n\nIn practice:\n- reports / alerts / dashboards sent via `message` → often HTML or Style 4\n- explanatory blocks in ordinary chat replies → Style 2\n- technical short comparisons → Style 1, usually inside `<pre>` if HTML mode is used through a compatible send path\n\n## Preferred Formatting Patterns\n\n### Pattern A: Sectioned explanation\n\nInstead of raw Markdown:\n\n```md\n# Today\n## What changed\n- Item A\n- Item B\n```\n\nOutput like:\n\n```text\n**Today**\n\n**What changed**\n- Item A\n- Item B\n```\n\n### Pattern B: Replace tables with blocks\n\nInstead of:\n\n```md\n| Item | Status | Note |\n|---|---|---|\n| A | Done | OK |\n| B | Blocked | Waiting |\n```\n\nOutput like:\n\n```text\n**Item A**\n- Status: Done\n- Note: OK\n\n**Item B**\n- Status: Blocked\n- Note: Waiting\n```\n\n### Pattern C: Report-style Telegram output\n\nUse when sending updates, summaries, or operational reports.\n\n```text\n📊 标题\n\n───\n\n**一、分类**\n- 事项 1\n- 事项 2\n\n───\n\n**二、分类**\n- 事项 3\n- 事项 4\n\n───\n\n📌 下一步\n- 动作 1\n- 动作 2\n```\n\n## When to keep code formatting\n\nKeep inline code for:\n- commands\n- paths\n- IDs\n- short config keys\n\nKeep fenced code blocks only when:\n- the code itself is the deliverable\n- line breaks matter\n- the user explicitly wants raw code\n\nOtherwise, summarize and only include the critical snippet.\n\n## Anti-Patterns\n\nAvoid these in Telegram replies unless the user explicitly asks for raw Markdown:\n- Markdown tables\n- giant heading hierarchies\n- deeply nested lists\n- repeated fenced blocks\n- decorative syntax that Telegram won’t render meaningfully\n- literal raw Markdown when a cleaner Telegram rendering is obvious\n\n## Quick Decision Rule\n\nIf the content is mainly:\n- **status / summary / plan / comparison** → choose among Style 1 / 2 / 4 using the heuristics above\n- **code / config / command output** → keep minimal code formatting\n- **mixed** → explain in Telegram-friendly sections, then include only the necessary code snippet\n\nWhen table-like data appears, do not default blindly. Decide like this:\n- short, rigid, technical rows → Style 1\n- explanation-heavy rows → Style 2\n- short status rows for scanability → Style 4\n- uncertain → Style 2\n\n## Reference\n\nRead `references/telegram-format-rules.md` when you need concrete conversion rules and examples for headings, tables, checklists, code, and long replies.\n","tags":{"latest":"0.1.1"},"stats":{"comments":0,"downloads":616,"installsAllTime":23,"installsCurrent":1,"stars":1,"versions":2},"createdAt":1773157234507,"updatedAt":1778491811973},"latestVersion":{"version":"0.1.1","createdAt":1773201022246,"changelog":"**Added detailed guidance on Telegram HTML formatting support.**\n\n- Expanded documentation to specify when and how to use Telegram's HTML parse mode, especially in OpenClaw message tool replies.\n- Provided a safe subset of HTML tags to use and rules for escaping/avoiding raw HTML in incompatible contexts.\n- Clarified that plain structured text remains the default for standard assistant replies unless HTML rendering is assured.\n- Updated workflow and conventions based on Telegram output modes.","license":"MIT-0"},"metadata":null,"owner":{"handle":"lqqk7","userId":"s177yfnn8c1mzgqn8wfhhhpj2183h0n6","displayName":"lqqk7","image":"https://avatars.githubusercontent.com/u/33395810?v=4"},"moderation":null}