Support → docs agent: Intercom conversations → Mintlify PRs

The problem

Support answers the same questions week after week. The docs lag behind what users actually ask. Nobody owns closing the gap, so the gap never closes. The information is there — every Intercom conversation is a signal of what users find unclear — but nobody sits down on a Friday and turns 200 conversations into doc updates.

What you’ll build

A scheduled GitHub Action that reads the last seven days of Intercom conversations, clusters the recurring questions, maps each cluster to your existing Mintlify docs, and opens a pull request on the docs repo with:

• Proposed edits to existing docs (commits on a new branch)
• A docs-gaps.md report listing themes that have no existing doc
• A short summary at the top of the PR description

A human reviews the PR, edits or rejects proposed changes, and merges.

Example output

The Monday morning PR title + body that lands on your docs repo:

docs: weekly support-driven updates (2026-05-27 · 4 clusters)

This week the agent clustered 142 recent Intercom conversations into
4 themes. Each cluster maps to an existing doc edit or a new gap.

— Proposed edits ————————————————————————————————————————

docs/api/authentication.mdx
  Cluster: "API key rotation expiry confusion" (22 conversations)
  Added a callout in the Rotation section linking to the expiration
  matrix. Users repeatedly missed how the 30-day grace period interacts
  with rotation.

docs/integrations/slack.mdx
  Cluster: "Slack OAuth permission scope errors" (11 conversations)
  Clarified the required scopes and added a screenshot of the consent
  screen showing the right boxes ticked.

— New gaps (no doc yet) ————————————————————————————————

SSO debug log location (8 conversations)
  Where users find logs to diagnose failed SSO. Appended to
  docs-gaps.md.

CSV export size limits (5 conversations)
  We never documented the 50k-row cap on the CSV export endpoint.

You read this in 5 minutes. The model did the synthesis; you do the editorial pass.

Prerequisites

• Intercom with API access
• A Mintlify docs repo on GitHub
• An Anthropic API key
• A repo-scoped GitHub token with permission to open PRs on the docs repo
• A weekly cadence the team can actually keep up with

Build it

1. Add secrets. In the docs repo: INTERCOM_API_KEY, ANTHROPIC_API_KEY, and a DOCS_PR_TOKEN (a fine-grained PAT scoped to the docs repo with PR-write access — do not reuse the default GITHUB_TOKEN if you want cross-repo branch creation).

2. Schedule the workflow. Add .github/workflows/docs-from-support.yml:

   name: docs-from-support
   on:
     schedule:
       - cron: "0 14 * * MON"   # Mondays 14:00 UTC
     workflow_dispatch:
   jobs:
     propose:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - uses: actions/setup-node@v4
           with: { node-version: 20 }
         - name: Propose docs updates
           env:
             INTERCOM_API_KEY: ${{ secrets.INTERCOM_API_KEY }}
             ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
             GITHUB_TOKEN: ${{ secrets.DOCS_PR_TOKEN }}
           run: node .github/scripts/docs-from-support.mjs

3. Pull recent Intercom conversations. Call GET /conversations/search with a created-at filter for the last 7 days. Extract the user-question text from each conversation (filter to inbound messages from end-users; drop your team’s replies).

4. Read the docs tree. Parse mint.json to learn the nav structure and list the MDX files. Read each one’s frontmatter title and first paragraph; the agent needs to know what docs already exist so it doesn’t propose a parallel structure.

5. Cluster + map. One Claude call with a system prompt that:

   • Receives the conversations and the docs tree
   • Clusters the conversations by underlying question
   • For each cluster, matches it to an existing doc or flags it as a gap
   • Returns JSON: { edits: [{ file, diff, reason }], gaps: [{ theme, example_questions }] }

   Pin the JSON shape strictly. JSON-out is what makes the next step mechanical.

6. Apply edits and write the gap report. For each proposed edit, write the change to a new branch (docs/auto-YYYY-MM-DD). Append the gaps to docs-gaps.md at the repo root, with the date.

7. Open the PR. Use gh pr create with a title like docs: weekly support-driven updates (YYYY-MM-DD, N clusters) and a body summarizing the clusters and gap counts.

How it works

Four stages:

• Ingest — recent conversations. This is the signal: what users actually struggle with this week.
• Cluster — collapse hundreds of conversations into a handful of recurring themes. Without clustering you’d get one PR per conversation, which is unreadable.
• Map — the agent receives the current docs structure as part of its input, so it proposes edits to real files and flags real gaps rather than inventing a parallel structure. This is the difference between a useful PR and a useless one.
• Propose — the output is a PR, never a direct publish. The human-in-the-loop step is deliberate and non-negotiable: docs are user-facing, the model can be confidently wrong, and the value of the agent is that a human can review a single weekly PR much faster than they could read 200 conversations.

The model is doing the synthesis humans hate doing weekly. The human is doing the editorial work humans are still better at. That split is the entire point.

Variations & next

• High-signal source only. Run the agent against an Intercom tag like support-escalation instead of the full inbox. Higher signal, fewer false-positive clusters.
• Contradiction-flagging. Ask the agent to flag any cluster that contradicts recent product changes. Catches docs that say one thing while the product does another.
• Slack digest. In parallel with the PR, post the week’s gap report to a #docs channel. Faster awareness even when the PR sits.

Limits & honesty

It surfaces what to document well. The proposed wording still needs an editor — the model writes serviceably but not in your voice. It will sometimes cluster two distinct issues together; the human reviewer catches that. It does not, and must not, publish docs without review. If you ever feel tempted to let it auto-merge, you’ve forgotten what the agent is for.