playbooks

home / skills / probichaux / clawdskills / m365-calendar

m365-calendar skill

/m365-calendar

This skill helps you manage Microsoft 365 calendar events via Graph API, including invitations and Teams meetings.

npx playbooks add skill probichaux/clawdskills --skill m365-calendar

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
3.3 KB
---
name: m365-calendar
description: Read, create, and manage Microsoft 365 calendar events via Graph API. Supports meeting invitations with attendees and Teams meetings.
---

# Microsoft 365 Calendar

CLI tool for Microsoft 365 Calendar via Microsoft Graph API.

## Setup

Uses the same client/tenant from m365mail. Just authenticate with calendar scope:

```bash
# Authenticate (device code flow)
m365cal auth
```

If you haven't set up m365mail yet, do that first — the calendar tool shares its config.

### Required Permissions

In your Entra ID app, add these Graph permissions:
- `Calendars.ReadWrite` (delegated)

## Commands

### View Events

```bash
m365cal today                     # Today's events
m365cal tomorrow                  # Tomorrow's events
m365cal week                      # Next 7 days
m365cal range 2024-01-15          # Specific date
m365cal range 2024-01-15 2024-01-20  # Date range
m365cal show <event_id>           # Event details
```

### Create Events

```bash
# Simple event
m365cal create -s "Team standup" --start "2024-01-15 09:00" -d 30

# With location
m365cal create -s "Lunch" --start "2024-01-15 12:00" -d 60 -l "Cafe"

# With attendees (sends invitations automatically)
m365cal create -s "Project review" --start "2024-01-15 14:00" -d 60 \
  -a [email protected] [email protected] \
  -o [email protected]

# Teams meeting with attendees
m365cal create -s "Sprint planning" --start "2024-01-15 10:00" -d 90 \
  -a [email protected] --teams

# All-day event
m365cal create -s "Conference" --start "2024-01-20" --all-day
```

### Update Events

```bash
m365cal update <event_id> --subject "New title"
m365cal update <event_id> --start "2024-01-15 15:00"
m365cal update <event_id> -l "Room 201"
```

Updates with attendees automatically send update notifications.

### Delete/Cancel Events

```bash
m365cal delete <event_id>                    # Silent delete
m365cal delete <event_id> -m "Rescheduling"  # Cancel with message to attendees
```

### Respond to Invitations

```bash
m365cal respond <event_id> accept
m365cal respond <event_id> tentative -m "Might be late"
m365cal respond <event_id> decline --silent  # Don't notify organizer
```

### List Calendars

```bash
m365cal calendars
m365cal calendars --json
```

## Options

- `-v, --verbose`: Show more details
- `--json`: Output as JSON (for scripting)
- `-d, --duration`: Duration in minutes (default: 60)
- `-a, --attendees`: Required attendees (emails)
- `-o, --optional`: Optional attendees
- `-t, --teams`: Create Teams meeting
- `-l, --location`: Location
- `-b, --body`: Description/notes

## Meeting Invitations

When you create or update an event with attendees, Microsoft Graph automatically:
1. Sends meeting invitations via email
2. Adds the event to attendees' calendars (pending acceptance)
3. Sends update/cancellation notices when changed

No need to use m365mail separately — invitations are built into the calendar API.

## Event IDs

Events are identified by long IDs. Commands accept:
- Full ID
- ID prefix (first 8+ chars usually unique)

## Token Storage

- Config (shared): `~/.m365mail/config.json`
- Calendar tokens: `~/.m365calendar/token_cache.json`

## Troubleshooting

**"No cached token"**: Run `m365cal auth`

**"Run m365mail setup first"**: Calendar shares credentials with mail. Set up mail first.

**Permission denied**: Ensure `Calendars.ReadWrite` permission is granted in Entra ID.

Overview

This skill integrates with Microsoft 365 Calendar via the Microsoft Graph API to read, create, update, and delete calendar events. It supports meeting invitations, attendee management, Teams meeting creation, and script-friendly JSON output. It reuses the same authentication/config as the mail client for seamless setup.

How this skill works

The skill authenticates with Microsoft Graph using delegated calendar permissions and stores tokens locally. It lists events for common ranges, creates events with optional attendees and Teams conferencing, updates or cancels events (sending notifications automatically when attendees are present), and can output results as JSON for automation. Event IDs or prefixes are accepted for operations.

When to use it

  • Schedule meetings or create all-day events from the command line or scripts.
  • Send invitations and manage attendee responses without switching to the Outlook UI.
  • Query today/tomorrow/the week or a custom date range programmatically.
  • Create Teams meetings including conference details automatically.
  • Integrate calendar actions into CI/CD or automation pipelines using JSON output.

Best practices

  • Ensure your Entra ID app has the Calendars.ReadWrite delegated permission before authenticating.
  • Run the mail setup first if not already configured — calendar reuses that config and token cache paths.
  • Use --json output for reliable parsing in scripts and automation.
  • Provide full or 8+ character event ID prefixes to avoid ambiguity when updating or deleting events.
  • When modifying events with attendees, include a clear message for cancellations or updates so recipients get contextual notifications.

Example use cases

  • Quickly list today’s meetings: fetch concise calendar summaries for standups or daily planning.
  • Create a cross-company review meeting with required and optional attendees and have invitations sent automatically.
  • Provision a Teams meeting from a deployment script when a release needs a live discussion.
  • Update a meeting location or time programmatically and automatically notify all attendees.
  • Cancel an event with a cancellation message so attendees receive a clear reason.

FAQ

What permissions are required?

You need Calendars.ReadWrite (delegated) configured in your Entra ID app.

How do invitations get sent to attendees?

Microsoft Graph handles sending invitations, adding events to attendees’ calendars, and notifying them of updates or cancellations automatically.

Where are tokens and config stored?

Config is shared with the mail client under ~/.m365mail/config.json; calendar tokens are stored at ~/.m365calendar/token_cache.json.