msteams

Interact with Microsoft Teams — send and read messages, search conversations, look up people, check calendar, get meeting transcripts, and manage chats. Use this skill whenever the user mentions Teams

SKILL.md

GitHub

Microsoft Teams

Send and read messages, search conversations, look up people, check calendar, get meeting transcripts, and manage chats via Microsoft Teams.

Setup (run FIRST — every time, before any operation)

You MUST complete this setup before running any script. Do NOT skip this step.

sig status ms-teams 2>&1
sig status ms-graph 2>&1

Check the JSON output fields configured and valid for BOTH providers:

  • configured: false → run Provider Setup below. Do NOT proceed without completing it.
  • valid: false (but configured: true) → run sig login ms-teams, then re-check.
  • valid: true → detect proxy (see below), then execute the user's request.

Provider Setup

  1. Read <SKILL_DIR>/references/provider-config.yaml
  2. Append BOTH provider blocks (ms-teams and ms-graph) to ~/.sig/config.yaml under providers:
  3. Ask the user: "Do you need a proxy to access this site?" — if yes, add networkProxy: <url> under each provider in config.yaml
  4. Run sig login ms-teams (with --network-proxy <url> if proxy was specified) — this covers both providers
  5. Verify: run sig status ms-teams and sig status ms-graph again — both must show valid: true before proceeding

Proxy Detection (after provider is valid)

grep -A15 "^\s*ms-teams:" ~/.sig/config.yaml | grep networkProxy | awk '{print $2}'

