| name | notifications |
| description | Use when creating, updating, reviewing, or debugging notifications, email, SMS, push messages, templates, delivery status, retries, user preferences, or notification security. |
Notifications
Use this skill for safe and reliable notification flows.
Rules
- Follow the project’s existing notification pattern.
- Do not add a new email, SMS, push, queue, or template provider unless already used or explicitly requested.
- Keep notification sending outside critical request paths when the project supports background jobs.
- Use templates for reusable messages.
- Validate recipients and required template data.
- Avoid duplicate sends with idempotency when retries or webhooks are involved.
- Track delivery status when the project has a notification record model.
- Respect user notification preferences for non-critical messages.
- Always allow critical security, billing, and account notifications when required.
- Never log full emails, phone numbers, tokens, reset links, magic links, or private message content.
- Preserve existing response, error, logging, and test patterns.
- Avoid unrelated refactors.
Inspect First
Before changing notification code, check existing patterns for:
- provider
- template system
- queue/background job usage
- delivery records
- retry behavior
- recipient validation
- user preferences
- logging/redaction
- test style
Implementation Checklist
- Identify the notification type and channel.
- Reuse existing service/provider/template helpers.
- Validate recipient and payload.
- Render message from the existing template pattern.
- Send immediately only if the project already does that safely.
- Prefer async/background sending when available.
- Make retries safe.
- Prevent duplicate delivery.
- Store delivery status if the project supports it.
- Mask recipient data in logs.
- Add or update relevant tests.
Security Checklist
- Do not expose secrets or provider keys.
- Do not log reset links, verification links, OTP codes, or magic links.
- Do not send sensitive content to an unverified recipient unless the project allows it.
- Do not let users send notifications to resources they do not own.
- Do not ignore opt-out preferences for marketing or non-critical messages.
- Keep critical notifications safe, minimal, and reliable.
Failure Handling
- Invalid recipient: fail safely and do not retry endlessly.
- Provider failure: retry only if safe and supported.
- Template missing: fail clearly.
- Duplicate request: skip or reuse existing delivery record.
- Rate limit: back off when the project supports it.
- Partial failure: record the failed channel without hiding the error.
Tests
Cover relevant paths:
- notification created or queued
- template renders correctly
- invalid recipient
- provider failure
- retry or duplicate prevention
- preference opt-out
- critical notification still allowed
- sensitive data not logged