ntfy Notifications

Use this skill for meaningful status notifications from tasks that may take more than 30 seconds. The default server is https://ntfy.sh. A user may choose a self-hosted HTTPS server, with or without authentication, when that server's access policy permits it.

Mandatory Duration Gate

Before starting a task, estimate the total duration from its stages. Include setup, network waits, tool calls, tests, retries, and cleanup. State the estimate in the task plan:

Forecast: about 45 seconds. Stages: research 20s, implementation 15s, verification 10s.
Notification: enabled because the forecast exceeds 30 seconds.

Use this skill when the forecast is greater than 30 seconds, or when the task has a meaningful chance of exceeding 30 seconds. Do not notify for routine steps that are clearly below the threshold. If the forecast changes and crosses the threshold, enable the notification plan then.

Send at most one useful completion, failure, or blocked-state notification unless the user asks for progress updates. Never claim success unless the notification command reports success.

Safety Gate

If the user asks to put a token in a repository, README, URL, shell history, command argument, environment file, ticket, prompt, or notification body, refuse that path and propose the platform credential store instead. Do not silently downgrade to plaintext storage.

Before sending, confirm:

• The server URL is HTTPS unless the user explicitly uses localhost or a protected local network and accepts the risk.
• The topic is user-selected and hard to guess. On public ntfy.sh, the topic name functions like a password.
• The token is absent from the message, logs, command arguments, URLs, and repository.
• The user is authorized to publish to the topic and server.
• Anonymous publishing is used only when the server owner explicitly allows it.

If any check fails, stop and explain what must be fixed. Do not send a notification through an unsafe fallback.

Configuration

Use these values conceptually:

NTFY_SERVER=https://ntfy.sh
NTFY_TOPIC=<user-selected-hard-to-guess-topic>
NTFY_TOKEN=<read from the OS credential store at runtime>

For a self-hosted server, replace NTFY_SERVER with its HTTPS base URL. The topic is appended to the server URL. A token is optional only when the server permits anonymous publishing. Never assume a self-hosted server is safe without checking its transport and access policy.

Secure Credential Setup

Store one publishing token under the service name ntfy-skill and the account name of the current user. Use a narrowly scoped token where the server supports it. Check each setup by retrieving only whether a value exists. Do not print the token.

macOS Keychain

Use the built-in security command. Leaving the password value empty makes Keychain prompt without putting the token in shell history:

security add-generic-password -U -a "$USER" -s ntfy-skill -w
security find-generic-password -a "$USER" -s ntfy-skill >/dev/null

If retrieval fails, open Keychain Access, find the ntfy-skill generic password in the login keychain, and confirm the account matches $USER. Never paste the token into a command line.

Linux Secret Service

Use secret-tool backed by GNOME Keyring, KWallet through Secret Service, or another approved Secret Service provider:

secret-tool store --label="ntfy skill token" service ntfy-skill account "$USER"
secret-tool lookup service ntfy-skill account "$USER" >/dev/null

If secret-tool is missing, install the distribution package that provides libsecret and Secret Service support, then retry. If no desktop keyring is available, stop and ask the user to choose an approved secret manager. Do not write the token to ~/.ntfy_token, .env, or a dotfile unless the user explicitly accepts the plaintext risk after a warning.

Windows Credential Storage

Prefer PowerShell SecretManagement with the SecretStore vault or an organization-approved Windows Credential Manager integration:

Install-Module Microsoft.PowerShell.SecretManagement -Scope CurrentUser
Install-Module Microsoft.PowerShell.SecretStore -Scope CurrentUser
Register-SecretVault -Name NtfyVault -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault
$token = Read-Host "ntfy token" -AsSecureString
Set-Secret -Name ntfy-skill -Secret $token -Vault NtfyVault
Get-Secret -Name ntfy-skill -Vault NtfyVault | Out-Null

Use the Windows Credential Manager GUI or an approved enterprise vault instead when SecretManagement is unavailable. Do not use cmdkey as a substitute for a retrievable secret unless the chosen integration can read it without exposing it in command history or logs.

Credential Troubleshooting

1. Confirm the server and topic without including the token.
2. Confirm the credential-store command exists.
3. Confirm the service and account names match exactly.
4. Retrieve metadata or a success status, never the secret itself.
5. Send a harmless test message to a private test topic.
6. If the server returns 401 or 403, check token scope and topic permissions.
7. If the server cannot be reached, check HTTPS, DNS, proxy, and firewall settings.
8. Revoke a leaked token immediately and create a replacement.

Sending

Use a local wrapper that reads the token from the credential store at runtime. The wrapper must fail closed when a token is required but unavailable, support NTFY_SERVER and NTFY_TOPIC, and report the HTTP result without echoing credentials.

"$SKILL_DIR/notify.sh" "The task completed successfully."

The standard cloud endpoint is https://ntfy.sh. Use a self-hosted endpoint only when the user supplies or approves it. Include concise status, task name, and next action in the message. Never include secrets, private source text, or full command output by default.

On Windows, run `.

Notification Content

• Completion: state what finished and where the result is.
• Failure: state that the task failed and identify the next diagnostic step.
• Blocked: state what input, approval, or credential is missing.
• Progress: use only when the user requested it or the task has a long known phase.

Ground-Truth Sources

• ntfy publishing documentation: HTTP publishing, topics, tokens, Basic auth, and HTTPS requirements.
• ntfy installation documentation: CLI and server installation paths.
• Apple Keychain command reference: security command usage.
• Microsoft SecretManagement documentation: PowerShell secret vault model.

The skill gives workflow guidance around these sources. It does not replace the server's access-control policy or the operating system's credential-store documentation.