workspace-builder

Workspace Builder

Sets up a CRM workspace conversationally — turning "I don't know how to start" into a working board on day 1. Replaces the manual template-pick → column-rename → column-add → group-rename loop that gates 442 median days between CRM install and first MCP execution. This is the single highest-leverage retention skill in the catalog.

Flow: Trigger → Discover → Propose → Confirm → Build (α) → Seed (β, opt-in) → Handoff.

Input

• Optional: business description via argument.
• Optional: user pre-declared mode (Default / Silent / Proactive). Add "silently" or "skip confirmations" to your request to run in Silent mode. Silent mode builds without per-step confirmations.

Output

• α (default): One board (or set of boards) created in the user's chosen workspace. Boards carry the user's chosen names (no plugin prefix). Groups + columns scaffolded per the proposed structure. A CRM Setup — <Mon DD> doc summarizes what was created and what's next, with Generated by Claude · <ISO timestamp> + <!-- claude-skill-id: workspace-builder --> in the body.
• β (Seed mode, opt-in): 5–10 example items per board so the user can see the shape with data, not just empty columns. Each example item carries Source = Claude on a status column (auto-create the column with user confirm if missing) — no [Example] prefix on names.
• Proactive extension: Out of scope for v0.1 (automation creation requires create_automation_rule, not yet shipped). The setup doc includes a deep-link to the in-product Automation Recipes UI for that step.

Knowledge

• monday CRM entity board catalog + relationships (§ monday CRM Entity Boards).
• Industry → board-shape map (§ Step 3).
• Column-type repertoire (§ Step 4).
• Shared artifact conventions (§ Shared patterns).
• GraphQL mutations for group operations: references/monday-graphql-mutations.md.

Tools (MCP)

• get_user_context — resolve user + existing workspaces.
• list_workspaces / workspace_info — find a target workspace.
• search — confirm we aren't duplicating an existing CRM board.
• create_workspace — only if the user explicitly wants a new workspace.
• create_board — the core write.
• create_group — pipeline stages as groups (or as status labels — see Step 4).
• create_column — typed columns per the proposed schema.
• create_item — β seed items.
• create_doc — publish the setup summary doc.
• all_monday_api — group rename/delete mutations + column settings (status labels, number units) not exposed by wrapped tools. See references/monday-graphql-mutations.md for exact payloads.

Cross-skill handoffs

• From none (entry point): First-run user, in-product CTA route, or explicit ask.
• To daily-briefing: Once the board has at least 5 items with a stage column populated, suggest /monday-crm:daily-briefing to start the daily-ops loop.
• To data-cleanup: After 30 days of use, suggest /monday-crm:data-cleanup for a fill-rate audit.

---

monday CRM Entity Boards

monday CRM is built around five canonical entity board types. When proposing a workspace structure, use these as building blocks — don't invent custom schemas. Use the user's own terminology for board and column names, but match the underlying column types and group structure.

Always propose Deals. Add other boards only when the user's description clearly signals the need.

Deals — the pipeline board (always included)

Every monday CRM user starts here.

• Groups (pipeline stages): New · Discovery · Proposal · Negotiation · Won · Lost
• Columns: Stage (status, is_done: true on Won), Owner (people), Deal Value (numbers $), Probability (numbers %), Expected Close (date), Last Touch (date), Source (status), Notes (long_text)

Contacts — individual people records

Add when the user mentions tracking people, contacts, or has account managers / a team managing relationships.

• Groups: Active · Inactive
• Columns: Email (email), Phone (phone), Company (text), Owner (people), Source (status), Last Activity (date), Notes (long_text)
• Relates to: Deals (link contact to their deal via board_relation)

Leads — inbound / unqualified prospects

Add when the user mentions SDR, outbound, lead gen, or has a qualification step before deals.

• Groups: New · Contacted · Qualified · Disqualified
• Columns: Stage (status), Owner (people), Source (status), Email (email), Phone (phone), Company (text), Last Touch (date), Notes (long_text)
• Relates to: Deals (qualified leads become deals — link via board_relation)

Accounts — companies / organizations

Add when the user mentions account management, renewals, B2B with multiple contacts per company, or CSM workflows.

• Groups: Active Customers · Prospects · Churned
• Columns: Owner (people), Industry (status), Size (numbers), ARR (numbers $), Health (status), Last Activity (date), Notes (long_text)
• Relates to: Contacts (people at this account), Deals (deals linked to this account)

