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:

bash

# 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:

bash

# 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

bash

# 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

bash

# 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

bash

# 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

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

Search Events

bash

# 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

json

{
  "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

json

{
  "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

bash

# 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

bash

# 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

bash

# 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

bash

# 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:

bash

# 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

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:

bash

# 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:

bash

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:

powershell

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

local-tools

NPX Install

Tags

SKILL.md Content

Local Tools Skill

When to Use This Skill

How It Works

Platform Support

Permissions

macOS

Windows

Calendar Operations

Best Practices for AI Assistant

List Events

Create Event

Update Event

Delete Event

Search Events

Output Format

Success Response

Error Response

Error Codes

Date Format Guidelines

Important: Date Format Guidelines

Common Patterns

Pattern 1: Schedule Management

Pattern 2: Meeting Scheduling

Pattern 3: Event Search

Pattern 4: Availability Check

Known Behaviors

Time Range Matching

All-Day Events

Time Precision

Recurring Events

Best Practices

1. Always Check Before Creating

2. Use Specific Calendars (macOS)

3. Search Before Updating/Deleting

4. Handle Errors Gracefully

Limitations

macOS

Windows

General

Troubleshooting

macOS

Windows

Technical Details

macOS Implementation

Windows Implementation

Cross-Platform Consistency

Related Skills