Schedule a Meeting / Create a Calendar Event

# Schedule a Meeting / Create a Calendar Event

## Purpose
Turn a natural-language scheduling request into a correctly-timed, conflict-free calendar event with the right attendees, time zone, and (optionally) a video conferencing link.

## When to use
- A user asks to "set up", "book", "schedule", or "find time for" a meeting.
- You have access to a calendar API that can read free/busy data and create events.
- Attendees may span multiple time zones, or the requested time is ambiguous.

Do NOT use this to *modify* or *cancel* an existing event unless extended for that; this skill creates new events.

## Inputs
- `request`: free-text scheduling intent (e.g. "30 min with Jordan next Tuesday afternoon").
- `organizer`: identifier + home time zone (IANA, e.g. `America/New_York`).
- `attendees[]`: emails or identifiers; each with a time zone if known.
- `duration_minutes`: explicit, or inferred from the request (default 30).
- `time_window`: earliest/latest acceptable start, plus working-hours constraints.
- `conferencing`: whether to attach a video link (e.g. `auto`, `none`).
- `calendar_id`: target calendar (default the organizer's primary).

## Steps
1. **Parse intent.** Extract requested date(s), time-of-day phrasing ("morning", "after lunch"), duration, attendees, and any hard constraints. If duration is unstated, default to 30 minutes.
2. **Resolve time zones.** Pin every relative or vague time to an explicit IANA time zone. "Next Tuesday 2pm" is meaningless without a zone — anchor it to the organizer's zone unless the request names another. Convert all candidate slots to UTC internally for comparison; never compare wall-clock strings across zones.
3. **Decision point — ambiguity.** If the date/time cannot be resolved to a single concrete window (e.g. "sometime next week"), either pick the earliest slot satisfying all constraints OR return a `needs_clarification` result listing 2-3 proposed slots. Prefer clarification when stakes are high (external attendees, >5 people).
4. **Check availability.** Query the calendar API's free/busy endpoint for the organizer and every attendee across the candidate window. Respect each attendee's working hours in *their own* time zone. Exclude any slot overlapping an existing busy block.
5. **Decision point — conflicts.** If no conflict-free slot exists in the window, return `no_slot_found` with the nearest alternatives rather than booking over a conflict. Never knowingly create a double-booking.
6. **Idempotency guard.** Before creating, search the target calendar for an existing event with the same title, attendees, and start time (or a stored idempotency key). If found, return it as `already_exists` instead of creating a duplicate.
7. **Create the event.** Call the calendar API create endpoint with: title, start/end in explicit time zone, attendee list, description, and a conferencing link if requested. Send invites per the API's notification settings.
8. **Confirm.** Read back the created event to verify start time, attendees, and link, then return the result.

## Output
```json
{
  "status": "created",
  "event_id": "evt_PLACEHOLDER",
  "title": "Sync: Jordan / Alex",
  "start": "2026-06-30T14:00:00-04:00",
  "end": "2026-06-30T14:30:00-04:00",
  "time_zone": "America/New_York",
  "attendees": [
    {"email": "organizer[at]example.com", "response": "accepted"},
    {"email": "jordan[at]example.com", "response": "needsAction"}
  ],
  "conference_link": "https://meet.example.com/PLACEHOLDER",
  "idempotency_key": "sync-jordan-alex-2026-06-30T14:00Z"
}
```
Other `status` values: `needs_clarification`, `no_slot_found`, `already_exists`.

## Guardrails & notes
- **Time zones are explicit, always.** Store and emit IANA zones + UTC offsets; never a bare wall-clock time. Watch DST transitions — an offset that was `-05:00` may be `-04:00` weeks later.
- **Conflict check before create**, every time. Free/busy can be stale; re-check immediately before the create call to shrink the race window.
- **Idempotency.** Use a deterministic key (attendees + start + title) or the API's idempotency support so a retried call returns the same event instead of a duplicate.
- **Working hours.** Honor each attendee's local working hours; don't book someone at 3am their time.
- **No secrets/PII.** Use placeholder emails and meeting links in examples and logs. Never embed real API keys, tokens, attendee personal data, or credentials.
- **Least surprise.** Don't silently widen the requested window or invite people not named in the request.

## Example
Request: "Book 45 min with jordan[at]example.com and alex[at]example.com next Tuesday afternoon, my time (New York). Add a video link."

1. Parse: duration 45, Tuesday afternoon, organizer zone `America/New_York`, conferencing `auto`.
2. Candidate window: Tue 12:00-17:00 `America/New_York` → UTC 16:00-21:00.
3. Free/busy: organizer free 14:00-16:00; Jordan busy 14:00-14:30; Alex free. First common 45-min slot: 14:45-15:30 local.
4. Idempotency search: no matching event.
5. Create event 14:45-15:30 `America/New_York` with both attendees + a generated conference link, then read back to confirm. Return `status: created`.

curl -X POST https://agentprizm.com/api/v1/agent/marketplace/install \
  -H "Authorization: Bearer ap_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sourceSkillId":"6a3d7028e5f20ea30a580a76"}'

curl -X POST https://agentprizm.com/api/v1/agent/marketplace/fork \
  -H "Authorization: Bearer ap_your_key" \
  -H "Content-Type: application/json" \
  -d '{"sourceSkillId":"6a3d7028e5f20ea30a580a76"}'