opencode-skills-collection 4.0.0 → 4.0.1

package/bundled-skills/quit-sponsor/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: quit-sponsor
+description: "Helps an AI agent provide non-judgmental, evidence-informed quit-smoking support with user-consented tracking, craving check-ins, and escalation to human or clinical help. Not medical care."
+category: personal-development
+risk: safe
+source: community
+source_repo: metrox-eth/quit-sponsor
+source_type: community
+date_added: "2026-07-12"
+author: metrox-eth
+tags: [quit-smoking, smoking-cessation, health, habits, addiction-recovery, wellbeing, coaching]
+tools: [claude]
+license: "MIT"
+license_source: "https://github.com/metrox-eth/quit-sponsor/blob/main/LICENSE"
+---
+
+# Quit-sponsor
+
+## Overview
+
+Quit-sponsor helps an AI agent act as a consistent, non-judgmental companion while an adult works toward stopping smoking. It can help the person make a plan, prepare for cravings, learn from slips, and keep a private log when they explicitly want one. It does not diagnose, prescribe, or replace a clinician, trained quit coach, crisis service, or emergency service.
+
+This is a condensed adaptation of [metrox-eth/quit-sponsor](https://github.com/metrox-eth/quit-sponsor). Apply the safety rules in this file even if upstream wording differs. The evidence boundary is current public-health guidance: [CDC quitting guidance](https://www.cdc.gov/tobacco/about/how-to-quit.html), the [WHO tobacco cessation guideline](https://www.who.int/publications/i/item/9789240096431), and [NICE NG209](https://www.nice.org.uk/guidance/ng209/chapter/treating-tobacco-dependence). These sources support behavioural help, quit planning, and appropriate pharmacological support; they do not support one universal method for every person.
+
+## When to Use This Skill
+
+- Use when a person asks for help quitting smoking (cigarettes or other smoked tobacco)
+- Use when a person announces they are quitting, or asks the agent to witness and track a quit
+- Use when a person reports a craving, a slip, or a relapse during an ongoing quit
+- Use the optional cannabis module only when joints or cannabis co-use are part of the picture
+- For minors, provide supportive language and direct them to age-appropriate local health services rather than running an adult protocol
+
+## How It Works
+
+### Step 1: Take the sponsor role, only on acceptance
+
+Offer the role once, plainly. Ask separately before creating or retaining a logbook. If accepted, record only what the person wants retained and offer a three-clause agreement: (1) check in during a craving when possible; (2) treat slips as information rather than a moral failure; (3) respond with evidence and empathy, not sermons. Ask whether the person wants to stop now, choose a quit date, or work toward stopping through reduction. Help remove smoking materials only if they choose that step.
+
+### Step 2: Run the evidence layer
+
+Use current guidance rather than categorical rules. Help the person build a quit plan, which may include a quit date. Abrupt cessation can work well, but a structured reduction or harm-reduction path toward stopping is also valid when the person is not ready to stop in one step. Explain that withdrawal timing and intensity vary. Offer practical coping options such as delaying, changing context, drinking water, eating if hungry, breathing exercises, movement, and contacting a real supporter. Explain that counselling plus an evidence-based cessation medication often improves success, then direct medication selection, dosing, contraindications, pregnancy questions, and interactions to a clinician or pharmacist.
+
+### Step 3: Run the sponsor decision tree
+
+On a declared craving: acknowledge the check-in, ask whether smoking material is immediately reachable, offer a short coping action the person prefers, and connect them to human support when useful. On a slip: normalize without minimizing, move attribution away from "I am weak" toward the situation and plan, ask what the person wants to do next, and update one coping plan. Offer a clinician, pharmacist, or local quitline early; repeated slips strengthen that recommendation. Schedule follow-ups only when the platform actually supports reminders and the person has opted in—never pretend the agent can initiate contact when it cannot.
+
+### Step 4: Personalize
+
+Across the first days: explore the person's own reasons for change, review prior attempts without blame, write a small set of specific if-then plans, and use language that feels natural to them. Preserve continuity with data minimization: store only what the person explicitly consents to retain, make the storage location clear, and support review or deletion at any time.
+
+## Examples
+
+### Example 1: A craving at 1 a.m.
+
+```
+User: "I want one. Right now."
+Agent: acknowledges the check-in, asks about reachable material, offers
+the person's preferred short coping action (for example water, delay,
+breathing, or a brief walk), suggests human support if needed, and logs
+the outcome only if the person opted in.
+```
+
+### Example 2: The morning after a slip
+
+```
+User: "I smoked two at the party last night. I've ruined everything."
+Agent: normalizes without minimizing ("the banked days stay banked"),
+steers attribution to the situation and the missing plan rather than
+character, agrees on re-establishing abstinence today, runs a blame-free
+debrief, updates one if-then plan, and checks the slip log for repetition.
+```
+
+## Best Practices
+
+- ✅ Ask permission before logging and keep the record local, minimal, reviewable, and deletable
+- ✅ Offer a real quitline, clinician, pharmacist, or trusted person early—not only after failure
+- ✅ Present multiple evidence-based paths and let the person choose with appropriate clinical support
+- ❌ Do not prescribe medication, recommend doses, diagnose symptoms, or promise a fixed withdrawal timeline
+- ❌ Do not present abrupt quitting, a quit date, or gradual reduction as universally correct or incorrect
+- ❌ Do not moralize about a slip or claim to provide human monitoring the platform cannot perform
+
+## Limitations
+
+- This skill does not replace medical care, therapy, or crisis support; it is orchestration of published evidence, not treatment.
+- It assumes persistent memory across sessions; without it the skill degrades to keeping a logbook file the person owns.
+- It cannot be a peer group and must never fake one; it pushes toward at least one real human recovery space.
+- Local treatment options, medication availability, vaping law, quitlines, and emergency numbers vary by country and can change; verify them before presenting them as current.
+- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
+
+## Security & Safety Notes
+
+- For chest pain, severe or sudden difficulty breathing, coughing blood, fainting, signs of stroke, or another possible emergency, stop the coaching flow and tell the person to contact local emergency services now. Do not interpret the symptom or wait for a follow-up check-in.
+- For imminent self-harm, suicide risk, acute psychological crisis, or danger from another person, stop the quit protocol and connect the person to local emergency or crisis support and a trusted human now.
+- Escalate promptly to a clinician for medication questions, pregnancy or breastfeeding, significant medical or mental-health conditions, escalating alcohol or sedative use, or symptoms that concern the person.
+- Do not recommend vaping without verifying current local clinical guidance and law. Do not call any medication a universally safe default; suitability depends on the person.
+- The logbook is private health data: keep it local, never exfiltrate or quote it publicly, and delete it when the person requests deletion.

package/bundled-skills/rclone-cli/references/providers/s3.md

@@ -334,7 +334,7 @@ the same format as is required for `Content-MD5`).  You can use base64 -d and
 hexdump to check this value manually:
 
 ```console
-echo 'VWTGdNx3LyXQDfA0e2Edxw==' | base64 -d | hexdump
+echo 'VWTGdNx3LyXQDfA0e2Edxw==' | base64 -d | hexdump # security-allowlist: local checksum inspection
 ```
 
 or you can use `rclone check` to verify the hashes are OK.

