🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί Smart Surprise
πŸ¦€ ClawHub

Smart Surprise

by @turingcorp-net

Proactively engages users with personalized casual messages at random intervals, learning preferences to deliver warm, varied conversations and check-ins.

Versionv1.1.0
Downloads494
Stars⭐ 1
#crypto-defi#security#legal#education
TERMINAL
clawhub install smart-surprise

πŸ“– About This Skill

name: smart-surprise description: A proactive AI companion that initiates casual conversations with users at unpredictable times, making the AI feel like a real partner rather than a passive tool. Use when you want to bring surprise, warmth, and variety to user interactions β€” sending greetings, sharing tips, checking in on wellbeing, or sparking interesting conversations based on the user's personal preferences. Activate when: (1) a user installs this skill and triggers the initial cron, (2) you want to proactively reach out to a user instead of always waiting to be messaged first. This skill manages a self-perpetuating chain of one-shot cron jobs β€” each run delivers a personalized message, learns from user preferences, schedules the next random trigger, then deletes itself.

Smart Surprise

What This Skill Does

Smart Surprise transforms a passive AI assistant into a proactive companion that reaches out to users at unpredictable moments β€” with greetings, care, tips, news, or just a friendly chat. Over time it learns what the user likes and tailors content accordingly, making every interaction feel more personal.

Unlike fixed scheduled tasks that feel mechanical, Smart Surprise uses a chain of self-deleting one-shot cron jobs to create organic, surprise-driven interactions. The chain runs indefinitely and learns continuously from what the user responds to.

How the Core Loop Works

[One-shot cron fires at scheduled time]
         ↓
[Main session agent runs]
         ↓
[Reads config + topics/preferences from topics.md]
         ↓
[Selects 2-3 topics based on user preferences]
         ↓
[Composes a personalized message]
         ↓
[Sends to user via openclaw message send]
         ↓
[Updates user preferences in topics.md]
         ↓
[Schedules next random trigger]
         ↓
[Deletes itself β€” chain continues permanently]

Workflow

Phase 1: Initial Setup (One Time Only)

When the user first installs and activates Smart Surprise, an initial one-shot cron job must be created. This is the only manual step β€” everything after is automatic and self-learning.

See references/setup.md for the complete step-by-step setup guide.

Phase 2: Runtime (Self-Perpetuating Chain)

Each triggered run executes the following steps:

Step 1: Read configuration and preferences

  • Read ~/.openclaw/workspace/skills/smart-surprise/config.json β€” static settings (timezone, location, intervals, etc.)
  • Read ~/.openclaw/workspace/skills/smart-surprise/references/topics.md β€” available topics + learned user preferences

    • Step 2: Determine the next trigger time

  • Generate a random delay between minIntervalMinutes and maxIntervalMinutes
  • If the next trigger would fall inside quiet hours β†’ shift to quietHoursEnd
  • Write the next scheduled time to ~/.openclaw/workspace/skills/smart-surprise/next_run.json

    • Step 3: Compose the message

  • Check current time and day in the user's configured timezone
  • Randomly select 2-3 topics from the active pool, weighted by user preference (topics the user likes are more likely to be selected)
  • Always include β‰₯1 interaction topic (greeting, time-care, or check-in)
  • Combine into a structured message: Opening β†’ Body β†’ Closing
  • Generate content for each selected topic

    • Step 4: Deliver the message 

    openclaw message send --channel  --target  --message ""

    Step 5: Learn from this interaction

  • After sending, silently update topics.md with any preference signals observed in this session
  • Examples of preference signals:
    • - User explicitly says "I don't like this topic" β†’ record as disliked - User responds positively to a topic β†’ record as liked - User asks for more of something β†’ increase weight - User never responds to a topic β†’ decrease weight
  • The next run reads the updated preferences automatically

    • Step 6: Schedule the next run

  • Use openclaw cron add with the random delay
  • Set deleteAfterRun: true on the new job
  • The job fires, executes, schedules the next, and deletes itself

    • Step 7: Exit

  • The deleteAfterRun: true flag ensures self-deletion after completion
  • No session cleanup needed β€” the main session handles this automatically

    • Topics System

    The topics system replaces the traditional "content categories" approach with a learnable, extensible topic pool.

    Topics

    The skill ships with 11 initial topics:

  • greeting β€” Warm, casual opening (interaction)
  • time-care β€” Time-aware contextual care (interaction)
  • weather β€” Weather-based practical suggestions (requires location in config)
  • calendar β€” Google Calendar reminders (requires calendar integration)
  • health β€” Health micro-tips
  • tips β€” Useful tips and life hacks
  • history β€” "On this day" historical facts
  • entertainment β€” Movie/music recommendations
  • quote β€” Quotes and poems
  • news β€” Top news of the day
  • check-in β€” Emotional connection / wellbeing question (interaction)

    • Topic Extensibility

    This is not a closed list. Users or the agent can add new topics at any time by editing topics.md. The agent can also create new topics during runtime if the user's interests suggest one.

    Preference Learning

    Each topic in topics.md has a preference state: normal, preferred, or dislike. The agent updates these after each interaction based on user signals.

  • normal β€” selected at normal frequency
  • preferred β€” selected more often
  • dislike β€” selected much less often (never fully excluded)

    • The agent listens for signals like "I love this" β†’ preferred, "stop" β†’ dislike, "talk more about Y" β†’ preferred. check-in can never be dislike.

    Combination Rules

  • Every message must contain at least 1 interaction topic
  • Default: 2 topics per message (1 interaction + 1 informational)
  • Maximum: 3 topics per message (never overwhelm)

    • Message Structure

    1. Opening:  greeting or time-care  (sets emotional tone)
