---
slug: "calendar-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/keith-hung/Calendar-Skill@main/README.md"
repo: "https://github.com/keith-hung/Calendar-Skill"
source_file: "README.md"
branch: "main"
---
# Outlook Calendar Skill for Claude Code

A Claude Code Skill that reads your Outlook calendar via ICS subscription URL.

## Features

- Read calendar events from Microsoft Outlook (M365)
- No admin approval required (uses ICS subscription)
- Query by date range (today, this week, specific dates)
- Timezone-aware (converts to local time)
- Automatic recurring event (RRULE) expansion
- Handles all Outlook DTSTART formats

## Prerequisites

### uv (Required)

This skill uses [uv](https://docs.astral.sh/uv/) to run the ICS parser script with automatic dependency management.

**Install uv:**

```bash
# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv
```

**Verify installation:**

```bash
uv --version
```

## Installation

### Option 1: Global (for personal use across all projects)

```bash
git clone https://github.com/keith-hung/Calendar-Skill.git
cd Calendar-Skill
./install.sh
```

### Option 2: Project-level (for team use)

```bash
git clone https://github.com/keith-hung/Calendar-Skill.git
cd Calendar-Skill
./install.sh /path/to/your-project
```

## Configuration

### Step 1: Get your ICS URL from Outlook

> ⚠️ **Important**: ICS publishing is **only available via Outlook Web (OWA)**.
> The macOS and Windows Outlook desktop apps do **not** have this feature.

#### Using Outlook Web (Required)

1. Open [Outlook Web](https://outlook.office365.com) in your browser
2. Click **Calendar** icon in the left sidebar
3. Click **Settings** (⚙️ gear icon, top right)
4. Click **View all Outlook settings** at the bottom
5. Navigate to: **Calendar** → **Shared calendars**
6. Scroll down to **Publish a calendar** section
7. Select your calendar from the dropdown
8. Choose permission level:
   - **Can view all details** - Recommended for personal use
   - **Can view titles and locations** - Hide sensitive details
9. Click **Publish**
10. Copy the **ICS** link (not the HTML link)

```
┌─────────────────────────────────────────────────┐
│ Publish a calendar                              │
├─────────────────────────────────────────────────┤
│ Select a calendar: [Calendar ▼]                 │
│ Select permissions: [Can view all details ▼]    │
│                                                 │
│ [Publish]                                       │
│                                                 │
│ HTML: https://outlook.office365.com/.../html    │
│ ICS:  https://outlook.office365.com/.../ics  ← Copy this │
└─────────────────────────────────────────────────┘
```

#### Why OWA Only?

| Client | Publish ICS | Subscribe ICS |
|--------|-------------|---------------|
| Outlook Web (OWA) | ✅ Yes | ✅ Yes |
| Outlook for Mac | ❌ No | ✅ Yes |
| Outlook for Windows | ❌ No | ✅ Yes |
| Outlook Mobile | ❌ No | ❌ No |

### Step 2: Configure the Skill

Edit the SKILL.md file and replace the placeholder with your ICS URL:

```
# Location depends on your installation:
# Project-level: .claude/skills/outlook-calendar/SKILL.md
# Global: ~/.claude/skills/outlook-calendar/SKILL.md
```

Find this line:

```markdown
**ICS URL**: `<YOUR_ICS_URL_HERE>`
```

Replace `<YOUR_ICS_URL_HERE>` with your actual ICS URL:

```markdown
**ICS URL**: `https://outlook.office365.com/owa/calendar/xxx/yyy/calendar.ics`
```

## Usage

Once installed and configured, simply ask Claude Code about your calendar:

```
What meetings do I have today?
Show my calendar for this week
Am I free tomorrow afternoon?
What's on my schedule for 12/5?
```

Claude will automatically invoke this skill and display your calendar events.

## Example Output

| Time | Event | Location |
|------|-------|----------|
| 09:00-10:00 | Weekly Standup | Meeting Room A |
| 14:00-15:00 | 1:1 with Manager | Microsoft Teams |
| 16:00-17:00 | Sprint Review | Conference Room B |

## Limitations

- **Read-only**: Cannot create, modify, or delete events
- **Polling-based**: Changes reflect when ICS is re-fetched (not real-time push)
- **Requires ICS publish**: Your organization must allow calendar publishing

## Troubleshooting

| Issue | Solution |
|-------|----------|
| `uv: command not found` | Install uv (see Prerequisites section) |
| Empty calendar | Check if ICS URL in SKILL.md is configured correctly |
| Cannot publish calendar | Contact IT admin - this feature may be disabled |
| Events not updating | ICS reflects server-side data; wait a few minutes |
| Placeholder still showing | Edit SKILL.md and replace `<YOUR_ICS_URL_HERE>` |

## License

MIT