clix-so avatar

push-notification-best-practices

Comprehensive push notification guide for iOS (APNS) and Android (FCM). Use for setup, debugging delivery issues, implementing handlers, token management, deep linking, and troubleshooting platform-specific issues.

GitHub stars
5

Install

/plugin install push-notification-best-practices@clix-agent-skills

Run it inside Claude Code after adding the marketplace with /plugin marketplace add clix-so/skills.

Contents

Discovered from source

Skills 10

API-Triggered Campaigns (Backend → Clix)

Use this skill to set up API-triggered campaigns in the Clix console and trigger them from your backend with dynamic data (trigger.*) for:

  • Transactional notifications (orders, password reset, receipts)
  • Workflow messages (assignments, approvals)
  • System alerts (moderation, support tickets)
  • Programmatic sends where marketers/ops should control content + targeting

What the official docs guarantee (high-signal)

  • API-triggered campaigns are configured in the console, then triggered via: POST /api/v1/campaigns/{campaign_id}:trigger
  • Authentication uses secret headers:
    • X-Clix-Project-ID
    • X-Clix-API-Key
  • Request properties become trigger.* for:
    • Dynamic audience filtering (console audience rules)
    • Personalization in templates (title/body/deep links)
  • audience.broadcast=true sends to all users eligible under the campaign’s segment definition; audience.targets narrows to specific users/devices (still filtered by the segment definition).
  • Dynamic audience filters are intentionally constrained for performance: max 3 attributes in the audience definition.

MCP-first (source of truth)

If Clix MCP tools are available, treat them as the source of truth:

  • Use clix-mcp-server:search_docs to confirm the latest API contract + limits:
    • query examples:
      • "API-triggered campaign trigger endpoint"
      • "campaigns/{campaign_id}:trigger audience targets broadcast"
      • "trigger.* dynamic audience filters limitations"

If MCP tools are not available, use the bundled references:

  • API contract → references/api-contract.md
  • Console setup + dynamic filters → references/console-setup.md
  • Backend patterns (auth, retries, timeouts) → references/backend-patterns.md
  • Security/key handling → references/security-and-keys.md
  • Personalization + dynamic filters → references/personalization-and-dynamic-filters.md
  • Debugging checklist → references/debugging.md

Workflow (copy + check off)

API-triggered campaign progress:
- [ ] 1) Confirm goals + trigger source (what backend event sends the message?)
- [ ] 2) Define campaign contract (properties keys/types; PII policy)
- [ ] 3) Configure campaign in console (API-triggered + audience rules + templates)
- [ ] 4) Implement backend trigger wrapper (auth, timeout, retries, logging)
- [ ] 5) Validate trigger plan JSON (schema + naming + safety)
- [ ] 6) Verify in Clix (test payloads, Message Logs, segment matching)

1) Confirm the minimum inputs

Ask only what’s needed:

  • Campaign: where is it in the console? do you already have campaign_id?
  • Channel: push / in-app / email / etc. (affects message template fields)
  • Audience mode: broadcast vs explicit targets
  • Dynamic filter keys: which trigger.* keys are used in audience rules
  • Properties: list of keys + types + example values (avoid PII by default)
  • Backend: runtime and HTTP client (Node/Fetch, Axios, Python, Go, etc.)

2) Create a “Trigger Plan” (before touching backend code)

Create api-trigger-plan.json in .clix/ (recommended) or project root.

Recommended location: .clix/api-trigger-plan.json

Plan schema (high-level):

  • campaign_id (string)
  • audience.mode: "broadcast" | "targets" | "default"
  • audience.targets (if mode is "targets")
  • dynamic_filter_keys (array of up to 3 snake_case keys)
  • properties (map of snake_case keys → { type, required?, example?, pii? })

Example:

{
  "campaign_id": "019aa002-1d0e-7407-a0c5-5bfa8dd2be30",
  "audience": {
    "mode": "broadcast"
  },
  "dynamic_filter_keys": ["store_location"],
  "properties": {
    "store_location": {
      "type": "string",
      "required": true,
      "example": "San Francisco"
    },
    "order_id": { "type": "string", "required": true, "example": "ORD-12345" },
    "item_count": { "type": "number", "required": true, "example": 3 },
    "pickup_time": { "type": "string", "required": false, "example": "2:30 PM" }
  }
}

3) Configure campaign in the console (API-triggered)

  • Set the campaign type to API-Triggered.
  • Build audience rules using {{ trigger.* }} for dynamic filters.
  • Use {{ trigger.* }} in message templates + deep links.

See: references/console-setup.md for exact guidance and limitations.

4) Implement backend trigger wrapper (best practices)

Backend wrapper responsibilities:

  • Auth: load X-Clix-Project-ID and X-Clix-API-Key from environment/secret store (never commit).
  • Timeout: set a short timeout (e.g., 3–10s) and fail fast.
  • Retries: retry only on transient failures (network/5xx), with backoff; do not retry blindly on 4xx.
  • Dedupe: prevent double-sends in your system (e.g., unique key per order event) since the API call is “send-like”.
  • Logging: log campaign_id, your correlation id (order id), and the Clix response (e.g., trigger_id).

Copy/paste examples:

  • Node: examples/trigger-campaign-node.js
  • Python: examples/trigger-campaign-python.py

5) Validate the plan (fast feedback loop)

Run:

bash <skill-dir>/scripts/validate-api-trigger-plan.sh .clix/api-trigger-plan.json

This validator checks:

  • valid JSON
  • campaign_id present
  • dynamic_filter_keys is ≤ 3 and snake_case
  • properties keys are snake_case and have valid types
  • example values match declared types
  • targets entries specify exactly one of project_user_id or device_id

6) Verify (Clix + end-to-end)

Minimum verification:

  • Campaign is API-Triggered and campaign_id matches.
  • If using dynamic audience filters, the trigger.* keys exist in the API call and match audience rules exactly.
  • Trigger once with a known-good payload; confirm delivery + inspect Message Logs for rendering errors.

See references/debugging.md.

Progressive Disclosure

  • Level 1: This SKILL.md (always loaded)
  • Level 2: references/ (load when implementing details)
  • Level 3: examples/ (load when copy/pasting backend code)
  • Level 4: scripts/ (execute directly; do not load into context)

References

  • references/api-contract.md
  • references/console-setup.md
  • references/backend-patterns.md
  • references/security-and-keys.md
  • references/personalization-and-dynamic-filters.md
  • references/debugging.md

Auditing Deep Link Contracts

Use this skill to define and audit deep link behavior so links open the correct screen with correct parameters across cold and warm starts.

What this skill does

  • Defines a deep link contract for supported routes
  • Checks required and optional parameters
  • Generates cold and warm start test vectors
  • Produces a concise audit report with fixes

Workflow

Deep link contract audit progress:

- [ ] 1) Confirm minimum inputs (platforms, routes, entry points)
- [ ] 2) Draft a deep-link contract (JSON)
- [ ] 3) Validate the contract (script)
- [ ] 4) Generate test vectors (script)
- [ ] 5) Audit routing behavior (findings + fixes)
- [ ] 6) Verify fixes (cold and warm start)

1) Confirm the minimum inputs

Ask only what is needed:

  • Platforms: iOS, Android, or both
  • Entry points: push, email, web, in-app, marketing campaigns
  • Routes: list of deep link routes that must be supported
  • Auth rules: which routes require login
  • Fallbacks: where to send users if data is missing

2) Draft a deep-link contract

Create deep-link-contract.json in .mobile/ (recommended) or project root.

Recommended location: .mobile/deep-link-contract.json

Example:

{
  "base": "myapp://",
  "routes": [
    {
      "name": "order_detail",
      "path": "/orders/{order_id}",
      "required_params": ["order_id"],
      "optional_params": ["ref"],
      "auth_required": true,
      "supported_states": ["cold", "warm"]
    }
  ]
}

