{
  "markdown": "<p align=\"center\">\n  <img src=\"assets/banner.svg\" alt=\"Claude Ads, Claude-first paid-media operations across twelve advertising platforms\" width=\"100%\">\n</p>\n\n# Claude Ads\n\nClaude-first, portable paid-media operations for agencies, consultants, and\nin-house performance teams.\n\nClaude Ads turns authorized exports or account reads into source-grounded\naudits, plans, creative workflows, experiments, monitoring, and reports. It is\nread-only by default. Live changes stay disabled until the exact platform and\noperation pass approval, idempotency, verification, audit, and rollback gates.\n\n> [!NOTE]\n> Claude Ads ships from two homes: the **public release** at\n> [`AgriciDaniel/claude-ads`](https://github.com/AgriciDaniel/claude-ads)\n> (MIT, no membership required) and the **community mirror** at\n> `AI-Marketing-Hub/claude-ads`, where\n> [AI Marketing Hub Pro](https://www.skool.com/ai-marketing-hub-pro) members\n> get early access and direct collaboration.\n\n<p align=\"center\">\n  <img src=\"assets/diagrams/how-it-works.svg\" alt=\"Validated inputs flow through bounded workers into schema-valid findings and deterministic reports\" width=\"100%\">\n</p>\n\n## What it does\n\n- Audits paid-media accounts with dated evidence and explicit confidence.\n- Plans campaigns, channels, budgets, measurement, and experiments.\n- Creates copy, image, video, and product-photo briefs and assets.\n- Monitors pacing, delivery, tracking, fatigue, policy, and performance.\n- Produces versioned JSON, then renders Markdown, HTML, and optional PDF.\n- Drafts safe account changes without applying them by default.\n- Reports missing data, stale sources, contradictions, and partial failures.\n\n## Platforms\n\n<p align=\"center\">\n  <img src=\"assets/diagrams/platform-coverage.svg\" alt=\"Twelve first-class paid-advertising platform surfaces\" width=\"100%\">\n</p>\n\n| Segment | Platforms |\n| --- | --- |\n| Search, video, and social | Google Ads, Meta Ads, YouTube Ads, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Reddit Ads, Snapchat Ads, X Ads |\n| Commerce and retail media | Apple Ads, Amazon Ads, Pinterest Ads |\n\nEach platform has a focused skill, audit worker, control reference, capability\ndeclaration, and testable routing surface. The\n[capability manifest](control-plane/manifests/capability-manifest.json) is the\nauthoritative record for live reads and writes.\n\n## Commands\n\nStandalone installs use `/ads`. Claude Code plugins are namespaced and use\n`/claude-ads:ads`. Both load the same `ads/SKILL.md` contract.\n\n| Command | Outcome |\n| --- | --- |\n| `/ads setup` | Create the client, account, KPI, privacy, and guardrail profile |\n| `/ads audit [all\\|platform\\|scope]` | Run a complete or scoped evidence-backed audit |\n| `/ads plan` | Build channel, campaign, budget, competitor, and measurement plans |\n| `/ads create` | Produce copy, image, video, or product-photo assets |\n| `/ads launch --draft` | Draft a campaign mutation plan without changing the account |\n| `/ads monitor` | Review pacing, delivery, tracking, fatigue, policy, and performance |\n| `/ads optimize --draft` | Draft evidence-backed optimization changes |\n| `/ads experiment` | Design or read out a controlled test |\n| `/ads report` | Render a validated JSON run bundle |\n| `/ads research refresh` | Refresh platform, policy, API, benchmark, and ecosystem evidence |\n| `/ads validate` | Validate contracts, runs, capabilities, maturity, or release readiness |\n| `/ads status`, `/ads next` | Show current status and the highest-priority blocker |\n\nPlatform shortcuts such as `/ads google`, `/ads meta`, `/ads amazon`, and\n`/ads reddit` route to the matching platform audit.\n\n## Demo\n\n<p align=\"center\">\n  <img src=\"assets/demo.gif\" alt=\"Claude Ads command discovery inside Claude Code\" width=\"800\">\n</p>\n\nThe GIF shows the original command-discovery experience. The v2 command table\nabove and the platform table are current and authoritative.\n\n## Installation\n\nClaude Code is the canonical runtime. Codex, Gemini, Cursor, Windsurf, Goose,\nand compatible Agent Skills hosts can consume the same skill files where their\nruntime supports them.\n\nPrefer the host's native plugin flow or a tagged release archive with a verified\nSHA-256 checksum. Never pipe a remote installer directly to a shell.\n\nFor Claude Code, the native plugin flow is:\n\n```text\n/plugin marketplace add AgriciDaniel/claude-ads\n/plugin install claude-ads@ai-marketing-hub-claude-ads\n```\n\nOr install from a local clone of the public repository:\n\n```bash\ngit clone https://github.com/AgriciDaniel/claude-ads.git\ncd claude-ads\nbash install.sh --source=local\n```\n\nSelect another standalone host explicitly:\n\n```bash\nbash install.sh --target=codex --source=local\nbash install.sh --target=gemini --source=local --no-deps\n```\n\nPowerShell uses the same managed ownership model:\n\n```powershell\ngit clone https://github.com/AgriciDaniel/claude-ads.git\nSet-Location claude-ads\n.\\install.ps1 -Source local\n```\n\nManaged dependencies support CPython 3.11 and 3.12 on the declared Linux,\nmacOS, and Windows wheel matrix. Unsupported interpreters fail before the\ndestination changes. Use `--no-deps` or `-NoDeps` for a skill-only install.\n\nBrowser capture requires an operator-installed Playwright browser payload. PDF\nrendering requires the host's WeasyPrint and Pango system libraries. These are\ndocumented in the\n[external runtime dependency manifest](control-plane/manifests/external-runtime-dependencies.json).\n\nUninstall only manifest-owned files:\n\n```bash\nbash uninstall.sh --target=claude\n```\n\nThe PowerShell equivalent is `uninstall.ps1`.\n\n## Architecture\n\n<p align=\"center\">\n  <img src=\"assets/diagrams/architecture.svg\" alt=\"One conductor dispatches platform and cross-platform workers, then validates and renders a canonical JSON bundle\" width=\"100%\">\n</p>\n\nOne conductor owns scope, policy, aggregation, and final artifacts. Workers\nanalyze bounded slices and return schema-valid findings. Required-worker failure\nmakes the run partial. It is never silently presented as a complete audit.\n\nThe canonical result is versioned JSON. Markdown, HTML, and PDF are renderings\nof the same validated run bundle.\n\n## Scoring and evidence\n\n<p align=\"center\">\n  <img src=\"assets/diagrams/ads-health-score.svg\" alt=\"Health and evidence coverage remain separate; scoring requires an approved platform profile\" width=\"100%\">\n</p>\n\nControls use `pass`, `fail`, `unknown`, or `not_applicable`.\n\n- Health, evidence coverage, regulatory exposure, and opportunities stay separate.\n- Unknown controls reduce evidence coverage without changing known health.\n- Coverage of 80% or more is graded, 60 to 79% is provisional, and below 60%\n  is insufficient evidence.\n- Optional, beta, premium, unavailable, and ineligible features stay unscored.\n- A disabled or unapproved platform profile produces no health score.\n- A failed platform is excluded from portfolio scoring and makes the run partial.\n\nSee the [scoring reference](ads/references/scoring-system.md) and production\nimplementation in `claude_ads_core/scoring.py`.\n\n## Account safety\n\nAll adapters are read-only by default. Applying a change requires:\n\n1. A tested and enabled capability for the exact operation.\n2. Explicit account and object IDs.\n3. A human-readable before and after diff with blast radius.\n4. Owner approval within account-defined ceilings.\n5. An idempotency key, audit destination, rollback, and verification window.\n6. Verification that remote state still matches the mutation precondition.\n\nMissing ceilings mean no write. Permanent deletion is not supported in v2.\nCredentials belong in environment variables, an OS keychain, or an approved\nsecret manager. They never belong in the repository, profiles, reports, or logs.\n\n## Evidence and release controls\n\nThe public-safe `control-plane/` records product boundaries, dated sources,\nclaims, capabilities, safety rules, privacy rules, ecosystem decisions, and\nrelease requirements.\n\n- No source means no current platform claim.\n- No implementation, fixture, and test means no capability claim.\n- No approval and rollback means no account mutation.\n- No independent verification means no release.\n\nSee the [release requirements](control-plane/RELEASE_REQUIREMENTS.md) and\n[publishing policy](control-plane/PUBLISHING_POLICY.md).\n\n## Development\n\nCreate a virtual environment and run the complete suite:\n\n```bash\npython3.12 -m venv .venv\n.venv/bin/python -m pip install --no-deps -e .\n.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements.lock\n.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.lock\n.venv/bin/python -m pip check\n.venv/bin/python -m pytest -q\n```\n\nUseful focused checks:\n\n```bash\npython -m claude_ads_core --version\npython -m claude_ads_core validate finding path/to/finding.json\nbash -n install.sh uninstall.sh\n```\n\n## Repository map\n\n```text\nads/                  main skill, interface metadata, and shared references\nskills/               platform and lifecycle skills\nagents/               platform, cross-platform, research, and verifier workers\nclaude_ads_core/      typed contracts, adapters, validation, and scoring\ncontrol-plane/        evidence, capability, safety, maturity, and release state\nscripts/              browser, creative, reporting, and release helpers\nevals/                routing and behavioral evaluation cases\ntests/                deterministic, security, installer, and adapter tests\n```\n\n## Privacy\n\nClient data, raw private research, captured prompts, credentials, account\nexports, and agent transcripts must never enter Git history, reports, or release\narchives. Keep credentials in environment variables, an OS keychain, or an\napproved secret manager.\n\n## License\n\nOriginal Claude Ads code and documentation are available under the MIT License.\nThird-party APIs, trademarks, documentation, and cited artifacts remain subject\nto their own terms. Review the [source ledger](control-plane/manifests/source-ledger.json)\nand [third-party notices](THIRD_PARTY_NOTICES.md) before importing external work.\n",
  "bytes": 10034,
  "sha": "9a887834b5496e003efc9eee066b827527bda34f6a4f8d6be28e5d581c4f43b4",
  "repo_slug": "agricidaniel/claude-ads",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_agricidaniel_claude_ads_ads_98abd2af/readme"
}