intercom · normprovost · Mar 9, 2026 · Feb 25, 2026 · Feb 25, 2026 · Feb 25, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,54 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Is
+
+Intercom plugin for Claude Code — a skill-based integration (not compiled code). Skills are pure Markdown files that Claude reads at runtime to interact with Intercom workspaces via a remote MCP server.
+
+## Architecture
+
+```
+User → Claude Code CLI → Skill (SKILL.md) → MCP Server (https://mcp.intercom.com/mcp) → Intercom API
+```
+
+- **No build step, no dependencies, no tests.** The plugin is entirely declarative.
+- `.mcp.json` routes the `intercom` namespace to the remote HTTP-based MCP server.
+- `.claude-plugin/plugin.json` is the plugin manifest for Claude Code's plugin registry.
+- `.claude/settings.local.json` manages local permissions (currently allows WebFetch from raw.githubusercontent.com).
+
+## Skills
+
+Three skills live under `skills/`, each in its own directory:
+
+| Skill               | Trigger                                                    | Key Files                                    |
+| ------------------- | ---------------------------------------------------------- | -------------------------------------------- |
+| `install-messenger` | Explicit: `/intercom:install-messenger [framework]`        | `SKILL.md`, `references/framework-guides.md` |
+| `intercom-analysis` | Auto-triggered by keywords                                 | `SKILL.md`, `references/mcp-tools.md`        |
+| `customer-360`      | Explicit: `/intercom:customer-360 [email or company name]` | `SKILL.md`                                   |
+
+### Skill File Structure
+
+Each skill directory contains:
+
+- `SKILL.md` — Main skill file with YAML frontmatter (`name`, `description`, optional `disable-model-invocation`, `argument-hint`) followed by Markdown instructions Claude reads at runtime.
+- `references/` — Supplementary docs loaded on demand for progressive disclosure (keeps SKILL.md concise).
+
+### Invocation Modes
+
+- **Auto-triggered:** No `disable-model-invocation` in frontmatter. Claude activates the skill when the user's intent matches the `description` field.
+- **Explicit:** `disable-model-invocation: true` in frontmatter. Only invoked via `/intercom:<skill-name>`.
+
+## Key Conventions
+
+- **Security-first:** `install-messenger` defaults to JWT-based identity verification (HS256). Insecure mode requires explicit user opt-in. Never default to insecure installation.
+- **Progressive disclosure:** Keep SKILL.md focused on workflow logic. Move API references, framework-specific code, and tool documentation into `references/` subdirectories.
+- **Read-only access:** The MCP server only supports search and retrieval operations — no create, update, or delete.
+- **Regional awareness:** Intercom supports US, EU (Ireland), and Australia data residency. Currently US-only; EU/AU planned.
+
+## Development Workflow
+
+1. Edit SKILL.md files or reference documents
+2. Test by running skills in Claude Code CLI (e.g., `/intercom:install-messenger react`)
+3. For auto-triggered skills, test by typing natural language that matches the skill's `description` field
+4. Push to GitHub — the plugin registry picks up changes from the repository
diff --git a/README.md b/README.md
@@ -12,9 +12,9 @@ Connect your Intercom workspace to Claude Code. Search conversations, analyze cu
 
 | Skill | Invocation | Description |
 |-------|-----------|-------------|
-| **Intercom Insights** | Auto-triggered | Analyze conversations, find support patterns, investigate customer issues, and look up contacts. Triggers automatically when you ask about your Intercom data. |
-| **Install Messenger** | `/intercom:install-messenger [framework]` | Step-by-step guide to install the Intercom Messenger on your website. Supports React, Next.js, Vue.js, and plain JavaScript. |
-| **Intercom Search** | `/intercom:intercom-search [type] [query]` | Quick search for conversations or contacts by keyword, email, or topic. Returns formatted results with follow-up options. |
+| **Intercom Analysis** | Auto-triggered | Analyze conversations, find support patterns, investigate customer issues, and look up contacts. Triggers automatically when you ask about your Intercom data. |
+| **Install Messenger** | `/intercom:install-messenger [framework]` | Install the Intercom Messenger with secure JWT-based identity verification. Supports React, Next.js, Vue.js, and plain JavaScript. |
+| **Customer 360** | `/intercom:customer-360 [email or company]` | Build a comprehensive customer profile with conversation history, account context, and interaction timeline. |
 
 ## Usage Examples
 
