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,
/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
"
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
"
List events for specific date range
bash
"
List events from specific calendar (macOS)
bash
"
Create a simple event
bash
"
Create event with location and notes
bash
"
Update event title
bash
"
Update event time
bash
"
Search for events containing keyword (searches ALL calendars)
bash
"
Search in specific calendar only
- bash
- "
/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
"
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
"
User asks: "Schedule a meeting for tomorrow at 3 PM"
Claude's approach:
bash
"
User asks: "Find all meetings about the project"
Claude's approach:
bash
"
User asks: "Am I free tomorrow afternoon?"
Claude's approach:
1. List tomorrow's events
2. Analyze time slots
3. Report availability
bash
"
First check existing events
bash
"
Then create if no conflict
bash
"
Search to find event ID
bash
"
Then update or delete
bash
"
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
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