Focus Break Reminder

Workspace wellness break reminder with configurable work interval, cooldown, idle reset, quiet hours, and per-day caps. Use when users want OpenClaw to remin...

Security Scan

This instruction-only reminder skill is internally consistent with its stated purpose: it needs no credentials, no installs, and only asks to persist minimal per-user timestamps to a small JSON file for restart survival.

Purpose & Capability

Name and description match the instructions: a local, per-user/session break reminder. It requests no unrelated binaries, credentials, or external services.

Instruction Scope

Instructions stay within scope (track timestamps, evaluate eligibility, deliver templates, provide commands). They require persisting minimal state to a JSON file and integrating with inbound message handling and a heartbeat, but do not instruct reading unrelated files, environment variables, or contacting external endpoints. The storage path for the JSON is unspecified — this is expected for an instruction-only skill but the operator should confirm where files will be written and with what permissions.

Install Mechanism

No install spec or code is included (instruction-only), so nothing is downloaded or written by an installer. This is low-risk from an install perspective.

Credentials

The skill declares no required environment variables, credentials, or config paths. The requested data (timestamps, counters, simple settings) is minimal and proportionate to the stated functionality.

Persistence & Privilege

The skill persists a small JSON state file (normal for this use). It does not set always:true and does not request elevated privileges. Be aware the platform default allows autonomous invocation; if you do not want the agent to run reminders without explicit user action, adjust invocation permissions in the platform.

Assessment

This skill appears coherent and low-risk: it only needs to store simple timestamps and settings and doesn't ask for credentials or external access. Before installing, confirm where the JSON state file will be stored and ensure the location and file permissions meet your privacy policies. Decide whether you want the agent to run reminders autonomously (platform default) or only when explicitly invoked, and verify reminder templates and quiet-hour defaults match your users' expectations. If you need stronger guarantees, run the skill in a sandboxed environment and verify it only writes the minimal fields documented in SKILL.md.

Implement a lightweight per-user/session state machine that triggers rest reminders without spamming.

Configure

Create or load references/config.example.json as the default schema.

Required settings:

• enabled
• timezone
• work_minutes
• cooldown_minutes
• idle_reset_minutes
• daily_max_reminders
• quiet_hours
• snooze_until
• templates

Prefer defaults that are practical and non-intrusive:

• work interval: 50 minutes
• cooldown: 30 minutes
• idle reset: 15 minutes
• daily cap: 4

Track state

Maintain minimal state per user (or per DM/chat for first version):

• session_start_at
• last_active_at
• last_remind_at
• remind_count_today
• today_key

Persist to a small JSON file so reminders survive restarts.

Update activity

On each inbound user message:

1. If date changed in configured timezone, reset remind_count_today and today_key.
2. If idle time since last_active_at >= idle_reset_minutes, reset session_start_at to now.
3. Set last_active_at to now.

Evaluate reminder eligibility

Only remind when all conditions pass:

1. enabled is true.
2. Not in quiet hours.
3. Not snoozed (now < snooze_until means skip).
4. Daily cap not exceeded.
5. Active duration (now - session_start_at) >= work_minutes.
6. Cooldown passed (now - last_remind_at) >= cooldown_minutes.

If all pass, send one reminder and set:

• last_remind_at = now
• remind_count_today += 1

Reminder delivery

Use one short template per reminder. Keep copy practical and non-medical.

Example template:

• “你已经连续工作一段时间了。现在起身 2 分钟、喝口水，再看 20 秒远处 👀”

Commands

Support these chat commands:

• /break on → enable reminders
• /break off → disable reminders
• /break status → show current config + next eligible reminder window
• /break set <minutes> → update work_minutes
• /break snooze <minutes> → set snooze_until = now + minutes

Validate numeric ranges (e.g., 15–180 for work interval).

Heartbeat integration

Use heartbeat polling to run eligibility checks when there is recent activity. Avoid noisy polling loops.

Recommended behavior:

• If no user activity for a long period, skip checks.
• If reminder was just sent, honor cooldown and return quickly.

Safety and UX boundaries

• Do not provide medical diagnosis or treatment advice.
• Keep reminders optional and easy to disable.
• Store only minimum timestamps and settings needed for reminder logic.
• Use clear language when data is missing: “待补充”.

Testing checklist

Use references/test-cases.md.

At minimum verify:

• triggers at/after work interval
• cooldown suppresses duplicates
• idle reset restarts session timer
• quiet hours suppress reminders
• snooze suppresses reminders until expiry
• daily cap blocks additional reminders