upcoming-dates - SKILL.md Agent Skill

name: upcoming-dates description: Daily scheduled task (8am) — check for important dates (birthdays, anniversaries) in the next 7 days, draft date notifications, and deliver via notify. version: 1.0.0 tags: [relationship, scheduling, dates]

Upcoming Dates Check

Scheduled daily at 8am. Check for important dates in the next 7 days and draft date notifications for delivery via Telegram.

Purpose

Proactively surface upcoming birthdays, anniversaries, and other important dates so the user can prepare and reach out to contacts at the right time.

Tool Sequence

Step 1: Query Upcoming Dates

upcoming_dates(days_ahead=7)

Returns a list of upcoming dates across all contacts within the next 7 days.

Step 2: Enrich Each Date Entry

For each date returned, gather context to make the notification meaningful:

# Get contact details
contact_get(contact_id="<contact_id>")

# Pull recent notes for personal context
note_list(contact_id="<contact_id>", limit=3)

# Check interaction history
interaction_list(contact_id="<contact_id>", limit=1)

# Check if there's a pending gift idea for this occasion
gift_list(contact_id="<contact_id>")

Step 3: Check for Existing Calendar Events

Avoid duplicate notifications for dates already scheduled:

calendar_list_events(start_at=<today>, end_at=<today + 14 days>)

Filter the returned events by title or description to identify any that already cover this date. Skip drafting a notification if a matching calendar event already exists for this contact's date.

Step 4: Draft Notification Messages

For each upcoming date without an existing calendar event, compose a personalized message:

Birthday format:

[Name]'s birthday is [date] ([X days away]).
[Context: last interaction summary, recent note if relevant, pending gift if any]

Anniversary format:

[Name and user's] [X-year] anniversary is [date] ([X days away]).
[Context if relevant]

Other date format:

[Date label] for [Name] is [date] ([X days away]).

Step 5: Deliver via notify

Send the compiled date digest to the user:

notify(
    channel="telegram",
    message="<compiled date digest>",
    intent="send"
)

If there are no upcoming dates in the next 7 days, skip the notify call entirely (no empty messages).

Message Format

When multiple dates are upcoming, compile them into a single digest message rather than sending one message per date:

Upcoming dates this week:

- Sarah's birthday is tomorrow (March 15). You last talked 3 weeks ago — she was excited about her pottery class.
- John and Alex's 5-year friendiversary is Friday. Consider reaching out.
- Mom's birthday is in 5 days (March 19). Gift idea on record: noise-canceling headphones.

Edge Cases

Today's date: If a date is today, use "today" not "0 days away"
Tomorrow: Use "tomorrow" for clarity
No upcoming dates: Do not send a message — silence is correct behavior
Already scheduled: Check calendar_list_events to avoid duplicate notifications
Multiple dates for same contact: Group them together in the digest

Integration Notes

This skill is triggered by the upcoming-dates-check schedule entry in butler.toml (cron: 0 8 * * *)
The upcoming_dates tool queries across all contacts in the relationship schema
Use date_list(contact_id) if you need to pull dates for a specific contact directly
After sending the digest, optionally create calendar events for upcoming dates so the user can track them