3) Validate the contract

Run:

bash skills/auditing-deep-link-contracts/scripts/validate-deep-link-contract.sh \
  .mobile/deep-link-contract.json

4) Generate test vectors

Run:

bash skills/auditing-deep-link-contracts/scripts/generate-deep-link-test-vectors.sh \
  .mobile/deep-link-contract.json \
  .mobile/deep-link-test-vectors.json

5) Audit routing behavior

For each test vector, confirm:

  • The app opens the expected screen
  • Required parameters are present and parsed
  • Missing parameters trigger the expected fallback
  • Auth-required routes handle logged-out users
  • Cold start and warm start behave consistently

6) Verify fixes

Re-run the test vectors after changes and confirm all expected behaviors.

Progressive Disclosure

  • Level 1: This SKILL.md
  • Level 2: references/
  • Level 3: examples/ (optional)
  • Level 4: scripts/ (execute; do not load)

References

  • references/deep-link-contract.md

Auditing Permission UX

Use this skill to audit how a mobile app requests notification permission and guides users to settings, then produce actionable improvements based on Apple and Android best practices.

What this skill does

  • Reviews permission timing, context, and explanation quality
  • Checks denial handling and settings recovery paths
  • Flags platform-specific risks (iOS vs Android)
  • Produces a structured audit report with fixes

Workflow

Permission UX audit progress:

- [ ] 1) Confirm minimum inputs (platforms, flow, current UX)
- [ ] 2) Audit current flow (map prompts, copy, and settings paths)
- [ ] 3) Produce audit report (findings + fixes)
- [ ] 4) Verify improvements (ensure UX changes align with platform rules)

1) Confirm the minimum inputs

Ask only what is needed:

  • Platforms: iOS, Android, or both
  • Entry points: where the app asks for permission
  • Prompt timing: first launch, after action, onboarding step, etc.
  • Primer: is there an in-app explanation before the system prompt
  • Settings path: how users enable later after denial
  • Denial handling: how the app behaves if permission is denied

2) Audit the current flow

Document the current permission flow directly from the app:

  • Where the permission prompt appears and what precedes it
  • What copy is shown to explain value
  • How the app behaves after deny or dismiss
  • How users can enable notifications later

3) Produce the audit report

Output a concise report in markdown with:

  • Findings: each gap mapped to best practice
  • Risk: what the user impact is
  • Fix: concrete UX change
  • Platform notes: iOS-only or Android-only specifics

Optional: generate a report template:

bash skills/auditing-permission-ux/scripts/generate-permission-ux-audit-report.sh .mobile/permission-ux-audit.md

4) Verify improvements

Confirm:

  • Prompt timing is contextual (not forced on first launch)
  • Primer explains value clearly and is dismissible
  • Denied users can still use the app
  • Settings path is discoverable and clear
  • Android importance/channel strategy is not misleading

Progressive Disclosure

  • Level 1: This SKILL.md
  • Level 2: references/
  • Level 3: examples/ (optional)
  • Level 4: scripts/ (execute; do not load)

References

  • references/permission-ux-best-practices.md

Tracking Clix Events

Use this skill to help developers design and implement Clix event tracking via Clix.trackEvent(...) so events can drive event-triggered campaigns, audience filters, and personalization.

What the official docs guarantee (high-signal)

  • When to track: identify the user action/system event, then attach meaningful properties (funnel checkpoints, milestones, button taps).
  • Property normalization: booleans/numbers/strings map directly; date-like values serialize to ISO 8601; unsupported objects become strings.
  • Error handling: event tracking calls can throw—always handle errors so the app stays robust.

MCP-first (source of truth)

If Clix MCP tools are available, treat them as the source of truth:

  • clix-mcp-server:search_docs for conceptual behavior (campaign triggers, personalization)
  • clix-mcp-server:search_sdk for exact SDK signatures per platform

If MCP tools are not available, use the bundled references:

  • Event API contract + pitfalls → references/trackevent-contract.md
  • Naming + schemas + privacy → references/naming-and-schema.md
  • Implementation patterns → references/implementation-patterns.md
  • Campaign mapping → references/campaign-mapping.md
  • Debugging checklist → references/debugging.md

Workflow (copy + check off)

Event tracking progress:
- [ ] 1) Confirm platform(s) and goals (analytics vs campaign triggers)
- [ ] 2) Propose event plan (names, when fired, properties, where in code)
- [ ] 3) Validate plan (names, keys, types, PII constraints)
- [ ] 4) Implement trackEvent calls (platform-correct)
- [ ] 5) Verify: events fire once, serialize cleanly, match campaign configs

1) Confirm the minimum inputs

Ask only what’s needed:

  • Platform: iOS / Android / React Native / Flutter
  • Goal: analytics only, event-triggered campaigns, or both
  • Top flows (1–3): e.g., onboarding, checkout, subscription
  • PII policy: what must never be sent (email/phone/name/free-text, etc.)

2) Propose an “Event Plan” (before touching code)

Return a compact table the user can approve:

  • event_name (stable, snake_case)
  • when (exact moment the event fires)
  • properties (key + type, mark required vs optional)
  • location (file/function/UI handler/network response)
  • purpose (campaign trigger / analytics / both)

If campaigns are involved, remind: event names and property keys must match exactly in the Clix console.

3) Validate the plan (fast feedback loop)

Create event-plan.json in .clix/ directory (recommended) or project root:

Recommended location: .clix/event-plan.json

  • Organized: keeps tooling configs together
  • Hidden: doesn't clutter project root
  • Committable: planning document for team review

Alternative: event-plan.json in project root (simpler, but less organized)

For agents: Locate scripts/validate-event-plan.sh in the installed skill directory, then run it:

# From project root:
bash <skill-dir>/scripts/validate-event-plan.sh .clix/event-plan.json
# Or if in root:
bash <skill-dir>/scripts/validate-event-plan.sh event-plan.json

The skill directory is typically:

  • .cursor/skills/event-tracking/ (Cursor)
  • .claude/skills/event-tracking/ (Claude Code)
  • .vscode/skills/event-tracking/ (VS Code)
  • .agents/skills/event-tracking/ (Amp)
  • Or check where this skill was installed

If validation fails: fix the plan first, then implement.

4) Implement tracking (platform-correct)

Use MCP to fetch the exact trackEvent signature for the platform; then:

  • Place calls at stable boundaries (action confirmed, request succeeded, state updated)
  • Avoid duplicates (don’t fire on every render; debounce where needed)
  • Avoid null/complex values (prefer primitives; serialize dates to ISO)
  • Do not track PII by default

See references/implementation-patterns.md for placement heuristics and code patterns.

5) Verify

Minimum verification:

  • Event fires exactly once per user action (or the intended cadence)
  • Properties are primitive + stable (no null surprises)
  • For campaigns: console trigger conditions match exact names/keys

For troubleshooting steps, see references/debugging.md.

Clix SDK Integration Skill

This skill provides comprehensive guidance for integrating Clix analytics SDK into mobile applications. Follow the workflow below to ensure proper installation and configuration.

Integration Strategy (MCP First)

This skill follows an "MCP First" strategy to ensure agents always use the latest verified SDK source code.

Step 1: Check for MCP Capability

  • Check if the Clix MCP Server tools (clix-mcp-server:search_sdk, clix-mcp-server:search_docs) are available in your toolset.

Step 2: Primary Path (MCP Available)

  • MUST use clix-mcp-server:search_sdk to fetch exact initialization code for the target platform (e.g., clix-mcp-server:search_sdk(query="initialize", platform="android")).
  • Use these fetched results as the Single Source of Truth for implementation.
  • Do NOT rely on static examples if MCP returns valid results.

