local-tools

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Local Tools Skill

本地工具Skill

When to Use This Skill

何时使用此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"

当你需要以下操作时，可使用local-tools skill：

日历管理 - 查看、创建、更新或删除日历事件

使用场景示例：

用户："显示我明天的日程"
用户："创建一个下午3点的会议"
用户："搜索包含'项目'的日历事件"
用户："删除明天的会议"

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

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

架构：

CLI脚本 - 特定于平台的脚本，无需HTTP服务器
- ```
calendar.sh
```
  - 适用于macOS的Bash脚本
- ```
calendar.ps1
```
  - 适用于Windows的PowerShell脚本
本地日历访问 - 直接访问系统日历
- macOS：使用JXA（JavaScript for Automation）控制Calendar.app
- Windows：使用PowerShell COM API控制Microsoft Outlook
JSON输出 - 结构化数据格式，便于解析

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

平台	实现方式	日历应用	状态
macOS 10.10+	JXA + Calendar.app	Calendar.app	✅ 完全支持
Windows 7+	PowerShell + COM	Microsoft Outlook	✅ 完全支持
Linux	-	-	❌ 不支持

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

需要安装Microsoft Outlook
访问COM API可能需要管理员权限

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

undefined

重要提示：如何定位脚本

当你使用Read工具读取此SKILL.md文件时，会获取到它的绝对路径（例如：

/Users/username/.../SKILLs/local-tools/SKILL.md

）。

构造脚本路径的方法：

追加

/scripts/calendar.sh

（macOS）或

/scripts/calendar.ps1

（Windows）

示例：

bash

undefined

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.

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


以下所有示例中，`<skill-dir>/scripts/calendar.sh` 为占位符，请替换为实际的绝对路径。

Best Practices for AI Assistant

AI助手最佳实践

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

undefined

建议做法：

✅ 直接执行命令，无需展示反复尝试的过程
✅ 如果命令执行失败，告知用户权限问题，无需展示技术错误信息
✅ 使用
```
search
```
命令搜索生日/纪念日
✅ 如果未指定日历名称，脚本会自动使用第一个可用的日历

禁止做法：

❌ 不要反复尝试不同的命令组合
❌ 不要向用户展示错误堆栈或技术细节
❌ 不要读取脚本源代码来分析问题
❌ 不要询问用户日历名称，使用默认行为

示例 - 搜索生日：

bash

undefined

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"

undefined

undefined

List Events

列出事件

bash

undefined

bash

undefined

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"

undefined

bash "<skill-dir>/scripts/calendar.sh" list
--calendar "Work"

undefined

Create Event

创建事件

bash

undefined

bash

undefined

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"

undefined

undefined

Update Event

更新事件

bash

undefined

bash

undefined

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"

undefined

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

undefined

Delete Event

删除事件

bash

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

bash

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

Search Events

搜索事件

bash

undefined

bash

undefined

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.

bash "<skill-dir>/scripts/calendar.sh" search
--query "project"
--calendar "Work"


**注意：** 当未指定`--calendar`参数时，搜索操作会遍历macOS和Windows系统上的**所有可用日历**。

Output Format

输出格式

All commands return JSON with the following structure:

所有命令均返回JSON格式的结果，结构如下：

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
  }
}

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
  }
}

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

代码	含义	是否可恢复
`CALENDAR_ACCESS_ERROR`	权限被拒绝或日历无法访问	是
`INVALID_INPUT`	缺少必填参数	否
`EVENT_NOT_FOUND`	未找到指定ID的事件	否
`OUTLOOK_NOT_AVAILABLE`	未安装Microsoft Outlook（Windows）	是

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.

使用

list

命令查询时间范围时：

必须使用ISO 8601格式：
```
YYYY-MM-DDTHH:mm:ss
```
使用本地时区：不要使用UTC或时区后缀（如+08:00或Z）
自行计算日期：不要使用
```
$(date ...)
```
这类Shell命令替换
由Claude计算日期：根据当前日期直接计算目标日期

示例：

今日零点：
```
2026-02-13T00:00:00
```
今日23:59:59：
```
2026-02-13T23:59:59
```
明日上午9点：
```
2026-02-14T09:00:00
```
下周一：
```
2026-02-16T00:00:00
```

原因：脚本需要与系统时区匹配的本地时间字符串，Shell命令替换在部分环境中可能无法正常执行。

Common Patterns

常见使用模式

Pattern 1: Schedule Management

模式1：日程管理

bash

undefined

bash

undefined

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"

undefined

bash "<skill-dir>/scripts/calendar.sh" list
--start "2026-02-14T00:00:00"
--end "2026-02-14T23:59:59"

undefined

Pattern 2: Meeting Scheduling

模式2：会议安排

bash

