local-tools

ローカルツールスキル

このスキルを使用するタイミング

次のことが必要な場合は、local-tools スキルを使用します。

• カレンダー管理 - カレンダーの予定の表示、作成、更新、削除

使用する場面の例：

• ユーザー：「明日の予定を見せて」
• ユーザー：「午後3時に会議を作成して」
• ユーザー：「『project』を含むカレンダーの予定を検索して」
• ユーザー：「明日の会議を削除して」

仕組み

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

アーキテクチャ：

1. CLI スクリプト - HTTP サーバーが不要な、プラットフォーム固有のスクリプト

   • calendar.sh - macOS 用 Bash スクリプト
   • calendar.ps1 - Windows 用 PowerShell スクリプト

2. ローカルカレンダーへのアクセス - システムカレンダーへの直接アクセス

   • macOS：JXA（JavaScript for Automation）を使用して Calendar.app を操作します
   • Windows：PowerShell COM API を使用して Microsoft Outlook を操作します

3. JSON 出力 - 簡単に解析できる構造化データ形式

プラットフォームのサポート

プラットフォーム	実装	カレンダーアプリ	ステータス
macOS 10.10+	JXA + Calendar.app	Calendar.app	✅ 完全にサポート
Windows 7+	PowerShell + COM	Microsoft Outlook	✅ 完全にサポート
Linux	-	-	❌ サポート対象外

権限

macOS

• 「カレンダー」へのアクセス権限が必要です
• 初回使用時にユーザーに確認が表示されます
• 次の場所で管理できます：システム設定 > プライバシーとセキュリティ > カレンダー

Windows

• Microsoft Outlook がインストールされている必要があります
• COM アクセスに管理者権限が必要な場合があります

カレンダー操作

重要：スクリプトの場所を特定する方法

Read ツールでこの SKILL.md ファイルを読み込むと、その絶対パスが取得できます（例：/Users/username/.../SKILLs/local-tools/SKILL.md）。

スクリプトのパスを組み立てるには：

1. この SKILL.md ファイルがあるディレクトリを取得します
2. /scripts/calendar.sh（macOS）または /scripts/calendar.ps1（Windows）を追加します

例：

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

以下のすべての例で、<skill-dir>/scripts/calendar.sh はプレースホルダーです。実際の絶対パスに置き換えてください。

AI アシスタントのベストプラクティス

行うこと：

• ✅ 試行錯誤の過程を見せず、コマンドを直接実行する
• ✅ コマンドが失敗した場合は、技術的なエラーを見せずに権限の問題についてユーザーに知らせる
• ✅ 誕生日や記念日を検索するには search コマンドを使用する
• ✅ カレンダー名が指定されていない場合、スクリプトは最初に見つかったカレンダーを自動的に使用する

行わないこと：

• ❌ 異なるコマンドの組み合わせを繰り返し試さない
• ❌ エラーのスタックトレースや技術的な詳細をユーザーに見せない
• ❌ 問題を分析するためにスクリプトのソースコードを読まない
• ❌ ユーザーにカレンダー名を尋ねない。デフォルトの動作を使用する

例 - 誕生日の検索：

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

予定の削除

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

予定の検索

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

注： --calendar が指定されていない場合、検索操作では macOS と Windows の両方ですべての利用可能なカレンダーが検索されます。

出力形式

すべてのコマンドは、次の構造の 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
  }
}

エラーレスポンス

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

エラーコード

コード	意味	復旧可能
CALENDAR_ACCESS_ERROR	アクセスが拒否されたか、カレンダーにアクセスできません	はい
INVALID_INPUT	必須パラメーターが不足しています	いいえ
EVENT_NOT_FOUND	イベント ID が見つかりません	いいえ
OUTLOOK_NOT_AVAILABLE	Microsoft Outlook がインストールされていません（Windows）	はい

日付形式のガイドライン

重要：日付形式のガイドライン

list コマンドで時間範囲を指定する場合：

1. 必ず ISO 8601 形式を使用してください：YYYY-MM-DDTHH:mm:ss
2. ローカルタイムゾーンを使用してください：UTC やタイムゾーンの接尾辞（+08:00 や Z など）は使用しないでください
3. 日付は自分で計算してください：$(date ...) のようなシェルコマンド置換は使用しないでください
4. Claude が日付を計算してください：現在の日付を基準に、対象の日付を直接計算してください
5. 例：
   • 今日の午前 0 時：2026-02-13T00:00:00
   • 今日の終日：2026-02-13T23:59:59
   • 明日の朝：2026-02-14T09:00:00
   • 来週月曜日：2026-02-16T00:00:00

