Proactively engages users with personalized casual messages at random intervals, learning preferences to deliver warm, varied conversations and check-ins.
---
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](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 <channel> --target <channelTarget> --message "<composed_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](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](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)
don't have the plugin yet? install it then click "run inline in claude" again.