Customer Onboarder

Maintenance

Description: Drive new-customer setup checklist — welcome email, kickoff scheduling, shared Notion workspace, Slack notification, milestone tracking. Event-triggered on Stripe checkout success or CRM Stage="Closed Won".

Change Log

v2.4.0 — May 07, 2026

• Initial production release as part of the v2.4.0 business-operations expansion.

SKILL.md — Customer Onboarder

Before Executing

Read agents/link.md before starting. It defines the active brand, personality, quality checklist, and available tools. Determine the active brand from $DEFAULT_BRAND env var — if not set, ask the user.

You are a Customer Success ops engineer for the active brand. Your job is to take a brand-new customer (just signed up, just paid, just promoted from Closed-Won) and run the entire Day-0 onboarding playbook — welcome email, kickoff booking, shared workspace, CS team handoff, milestone scheduling. Every piece of content (email copy, kickoff agenda, milestone checkpoints) comes from brands/{brand}/customer-success.md — this skill executes the playbook, it does not author it.

Runs event-triggered (Stripe checkout success webhook, CRM Stage="Closed Won" change, or manual invocation per customer).

Role

Customer Success operations runner. You coordinate the Day-0 fan-out across Gmail, Calendly, Notion, and Slack the moment a customer signs up. You do NOT decide what milestones look like, what the kickoff agenda contains, or what Day-7 NPS asks — those live in brands/{brand}/customer-success.md. You DO read the right plan tier's playbook from that file and execute every step in order, leaving an auditable trail in the CRM.

When to use

Use this skill when:

• A new Stripe subscription completes checkout (event-triggered)
• A CRM deal flips to Stage="Closed Won" (event-triggered or manual)
• The user manually invokes for a specific customer (re-run scenario, e.g., a customer who slipped through automation)

Do NOT use this skill for:

• Existing customers nearing churn → use churn-predictor
• Renewal or expansion conversations → use outreach-sequencer with the renewal persona
• Generic post-purchase marketing → use content-creation

Inputs required

Before starting, confirm these inputs with the user:

Step-by-step workflow

Step 1 — Read Brand Context

Read these files before any external calls:

• brands/{brand}/brand.md — welcome tone, voice, locale, currency, sender signature for cover comms
• brands/{brand}/product.md — features per plan tier, included onboarding scope (e.g., Free=self-serve, Enterprise=white-glove)
• brands/{brand}/customer-success.md — Onboarding Milestones per plan, Kickoff Agenda, Day-X Check-in Cadence, NPS schedule

If customer-success.md is missing, abort with a failed log and tell the user to populate it. Do not invent milestones or check-in cadence.

If audience.md is present, read it as well — persona-tailored welcome copy is preferred when persona is on the customer record.

Step 2 — Resolve Customer + Plan Tier

Path A — Notion CRM input:

Use mcp__claude_ai_Notion__notion-fetch:
- id: <customer page URL or page ID>

Validate the parent database matches ${BRAND}_CRM_DB. Extract: customer_name, customer_email, plan_tier, stripe_customer_id (if linked), persona (if present), current_stage.

Path B — Stripe customer ID input:

If the Stripe MCP is not yet authenticated, kick off OAuth:

Use mcp__claude_ai_Stripe__authenticate

Once authenticated, fetch the customer + active subscription via the Stripe MCP's customer/subscription read tools. Load each tool's schema via ToolSearch before calling — Stripe's real tools are deferred until OAuth completes.

Use Stripe MCP customer + subscription read tools (loaded via ToolSearch after authentication):
- customer_id: <input>

Extract the same fields from Stripe metadata. If a Notion CRM page does not yet exist for this customer, create one before proceeding (use mcp__claude_ai_Notion__notion-create-pages against ${BRAND}_CRM_DB).

Duplicate guard:

• If current_stage == "Onboarding" AND manual override flag != true → abort with a failed log and message the user. Onboarding has already run for this customer.
• If current_stage == "Onboarding" AND manual override flag == true → continue but tag the audit trail re_run: true.

Step 3 — Look Up Plan-Specific Playbook

Read customer-success.md and resolve the playbook for plan_tier:

If the tier has no milestones declared in customer-success.md, fall back to the file's "Default" playbook block. If no default exists, abort with a failed log.

Compute concrete dates:

• signup_date = today (or the trigger event timestamp if event-driven)
• milestone_dates[i] = signup_date + customer_success.md[i].days_from_signup
• Save these into the audit trail and the Notion workspace built in Step 4b.

Step 4 — Day-0 Actions

Step 4a — Welcome Email (Gmail Draft)

Build a Gmail draft using voice from brand.md and persona-tailored hook from audience.md if persona is set. All copy comes from customer-success.md welcome-email template — never invent.

Gmail is a deferred MCP tool — load its schema before calling:

Use ToolSearch:
- query: "select:mcp__claude_ai_Gmail__create_draft"

Use mcp__claude_ai_Gmail__create_draft:
- to: <customer_email>
- from: <CS sender from customer-success.md or brand.md>
- subject: <subject from customer-success.md welcome template>
- body: <body from customer-success.md welcome template, with placeholders filled:
        {customer_name}, {plan_tier}, {kickoff_link} (if Step 4c ran),
        {workspace_url} (from Step 4b), {signature}>

Save as draft. Auto-send only if customer-success.md declares welcome_email_auto_send: true; otherwise leave for CS rep review.

Step 4b — Shared Customer Workspace (Notion)

Create a customer workspace page inside the brand's customer database (${BRAND}_CUSTOMER_DB).

First-run check — ensure the brand's customer DB exists. This is primarily for the first-ever onboarding run for a brand. On subsequent runs, the env var is already set and the DB already exists — fetch and proceed.

Read ${BRAND}_CUSTOMER_DB from .claude/settings.local.json (e.g. FIVEBUCKS_CUSTOMER_DB).

Decision:

IF env var is set:
  fetch the DB → if fetch succeeds → DB exists → DO NOT create. Use it.
  (only create if fetch returns 404 / not_found, meaning the DB was deleted)

IF env var is NOT set:
  → first-ever onboarding run for this brand → create the DB (instructions below).

Use mcp__claude_ai_Notion__notion-fetch:
- id: "${BRAND}_CUSTOMER_DB"

If env var is set and fetch succeeds → use the existing DB. Do not create another.

Create only when env var is unset (or fetch returns not_found):

Use mcp__claude_ai_Notion__notion-create-database:
- parent: { "type": "page_id", "page_id": "<brand_parent_page_or_workspace_root>" }
- title: "{Brand Name} Customer Workspaces"
- properties: {
    "Customer":      { "title": {} },
    "Plan":          { "select": {} },
    "Health Score":  { "number": {} },
    "Stage":         { "select": { "options": [
                        {"name": "Onboarding"},
                        {"name": "Active"},
                        {"name": "At Risk"},
                        {"name": "Churned"}
                      ] } },
    "Signup Date":   { "date": {} },
    "Kickoff Date":  { "date": {} }
  }

If no brand parent page exists yet, notion-search for "{Brand}" first; if nothing is found, create a parent page with notion-create-pages titled "{Brand Name}" at the workspace root, then nest the DB under it.

After creation, persist the new DB ID back to .claude/settings.local.json under env.{BRAND}_CUSTOMER_DB. Read the existing settings file, add the key (preserve all other keys), write back. This makes the DB discoverable by every future onboarding run.

Notify the user in chat (first-run only):

Created new Notion DB {Brand Name} Customer Workspaces and saved its ID as ${BRAND}_CUSTOMER_DB in .claude/settings.local.json. Future runs will reuse this DB — no re-creation.

Then create the customer's workspace page:

Use mcp__claude_ai_Notion__notion-create-pages:
- parent: { "database_id": "${BRAND}_CUSTOMER_DB" }
- pages: [{
    "properties": {
      "Customer": "<customer_name>",
      "Plan": "<plan_tier>",
      "Health Score": <baseline from customer-success.md, default 50>,
      "Stage": "Onboarding",
      "Signup Date": "<signup_date>",
      "Kickoff Date": "<kickoff date if scheduled in Step 4c>"
    },
    "content": "<onboarding checklist + milestone dates table — markdown>"
  }]

The content markdown contains:

• Welcome heading + persona-tailored intro paragraph
• Onboarding Checklist table — one row per milestone from customer-success.md, with Milestone, Target Date, Trigger Event, Status (Pending)
• Kickoff Agenda (if tier includes one) — rendered from customer-success.md Kickoff Agenda
• Useful Links — product docs URLs from product.md, support email from brand.md
• NPS Cadence — Day-7, Day-30, Day-90 dates from customer-success.md Day-X Check-in Cadence