If this outputs a URL, prefix ALL python3 commands with HTTPS_PROXY=<url> HTTP_PROXY=<url>. If using socks5, convert to socks5h for python (e.g. socks5://... → socks5h://...). If empty, no proxy needed.

Running Scripts

All scripts require setup to be completed first (see above).

User Profile & Region Configuration

Before using this skill, check memory/user-profile.md for the user's stored profile (name, email, region, etc.). See CLAUDE.md for details.

All scripts support a --region parameter for the Teams Chat API regional endpoint. Resolution order:

  1. Stored region from memory/user-profile.md
  2. --region CLI argument (if provided)
  3. TEAMS_REGION environment variable
  4. Default: apac

Common regions: apac, emea, amer.

Region: If the region is not in memory/user-profile.md or the env var, ask the user once, then store it immediately in memory/user-profile.md.

Profile enrichment: When you call teams_people.py --action profile (or Graph /me), persist the user's name, email, and I-number to memory/user-profile.md so other skills can use them without re-querying.

Scripts Reference

All scripts are in this skill's scripts/ directory. Run via Bash tool.

Script Purpose Token(s)
teams_conversations.py List/search conversations Chat
teams_messages.py Get messages from a conversation Chat
teams_send.py Send message or threaded reply Chat
teams_chat.py Find 1:1 chat or create group chat Chat + Graph
teams_members.py Get conversation members Chat + Graph
teams_meetings.py Get recordings and transcripts Chat
teams_calendar.py Get calendar events Graph
teams_people.py Search people, manager, reports, profile Graph

teams_conversations.py

--token TOKEN          Chat API token (required)
--search TEXT          Filter by topic, participant, or content
--limit N             Max conversations (default: 20)
--since ISO_DATE      Only conversations after this time
--until ISO_DATE      Only conversations before this time
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_messages.py

--token TOKEN          Chat API token (required)
--conversation-id ID   Conversation ID (required)
--search TEXT          Filter messages by content
--limit N             Max messages (default: 20, use 50+ for summarization)
--since ISO_DATE      Only messages after this time
--until ISO_DATE      Only messages before this time
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_send.py

--token TOKEN          Chat API token (required)
--conversation-id ID   Conversation ID (required)
--message TEXT         Message content (required)
--format FORMAT        "html" (default) or "markdown"
--parent-message-id ID Parent message ID (for threaded replies)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_chat.py

--token TOKEN          Chat API token (required)
--graph-token TOKEN    Graph API token (required)
--query TEXT           Person name/email (finds 1:1 chat)
--members GUIDS        Comma-separated user GUIDs (creates group chat)
--topic TEXT           Group chat topic (optional)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_members.py

--token TOKEN          Chat API token (required)
--graph-token TOKEN    Graph API token (for name resolution, optional)
--conversation-id ID   Conversation ID (required)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_meetings.py

--token TOKEN          Chat API token (required)
--conversation-id ID   List recordings in conversation
--transcript-url URL   Fetch transcript content (Teams AMS URL only)
--region REGION        Teams region (default: $TEAMS_REGION or 'apac')

teams_calendar.py

--graph-token TOKEN    Graph API token (required)
--range RANGE          "today", "week", or "month"
--start ISO_DATE       Custom start date (alternative to --range)
--end ISO_DATE         Custom end date (use with --start)
--limit N             Max events (default: 50)

teams_people.py

--graph-token TOKEN    Graph API token (required)
--action ACTION        "search" (default), "manager", "reports", or "profile"
--query TEXT           Search query (required for search action)
--limit N             Max results (default: 10)
--enrich              Fetch extra details (I-number, city, country)

Message Formatting

When sending messages, use --format html (default) for rich formatting:

<b>Bold</b>, <i>Italic</i>, <a href="url">Link</a>
<ul>
    <li>Item</li>
</ul>
,
<ol>
    <li>Item</li>
</ol>
<pre>Code block</pre>
, <code>Inline code</code>

Or --format markdown for Teams markdown:

**bold**, _italic_, ~~strikethrough~~
`code`, [link](url), - bullet, 1. numbered

See references/messaging-guide.md for complete formatting reference.

Key Concepts

Conversation IDs — Unique identifiers for chats/channels. Format varies by type:

  • 1:1 chat: 19:{guid1}_{guid2}@unq.gbl.spaces
  • Group/channel: 19:{hash}@thread.tacv2

User GUIDs — Microsoft 365 user identifiers (e.g., abc12345-def6-7890-...). Get from teams_people.py --action search.

Transcript URLs — Only Teams AMS URLs (asyncgw.teams.microsoft.com) work with the Chat API token. SharePoint URLs require different auth.

Time parameters — All use ISO 8601: 2025-01-15 or 2025-01-15T09:00:00Z.

Error Handling

Error Cause Fix
401 Unauthorized Token expired Auto-run sig login (no user prompt needed), retry
403 Forbidden No access to conversation User lacks permission
404 Not found Invalid conversation ID Check ID format, conversation may not exist
NOT_FOUND (people) No user matching query Try a more specific name or email
MISSING_ARGS Required arguments missing Check script --help for required args
Multiple candidates Ambiguous people search Ask user to specify more precisely

Workflow Examples

Send a message to someone

  1. Find their chat:
    sig run ms-teams ms-graph -- bash -c 'python scripts/teams_chat.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --query "John Smith" --region apac'
    
  2. Send: sig run ms-teams -- bash -c 'python scripts/teams_send.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --message "Hello!" --region apac'

Summarize a conversation

  1. Search: sig run ms-teams -- bash -c 'python scripts/teams_conversations.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --search "project standup"'
  2. Get messages: sig run ms-teams -- bash -c 'python scripts/teams_messages.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --limit 50'
  3. Summarize the returned messages

Get a meeting transcript

  1. Find recordings: sig run ms-teams -- bash -c 'python scripts/teams_meetings.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID"'
  2. Fetch transcript: sig run ms-teams -- bash -c 'python scripts/teams_meetings.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --transcript-url "$AMS_URL"'

Check today's calendar

  1. sig run ms-graph -- bash -c 'python scripts/teams_calendar.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --range today'

Look up a colleague

  1. sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action search --query "Jane Doe" --enrich'

Check org chart

  1. Manager: sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action manager'
  2. Reports: sig run ms-graph -- bash -c 'python scripts/teams_people.py --graph-token "$SIG_MS_GRAPH_ACCESS_TOKEN" --action reports'

Reply to a message in a thread

  1. Get messages to find the parent message ID: sig run ms-teams -- bash -c 'python scripts/teams_messages.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --limit 10'
  2. Reply: sig run ms-teams -- bash -c 'python scripts/teams_send.py --token "$SIG_MS_TEAMS_ACCESS_TOKEN" --conversation-id "$CONV_ID" --parent-message-id "$MSG_ID" --message "Thanks!"'