@@ -28,14 +28,9 @@ Show me the most common topics in open conversations this week
 Look up all conversations from jane@example.com and summarize her issues
 ```
 
-**Search for specific conversations:**
+**Build a customer profile:**
 ```
-/intercom:intercom-search conversations billing error
-```
-
-**Find contacts at a company:**
-```
-/intercom:intercom-search contacts @acme.com
+/intercom:customer-360 jane@example.com
 ```
 
 **Install the Messenger:**
@@ -48,9 +43,9 @@ Look up all conversations from jane@example.com and summarize her issues
 Pull up conversation #12345 and show me the full thread
 ```
 
-## Limitations
+## Access & Limitations
 
-- **Read-only access** — The plugin can search and retrieve data but cannot create, update, or delete conversations, contacts, or other Intercom objects.
+- **Safe, read-only access** — The plugin can search and retrieve data but cannot create, update, or delete conversations, contacts, or other Intercom objects. Your workspace data is never modified.
 - **US region only** — Currently supports US-hosted Intercom workspaces. EU and Australia region support is planned.
 - **Rate limits** — Search operations are subject to Intercom API rate limits. The MCP server handles throttling automatically.
 

diff --git a/skills/customer-360/SKILL.md b/skills/customer-360/SKILL.md
@@ -0,0 +1,77 @@
+---
+name: customer-360
+license: MIT
+description: >
+  Build a comprehensive customer profile from Intercom data, including
+  conversation history, account context, and interaction timeline. Use when
+  the user asks to "look up a customer", "customer profile", "customer 360",
+  "tell me about this customer", "summarize a customer's history", or provides
+  a customer email or company name and wants a full picture.
+disable-model-invocation: true
+argument-hint: "[email or company name]"
+---
+
+# Customer 360
+
+Produce a comprehensive customer profile by aggregating data from across the Intercom workspace.
+
+## Workflow
+
+### Step 1: Identify the Customer
+- Parse the user's input for an email, name, or company
+- Use `search_contacts` to find the contact (by email is most reliable)
+- If company name given, search contacts by email domain
+- Use `get_contact` to fetch the full profile (attributes, tags, segments, companies)
+
+### Step 2: Gather Conversation History
+- Use `search_conversations` filtered to this contact's conversations
+- Paginate to get all conversations (not just the first page)
+- For the most recent/relevant conversations, use `get_conversation` for full threads
+
+### Step 3: Build the Profile
+Produce a markdown profile with these sections:
+
+#### Contact Summary
+- Name, email, role (user/lead), company
+- Location, timezone, last seen
+- Plan/tier (if available via custom attributes)
+- Tags and segments
+
+#### Conversation History
+- Total conversation count
+- Table: ID | Subject | State | Channel | Date
+- Highlight any currently open/snoozed conversations
+
+#### Key Themes
+- Common topics across conversations
+- Recurring issues or feature requests
+- Sentiment signals (escalations, positive feedback)
+
+#### Timeline
+- Chronological list of significant interactions
+- First contact → most recent activity
+
+#### Open Items
+- Unresolved conversations
+- Pending questions or follow-ups
+
+### Step 4: Present and Offer Next Steps
+- Present the profile
+- Offer to dive deeper into any conversation
+- Offer to search for similar customers (same company, same issues)
+
+## Best Practices
+- Always cite conversation IDs so the user can find them in the Intercom inbox
+- Note data freshness — states may have changed since events occurred
+- If the contact has many conversations, summarize the most recent 10-15 and note the total count
+- Handle cases where the contact exists but has no conversations
+
+## Troubleshooting
+
+### Contact Not Found
+Symptom: No results for the provided email or name.
+Solution: Check for typos. Try searching by email domain to find related contacts. Ask the user to confirm the identifier.
+
+### Too Many Conversations
+Symptom: Contact has 50+ conversations, making full analysis impractical.
+Solution: Focus on the most recent 10-15 conversations. Summarize older ones by theme rather than individually. Note the total count.