MCPInstall

audience-targeting

by hubspotMarketing & SEO

Build a targeted contact segment by filtering on lifecycle, engagement, jobtitle, geography, or firmographics — then export it as JSONL for a campaign or downstream tool.

Installs
1.7K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/hubspot/agent-cli-skills --skill audience-targeting
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads audience-targeting automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Foundation

Read bulk-operations/SKILL.md first — pagination, JSONL piping, destructive-op safety. Reshape recipes in bulk-operations/resources/json-patterns.md. Resource: resources/contact-segmentation-filters.md is the filter-expression cookbook (lifecycle, lead status, email engagement, activity, deals, owner).

Filter syntax cheat sheet

Source of truth: hubspot objects search --help.

  • One --filter flag = one AND group: --filter "lifecyclestage=lead AND !hubspot_owner_id".
  • Multiple --filter flags are OR'd. Use for enum-OR-enum.
  • Operators: =, !=, >, >=, <, <=, ~ (CONTAINS_TOKEN — whole-word, NOT substring), @= (IN), @!= (NOT_IN).
  • HAS_PROPERTY: bare name or name?. NOT_HAS_PROPERTY: !name. Dates: YYYY-MM-DD.
  • Limits (CRM search API): max 5 --filter flags, max 6 conditions per flag, max 18 conditions total. Prefer @= / @!= for enum lists — lifecyclestage@=lead,customer is one condition, --filter "lifecyclestage=lead" --filter "lifecyclestage=customer" is two groups.
  • "None of these, or empty" needs two groups — @!= skips records where the property is unset, so OR in a !name group and repeat the shared conditions in both: --filter "hubspot_owner_id=123 AND lifecyclestage@!=customer,evangelist" --filter "hubspot_owner_id=123 AND !lifecyclestage"

~ gotcha: jobtitle~director matches the token "director", not arbitrary substrings. No regex operator — search broadly, post-filter with jq.

Properties this skill turns on

Full live list: hubspot properties list --type contacts. Enum options: hubspot properties options-list --type contacts <name> | jq -r '.value'. As a fallback (e.g. to see which values are actually in use), read live records: hubspot objects list --type contacts --properties <name> --limit 100 --format json | jq -r '.data[].properties.<name> // empty' | sort -u.

Core fields used here: lifecyclestage, hubspot_owner_id (bare/! for owned/unowned; hubspot owners list for IDs), hs_email_optout (!=true excludes opted-out), hs_email_last_open_date / notes_last_contacted (recency), jobtitle / country / city (string = or ~), num_associated_deals (0 net-new, >=1 has-pipeline).

Firmographics (industry, numberofemployees, annualrevenue) live on companies — see cross-object section.

Common segments

# Recent leads (this quarter, not yet owned)
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND createdate>2026-01-01 AND !hubspot_owner_id" \
  --properties email,firstname,lastname,createdate

# Decision-makers by jobtitle (OR across tokens)
hubspot objects search --type contacts \
  --filter "jobtitle~director" --filter "jobtitle~vp" --filter "jobtitle~chief" \
  --properties email,jobtitle,company

# Engaged but not yet MQL (opened recently, still lead, opted in)
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND hs_email_last_open_date>2026-04-01 AND hs_email_optout!=true" \
  --properties email,firstname,hs_email_last_open_date

# Geographic — US contacts opted in
hubspot objects search --type contacts \
  --filter "country=United States AND hs_email_optout!=true" \
  --properties email,state,city

More patterns (lead status, deals, owners, combined AND/OR) in resources/contact-segmentation-filters.md.

Cross-object: companies-in-industry → their contacts

industry/numberofemployees/annualrevenue live on the company. Build the company set, then traverse — never xargs -I{} hubspot objects get per company. associations list emits {"id":"...","labels":[...],"associationTypes":[...]} — {id} feeds directly into a single batched objects get.

