OpenParable
Skip to content
← Back to skills

Msteams

Productivity
msteams

Msteams is an Agent Skill for productivity published in the sigcli/sigcli repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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, MS Teams, Microsoft Teams, wants to send a message, read chat history, search conversations, look up a colleague, check their calendar, find meeting recordings or transcripts, see direct reports or manager, or do anything involving Teams communication. Also trigger when the user asks about scheduling, org chart, people search, or wants to message someone.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/sigcli/sigcli/blob/HEAD/skills/msteams/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/msteams, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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.

ScriptPurposeToken(s)
teams_conversations.pyList/search conversationsChat
teams_messages.pyGet messages from a conversationChat
teams_send.pySend message or threaded replyChat
teams_chat.pyFind 1:1 chat or create group chatChat + Graph
teams_members.pyGet conversation membersChat + Graph
teams_meetings.pyGet recordings and transcriptsChat
teams_calendar.pyGet calendar eventsGraph
teams_people.pySearch people, manager, reports, profileGraph

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

ErrorCauseFix
401 UnauthorizedToken expiredAuto-run sig login (no user prompt needed), retry
403 ForbiddenNo access to conversationUser lacks permission
404 Not foundInvalid conversation IDCheck ID format, conversation may not exist
NOT_FOUND (people)No user matching queryTry a more specific name or email
MISSING_ARGSRequired arguments missingCheck script --help for required args
Multiple candidatesAmbiguous people searchAsk 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!"'