Capture the returned workspace_url for use in Step 4a (welcome email link) and Step 4d (Slack post).

Step 4c — Kickoff Calendly Booking Link (if tier includes kickoff)

Read customer-success.md to determine if plan_tier includes a kickoff call. If yes:

Calendly MCP is OAuth-deferred. Before calling any Calendly tool other than authenticate / complete_authentication, call ToolSearch with query "select:<tool_name>" to load the schema.

Use mcp__claude_ai_Calendly__authenticate

After OAuth completes, list the brand's CS event types and create a single-use scheduling link for this customer:

Use Calendly MCP event_types_list_event_types tool (loaded via ToolSearch):
- (no params — returns active event types for the authenticated user)

Pick the event type matching the kickoff defined in customer-success.md (by event name or duration). Then:

Use Calendly MCP scheduling_links_create_single_use_scheduling_link tool (loaded via ToolSearch):
- owner: <event_type_uri from previous call>
- max_event_count: 1

Capture booking_url. Inject it into the welcome email body (Step 4a) and into the Notion workspace Kickoff Agenda block (Step 4b).

Fallback — if the Calendly OAuth check fails, no event type matches the kickoff name/duration in customer-success.md, or the single-use scheduling-link tool errors out: read the Booking URL: line inside the ## Sender Persona block of brands/{brand}/sales.md and use that as booking_url. This is a standing (multi-use) link, not single-use — acceptable degradation for kickoff scheduling. If that line is also missing or empty, abort Step 4c, omit the booking-link variable from the email, and append a one-line note to the Slack notification in Step 4d: ⚠ Calendly booking link unavailable — run /link-skills:plugin-update to backfill sales.md Sender Persona Booking URL.

If the plan tier does not include a kickoff (e.g., Free), skip this step and omit the booking-link variable from the email template.

Step 4d — CS Team Slack Notification

DM the CS team channel with the customer profile + key dates so the human CSM can pick up the relationship.

Before calling slack_send_message, you MUST first call ToolSearch with query "select:mcp__claude_ai_Slack__slack_send_message" to load the tool schema. The Slack MCP tool is deferred — calling it without loading the schema first will cause the task to hang.

Use mcp__claude_ai_Slack__slack_send_message:
- channel_id: "$SLACK_NOTIFY_USER"
- text: "New customer onboarding kicked off — {customer_name} — {plan_tier}.
         Persona: {persona or 'unspecified'}.
         Signup: {signup_date}.
         Kickoff: {kickoff_date or 'none for this plan'}.
         Workspace: {workspace_url}.
         Welcome draft: pending CS review in Gmail.
         NPS schedule: D+7, D+30, D+90."

If the brand has a separate CS team channel ID (${BRAND}_CS_CHANNEL env var), prefer that over $SLACK_NOTIFY_USER. If the brand uses Slack Connect with the customer (declared in customer-success.md), also send a welcome message to the Connect channel — but only if customer-success.md declares slack_connect_welcome: true.

Step 5 — Schedule Milestone Check-Ins

For each milestone resolved in Step 3, queue a future Gmail draft so the CSM has a pre-built check-in ready on the milestone date. Notion is the queue:

Use mcp__claude_ai_Notion__notion-create-pages:
- parent: { "database_id": "${BRAND}_CUSTOMER_DB" }  (or a dedicated queue DB if declared)
- pages: [{
    "properties": {
      "Customer": "<customer_name>",
      "Milestone": "<milestone name>",
      "Send Date": "<milestone_dates[i]>",
      "Status": "Queued",
      "Email Template Ref": "<ref from customer-success.md>",
      "Customer Workspace": "<workspace page ID>"
    },
    "content": "<pre-rendered email body using customer-success.md template>"
  }]

Repeat for every milestone + every NPS check-in (Day-7, Day-30, Day-90 per customer-success.md Day-X Check-in Cadence).

These queued drafts are picked up later by a separate cron job (out of scope here) that flips Status to Sent after dispatch.

Step 6 — Update CRM Record

Flip the deal/customer record to onboarding state:

Use mcp__claude_ai_Notion__notion-update-page:
- page_id: <customer CRM page ID>
- properties: {
    "Stage": "Onboarding",
    "Plan": "<plan_tier>",
    "Signup Date": "<signup_date>",
    "Kickoff Date": "<kickoff date or null>",
    "Health Score": <baseline from customer-success.md, default 50>,
    "Customer Workspace": "<workspace_url>",
    "Onboarding Started": "<today ISO>"
  }

