From merge-unified
Guide an AI coding agent through the full post-connection experience — settings page, sync status visibility, relinking, integration configuration, custom fields, and category-specific data scope filtering. Use after completing Merge Link setup to build the ongoing integration management experience or settings UI.
How this skill is triggered — by the user, by Claude, or both
Slash command
/merge-unified:implementing-post-connectionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
The post-connection experience covers everything customers interact with after an integration is first connected: visibility into sync health, self-service relinking, and configuration. Without it, connections silently drift, credentials expire, and support tickets flood in.
The post-connection experience covers everything customers interact with after an integration is first connected: visibility into sync health, self-service relinking, and configuration. Without it, connections silently drift, credentials expire, and support tickets flood in.
I'm the implementing-post-connection skill. I'll guide you through the integration management experience users see after connecting. Which part do you need first — a settings page, sync status display, or relinking support?
Merge Link implementation must be complete: a linked_accounts table exists with an account_token column storing the Merge account token per customer.
Work through these steps in order. Steps 2–6 invoke focused sub-skills; Step 1 runs inline.
Do not write any code in this step. Read the reference docs first, then scan the codebase, then confirm readiness.
1a. Read these reference docs:
../implementing-link/references/platform-overview.md — Merge concepts and account lifecycle../implementing-link/references/backend-implementation.md — Backend patterns and sync implementationreferences/post-connection-fundamentals.md — Initial sync best practices, error messaging, custom fields, and filtering options1b. Scan the codebase. Ask the user first:
"I'll search your codebase for existing settings pages, error handling, and the
linked_accountsschema. Ready to proceed?"
Then identify:
settings, account, admin, integrations, preferences. Record the exact file path or not found.linked_accounts schema: columns currently present, particularly status, error_category, initial_sync_complete.@mergeapi/merge-node-client (package.json), MergePythonClient (requirements.txt / pyproject.toml), dev.merge:merge-java-client (pom.xml / build.gradle), merge-go-client (go.mod), merge_ruby_client (Gemfile), Merge.Client (.csproj). Record yes/no and which language.@mergeapi/react-merge-link. Record yes/no (or N/A).1c. Confirm readiness with a brief summary:
{file} or not foundlinked_accounts schema (relevant columns present / missing)1d. Ask all unresolved questions in one message before proceeding to Step 2:
Before I start building, I have a few quick questions:
Which sub-skills do you want to run? Pick any combination — I'll invoke them in order:
- Settings page (Step 2 — recommended baseline)
- Sync status visibility (Step 3)
- Relinking + error messaging (Step 4)
- Custom field selection (Step 5 — needs Merge Enterprise plan)
- Data-scope filtering (Step 6 — required if customers control which records sync)
Settings page surface (only if Step 2 is selected): [If found:] I found
{file}as your existing settings/account page — I'll insert an "Integrations" section there. Is that correct? [If not found:] I didn't find an existing settings page. Do you have design mockups, or should I generate a new page matching the visual style of your existing pages?Backend SDK preference: [If not installed:] Would you prefer the official Merge SDK (recommended — handles types and retries) or raw HTTP? [If already installed:] I see the Merge SDK is in your dependencies — I'll use it unless you prefer raw HTTP.
Frontend SDK (React projects only): [If
@mergeapi/react-merge-linknot installed:] Would you prefer the React Merge Link SDK (@mergeapi/react-merge-link, recommended) or CDN+vanilla JS? [If already installed:] I see@mergeapi/react-merge-linkin your dependencies — I'll use it unless you prefer the CDN approach. [If not React:] Skipped.
Record the user's answers. Carry them as context into all sub-skills (Steps 2–6).
post-connection-build-settings-pageBuild the dedicated settings page that lets end users manage their connected integrations — reconnect, view health status, persist per-integration configuration, and adjust scope. (Absorbs the standalone configure flow: settings UI structure and the underlying persistence model are now treated as one artifact.)
Before invoking the sub-skill: Use the existing-settings-page finding from Step 1d.
post-connection-surface-sync-statusMake the initial sync timeline visible to end users so they aren't left wondering whether the connection worked.
post-connection-implement-relinkingWire up first-class relinking and detailed error surfacing for revoked credentials, missing scopes, and stale connections.
post-connection-enable-custom-fieldsLet customers select and enable custom fields from their connected system using Merge's Field Mapping API.
post-connection-data-scope-filteringPick a pre-storage or post-storage filtering strategy for the data your customers actually need (employees in HRIS, candidates in ATS, accounts in CRM, tickets in Ticketing, etc.). Required when customers need control over which records are synced.
SYMPTOM: Settings page shows "connection healthy" but sync has been failing for days
CAUSE: Status is read from local linked_accounts.status field which was never updated from Merge Issues API
FIX: Poll GET /issues?linked_account_id=<id> and surface any ONGOING issues as warnings alongside the local status
SYMPTOM: Relink button triggers a new connection instead of relinking the existing one
CAUSE: /api/merge/create-link-token is called without end_user_origin_id matching the existing account
FIX: Always pass the existing end_user_origin_id when generating a relink token; Merge will attach it to the same Linked Account
SYMPTOM: Field Mapping API returns no remote fields for a customer
CAUSE: Remote data was not enabled for this Linked Account's category
FIX: Enable remote data in Merge dashboard → Linked Account → Settings, or set via the configuration API before fetching fields
npx claudepluginhub merge-api/merge-unified-skills --plugin merge-unifiedCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.