# Step 1: target companies. Industry options are portal-specific — discover with:
#   hubspot objects list --type companies --properties industry --limit 100 --format json \
#   | jq -r '.data[].properties.industry // empty' | sort -u
hubspot objects search --type companies \
  --filter "industry=SOFTWARE AND numberofemployees>=100" \
  --properties name,industry,numberofemployees \
  > target_companies.jsonl

# Step 2: gather association IDs (associations list has no batch --from), then ONE batched
# objects get for all contacts. Page each company with --limit/--after — a company with >100
# associated contacts truncates silently on a single call.
while read -r cid; do
  after=""
  while :; do
    page=$(hubspot associations list --from "companies:$cid" --to contacts --limit 100 ${after:+--after "$after"} --format json)
    echo "$page" | jq -c '.data[]?'
    after=$(echo "$page" | jq -r '.meta.next // empty')
    [ -z "$after" ] && break
  done
done \
  < <(jq -r '.id' target_companies.jsonl) \
| jq -c '{id}' | sort -u \
| hubspot objects get --type contacts --properties email,firstname,jobtitle,hs_email_optout \
> target_contacts.jsonl

# Optional: drop opted-out
jq -c 'select(.properties.hs_email_optout != "true")' target_contacts.jsonl > campaign_audience.jsonl

Saving and reusing a segment

A segment is a JSONL file. Re-use for updates, exports, or re-fetches:

# Save
hubspot objects search --type contacts \
  --filter "lifecyclestage=lead AND hs_email_optout!=true" \
  --properties email,firstname,lastname,jobtitle \
  > segments/opted_in_leads.jsonl

# Assign owner (dry-run first per bulk-operations/SKILL.md)
jq -c '{id, properties:{hubspot_owner_id:"12345"}}' segments/opted_in_leads.jsonl \
| hubspot objects update --type contacts --dry-run

# Re-fetch with different properties later
jq -c '{id}' segments/opted_in_leads.jsonl \
| hubspot objects get --type contacts --properties email,lifecyclestage,hs_lead_status

Destructive ops on a saved segment follow the dry-run → digest → confirm flow in bulk-operations/SKILL.md.

Save as a HubSpot list or view

A JSONL segment is portable, but you can also persist an audience in HubSpot:

  • List — hubspot segments create saves a list; segments get / list inspect it; segments members-list reads members; segments members-add / members-remove manage membership. Use segments update-filters to set a dynamic list's filter criteria.
  • View — hubspot views create --type <t> --name "..." --columns a,b [--filters-file filters.json] [--sort prop:asc] saves a filter set as a reusable object view; views list / get / update / replace-field / delete manage it.
  • Size it first — hubspot objects count --type contacts --filter "..." returns {"object_type":"contacts","total":N} without paging, so you can size an audience before saving or exporting it.

Related read-only signals (context for targeting)

  • hubspot buyer-intent — visiting-company intent signals (read-only). Requires OAuth login (hubspot auth login); service keys are NOT supported.
  • hubspot analytics traffic sources — where sessions/contacts came from, for source-based segmentation.
  • hubspot marketing forms list — form definitions, to segment by which form a contact converted on.

Run each command's --help for the full surface.

Known limits

  • ~ is token-match, not substring. No regex operator.
  • Enum options: hubspot properties options-list --type contacts <name> (fallback: read live records via objects list + jq).
  • associations list has no batch --from, and returns one page (default 100) per call. Loop to gather IDs and page each call with --limit/--after until .meta.next is null, then batch the downstream objects get — otherwise a company with >100 associated contacts truncates silently.
  • For >100 results, use the pagination loop in bulk-operations/SKILL.md.

FAQ

What does the audience-targeting skill do?

Build a targeted contact segment by filtering on lifecycle, engagement, jobtitle, geography, or firmographics — then export it as JSONL for a campaign or downstream tool.

How do I install audience-targeting?

