Marketing skills — build targeting lists & processes from fcr-dashboard

What this is. FCR provides marketing with a process and a binding so they can build their own targeting lists and processes as Claude Code skills, from this repo. We do not dictate what they build or how they model their data — marketing own their own BigQuery dataset and schema, their Airtable bases, and whatever workflows they want, called via n8n.

We deliberately did not take the separate service-bound-worker path in extending-with-workers.md. There is no fcr-marketing-api worker. Skills read the data lake directly and route every write through n8n.

The split: what FCR provides vs what marketing owns

The one rule that protects everyone: writes go through n8n, and shared/production systems are read-only to experiments. fcr_operations, SUPERSET_MASTER, etc. are what the advisor, HubSpot card, and dashboard read live — never write them. Marketing's own dataset and Airtable are theirs to shape however they like.

Content-admin curation (the one sanctioned non-n8n write path)

There is one deliberate exception to "writes go through n8n": the three content-admin skills that let marketing own the knowledge the advisor reads. These write through governed worker endpoints (x-api-key), not n8n — the same pattern as am-email-templates and case-studies-reindex. This is content curation, not targeting-list data, and each endpoint owns its own validated write + soft-delete + audit, so the same guardrails (confirm-first, --dry-run, reversible delete, audit trail) hold without n8n plumbing.

Every write is confirmed first, supports --dry-run, soft-deletes (re-adding the same id restores it), and writes a row to fcr_operations.marketing_kb_audit. De-index = soft-delete the row and deleteByIds the vectors.

