Agent skill · software engineering · jeremylongshore
intercom-reference-architecture
Implement Intercom reference architecture with layered project structure.
Why this skill is useful
Provides a structured reference architecture for building Intercom integrations, including specific implementation patterns and type-safe SDK usage that the AI wouldn't generate on its own.
What it needs
Requires intercom-client, node installed locally. Requires intercom account access. About 3k tokens when loaded. Last updated 2026-08-07. 2,604 stars on the source repository.
What this skill does
Intercom Reference Architecture Overview A production-ready reference architecture for Intercom integrations built on four layers — API/webhook, service, Intercom client, and infrastructure — with type-safe SDK usage, webhook processing, contact sync, and Help Center management. Use it to scaffold a new integration or to review an existing one against a known-good structure. The layers (top to bottom): the API / Webhook layer (Express routes, webhook endpoints) calls into the service layer (contacts, conversations, articles — business logic and orchestration), which calls the Intercom client layer (a singleton intercom-client SDK wrapper with typed errors, caching, and rate limit handling), all resting on infrastructure (Redis cache, job queue, monitoring). Keeping dependencies flowing strictly downward is what prevents the circular imports and test-isolation problems listed under Error Handling. Prerequisites Node.js project with TypeScript and the intercom-client npm package installed. An Intercom access token — the SDK authenticates every request with a Bearer token read from the INTERCOMACCESSTOKEN environment variable (see Step 1). Create one under Intercom → Developer Hub → your app → Authentication. Never commit it; load it from the environment. For webhook verification, your app's client secret to validate the X-Hub-Signature header on inbound webhook POSTs. Redis (optional) if you enable the caching layer. Instructions Use Read/Grep to inspect the current project layout, then build each layer in order — the client layer is the dependency root for every service. 1. Client layer (src/intercom/client.ts) — a lazy singleton getClient() that reads INTERCOMACCESSTOKEN once, plus an IntercomServiceError that wraps raw SDK errors into a typed, retry-aware shape. Skeleton: 2. Contacts service (src/services/contacts.service.ts) — findOrCreate (search-before-create to avoid 409s), syncFromCRM, mergeLead, and a searchAll async generator for cursor pagination. 3. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills jeremylongshore/intercom-reference-architecture