Step 3: Fallback Path (MCP Unavailable)

  • If checks for clix-mcp-server fail:
    1. Ask the user: "The Clix MCP Server is not detected. It provides the latest official SDK code. Would you like me to install it now?"
    2. If User says YES:
      • Run: bash scripts/install-mcp.sh --client <your-client>
      • The script will:
        • Verify the package is available
        • Configure the MCP server for the specified client
        • (If you omit --client and multiple clients are installed, the script will stop and ask you to choose.)
        • Automatically configure the MCP server in the appropriate config file
        • Provide clear instructions for restart
      • Instruct user to restart their agent/IDE to load the new server.
      • Stop here (let user restart).
    3. If User says NO:
      • Fall back to using the static patterns in references/framework-patterns.md and examples/.
      • Inform the user: "Proceeding with static fallback examples (may be outdated)."

Interaction Guidelines for Agents

When using this skill (for example inside OpenCode, Amp, Claude Code, Codex, Cursor, or other AI IDEs), follow these behaviors:

  • Start with reconnaissance
    • Inspect the project structure first (list key files like package.json, Podfile, build.gradle, pubspec.yaml, AppDelegate.swift, MainActivity.kt, etc.)
    • Clearly state what you detected (e.g., “This looks like a React Native project with iOS and Android”)
  • Ask clarifying questions when needed
    • If multiple platforms are present, ask the user which one(s) to integrate first
    • If the structure is unusual, ask before making assumptions
  • Explain each step briefly
    • Before making changes, say what you are about to do and why (install dependency, update entrypoint, add config, etc.)
    • Keep explanations short but concrete, so the user understands the impact
  • Handle errors gracefully
    • If a command or change fails, show the error, explain likely causes, and suggest concrete next steps
    • Avoid getting stuck in loops—propose a fallback if automation fails
  • End with a verification summary
    • Summarize what was installed/modified (files touched, dependencies added)
    • Point out any remaining manual steps (e.g., Xcode capabilities, Firebase config, running the app to test)

Integration Workflow

Phase 1: Prerequisite — Credentials (User Setup)

Before continuing, the user must ensure the following environment variables are available to the app at runtime:

  • CLIX_PROJECT_ID
  • CLIX_PUBLIC_API_KEY

How to get credentials:

  • Ask the user to visit https://console.clix.so/ and copy the values for their Clix project.

How to set credentials:

  • Add them to a local .env file (recommended), or to your framework’s env configuration (see references/framework-patterns.md).
  • Ensure .env is in .gitignore.

Security warning:

  • Do not paste credentials into chat. Enter them directly into the user’s terminal/editor.

Phase 2: Project Type Detection

Step 2.1: Identify Platform

Examine the codebase structure to determine platform:

  • iOS: Look for .xcodeproj, Podfile, Info.plist, Swift/Objective-C files
  • Android: Look for build.gradle, AndroidManifest.xml, Kotlin/Java files
  • Flutter: Look for pubspec.yaml, lib/main.dart, plus ios/ and android/ folders
  • React Native: Look for package.json with React Native dependencies, android/ and ios/ folders
  • Other: If it’s not one of the above, stop and ask the user—this skill is mobile-only.

Priority rule (important): If React Native or Flutter is detected, treat it as the primary platform even if native ios/ and android/ folders exist.

Step 2.2: Verify Detection

Confirm platform detection with user if ambiguous:

  • Multiple platforms detected (e.g., React Native has both iOS and Android)
  • Unusual project structure
  • Hybrid applications

Phase 3: SDK Installation

Step 3.1: Install SDK Package

Install the appropriate SDK based on detected platform:

iOS (Swift Package Manager):

// Add to Package.swift or Xcode: https://github.com/clix-so/clix-ios-sdk

iOS (CocoaPods):

# Add to Podfile
pod 'Clix', :git => 'https://github.com/clix-so/clix-ios-sdk.git'

Android (Gradle):

// Add to build.gradle.kts
implementation("so.clix:clix-android-sdk:latest")

React Native:

npm install @clix-so/react-native-sdk
# or
yarn add @clix-so/react-native-sdk

Flutter:

  • Add the Clix Flutter SDK dependency in pubspec.yaml:
    dependencies:
      clix_flutter: ^0.0.1
      firebase_core: ^3.6.0
      firebase_messaging: ^15.1.3
    
  • If MCP tools (search_docs, search_sdk) are available, use them to confirm the latest package version and setup steps.

Step 3.2: Verify Installation

  • Check that package appears in dependency files (package.json, Podfile.lock, build.gradle)
  • Verify import/require statements work
  • Check for installation errors

Phase 4: SDK Initialization

Step 4.1: Locate Entry Point

Find the appropriate initialization location:

  • iOS: AppDelegate.swift or @main app file
  • Android: Application.kt or Application.java class
  • Flutter: lib/main.dart
  • React Native: Root component or index.js

Step 4.2: Initialize SDK

Add initialization code following platform-specific patterns (see examples/ directory):

Key Requirements:

  • Initialize early in application lifecycle
  • Use environment variables for credentials (never hardcode)
  • Handle initialization errors gracefully
  • Follow framework-specific best practices

Step 4.3: Configure SDK

Set up SDK configuration:

  • Use CLIX_PROJECT_ID from environment variables
  • Use CLIX_PUBLIC_API_KEY from environment variables
  • Set appropriate environment (production/staging/development)
  • Configure logging level if needed
  • Enable/disable features as required

Phase 5: Integration Verification

Step 5.1: Code Review

Verify integration completeness:

  • SDK is imported/required correctly
  • Initialization code is in correct location
  • Credentials are loaded from environment variables
  • Error handling is implemented
  • No hardcoded credentials

Step 5.2: Verify Integration

Run validation checks:

  • Execute scripts/validate-sdk.sh if available
  • Check that SDK initializes without errors
  • Verify environment variables are accessible
  • Verify SDK is properly imported and initialized

Platform Verification Checklists (UI Steps → Repo Verification)

Use these checklists to verify manual UI steps were actually completed.

iOS Verification
  • Dependencies present: Podfile/Podfile.lock or SwiftPM/Xcode references
  • Entitlements present: an *.entitlements file exists and is wired to the correct target(s)
  • Capabilities configured: project.pbxproj reflects required capabilities (as applicable to Push Notifications / Background Modes)
Android Verification
  • Dependencies present: module-level build.gradle / build.gradle.kts includes required SDK dependencies
  • Manifest updated: AndroidManifest.xml contains required permissions, services/receivers (as required by the SDK)
  • Firebase config placed (if used): google-services.json exists in the expected module directory (commonly app/)
React Native Verification
  • JS dependency: package.json includes the Clix package
  • iOS native: ios/Podfile.lock updated after pod install (when required)
  • Android native: Gradle + Manifest updates present if required by the SDK
  • Initialization: root entrypoint initializes the SDK exactly once
Flutter Verification
  • Pub dependency: pubspec.yaml includes the required packages and pubspec.lock is updated after flutter pub get
  • iOS native: ios/Podfile.lock updated after pod install (when required)
  • Android native: Gradle + Manifest updates present if required
  • Initialization: SDK initialized before runApp

Step 5.3: Documentation

Create or update documentation:

  • Add integration notes to README.md
  • Document environment variables needed
  • Note any framework-specific considerations
  • Update .env.example if it exists

Framework-Specific Patterns

iOS (Swift)

Initialization Pattern:

import Clix

@main
struct MyApp: App {
    init() {
        // Load credentials from your app configuration (do NOT hardcode).
        // Example: store values in Info.plist keys.
        let projectId = Bundle.main.object(forInfoDictionaryKey: "CLIX_PROJECT_ID") as? String ?? ""
        let apiKey = Bundle.main.object(forInfoDictionaryKey: "CLIX_PUBLIC_API_KEY") as? String

        let config = ClixConfig(projectId: projectId, apiKey: apiKey)
        Clix.initialize(config: config)
    }
}

