local-tools

name	local-tools
description	Access local system resources including Calendar on macOS and Windows. Use this skill when you need to manage user's schedule directly on their device.
official	true

Local Tools Skill

When to Use This Skill

Use the local-tools skill when you need to:

• Calendar Management - View, create, update, or delete calendar events

Examples of when to use:

• User: "Show me my schedule for tomorrow"
• User: "Create a meeting at 3 PM"
• User: "Search for calendar events containing 'project'"
• User: "Delete tomorrow's meeting"

How It Works

┌──────────┐    Bash/PowerShell    ┌─────────────────────────────────────────────────────────────┐
│  Claude  │──────────────────────▶│  calendar.sh / calendar.ps1                                 │
│          │                       │  ├─ macOS: osascript -l JavaScript (JXA) ──▶ Calendar.app   │
│          │                       │  └─ Windows: PowerShell ──▶ Outlook COM API                 │
└──────────┘                       └─────────────────────────────────────────────────────────────┘

Architecture:

1. CLI Scripts - Platform-specific scripts, no HTTP server needed

   • calendar.sh - Bash script for macOS
   • calendar.ps1 - PowerShell script for Windows

2. Local Calendar Access - Direct access to system calendar

   • macOS: Uses JXA (JavaScript for Automation) to control Calendar.app
   • Windows: Uses PowerShell COM API to control Microsoft Outlook

3. JSON Output - Structured data format for easy parsing

Platform Support

Platform	Implementation	Calendar App	Status
macOS 10.10+	JXA + Calendar.app	Calendar.app	✅ Fully Supported
Windows 7+	PowerShell + COM	Microsoft Outlook	✅ Fully Supported
Linux	-	-	❌ Not Supported

Permissions

macOS

• Requires "Calendar" access permission
• User will be prompted on first use
• Can be managed in: System Settings > Privacy & Security > Calendar

Windows

• Requires Microsoft Outlook to be installed
• May require administrative privileges for COM access

Calendar Operations

IMPORTANT: How to Locate the Script

When you read this SKILL.md file using the Read tool, you receive its absolute path (e.g., /Users/username/.../SKILLs/local-tools/SKILL.md).

To construct the script path:

1. Take the directory of this SKILL.md file
2. Append /scripts/calendar.sh (macOS) or /scripts/calendar.ps1 (Windows)

Example:

# If SKILL.md is at: /Users/username/path/to/SKILLs/local-tools/SKILL.md
# Then the script is: /Users/username/path/to/SKILLs/local-tools/scripts/calendar.sh

bash "/Users/username/path/to/SKILLs/local-tools/scripts/calendar.sh" <operation> [options]

In all examples below, <skill-dir>/scripts/calendar.sh is a placeholder. Replace it with the actual absolute path.

Best Practices for AI Assistant

DO:

• ✅ Execute commands directly without showing trial-and-error process
• ✅ If command fails, inform user about permission issues without showing technical errors
• ✅ Use search command for searching birthdays/anniversaries
• ✅ If no calendar name specified, script will automatically use first available calendar

DON'T:

• ❌ Don't repeatedly try different command combinations
• ❌ Don't show error stacks or technical details to users
• ❌ Don't read script source code to analyze issues
• ❌ Don't ask users for calendar name, use default behavior

Example - Searching for birthdays:

# Correct approach: Search directly, don't trial-and-error
bash "<skill-dir>/scripts/calendar.sh" search --query "birthday"

# If permission error returned, directly tell user:
# "Calendar access permission is required. Please open System Settings > Privacy & Security > Calendar, and authorize Terminal or Popiai"

List Events

# List events for next 7 days (default)
bash "<skill-dir>/scripts/calendar.sh" list

# List events for specific date range
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-12T00:00:00" \
  --end "2026-02-19T23:59:59"

# List events from specific calendar (macOS)
bash "<skill-dir>/scripts/calendar.sh" list \
  --calendar "Work"

Create Event

# Create a simple event
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Team Meeting" \
  --start "2026-02-13T14:00:00" \
  --end "2026-02-13T15:00:00"

# Create event with location and notes
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Client Call" \
  --start "2026-02-14T10:00:00" \
  --end "2026-02-14T11:00:00" \
  --calendar "Work" \
  --location "Conference Room A" \
  --notes "Discuss Q1 roadmap"

