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:

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

• calendar.sh

• Bash script for macOS

• calendar.ps1

• PowerShell script for Windows

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

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:

• Take the directory of this SKILL.md file

• 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 LobsterAI"

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:

• Always use ISO 8601 format: YYYY-MM-DDTHH:mm:ss

• Use local timezone: Do NOT use UTC or timezone suffixes (like +08:00 or Z)

• Calculate dates yourself: Do NOT use shell command substitution like $(date ...)

• Claude should compute dates: Based on current date, calculate target dates directly

• 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 LobsterAI

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

• scheduled-task - For recurring calendar synchronization