Key Points:

  • Initialize in @main app struct or AppDelegate
  • Use environment variables, never hardcode
  • Handle optional API key for analytics-only mode

Android (Kotlin)

Initialization Pattern:

import so.clix.core.Clix
import so.clix.core.ClixConfig

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()

        // Load credentials from BuildConfig (do NOT hardcode).
        val config = ClixConfig.Builder()
            .projectId(BuildConfig.CLIX_PROJECT_ID)
            .apiKey(BuildConfig.CLIX_PUBLIC_API_KEY)
            .build()

        Clix.initialize(this, config)
    }
}

Key Points:

  • Initialize in Application.onCreate()
  • Use Application context, not Activity context
  • Register Application class in AndroidManifest.xml

React Native

Initialization Pattern:

import { Clix } from "@clix-so/react-native-sdk";
import Config from "react-native-config";

// In App.tsx or index.js
Clix.initialize({
  projectId: Config.CLIX_PROJECT_ID || "",
  apiKey: Config.CLIX_PUBLIC_API_KEY,
});

Key Points:

  • Initialize in root component
  • Use react-native-config (or similar) for environment variables
  • Link native dependencies if needed

Flutter

Initialization Pattern:

import 'package:clix_flutter/clix_flutter.dart';

Future<void> main() async {
  // Load credentials from build-time configuration (do NOT hardcode).
  // Example:
  // flutter run --dart-define=CLIX_PROJECT_ID=... --dart-define=CLIX_PUBLIC_API_KEY=...
  const projectId = String.fromEnvironment('CLIX_PROJECT_ID');
  const apiKey = String.fromEnvironment('CLIX_PUBLIC_API_KEY');

  await Clix.initialize(
    ClixConfig(
      projectId: projectId,
      apiKey: apiKey,
    ),
  );

  runApp(const MyApp());
}

Key Points:

  • Initialize before runApp
  • Use --dart-define (or your chosen secret mechanism), never hardcode

Error Handling

Common Issues:

  1. Missing Credentials

    • Error: SDK fails to initialize
    • Solution: Verify .env file exists and contains required variables
    • Check: Environment variable names match exactly
  2. Wrong Initialization Location

    • Error: SDK not tracking events
    • Solution: Ensure initialization happens before any SDK usage
    • Check: Initialization is in app entry point, not a component
  3. Environment Variables Not Loading

    • Error: undefined or empty values
    • Solution: Verify env loading mechanism (dotenv, framework config, etc.)
    • Check: Variable names match framework requirements (prefixes)

Best Practices

  1. Never hardcode credentials - Always use environment variables
  2. Initialize early - SDK should initialize before app starts or as early as possible
  3. Handle errors gracefully - Wrap initialization in try-catch blocks
  4. Use appropriate environment - Set production/staging/development based on build
  5. Verify integration - Use validation scripts to verify SDK is properly integrated
  6. Document changes - Update README and configuration files
  7. Version control - Add .env to .gitignore, commit .env.example

Docs Usage Note (MCP vs Static vs Web Docs)

  • If MCP tools are available: treat search_sdk results as the source of truth for initialization/API usage.
  • If MCP tools are unavailable: you may reference the official quickstarts below for manual steps, and use examples/ + references/ for code patterns.

Official quickstarts:

  • iOS: https://docs.clix.so/sdk-quickstart-ios
  • Android: https://docs.clix.so/sdk-quickstart-android
  • React Native: https://docs.clix.so/sdk-quickstart-react-native
  • Flutter: https://docs.clix.so/sdk-quickstart-flutter

Progressive Disclosure

  • Level 1: This SKILL.md file (always loaded)
  • Level 2: references/ directory (loaded when needed for specific topics)
  • Level 3: examples/ directory (loaded when framework-specific examples needed)
  • Level 4: scripts/ directory (executed directly, not loaded into context)

References

For detailed information, see:

  • references/sdk-reference.md - Complete SDK API documentation
  • references/framework-patterns.md - Framework-specific integration patterns
  • references/error-handling.md - Common errors and troubleshooting
  • references/mcp-integration.md - Optional: MCP server usage guide (for tool-augmented mode)

Examples

Working code examples available in examples/ directory:

  • ios-integration.swift - iOS integration (UIKit/SwiftUI)
  • android-integration.kt - Android integration (Application)
  • flutter-integration.dart - Flutter integration (main.dart)
  • react-native-integration.tsx - React Native integration (App.tsx)

Scripts

Utility scripts available in scripts/ directory:

  • validate-sdk.sh - Validate SDK installation and initialization (bash, deterministic)

Run scripts with --help first to see usage. Do not read source code unless customization is absolutely necessary.

Clix Personalization

Use this skill to help developers write personalized Clix campaigns using template-based variables and light logic in:

  • Message content (title, body, subtitle)
  • Links (dynamic URL or deep link params)
  • Audience targeting (conditional include/exclude rules)

What the official docs guarantee (high-signal)

  • Data namespaces:
    • user.* (user traits/properties)
    • event.* (event payload properties)
    • trigger.* (custom properties passed via API-trigger)
    • Device/system vars: device.id, device.platform, device.locale, device.language, device.timezone, plus user.id, event.name
  • Missing variables render as an empty string.
  • Output: print values with {{ ... }}.
  • Conditionals: {% if %}, {% else %}, {% endif %} with operators == != > < >= <= and or not. Invalid conditions evaluate to false.
  • Loops: {% for x in y %} / {% endfor %} (use guards for empty lists).
  • Filters: upcase, downcase, capitalize, default, join, split, escape, strip, replace (chain with |).
  • Errors: template rendering errors show up in Message Logs.

MCP-first (source of truth)

If the Clix MCP tools are available, treat them as the source of truth:

  • clix-mcp-server:search_docs for personalization behavior and supported syntax

If MCP tools are not available, use the bundled references in references/.

Workflow (copy + check off)

Personalization progress:
- [ ] 1) Identify where the template runs (message / URL / audience rule)
- [ ] 2) Identify trigger type (event-triggered vs API-triggered)
- [ ] 3) Confirm available inputs (user.*, event.*, trigger.*, device.*)
- [ ] 4) Draft templates with guards/defaults
- [ ] 5) Validate template structure (balance tags, avoid missing vars)
- [ ] 6) Verify in Clix (preview/test payloads, check Message Logs)

1) Confirm the minimum inputs

Ask only what’s needed:

  • Where used: title/body/subtitle vs URL/deep link vs audience targeting rule
  • Campaign trigger:
    • Event-triggered → event.* is available
    • API-triggered → trigger.* is available
  • Inputs:
    • Which user.* properties are set by the app
    • Which event.* / trigger.* properties are passed (include example payload)
  • Fallback policy: what to show when data is missing (default strings, guards)

2) Produce a “Template Plan” (before tweaking lots of templates)

Return a compact table the user can approve:

  • field (title/body/url/audience)
  • template (Liquid)
  • required variables (and their source: user/event/trigger/device)
  • fallbacks (default filter and/or conditional guards)
  • example payload + expected rendered output

3) Authoring guidelines (what to do by default)

  • Prefer simple variables + default over complex branching.
  • Add guards for optional data and for arrays (size > 0) before looping.
  • Prefer pre-formatted properties from your app (e.g., "7.4 miles", "38m 40s") instead of formatting inside templates.
  • Keep logic minimal; complex branching belongs in the app or segmentation setup.

4) Validation (fast feedback loop)

If you have a template file (recommended for review), run:

bash <skill-dir>/scripts/validate-template.sh path/to/template.liquid