undefined

bash

undefined

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"

undefined

bash "<skill-dir>/scripts/calendar.sh" create
--title "Meeting"
--start "2026-02-13T15:00:00"
--end "2026-02-13T16:00:00"
--calendar "Work"

undefined

Pattern 3: Event Search

模式3：事件搜索

bash

undefined

bash

undefined

User asks: "Find all meetings about the project"

Claude's approach:

bash "<skill-dir>/scripts/calendar.sh" search
--query "project"
--calendar "Work"

undefined

bash "<skill-dir>/scripts/calendar.sh" search
--query "project"
--calendar "Work"

undefined

Pattern 4: Availability Check

模式4：空闲时间查询

bash

undefined

bash

undefined

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"

undefined

bash "<skill-dir>/scripts/calendar.sh" list
--start "2026-02-14T00:00:00"
--end "2026-02-14T23:59:59"

undefined

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)

list

命令使用区间重叠检测：

返回与查询时间范围有任何重叠的事件
不要求事件完全包含在查询范围内

示例：

查询范围：2026-02-13 00:00:00 至 23:59:59
返回的事件：
- ✅ 完全在2月13日的事件（如10:00-11:00）
- ✅ 跨2月13日的多日事件（如2月12日10:00 - 2月14日10:00）
- ✅ 跨午夜的事件（如2月13日23:30 - 2月14日00:30）
- ❌ 完全在2月13日之前的事件（如2月12日10:00-11:00）
- ❌ 完全在2月13日之后的事件（如2月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

全天事件被视为在对应日期的00:00:00至23:59:59之间
多日全天事件（如2月12-14日）会在查询该范围内任意日期时显示

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

1. 创建前先检查

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

bash

undefined

创建事件前，先列出已有事件以避免冲突：

bash

undefined

First check existing events

bash "<skill-dir>/scripts/calendar.sh" list

Then create if no conflict

bash "<skill-dir>/scripts/calendar.sh" create ...

undefined

bash "<skill-dir>/scripts/calendar.sh" create ...

undefined

2. Use Specific Calendars (macOS)

2. 指定特定日历（macOS）

Specify the calendar to keep events organized:

bash

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

指定日历以保持事件分类有序：

bash

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

3. Search Before Updating/Deleting

3. 更新/删除前先搜索

Always search first to get the correct event ID:

bash

undefined

先执行搜索以获取正确的事件ID：

bash

undefined

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

undefined

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

undefined

4. Handle Errors Gracefully

4. 优雅处理错误

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

解析响应并处理错误：

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

需要macOS 10.10 Yosemite或更高版本（支持JXA）
需要日历访问权限
不支持高级重复事件查询
无法修改重复事件规则

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

需要安装Microsoft Outlook
不支持其他日历应用（Windows日历、谷歌日历等）
企业环境中可能需要COM访问权限
文件夹枚举可能会跳过受限制的日历

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

所有日期必须使用ISO 8601格式（
```
YYYY-MM-DDTHH:mm:ss
```
）
所有操作使用本地时区
返回值会转换为UTC时间（带Z后缀的ISO 8601格式）
不支持参会者或会议邀请功能

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

权限被拒绝：

Error: Calendar access permission is required

解决方案： 打开「系统设置 > 隐私与安全性 > 日历」，授权Terminal或LobsterAI访问权限

未找到脚本：

bash: calendar.sh: No such file or directory

解决方案： 确保使用SKILL.md文件所在目录 +

/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

未找到Outlook：

Error: Microsoft Outlook is not installed or not accessible

解决方案： 安装Microsoft Outlook并确保配置正确

PowerShell执行策略限制：

Error: Execution of scripts is disabled on this system

解决方案： 以管理员身份运行PowerShell并执行以下命令：

powershell

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Technical Details

技术细节

macOS Implementation

macOS实现

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)

JXA（JavaScript for Automation）：

使用
```
osascript -l JavaScript
```
执行JXA代码
通过Apple Events控制Calendar.app
支持Intel和Apple Silicon架构的Mac
需要用户授权访问日历

日期处理：

使用macOS原生的BSD date命令
格式：
```
date +%Y-%m-%dT%H:%M:%S
```
（本地时区）
相对日期：
```
date -v+7d
```
（7天后）

Windows Implementation

Windows实现

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

PowerShell + COM：

通过PowerShell使用Outlook COM API
需要安装并配置Outlook
支持所有与Outlook兼容的日历

日期处理：

使用PowerShell
```
[DateTime]::Parse()
```
解析日期
自动处理本地时区

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

两种实现方式均：

使用相同的JSON输出格式
支持相同的操作（列出、创建、更新、删除、搜索）
使用本地时区处理日期
返回UTC时间戳的ISO 8601格式