Update Event

# Update event title
bash "<skill-dir>/scripts/calendar.sh" update \
  --id "EVENT-ID" \
  --title "Updated Meeting Title"

# Update event time
bash "<skill-dir>/scripts/calendar.sh" update \
  --id "EVENT-ID" \
  --start "2026-02-13T15:00:00" \
  --end "2026-02-13T16:00:00"

Delete Event

bash "<skill-dir>/scripts/calendar.sh" delete \
  --id "EVENT-ID"

Search Events

# Search for events containing keyword (searches ALL calendars)
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "meeting"

# Search in specific calendar only
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "project" \
  --calendar "Work"

Note: When --calendar is not specified, the search operation will look through all available calendars on both macOS and Windows.

Output Format

All commands return JSON with the following structure:

Success Response

{
  "success": true,
  "data": {
    "events": [
      {
        "eventId": "E621F8C4-...",
        "title": "Team Meeting",
        "startTime": "2026-02-13T14:00:00.000Z",
        "endTime": "2026-02-13T15:00:00.000Z",
        "location": "Conference Room",
        "notes": "Weekly sync",
        "calendar": "Work",
        "allDay": false
      }
    ],
    "count": 1
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "CALENDAR_ACCESS_ERROR",
    "message": "Calendar access permission is required...",
    "recoverable": true,
    "permissionRequired": true
  }
}

Error Codes

Code	Meaning	Recoverable
CALENDAR_ACCESS_ERROR	Permission denied or calendar not accessible	Yes
INVALID_INPUT	Missing required parameters	No
EVENT_NOT_FOUND	Event ID not found	No
OUTLOOK_NOT_AVAILABLE	Microsoft Outlook not installed (Windows)	Yes

Date Format Guidelines

Important: Date Format Guidelines

When using the list command with time ranges:

1. Always use ISO 8601 format: YYYY-MM-DDTHH:mm:ss
2. Use local timezone: Do NOT use UTC or timezone suffixes (like +08:00 or Z)
3. Calculate dates yourself: Do NOT use shell command substitution like $(date ...)
4. Claude should compute dates: Based on current date, calculate target dates directly
5. Examples:
   • Today at midnight: 2026-02-13T00:00:00
   • Today at end of day: 2026-02-13T23:59:59
   • Tomorrow morning: 2026-02-14T09:00:00
   • Next week Monday: 2026-02-16T00:00:00

Why: The script expects local time strings that match your system timezone. Shell substitutions may not execute correctly in all environments.

Common Patterns

Pattern 1: Schedule Management

# User asks: "What meetings do I have today?"
# Claude's approach: Calculate today's date and query full day from 00:00 to 23:59
# IMPORTANT: Claude should replace 2026-02-13 with the actual current date
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-13T00:00:00" \
  --end "2026-02-13T23:59:59"

# User asks: "What's on my schedule tomorrow?"
# Claude should calculate tomorrow's date (e.g., if today is 2026-02-13, tomorrow is 2026-02-14)
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-14T00:00:00" \
  --end "2026-02-14T23:59:59"

Pattern 2: Meeting Scheduling

# User asks: "Schedule a meeting for tomorrow at 3 PM"
# Claude's approach:
bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Meeting" \
  --start "2026-02-13T15:00:00" \
  --end "2026-02-13T16:00:00" \
  --calendar "Work"

Pattern 3: Event Search

# User asks: "Find all meetings about the project"
# Claude's approach:
bash "<skill-dir>/scripts/calendar.sh" search \
  --query "project" \
  --calendar "Work"

Pattern 4: Availability Check

# User asks: "Am I free tomorrow afternoon?"
# Claude's approach:
# 1. List tomorrow's events
# 2. Analyze time slots
# 3. Report availability
bash "<skill-dir>/scripts/calendar.sh" list \
  --start "2026-02-14T00:00:00" \
  --end "2026-02-14T23:59:59"

Known Behaviors

Time Range Matching

The list command uses interval overlap detection:

• Returns events that have any overlap with the query time range
• Does NOT require events to be fully contained within the range

Examples:

• Query: 2026-02-13 00:00:00 to 23:59:59
• Returns:
  • ✅ Events fully on Feb 13 (e.g., 10:00-11:00)
  • ✅ Multi-day events spanning Feb 13 (e.g., Feb 12 10:00 - Feb 14 10:00)
  • ✅ Events crossing midnight (e.g., Feb 13 23:30 - Feb 14 00:30)
  • ❌ Events entirely before Feb 13 (e.g., Feb 12 10:00-11:00)
  • ❌ Events entirely after Feb 13 (e.g., Feb 14 10:00-11:00)

All-Day Events

• Treated as spanning from 00:00:00 to 23:59:59 on their date(s)
• Multi-day all-day events (e.g., Feb 12-14) will appear when querying any date within that range

Time Precision

• Comparisons use second-level precision
• Milliseconds are ignored in date comparisons

Recurring Events

• Each occurrence is treated as a separate event instance
• The script returns individual occurrences within the queried time range

Best Practices

1. Always Check Before Creating

Before creating an event, list existing events to avoid conflicts:

# First check existing events
bash "<skill-dir>/scripts/calendar.sh" list

# Then create if no conflict
bash "<skill-dir>/scripts/calendar.sh" create ...

2. Use Specific Calendars (macOS)

Specify the calendar to keep events organized:

bash "<skill-dir>/scripts/calendar.sh" create \
  --title "Team Meeting" \
  --calendar "Work" \
  ...

3. Search Before Updating/Deleting

Always search first to get the correct event ID:

# Search to find event ID
bash "<skill-dir>/scripts/calendar.sh" search --query "meeting"

# Then update or delete
bash "<skill-dir>/scripts/calendar.sh" update --id "FOUND-ID" ...

4. Handle Errors Gracefully

Parse the response and handle errors:

result=$(bash "<skill-dir>/scripts/calendar.sh" list)
if echo "$result" | grep -q '"success":true'; then
  # Process events
  events=$(echo "$result" | jq '.data.events')
else
  # Handle error
  error=$(echo "$result" | jq '.error.message')
  echo "Failed: $error"
fi

Limitations

macOS

• Requires macOS 10.10 Yosemite or later (for JXA support)
• Requires Calendar access permission
• Does not support advanced recurring event queries
• Cannot modify recurring event rules

Windows

• Requires Microsoft Outlook to be installed
• Does not support other calendar applications (Windows Calendar, Google Calendar, etc.)
• May require COM access permissions in corporate environments
• Folder enumeration may skip restricted calendars

General

• All dates must be in ISO 8601 format (YYYY-MM-DDTHH:mm:ss)
• Uses local timezone for all operations
• Return values are converted to UTC (ISO 8601 with Z suffix)
• No support for attendees or meeting invitations

Troubleshooting

macOS

Permission Denied:

Error: Calendar access permission is required

Solution: Open System Settings > Privacy & Security > Calendar, authorize Terminal or Popiai

Script Not Found:

bash: calendar.sh: No such file or directory

Solution: Ensure you're using the absolute path from SKILL.md's directory + /scripts/calendar.sh

Windows

Outlook Not Found:

Error: Microsoft Outlook is not installed or not accessible

Solution: Install Microsoft Outlook and ensure it's properly configured

PowerShell Execution Policy:

Error: Execution of scripts is disabled on this system

Solution: Run PowerShell as Administrator and execute:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Technical Details

macOS Implementation

JXA (JavaScript for Automation):

• Uses osascript -l JavaScript to execute JXA code
• Controls Calendar.app via Apple Events
• Works on both Intel and Apple Silicon Macs
• Requires user permission for Calendar access

Date Handling:

• Uses BSD date command (macOS native)
• Format: date +%Y-%m-%dT%H:%M:%S (local timezone)
• Relative dates: date -v+7d (7 days from now)

Windows Implementation

PowerShell + COM:

• Uses Outlook COM API via PowerShell
• Requires Outlook to be installed and configured
• Works with all Outlook-compatible calendars

Date Handling:

• Uses PowerShell [DateTime]::Parse() for date parsing
• Automatically handles local timezone

Cross-Platform Consistency

Both implementations:

• Use identical JSON output format
• Support the same operations (list, create, update, delete, search)
• Handle dates in local timezone
• Return UTC timestamps in ISO 8601 format

Related Skills

• imap-smtp-email - For email-based meeting invitations