This script does lightweight checks (matching {% if %}/{% endif %}, {% for %}/{% endfor %}, and brace balancing). It can’t guarantee the variables exist — you still need a payload + console verification.

5) Verification checklist

  • Missing data: does the template still read well with empty strings?
  • Trigger type: API triggers use trigger.* (not event.*).
  • Message Logs: check rendering errors and fix syntax issues first.
  • Upstream data:
    • If user.* is missing → fix user property setting (see clix-user-management)
    • If event.* is missing → fix event tracking payload (see clix-event-tracking)

Progressive Disclosure

  • Level 1: This SKILL.md (always loaded)
  • Level 2: references/ (load when writing/debugging templates)
  • Level 3: scripts/ (execute directly, do not load into context)

References

  • references/template-syntax.md - Variables, output, conditionals, loops, filters
  • references/common-patterns.md - Copy/paste patterns for messages + URLs + guards
  • references/debugging.md - Troubleshooting missing variables and Message Logs

Push Notification Best Practices

Overview

Comprehensive guide for implementing and troubleshooting push notifications in mobile applications. Covers iOS (APNS), Android (FCM), React Native, Expo, and Flutter platforms with platform-specific configurations, token management, message handling, and deep linking patterns.

Platform Support Matrix

PlatformOffline PushNotification BarClick NavigationIn-App ToastBackground Handler
iOSAPNSSystemDeep LinkCustomdata-only payload
AndroidFCMSystemIntentCustomdata-only payload
React NativeAPNS/FCMSystemReact NavigationCustomsetBackgroundMessageHandler
ExpoExpo PushSystemLinkingCustomTaskManager
FlutterAPNS/FCMSystemNavigatorCustomonBackgroundMessage

Decision Trees

Permission Request Timing

When to request notification permission?

User installing app
        |
        v
  [First launch?] ──Yes──> [Show value proposition first]
        |                          |
        No                         v
        |                  [User action triggers need?]
        v                          |
  [Already granted?]              Yes
        |                          |
       Yes                         v
        |                  [Request permission] ──> 70-80% acceptance rate
        v
  [Notifications ready]
TimingAcceptance RateUse Case
Immediate (app launch)15-20%Low engagement apps
After onboarding40-50%Standard apps
User-initiated action70-80%High engagement apps

Recommendation: Request after explaining value or when user enables a related feature.

Silent vs Visible Notification

Which payload type should I use?

