Skip to content

iamwaqargulzar/Marketing-Agent-OS / skills/ads

When the user wants to plan, run, or fix paid ads on Google, Meta, and LinkedIn, or asks a judgement call on them: are ads worth it, which channel or budget split, why CPA rose, kill or keep a campaign. End with facts, hypotheses, and missing data; label unavailable inputs MISSING instead of estimating. For ad copy, see ad-creative. For pixels and CAPI, see conversion-tracking. For landing pages, see cro.

FileKindSize
LICENSE.txtmarkdown12.1 KB
NOTICE.mdmarkdown381 B
SKILL.mdskill md28.4 KB
references/abm-playbook.mdmarkdown7.6 KB
references/account-evidence.mdmarkdown3.1 KB
references/ad-copy-templates.mdmarkdown4.7 KB
references/additions.mdmarkdown1.9 KB
references/audience-targeting.mdmarkdown5.9 KB
references/audit-guardrails.mdmarkdown8.0 KB
references/b2b-paid-playbook.mdmarkdown7.8 KB
references/continued.mdmarkdown1.9 KB
references/creative-research-automation.mdmarkdown10.2 KB
references/google-ads-audit-checklist.mdmarkdown12.5 KB
references/google-search-playbook.mdmarkdown10.6 KB
references/linkedin-b2b-playbook.mdmarkdown9.0 KB
references/meta-andromeda-playbook.mdmarkdown8.0 KB
references/meta-decision-system.mdmarkdown15.3 KB
references/operating-check.mdmarkdown7.1 KB
references/operating-review.mdmarkdown1.8 KB
references/payback-period.mdmarkdown6.8 KB
references/platform-setup-checklists.mdmarkdown7.4 KB
references/reading-google-ads-data.mdmarkdown8.5 KB
references/rsa-output-spec.mdmarkdown3.6 KB
references/shared/skills-ad-creative-references-meta-creative-formats.mdmarkdown10.5 KB
references/shared/tools-REGISTRY.mdmarkdown38.2 KB
references/shared/tools-integrations-ga4.mdmarkdown5.8 KB
references/shared/tools-integrations-google-ads.mdmarkdown10.1 KB
references/shared/tools-integrations-linkedin-ads.mdmarkdown5.6 KB
references/shared/tools-integrations-meta-ads.mdmarkdown5.2 KB
references/shared/tools-integrations-segment.mdmarkdown5.7 KB
references/shared/tools-integrations-tiktok-ads.mdmarkdown3.5 KB
references/skill-contract.mdmarkdown2.4 KB

references/shared/tools-integrations-linkedin-ads.md

View on GitHub
# LinkedIn Ads

B2B advertising platform with professional targeting (job title, function, seniority, company, industry, company size) and account-based targeting from uploaded company and contact lists.

