home / skills / hoangnguyen0403 / agent-skills-standard / flutter-notifications

flutter-notifications skill

This skill implements push and local Flutter notifications using Firebase Cloud Messaging and flutter_local_notifications, handling foreground, background, and

npx playbooks add skill hoangnguyen0403/agent-skills-standard --skill flutter-notifications

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.5 KB

---
name: Flutter Notifications
description: Push notifications and local notifications for Flutter using Firebase Cloud Messaging and flutter_local_notifications.
metadata:
  labels: [flutter, notifications, fcm, firebase, push, local-notifications]
  triggers:
    files: ['**/*notification*.dart', '**/main.dart']
    keywords:
      [
        FirebaseMessaging,
        FlutterLocalNotificationsPlugin,
        FCM,
        notification,
        push,
      ]
---

# Flutter Notifications

## **Priority: P1 (OPERATIONAL)**

Push and local notifications interactions.

## Guidelines

- **Stack**: Use `firebase_messaging` (Push) + `flutter_local_notifications` (Local/Foreground).
- **Lifecycle**: Handle all 3 states explicitly: Foreground, Background, Terminated.
- **Permissions**: Prime users with a custom dialog explaining benefits _before_ system request.
- **Navigation**: Validate notification payload data strictly before navigating.
- **Badges**: Manually clear iOS app badges when visiting relevant screens.

[Implementation Details](references/implementation.md)

## Anti-Patterns

- **No Unconditional Permission**: Don't ask on startup without context.
- **No Missing State Handlers**: Forgetting `getInitialMessage()` breaks "open from terminated".
- **No Forgotten Badge Clear**: Leaving notifications un-cleared frustrates users.
- **No Direct Navigation**: Parsing JSON payloads without validation leads to crashes.

## Related Topics

flutter-navigation | mobile-ux-core | firebase/fcm

Overview

This skill provides practical guidance for implementing push and local notifications in Flutter apps using firebase_messaging and flutter_local_notifications. It focuses on reliable notification delivery across foreground, background, and terminated app states while preserving user experience and safety. The guidance emphasizes permissions, payload validation, and badge management to avoid common operational pitfalls.

How this skill works

The skill outlines using firebase_messaging for FCM push delivery and flutter_local_notifications for displaying notifications when the app is in the foreground or handling platform-specific features like badges. It insists on explicit handling for three lifecycle states: foreground (show local notification), background (message handler and tap actions), and terminated (getInitialMessage to detect opens). It also prescribes a pre-permission UX dialog, strict payload validation before navigation, and manual iOS badge clearing where appropriate.

When to use it

When you need consistent push notification behavior across Android and iOS.
When foreground messages must be shown with custom UI or sound.
When users should be prompted for notification permission with context.
When navigation on notification tap requires validated payloads.
When your app manages iOS badges that must be cleared manually.

Best practices

Use firebase_messaging for remote delivery and flutter_local_notifications for foreground/local display and platform features.
Show a custom in-app dialog explaining benefits before calling the system permission prompt.
Implement handlers for foreground, background, and terminated states; call getInitialMessage() to catch terminated opens.
Validate notification payload JSON thoroughly before using it to navigate or update UI.
Clear iOS app badges manually when users view the related content to avoid stale counts.
Avoid unconditional permission requests on startup; tie the request to a clear user action or context.

Example use cases

A news app that shows breaking-story alerts while the app is open and navigates to the article after validating the payload.
A messaging app that displays in-app notifications with sound and updates the chat screen when tapped from background or terminated state.
An e-commerce app that prompts users for notification permission with an explanation before showing promotional push messages.
An appointment app that ensures badge counts reflect only unread items and clears badges when the appointments screen is viewed.

FAQ

How do I handle opens from a terminated app?

Call getInitialMessage() on startup to detect the message that opened the app and route after validating its payload.

Should I ask for notification permission immediately?

No. Show a short in-app dialog explaining benefits and request permission only after the user understands why notifications help.