Activities — calls, emails, meetings log

Add when the user explicitly mentions logging activity, tracking touchpoints, or managing a high-touch sales motion with multiple interactions per deal.

• Groups: This Week · This Month · Archive
• Columns: Type (status: Call / Email / Meeting / Demo), Owner (people), Date (date), Notes (long_text)
• Relates to: Deals (the deal this activity belongs to), Contacts (the person involved)

---

Board relationships

Leads ──qualified──▶ Deals ◀──linked──── Accounts
                       │                     │
                       └──── Contacts ────────┘
                                 │
                             Activities

• Leads → Deals: when a lead qualifies, create (or link to) a deal. board_relation on Leads pointing to Deals.
• Contacts ↔ Deals: contacts are participants on deals. board_relation on both sides.
• Accounts → Contacts + Deals: an account owns many contacts and many deals. board_relation on Contacts and Deals pointing to Accounts.
• Activities → Deals + Contacts: each activity is scoped to one deal and one contact. board_relation columns on Activities.

v0.1 constraint: create_column with board_relation type requires the target board to already exist. Build all boards first (Step 5), then add relation columns in a second pass via all_monday_api. Only wire relations the user explicitly asked for — don't create them by default.

---

Persona → board set

Signal in user's description	Boards to propose
Sales rep / AE / closing deals	Deals + Contacts
SDR / BDR / outbound / lead gen	Leads + Deals
Sales manager / team lead	Deals — suggest dashboards manually
Account manager / renewals / CSM	Accounts + Contacts + Deals
Full team / full CRM setup	Deals + Contacts + Leads + Accounts
Solo founder / small team	Deals only — keep it simple

Never create all 5 boards by default. Blank boards are intimidating and reduce activation.

---

Step 0: Connector check

Goal: Fail fast if the monday MCP connection is missing. Detect the CRM product and cache its numeric ID for workspace creation.

1. Try mcp__monday__get_user_context.
2. If missing/auth error/no workspace:
   • Print exactly: "I don't see the monday connector active on this session. Install the monday connector at monday.com/mcp, then run /monday-crm:workspace-builder again."
   • Stop.
3. If connector works, cache user.id and user.name.
4. Check account.products (from get_user_context) for an entry with kind: "crm". If not found, print: "This plugin requires a monday CRM account. Your current plan doesn't include the CRM product — visit monday.com/crm to start a trial." and stop.
5. Get the CRM product's numeric ID (needed for workspace creation — the kind string alone is not sufficient):

   { account { products { id kind } } }
   

   via all_monday_api. Find the entry with kind: "crm" and cache its id as crmProductId. This ID is account-specific (e.g., "1312540") — do not hardcode it.

PAUSE: do not write any create_* call before Step 5, and never before Step 0 passes.

---

Step 1: Detect mode

• Default — confirm the full build plan once (batch) before executing. Confirms again only for delete operations.
• Silent — skip confirmations, stay on α scope (no β seed items). Triggered by "silently", "skip confirmations", or similar in the user's request.
• Proactive — ask once: "Proactive mode will create the board(s), groups, columns, AND seed example items. (a) Approve all, (b) Review each create call, (c) Skip seed items?". Cache the choice.

If undeclared, assume Default.

Hard safety rail regardless of mode: no deletes (boards, columns, items), no amount-column writes, no cross-workspace moves, no overwriting an existing same-named board, no modifying columns on boards the user didn't ask us to touch, no board creates outside the user-confirmed workspace.

---

Step 2: Discover — learn about the user's business

Goal: Get enough signal to propose a board shape without forcing the user into a taxonomy. The whole skill exists to bypass the "where do I start" paralysis — surfacing internal labels like "B2B sales" or "Outbound" defeats that.

2a: Website enrichment (preferred)

Ask first: "What's your company website? I'll read it to get context on your business — or describe your business in a sentence if you'd prefer."

• If a URL is provided → WebFetch the homepage. Extract: industry, product/service description, target customer (B2B/B2C, company size), any sales/CRM terminology used on the site (e.g., "clients", "projects", "leads", "cases"). Use this as the primary business context for Step 3 — skip the free-text question below entirely.
• If no URL / user prefers to describe → fall through to 2b.

If WebFetch fails (404, timeout, paywalled) → fall through to 2b silently, don't surface the error.

2b: Free-text fallback

Ask one open prompt: "Tell me about your business — industry, what you sell, who you sell to, roughly how many deals/leads you track. One or two sentences."