API facts below were checked against the [LinkedIn Marketing API docs](https://learn.microsoft.com/en-us/linkedin/marketing/versioning) on 2026-10-07.

## Capabilities

| Integration | Available | Notes |
|-------------|-----------|-------|
| API | ✓ | Versioned Marketing API at `https://api.linkedin.com/rest` (accounts, campaigns, creatives, targeting, audiences, reporting) |
| MCP | - | No official server; Composio offers a LinkedIn toolkit |
| CLI | ✓ | Zero-dependency Node.js CLI (versioned REST API) |
| SDK | - | API-only (community libraries available) |

## Authentication

- **Type**: OAuth 2.0 (3-legged) access token from an app approved for the Marketing API program
- **Header**: `Authorization: Bearer {access_token}`
- **Scopes**: `r_ads`, `rw_ads`, `r_ads_reporting`
- **Env vars**: `LINKEDIN_ACCESS_TOKEN`; optional `LINKEDIN_API_VERSION` (YYYYMM, CLI default `202609`)

## Versioning

- Every call needs a `Linkedin-Version: YYYYMM` header plus `X-Restli-Protocol-Version: 2.0.0`. Requests without a version, or with a sunset version, return an error; the latest version is never applied by default.
- New versions ship monthly and each is supported for at least a year. Version `202510` sunsets on 2026-10-15. Bump the version at least once a year.
- The old unversioned `/v2/adAccountsV2`, `/v2/adCampaignsV2`, `/v2/adCreativesV2`, `/v2/adAnalyticsV2`, and `/v2/audienceCountsV2` paths are replaced by the versioned paths below.
- Rest.li 2.0 syntax: lists are `List(a,b)`, objects are `(key:value)`, and URNs inside query parameters must be URL-encoded (`urn%3Ali%3AsponsoredCampaign%3A123`).

## Common Agent Operations

### Ad accounts

```bash
node tools/clis/linkedin-ads.js accounts list
# GET https://api.linkedin.com/rest/adAccounts?q=search
```

### Campaigns (scoped to an ad account)

```bash
node tools/clis/linkedin-ads.js campaigns list --account-id 507404993 --status ACTIVE
# GET /rest/adAccounts/{accountId}/adCampaigns?q=search&search=(status:(values:List(ACTIVE)))

node tools/clis/linkedin-ads.js campaigns create --account-id 507404993 --campaign-group-id 600 --name "ABM retargeting" --daily-budget 50
# POST /rest/adAccounts/{accountId}/adCampaigns   (created PAUSED; add targeting before activating)

node tools/clis/linkedin-ads.js campaigns update --account-id 507404993 --id 123456 --status PAUSED
# POST /rest/adAccounts/{accountId}/adCampaigns/{campaignId}
# X-RestLi-Method: PARTIAL_UPDATE   body: {"patch":{"$set":{"status":"PAUSED"}}}
```

### Reporting

```bash
node tools/clis/linkedin-ads.js campaigns analytics --id 123456 --start 2026-09-01 --end 2026-09-30
# GET /rest/adAnalytics?q=analytics&pivot=CAMPAIGN&timeGranularity=ALL
#     &dateRange=(start:(year:2026,month:9,day:1),end:(year:2026,month:9,day:30))
#     &campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123456)
#     &fields=impressions,clicks,landingPageClicks,costInLocalCurrency,externalWebsiteConversions,dateRange,pivotValues
```

Request metrics explicitly with `fields` (up to 20); otherwise only impressions and clicks come back. Use `q=statistics` with `pivots=List(...)` for up to three pivots, and the `MEMBER_COMPANY` pivot to see which companies saw an ABM campaign. Professional demographic metrics are approximate and delayed 12–24 hours.

### Creatives

```bash
node tools/clis/linkedin-ads.js creatives list --account-id 507404993 --campaign-id 123456
# GET /rest/adAccounts/{accountId}/creatives?q=criteria&campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123456)
```

### Audience size

```bash
node tools/clis/linkedin-ads.js audiences count \
  --targeting "(include:(and:List((or:(urn%3Ali%3AadTargetingFacet%3Alocations:List(urn%3Ali%3Ageo%3A103644278))))))"
# GET /rest/audienceCounts?q=targetingCriteriaV2&targetingCriteria=...
```

The count is 0 when the audience is under 300 members (privacy threshold). Look up targeting entity URNs with `/rest/adTargetingEntities` (typeahead or by facet).

## Account-Based and Outbound Use

- **Matched Audiences**: upload a target account list (companies) or contact list to retarget the accounts you're prospecting, so your name is familiar before and during outreach. See [Matched Audiences](https://learn.microsoft.com/en-us/linkedin/marketing/matched-audiences/matched-audiences). Test ad accounts can't upload audience segments.
- **Company engagement**: the `MEMBER_COMPANY` reporting pivot shows which target companies are seeing and clicking ads, a warm signal for sales follow-up (see the `ads` skill's ABM playbook).

## Key Metrics

| Metric | Description |
|--------|-------------|
| `impressions` | Ad impressions |
| `clicks` | Total clicks |
| `landingPageClicks` | Clicks to the landing page |
| `costInLocalCurrency` | Spend |
| `externalWebsiteConversions` | Conversions tracked with the Insight Tag or Conversions API |
| `oneClickLeads` | Lead Gen Form submissions |

## Campaign Types

- `SPONSORED_UPDATES` - Sponsored content
- `TEXT_AD` - Text ads
- `SPONSORED_INMAILS` - Message ads
- `DYNAMIC` - Dynamic ads

## Rate Limits

- Limits are set per application and per member and shown in your app's Developer Portal analytics; LinkedIn doesn't publish fixed numbers for most endpoints.
- `adAnalytics` throttles above 45 million metric values per 5-minute window; request only the fields you need. Long URLs can hit `414`; use [query tunneling](https://learn.microsoft.com/en-us/linkedin/shared/references/migrations/query-tunneling-migration).

## Relevant Skills

- ads
- analytics
- attribution
- prospecting (account lists for ABM)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall