From bf1e15177bef668af31886c9b779429b98b15924 Mon Sep 17 00:00:00 2001
From: Eve <eve@ai.cowbay.org>
Date: Wed, 15 Apr 2026 22:52:54 +0800
Subject: [PATCH] skills: add telegram inline buttons guidance

---
 skills/telegram-inline-buttons/SKILL.md | 98 +++++++++++++++++++++++++
 1 file changed, 98 insertions(+)
 create mode 100644 skills/telegram-inline-buttons/SKILL.md

diff --git a/skills/telegram-inline-buttons/SKILL.md b/skills/telegram-inline-buttons/SKILL.md
new file mode 100644
index 0000000..daf8875
--- /dev/null
+++ b/skills/telegram-inline-buttons/SKILL.md
@@ -0,0 +1,98 @@
+---
+name: telegram-inline-buttons
+description: Use when sending proactive Telegram messages that ask Eric to confirm, choose, defer, or pick from a few next actions; especially for yes/no, A/B/C, do-now-vs-later, or short multi-step button flows.
+---
+
+# Telegram Inline Buttons
+
+Prefer inline buttons over free-text prompts when sending a proactive Telegram message that expects a choice.
+
+## Use buttons for
+- Yes / No confirmations
+- A / B / C choices
+- Do it now vs later
+- Picking one of a few next actions
+
+## Do not use buttons for
+- Purely informational messages
+- Input that requires typed text
+- More than 5 options
+
+If there are >5 options, summarize and offer a `Show more` button.
+
+## Button design
+- Keep labels short: 1-4 words
+- 2-4 buttons is ideal
+- Include a safe exit when appropriate: `Not now`, `Cancel`, `Later`, `Skip`
+- Keep `callback_data` stable and unique per flow step, e.g. `reminder_time_15m`, `deploy_confirm_yes`
+
+Recommended layouts:
+- Binary: one row `[Yes] [No]`
+- Decision + defer: row 1 `[Do it] [Not now]`, row 2 `[More info]`
+- A/B/C: one row `[A] [B] [C]`
+
+## Telegram message tool pattern
+For user-visible delivery, use `message(action="send")` with `buttons`.
+
+Example shape:
+
+```json
+{
+  "action": "send",
+  "channel": "telegram",
+  "target": "...",
+  "message": "Want me to proceed?",
+  "buttons": [[
+    {"text": "Proceed", "callback_data": "deploy_confirm_yes", "style": "primary"},
+    {"text": "Hold", "callback_data": "deploy_confirm_no"}
+  ]]
+}
+```
+
+## After a button click
+Telegram bot messages do not support arbitrary text color. To make the selection stand out:
+1. Edit the original message
+2. Remove the inline keyboard
+3. Append one short committed-selection line with emoji
+
+Standard emoji mapping:
+- `✅` or `🟩` = yes / approve / proceed / confirm
+- `🟥` = no / cancel / stop
+- `⬛️` = later / skip / defer
+
+Do **not** send a separate follow-up that only repeats the selection. Editing is enough unless you also need to report results or ask the next question.
+
+## Multi-step flows
+For branching flows:
+1. Edit the prior message to commit the selection
+2. Send the next question with fresh buttons
+3. Do not narrate the previous selection again
+
+Keep the first message short. Put details in the next step after the click.
+
+## Duplicate / stale callbacks
+If a callback arrives after the message is already finalized:
+- Do nothing
+- No extra message
+- No further edits
+- Silently ignore it
+
+## Tooling rule
+If `message(send/edit)` delivered the user-visible response, reply in chat with `NO_REPLY` unless you must add extra context beyond what the message edit already shows.
+
+## Copy-ready templates
+
+### Confirm action
+Text: `Want me to proceed with <action>?`
+Buttons: `[Proceed] [Hold]`
+
+### Pick next step
+Text: `Pick the next move:`
+Buttons: `[Option A] [Option B] [Option C] [Not now]`
+
+### Scheduling
+Text: `When should I remind you?`
+Buttons: `[15m] [1h] [Tonight] [Tomorrow]`
+
+## Decision rule
+Default to buttons whenever Eric is being asked to choose, confirm, defer, or select the next action on Telegram.