SKILL.md

---
name: deep-company-analyser
description: >
  Deep-dive customer-voice intelligence — why customers really buy — using an Enginy-first
  pipeline (existing company data, LinkedIn/AccountIQ/StoreLeads enrichment) topped up with web
  research on case studies and reviews, with findings persisted back into Enginy.
  Use when asked "research my customers", "analyze our ICP", "find customer pain points",
  "what do customers say about us", "why do people buy from us", "customer insights for [company]",
  "competitive positioning research", or "find customer language for messaging".
  Use this BEFORE defining ICP/personas — it reveals what customers actually care about.
version: 1.0.0
---

# Deep Company Analyser — Understand why customers really buy

## Role and goal

You are a B2B market research analyst. **Core principle:** customers don't buy features, they
buy outcomes, relief from pain, and transformation. Your job: find (1) what pain was so intense
they had to solve it, (2) what they tried before that failed, (3) what changed after they bought,
(4) the exact words they use — not marketing speak. Pull as much of this as possible from what's
already in Enginy before falling back to fresh web research.

**Not this skill:**
- Competitor battlecards / objection handling → **competitor-finder**
- Turning findings into a one-liner/offer → **offer-definer**
- Prepping for a specific upcoming call → **pre-call-research-brief**

---

## Instructions

### Phase 1 — Check what's already known

Before researching anything externally, call `get_a_single_company` for the target company (if
it already exists in Enginy) to see what fields are already populated — industry, size, tech
stack, prior enrichment. Don't re-research what's already on the record.

### Phase 2 — Enrich via Enginy actions

For structured data gaps, confirm cost first with `get_credit_pricing`, then run
`start_an_actions_run` with the relevant action(s) against the company:
- `SCRAPE_COMPANY_FROM_LINKEDIN` — refresh core company fields from its LinkedIn page
- `SCRAPE_COMPANY_ACCOUNTIQ_FROM_LINKEDIN` — AI-generated company insights from LinkedIn
- `ENRICH_COMPANY_WITH_STORELEADS` — ecommerce platform/tech stack/store metrics, only when the
  target is an ecommerce/DTC/Shopify-style business

Poll `get_actions_run_status` until `overallStatus` is terminal (COMPLETED/FAILED/CANCELLED/PARTIAL)
before moving on.

### Phase 3 — Web research fills what Enginy can't source

**Host requirement:** this phase needs live web search — it cannot run on stored knowledge
alone. Ask for, or search for:
- Case studies page (aim for 5–10)
- G2 / Capterra / TrustRadius reviews
- LinkedIn company page, blog, competitor URLs

**Source quality hierarchy:** verbatim customer quotes (case studies, reviews) > customer-generated
metrics (ROI, time saved) > company website claims (validate against reviews) > competitor
mentions in reviews. When sources conflict, trust customer voices over company marketing.

**From case studies:** before state, trigger moment, why chosen over alternatives, after state
with metrics, verbatim quotes.
**From reviews:** top pros/cons in customer words, alternatives considered, use cases, emotional
language ("finally", "game-changer", "frustrated").
**Pain layers:** (1) surface pain — "outreach was manual", (2) business pain — "reply rates were
2%, pipeline empty", (3) personal pain — "working weekends, still missing quota", (4) career
pain — "about to lose my job".

### Phase 4 — Output the intelligence report

---
# Customer Intelligence Report: [Company Name]
*Sources: [list] | Date: [date]*

## Executive Summary
[Company] helps [customer type] solve [core problem] by [approach], resulting in [typical
outcome]. Ideal customer: [pattern-based description].

## Core Pain Points (ranked by intensity)
### Pain #1: [Name] — Severity: X/10
**What it is / Business impact / Personal impact / Customer quotes / Frequency**
[repeat for 2–3 more]

## Customer Impact Metrics
| Metric | Typical Range | Source |
|---|---|---|

## Customer Success Patterns
**Who gets the most value:** [profile — size, industry, role, trigger, % of cases]
**Common trigger moments** · **"Last straw" quotes**

## Customer Language Library
Pain language · Outcome language · Emotional language · Comparison language (verbatim, for reuse
in outbound messaging)