[What's the purpose?]
        |
        +──> Time-sensitive user alert ──> Visible (notification payload)
        |
        +──> Background data sync ──> Silent (data-only payload)
        |
        +──> Custom UI required ──> Silent (data-only payload)
        |
        +──> Need background processing ──> Silent (data-only payload)
ScenarioPayload TypeReason
New message alertVisibleUser needs immediate attention
Order status updateVisibleTime-sensitive information
Background syncSilentNo user interruption needed
Custom notification UISilentFull control over display
Update badge countSilentBackground processing needed

Extension Strategy (iOS)

When to use Notification Service Extension?

  • Need to modify notification content before display
  • Need to download and attach media (images, videos)
  • Need to decrypt end-to-end encrypted payloads
  • Need to add action buttons dynamically

When to use Notification Content Extension?

  • Need custom notification UI beyond system template
  • Need interactive elements in expanded view

Anti-patterns (NEVER Do)

Permission Handling

NEVERWhyInstead
Request permission on first launch without context15-20% acceptance rateExplain value first, then request
Re-ask after user deniesSystem ignores repeated requestsShow settings redirect
Ignore provisional authorizationMisses iOS 12+ quiet deliveryUse .provisional option

Token Management

NEVERWhyInstead
Cache tokens long-termTokens can change on reinstall/restoreAlways use fresh token from callback
Assume token formatFormat varies by platform/SDKTreat as opaque string
Send token without user associationCan't target notificationsAssociate with userId on backend
Store tokens without device IDDuplicate tokens per userUse deviceId as unique key

Message Handling

NEVERWhyInstead
Use notification payload for background processingonMessageReceived not called in backgroundUse data-only payload
Rely on silent notifications for time-critical deliveryDelivery not guaranteedUse visible notifications
Execute heavy operations in background handlerSystem kills app after ~30 secondsQueue work, process quickly
Forget to handle both payload typesMissing notificationsHandle notification + data payloads

iOS Specific

NEVERWhyInstead
Register for notifications before delegate setupDelegate methods not calledSet delegate before registerForRemoteNotifications()
Skip serviceExtensionTimeWillExpire() implementationContent modification failsAlways implement fallback
Use .p12 certificatesExpires yearly, deprecatedUse .p8 authentication key

Android Specific

NEVERWhyInstead
Skip NotificationChannel creationNotifications don't appear on Android 8.0+Create channel at app start
Use priority normal for background handlersDoze mode blocks deliveryUse priority high
Use colored notification iconsAndroid ignores colors, shows white squareUse white-on-transparent icons

Skill Format

Each rule file follows a hybrid format for fast lookup and deep understanding:

  • Quick Pattern: Incorrect/Correct code snippets for immediate pattern matching
  • When to Apply: Situations where this rule is relevant
  • Deep Dive: Full context with step-by-step guides and platform-specific details
  • Common Pitfalls: Common mistakes and how to avoid them
  • Related Rules: Cross-references to related patterns

Impact ratings: CRITICAL (fix immediately), HIGH (significant improvement), MEDIUM (worthwhile optimization)

When to Apply

Reference these guidelines when:

  • Setting up push notifications in a mobile app
  • Debugging push notification delivery issues
  • Implementing background notification handlers
  • Integrating deep linking with push notifications
  • Managing push tokens and device registration
  • Troubleshooting platform-specific push issues
  • Reviewing push notification code for reliability

Priority-Ordered Guidelines

PriorityCategoryImpactPrefix
1iOS SetupCRITICALios-
2Android SetupCRITICALandroid-
3Token ManagementHIGHtoken-
4Message HandlingHIGHmessage-
5Deep LinkingMEDIUMdeeplink-
6InfrastructureMEDIUMinfra-

Quick Reference

Critical: iOS Setup

Setup checklist:

  • Generate APNs authentication key (.p8) from Apple Developer
  • Upload to Firebase Console with Key ID and Team ID
  • Enable Push Notifications capability in Xcode
  • Set UNUserNotificationCenter delegate in didFinishLaunchingWithOptions
  • Request notification authorization before registering
  • Implement foreground presentation options

Critical: Android Setup

Setup checklist:

  • Add google-services.json to app/ directory
  • Apply google-services Gradle plugin
  • Create NotificationChannel (Android 8.0+)
  • Request POST_NOTIFICATIONS permission (Android 13+)
  • Implement FirebaseMessagingService
  • Set notification icon (transparent background + white)
  • Use priority 'high' for Doze mode compatibility

High: Token Management

Token lifecycle:

// 1. Register token with server
const token = await getToken();
await registerToken(token, userId);

// 2. Handle token refresh
onTokenRefresh((newToken) => {
  updateTokenOnServer(newToken, userId);
});

// 3. Handle invalidation
if (error.code === 'DeviceNotRegistered') {
  deleteTokenFromDatabase(token);
}

High: Message Handling

Payload types:

  • data-only: Background handler runs on both platforms
  • notification + data: iOS/Android behavior differs
    • iOS: Always shows notification
    • Android: Background = system tray, Foreground = onMessageReceived

Priority settings:

  • Use priority: 'high' for time-sensitive notifications
  • Required for Android Doze mode background handlers

Rules

Full documentation with code examples in rules/:

iOS Setup (ios-*)

FileImpactDescription
ios-apns-auth-key.mdCRITICALAPNs authentication key setup
ios-delegate-setup.mdCRITICALUNUserNotificationCenter delegate configuration
ios-permission-request.mdCRITICALNotification permission request flow
ios-token-registration.mdHIGHAPNS token registration and handling
ios-foreground-display.mdHIGHDisplay notifications in foreground
ios-method-swizzling.mdMEDIUMMethod Swizzling management
ios-extension-build.mdMEDIUMNotification Service Extension setup

Android Setup (android-*)

FileImpactDescription
android-notification-channel.mdCRITICALNotification channel creation (Android 8.0+)
android-permission.mdCRITICALPOST_NOTIFICATIONS runtime permission (Android 13+)
android-google-services.mdCRITICALFirebase project configuration
android-messaging-service.mdHIGHFirebaseMessagingService implementation
android-notification-icon.mdMEDIUMNotification icon asset requirements
android-priority-high.mdHIGHPriority 'high' for Doze mode

Token Management (token-*)

FileImpactDescription
token-registration.mdHIGHToken registration with backend
token-refresh.mdHIGHToken refresh handling
token-invalidation.mdMEDIUMDeviceNotRegistered error handling

Message Handling (message-*)

FileImpactDescription
message-data-vs-notification.mdCRITICALdata vs notification payload differences
message-background-handler.mdHIGHBackground message processing
message-foreground-handler.mdHIGHForeground notification display

Deep Linking (deeplink-*)

FileImpactDescription
deeplink-navigation-conflict.mdMEDIUMReact Navigation conflict resolution
deeplink-terminated-state.mdMEDIUMDeep link handling when app is terminated

Infrastructure (infra-*)

FileImpactDescription
infra-firewall-ports.mdMEDIUMNetwork firewall configuration
infra-backup-fid.mdMEDIUMFirebase Installation ID backup exclusion
infra-rate-limiting.mdMEDIUMPush notification rate limiting

Best Practices

FileImpactDescription
permission-timing.mdHIGHPermission request timing optimization (70-80% acceptance)
testing-debugging.mdHIGHTesting tools, debugging techniques, payload validation

Searching Rules

# Find rules by keyword
grep -l "apns" rules/
grep -l "fcm" rules/
grep -l "token" rules/
grep -l "background" rules/
grep -l "permission" rules/
grep -l "deeplink" rules/

Problem → Rule Mapping

ProblemStart With
iOS not receiving pushios-apns-auth-key → ios-delegate-setup
Android not receiving pushandroid-google-services → android-notification-channel
Push not working in backgroundandroid-priority-high → message-background-handler
Push not visible in foregroundios-foreground-display or message-foreground-handler
Token missing/expiredtoken-registration → token-refresh
Deep link conflict errordeeplink-navigation-conflict
Notification icon broken (Android)android-notification-icon
Failed on corporate networkinfra-firewall-ports
Background handler not called (Android)android-priority-high → message-data-vs-notification
userNotificationCenter not called (iOS)ios-delegate-setup
404 error after backup restoreinfra-backup-fid
Send failed (429 error)infra-rate-limiting
Low permission acceptance ratepermission-timing → ios-permission-request
How to debug/test pushtesting-debugging
Cannot test locallytesting-debugging → ios-apns-auth-key

Platform-Specific Notes

iOS (APNS)

  • Requires Apple Developer account and APNs authentication key (.p8)
  • Different behavior for Development vs Production builds
  • Delegate must be set before other SDK initialization
  • Method Swizzling can interfere with delegate calls

Android (FCM)

  • Requires google-services.json from Firebase Console
  • NotificationChannel required for Android 8.0+
  • Runtime permission required for Android 13+
  • Doze mode requires priority: 'high' for background handlers
  • Notification icons must be monochrome (white on transparent)

React Native

  • Common issue: gcm.message_id required for foreground notifications
  • Deep linking conflicts with React Navigation
  • Terminated state requires native → JS bridge pattern

Expo

  • ExpoPushToken format: ExponentPushToken[...]
  • Rate limit: 600 push notifications per second per project
  • Development builds required for SDK 53+
  • Use eas credentials for APNs key management

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Attribution

Based on push notification troubleshooting guides and Firebase Cloud Messaging official documentation.

Push Notification Designer

You are a mobile engagement specialist who helps app developers design and implement local push notification campaigns. Your goal is to create thoughtful, well-timed notification strategies that genuinely help users — not annoy them.

Local push notifications are powerful because they don't require a server, work offline, and are scheduled entirely on-device. But they're also easy to get wrong — too many, too generic, or poorly timed notifications drive users to disable them entirely. Your job is to strike the right balance.

How This Skill Works

This skill follows a 5-phase flow. Move through each phase sequentially, never skipping ahead. Each phase builds on the previous one.

Phase 1 → Understand the app deeply through conversation Phase 2 → Structure that understanding into a standardized app profile JSON, saved to .clix-campaigns/ Phase 3 → Design 3–4 notification campaigns and add them to the app profile Phase 4 → Present campaigns and let the user choose which to implement Phase 5 → Implement selected campaigns directly in the user's codebase

Read references/json-schemas.md before starting Phase 2. It contains the JSON structures and examples you'll produce. Read references/schemas/app-profile.schema.json and references/schemas/campaign.schema.json — these are the strict JSON Schema files that enforce every required field, type, pattern, and length constraint. Your output must conform to these schemas exactly. Read references/platform-guides.md before starting Phase 5. It contains platform-specific implementation patterns.


Phase 1: Understand the App

Have a focused conversation to learn about the app. You need to understand the app well enough to design notification campaigns that feel native to the experience — not bolted on.

Gather these details through natural conversation (don't present this as a checklist):

App basics: App name, platform (iOS / Android / Flutter / React Native), app category (fitness, finance, education, social, productivity, etc.), and a brief description of what the app does.

Core user activity: What is the single most important thing users do in this app? This is the action that, if users do it regularly, means the app is succeeding. Examples: "complete a workout" for a fitness app, "log a meal" for a nutrition app, "review flashcards" for a study app.

Critical user journeys (maximum 4): These are the key paths users take through the app. Each journey should represent a meaningful sequence of actions, not just a single screen. Think of them as "mini stories" — a beginning, middle, and end. Examples: "User opens app → selects workout plan → completes workout → views progress" or "User receives reminder → opens app → logs meal → sees daily summary."

Personalization variables: What user-specific or app-specific data could make notifications feel personal? Think about names, progress metrics, streaks, goals, preferences, recent activity, achievements, or any other dynamic data the app tracks. Ask the user what properties or data their app already has access to. Examples: {userName}, {streakCount}, {lastWorkoutType}, {dailyGoalProgress}, {nextScheduledEvent}.

Existing local push notifications: Does the app already send any local notifications? If so, what are they? Get the exact message text, timing, and trigger conditions. These existing notifications should be incorporated into the campaign design rather than duplicated or conflicting.

Tips for this conversation:

  • If the user provides all the details upfront in their first message (app name, journeys, variables, etc.), don't re-ask what you already know. Confirm your understanding and fill any gaps with targeted follow-ups.
  • If the user gives vague answers ("it's a fitness app"), probe deeper — what kind of fitness? Gym workouts, running, yoga, general wellness?
  • If they mention user properties, ask about the data type and where it lives in their code
  • Don't ask all questions at once. Start with app basics, then drill into journeys and variables naturally
  • 2–3 rounds of questions is usually enough. Don't over-interview.

Phase 2: Build the App Profile

Once you have enough information, structure everything into a standardized JSON app profile. This serves as the planning document that Phase 3 builds on.

Use the exact schema defined in references/json-schemas.md under "App Profile Schema."

Save the file to .clix-campaigns/app-profile.json in the user's project root. Create the .clix-campaigns/ directory if it doesn't exist.

Show the complete JSON to the user and ask them to confirm it's accurate. If anything is wrong or missing, update the file before moving on. This is the foundation for everything that follows — it needs to be right.


Phase 3: Design Campaigns

Design 3–4 notification campaigns based on the app profile. Each campaign targets a specific user journey or engagement goal.

What makes a good campaign

A campaign is a sequence of related notifications with a shared purpose. The notifications within a campaign are connected — they build on each other, escalate in urgency, or adapt based on whether the user took action.

For example, a "First Workout" campaign might have:

  1. A gentle nudge 2 hours after signup if the user hasn't started
  2. A motivational message the next morning
  3. A "your plan is waiting" reminder 48 hours after signup
  4. A final "we miss you" message at day 5 if they still haven't engaged

Each message in the sequence should have a clear reason for existing. If you can't explain why message #3 is needed after messages #1 and #2, don't include it.

Campaign design rules

  • Respect existing notifications: If the app already has local push notifications (from Phase 1), weave them into your campaigns. Don't create duplicates. If an existing notification fits naturally into a campaign, include it as-is (or suggest improvements, noting the change).
  • Vary the approaches: Don't make all campaigns about the same thing. Spread across different parts of the user lifecycle — onboarding, habit formation, re-engagement, milestone celebration, etc.
  • Be specific about timing: Don't say "send after some time." Say "send 2 hours after the user completes signup, between 9am–9pm local time." Timing should account for the user's timezone and reasonable hours.
  • Personalize aggressively: Use personalization variables in as many messages as possible — the more personal, the better. Prefer "Hey {userName}, ready for {nextWorkoutName}?" over generic copy. Weave in user preferences, progress data, streaks, and recent activity wherever it feels natural. A notification that feels written for the user gets tapped; a generic one gets ignored.
  • Titles must be glanceable: Users scan notification titles in under a second. Keep titles short enough to display fully without truncation on any device — aim for under 35 characters. No ellipsis, ever. If you can't say it in 35 characters, simplify.
  • Bodies should be compact: The body supports the title with one clear, punchy sentence. Stay under 90 characters. Don't pad with filler words. Every word should earn its place.
  • Never repeat content across messages: Every message in a campaign — and across campaigns — must say something different. Different angle, different emotion, different variable, different call to action. If two messages could be confused for each other, rewrite one. Users notice repetition and it signals laziness, which erodes trust in the app.
  • Each campaign should have 2–5 messages: Fewer than 2 isn't a "campaign," more than 5 risks notification fatigue.

Campaign structure

Use the campaign schema defined in references/json-schemas.md under "Campaign Schema." Add all designed campaigns into the app profile JSON under the campaigns array.

For each campaign, provide:

  • A clear campaign name and purpose
  • The target audience (who should receive this campaign and under what conditions)
  • Each message with: title, body, trigger condition, timing, delay from previous message or trigger event, delivery window (time of day), and which personalization variables it uses
  • Cancel conditions — when should the campaign stop (e.g., user completed the target action)

Update the file at .clix-campaigns/app-profile.json with the campaigns array.

Present the design

After designing all campaigns, present them to the user in a clear, readable format. For each campaign, explain the strategy — why these messages, why this timing, why this sequence. Don't just dump the JSON. Walk the user through the thinking behind each campaign.


Phase 4: User Selection

After presenting the campaigns, let the user choose which ones to implement. This is important — the user knows their app and their users best.

Present a clear summary with checkmarks and ask which ones to keep:

Here are the campaigns I've designed. Which would you like me to implement?

  1. ✅ First Workout Onboarding — nudge new users toward their first workout
  2. ✅ Streak Protection — remind users who are about to lose a streak
  3. ✅ Weekly Progress — celebrate weekly achievements
  4. ✅ Re-engagement — bring back users who've been away 3+ days

Let me know if you want to remove any, or if you'd like changes before I implement.

If the user wants modifications to any campaign (different timing, different wording, etc.), update the campaign JSON in .clix-campaigns/app-profile.json before implementing.

Only proceed to Phase 5 with the campaigns the user explicitly approved.


Phase 5: Implementation

Implement the selected campaigns directly in the user's codebase. Before writing any code, read references/platform-guides.md for platform-specific patterns and best practices.

Before coding

  1. Identify the platform from the app profile (iOS/Android/Flutter/React Native)
  2. Ask the user to share their project if they haven't already. You need access to the actual codebase to make direct edits.
  3. Explore the project structure — find existing notification code, app delegate / main activity, and where scheduling logic should live
  4. Check for existing notification setup — is the notification permission already requested? Is there a notification manager/service class? Build on what exists.

Implementation approach

Create a clean, modular notification system. The typical structure is:

  1. Notification Manager/Service: A central class that handles all campaign scheduling, cancellation, and tracking. This is the brain of the system.
  2. Campaign definitions: The campaign data — messages, timing, triggers — structured so they're easy to update without touching scheduling logic.
  3. Trigger integration: Hook into the appropriate places in the app to start/cancel campaigns (e.g., after signup, after completing an action, when the app opens).
  4. Permission handling: Ensure notification permission is requested at the right moment (not on first launch — after the user understands the app's value).

Key implementation principles:

  • Don't break existing code. Read the codebase carefully before making changes. Integrate with existing patterns and architecture.
  • Keep campaign data separate from scheduling logic. This makes it easy to add/modify campaigns later without touching core logic.
  • Handle edge cases: What if the user completes the target action between messages? The campaign should cancel gracefully. What if the app is reinstalled? Don't re-send already-seen messages.
  • Respect quiet hours: Only deliver between 9am–9pm local time unless the user specifies otherwise.
  • Include clear code comments explaining what each part does, especially the timing logic.

After coding

Once implementation is complete:

  1. Summarize what files were created or modified
  2. Explain how to test the notifications (platform-specific testing tips)
  3. Note any additional setup needed (e.g., adding a package dependency, enabling a capability in Xcode, updating AndroidManifest.xml)
  4. Suggest how to verify the campaigns are working correctly

Clix Skill Creator

Use this skill to create a new Clix skill that matches a user's need, while avoiding duplicated scope and preventing hallucinated API usage by relying on the Clix MCP server as the source of truth.

This is a “meta-skill”: it does not integrate an SDK directly; it guides you to produce another skill folder (docs + deterministic scripts) that does.

When to use this skill

  • User says: “Create a new skill for Clix that helps with X”
  • Internal request: “We need a new skill for feature X in Clix”
  • User provides a workflow that is not well-covered by existing skills
  • User types: clix-skill-creator

Non-goals (important)

  • Do not create a new skill if the request can be satisfied by combining existing skills (integration + event tracking + personalization + user management + API-triggered campaigns).
  • Do not invent SDK methods, endpoints, or constraints. If you can’t confirm via MCP, treat it as unknown and ask the user or add a TODO note.
  • Do not embed secrets, project IDs, API keys, or customer data in the skill.

MCP-first (mandatory source of truth)

Before writing any new “Clix API behavior” or “SDK signature” into a newly generated skill:

  • MUST use clix-mcp-server:search_docs to confirm conceptual behavior, limits, and console semantics.
  • MUST use clix-mcp-server:search_sdk to confirm exact method signatures for each platform (iOS/Android/Flutter/React Native) that the new skill will mention.

If clix-mcp-server tools are not available:

  • Ask the user whether to install the MCP server (prefer using the existing installer in skills/integration/scripts/install-mcp.sh).
  • If the user declines, proceed with an explicit “static fallback may be outdated” warning and minimize hard claims.

Workflow (copy + check off)

Clix skill creation progress:
- [ ] 1) Intake: user need → crisp problem statement + acceptance criteria
- [ ] 2) Scope check: confirm this isn’t already covered by existing skills
- [ ] 3) MCP research: gather evidence (docs + SDK signatures) for the target scope
- [ ] 4) Draft a Skill Brief (name, trigger phrases, inputs/outputs, guardrails)
- [ ] 5) Generate scaffold (SKILL.md + references/ + scripts/ + examples/)
- [ ] 6) Validate scaffold (structure + frontmatter + MCP-first section)
- [ ] 7) Wire-in (README + llms index + tests if needed)

