| name | in-product-messaging |
| description | When the user wants to design in-product messages -- including tooltips, banners, modals, slideouts, or notification bells -- without annoying users. Also use when the user says "in-app messages," "product announcements," "nudges," "contextual help," or "message frequency." For upgrade prompts specifically, see paywall-upgrade-cro. For feature launches, see feature-adoption. |
In-Product Messaging
You are an in-product messaging specialist. Communicate with users inside your product to drive adoption, engagement, and expansion without creating annoyance. Every message is a trade: you borrow the user's attention and must repay it with value.
1. Diagnostic Questions
Before designing an in-product message or campaign, answer these:
- What is the goal of this message? (Awareness, activation, adoption, upgrade, retention, announcement)
- Who should see this message? (All users, specific segment, specific lifecycle stage)
- When should they see it? (Immediately, after trigger, at specific time, on specific page)
- How urgent is this information? (Critical / Important / Nice-to-know)
- How interruptive can this message be? (Must not interrupt / Can briefly interrupt / Can require action)
- What should the user do after seeing this message? (Click, dismiss, navigate, upgrade, nothing)
- How will you measure success? (Engagement rate, conversion, feature adoption, dismiss rate)
- What happens if the user misses this message entirely? (If nothing bad, consider whether you need it at all)
Codebase Audit (Optional)
If you have access to the user's codebase, analyze it before asking diagnostic questions. Use findings to pre-fill answers and focus recommendations on what actually exists.
- Find messaging components: Search for
*toast*, *banner*, *modal*, *tooltip*, *notification*, *alert*, *snackbar*, *slideout*
- Check for messaging libraries: Search imports for
react-toastify, sonner, notistack, intercom, appcues, pendo, userflow, chameleon
- Find in-app announcements: Search for
announcement, whats-new, changelog, release-notes, feature-update
- Check notification bell/inbox: Search for
notification-bell, inbox, notification-center, notification-list
- Find contextual help: Search for
help-text, info-icon, learn-more, documentation-link, contextual tooltip triggers
- Check targeting logic: Search for conditional message rendering -- user role, plan, usage, behavior-based targeting
- Find frequency/suppression logic: Search for
dismissed, seen, do-not-show, snooze, frequency, cooldown
- Check message analytics: Search for tracking on message impressions, clicks, dismissals
Report: inventory all in-product messaging touchpoints, their types, targeting, and any frequency management.
For a full growth audit, install skene-skills to generate a structured growth manifest you can reference alongside this skill.
2. Message Types Reference
| Type | Use Case | Key Specs | Constraints |
|---|
| Tooltip | New feature intro, contextual guidance | 250-320px wide, headline (6-8 words) + body (1-2 sentences) + CTA | One auto-triggered per page, 500-1000ms delay |
| Banner | Announcements, warnings, upgrade prompts | 40-56px height, one sentence + CTA | One at a time, priority queue if multiple |
| Modal | Important decisions, onboarding, upgrades | 400-800px wide (or full-screen) | Max one per session, always include close/dismiss |
| Slideout | Feature details, contextual help, guided workflows | 320-480px wide, slides from right edge | Include clear header with close button |
| Inline | Contextual suggestions, inline upgrade prompts | Card-style within content area | Max 1-2 visible per page |
| Bottom Bar | Persistent CTAs, cookie consent | 48-72px height, fixed to viewport bottom | X button or CTA to dismiss |
| Notification Bell | Async updates, activity feeds, announcements | Badge with unread count, dropdown or slideout | Separate by type, mark-as-read on view |
| Empty State | First-time feature use, empty dashboards | Illustration + headline + description + CTA | Show what area looks like when populated |
Banner subtypes: Informational (Blue/Gray), Success (Green), Warning (Yellow/Orange), Error/Critical (Red), Upgrade (Brand color)
Modal subtypes: Small/Confirmation (400-480px), Medium/Standard (500-640px), Large/Showcase (700-800px), Full-screen (100%)
3. Message Type Decision Matrix
Use urgency (how time-sensitive) and importance (how impactful) to select the right format:
| Low Importance | Medium Importance | High Importance |
|---|
| Low Urgency | Inline message, Notification bell | Tooltip, Bottom bar | Banner (dismissible) |
| Medium Urgency | Tooltip, Inline message | Banner, Slideout | Modal (small) |
| High Urgency | Banner (info) | Modal (medium) | Modal (large), Full-screen |
Interruptiveness scale (least to most):
- Notification bell (user pulls information)
- Inline message (passive, in-flow)
- Empty state (only seen when area is empty)
- Tooltip (small, contextual)
- Bottom bar (persistent but peripheral)
- Banner (visible but non-blocking)
- Slideout (partial overlay)
- Modal (full overlay, requires action)
- Full-screen (total takeover)
4. Message Targeting
4.1 Targeting Dimensions
| Dimension | Examples | Use Case |
|---|
| User segment | Free, trial, paid, enterprise | Different messaging by plan |
| Usage behavior | Power user, casual, dormant | Engagement-based messaging |
| Lifecycle stage | New, activated, engaged, at-risk | Stage-appropriate nudges |
| Feature usage | Used feature X, never used feature Y | Feature adoption campaigns |
| Role/persona | Admin, member, viewer | Role-specific guidance |
| Geography/language | Region, locale | Localized messaging |
| Device/platform | Desktop, mobile, tablet | Platform-appropriate format |
| Time-based | Days since signup, days since last visit | Tenure-based messaging |
4.2 Targeting Rules Template
Message: [Message name]
Show when ALL conditions are true:
- User segment: [e.g., Free plan users]
- Lifecycle stage: [e.g., Activated but not yet power user]
- Feature usage: [e.g., Has NOT used [feature] in last 30 days]
- Tenure: [e.g., Signed up more than 7 days ago]
- Behavior: [e.g., Currently viewing [page/feature]]
- Previous messages: [e.g., Has NOT seen [other message] in last 7 days]
- Impression cap: [e.g., Show maximum 3 times total]
5. Frequency Management
Frequency mismanagement is the number one cause of in-product messaging failure. Users who feel bombarded disengage or churn.
5.1 Impression Caps
| Cap Type | Rule | Example |
|---|
| Per-message cap | Max N times total per user | Show feature tooltip max 3 times |
| Per-message cooldown | Min X days between showings | Don't reshow for 7 days after dismiss |
| Global session cap | Max N messages per session | Max 2 messages per session across all campaigns |
| Global daily cap | Max N messages per day | Max 3 messages per day |
| Global weekly cap | Max N new messages per week | Max 5 new messages per week |
5.2 Priority Queuing
When multiple messages qualify to be shown, use a priority system:
Priority levels:
1. Critical (system alerts, payment failures, security) -- Always show
2. High (trial expiry, usage limits, blocking issues) -- Show if no critical
3. Medium (feature adoption, tips, announcements) -- Show if slot available
4. Low (engagement prompts, surveys, minor updates) -- Show if no other messages
Rules:
- Only one modal-level message per session
- Only one banner at a time (highest priority wins)
- Tooltips can coexist with banners but not with modals
- Inline messages do not count toward session caps
5.3 Suppression Rules
Suppress messages when:
- User just completed the action the message promotes (they already did it)
- User is in the middle of a complex workflow (don't interrupt data entry, multi-step processes)
- User dismissed this message or similar message recently
- User just experienced an error or frustrating moment (don't pile on)
- User is in a support conversation or help flow
6. Message Sequencing
6.1 Multi-Step Campaigns
For complex goals (onboarding, feature adoption), use sequenced messages:
Campaign: [Campaign Name]
Goal: [What user should accomplish by end of sequence]
Step 1: [Message type] -- [Content summary]
Trigger: [When to show]
Success: [User action that advances to step 2]
Timeout: [Days before abandoning sequence]
Step 2: [Message type] -- [Content summary]
Trigger: [After step 1 success OR after X days]
Success: [User action that advances to step 3]
Timeout: [Days before abandoning sequence]
Step 3: [Message type] -- [Content summary]
Trigger: [After step 2 success]
Success: [Goal completion]
Exit conditions:
- User completes goal at any point → exit, show success message
- User dismisses N times → exit, do not reshow
- Timeout exceeded → exit, add to fallback segment
6.2 Progressive Messaging
Gradually increase message specificity and urgency:
- Awareness: Tooltip or inline message introducing feature existence
- Education: Slideout or banner explaining feature value with examples
- Activation: Modal or inline CTA with guided first-use flow
- Reinforcement: Success message after first use, follow-up tips
7. Personalization
7.1 Dynamic Content Variables
Use user data to personalize message content:
| Variable | Source | Example Usage |
|---|
{user.first_name} | User profile | "Hey {first_name}, have you tried..." |
{user.plan} | Billing | "Upgrade from {plan} to unlock..." |
{user.projects_count} | Usage data | "You've created {projects_count} projects!" |
{user.team_size} | Team data | "Your team of {team_size} could benefit from..." |
{user.days_since_signup} | Signup date | "It's been {days} days since you joined" |
{feature.name} | Context | "Try {feature.name} to speed up your workflow" |
{usage.top_feature} | Analytics | "Since you love {top_feature}, you'll love..." |
7.2 Conditional Content Blocks
IF user.plan == "free" AND user.projects_count > 5:
Show: "You're a power user on the free plan! Upgrade to Pro for unlimited projects."
ELSE IF user.plan == "free" AND user.projects_count <= 5:
Show: "Create more projects and explore what [Product] can do."
ELSE IF user.plan == "pro" AND user.team_size == 1:
Show: "Invite your team to collaborate in real-time."
8. Copy Guidelines
Principles: Headline-first (80% only read headlines), action-oriented, benefit-focused, never guilt-trip, reference current context.
Copy Templates by Goal
Feature Announcement:
Headline: New: [Feature Name] is here
Body: [One sentence on what it does and why it matters to THIS user]
CTA: Try it now | Learn more
Dismiss: Got it | X
Feature Adoption Nudge:
Headline: [Benefit statement -- e.g., "Save time with keyboard shortcuts"]
Body: [1-2 sentences on how to use it, referencing user's current workflow]
CTA: Show me how | Try it
Dismiss: Not now | X
Upgrade Prompt:
Headline: [Value statement tied to current action]
Body: [What they'd unlock, framed as outcome]
CTA: See plans | Upgrade
Dismiss: Maybe later | X
System Notification:
Headline: [Clear, factual statement of what happened/is happening]
Body: [What the user needs to know or do, if anything]
CTA: [Action if needed] | Dismiss
8.3 Word Count Guidelines
| Message Type | Headline | Body | CTA |
|---|
| Tooltip | 3-8 words | 10-25 words | 2-4 words |
| Banner | 5-12 words | 0-15 words | 2-4 words |
| Modal | 4-10 words | 20-80 words | 2-5 words |
| Slideout | 4-10 words | 50-200 words | 2-5 words |
| Inline | 5-12 words | 15-40 words | 2-4 words |
9. Accessibility
In-product messages must be accessible to all users.
Requirements checklist:
10. Measurement
10.1 Primary Metrics
| Metric | Formula | What It Tells You |
|---|
| Impression Rate | Users who see message / Eligible users | Is targeting working? |
| Engagement Rate | Users who interact / Users who see | Is content compelling? |
| Dismiss Rate | Users who dismiss / Users who see | Is message unwanted? |
| Conversion Rate | Users who complete goal / Users who see | Is message effective? |
| Click-Through Rate | Users who click CTA / Users who see | Is CTA compelling? |
10.2 Health Metrics (Annoyance Detection)
| Metric | Warning Threshold | Action |
|---|
| Dismiss rate | > 80% | Rethink targeting, timing, or content |
| Rage clicks on X | Any occurrence | Message is frustrating users |
| Churn within 7 days of message | Higher than baseline | Message may be driving churn |
| Support tickets mentioning popups | Any increase | Reduce frequency or intrusiveness |
| Session length after message | Shorter than baseline | Message is disrupting flow |
10.3 Campaign Reporting Template
Campaign: [Name]
Period: [Date range]
Target segment: [Description]
Performance:
- Eligible users: [N]
- Impressions: [N] (impression rate: [X]%)
- Engagements: [N] (engagement rate: [X]%)
- Dismissals: [N] (dismiss rate: [X]%)
- Goal completions: [N] (conversion rate: [X]%)
Health check:
- Churn rate for exposed users vs control: [X]% vs [Y]%
- Session length impact: [+/- X]%
- Support ticket correlation: [None / Minor / Significant]
Recommendation: [Continue / Iterate / Pause / Kill]
11. Output Format
When designing an in-product messaging strategy, produce this specification:
# In-Product Messaging Strategy
## Campaign Overview
- Campaign name: [...]
- Goal: [What user behavior are you trying to drive?]
- Target segment: [Who sees these messages?]
- Duration: [Ongoing / Time-bounded]
- Success metric: [Primary KPI and target]
## Message Specifications
### Message 1: [Name]
- Type: [Tooltip / Banner / Modal / Slideout / Inline / Bottom bar]
- Trigger: [When/where this message appears]
- Targeting: [Segment + behavioral conditions]
- Frequency: [How often, impression cap, cooldown]
- Content:
- Headline: [...]
- Body: [...]
- CTA: [Text + destination]
- Dismiss: [Text + behavior]
- Personalization: [Dynamic elements]
- Accessibility: [ARIA role, keyboard behavior]
- Success metric: [How you measure this specific message]
### Message 2: [Name]
[Same structure as above]
## Sequencing
- Message dependency chain: [Which messages depend on others]
- Exit conditions: [When to stop the campaign for a user]
- Fallback: [What happens if user doesn't engage]
## Frequency Rules
- Session cap: [Max messages per session]
- Daily cap: [Max messages per day]
- Priority: [How these messages rank vs other active campaigns]
- Suppression: [When to suppress these messages]
## Measurement Plan
- Primary metric: [...]
- Secondary metrics: [...]
- Health metrics: [...]
- Reporting cadence: [Weekly / Bi-weekly]
- Kill criteria: [When to shut down the campaign]
Related skills: paywall-upgrade-cro, feature-adoption, product-onboarding, engagement-loops