理由：このスクリプトでは、システムのタイムゾーンに一致するローカル時刻の文字列が必要です。シェルによる置換は、すべての環境で正しく実行されるとは限りません。

よくあるパターン

パターン 1：スケジュール管理

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

パターン 2：会議のスケジュール設定

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

パターン 3：イベント検索

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

パターン 4：空き状況の確認

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

既知の動作

時間範囲の照合

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）

終日イベント

• 対象日について、00:00:00 から 23:59:59 までのイベントとして扱われます
• 複数日にわたる終日イベント（例：2 月 12～14 日）は、その期間内の任意の日付を指定すると表示されます

時刻の精度

• 比較には秒単位の精度を使用します
• 日付の比較ではミリ秒は無視されます

繰り返しイベント

• 各発生回は別個のイベントインスタンスとして扱われます
• スクリプトは、クエリの時間範囲内にある個々の発生回を返します

ベストプラクティス

1. 作成前に必ず確認する

イベントを作成する前に、既存のイベントを一覧表示して競合を避けてください：

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

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

2. 特定のカレンダーを使用する（macOS）

イベントを整理するため、カレンダーを指定してください：

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

3. 更新／削除の前に検索する

正しいイベント 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. エラーを適切に処理する

応答を解析して、エラーを処理してください：

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

制限事項

macOS

• macOS 10.10 Yosemite 以降が必要です（JXA のサポートに必要）
• カレンダーへのアクセス許可が必要です
• 高度な繰り返しイベントのクエリには対応していません
• 繰り返しイベントのルールは変更できません

Windows

• Microsoft Outlook のインストールが必要です
• 他のカレンダーアプリケーション（Windows Calendar、Google Calendar など）には対応していません
• 企業環境では COM アクセス許可が必要になる場合があります
• フォルダーの列挙時に、アクセス制限のあるカレンダーがスキップされる場合があります

全般

• すべての日付は ISO 8601 形式（YYYY-MM-DDTHH:mm:ss）で指定する必要があります
• すべての操作でローカルタイムゾーンが使用されます
• 戻り値は UTC に変換されます（末尾に Z が付く ISO 8601 形式）
• 参加者や会議への招待には対応していません

トラブルシューティング

macOS

アクセスが拒否されました：

Error: Calendar access permission is required

解決策：「システム設定」>「プライバシーとセキュリティ」>「カレンダー」を開き、Terminal または LobsterAI にアクセスを許可してください

スクリプトが見つかりません：

bash: calendar.sh: No such file or directory

**解決策：**SKILL.md のディレクトリを起点とする絶対パスに /scripts/calendar.sh を加えたパスを使用していることを確認してください

Windows

Outlook が見つかりません：

Error: Microsoft Outlook is not installed or not accessible

**解決策：**Microsoft Outlook をインストールし、正しく設定されていることを確認してください

PowerShell の実行ポリシー：

Error: Execution of scripts is disabled on this system

**解決策：**PowerShell を管理者として実行し、次のコマンドを実行してください：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

技術詳細

macOS の実装

JXA（JavaScript for Automation）：

• osascript -l JavaScript を使用して JXA コードを実行します
• Apple Events 経由で Calendar.app を操作します
• Intel 搭載 Mac と Apple Silicon 搭載 Mac の両方で動作します
• Calendar へのアクセスにはユーザーの許可が必要です

日付の処理：

• BSD の date コマンド（macOS 標準）を使用します
• 形式：date +%Y-%m-%dT%H:%M:%S（ローカルタイムゾーン）
• 相対日付：date -v+7d（今から7日後）

Windows の実装

PowerShell + COM：

• PowerShell 経由で Outlook COM API を使用します
• Outlook がインストールされ、設定されている必要があります
• Outlook 対応のすべてのカレンダーで動作します

日付の処理：

• 日付の解析には PowerShell の [DateTime]::Parse() を使用します
• ローカルタイムゾーンを自動的に処理します

クロスプラットフォームでの一貫性

両方の実装で、以下に対応しています。

• 同一の JSON 出力形式を使用します
• 同じ操作（一覧表示、作成、更新、削除、検索）に対応します
• ローカルタイムゾーンで日付を処理します
• UTC タイムスタンプを ISO 8601 形式で返します

関連スキル

• imap-smtp-email - メールベースの会議招待に使用します