skills/ntfy/SKILL.md

name, description

name	description
ntfy	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:

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:

chmod 600 ~/.env/pi-ntfy.env

Loading Credentials

Before making requests, source the file:

source ~/.env/pi-ntfy.env

Or use it inline:

. ~/.env/pi-ntfy.env

Checking Credentials

Verify the file is set up correctly:

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:

-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:

-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:

-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):

-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

. ~/.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

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

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

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

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.