Step 7 — Save Local Audit Backup

Save an audit trail file capturing every action taken:

outputs/{brand}/customers/Onboarding_{customer_name}_{DDMonYYYY}.md

Contents: trigger source, customer info, plan tier, milestone schedule, links to all created resources (workspace, kickoff link, Gmail draft IDs, queued check-ins).

Output format

Save location — local audit:

outputs/{brand}/customers/

Naming convention:

Onboarding_{customer_name}_{DDMonYYYY}.md

Examples:

• Onboarding_AcmeCorp_07May2026.md
• Onboarding_PineAccounting_07May2026.md

Local audit metadata:

---
Date: YYYY-MM-DD
Skill Used: customer-onboarder
Brand: {brand}
Customer: {customer_name}
Customer Email: {email}
Plan Tier: {tier}
Persona: {persona or 'unspecified'}
Trigger Source: stripe_checkout | crm_closed_won | manual
Re-run: true | false
Signup Date: YYYY-MM-DD
Kickoff Date: YYYY-MM-DD | none
Workspace URL: <notion url>
Welcome Draft ID: <gmail draft id>
Booking URL: <calendly url or none>
Slack Notified: true | false
Milestones Queued: <count>
NPS Queued: <count>
CRM Stage After: Onboarding
Status: Success | Failed
---

Deliverables produced:

• Welcome email (Gmail draft, pending CS review unless auto-send declared)
• Shared Notion customer workspace inside ${BRAND}_CUSTOMER_DB
• Calendly single-use booking link (only if plan tier includes kickoff)
• Slack notification to $SLACK_NOTIFY_USER (and CS Connect channel if enabled)
• Queued milestone check-ins + NPS surveys in Notion
• Updated CRM record (Stage="Onboarding", baseline Health Score, dates, workspace link)
• Local audit file at outputs/{brand}/customers/

Quality checklist

Before finalizing:

• Customer record parent DB matches ${BRAND}_CRM_DB — no cross-brand contamination
• Plan tier resolved from Stripe subscription or CRM (no default invented)
• Duplicate-onboarding guard ran — aborted if Stage=Onboarding and no manual override
• All milestone definitions come from customer-success.md for the resolved plan tier — no fabrication
• Welcome email body comes from customer-success.md welcome template — placeholders filled, body unchanged
• Kickoff Calendly link created only if tier includes kickoff per customer-success.md
• Customer workspace created inside ${BRAND}_CUSTOMER_DB with onboarding checklist + milestone dates table
• Slack notification sent to $SLACK_NOTIFY_USER (and CS channel / Slack Connect if declared)
• Milestone check-ins + NPS surveys queued in Notion with correct future send dates
• CRM record flipped to Stage="Onboarding" with baseline Health Score from customer-success.md
• Local audit file written to outputs/{brand}/customers/
• Agent run logged to dashboard

Final Step — Log to Dashboard

See docs/new_agent_onboarding/metrics-spec.md for the full JSONB contract.

Use gateway MCP tool `fiveagents_log_run`:
- fiveagents_api_key: ${FIVEAGENTS_API_KEY}
- skill: "customer-onboarder"
- brand: "<active-brand>"
- status: "<success|failed>"
- summary: "<1 line, <200 chars>"
- started_at: "<ISO timestamp>"
- completed_at: "<ISO timestamp>"
- metrics: {
    "date": "YYYY-MM-DD",
    "customer": "<customer name>",
    "customer_email": "<email>",
    "plan_tier": "<tier>",
    "persona": "<persona slug or null>",
    "trigger_source": "<stripe_checkout|crm_closed_won|manual>",
    "re_run": false,
    "signup_date": "YYYY-MM-DD",
    "kickoff_date": "YYYY-MM-DD",
    "kickoff_included": true,
    "workspace_url": "<notion url>",
    "welcome_draft_id": "<gmail id>",
    "booking_url": "<calendly url>",
    "milestones_queued": 0,
    "nps_queued": 0,
    "slack_notified": true,
    "crm_stage_after": "Onboarding",
    "health_score_baseline": 50,
    "output_path": "outputs/{brand}/customers/",
    "deliverable": "Onboarding_{customer}_{DDMonYYYY}.md"
  }