The boundary still holds for everything else: targeting-list data writes (deals, notes, static lists, marketing's own BQ dataset) still go n8n-only via the registry — a skill must never call /dashboard-bq-admin, api.hubapi.com, or Airtable directly. The content-admin endpoints above are the only worker write surface a marketing skill may call, and only for the three corpora named here.

The binding

SKILL.md (Claude Code, in this repo)
  ├─ READ  → fcr-dashboard-api  (x-api-key)         reads only, direct
  └─ WRITE → n8n webhook        (x-api-key)         resolved via the action registry
               ├─ FCR cloud n8n: shared, governed actions (HubSpot deals/notes/lists)
               └─ marketing's community n8n: their own actions
                     ↓
            their BigQuery dataset (their schema) · their Airtable · HubSpot (shared)

A skill never writes a database or calls HubSpot/Airtable directly — it POSTs to an n8n webhook that owns the write. That keeps powerful credentials in n8n, and means a buggy experiment can't corrupt the data reps read live.

The write contract

Every write is a POST with this envelope (header x-api-key):

{
  "action": "<action name from the registry>",
  "idempotency_key": "<stable hash of the inputs>",
  "dry_run": false,
  "source": { "skill": "<skill-name>", "actor": "<email>", "run_id": "<uuid>" },
  "payload": { "...action-specific..." }
}

Response (synchronous — returned on the same call):

{ "ok": true, "action": "...", "deduped": false,
  "result": { "ids": ["..."], "hubspot_url": "...", "count": 1 } }

or { "ok": false, "action": "...", "error": "...", "status": 4xx }.

• idempotency_key — recommended on every write. Compute it deterministically from the inputs (e.g. sha1("create-deal|" + business_key + "|" + list_name)). If the workflow records keys (the recommended pattern — see below), a re-run returns the prior result with deduped:true instead of writing twice. Re-running a list is then safe.
• dry_run:true — the workflow echoes what it would do and performs no side effect. Always offer a dry run before the first live write.

The action registry (FCR vs your community n8n)

Skills don't hard-code webhook URLs — they read .claude/skills/_marketing/n8n-registry.json:

{
  "tenants": {
    "fcr":       { "webhook_base": "https://fcrmedia.app.n8n.cloud/webhook", "key_env": "VITE_N8N_API_KEY" },
    "community": { "webhook_base": "<your-box>/webhook",                     "key_env": "MARKETING_N8N_KEY" }
  },
  "actions": {
    "create-deal":       { "tenant": "fcr", "path": "marketing-create-deal" },       // shared, governed
    "note-on-deal":      { "tenant": "fcr", "path": "marketing-note-on-deal" },      // shared, governed
    "build-static-list": { "tenant": "fcr", "path": "marketing-build-static-list" }, // shared, governed
    "bq-append":         { "tenant": "fcr", "path": "marketing-bq-append" }          // writes to YOUR dataset
    // add your own, e.g.:
    // "airtable-sync":  { "tenant": "community", "path": "marketing-airtable-sync" }
  }
}

The skill resolves action → tenant → webhook_base, reads the tenant's key_env line from .env.local, and POSTs. x-api-key is the header on every call.

Shared, governed actions (FCR-provided)

HubSpot is the company CRM, so writes to it run through FCR-owned workflows on the FCR cloud tenant, with HubSpot scopes managed centrally:

• create-deal — create one deal per target (needs crm.objects.deals.write).
• note-on-deal — note on an existing deal (needs crm.objects.contacts.write + deals.write).
• build-static-list — create a MANUAL list + add members (needs crm.lists.write).

If one of these returns 403, the n8n HubSpot credential is missing a scope and needs re-authorizing — flag it to the dashboard owner.

Your own actions (marketing-owned)

Anything that touches your systems is yours to build, typically on your community n8n box:

• BigQuery → your dataset. You create and own the dataset and schema. A starter bq-append action streams rows into a table you name; the workflow allowlists your dataset so it can never touch fcr_operations. The columns are whatever you defined.
• Airtable. You have Airtable bases — wire an n8n workflow (Airtable node) and add an action (e.g. airtable-sync) to the registry under "tenant": "community".
• Anything else (ESP, Slack, sheets) — same pattern: build the workflow, register the action, call it from a skill with the envelope.

Register a workflow on your own community n8n

1. Build the workflow on your self-hosted n8n Community box: Webhook (POST) node + header-auth credential + whatever it does (BigQuery / Airtable / …).
2. In the registry, set tenants.community.webhook_base to your box's /webhook base, and add an action with "tenant": "community" and the webhook path.
3. Add the box's key to .env.local as MARKETING_N8N_KEY. Never reuse the FCR key (VITE_N8N_API_KEY) for the community box.
4. Secure the box — it holds real credentials. Put it behind Cloudflare Access / HTTPS, never a bare public port (see extending-with-workers.md §3).

Your BigQuery — you create it, you own the schema

Marketing create and own their dataset (e.g. marketing_ops) once, and define whatever tables/schema they need — FCR doesn't dictate the data model. Two habits worth keeping:

• Write only to your dataset. Give the n8n BigQuery credential dataEditor on your dataset (and read-only elsewhere), so an accident can't reach production tables.
• Make state tables idempotency-friendly. For anything you don't want processed twice (sends, deal creation), keep a unique key + created_at/status so a re-run dedupes. This is what makes the idempotency_key above actually safe.

Data rules to respect

Marketing skills inherit the rules in ../CLAUDE.md (see Data Rules and Marketing Write Rules). The ones that bite list selection most:

• Ads spend = retail (what the client pays FCR). Never "media spend".
• KEYWORD_INTELLIGENCE / CATEGORY_BENCHMARKS are cumulative, not monthly.
• Golden Pages subscriber counts ≠ FCR clients — use them for competitive density.
• Citation URLs: every created HubSpot deal/list you report must be a clickable link, never a bare ID.

Checklist — adding a new marketing skill

1. Clone the template: copy .claude/skills/marketing-list/ to .claude/skills/<your-skill>/ and mirror to .agents/skills/<your-skill>/ (keep both identical).
2. Set frontmatter: name, description, argument-hint, user-invocable: true.
3. Write the source query — reads only, via dashboard API endpoints.
4. Pick the writes — shared HubSpot actions and/or your own (BQ/Airtable) actions.
5. Keep the confirm step + --dry-run — never write without showing the user first.
6. Add idempotency_key to every write.
7. Test each path end-to-end: dry-run → live → re-run (expect deduped).
8. For HubSpot actions, confirm scopes are granted on the n8n credential (else 403).

Compliance

If a process ends in outreach email, it needs consent + unsubscribe (GDPR) and SPF/DKIM on the sending domain — settle before the first send.

Related: extending-with-workers.md (broader team-environment pattern; the separate-worker path is not used here), n8n-workflows.md, the template skill .claude/skills/marketing-list/SKILL.md, the registry .claude/skills/_marketing/n8n-registry.json.

FCR Dashboard documentation · generated from docs/ · keep counts verified, not guessed.