Agent skill

microsoft-graph-api

This skill should be used when the user asks to "read my emails", "send an email", "compose email", "check my calendar", "get calendar events", "create a meeting", "schedule an event", "add calendar event", "search emails", "list mail folders", "show unread messages", "what meetings do I have", "fetch emails from Microsoft", "access Outlook", or mentions Microsoft Graph, Office 365 email, or Outlook calendar integration.

View SKILL.md on GitHub Repository
Stars 232
Forks 15

Install this agent skill to your Project

npx add-skill https://github.com/aiskillstore/marketplace/tree/main/skills/bltgv/microsoft-graph-api

SKILL.md

Microsoft Graph API Integration

Access Microsoft 365 emails and calendar through TypeScript scripts executed via Bun.

Overview

This skill provides access to Microsoft Graph API for:

  • Email: List, read, search, and send emails
  • Calendar: View, search, and create calendar events

All scripts return JSON and handle authentication automatically.

Response Format

All scripts output JSON with a consistent structure:

Success

json
{"status": "success", "data": [...]}

Authentication Required

json
{
  "status": "auth_required",
  "userCode": "ABC123",
  "verificationUri": "https://microsoft.com/devicelogin",
  "expiresAt": "2024-01-15T10:30:00.000Z",
  "message": "To sign in, use a web browser..."
}

When you receive auth_required, display to the user:

To access your email, please authenticate:
1. Go to: https://microsoft.com/devicelogin
2. Enter code: ABC123

Let me know when you've completed authentication.

Then retry the same command - the script will automatically complete authentication.

Authentication Pending

json
{
  "status": "auth_pending",
  "userCode": "ABC123",
  "verificationUri": "https://microsoft.com/devicelogin",
  "expiresAt": "...",
  "message": "..."
}

User has been shown the code but hasn't completed login yet. Remind them to complete authentication.

Error

json
{"status": "error", "error": "Error description"}

Email Access

All scripts are located at ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/.

List Emails

bash
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/emails.ts list
bun run emails.ts list --folder "Sent Items" --top 5
bun run emails.ts list --profile work

Read Specific Email

bash
bun run emails.ts read --id AAMkAG...

Get the ID from the list command output.

Search Emails

bash
bun run emails.ts search --query "from:boss@company.com"
bun run emails.ts search --query "subject:quarterly report"
bun run emails.ts search --query "hasAttachments:true"

List Mail Folders

bash
bun run emails.ts folders

Send Email

bash
# Simple email
bun run emails.ts send --to "user@example.com" --subject "Hello" --body "Hi there!"

# Multiple recipients with CC
bun run emails.ts send --to "a@example.com,b@example.com" --cc "c@example.com" --subject "Team Update" --body "Here's the update..."

# HTML email
bun run emails.ts send --to "user@example.com" --subject "Report" --body "<h1>Monthly Report</h1><p>Details...</p>" --html

# With BCC
bun run emails.ts send --to "team@example.com" --bcc "manager@example.com" --subject "Announcement" --body "..."

Calendar Access

List Upcoming Events

bash
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/calendar.ts list
bun run calendar.ts today
bun run calendar.ts week
bun run calendar.ts list --start tomorrow --end +7d

View Specific Event

bash
bun run calendar.ts view --id AAMkAG...

Search Events

bash
bun run calendar.ts search --query "team standup"

Date Formats

  • Relative: today, tomorrow, +7d, +1m, +1y
  • Absolute: ISO format 2024-01-15 or 2024-01-15T14:00:00

Create Calendar Event

bash
# Basic event (1 hour default duration)
bun run calendar.ts create --subject "Team Meeting" --start "2024-01-15T14:00:00"

# Event with end time
bun run calendar.ts create --subject "Workshop" --start "2024-01-15T09:00:00" --end "2024-01-15T12:00:00"

# Event with location and description
bun run calendar.ts create --subject "Lunch" --start "2024-01-15T12:00:00" --location "Cafe" --body "Team lunch"

# Event with attendees
bun run calendar.ts create --subject "1:1" --start tomorrow --end +1d --attendees "colleague@example.com"

# Multiple attendees
bun run calendar.ts create --subject "Review" --start "2024-01-15T10:00:00" --attendees "a@ex.com,b@ex.com,c@ex.com"

# All-day event
bun run calendar.ts create --subject "Holiday" --start "2024-12-25" --all-day

# Using relative dates
bun run calendar.ts create --subject "Follow-up" --start tomorrow --end +1d

Multi-Profile Support

Store multiple accounts using profiles:

bash
# Use work profile
bun run emails.ts list --profile work
bun run calendar.ts today --profile work

# Use personal profile
bun run emails.ts list --profile personal

Manual Authentication

For explicit auth management (listing/deleting profiles):

bash
# List all profiles
bun run ${CLAUDE_PLUGIN_ROOT}/skills/microsoft-graph/scripts/auth.ts --list

# Delete a profile
bun run auth.ts --delete --profile old-account

# Authenticate with custom Azure AD app
bun run auth.ts --client-id your-app-id --tenant-id your-tenant-id

Token Lifecycle

Token Type Lifetime Handling
Access Token ~1 hour Automatically refreshed
Refresh Token ~90 days When expired, scripts return auth_required

Users only need to re-authenticate when the refresh token expires (~90 days).

Credential Storage

Credentials are stored at ~/.config/api-skills/credentials.json.

Script Reference

Script Purpose
emails.ts Email list, read, search, send, and folder operations
calendar.ts Calendar view, search, and create operations
auth.ts Manual credential management (list, delete profiles)

Additional Resources

For detailed API reference, see:

  • references/graph-api.md - Microsoft Graph API endpoints and parameters

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

aiskillstore/marketplace

perigon-backend

Perigon ASP.NET Core + EF Core + Aspire conventions

232 15
Explore
aiskillstore/marketplace

perigon-agent

Pointers for Copilot/agents to apply Perigon conventions

232 15
Explore
aiskillstore/marketplace

perigon-angular

Angular 21+ standalone/Material/signal conventions for Perigon WebApp

232 15
Explore
aiskillstore/marketplace

fastapi-mastery

Comprehensive FastAPI development skill covering REST API creation, routing, request/response handling, validation, authentication, database integration, middleware, and deployment. Use when working with FastAPI projects, building APIs, implementing CRUD operations, setting up authentication/authorization, integrating databases (SQL/NoSQL), adding middleware, handling WebSockets, or deploying FastAPI applications. Triggered by requests involving .py files with FastAPI code, API endpoint creation, Pydantic models, or FastAPI-specific features.

232 15
Explore
aiskillstore/marketplace

context7-efficient

Token-efficient library documentation fetcher using Context7 MCP with 86.8% token savings through intelligent shell pipeline filtering. Fetches code examples, API references, and best practices for JavaScript, Python, Go, Rust, and other libraries. Use when users ask about library documentation, need code examples, want API usage patterns, are learning a new framework, need syntax reference, or troubleshooting with library-specific information. Triggers include questions like "Show me React hooks", "How do I use Prisma", "What's the Next.js routing syntax", or any request for library/framework documentation.

232 15
Explore
aiskillstore/marketplace

browser-use

Browser automation using Playwright MCP. Navigate websites, fill forms, click elements, take screenshots, and extract data. Use when tasks require web browsing, form submission, web scraping, UI testing, or any browser interaction.

232 15
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results