stack/packages/skills/calendar/SKILL.md

name, description

name	description
mosaic-plugin-calendar	Integration with Mosaic Stack's Events API for calendar management. Use when the user wants to schedule, view, update, or cancel events/meetings/appointments in their Mosaic calendar, including queries like "schedule a meeting", "what's on my calendar", "upcoming events", "cancel meeting", or "reschedule appointment".

Mosaic Calendar

Integration with Mosaic Stack's Events API for comprehensive calendar management.

Quick Start

Use scripts/calendar.js for all calendar operations. The script handles authentication and API communication automatically.

Creating Events

node scripts/calendar.js create \
  --title "Team Meeting" \
  --start "2024-01-30T15:00:00Z" \
  --end "2024-01-30T16:00:00Z" \
  --description "Weekly sync" \
  --location "Conference Room A"

Natural language examples:

• "Schedule a meeting tomorrow at 3pm"
• "Create an event called 'dentist appointment' on Friday at 2pm"
• "Add a recurring standup every weekday at 9am"

Querying Events

# List all upcoming events
node scripts/calendar.js list

# Events in a date range
node scripts/calendar.js list \
  --from "2024-01-30" \
  --to "2024-02-05"

# Events for a specific project
node scripts/calendar.js list --project-id "uuid-here"

Natural language examples:

• "What's on my calendar this week?"
• "Show me upcoming events"
• "What do I have scheduled for tomorrow?"
• "Any meetings today?"

Updating Events

node scripts/calendar.js update EVENT_ID \
  --title "Updated Title" \
  --start "2024-01-30T16:00:00Z"

Natural language examples:

• "Move my 3pm meeting to 4pm"
• "Reschedule tomorrow's dentist appointment to Friday"
• "Change the location of my team meeting to Zoom"

Deleting Events

node scripts/calendar.js delete EVENT_ID

Natural language examples:

• "Cancel my meeting with Sarah"
• "Delete tomorrow's standup"
• "Remove the 3pm appointment"

Event Fields

• title (required): Event name (1-255 characters)
• startTime (required): ISO 8601 date string (e.g., "2024-01-30T15:00:00Z")
• endTime (optional): ISO 8601 date string
• description (optional): Event details (max 10,000 characters)
• location (optional): Physical or virtual location (max 500 characters)
• allDay (optional): Boolean flag for all-day events
• recurrence (optional): Recurrence rules (object)
• projectId (optional): Link event to a Mosaic project (UUID)
• metadata (optional): Custom key-value data (object)

Date Handling

When processing natural language date/time requests:

1. Convert to ISO 8601 format (e.g., "2024-01-30T15:00:00Z")
2. Handle relative dates ("tomorrow", "next week", "Friday")
3. Infer end time if not specified (default: 1 hour after start)
4. Use user's timezone (America/Chicago) unless specified otherwise

Response Format

All operations return JSON:

{
  "id": "uuid",
  "title": "Team Meeting",
  "startTime": "2024-01-30T15:00:00Z",
  "endTime": "2024-01-30T16:00:00Z",
  "description": "Weekly sync",
  "location": "Conference Room A",
  "allDay": false,
  "workspaceId": "uuid",
  "createdBy": "uuid",
  "projectId": null,
  "recurrence": null,
  "metadata": {},
  "createdAt": "2024-01-29T10:00:00Z",
  "updatedAt": "2024-01-29T10:00:00Z"
}

List queries return paginated results with metadata:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 100,
    "totalPages": 2
  }
}

Environment

The script reads configuration from:

• MOSAIC_API_URL (default: http://localhost:3001)
• MOSAIC_WORKSPACE_ID (required)
• MOSAIC_API_TOKEN (required for authentication)

Ensure these are set in the environment or .env file.

Error Handling

Common errors:

• 401 Unauthorized: Missing or invalid API token
• 403 Forbidden: Insufficient workspace permissions
• 404 Not Found: Event ID doesn't exist
• 400 Bad Request: Invalid date format or missing required fields

When operations fail, the script outputs clear error messages with guidance on resolution.