Smart Surprise

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

Security Scan

The skill's behavior (self-scheduling cron chain, autonomous messaging, and silent preference updates) is coherent with its description but grants persistent autonomous actions and access to user files/optional calendar credentials that users should explicitly consent to and monitor.

Purpose & Capability

The skill's name and description match what the SKILL.md instructs: composing personalized messages, sending them via openclaw message send, and scheduling cron jobs. Required artifacts (config.json, topics.md, next_run.json) are consistent with a proactive messaging companion. No unrelated environment variables or binaries are requested.

Instruction Scope

Runtime instructions instruct the agent to read and write files under ~/.openclaw/workspace/skills/smart-surprise/, silently update topics.md on every run, and to create an indefinite chain of cron jobs that autonomously trigger the agent. Silent updates to user preference files and the permanent self-perpetuating cron chain are within the skill's purpose but are significant scope/surprise for non-technical users and could be used to persistently send messages or change local state without explicit per-run consent.

Install Mechanism

No install spec or remote downloads; this is an instruction-only skill with only local text files. That minimizes installer risk (no arbitrary code fetched at install time).

Credentials

The skill declares no required env vars or primary credential (good). It does, however, optionally read Google Calendar OAuth credentials from ~/.openclaw/secrets/google-calendar.json if the calendar topic is enabled — that is expected for calendar integration but involves sensitive tokens. The skill also assumes the OpenClaw messaging channels (Telegram/Discord/etc.) are already configured at the platform level so the agent can call openclaw message send; those platform credentials are not requested here but will be used by the cron-run agent.

Persistence & Privilege

Although always:false, the skill explicitly instructs creating a self-perpetuating sequence of cron jobs that run indefinitely and can autonomously send messages and modify topics.md. This grants ongoing autonomous presence and action on the host. Combined with silent updates and optional access to calendar credentials, this persistent capability is a notable privilege and user-risk vector.

What to consider before installing

What to consider before installing: 1) This skill will create repeating, self-managed cron jobs that run the agent autonomously and send messages to the configured channel — verify you want the assistant to reach out without per-message consent. 2) It will read/write files in ~/.openclaw/workspace/skills/smart-surprise/ (config.json, topics.md, next_run.json) and will silently update topics.md after each run; if you prefer manual control, do not enable. 3) If you enable the calendar topic, the skill may read Google OAuth tokens from ~/.openclaw/secrets/google-calendar.json — only provide those tokens if you trust the skill. 4) Before activating, set conservative min/max intervals and quiet hours in config.json and test with an isolated channel or test account. 5) To stop the skill, remove its cron jobs (openclaw cron list / rm) and delete ~/.openclaw/workspace/skills/smart-surprise. 6) If you are unsure, inspect or back up topics.md and config.json and monitor cron jobs/logs for unexpected behavior. If you want lower risk, avoid granting calendar credentials and keep longer intervals or run manually rather than using the self-perpetuating cron chain.

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 <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 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)