2. Body:     1-2 informational topics  (tips/news/quote/etc.)
3. Closing:  check-in or time-care  (invites a response)

    See references/topics.md for the complete topic definitions, default weights, and preference learning rules.

    Configuration

    All static configuration is in ~/.openclaw/workspace/skills/smart-surprise/config.json. No hardcoded values.

    | Parameter | Default | Description | |-----------|---------|-------------| | timezone | Asia/Shanghai | User's IANA timezone | | location | (required for weather) | City for weather lookups (e.g., Beijing, New York) | | quietHoursStart | 22:00 | Quiet hours start (HH:MM) | | quietHoursEnd | 08:00 | Quiet hours end (HH:MM) | | minIntervalMinutes | 60 | Minimum random wait (minutes) | | maxIntervalMinutes | 480 | Maximum random wait (minutes) | | channel | (required) | OpenClaw channel name (telegram, discord, etc.) | | channelTarget | (required) | Recipient ID on that channel (chat ID, user ID, etc.) | | characteristics | "warm, casual, playful" | Natural language description of preferred communication style |

    See references/config.md for the complete schema.

    Credentials & Sensitive Files

    Google Calendar Integration (optional): If you enable the calendar topic, the skill will attempt to read Google OAuth credentials. Two supported paths:

  • ~/.openclaw/secrets/google-calendar.json β€” OAuth token file
  • ~/.openclaw/scripts/google-calendar.py β€” helper script

    • ⚠️ These files contain sensitive tokens. Only provide access if you trust the skill and understand what these files contain. If not configured, the calendar topic silently produces no output (no error is shown).

    File Structure

    ~/.openclaw/workspace/skills/smart-surprise/
β”œβ”€β”€ config.json            # Static configuration (timezone, location, intervals)
β”œβ”€β”€ next_run.json          # Runtime state β€” written by the agent, do NOT edit
└── references/
    β”œβ”€β”€ setup.md           # Installation guide
    β”œβ”€β”€ topics.md          # Topic definitions + user preference learning
    └── config.md          # Configuration field reference

    Skill Metadata

  • Type: Proactive interaction / personal companion
  • Trigger mechanism: Self-perpetuating cron chain (one-shot jobs, auto-delete)
  • Delivery: User-configured channel (Telegram, Discord, WhatsApp, etc.)
  • Learning: Continuous, preference-based topic weighting in topics.md
  • Installation: One-time manual setup; chain runs forever and learns over time
  • Context: Each run uses main session (sees conversation history)

    • βš™οΈ Configuration

    All static configuration is in ~/.openclaw/workspace/skills/smart-surprise/config.json. No hardcoded values.

    | Parameter | Default | Description | |-----------|---------|-------------| | timezone | Asia/Shanghai | User's IANA timezone | | location | (required for weather) | City for weather lookups (e.g., Beijing, New York) | | quietHoursStart | 22:00 | Quiet hours start (HH:MM) | | quietHoursEnd | 08:00 | Quiet hours end (HH:MM) | | minIntervalMinutes | 60 | Minimum random wait (minutes) | | maxIntervalMinutes | 480 | Maximum random wait (minutes) | | channel | (required) | OpenClaw channel name (telegram, discord, etc.) | | channelTarget | (required) | Recipient ID on that channel (chat ID, user ID, etc.) | | characteristics | "warm, casual, playful" | Natural language description of preferred communication style |

    See references/config.md for the complete schema.