Crystal (Crystal Knows) Platform Help
Step 1 — Gather context
If references/learnings.md exists, read it first for accumulated platform knowledge.
Ask the user (skip if their prompt already answers these):
-
What do you need help with?
- a) Reading/interpreting a prospect's personality profile (DISC looks wrong, low confidence)
- b) Chrome extension (LinkedIn/Gmail previews, preview limit)
- c) CRM sync (HubSpot deal sync, Salesforce) or Google Calendar meeting reports
- d) API integration (Profile lookup / text Analysis) or the MCP server
- e) Pricing / which plan unlocks a feature
- f) Privacy / GDPR / consent for profiling people
- g) Choosing Crystal vs a competitor → this is a strategy question (Step 2)
-
Which product/plan? Free · Premium · Sales (Basic/Pro/Max) · Hiring · Coaching · Teams · Enterprise (API/MCP)
Skip-ahead rule: if the user's prompt already contains enough context, skip to Step 2.
Step 2 — Route or answer directly
| Problem domain | Route to | Command |
|---|
| Choosing between personality-selling tools (Crystal vs Humantic/Humanlinker/Happysales), or how to sell to a DISC type | /sales-personality-selling | /sales-personality-selling {user's question} |
| General contact/company enrichment strategy across providers | /sales-enrich | /sales-enrich {user's question} |
| Actually sending the outreach / building a sequence | /sales-cadence | /sales-cadence {user's question} |
| Mapping the buying committee at a target account | /sales-account-map | /sales-account-map {user's question} |
| Connecting Crystal to other tools (iPaaS/webhooks) | /sales-integration | /sales-integration {user's question} |
When routing to another skill, provide the exact command: "This is a {problem domain} question — run: /sales-{skill} {user's original question}"
If the question is Crystal-specific, continue to Step 3.
Step 3 — Crystal platform reference
Read references/platform-guide.md for the full platform reference — modules and their
automation surface, pricing/plan gates, integrations, data model, and quick-start recipes.
If they're asking about the API or the MCP server, also read references/crystal-api-reference.md
for endpoints, auth, cURL/Python, and the MCP tool list.
Answer the user's question using only the relevant section. Don't dump the full reference.
Step 4 — Actionable guidance
You no longer need the platform guide — focus on the user's specific situation.
- Treat pricing/plan gates as best-effort and point to crystalknows.com/pricing to confirm. Call out that the API and MCP server are Enterprise/Business-only (demo-gated, ~30 free calls then paid) and that HubSpot deal sync is paid-plan-gated (Pro+), not on Sales Basic.
- When a DISC profile looks wrong or has low confidence, say the prediction is only as good as the input — a thin LinkedIn profile yields a low-confidence guess. Recommend feeding a text sample (their writing) via the Analysis path for a more defensible read, and tell the user to trust the buyer's observed behavior over a low-confidence prediction rather than assume the tool is right. Do not let a low-confidence prediction overwrite CRM fields — gate on
confidence (e.g. ≥ 0.6) and flag the rest for manual review.
- For API work, name the async flow explicitly:
POST profiles/async → get a Request ID → poll GET profiles/results/{id} until status == "complete"; auth via the X-Org-Token header on the Connect API (connect.crystalknows.com/v1). Map a 401 to a bad/expired token and a 402 to quota exceeded or an inactive account (a stop, not a retry).
- For Claude/Cursor automation, prefer the MCP server (
https://mcp.crystalknows.com, OAuth2) over the REST API — it returns tips pre-formatted and adds get_upcoming_meetings and profile-tagging tools the REST API lacks.
- For privacy/GDPR questions, flag that personality prediction is profiling — the customer is the data controller and typically relies on legitimate interest, must update their privacy notice, and should honor access/deletion requests. Note Crystal states no sensitive PII is stored and its data is not intended for hiring/credit decisions. Present this as best-effort guidance, not definitive legal advice — tell the user to confirm specifics with counsel.
- Crystal gives insight, not outreach — it doesn't send emails or run sequences; pair it with a cadence tool.
If you discover a gotcha, workaround, or tip not covered in references/learnings.md, append it there.
Gotchas
Best-effort from research (2026-07) — review these, especially items about plan-gated features and integration gotchas that may be outdated.
- API/MCP are Enterprise-only. No API on Free or standard Sales/Hiring tiers. A
402 Payment Required means quota exceeded (past the ~30 free calls) or an inactive account — contact your CSM, don't retry.
- DISC accuracy tracks input completeness. Predictions from a sparse LinkedIn profile come back low-confidence and are frequently "wrong." Use a text sample (Analysis) and gate downstream writes on
confidence.
- 10 lifetime Chrome previews on Free. The free plan's extension previews are a lifetime cap, not monthly — they run out fast. Unlimited previews require a paid Sales tier.
- HubSpot deal sync is paid-gated. On Sales Basic, deal-level personality sync is off; it's Pro+. Contact-level surfacing differs from deal sync.
- Two API generations. The SDK-backed Connect API uses
X-Org-Token; the newer Personality API docs show Authorization: Bearer. Confirm which your token targets before building.
- Profiling has consent implications. Predicting personality from public data is automated profiling under GDPR — the customer is the controller and must handle notice + data-subject rights. Crystal is not to be used for hiring/credit decisions.
- Insight, not automation. Crystal has no outbound sender and no documented webhooks — it enriches; you still need a cadence/CRM tool to act.
Related skills
/sales-personality-selling — Personality-based selling method (reading DISC/OCEAN, adapting outreach) and choosing between Crystal, Humantic AI, Humanlinker, Happysales/sales-enrich — Contact/company enrichment strategy and waterfall enrichment across providers/sales-cadence — Building the outbound sequence that acts on Crystal's tips/sales-account-map — Mapping buying committees at target accounts/sales-integration — Connecting Crystal to other tools via API/iPaaS/sales-do — Not sure which skill to use? The router matches any sales objective to the right skill. Install: npx skills add sales-skills/sales --skill sales-do -a claude-code
Examples
Example 1: "My prospect's DISC type on Crystal says 'C' but they seem really outgoing on our calls — is Crystal just wrong?"
→ Explains prediction confidence, that a thin LinkedIn profile yields low-confidence guesses, how to feed a text sample via Analysis for a better read, and to trust observed behavior over a low-confidence prediction.
Example 2: "How do I pull a prospect's DISC type into HubSpot automatically before my reps email them?" (developer/automation)
→ Walks through the async Profile API (POST profiles/async → poll profiles/results/{id}), X-Org-Token auth, gating the CRM write on confidence, that deal sync is Pro+, and using the MCP server for a Claude-driven pre-meeting brief.
Example 3: "We scrape LinkedIn to build Crystal profiles of prospects in the EU — are we allowed to do that?"
→ Frames personality prediction as GDPR profiling, the customer-as-controller / legitimate-interest basis, updating the privacy notice, honoring access/deletion, and Crystal's no-sensitive-PII and no-hiring-decision positions.
Troubleshooting
Crystal API returns 401 or 402
- Cause: 401 = invalid/expired token (or wrong auth header for the API generation); 402 = quota exceeded past the ~30 free calls, or the account is inactive.
- Fix: For 401, reissue the Org token and confirm you're sending
X-Org-Token for the Connect API (vs Authorization: Bearer for the newer Personality API). For 402, contact your Customer Success Manager — it's a plan/quota stop, not retryable.
A prospect's personality profile looks obviously wrong
- Cause: The DISC prediction was generated from a sparse LinkedIn profile → low
confidence.
- Fix: Re-run via the Analysis path with a real text sample (their About section, posts, or emails). Check
disc_scores.confidence; if it's low, trust observed behavior and don't push it into the CRM.
Chrome extension stopped showing previews
- Cause: Free plan's 10 lifetime previews are exhausted (they're a lifetime, not monthly, cap).
- Fix: Upgrade to a paid Sales tier for unlimited previews, or use the web app for individual profiles. Confirm current limits at crystalknows.com/pricing (best-effort).
