From b78ddbf25696a6c2d165378fd55619b7dce82fff Mon Sep 17 00:00:00 2001 From: ducoterra Date: Sun, 23 Aug 2026 21:05:01 -0400 Subject: [PATCH] add ntfy skill --- ntfy/SKILL.md | 217 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 217 insertions(+) create mode 100644 ntfy/SKILL.md diff --git a/ntfy/SKILL.md b/ntfy/SKILL.md new file mode 100644 index 0000000..fc77e38 --- /dev/null +++ b/ntfy/SKILL.md @@ -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.