add ntfy skill
This commit is contained in:
+217
@@ -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.
|
||||
Reference in New Issue
Block a user