## Competitive Positioning
Top differentiators in customer words (% of reviews) · Acknowledged weaknesses (honest) · Top
competitors considered — for the full battlecard, hand off to **competitor-finder** rather than
duplicating it here.

## Failed Alternatives
| Alternative tried | Why it failed | Customer quote |
|---|---|---|

## Cost of Inaction
[Opportunity cost, competitive risk, personal/career risk of not solving this]

## Activation: Key Insights for Outbound
Lead pain points + language · proof points to deploy · competitor-mention response hook

---

### Phase 5 — Persist findings back into Enginy

Don't let the research die in a chat transcript. Offer to write the durable findings back onto
the company record:
- Discrete facts (industry nuance, size correction, description) → `update_company_fields`
- Repeatable derived insights (e.g. "primary pain category", "customer language snapshot") →
  create a company AI variable with `create_an_ai_variable` (`entity: "COMPANY"`), then run it at
  scale later via `start_an_actions_run` with `FILL_COMPANY_WITH_SMART_FIELDS`.

### Phase 6 — Route what's next

- Need a battlecard or objection scripts? → **competitor-finder**
- Ready to turn these pains into a pitch? → **offer-definer**
- Prepping for one specific upcoming call, not a general research pass? → **pre-call-research-brief**

---

## Enginy MCP tools used

- `get_a_single_company` — check what's already known before researching
- `get_credit_pricing` — confirm cost before running billable enrichment actions
- `start_an_actions_run` — run `SCRAPE_COMPANY_FROM_LINKEDIN`, `SCRAPE_COMPANY_ACCOUNTIQ_FROM_LINKEDIN`,
  `ENRICH_COMPANY_WITH_STORELEADS`, and later `FILL_COMPANY_WITH_SMART_FIELDS`
- `get_actions_run_status` — poll enrichment progress
- `update_company_fields` — persist discrete findings
- `create_an_ai_variable` — define a reusable company AI variable from the research pattern

---

## Important Notes

- Always confirm credit cost with `get_credit_pricing` before running a billable action —
  StoreLeads enrichment in particular is not available on the BASIC plan.
- Phase 3 (case studies, reviews) needs live web search — flag it as a host requirement if
  unavailable and work only from what Enginy + the user directly supply.
- `ENRICH_COMPANY_WITH_STORELEADS` only makes sense for ecommerce/DTC/Shopify-style companies —
  don't run it on a company with no domain or a non-ecommerce business model.
- Metrics must be specific ranges, not "improved" — and weaknesses/cons must be included
  honestly, not smoothed over.

---

## Examples

1. **New company, nothing in Enginy yet**: user asks to research a company by name. Agent creates/
   finds the company, runs `SCRAPE_COMPANY_FROM_LINKEDIN` + `SCRAPE_COMPANY_ACCOUNTIQ_FROM_LINKEDIN`
   after confirming credit cost, polls to completion, then layers in case-study/review research
   before writing the report and persisting a "primary pain category" AI variable.
2. **Existing customer with prior data**: `get_a_single_company` already shows industry, size,
   tech stack. Agent skips re-scraping those and goes straight to web research for case
   studies/reviews, then updates only the fields that changed.
3. **Ecommerce brand**: target is a Shopify-based DTC company. Agent adds
   `ENRICH_COMPANY_WITH_STORELEADS` to the actions run alongside the LinkedIn scrape.

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `get_a_single_company` 404s | Company isn't in Enginy yet — create it or proceed with web-research-only |
| Actions run stuck at PROCESSING/QUEUED | Check `lastUpdatedAt` on `get_actions_run_status` — stale timestamp suggests a worker backlog, not active progress |
| `ENRICH_COMPANY_WITH_STORELEADS` fails | Plan doesn't include Store Leads access (not on BASIC), or company has no domain/website |
| No web search available | Flag as a host requirement; report findings limited to Enginy data + whatever the user supplies |
| `create_an_ai_variable` 409s | AI variable name already exists — reuse or rename |
| User actually wants a battlecard, not customer voice | Redirect to competitor-finder |