OpenParable
Skip to content
← Back to skills

Shiny Notifications

Development
shiny-notifications

Shiny Notifications is an Agent Skill for development published in the shinyorg/shiny repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Cross-platform local notification management for .NET MAUI apps using Shiny, supporting scheduled, repeating, and geofence-triggered notifications with channels, badges, and interactive actions.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/shinyorg/shiny/blob/HEAD/skills/shiny-notifications/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/shiny-notifications, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Shiny Notifications

When to Use This Skill

Use this skill when the user needs to:

  • Send local notifications (immediate, scheduled, repeating, or geofence-triggered)
  • Manage notification channels with importance levels, sounds, and actions
  • Handle notification tap responses and interactive action buttons
  • Request notification permissions on iOS and Android
  • Manage app icon badge counts
  • Configure platform-specific notification behavior (Android ongoing, iOS subtitles, etc.)

Library Overview

ItemValue
NuGet PackageShiny.Notifications (iOS, Mac Catalyst, Android, macOS, Windows); Shiny.Notifications.Linux (Linux)
Primary NamespaceShiny.Notifications
Registration NamespaceShiny (extension methods on IServiceCollection)
PlatformsiOS, Mac Catalyst, Android, macOS, Windows, Linux
DependenciesShiny.Core, Shiny.Locations, Shiny.Support.Repositories

Linux

Linux notifications ship in a separate package, Shiny.Notifications.Linux. They are delivered via the freedesktop org.freedesktop.Notifications D-Bus service (GNOME, KDE, XFCE, etc.) and support the same INotificationManager API surface as the other platforms. Scheduled notifications are tracked in-process only — there is no OS-level scheduler like BGTaskScheduler or WorkManager, so the host process must be running for a scheduled notification to fire. Channels are exposed but only a subset of freedesktop hints (urgency, category, image) are actually honoured by most daemons. Geofence triggers and time-sensitive flags are not applicable.

Register with services.AddNotifications<TDelegate>(); from the Shiny namespace — the same call site as the other platforms.

Setup

Register the notification services in your MauiProgram.cs:

using Shiny;

// Without a delegate (fire-and-forget notifications)
services.AddNotifications();

// With a delegate to handle notification taps
services.AddNotifications<MyNotificationDelegate>();

On iOS, you can optionally pass an IosConfiguration to control authorization and presentation options:

#if IOS || MACCATALYST
services.AddNotifications<MyNotificationDelegate>(new IosConfiguration(
    UNAuthorizationOptions: UNAuthorizationOptions.Alert | UNAuthorizationOptions.Badge | UNAuthorizationOptions.Sound,
    PresentationOptions: UNNotificationPresentationOptions.Banner | UNNotificationPresentationOptions.Badge | UNNotificationPresentationOptions.Sound
));
#endif

Code Generation Instructions

When generating code that uses Shiny Notifications, follow these conventions:

  1. Always request access before sending notifications:

    var access = await notificationManager.RequestAccess();
    if (access != AccessState.Available)
    {
        // Handle denied permission
        return;
    }
    
  2. Use AccessRequestFlags when the notification uses triggers:

    • AccessRequestFlags.TimeSensitivity for scheduled or repeating notifications.
    • AccessRequestFlags.LocationAware for geofence-triggered notifications.
    • Or use the RequestRequiredAccess extension method that infers flags from the notification object.
  3. A Notification must have a Message set -- validation will throw otherwise.

  4. Only one trigger type per notification -- you cannot mix ScheduleDate, RepeatInterval, and Geofence on the same notification.

  5. Implement INotificationDelegate for handling user taps:

    public class MyNotificationDelegate : INotificationDelegate
    {
        public async Task OnEntry(NotificationResponse response)
        {
            // response.Notification -- the original notification
            // response.ActionIdentifier -- which action button was pressed
            // response.Text -- text reply if action was TextReply type
        }
    }
    
  6. Create channels before sending notifications that reference them:

    notificationManager.AddChannel(new Channel
    {
        Identifier = "alerts",
        Importance = ChannelImportance.High,
        Sound = ChannelSound.High
    });
    
  7. Use the convenience Send extension for simple notifications:

    await notificationManager.Send("Title", "Message body");
    
  8. For platform-specific properties, use the native subclasses:

    • Android: AndroidNotification and AndroidChannel
    • iOS: AppleNotification and AppleChannel
  9. Always inject INotificationManager via constructor injection -- never create instances directly.

  10. Use CancelScope wisely when cancelling:

    • CancelScope.DisplayedOnly -- clears only shown notifications.
    • CancelScope.Pending -- clears only scheduled/triggered notifications.
    • CancelScope.All -- clears everything (default).