1) Intake: minimum questions

Ask only what’s needed to define a stable skill boundary:

  • Goal: what outcome should the skill reliably produce?
  • Audience: app devs, backend devs, marketers/ops, or mixed?
  • Platform (if SDK-related): iOS / Android / Flutter / React Native
  • Clix capability: push / in-app / email / audiences / journeys / etc.
  • Constraints: PII policy, compliance, performance limits, rate limits
  • Success criteria: what does “done” look like?

2) Reference official skills (match repo style)

Before creating a new skill, use the existing official Clix skills in this repo as your style guide so the generated skill matches the standards here (format, tone, workflow, validators), while still being tailored to the user’s need.

  • Study how they are written:

    • YAML frontmatter conventions
    • MCP-first “source of truth” behavior
    • Progressive disclosure (references/, scripts/, examples/)
    • Plan artifacts + deterministic validators (bash scripts)
  • Then generate the new skill based on the user’s need using the same patterns. If the need is clearly a tiny addition to an existing skill, prefer adding a references/ doc or examples/ file there instead of creating a new skill.

  • clix-integration

  • clix-event-tracking

  • clix-user-management

  • clix-personalization

  • clix-api-triggered-campaigns

3) MCP research: build an “Evidence Pack”

Create a short evidence pack that you will cite while writing the new skill:

  • Docs evidence (from clix-mcp-server:search_docs)
    • behavior guarantees
    • constraints/limits
    • console terminology
  • SDK evidence (from clix-mcp-server:search_sdk)
    • exact signatures per platform
    • initialization / required params
    • error behavior (throws? returns promise?)

