Skip to content
Back to search

ai-marketing-hub-claude-ads

MarketplaceWorks with Claude CodeGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/agricidaniel-claude-ads/badge.svg)](/listings/agricidaniel-claude-ads)

HTML

<a href="/listings/agricidaniel-claude-ads"><img src="/api/listings/agricidaniel-claude-ads/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install (see [Installation](#installation)): `/plugin marketplace add agricidaniel/claude-ads`, then `/plugin install claude-ads@ai-marketing-hub-claude-ads`. 2. Run `/ads setup` and answer a few questions: your business model, goal, main conversion, monthly spend, active platforms, and who approves changes. Never paste API keys or tokens. 3. Bring evidence: an account export (CSV or JSON), screenshots, or a pasted summary with its date range, currency, and timezone. 4. Run `/ads audit google` (or `/ads audit all`). You get a report that states what passed, what failed, and what is missing. 5. Run `/ads report` to see a past run again, and `/ads next` to see the most important blocker.

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="assets/how-it-works-dark.svg"> </picture> </p>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 80 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "ai-marketing-hub-claude-ads",
  3. "owner": {
  4. "name": "AgriciDaniel"
  5. },
  6. "metadata": {
  7. "description": "Claude-first, portable paid-media operations across 12 advertising platforms.",
  8. "version": "2.1.0"
  9. },
  10. "plugins": [
  11. {
  12. "name": "claude-ads",
  13. "source": "./",
  14. "description": "Claude-first, portable paid-media operations across 12 advertising platforms with source-grounded audits, deterministic findings and evidence coverage, lifecycle workflows, versioned JSON reports, and capability-gated account changes.",
  15. "version": "2.1.0",
  16. "author": {
  17. "name": "AgriciDaniel"
  18. },
  19. "homepage": "https://agricidaniel.com/blog/claude-code-ad-agency",
  20. "repository": "https://github.com/AgriciDaniel/claude-ads",
  21. "license": "MIT",
  22. "category": "marketing",
  23. "tags": [
  24. "agent-skills",
  25. "advertising",
  26. "audit",
  27. "google-ads",
  28. "meta-ads",
  29. "linkedin-ads",
  30. "tiktok-ads",
  31. "microsoft-ads",
  32. "apple-ads",
  33. "amazon-ads",
  34. "youtube-ads",
  35. "reddit-ads",
  36. "pinterest-ads",
  37. "snapchat-ads",
  38. "x-ads",
  39. "attribution",
  40. "server-side-tracking",
  41. "retail-media",
  42. "ppc",
  43. "optimization",
  44. "creative-generation",
  45. "multi-host"
  46. ],
  47. "keywords": [
  48. "agent-skills",
  49. "advertising-audit",
  50. "paid-advertising",
  51. "amazon-ads",
  52. "attribution",
  53. "server-side-tracking",
  54. "retail-media",
  55. "claude-code-skill",
  56. "codex-cli",
  57. "cursor",
  58. "multi-host"
  59. ]
  60. },
  61. {
  62. "name": "ads-cockpit",
  63. "source": "./mods/claude-ads-cockpit",
  64. "description": "Optional local Claude Ads workbench for runs, evidence, inputs, comparison and report receipts. Enabled separately.",
  65. "version": "0.1.0",
  66. "author": {
  67. "name": "AI Marketing Hub"
  68. },
  69. "repository": "https://github.com/AgriciDaniel/claude-ads",
  70. "license": "MIT",
  71. "category": "marketing",
  72. "tags": [
  73. "advertising",
  74. "local-workbench",
  75. "evidence",
  76. "mods"
  77. ]
  78. }
  79. ]
  80. }