Namespace Ambiguities

  • Notification: Both Shiny.Notifications and Shiny.Push define a Notification type. If both packages are referenced in the same project, do NOT add both namespaces as global usings. Use Shiny.Notifications.Notification FQN or a file-level using Shiny.Notifications; directive to disambiguate.

Best Practices

  • Always check the AccessState result before attempting to send notifications.
  • Use channels to group notifications by category (e.g., "alerts", "reminders", "messages").
  • The default channel (Channel.Default) always exists with Identifier = "Notifications" and ChannelImportance.Low.
  • Do not remove the default channel -- the library will throw an InvalidOperationException.
  • Set BadgeCount only on immediate notifications (not triggered ones) -- validation will fail otherwise.
  • Use IntervalTrigger with either Interval (raw TimeSpan) or TimeOfDay (daily/weekly recurring), never both.
  • For geofence notifications, ensure Center and Radius are both set on GeofenceTrigger.
  • On Android, create a drawable resource named notification for the default small icon, or set SmallIconResourceName on AndroidNotification.
  • Prefer the RequestRequiredAccess extension method to automatically determine needed permission flags from a Notification object.
  • Use Payload dictionary on Notification to pass custom data that you can read back in your INotificationDelegate.OnEntry.

AI Tool Integration (Shiny.Notifications.Extensions.AI)

The optional Shiny.Notifications.Extensions.AI package exposes INotificationManager as reminder-framed Microsoft.Extensions.AI tool functions (AIFunctions) for LLM agents. You opt-in exactly which operations the model can see — a read/write allow-list you control on behalf of the agent (not an OS permission prompt; the platform notification permission must already be granted). Read-only by default; write is opt-in. AOT-compatible (hand-built schemas, JsonNode results — no reflection).

using Shiny.Notifications;
using Shiny.Notifications.Extensions.AI;

builder.Services.AddNotifications();                             // registers INotificationManager
builder.Services.AddNotificationAITools(tools => tools
    .AddReminders(ReminderAICapabilities.ReadWrite, channel: "reminders")   // channel is optional
);

// resolve the bundle and pass the tools to any IChatClient
var tools = sp.GetRequiredService<NotificationAITools>().Tools;
var response = await chatClient.GetResponseAsync(
    messages,
    new ChatOptions { Tools = [.. tools] }
);

Key types:

  • AddNotificationAITools(Action<INotificationAIToolBuilder>) — DI extension; throws if nothing is added.
  • INotificationAIToolBuilder — AddReminders(ReminderAICapabilities, string? channel = null). The channel (if supplied) must already be registered via AddChannel.
  • ReminderAICapabilities [Flags] — None, Read (default), Write, ReadWrite.
  • NotificationAITools — resolve from DI; .Tools is IReadOnlyList<AITool>.

Generated tools (only for opted-in capabilities): list_reminders (pending/scheduled), create_reminder (omit both scheduleFor/repeatDailyAt to send now, scheduleFor for a one-time reminder, repeatDailyAt "HH:mm" for a daily one), cancel_reminder (by id). scheduleFor and repeatDailyAt are mutually exclusive; dates are ISO-8601.

The AI tools assume permissions are already granted — they do not trigger the platform permission UI (needs a foreground activity). Call INotificationManager.RequestAccess(...) from the app before invoking the agent.

Reference Files