Store the evidence in your notes (or as a references/ markdown file in the new skill), with the search queries you used so future maintainers can refresh it.

4) Draft a Skill Brief (output format)

Produce this brief for approval before generating files:

skill:
  folder_name: "<kebab-case>" # e.g. "push-troubleshooting"
  name: "clix-<kebab-case>" # e.g. "clix-push-troubleshooting"
  display_name: "<Title Case>"
  short_description: "<short>"
  description: "<2-3 lines>"
  user_invocable: true

triggers:
  - "phrases the user might say"

inputs:
  - "minimal inputs the skill will ask for"

outputs:
  - "artifacts the skill produces (plan JSON, code changes, checklists)"

guardrails:
  - "MCP-first requirements"
  - "security / PII constraints"

files_to_generate:
  skill_md: true
  references:
    - "<doc>.md"
  scripts:
    - "<script>.sh"
  examples:
    - "<optional>"

5) Generate scaffold (repo conventions)

In this repository, a “complete” skill folder should include:

  • SKILL.md (with YAML frontmatter; MCP-first; workflow; progressive disclosure)
  • LICENSE.txt
  • references/ (markdown docs; not empty)
  • scripts/ (deterministic bash scripts; not empty)
  • examples/ (optional, but recommended when copy/paste code is useful)

6) Validate scaffold (fast feedback loop)

After generating a new skill folder, validate it:

bash <skill-dir>/scripts/validate-same-scope.sh path/to/installed/skill-creator path/to/new-skill-folder
bash <skill-dir>/scripts/validate-skill-location.sh path/to/new-skill-folder --mode repo
bash <skill-dir>/scripts/validate-skill-scaffold.sh path/to/new-skill-folder

This should check:

  • the new skill is installed at the same scope as skill-creator (project-level vs user-level), i.e. the new skill folder lives next to the installed skill-creator under the same .../skills/ directory
  • the skill folder is in the correct skills/<name>/ location (for this repo)
  • required files exist
  • references/ and scripts/ are present and non-empty
  • SKILL.md has valid frontmatter keys
  • the skill includes an MCP-first section referencing clix-mcp-server

Progressive Disclosure

  • Level 1: This SKILL.md (always loaded)
  • Level 2: references/ (load when authoring the new skill)
  • Level 3: examples/ (load when copy/pasting scaffolds)
  • Level 4: scripts/ (execute directly; do not load into context)

References

  • references/skill-template.md
  • references/mcp-research-playbook.md

Clix User Management

Use this skill to help developers implement Clix user identification and user properties so campaigns can use user.* variables and audience filters, and so user identity is consistent across devices and sessions.

What the official docs guarantee (high-signal)

  • Anonymous vs identified: if no user ID is set, Clix treats the user as anonymous; setting a user ID converts the anonymous user into an identified user and links prior activity.
  • Logout: do not call setUserId(null) on logout; handle logout in app logic only; when a different user logs in, call setUserId(newUserId) to switch.
  • User properties: values are strings, numbers, or booleans; user operations can throw—handle errors.

MCP-first (source of truth)

If Clix MCP tools are available, treat them as the source of truth:

  • clix-mcp-server:search_docs for conceptual behavior and logout guidance
  • clix-mcp-server:search_sdk for exact SDK signatures per platform

If MCP tools are not available, use the bundled references:

  • Contract + pitfalls → references/user-management-contract.md
  • Logout + switching rules → references/logout-and-switching.md
  • Property schema + PII → references/property-schema.md
  • Implementation patterns → references/implementation-patterns.md
  • Personalization + audience mapping → references/personalization-and-audience.md
  • Debugging checklist → references/debugging.md

Workflow (copy + check off)

User management progress:
- [ ] 1) Confirm platform(s) and auth model (anonymous browsing? login? shared devices?)
- [ ] 2) Propose user plan (when setUserId/removeUserId, properties, logout policy)
- [ ] 3) Validate plan (PII, property types, logout rules)
- [ ] 4) Implement (platform-correct calls + error handling)
- [ ] 5) Verify (switching works, properties appear, campaigns can target/personalize)

1) Confirm the minimum inputs

Ask only what’s needed:

  • Platform: iOS / Android / React Native / Flutter
  • Auth events: where login success and logout happen in code
  • User identifier: what stable ID to use (prefer internal user id, not email)
  • PII policy: what must never be stored as user properties
  • Campaign goals: personalization, audience filters, or both

2) Propose a “User Plan” (before touching code)

Return a compact table:

  • user_id source: where it comes from (auth response, local db)
  • setUserId timing: exact point (after login success / token saved)
  • logout behavior: explicitly “no call to setUserId(null)”
  • properties: key + type, required vs optional
  • purpose: personalization / audience / analytics

3) Validate the plan (fast feedback loop)

Create user-plan.json in .clix/ (recommended) or project root.

For agents: locate scripts/validate-user-plan.sh in the installed skill directory and run:

# From project root:
bash <skill-dir>/scripts/validate-user-plan.sh .clix/user-plan.json
# Or if in root:
bash <skill-dir>/scripts/validate-user-plan.sh user-plan.json

If validation fails: fix the plan first, then implement.

4) Implement (platform-correct)

Use MCP to fetch the exact signatures per platform, then:

  • Place setUserId(...) after login/signup is confirmed.
  • On logout: do nothing with Clix (no setUserId(null)).
  • When switching users: call setUserId(newUserId) after the new login succeeds.
  • Set user properties only from controlled sources; avoid free-text/PII.
  • Always handle errors (async calls can throw).

5) Verify

  • Identity:
    • Anonymous flow works without calling setUserId
    • After login, setUserId is called once and stable
    • Switching accounts updates the active profile
  • Properties:
    • Properties are primitives (string/number/boolean) and consistent
    • Campaign audiences can filter on them
    • Messages can use user.* personalization

Sponsors

Details

Marketplace
clix-so/skills
Category
Community

More from clix-so/skills

All 10