Microsoft 365

SKILL.md

---
name: microsoft365
description: >
  Access Microsoft 365 services (Outlook email, Calendar, OneDrive, SharePoint, OneNote, Tasks, Contacts) using Microsoft Graph API.
  Use when the user wants to check emails, manage calendar, access files, take notes, manage tasks, or look up contacts.
  Keywords: microsoft, office, outlook, email, calendar, onedrive, sharepoint, onenote, notes, notebook, tasks, todo, contacts.
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: MS365_ACCESS_TOKEN
        type: oauth2
        integration_id: microsoft
        description: Microsoft 365 OAuth access via Microsoft Graph API
        scopes:
          - Mail.ReadWrite
          - Mail.Send
          - Calendars.ReadWrite
          - Files.ReadWrite.All
          - Notes.ReadWrite.All
          - Tasks.ReadWrite
          - Contacts.ReadWrite
          - Sites.Read.All
          - offline_access
    primaryEnv: MS365_ACCESS_TOKEN
---

# Microsoft 365 Connector

Access Microsoft 365 services through the Microsoft Graph API with Polly-managed OAuth authentication.

---

## Prerequisites

### Authentication

This skill uses **Polly-managed OAuth2 authentication**. The access token is automatically managed and refreshed by Polly's auth system via the `MS365_ACCESS_TOKEN` environment variable.

**No manual token refresh is needed** — Polly handles token refresh automatically when needed.

On first use, if not connected, call:
```
manage_auth(action="connect", integration_id="microsoft", auth_env="MS365_ACCESS_TOKEN")
```

---

## Script

All API calls go through `scripts/ms365_api.py`:

```bash
python3 /home/polly/skills/installed/microsoft365-connector/scripts/ms365_api.py <command> [args]
```

---

## Commands

### Email (Outlook)

**List recent emails:**
```bash
python3 scripts/ms365_api.py mail list --top 10
```

**Read email:**
```bash
python3 scripts/ms365_api.py mail read <message_id>
# Add --raw to get original HTML instead of Markdown
python3 scripts/ms365_api.py mail read <message_id> --raw
```

**Send email:**
```bash
python3 scripts/ms365_api.py mail send --to "user@example.com" --subject "Subject" --body "Message"
```

**Search emails:**
```bash
python3 scripts/ms365_api.py mail search --query "subject:urgent"
```

### Calendar

**List upcoming events:**
```bash
python3 scripts/ms365_api.py calendar list --top 5
```

**Get event details:**
```bash
python3 scripts/ms365_api.py calendar get <event_id>
```

**Create event:**
```bash
python3 scripts/ms365_api.py calendar create --subject "Meeting" --start "2026-04-10T10:00:00" --end "2026-04-10T11:00:00"
```

### Files (OneDrive)

**List files (by path):**
```bash
# List files by folder path
python3 scripts/ms365_api.py files list --path "/Documents/ULTA"

# List files in root
python3 scripts/ms365_api.py files list --top 10
```

**Get user info:**
```bash
python3 scripts/ms365_api.py user me
```

**Download file:**
```bash
python3 scripts/ms365_api.py files download <file_id> --output-path /tmp/document.docx
```

**Extract content from Office files (Word/Excel):**
```bash
python3 scripts/ms365_api.py files content <file_id>
```

### Tasks (Microsoft To Do)

**List task lists:**
```bash
python3 scripts/ms365_api.py tasks lists
```

**List tasks in a list:**
```bash
python3 scripts/ms365_api.py tasks get <list_id> --filter pending
```
`--filter` accepts `all` (default), `pending`, or `completed`.

**Create a task:**
```bash
python3 scripts/ms365_api.py tasks create <list_id> --title "Buy milk" --due "2026-04-20T09:00:00" --body "Optional notes"
```

**Complete a task:**
```bash
python3 scripts/ms365_api.py tasks complete <list_id> <task_id>
```

### Contacts

**List contacts:**
```bash
python3 scripts/ms365_api.py contacts list --top 20
```

**Search contacts:**
```bash
python3 scripts/ms365_api.py contacts search "Alice"
```

**Create a contact:**
```bash
python3 scripts/ms365_api.py contacts create --first-name "Alice" --last-name "Smith" --email "alice@example.com" --phone "+1-555-0100"
```

### SharePoint

**Search/list sites:**
```bash
python3 scripts/ms365_api.py sharepoint sites --search "marketing"
```

**List document libraries in a site:**
```bash
python3 scripts/ms365_api.py sharepoint lists <site_id>
```

**List items in a list:**
```bash
python3 scripts/ms365_api.py sharepoint items <site_id> <list_id>
```

### OneNote

**List notebooks:**
```bash
python3 scripts/ms365_api.py onenote notebooks --top 20
```

**Create a new notebook:**
```bash
python3 scripts/ms365_api.py onenote create-notebook --name "My Notebook"
```

**List sections in a notebook:**
```bash
python3 scripts/ms365_api.py onenote sections <notebook_id>
```

**Create a new section:**
```bash
python3 scripts/ms365_api.py onenote create-section <notebook_id> --name "Section Name"
```

**List pages in a section:**
```bash
python3 scripts/ms365_api.py onenote pages <section_id>
```

**Get page content (returns Markdown by default):**
```bash
python3 scripts/ms365_api.py onenote get-page <page_id>
# Add --raw to get original HTML instead
python3 scripts/ms365_api.py onenote get-page <page_id> --raw
```

**Create a new page:**
```bash
python3 scripts/ms365_api.py onenote create-page <section_id> --title "Page Title" --content "<p>Page body content</p>"
```

**Delete a page:**
```bash
python3 scripts/ms365_api.py onenote delete-page <page_id>
```

---

## Notes

- Access tokens are valid for ~1 hour and are **automatically refreshed by Polly's auth system**
- The LLM never directly accesses refresh tokens — they are managed securely by Polly
- The `MS365_ACCESS_TOKEN` environment variable is injected automatically when the skill runs
- Uses Microsoft Graph API v1.0 endpoints