2c: One clarifying follow-up (if needed)

Only if the description (from website or free-text) is genuinely under-specified for a column-set decision, ask one clarifying follow-up:

• Currency / deal-size unit if values are mentioned.
• Approximate pipeline volume (<50 / 50–500 / 500+) if it'll change between a single-board vs. two-board funnel.

Hard cap: 2 questions total across 2a–2c. Anything beyond that defeats the skill.

---

Step 3: Map description → internal archetype → board shape (Synthesize)

Goal: Translate the free-text description into a concrete board proposal. Internal mapping uses an archetype taxonomy as scaffolding — the user never sees the archetype label.

Internal archetype map (not user-visible)

Signals in description	Internal archetype	Default board shape
Long sales cycle, account/stakeholder language ("contracts", "buyers", "procurement"), deal sizes >$1K	B2B sales	Single Deals board, pipeline as groups, rich columns
High volume / short cycle / consumer-facing ("orders", "customers", "products", e-commerce, retail)	B2C transactional	Orders + Customers (two boards), pipeline as status column
Project / hourly / engagement language ("clients", "retainers", "billable", "projects")	Services	Engagements + Clients, pipeline as groups, effort/hours columns
Outbound / lead-gen / top-of-funnel ("SDR", "cold outreach", "leads", "ICP")	Outbound	Leads + Deals (two-board funnel), status on Leads, groups on Deals
Mixed / unclear / industry-specific (recruiting, real estate, law firm, etc.)	Custom	Compose from primitives (see below) — don't force a fit

Custom mode

When the description doesn't fit cleanly, compose the board structure from primitives rather than forcing an archetype:

• Primary entity board (e.g., Candidates for recruiting, Listings for real estate, Matters for a law firm) — name reflects the user's own language.
• Pipeline mechanism (groups vs. status column) — pick groups for low-volume / high-touch, status column for high-volume.
• Secondary board if the description names two distinct entities (e.g., Candidates + Roles, Listings + Buyers).
• Columns chosen from the standard set (Owner, Stage, Value, Probability, Date, Source, Notes) plus 1–3 industry-specific columns inferred from the description.

Output to user

Present a complete, named board structure as a markdown table. Use the user's own terminology wherever possible (if they said "matters", call the board "Matters" not "Cases"). Skip any internal archetype label.

For each proposed board:

• Board name (no plugin prefix).
• Group list with concrete labels.
• Column list with types (e.g., Stage (status), Owner (people), Value (numbers, $), Last touch (date)).
• One line of rationale grounded in the user's description (not the archetype): "You mentioned tracking listings and buyers separately, so I split them across two boards."

Do not include workspace name here — workspace hasn't been resolved yet (Step 4). The batch confirm in Step 5 is where the workspace name appears.

Then ask: "Build this as-is, change anything before building, or describe your business differently?"

Hard rule: no writes until the user confirms.

---

Step 4: Resolve target workspace

Goal: Land in the right workspace without cluttering Main. Prefer existing CRM workspaces over creating new ones.

1. From get_user_context, get the workspace list. Then call list_workspaces to get all writable workspaces.
2. Identify CRM workspaces: A workspace is likely CRM-native if its name contains "CRM" (case-insensitive) or if it was previously used for CRM boards. Surface CRM-named workspaces first in the options list.
3. If the user has exactly one writable workspace → use it (skip ask).
4. If multiple → AskUserQuestion with workspace names (CRM ones labeled [CRM]) + option "create a new one".
5. If "create a new one" → after confirming, call:

   create_workspace({ name: "<user input or default 'CRM'>", workspaceKind: "open", accountProductId: "<crmProductId>" })
   

   where crmProductId is the numeric ID cached in Step 0 (e.g., "1312540") — NOT the string "crm". Passing the numeric ID ties the workspace to the monday CRM product; omitting it or passing "crm" creates a generic monday workspace with no product association.
6. Idempotency: before any create_board, search for existing boards in this workspace whose names match the proposed names (case-insensitive). If found:
   • Surface to user: "You already have a board named <name>. (a) Skip this board, (b) Create alongside as <name> 2 (I'll re-confirm the full plan before building), (c) Cancel and pick a different workspace?"
   • Option (b) updates the plan — show the revised full plan and ask for confirmation before any writes (even in Default mode).
   • Never overwrite, never write into the existing board, never delete it.

---

