add ntfy skill

2026-08-23 21:05:01 -04:00
parent 85ac0d61b9
commit b78ddbf256
1 changed files with 217 additions and 0 deletions
@@ -0,0 +1,217 @@
 ---
 name: ntfy
 description: "Send push notifications via a self-hosted ntfy server. Use when phases complete, tasks finish, the LLM needs to ask the user a question, or any scenario where the user needs to be notified."
 ---
 # ntfy — Push Notifications
 Send push notifications to the user's device via ntfy. Use this skill whenever the user needs to be notified — phase completions, task finishes, questions requiring user input, errors, or any other event warranting attention.
 ## Configuration — `~/.env/pi-ntfy.env`
 All ntfy credentials are stored in `~/.env/pi-ntfy.env`. If this file doesn't exist, the ntfy skill won't work.
 ### Required Variables
 | Variable | Description | Example |
 |----------|-------------|---------|
 | `NTFY_URL` | ntfy server URL | `https://ntfy.reeseapps.com` |
 | `NTFY_TOKEN` | Authorization token | `tk_your_token_here` |
 | `NTFY_TOPIC` | Default topic name | `pi` |
 ### Setting Up the Config File
 Create the config file with your ntfy credentials:
 ```bash
 mkdir -p ~/.env
 cat > ~/.env/pi-ntfy.env << 'EOF'
 NTFY_URL=https://ntfy.reeseapps.com
 NTFY_TOKEN=tk_your_token_here
 NTFY_TOPIC=pi
 EOF
 ```
 Then restrict permissions so only your user can read it:
 ```bash
 chmod 600 ~/.env/pi-ntfy.env
 ```
 ### Loading Credentials
 Before making requests, source the file:
 ```bash
 source ~/.env/pi-ntfy.env
 ```
 Or use it inline:
 ```bash
 . ~/.env/pi-ntfy.env
 ```
 ### Checking Credentials
 Verify the file is set up correctly:
 ```bash
 source ~/.env/pi-ntfy.env
 echo "URL: $NTFY_URL"
 echo "Token: $NTFY_TOKEN"
 echo "Topic: $NTFY_TOPIC"
 ```
 ## Priority Levels
 Choose the priority based on urgency:
 | Priority | Header Value | Use Case |
 |----------|-------------|----------|
 | Min      | `X-Priority: 1` | Informational, low importance |
 | Low      | `X-Priority: 2` | Routine updates |
 | Default  | `X-Priority: 3` | Normal notifications |
 | High     | `X-Priority: 4` | Important, user should notice |
 | Emergency| `X-Priority: 5` | Critical, must act immediately |
 ## Tags & Emojis
 Use `X-Tags` to add emojis and labels. Separate multiple tags with commas:
 ```bash
 -H "X-Tags: heavy_check_mark,done"    # ✔️ done
 -H "X-Tags: rotating_light,urgent"    # 🚨 urgent
 -H "X-Tags: warning,caution"          # ⚠️ caution
 -H "X-Tags: tada,celebration"         # 🎉 celebration
 -H "X-Tags: loudspeaker,announce"     # 📢 announcement
 -H "X-Tags: question,ask"             # ❓ question
 -H "X-Tags: skull,error"              # 💀 error
 -H "X-Tags: computer,dev"             # 💻 development
 -H "X-Tags: facepalm,issue"           # 🤦 issue
 ```
 Common emoji tags: `tada`, `heavy_check_mark`, `rotating_light`, `warning`, `loudspeaker`, `question`, `skull`, `computer`, `facepalm`, `arrow_forward`, `one`, `-1`, `partying_face`, `triangular_flag_on_post`, `no_entry`, `cd`.
 ## Markdown Support
 Set `X-Markdown: yes` (or `Content-Type: text/markdown`) to enable rich formatting:
 ```bash
 -d "Phase complete! Here's what was done:
 - **Feature A** — implemented
 - **Feature B** — tested
 - **Feature C** — deployed
 See [details](https://example.com) for more."
 ```
 Supported: **bold**, *italics*, `[links](url)`, `inline code`, ``` code blocks ```, lists, blockquotes, headings, horizontal rules.
 ## Click Actions
 Open a URL when the notification is tapped:
 ```bash
 -H "X-Click: https://example.com/dashboard"
 ```
 Common patterns:
 - `https://...` — opens in browser
 - `mailto:user@example.com` — opens mail app
 - `ntfy://ntfy.reeseapps.com/pi` — opens ntfy app directly
 ## Action Buttons
 Add interactive buttons to the notification (JSON array):
 ```bash
 -H "X-Actions: [{'id': '1', 'label': 'View Details', 'uri': 'https://example.com'}]"
 ```
 Format: `[{"id": "1", "label": "Button Text", "uri": "https://url"}]`
 ## Message Structure Examples
 ### Phase Complete
 ```bash
 . ~/.env/pi-ntfy.env
 curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Phase 3 Complete" \
  -H "X-Priority: 4" \
  -H "X-Tags: heavy_check_mark,phase-3" \
  -H "X-Markdown: yes" \
  -d "**Phase 3: Authentication** completed successfully.\n\n- 12 tests passed\n- 94% coverage\n- 0 regressions"
 ```
 ### Task Finished
 ```bash
 curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Task Done" \
  -H "X-Priority: 3" \
  -H "X-Tags: computer,task-complete" \
  -H "X-Markdown: yes" \
  -d "Task completed: implemented user login flow"
 ```
 ### Question for User
 ```bash
 curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Question" \
  -H "X-Priority: 4" \
  -H "X-Tags: question,needs-input" \
  -H "X-Markdown: yes" \
  -H "X-Click: ${NTFY_URL}/${NTFY_TOPIC}" \
  -d "Should I proceed with the database migration? Reply 'yes' or 'no'."
 ```
 ### Error / Failure
 ```bash
 curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Error" \
  -H "X-Priority: 5" \
  -H "X-Tags: skull,error" \
  -H "X-Markdown: yes" \
  -d "**Phase 2 failed!**\n\n`Exit code: 1`\n\n```\nError: connection refused\n```\n\nCheck logs for details."
 ```
 ### General Announcement
 ```bash
 curl -X POST "${NTFY_URL}/${NTFY_TOPIC}" \
  -H "Authorization: Bearer ${NTFY_TOKEN}" \
  -H "X-Title: Update" \
  -H "X-Priority: 2" \
  -H "X-Tags: loudspeaker,update" \
  -H "X-Markdown: yes" \
  -d "The agent is now working on phase 4 of 7."
 ```
 ## Quick Reference
 | Field | Header | Example |
 |-------|--------|---------|
 | URL | (in request) | `${NTFY_URL}/${NTFY_TOPIC}` |
 | Token | (in Authorization) | `Bearer ${NTFY_TOKEN}` |
 | Title | `X-Title` | `X-Title: Phase Complete` |
 | Priority | `X-Priority` | `X-Priority: 5` (1–5) |
 | Tags/Emojis | `X-Tags` | `X-Tags: tada,done` |
 | Markdown | `X-Markdown` | `X-Markdown: yes` |
 | Click URL | `X-Click` | `X-Click: https://...` |
 | Actions | `X-Actions` | `X-Actions: [...]` |
 | Body | `-d` | `**Message**` |
 ## Guidelines
 1. **Always use markdown** (`X-Markdown: yes`) for readable, formatted messages.
 2. **Choose priority wisely** — use 4–5 for questions and errors, 2–3 for routine updates.
 3. **Pick appropriate tags** to convey the notification type at a glance.
 4. **Keep titles concise** (1–5 words) — they appear in the notification shade.
 5. **Include relevant details** in the body: phase numbers, task names, error messages.
 6. **Add click actions** when the user might want to check more details.
 7. **Use emergency priority (5)** only for critical failures requiring immediate attention.