Run npx skills add https://github.com/hubspot/agent-cli-skills --skill audience-targeting in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/audience-targeting/ (personal) or .claude/skills/audience-targeting/ (project).

Which AI agents can use audience-targeting?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is audience-targeting safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains audience-targeting?

It is published by hubspot in hubspot/agent-cli-skills. It has 1,683 recorded installs.

More from hubspot/agent-cli-skills

View all →

ticket-resolution

hubspot/agent-cli-skills

Create, triage, advance, and close HubSpot support tickets — pipeline discovery, contact/company association, priority queues, bulk stage moves, resolution close-out.

2K installs

crm-lookup

hubspot/agent-cli-skills

Find a specific CRM record by ID, email, domain, or name fragment, and traverse associations for the full account picture.

Business & Finance1.8K installs

bulk-operations

hubspot/agent-cli-skills

Foundation patterns for the hubspot CLI — JSONL piping, batch read, pagination, dry-run/digest/confirm for destructive ops, and hubspot history for recovery. Every other skill builds on this one.

1.8K installs

crm-data-quality

hubspot/agent-cli-skills

Find incomplete records, normalize field values in bulk, dedupe with hubspot objects merge, and audit custom properties. Builds on bulk-operations for JSONL piping and dry-run/digest/confirm.

Business & Finance1.8K installs

workflow-automation

hubspot/agent-cli-skills

List, inspect, create, update, and delete HubSpot workflows (v4 flows API) from the hubspot agent CLI, not the hs developer CLI. Classic v3 contact-based workflows are not covered.

Productivity & Automation1.8K installs

deal-management

hubspot/agent-cli-skills

Run the full deal lifecycle from CLI — discover pipelines/stages, qualify MQLs into deals with associations, advance/reassign in bulk, hunt stalled deals, and close.

1.7K installs

Popular marketing & seo skills

View category →

reddit-automation

flowkit-labs/skills

Find Reddit threads where people are genuinely asking for what you offer, then draft short, genuinely helpful replies — disclosing your affiliation honestly and naming your product only when it truly answers the question. Two moves: discovery — scan the right subreddits for real needs (recommendation asks, expressed pain, competitor mentions) and rank the few threads where you can actually help; drafting — write from real experience, respect each community's self-promo rules, and keep a human in the loop to review and post. This markets on Reddit the honest way: contribute value, disclose who you are, never astroturf. Distilled from the playbook behind doany.ai's Reddit agent. Triggers on "find reddit opportunities", "reddit marketing", "reddit automation", "reply on reddit for my product", "reddit community engagement", "reddit lead gen", or any ask to turn Reddit threads into genuine, disclosed marketing replies.

Marketing & SEO1.1M installs

twitter-automation

101-skills/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO880K installs

twitter-automation

magentosh/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO771.7K installs

twitter-automation

qu-skills/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO564.3K installs

product-launch-video

heygen-com/hyperframes

Turn a product or marketing URL, pasted script, or brief into a product launch / promo video — SaaS promos, feature reveals, product demos, app and company launches. Use when the user wants to market, launch, promote, or reveal a product; the default for any commercial URL. Site tours / showcases of a website route here too — the brief carries the show-it-as-is intent. Unclear → /hyperframes.

Marketing & SEO538.7K installs

twitter-automation

skills-shell/superpowers

Automate Twitter/X with posting, engagement, and user management via inference.sh CLI. Apps: x/post-tweet, x/post-create (with media), x/post-like, x/post-retweet, x/dm-send, x/user-follow. Capabilities: post tweets, schedule content, like posts, retweet, send DMs, follow users, get profiles. Use for: social media automation, content scheduling, engagement bots, audience growth, X API. Triggers: twitter api, x api, tweet automation, post to twitter, twitter bot, social media automation, x automation, tweet scheduler, twitter integration, post tweet, twitter post, x post, send tweet

Marketing & SEO453.7K installs