Step 5: Build α — create boards (Publish)

Goal: Execute the confirmed structure with idempotency, in a deterministic order.

Confirm-before-write (Default mode)

Before the first create_board call, print a single batched confirm: "I'll create board(s) with columns total in workspace <workspace>. Want example items added after building? (yes / no) — Proceed? (yes / no / show plan again)."

This single confirm captures both the build plan and the β opt-in. Per-call confirmation only kicks in for delete operations (group deletes). Spamming the user with N confirms defeats the skill.

Build sequence

For each proposed board:

1. create_board({ boardName: "<name>", workspaceId, boardKind: "public" | "private" }) — default public unless user said otherwise. Cache returned boardId.
2. Replace default groups: monday creates a default "Group Title" / "New Group" entry on every new board. Query existing groups first, then:
   • Rename the first default group to the first proposed group via all_monday_api using update_group mutation.
   • create_group for remaining proposed groups.
   • If renaming fails, use delete_group mutation via all_monday_api (Default mode confirms before delete) then create_group cleanly.
   • See references/monday-graphql-mutations.md for exact payloads.
3. For each proposed column: create_column({ boardId, columnType: <type>, title: <title>, defaults: <settings> }). For status columns, pass labels via defaults; for numbers columns, pass unit.symbol.
4. Order matters for the user's mental model: create columns left-to-right in the order proposed (Stage first, then Owner, then Value, then dates, then long_text last). monday assigns column position by creation order.
5. After each create_*, mirror to chat: "Created column Owner (people) on Deals.". Default mode runs through creates inside a confirmed plan; Silent runs through all; Proactive (b) confirms each; Proactive (c) skips seed step.

---

Step 6: Seed β (opt-in)

Goal: Show the shape with data — empty boards are intimidating.

Only runs if mode = Proactive (option a) OR user opted in at the Step 5 batch confirm.

For each created board, create_item for 5 example items distributed across the proposed groups/stages, with realistic but obviously-fake values:

• Names like Acme Corp — Q3 expansion, Beta Industries — pilot deal (clearly fictional but no prefix pollution).
• Stage spread: 1 New, 2 mid-funnel, 1 Won, 1 Lost (or shape-appropriate).
• Owner = the running user (so every example shows up in the user's "my items" filters).
• All other columns populated to demonstrate the data model.
• Source = Claude on a status column. The board was just created in Step 5 with this column included by default — Step 6 just sets the value. If for any reason the column wasn't created, prompt once: "Add a Source column so we can flag the example items? (yes / skip — keeps the items unflagged)".

Cap at 5 items per board, hard. The Source = Claude flag supports a clean cleanup loop later — user filters by source, deletes the examples manually once they have real data.

---

Step 7: Publish setup doc (Publish)

Goal: Leave a navigable summary so the user knows what was created and where to go next.

Idempotency: before creating, search same-day docs by title + the <!-- claude-skill-id: workspace-builder --> marker. If found, skip creation and print: "A setup doc from this session already exists: <doc url>. The build summary has been added to chat above." Do not attempt to update the existing doc.

If no existing doc found, create_doc in the user's workspace, title CRM Setup — <Mon DD>, <YYYY>. Body:

# CRM Setup — <Mon DD>

<!-- claude-skill-id: workspace-builder -->

## What was created

### Board: <Name>
- Workspace: <workspace>
- URL: <board url>
- Groups: <list>
- Columns: <list with types>

(Repeat per board.)

## Example items
<count> example items added per board, flagged `Source = Claude` on a status column. Filter by that source value to find and remove the examples once you've added real data.

## What's next

1. **Add your real deals.** Replace the examples or add fresh items.
2. **Try the morning briefing.** Once you have 5+ deals with stages set, run `/monday-crm:daily-briefing`.
3. **Set up automations.** Open the Automation Center on each board to wire status changes, due-date reminders, and lead routing.
4. **Audit hygiene later.** After 30 days, run `/monday-crm:data-cleanup` for a fill-rate audit.

---
Generated by Claude · <ISO timestamp> · re-run `/monday-crm:workspace-builder` only if you want to scaffold an additional CRM (won't touch this one).

---

Step 8: Handoff to daily-briefing

If at least one board was created and the user is in Default/Proactive mode, print: "Want to try the morning briefing now? Once you add a few real deals it'll prioritize your day. Run /monday-crm:daily-briefing whenever you're ready."

Silent mode skips this prompt.

---

Step 9: Close the loop

• Print a one-line summary: Created <N> board(s), <M> columns, <K> seed items. Doc: <url | "doc creation failed — see summary above">.
• If any write failed mid-run: list the failures and offer to retry only those — never re-run the whole skill on retry (would duplicate boards if Step 4 idempotency was bypassed).

---

Shared patterns

• No prefix on titles. Boards take the user's chosen names. Setup doc uses plain title + <!-- claude-skill-id: workspace-builder --> comment + Generated by Claude footer in body for findability + idempotency.
• Source = Claude on every seed item via a status column. No [Example] prefix.
• Idempotency before every create — board-name collision check, doc same-day collision check (by skill-id comment). On doc collision: skip creation, surface existing link.
• Safety rail. No deletes (except confirmed default-group cleanup on freshly-created boards), no amount-column writes, no cross-workspace creates, no writes outside the confirmed plan.
• Confirm in batches, not per-call — the whole skill exists to reduce friction; per-call confirms defeat it.
• Type-based column choices, not English-name-based — works on non-English monday installs.
• Use the user's terminology in board / group / column names, not the internal archetype names.

---

Output template

Setup doc (create_doc body)

# CRM Setup — Jun 15

<!-- claude-skill-id: workspace-builder -->

## What was created

### Board: Deals
- Workspace: CRM
- URL: https://monday.com/boards/123456789
- Groups: New · Discovery · Proposal · Negotiation · Won · Lost
- Columns: Stage (status) · Owner (people) · Deal Value (numbers, $) · Probability (numbers, %) · Expected Close (date) · Last Touch (date) · Source (status) · Notes (long_text)

## Example items
5 example items added, flagged `Source = Claude` on the Source status column. Filter by that source value to find and remove the examples once you've added real data.
- Acme Corp — Q3 expansion (Discovery, $85K, Owner: Tom Ramu)
- Beta Industries — pilot (Proposal, $32K, Owner: Tom Ramu)
- Gamma Ltd — renewal (Won, $120K, Owner: Tom Ramu)
- Delta Co — trial (New, $15K, Owner: Tom Ramu)
- Epsilon Inc — churned (Lost, $28K, Owner: Tom Ramu)

## What's next
1. **Add your real deals.** Replace the examples or add fresh items.
2. **Try the daily brief.** Once you have 5+ deals with stages set, run `/monday-crm:daily-briefing`.
3. **Set up automations.** Open the Automation Center on each board to wire status changes, due-date reminders, and lead routing.
4. **Audit hygiene later.** After 30 days, run `/monday-crm:data-cleanup` for a fill-rate audit.

---
Generated by Claude · 2026-06-15T09:00:00Z · re-run `/monday-crm:workspace-builder` only if you want to scaffold an additional CRM (won't touch this one).

Chat one-liner:

Created 1 board, 8 columns, 5 seed items. Doc: [url].

---

Error handling reference

Failure	Behavior
Connector not installed	Step 0 stops; print install link + skill re-run command.
No writable workspace	Step 4 stops; print: "You don't have write access to any workspace. Ask a workspace admin, then re-run."
Board name collision	Step 4 idempotency prompt; option (b) re-confirms full plan before building.
create_board fails (perms)	Stop and surface error verbatim — don't continue creating columns into a non-existent board.
create_column fails on a column	Skip that column, log to chat, continue with the rest, list skipped in Step 9 summary.
create_group fails	Skip; the board still works with default groups; flag in summary.
429 rate limit	Backoff 3x (1s, 2s, 4s); on third fail, halt and print: "monday is rate-limiting; retry in 60s."
User halts mid-build	Keep writes up to halt point; Step 7 setup doc reflects partial state.
Setup doc create fails	Print the doc body in chat with banner "Couldn't publish the setup doc — copy the summary below."

---

Completion criteria

• Step 0 (connector check) ran and passed.
• At least one board was created (or user explicitly cancelled at Step 3/4).
• No internal archetype label leaked into user-visible output (board/group/column names use the user's terminology).
• Every seed item carries Source = Claude on a status column (or the user explicitly skipped the source-column step).
• The setup doc was created (with <!-- claude-skill-id: workspace-builder --> + Generated by Claude footer) or printed to chat on failure.
• Safety rail held: no deletes outside default-group cleanup on freshly-created boards, no amount-column writes, no cross-workspace creates, no writes outside the confirmed plan.
• The chat summary lists any per-column failures.