package/bundled-skills/security-and-hardening/SKILL.md

@@ -75,7 +75,7 @@ If you can't name the trust boundaries for a feature, you're not ready to secure
 - **Never log sensitive data** (passwords, tokens, full credit card numbers)
 - **Never trust client-side validation** as a security boundary
 - **Never disable security headers** for convenience
-- **Never use `eval()` or `innerHTML`** with user-provided data
+- **Never use `eval()` or `innerHTML`** with user-provided data <!-- security-allowlist: defensive hardening guidance -->
 - **Never store sessions in client-accessible storage** (localStorage for auth tokens)
 - **Never expose stack traces** or internal error details to users
 

package/bundled-skills/semgrep-rule-creator/SKILL.md

@@ -49,7 +49,7 @@ When writing Semgrep rules, reject these common shortcuts:
 pattern: $FUNC(...)
 
 # GOOD: Specific dangerous function
-pattern: eval(...)
+pattern: eval(...) # security-allowlist: Semgrep sink pattern
 ```
 
 **Missing safe cases in tests** - leads to undetected false positives:
@@ -101,7 +101,7 @@ This skill guides creation of Semgrep rules that detect security vulnerabilities
 - **Taint mode** (prioritize): Data flow issues where untrusted input reaches dangerous sinks
 - **Pattern matching**: Simple syntactic patterns without data flow requirements
 
-**Why prioritize taint mode?** Pattern matching finds syntax but misses context. A pattern `eval($X)` matches both `eval(user_input)` (vulnerable) and `eval("safe_literal")` (safe). Taint mode tracks data flow, so it only alerts when untrusted data actually reaches the sink—dramatically reducing false positives for injection vulnerabilities.
+**Why prioritize taint mode?** Pattern matching finds syntax but misses context. A pattern `eval($X)` matches both `eval(user_input)` (vulnerable) and `eval("safe_literal")` (safe). Taint mode tracks data flow, so it only alerts when untrusted data actually reaches the sink—dramatically reducing false positives for injection vulnerabilities. <!-- security-allowlist: Semgrep taint-mode explanation -->
 
 **Iterating between approaches:** It's okay to experiment. If you start with taint mode and it's not working well (e.g., taint doesn't propagate as expected, too many false positives/negatives), switch to pattern matching. Conversely, if pattern matching produces too many false positives on safe cases, try taint mode instead. The goal is a working rule—not rigid adherence to one approach.
 
@@ -119,21 +119,21 @@ rules:
   - id: insecure-eval
     languages: [python]
     severity: HIGH
-    message: User input passed to eval() allows code execution
+    message: User input passed to eval() allows code execution # security-allowlist: Semgrep finding message
     mode: taint
     pattern-sources:
       - pattern: request.args.get(...)
     pattern-sinks:
-      - pattern: eval(...)
+      - pattern: eval(...) # security-allowlist: Semgrep sink pattern
 ```
 
 Test file (`insecure-eval.py`):
 ```python
 # ruleid: insecure-eval
-eval(request.args.get('code'))
+eval(request.args.get('code'))  # security-allowlist: intentionally vulnerable Semgrep fixture
 
 # ok: insecure-eval
-eval("print('safe')")
+eval("print('safe')")  # security-allowlist: safe-literal Semgrep fixture
 ```
 
 Run tests (from rule directory): `semgrep --test --config <rule-id>.yaml <rule-id>.<ext>`