README.md · README · 375 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="assets/banner-dark.svg">
  4. <img src="assets/banner-light.svg" alt="Claude Ads: every ad account, one command line" width="100%">
  5. </picture>
  6. </p>
  7. # Claude Ads
  8. Claude Ads is a free, open source skill for Claude Code. Give it your ad account data and it tells you what is working, what is broken, and what to fix first, across twelve ad platforms.
  9. It is made for agencies, consultants, and in-house marketing teams. It reads your data and reports back. It does not change your accounts on its own.
  10. > [!NOTE]
  11. > You can get Claude Ads from two places: the **public release** at
  12. > [`AgriciDaniel/claude-ads`](https://github.com/AgriciDaniel/claude-ads)
  13. > (MIT licensed, no membership needed), and the **community mirror** at
  14. > `AI-Marketing-Hub/claude-ads`, where
  15. > [AI Marketing Hub Pro](https://www.skool.com/ai-marketing-hub-pro) members
  16. > get early access and direct collaboration.
  17. ## Quickstart
  18. 1. Install (see [Installation](#installation)): `/plugin marketplace add agricidaniel/claude-ads`, then `/plugin install claude-ads@ai-marketing-hub-claude-ads`.
  19. 2. Run `/ads setup` and answer a few questions: your business model, goal, main conversion, monthly spend, active platforms, and who approves changes. Never paste API keys or tokens.
  20. 3. Bring evidence: an account export (CSV or JSON), screenshots, or a pasted summary with its date range, currency, and timezone.
  21. 4. Run `/ads audit google` (or `/ads audit all`). You get a report that states what passed, what failed, and what is missing.
  22. 5. Run `/ads report` to see a past run again, and `/ads next` to see the most important blocker.
  23. <p align="center">
  24. <picture>
  25. <source media="(prefers-color-scheme: dark)" srcset="assets/how-it-works-dark.svg">
  26. <img src="assets/how-it-works-light.svg" alt="Three steps: tell it about your business, give it your data, then read the audit" width="100%">
  27. </picture>
  28. </p>
  29. ## What you can do
  30. | You want to | Run | You get |
  31. | --- | --- | --- |
  32. | Find out what is wrong | `/ads audit` | A report of passed, failed, and unchecked items, each with its evidence |
  33. | Decide where to spend | `/ads plan` | Channel, budget, measurement, and competitor plans |
  34. | Make ads | `/ads create` | Copy, image, video, and product-photo briefs and assets |
  35. | Keep watch | `/ads monitor` | Checks on pacing, delivery, tracking, ad fatigue, and policy |
  36. | Improve results | `/ads optimize --draft` | Suggested changes, written as drafts |
  37. | Test an idea | `/ads experiment` | A test design, or a readout of a finished test |
  38. ## Platforms
  39. <p align="center">
  40. <picture>
  41. <source media="(prefers-color-scheme: dark)" srcset="assets/platforms-dark.svg">
  42. <img src="assets/platforms-light.svg" alt="Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Apple, Amazon, Reddit, Pinterest, Snapchat and X" width="100%">
  43. </picture>
  44. </p>
  45. Each platform has its own focused skill, audit worker, control reference, and capability declaration. The
  46. [capability manifest](control-plane/manifests/capability-manifest.json) is the authoritative record of what can be read or changed live.
  47. ## Commands
  48. Standalone installs use `/ads`. Claude Code plugins are namespaced and use
  49. `/claude-ads:ads`. Both load the same `ads/SKILL.md` contract.
  50. | Command | What it does |
  51. | --- | --- |
  52. | `/ads setup` | Save your client, account, goal, privacy, and guardrail profile |
  53. | `/ads audit [all\|platform\|scope]` | Run a full or scoped audit backed by evidence |
  54. | `/ads plan` | Build channel, campaign, budget, competitor, and measurement plans |
  55. | `/ads create` | Produce copy, image, video, or product-photo assets |
  56. | `/ads launch --draft` | Draft a campaign change plan without touching the account |
  57. | `/ads monitor` | Review pacing, delivery, tracking, fatigue, policy, and performance |
  58. | `/ads optimize --draft` | Draft evidence-backed improvements |
  59. | `/ads experiment` | Design or read out a controlled test |
  60. | `/ads report` | Render a saved run as Markdown, HTML, or PDF |
  61. | `/ads research refresh` | Refresh platform, policy, API, and benchmark evidence |
  62. | `/ads validate` | Check contracts, runs, capabilities, or release readiness |
  63. | `/ads status`, `/ads next` | Show where things stand and the most important blocker |
  64. Platform shortcuts such as `/ads google`, `/ads meta`, `/ads amazon`, and
  65. `/ads reddit` go straight to that platform's audit.
  66. ## Built to be trusted
  67. <p align="center">
  68. <picture>
  69. <source media="(prefers-color-scheme: dark)" srcset="assets/trust-dark.svg">
  70. <img src="assets/trust-light.svg" alt="Read only by default, evidence for every finding, honest about gaps, and your data stays yours" width="100%">
  71. </picture>
  72. </p>
  73. Every check ends in one of four results: `pass`, `fail`, `unknown`, or `not_applicable`. Unknown is a real answer. It means the data was missing, and it is never guessed.
  74. ## Claude Ads Cockpit (optional)
  75. Cockpit is a separate, optional companion (version 0.1.0, plugin ID `ads-cockpit`). `/ads-cockpit` opens a local workbench where you can look through a finished audit: its status, evidence, missing inputs, comparisons with an earlier run, and report receipts. A built-in demo with synthetic data lets you try it without any account.
  76. Task counts stay separate from health scores, and every scoring profile in the scoring manifest stays disabled. See the [Cockpit guide](docs/cockpit/user-guide.md) and its
  77. [compatibility and acceptance limits](docs/cockpit/compatibility.md).
  78. ## Installation
  79. Claude Code is the canonical runtime. Codex, Gemini, Cursor, Windsurf, Goose,
  80. and compatible Agent Skills hosts can consume the same skill files where their
  81. runtime supports them.
  82. Prefer the host's native plugin flow or a tagged release archive with a verified
  83. SHA-256 checksum. Never pipe a remote installer directly to a shell.
  84. For Claude Code, the native plugin flow is:
  85. ```text
  86. /plugin marketplace add agricidaniel/claude-ads
  87. /plugin install claude-ads@ai-marketing-hub-claude-ads
  88. ```
  89. If you added this marketplace before v2.0.0, Claude Code still holds it under
  90. the stale local alias `agricidaniel-claude-ads`. Remove that alias, then re-add
  91. and install:
  92. ```text
  93. /plugin marketplace remove agricidaniel-claude-ads
  94. /plugin marketplace add agricidaniel/claude-ads
  95. /plugin install claude-ads@ai-marketing-hub-claude-ads
  96. ```
  97. Managed dependencies require CPython 3.11 or 3.12. Linux x86_64 requires glibc
  98. 2.28 or later; musl is unsupported. macOS 11 x86_64/arm64 and Windows amd64
  99. remain declared wheel targets and require native CI qualification.
  100. CI checks the Linux minimum in an AlmaLinux 8 glibc 2.28 container with both
  101. supported interpreters. This checks Python wheels and the managed CLI lifecycle;
  102. browser payloads and PDF system libraries require separate host verification.
  103. Or install from a local clone of the public repository:
  104. ```bash
  105. git clone https://github.com/AgriciDaniel/claude-ads.git
  106. cd claude-ads
  107. bash install.sh --source=local
  108. ```
  109. Select another standalone host explicitly:
  110. ```bash
  111. bash install.sh --target=codex --source=local
  112. bash install.sh --target=gemini --source=local --no-deps
  113. ```
  114. > [!WARNING]
  115. > **EXPERIMENTAL:** Only Claude Code is verified. The Codex, Gemini, Cursor,
  116. > Windsurf, and Goose targets install the same skill artifacts under each host's
  117. > expected directory, but that host's runtime conventions may differ. Confirm the
  118. > result in your host, and pin the install locations with `--skill-dir` and
  119. > `--agent-dir` if the auto-detected paths are wrong. The installer creates the
  120. > managed Python environment only for the `claude` and `codex` targets.
  121. `--source=git` (the default when the installer is run outside a checkout) clones
  122. the default branch HEAD, which is unpinned and is not a verified release. Prefer
  123. `--source=local` from a checkout you have reviewed, or a release archive.
  124. To pin a git install, add the opt-in `--ref` option (PowerShell: `-Ref`) with a
  125. tag, branch, or commit. It is valid only with `--source=git`. The installer
  126. validates the value strictly, checks it out detached, prints the resolved full
  127. commit SHA, and fails before installing anything if the ref does not resolve:
  128. ```bash
  129. bash install.sh --source=git --ref=v2.1.0
  130. ```
  131. A git ref is not a checksum-verified release, and nothing here is signed. A
  132. release zip checked with the `SHA256SUMS` recipe below remains the verified path.
  133. PowerShell uses the same managed ownership model:
  134. ```powershell
  135. git clone https://github.com/AgriciDaniel/claude-ads.git
  136. Set-Location claude-ads
  137. .\install.ps1 -Source local
  138. ```
  139. Verify a release archive before using it. Each GitHub release publishes the zip,
  140. `release-manifest.json`, `sbom.cdx.json`, and a `SHA256SUMS` file. Releases are
  141. checksummed, not signed, so a checksum confirms the files match what the release
  142. published and is not an independent proof of origin. Download all four files into
  143. one empty directory, then run:
  144. ```bash
  145. sha256sum -c SHA256SUMS # macOS: shasum -a 256 -c SHA256SUMS
  146. ```
  147. Every line must report `OK` before you unzip and run `bash install.sh --source=local`
  148. from the extracted folder.
  149. Managed dependencies support CPython 3.11 and 3.12 on the declared Linux,
  150. macOS, and Windows wheel matrix. Unsupported interpreters fail before the
  151. destination changes. Use `--no-deps` or `-NoDeps` for a skill-only install.
  152. Browser capture requires an operator-installed Playwright browser payload. PDF
  153. rendering requires the host's WeasyPrint and Pango system libraries. These are
  154. documented in the
  155. [external runtime dependency manifest](control-plane/manifests/external-runtime-dependencies.json).
  156. Uninstall only manifest-owned files:
  157. ```bash
  158. bash uninstall.sh --target=claude
  159. ```
  160. The PowerShell equivalent is `uninstall.ps1`.
  161. The Bash and PowerShell skill installers do not enable or load Cockpit. Its
  162. optional plugin has its own marketplace entry and curated archive, and requires
  163. an explicitly bound trusted core and Python executable. Installing the main
  164. skill alone preserves the existing experience.
  165. ## Project status
  166. > [!IMPORTANT]
  167. > **Status: development candidate.** Claude Ads is not release-ready until every
  168. > gate in [control-plane/RELEASE_REQUIREMENTS.md](control-plane/RELEASE_REQUIREMENTS.md)
  169. > passes in a fresh verification context.
  170. >
  171. > - All twelve account-health scoring profiles are disabled, so no health score is
  172. > produced. Audits report findings, unknowns, and evidence coverage instead.
  173. > - The Cockpit companion is optional and not yet natively accepted; see its
  174. > [compatibility and acceptance limits](docs/cockpit/compatibility.md).
  175. > - Account changes stay drafts unless the full mutation gate passes.
  176. ## For engineers and contributors
  177. <details>
  178. <summary>How it is built, how scoring works, safety gates, and how to run the tests</summary>
  179. ### Architecture
  180. One conductor owns scope, policy, aggregation, and final artifacts. Workers
  181. analyze bounded slices and return schema-valid findings. Required-worker failure
  182. makes the run partial. It is never silently presented as a complete audit.
  183. Agent definitions omit model pins. The host or invocation selects the model;
  184. Claude Code inherits the main conversation's model when no higher-priority
  185. selection applies. See the [official subagent model documentation](https://code.claude.com/docs/en/sub-agents#choose-a-model).
  186. The canonical result is versioned JSON. Markdown, HTML, and PDF are renderings
  187. of the same validated run bundle.
  188. ### Scoring and evidence
  189. Controls use `pass`, `fail`, `unknown`, or `not_applicable`.
  190. - Health, evidence coverage, regulatory exposure, and opportunities stay separate.
  191. - Unknown controls reduce evidence coverage without changing known health.
  192. - Coverage of 80% or more is graded, 60 to 79% is provisional, and below 60%
  193. is insufficient evidence.
  194. - Optional, beta, premium, unavailable, and ineligible features stay unscored.
  195. - A disabled or unapproved platform profile produces no health score.
  196. - A failed platform is excluded from portfolio scoring and makes the run partial.
  197. See the [scoring reference](ads/references/scoring-system.md) and production
  198. implementation in `claude_ads_core/scoring.py`.
  199. ### Account safety
  200. All adapters are read-only by default. Applying a change requires:
  201. 1. A tested and enabled capability for the exact operation.
  202. 2. Explicit account and object IDs.
  203. 3. A human-readable before and after diff with blast radius.
  204. 4. Owner approval within account-defined ceilings.
  205. 5. An idempotency key, audit destination, rollback, and verification window.
  206. 6. Verification that remote state still matches the mutation precondition.
  207. Missing ceilings mean no write. Permanent deletion is not supported in v2.
  208. Credentials belong in environment variables, an OS keychain, or an approved
  209. secret manager. They never belong in the repository, profiles, reports, or logs.
  210. ### Evidence and release controls
  211. The public-safe `control-plane/` records product boundaries, dated sources,
  212. claims, capabilities, safety rules, privacy rules, ecosystem decisions, and
  213. release requirements.
  214. - No source means no current platform claim.
  215. - No implementation, fixture, and test means no capability claim.
  216. - No approval and rollback means no account mutation.
  217. - No independent verification means no release.
  218. See the [release requirements](control-plane/RELEASE_REQUIREMENTS.md) and
  219. [publishing policy](control-plane/PUBLISHING_POLICY.md).
  220. The MIT public distribution and private development/community repository have
  221. separate publication boundaries. Local verification does not authorize a new
  222. release, a visibility change, or publication of private review evidence.
  223. Runtime commands locate policy beside the source checkout or in the curated
  224. standalone installation. Use `--policy-root ROOT` for another explicit policy
  225. location. `status` and `next` retain `--root ROOT` as a compatibility alias;
  226. commands never select policy from an unrelated working directory. Repository
  227. audit and release helpers require a source checkout.
  228. Public scoring uses the canonical registry. Legacy control and category-weight
  229. inputs are accepted only when they exactly match approved policy. Report status
  230. and rendering reject fabricated health or incompatible historical bundles;
  231. regenerate those bundles using the current registry. All twelve production
  232. health profiles remain disabled, returning null health and zero approved
  233. coverage until a severity and weight policy is approved.
  234. ### Development
  235. Create a virtual environment and run the complete suite:
  236. ```bash
  237. python3.12 -m venv .venv
  238. .venv/bin/python -m pip install --no-deps -e .
  239. .venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements.lock
  240. .venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.lock
  241. .venv/bin/python -m pip install --require-hashes --only-binary=:all: -r .github/requirements-schema-tests.lock
  242. .venv/bin/python -m pip check
  243. .venv/bin/python -m pytest -q
  244. ```
  245. Useful focused checks:
  246. ```bash
  247. python -m claude_ads_core --version
  248. python -m claude_ads_core validate finding path/to/finding.json
  249. bash -n install.sh uninstall.sh
  250. ```
  251. ### Reference documents
  252. - [Cockpit implementation contract](docs/cockpit/implementation-contract.md): the integration boundary for the optional companion.
  253. - [Requirement index](control-plane/REQUIREMENT_INDEX.md): the stable requirement IDs the tracker ledger maps to.
  254. - [Control schema migration, v1 to v2](control-plane/migrations/control-schemas-v1-to-v2.md): what changed in the control schemas.
  255. ### Repository map
  256. ```text
  257. ads/ main skill, interface metadata, and shared references
  258. skills/ platform and lifecycle skills
  259. agents/ platform, cross-platform, research, and verifier workers
  260. claude_ads_core/ typed contracts, adapters, validation, and scoring
  261. control-plane/ evidence, capability, safety, maturity, and release state
  262. scripts/ browser, creative, reporting, and release helpers
  263. evals/ routing and behavioral evaluation cases
  264. tests/ deterministic, security, installer, and adapter tests
  265. ```
  266. </details>
  267. ## Contributing
  268. Found a problem or have an idea? See [CONTRIBUTING.md](CONTRIBUTING.md).
  269. Thank you to everyone who has reported issues and proposed fixes: [@aleps001](https://github.com/aleps001), [@bq9kpv2h98-max](https://github.com/bq9kpv2h98-max), [@haruntekin89](https://github.com/haruntekin89), [@reikjarloekl](https://github.com/reikjarloekl), [@osilova](https://github.com/osilova), [@Nath24591](https://github.com/Nath24591), [@sistemasond-ux](https://github.com/sistemasond-ux), [@principisimone-sys](https://github.com/principisimone-sys), [@HarKro753](https://github.com/HarKro753), [@plcosta](https://github.com/plcosta), [@ulises2k](https://github.com/ulises2k), [@kutzki](https://github.com/kutzki), [@SamaEducationalCo](https://github.com/SamaEducationalCo), [@Bortlesboat](https://github.com/Bortlesboat), [@gabbyran2026-gif](https://github.com/gabbyran2026-gif), [@AbundantASG](https://github.com/AbundantASG), [@hendrixfreire](https://github.com/hendrixfreire), [@josefresco](https://github.com/josefresco), [@dead-simba](https://github.com/dead-simba), [@c6zks4gssn-droid](https://github.com/c6zks4gssn-droid), [@kershrita](https://github.com/kershrita), [@popey](https://github.com/popey), [@xiaolai](https://github.com/xiaolai), [@seojcarlos](https://github.com/seojcarlos), [@botbikamordehai2-sketch](https://github.com/botbikamordehai2-sketch). What each person contributed is listed in [CONTRIBUTING.md](CONTRIBUTING.md#contributors-and-acknowledgments).
  270. ## Privacy
  271. Client data, raw private research, captured prompts, credentials, account
  272. exports, and agent transcripts never belong in Git history, reports, or release
  273. archives. Keep credentials in environment variables, an OS keychain, or an
  274. approved secret manager.
  275. ## License
  276. Original Claude Ads code and documentation are available under the MIT License.
  277. Third-party APIs, trademarks, documentation, and cited artifacts remain subject
  278. to their own terms. Review the [source ledger](control-plane/manifests/source-ledger.json)
  279. and [third-party notices](THIRD_PARTY_NOTICES.md) before importing external work.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.