Skip to content
Get packs

Guide · Open source

How to use claude-ads: install, run audits and read reports

Updated · written with AI from the project's own documentation and checked against our catalogue data

Claude Ads is a free, MIT-licensed skill for Claude Code. You give it ad account data such as exports, screenshots, or summaries, and it reports what is working, what is broken, and what to fix first across twelve ad platforms. This guide shows you how to install it, run your first audit, and read the results.

Claude AdsAgriciDaniel/claude-ads · ★ 10.7k · MIT

Quick start

  1. 1Add the marketplace. In Claude Code, run /plugin marketplace add agricidaniel/claude-ads.
  2. 2Install the plugin. Run /plugin install claude-ads@ai-marketing-hub-claude-ads.
  3. 3Set up your profile. Run /ads setup and answer questions about your goal, spend, platforms and who approves changes.
  4. 4Gather evidence. Prepare an account export (CSV or JSON), screenshots, or a summary with its date range, currency, and timezone.
  5. 5Run the audit. Run /ads audit google or /ads audit all to get a report of passed, failed, and missing items.
  6. 6Read the next blocker. Run /ads next to see the most important blocker, and /ads report to review a saved run.

Install Claude Ads in Claude Code

Claude Code is the canonical runtime for Claude Ads. Install it with the native plugin flow: first add the marketplace, then install the plugin.

Managed dependencies require CPython 3.11 or 3.12. Linux x86_64 requires glibc 2.28 or later; musl is unsupported.

  • If you added this marketplace before v2.0.0, remove the stale alias agricidaniel-claude-ads, then re-add and install.
/plugin marketplace add agricidaniel/claude-ads /plugin install claude-ads@ai-marketing-hub-claude-ads

Set up your business profile with /ads setup

Run /ads setup and answer a few questions: your business model, goal, main conversion, monthly spend, active platforms, and who approves changes. The profile saves your client, account, goal, privacy, and guardrail settings.

Never paste API keys or tokens into the setup.

/ads setup

Bring evidence for the audit

Claude Ads works from the data you provide. Use an account export (CSV or JSON), screenshots, or a pasted summary. Include the date range, currency, and timezone so the numbers can be read correctly.

  • Account export in CSV or JSON
  • Screenshots of the account
  • Pasted summary with its date range, currency, and timezone

Run an audit and read the results

Run an audit for one platform or for all of them. The report states what passed, what failed, and what is missing. Platform shortcuts such as /ads google, /ads meta, /ads amazon, and /ads reddit go straight to that platform's audit.

Every check ends in one of four results: pass, fail, unknown, or not_applicable. Unknown means the data was missing and is never guessed, so treat it as a gap to fill, not a clean bill of health.

  • pass: the check was met by the evidence you gave
  • fail: the evidence shows a problem
  • unknown: the data was missing
  • not_applicable: the check does not apply
/ads audit google /ads audit all

Review, save and revisit reports

Use /ads report to render a saved run as Markdown, HTML, or PDF. Use /ads next to see the most important blocker, and /ads status to see where things stand. The README says reports can be saved as versioned JSON, Markdown, HTML, or PDF.

Claude Ads reads your data and reports back. It does not change your accounts on its own. Changes are drafted with flags such as --draft rather than applied live.

/ads report /ads next /ads status

Other commands you can use

Beyond auditing, the skill covers planning, creating assets, monitoring, drafting optimizations, and designing experiments. Each command that changes things is written as a draft.

  • /ads plan: channel, campaign, budget, competitor, and measurement plans
  • /ads create: copy, image, video, or product-photo briefs and assets
  • /ads monitor: pacing, delivery, tracking, fatigue, and policy checks
  • /ads optimize --draft: suggested changes written as drafts
  • /ads experiment: a test design or readout of a finished test

What people use it for

  • An agency reviewing several client ad accounts with a consistent audit format
  • An in-house marketing team running a structured audit of paid campaigns across platforms
  • A consultant producing Markdown, HTML, or PDF reports from saved runs
  • A marketer drafting optimization suggestions with /ads optimize --draft for human review

Frequently asked questions

Is claude-ads free?

Yes. The README describes Claude Ads as a free, open source skill released under the MIT licence. The public release on GitHub needs no membership.

What do I need to run claude-ads?

You need Claude Code and CPython 3.11 or 3.12. On Linux x86_64 you need glibc 2.28 or later, since musl is unsupported.

Does claude-ads change my ad account automatically?

No. The README says it reads your data and reports back, and it does not change your accounts on its own. Suggested changes are written as drafts.

Which ad platforms does claude-ads support?

The README lists twelve platforms: Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, Amazon, Reddit, Pinterest, Snapchat and X.

Can I use claude-ads outside Claude Code?

The README says Claude Code is the canonical runtime and the only verified host. Codex, Gemini, Cursor, Windsurf and Goose targets are marked experimental, so confirm results in your host before relying on them.

What does unknown mean in an audit report?

Unknown means the data needed for that check was missing. Claude Ads does not guess, so an unknown item is a gap you should fill with more evidence.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Claude Ads suits agencies, consultants and in-house teams who already use Claude Code and want structured, evidence-based reviews of several ad accounts. It is a poor fit if you want the tool to make live changes to accounts automatically, or if you do not use Claude Code, since the README marks other hosts as experimental.

Install options & downloads