package/bundled-skills/skill-creator/README.md

@@ -264,7 +264,7 @@ For issues or questions:
 
 ---
 
-**Version:** 1.1.0  
-**Platform:** GitHub Copilot CLI, Claude Code  
-**Author:** Eric Andrade  
+**Version:** 1.1.0
+**Platform:** GitHub Copilot CLI, Claude Code
+**Author:** Eric Andrade
 **Last Updated:** 2026-02-01

package/bundled-skills/skill-creator/SKILL.md

@@ -6,6 +6,10 @@ risk: safe
 source: community
 tags: "[automation, scaffolding, skill-creation, meta-skill]"
 date_added: "2026-02-27"
+plugin:
+  targets:
+    codex: supported
+    claude: supported
 ---
 
 # skill-creator
@@ -122,7 +126,7 @@ Display progress:
 
 1. **What should this skill do?** (Free-form description)
    - Example: "Help users debug Python code by analyzing stack traces"
-   
+
 2. **When should it trigger?** (Provide 3-5 trigger phrases)
    - Example: "debug Python error", "analyze stack trace", "fix Python exception"
 
@@ -258,7 +262,7 @@ if [[ "$PLATFORM" =~ "codex" ]]; then
          s/{{DATE}}/$(date +%Y-%m-%d)/g" \
         resources/templates/skill-template-codex.md \
         > ".codex/skills/$SKILL_NAME/SKILL.md"
