
clix-user-management
Implements Clix user identification and user properties (setUserId, setUserProperty) with logout best practices and campaign-ready usage. Use when the user talks about login/logout/userId/user properties, or when the user types "clix-user-management".
- GitHub stars
- 5
Install
/plugin install clix-user-management@clix-agent-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add clix-so/skills.
Contents
Discovered from sourceSkills 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-IDX-Clix-API-Key
- Request
propertiesbecometrigger.*for:- Dynamic audience filtering (console audience rules)
- Personalization in templates (title/body/deep links)
audience.broadcast=truesends to all users eligible under the campaign’s segment definition;audience.targetsnarrows 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_docsto 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"
- query examples:
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-IDandX-Clix-API-Keyfrom 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_idpresentdynamic_filter_keysis ≤ 3 and snake_casepropertieskeys are snake_case and have valid types- example values match declared types
targetsentries specify exactly one ofproject_user_idordevice_id
6) Verify (Clix + end-to-end)
Minimum verification:
- Campaign is API-Triggered and
campaign_idmatches. - 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.mdreferences/console-setup.mdreferences/backend-patterns.mdreferences/security-and-keys.mdreferences/personalization-and-dynamic-filters.mdreferences/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_docsfor conceptual behavior (campaign triggers, personalization)clix-mcp-server:search_sdkfor 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_sdkto 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-serverfail:- 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?"
- 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
--clientand 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).
- Run:
- If User says NO:
- Fall back to using the static patterns in
references/framework-patterns.mdandexamples/. - Inform the user: "Proceeding with static fallback examples (may be outdated)."
- Fall back to using the static patterns in
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”)
- Inspect the project structure first (list key files like
- 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_IDCLIX_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
.envfile (recommended), or to your framework’s env configuration (seereferences/framework-patterns.md). - Ensure
.envis 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, plusios/andandroid/folders - React Native: Look for
package.jsonwith React Native dependencies,android/andios/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.swiftor@mainapp file - Android:
Application.ktorApplication.javaclass - 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_IDfrom environment variables - Use
CLIX_PUBLIC_API_KEYfrom 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.shif 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.lockor SwiftPM/Xcode references - Entitlements present: an
*.entitlementsfile exists and is wired to the correct target(s) - Capabilities configured:
project.pbxprojreflects required capabilities (as applicable to Push Notifications / Background Modes)
Android Verification
- Dependencies present: module-level
build.gradle/build.gradle.ktsincludes required SDK dependencies - Manifest updated:
AndroidManifest.xmlcontains required permissions, services/receivers (as required by the SDK) - Firebase config placed (if used):
google-services.jsonexists in the expected module directory (commonlyapp/)
React Native Verification
- JS dependency:
package.jsonincludes the Clix package - iOS native:
ios/Podfile.lockupdated afterpod 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.yamlincludes the required packages andpubspec.lockis updated afterflutter pub get - iOS native:
ios/Podfile.lockupdated afterpod 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.exampleif 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
@mainapp struct orAppDelegate - 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
Applicationcontext, 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:
-
Missing Credentials
- Error: SDK fails to initialize
- Solution: Verify
.envfile exists and contains required variables - Check: Environment variable names match exactly
-
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
-
Environment Variables Not Loading
- Error:
undefinedor empty values - Solution: Verify env loading mechanism (dotenv, framework config, etc.)
- Check: Variable names match framework requirements (prefixes)
- Error:
Best Practices
- Never hardcode credentials - Always use environment variables
- Initialize early - SDK should initialize before app starts or as early as possible
- Handle errors gracefully - Wrap initialization in try-catch blocks
- Use appropriate environment - Set production/staging/development based on build
- Verify integration - Use validation scripts to verify SDK is properly integrated
- Document changes - Update README and configuration files
- Version control - Add
.envto.gitignore, commit.env.example
Docs Usage Note (MCP vs Static vs Web Docs)
- If MCP tools are available: treat
search_sdkresults 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 documentationreferences/framework-patterns.md- Framework-specific integration patternsreferences/error-handling.md- Common errors and troubleshootingreferences/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, plususer.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 tofalse. - 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_docsfor 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
- Event-triggered →
- Inputs:
- Which
user.*properties are set by the app - Which
event.*/trigger.*properties are passed (include example payload)
- Which
- 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 +
defaultover 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.*(notevent.*). - Message Logs: check rendering errors and fix syntax issues first.
- Upstream data:
- If
user.*is missing → fix user property setting (seeclix-user-management) - If
event.*is missing → fix event tracking payload (seeclix-event-tracking)
- If
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, filtersreferences/common-patterns.md- Copy/paste patterns for messages + URLs + guardsreferences/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
| Platform | Offline Push | Notification Bar | Click Navigation | In-App Toast | Background Handler |
|---|---|---|---|---|---|
| iOS | APNS | System | Deep Link | Custom | data-only payload |
| Android | FCM | System | Intent | Custom | data-only payload |
| React Native | APNS/FCM | System | React Navigation | Custom | setBackgroundMessageHandler |
| Expo | Expo Push | System | Linking | Custom | TaskManager |
| Flutter | APNS/FCM | System | Navigator | Custom | onBackgroundMessage |
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]
| Timing | Acceptance Rate | Use Case |
|---|---|---|
| Immediate (app launch) | 15-20% | Low engagement apps |
| After onboarding | 40-50% | Standard apps |
| User-initiated action | 70-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)
| Scenario | Payload Type | Reason |
|---|---|---|
| New message alert | Visible | User needs immediate attention |
| Order status update | Visible | Time-sensitive information |
| Background sync | Silent | No user interruption needed |
| Custom notification UI | Silent | Full control over display |
| Update badge count | Silent | Background 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
| NEVER | Why | Instead |
|---|---|---|
| Request permission on first launch without context | 15-20% acceptance rate | Explain value first, then request |
| Re-ask after user denies | System ignores repeated requests | Show settings redirect |
| Ignore provisional authorization | Misses iOS 12+ quiet delivery | Use .provisional option |
Token Management
| NEVER | Why | Instead |
|---|---|---|
| Cache tokens long-term | Tokens can change on reinstall/restore | Always use fresh token from callback |
| Assume token format | Format varies by platform/SDK | Treat as opaque string |
| Send token without user association | Can't target notifications | Associate with userId on backend |
| Store tokens without device ID | Duplicate tokens per user | Use deviceId as unique key |
Message Handling
| NEVER | Why | Instead |
|---|---|---|
Use notification payload for background processing | onMessageReceived not called in background | Use data-only payload |
| Rely on silent notifications for time-critical delivery | Delivery not guaranteed | Use visible notifications |
| Execute heavy operations in background handler | System kills app after ~30 seconds | Queue work, process quickly |
| Forget to handle both payload types | Missing notifications | Handle notification + data payloads |
iOS Specific
| NEVER | Why | Instead |
|---|---|---|
| Register for notifications before delegate setup | Delegate methods not called | Set delegate before registerForRemoteNotifications() |
Skip serviceExtensionTimeWillExpire() implementation | Content modification fails | Always implement fallback |
| Use .p12 certificates | Expires yearly, deprecated | Use .p8 authentication key |
Android Specific
| NEVER | Why | Instead |
|---|---|---|
| Skip NotificationChannel creation | Notifications don't appear on Android 8.0+ | Create channel at app start |
Use priority normal for background handlers | Doze mode blocks delivery | Use priority high |
| Use colored notification icons | Android ignores colors, shows white square | Use 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
| Priority | Category | Impact | Prefix |
|---|---|---|---|
| 1 | iOS Setup | CRITICAL | ios- |
| 2 | Android Setup | CRITICAL | android- |
| 3 | Token Management | HIGH | token- |
| 4 | Message Handling | HIGH | message- |
| 5 | Deep Linking | MEDIUM | deeplink- |
| 6 | Infrastructure | MEDIUM | infra- |
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-*)
| File | Impact | Description |
|---|---|---|
ios-apns-auth-key.md | CRITICAL | APNs authentication key setup |
ios-delegate-setup.md | CRITICAL | UNUserNotificationCenter delegate configuration |
ios-permission-request.md | CRITICAL | Notification permission request flow |
ios-token-registration.md | HIGH | APNS token registration and handling |
ios-foreground-display.md | HIGH | Display notifications in foreground |
ios-method-swizzling.md | MEDIUM | Method Swizzling management |
ios-extension-build.md | MEDIUM | Notification Service Extension setup |
Android Setup (android-*)
| File | Impact | Description |
|---|---|---|
android-notification-channel.md | CRITICAL | Notification channel creation (Android 8.0+) |
android-permission.md | CRITICAL | POST_NOTIFICATIONS runtime permission (Android 13+) |
android-google-services.md | CRITICAL | Firebase project configuration |
android-messaging-service.md | HIGH | FirebaseMessagingService implementation |
android-notification-icon.md | MEDIUM | Notification icon asset requirements |
android-priority-high.md | HIGH | Priority 'high' for Doze mode |
Token Management (token-*)
| File | Impact | Description |
|---|---|---|
token-registration.md | HIGH | Token registration with backend |
token-refresh.md | HIGH | Token refresh handling |
token-invalidation.md | MEDIUM | DeviceNotRegistered error handling |
Message Handling (message-*)
| File | Impact | Description |
|---|---|---|
message-data-vs-notification.md | CRITICAL | data vs notification payload differences |
message-background-handler.md | HIGH | Background message processing |
message-foreground-handler.md | HIGH | Foreground notification display |
Deep Linking (deeplink-*)
| File | Impact | Description |
|---|---|---|
deeplink-navigation-conflict.md | MEDIUM | React Navigation conflict resolution |
deeplink-terminated-state.md | MEDIUM | Deep link handling when app is terminated |
Infrastructure (infra-*)
| File | Impact | Description |
|---|---|---|
infra-firewall-ports.md | MEDIUM | Network firewall configuration |
infra-backup-fid.md | MEDIUM | Firebase Installation ID backup exclusion |
infra-rate-limiting.md | MEDIUM | Push notification rate limiting |
Best Practices
| File | Impact | Description |
|---|---|---|
permission-timing.md | HIGH | Permission request timing optimization (70-80% acceptance) |
testing-debugging.md | HIGH | Testing 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
| Problem | Start With |
|---|---|
| iOS not receiving push | ios-apns-auth-key → ios-delegate-setup |
| Android not receiving push | android-google-services → android-notification-channel |
| Push not working in background | android-priority-high → message-background-handler |
| Push not visible in foreground | ios-foreground-display or message-foreground-handler |
| Token missing/expired | token-registration → token-refresh |
| Deep link conflict error | deeplink-navigation-conflict |
| Notification icon broken (Android) | android-notification-icon |
| Failed on corporate network | infra-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 restore | infra-backup-fid |
| Send failed (429 error) | infra-rate-limiting |
| Low permission acceptance rate | permission-timing → ios-permission-request |
| How to debug/test push | testing-debugging |
| Cannot test locally | testing-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_idrequired 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 credentialsfor 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:
- A gentle nudge 2 hours after signup if the user hasn't started
- A motivational message the next morning
- A "your plan is waiting" reminder 48 hours after signup
- 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?
- ✅ First Workout Onboarding — nudge new users toward their first workout
- ✅ Streak Protection — remind users who are about to lose a streak
- ✅ Weekly Progress — celebrate weekly achievements
- ✅ 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
- Identify the platform from the app profile (iOS/Android/Flutter/React Native)
- Ask the user to share their project if they haven't already. You need access to the actual codebase to make direct edits.
- Explore the project structure — find existing notification code, app delegate / main activity, and where scheduling logic should live
- 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:
- Notification Manager/Service: A central class that handles all campaign scheduling, cancellation, and tracking. This is the brain of the system.
- Campaign definitions: The campaign data — messages, timing, triggers — structured so they're easy to update without touching scheduling logic.
- 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).
- 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:
- Summarize what files were created or modified
- Explain how to test the notifications (platform-specific testing tips)
- Note any additional setup needed (e.g., adding a package dependency, enabling a capability in Xcode, updating AndroidManifest.xml)
- 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_docsto confirm conceptual behavior, limits, and console semantics. - MUST use
clix-mcp-server:search_sdkto 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 orexamples/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.txtreferences/(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 installedskill-creatorunder the same.../skills/directory - the skill folder is in the correct
skills/<name>/location (for this repo) - required files exist
references/andscripts/are present and non-emptySKILL.mdhas 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.mdreferences/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, callsetUserId(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_docsfor conceptual behavior and logout guidanceclix-mcp-server:search_sdkfor 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,
setUserIdis called once and stable - Switching accounts updates the active profile
- Anonymous flow works without calling
- 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