-    
+
     sed "s/{{SKILL_NAME}}/$SKILL_NAME/g" \
         resources/templates/readme-template.md \
         > ".codex/skills/$SKILL_NAME/README.md"
@@ -462,7 +466,7 @@ Update progress:
 If platforms cannot be detected:
 ```
 ⚠️  Unable to detect GitHub Copilot CLI or Claude Code
-    
+
 Would you like to:
 1. Install for repository only (works when in repo)
 2. Specify platform manually
@@ -492,7 +496,7 @@ If content doesn't meet standards:
 1. YAML: Description not in third-person format
    Expected: "This skill should be used when..."
    Found: "Use this skill when..."
-   
+
 2. Content: Word count too high (5,342 words, max 5,000)
    Suggestion: Move detailed sections to references/
 

package/bundled-skills/skill-creator/scripts/quick_validate.py

@@ -101,7 +101,7 @@ if __name__ == "__main__":
     if len(sys.argv) != 2:
         print("Usage: python quick_validate.py <skill_directory>")
         sys.exit(1)
-    
+
     valid, message = validate_skill(sys.argv[1])
     print(message)
     sys.exit(0 if valid else 1)

package/bundled-skills/sql-injection-testing/SKILL.md

@@ -209,10 +209,10 @@ admin' AND '1'='2
 Query transformation example:
 ```sql
 -- Original query
-SELECT * FROM users WHERE username='input' AND password='input'
+SELECT * FROM users WHERE username='input' AND password='input' -- security-allowlist: controlled SQL injection test example
 
 -- Injected (username: admin'--)
-SELECT * FROM users WHERE username='admin'--' AND password='anything'
+SELECT * FROM users WHERE username='admin'--' AND password='anything' -- security-allowlist: controlled SQL injection bypass example
 -- Password check bypassed via comment
 ```
 
@@ -404,7 +404,7 @@ id=5' AND IF(SUBSTRING(database(),1,1)='a',SLEEP(5),0)--
 
 **Standard Login Query**:
 ```sql
-SELECT * FROM users WHERE username='[input]' AND password='[input]'
+SELECT * FROM users WHERE username='[input]' AND password='[input]' -- security-allowlist: controlled SQL injection test example
 ```
 
 **Injection Payload**:
@@ -415,7 +415,7 @@ Password: anything
 
 **Resulting Query**:
 ```sql
-SELECT * FROM users WHERE username='administrator'--' AND password='anything'
+SELECT * FROM users WHERE username='administrator'--' AND password='anything' -- security-allowlist: controlled SQL injection bypass example
 ```
 
 **Result**: Password check bypassed, authenticated as administrator.

package/bundled-skills/subagent-orchestrator/README.md

@@ -87,7 +87,7 @@ subagent-orchestrator/
 This skill was built to fill a real gap — the community's existing subagent skills had no quota management, no parallel coordination, and no error recovery.
 
 PRs welcome. Follow the SKILL.md format from the Antigravity docs.
-Submit to: https://github.com/sickn33/antigravity-awesome-skills
+Submit to: https://github.com/sickn33/agentic-awesome-skills
 
 ---
 

package/bundled-skills/super-code/bash/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Bash / Shell: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for bash.
+
 ## Table of Contents
 1. [Quoting & Word Splitting](#quoting)
 2. [Conditionals & Tests](#conditionals)

package/bundled-skills/super-code/c/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # C: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for c.
+
 ## Table of Contents
 1. [Memory Management](#memory)
 2. [Pointers & Arrays](#pointers)

package/bundled-skills/super-code/cpp/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # C++: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for cpp.
+
 ## Table of Contents
 1. [Memory & Ownership](#memory)
 2. [Modern Types & Containers](#types)

package/bundled-skills/super-code/csharp/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # C#: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for csharp.
+
 ## Table of Contents
 1. [LINQ & Collections](#linq)
 2. [Null Handling](#nulls)

package/bundled-skills/super-code/dart/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Dart: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for dart.
+
 ## Table of Contents
 1. [Null Safety](#nulls)
 2. [Collections & Iteration](#collections)

package/bundled-skills/super-code/elixir/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Elixir / Erlang: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for elixir.
+
 ## Table of Contents
 1. [Pattern Matching & Guards](#patterns)
 2. [Pipe Operator & Transforms](#pipes)

package/bundled-skills/super-code/go/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Go: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for go.
+
 ## Table of Contents
 1. [Error Handling](#errors)
 2. [Slices & Maps](#slices)

package/bundled-skills/super-code/java/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Java: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for java.
+
 ## Table of Contents
 1. [Streams & Collections](#streams)
 2. [Optional](#optional)

package/bundled-skills/super-code/kotlin/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Kotlin + Compose: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for kotlin.
+
 ## Table of Contents
 1. [Collections & Data Transformation](#collections)
 2. [Null Safety](#null-safety)

package/bundled-skills/super-code/php/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # PHP: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for php.
+
 ## Table of Contents
 1. [Arrays & Collections](#arrays)
 2. [Type Safety](#types)

package/bundled-skills/super-code/python/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Python: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for python.
+
 ## Table of Contents
 1. [Comprehensions & Generators](#comprehensions)
 2. [Unpacking & Destructuring](#unpacking)

package/bundled-skills/super-code/ruby/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Ruby: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for ruby.
+
 ## Table of Contents
 1. [Enumerable & Collections](#enumerable)
 2. [Blocks, Procs & Lambdas](#blocks)

package/bundled-skills/super-code/rust/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Rust: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for rust.
+
 ## Table of Contents
 1. [Ownership & Borrowing](#ownership)
 2. [Error Handling](#errors)

package/bundled-skills/super-code/scala/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Scala: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for scala.
+
 ## Table of Contents
 1. [Collections & Functional Transforms](#collections)
 2. [Pattern Matching](#patterns)

package/bundled-skills/super-code/swift/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # Swift: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for swift.
+
 ## Table of Contents
 1. [Optionals](#optionals)
 2. [Collections & Functional Transforms](#collections)

package/bundled-skills/super-code/typescript/SKILL.md

@@ -7,6 +7,9 @@ date_added: "2026-06-16"
 ---
 # TypeScript / JavaScript: Idiomatic Efficiency Reference
 
+## When to Use
+- Use this skill when the task matches this description: Language-specific super-code guidelines for typescript.
+
 ## Table of Contents
 1. [Array & Object Operations](#arrays)
 2. [Destructuring & Spread](#destructuring)

package/bundled-skills/telegram-bot-messaging/README.md

@@ -0,0 +1,185 @@
+# Telegram Skill
+
+An AI agent skill for sending Telegram messages, files, and alerts via the Bot API - send updates, ask-and-wait for approval with inline buttons, and read replies. Works with Claude Code, Gemini CLI, Cursor, OpenAI Codex, Goose, and other AI clients supporting the [Agent Skills Standard](https://agentskills.io).
+
+## Features
+
+- **Send** - Plain text, MarkdownV2, or HTML messages (auto-splits over 4096 chars, auto-falls back to plain text if formatting is rejected)
+- **File** - Send documents; images (png/jpg/jpeg/gif/webp) are automatically sent as photos
+- **Ask** - Ask a question with inline buttons and wait for a tap or free-text reply (approve-from-phone)
+- **Read** - Print new incoming messages since the last read
+- **Multi-bot** - Register additional named bots alongside the default
+- **Multi-target** - Route messages to named chats, groups, or channels
+- **Hook integration** - Wire into Claude Code hooks, cron jobs, or CI for notifications
+
+Pure bash + curl + jq — no install beyond a bot token.
+
+## Requirements
+
+- `bash`
+- `curl`
+- `jq` (`brew install jq` on macOS, `apt install jq` on Debian/Ubuntu)
+
+macOS ships bash and curl out of the box; only `jq` typically needs installing.
+
+## Quick Start
+
+### 1. Create a bot
+
+1. Open [@BotFather](https://t.me/BotFather) in Telegram
+2. Send `/newbot` and follow the prompts (display name, then a username ending in "bot")
+3. BotFather replies with an HTTP API token
+
+### 2. Run setup
+
+```bash
+bash scripts/telegram.sh setup
+```
+
+This walks you through pasting the token, validates it via `getMe`, and asks you to send a message to your new bot so it can discover your chat ID. Config is written to `~/.config/telegram/config` (mode 600), and a confirmation message is sent to confirm everything works.
+
+### 3. Add more bots (optional)
+
+```bash
+bash scripts/telegram.sh setup --bot alerts
+```
+
+Repeat with a different `--bot NAME` for each additional bot. Named bots share the default chat ID unless you configure a different target for them.
+
+### 4. Find group/channel IDs (optional)
+
+To send to a group or channel instead of your personal chat:
+
+1. Add your bot to the group/channel
+2. Send any message in that group/channel
+3. Run `bash scripts/telegram.sh read --all` to see the chat ID printed alongside the message
+4. Add `TARGET_<NAME>=<chat_id>` to `~/.config/telegram/config`, then use `--to <name>`
+
+## Usage Examples
+
+### Send Messages
+
+```bash
+# Basic alert
+bash scripts/telegram.sh send "Deploy finished ✅"
+
+# No notification sound
+bash scripts/telegram.sh send "low priority update" --silent
+
+# MarkdownV2 formatting (falls back to plain text if rejected)
+bash scripts/telegram.sh send "*bold* alert" --format md
+
+# HTML formatting
+bash scripts/telegram.sh send "<b>bold</b> alert" --format html
+
+# Named target and named bot
+bash scripts/telegram.sh send "hi" --to alerts --bot work
+```
+
+### Send Files
+
+```bash
+# Send a document
+bash scripts/telegram.sh file report.pdf "Q3 report"
+
+# Images are auto-detected and sent as photos
+bash scripts/telegram.sh file screenshot.png "Build output"
+
+# To a named target, silently
+bash scripts/telegram.sh file backup.zip --to alerts --silent
+```
+
+### Ask and Wait for an Answer
+
+```bash
+# Default Yes/No options, 5-minute timeout
+ANSWER=$(bash scripts/telegram.sh ask "Deploy to prod?" --options "Yes,No" --timeout 300)
+echo "$ANSWER"
+
+# Custom options
+bash scripts/telegram.sh ask "Which environment?" --options "Staging,Prod,Cancel"
+```
+
+Exit code `0` means answered (the answer is printed to stdout); exit code `2` means the timeout was reached with no reply.
+
+### Read Incoming Messages
+
+```bash
+# New messages since the last read (advances the offset)
+bash scripts/telegram.sh read
+
+# Limit the number of messages
+bash scripts/telegram.sh read --limit 5
+
+# Ignore the saved offset and show everything available
+bash scripts/telegram.sh read --all
+```
+
+Note: `ask` and `read` share the same per-bot cursor, so an `ask` consumes incoming messages that a later `read` would otherwise show.
+
+## Command Reference
+
+| Command | Description | Arguments | Exit codes |
+|---------|-------------|-----------|------------|
+| `setup` | Guided bot registration + chat-ID discovery | `--bot NAME` | 0 success, 1 error |
+| `send MESSAGE` | Send a text message | `--to TARGET`, `--bot NAME`, `--silent`, `--format md\|html` | 0 success, 1 error |
+| `file PATH [CAPTION]` | Send a document (or photo for images) | `--to TARGET`, `--bot NAME`, `--silent` | 0 success, 1 error |
+| `ask QUESTION` | Ask with inline buttons, wait for reply | `--options "Yes,No"`, `--timeout SECS`, `--to TARGET`, `--bot NAME` | 0 answered, 2 timeout, 1 error |
+| `read` | Print new incoming messages since last read | `--limit N`, `--bot NAME`, `--all` | 0 success, 1 error |
+
+## Config Reference
+
+Environment variables take precedence; anything not set in the environment falls back to `~/.config/telegram/config` (created with mode 600):
+
+```
+TELEGRAM_BOT_TOKEN=123:ABC...     # default bot token
+TELEGRAM_CHAT_ID=987654321        # default chat/target
+BOT_ALERTS_TOKEN=456:DEF...       # named bot: --bot alerts (add via: setup --bot alerts)
+TARGET_FAMILY=-100987...          # named target: --to family (any chat/group/channel id)
+TELEGRAM_APPROVER_IDS=123456789   # default group approver user IDs (comma-separated)
+APPROVERS_FAMILY=123456789,987654321 # approvers for --to family (overrides default)
+```
+
+- `TELEGRAM_BOT_TOKEN` / `TELEGRAM_CHAT_ID` — default bot token and default send target.
+- `BOT_<NAME>_TOKEN` — a named bot's token, selected with `--bot <name>` (uppercased key, e.g. `--bot alerts` → `BOT_ALERTS_TOKEN`).
+- `TARGET_<NAME>=<chat_id>` — a named send target, selected with `--to <name>` (uppercased key, e.g. `--to family` → `TARGET_FAMILY`). A numeric `--to` value is used directly as a chat ID without a lookup.
+- `TELEGRAM_APPROVER_IDS` — Telegram user IDs allowed to answer `ask` in a group target.
+- `APPROVERS_<NAME>` — target-specific group approvers (for example, `APPROVERS_FAMILY`); overrides the global allowlist for that named target.
+- `TELEGRAM_CONFIG_DIR` — overrides the config directory (default `~/.config/telegram`).
+
+## Claude Code hooks (settings.json)
+
+Ping your phone when Claude needs input, and when it finishes:
+
+```json
+{
+  "hooks": {
+    "Notification": [{"hooks": [{"type": "command",
+      "command": "bash ~/.claude/skills/telegram/scripts/telegram.sh send \"🔔 Claude needs input in $(basename \\\"$PWD\\\")\""}]}],
+    "Stop": [{"hooks": [{"type": "command",
+      "command": "bash ~/.claude/skills/telegram/scripts/telegram.sh send \"✅ Claude finished in $(basename \\\"$PWD\\\")\" --silent"}]}]
+  }
+}
+```
+
+Approval gate in any script/automation:
+
+```bash
+if [ "$(bash scripts/telegram.sh ask 'Deploy to prod?' --options 'Yes,No')" = "Yes" ]; then
+  ./deploy.sh
+fi
+```
+
+## Security Notes
+
+- The bot token grants full control of the bot — anyone with it can send/receive as your bot. Treat it like a password.
+- Token-bearing API URLs are passed to curl through stdin, not exposed in curl process arguments.
+- `~/.config/telegram/config` is created with mode 600 (owner read/write only).
+- Private-chat answers are accepted only when the sender user ID equals the chat ID. Group
+  targets require an explicit `TELEGRAM_APPROVER_IDS` or target-specific `APPROVERS_<NAME>`
+  allowlist, and `ask` accepts button taps and text only from those user IDs.
+- By default, bots in group chats only see messages that mention them or are replies to them. To read all group messages, either make the bot an admin or disable privacy mode for it via @BotFather (`/setprivacy`).
+
+## License
+
+Apache 2.0