claude-ads README

The project's README from github.com/AgriciDaniel/claude-ads. As one markdown file: README.md.

Claude Ads, Claude-first paid-media operations across twelve advertising platforms

Claude Ads

Claude-first, portable paid-media operations for agencies, consultants, and in-house performance teams.

Claude Ads turns authorized exports or account reads into source-grounded audits, plans, creative workflows, experiments, monitoring, and reports. It is read-only by default. Live changes stay disabled until the exact platform and operation pass approval, idempotency, verification, audit, and rollback gates.

[!NOTE] Claude Ads ships from two homes: the public release at AgriciDaniel/claude-ads (MIT, no membership required) and the community mirror at AI-Marketing-Hub/claude-ads, where AI Marketing Hub Pro members get early access and direct collaboration.

Validated inputs flow through bounded workers into schema-valid findings and deterministic reports

What it does

Platforms

Twelve first-class paid-advertising platform surfaces

Segment Platforms
Search, video, and social Google Ads, Meta Ads, YouTube Ads, LinkedIn Ads, TikTok Ads, Microsoft Advertising, Reddit Ads, Snapchat Ads, X Ads
Commerce and retail media Apple Ads, Amazon Ads, Pinterest Ads

Each platform has a focused skill, audit worker, control reference, capability declaration, and testable routing surface. The capability manifest is the authoritative record for live reads and writes.

Commands

Standalone installs use /ads. Claude Code plugins are namespaced and use /claude-ads:ads. Both load the same ads/SKILL.md contract.

Command Outcome
/ads setup Create the client, account, KPI, privacy, and guardrail profile
/ads audit [all|platform|scope] Run a complete or scoped evidence-backed audit
/ads plan Build channel, campaign, budget, competitor, and measurement plans
/ads create Produce copy, image, video, or product-photo assets
/ads launch --draft Draft a campaign mutation plan without changing the account
/ads monitor Review pacing, delivery, tracking, fatigue, policy, and performance
/ads optimize --draft Draft evidence-backed optimization changes
/ads experiment Design or read out a controlled test
/ads report Render a validated JSON run bundle
/ads research refresh Refresh platform, policy, API, benchmark, and ecosystem evidence
/ads validate Validate contracts, runs, capabilities, maturity, or release readiness
/ads status, /ads next Show current status and the highest-priority blocker

Platform shortcuts such as /ads google, /ads meta, /ads amazon, and /ads reddit route to the matching platform audit.

Demo

Claude Ads command discovery inside Claude Code

The GIF shows the original command-discovery experience. The v2 command table above and the platform table are current and authoritative.

Installation

Claude Code is the canonical runtime. Codex, Gemini, Cursor, Windsurf, Goose, and compatible Agent Skills hosts can consume the same skill files where their runtime supports them.

Prefer the host's native plugin flow or a tagged release archive with a verified SHA-256 checksum. Never pipe a remote installer directly to a shell.

For Claude Code, the native plugin flow is:

/plugin marketplace add AgriciDaniel/claude-ads
/plugin install claude-ads@ai-marketing-hub-claude-ads

Or install from a local clone of the public repository:

git clone https://github.com/AgriciDaniel/claude-ads.git
cd claude-ads
bash install.sh --source=local

Select another standalone host explicitly:

bash install.sh --target=codex --source=local
bash install.sh --target=gemini --source=local --no-deps

PowerShell uses the same managed ownership model:

git clone https://github.com/AgriciDaniel/claude-ads.git
Set-Location claude-ads
.\install.ps1 -Source local

Managed dependencies support CPython 3.11 and 3.12 on the declared Linux, macOS, and Windows wheel matrix. Unsupported interpreters fail before the destination changes. Use --no-deps or -NoDeps for a skill-only install.

Browser capture requires an operator-installed Playwright browser payload. PDF rendering requires the host's WeasyPrint and Pango system libraries. These are documented in the external runtime dependency manifest.

Uninstall only manifest-owned files:

bash uninstall.sh --target=claude

The PowerShell equivalent is uninstall.ps1.

Architecture

One conductor dispatches platform and cross-platform workers, then validates and renders a canonical JSON bundle

One conductor owns scope, policy, aggregation, and final artifacts. Workers analyze bounded slices and return schema-valid findings. Required-worker failure makes the run partial. It is never silently presented as a complete audit.

The canonical result is versioned JSON. Markdown, HTML, and PDF are renderings of the same validated run bundle.

Scoring and evidence

Health and evidence coverage remain separate; scoring requires an approved platform profile

Controls use pass, fail, unknown, or not_applicable.

See the scoring reference and production implementation in claude_ads_core/scoring.py.

Account safety

All adapters are read-only by default. Applying a change requires:

  1. A tested and enabled capability for the exact operation.
  2. Explicit account and object IDs.
  3. A human-readable before and after diff with blast radius.
  4. Owner approval within account-defined ceilings.
  5. An idempotency key, audit destination, rollback, and verification window.
  6. Verification that remote state still matches the mutation precondition.

Missing ceilings mean no write. Permanent deletion is not supported in v2. Credentials belong in environment variables, an OS keychain, or an approved secret manager. They never belong in the repository, profiles, reports, or logs.

Evidence and release controls

The public-safe control-plane/ records product boundaries, dated sources, claims, capabilities, safety rules, privacy rules, ecosystem decisions, and release requirements.

See the release requirements and publishing policy.

Development

Create a virtual environment and run the complete suite:

python3.12 -m venv .venv
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements.lock
.venv/bin/python -m pip install --require-hashes --only-binary=:all: -r requirements-dev.lock
.venv/bin/python -m pip check
.venv/bin/python -m pytest -q

Useful focused checks:

python -m claude_ads_core --version
python -m claude_ads_core validate finding path/to/finding.json
bash -n install.sh uninstall.sh

Repository map

ads/                  main skill, interface metadata, and shared references
skills/               platform and lifecycle skills
agents/               platform, cross-platform, research, and verifier workers
claude_ads_core/      typed contracts, adapters, validation, and scoring
control-plane/        evidence, capability, safety, maturity, and release state
scripts/              browser, creative, reporting, and release helpers
evals/                routing and behavioral evaluation cases
tests/                deterministic, security, installer, and adapter tests

Privacy

Client data, raw private research, captured prompts, credentials, account exports, and agent transcripts must never enter Git history, reports, or release archives. Keep credentials in environment variables, an OS keychain, or an approved secret manager.

License

Original Claude Ads code and documentation are available under the MIT License. Third-party APIs, trademarks, documentation, and cited artifacts remain subject to their own terms. Review the source ledger and third-party notices before importing external work.

claude-ads (AgriciDaniel/claude-ads)

Searching Database…

10.1K ·GitHub
Claude-ads
Что это такое?Навык (skill) для Claude Code, заточенный под работу с платной рекламой: он превращает авторизованные выгрузки или чтение данных из рекламных аккаунтов в аудиты с опорой на источники, планы кампаний, брифы для креативов, эксперименты, мониторинг и версионируемые отчёты — и всё это на 12 рекламных платформах.
Это отдельное приложение или что-то внутри Claude Code?Это навык, а не приложение: каноническая среда выполнения — Claude Code, а Codex, Gemini, Cursor, Windsurf и Goose могут использовать те же файлы навыка там, где их среда это поддерживает. При отдельной установке используются команды /ads, в виде плагина для Claude Code — /claude-ads:ads.
Нужно ли мне самому доустановить какие-то зависимости, чтобы всё работало?Да, две: для захвата из браузера нужен браузерный пакет Playwright, который оператор устанавливает сам, а для рендеринга PDF — системные библиотеки WeasyPrint и Pango в вашем окружении. Обе описаны в манифесте внешних зависимостей среды выполнения.
Оно реально может вносить изменения в мои рекламные аккаунты или только анализировать?По умолчанию работает только на чтение. Живые изменения остаются выключенными, пока конкретная операция платформы не пройдёт все проверки: на возможности, одобрение, идемпотентность, верификацию, аудит и откат. Если лимиты (ceilings) не заданы — записи не будет, а безвозвратное удаление в v2 не поддерживается вовсе.
Какие рекламные платформы она охватывает?Двенадцать: в социальной части — Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, Reddit, Snapchat и X Ads, а для коммерции и retail media — Apple, Amazon и Pinterest Ads. Для каждой платформы есть свой отдельный навык, воркер аудита и манифест возможностей.
Где в итоге оказываются мои учётные данные и данные клиентов?Учётные данные должны лежать в переменных окружения, ключнице ОС или одобренном менеджере секретов — но никогда в репозитории, профилях, отчётах или логах. Данные клиентов, выгрузки аккаунтов и расшифровки работы агента не должны попадать в историю Git, отчёты или релизные архивы.
Можно бесплатно использовать для работы с клиентами?Да — публичный релиз распространяется по лицензии MIT, членство не нужно, так что коммерческое использование в агентствах и внутри компаний допустимо. Сторонние API, товарные знаки и цитируемые материалы остаются на условиях своих правообладателей.
Чем этот репозиторий отличается от зеркала AI Marketing Hub?Публичный релиз здесь — под лицензией MIT и без обязательного членства. А в комьюнити-зеркале AI-Marketing-Hub/claude-ads участники AI Marketing Hub Pro получают ранний доступ и возможность работать над проектом напрямую.
Что на практике значит 'source-grounded' — «с опорой на источники»?Каждое утверждение должно опираться на датированный источник: нет источника — нет утверждения о текущем состоянии платформы, нет реализации, фикстуры и теста — нет заявления о возможности. Отчёты также честно помечают недостающие данные, устаревшие источники, противоречия и частичные сбои, вместо того чтобы замалчивать их.
А если у меня несколько клиентских аккаунтов — справится?Да. Команда /ads setup создаёт профиль клиента, аккаунта, KPI, приватности и guardrail-ограничений, а оценка работает на уровне всего портфеля: упавшая платформа исключается из портфельной оценки, и весь запуск помечается как частичный.
Почему команды запуска и оптимизации работают только в режиме черновика (draft)?/ads launch --draft и /ads optimize --draft выдают читаемое сравнение «до/после» с оценкой масштаба воздействия (blast radius), чтобы владелец мог всё одобрить в рамках заданных для аккаунта лимитов до того, как что-то применится. Нет лимитов — нет записи.
What are similar projects?handout-remake, marketingskills, marketing-os, linkedin-agent-skill, huashu-art-motion, google-ads-meta-ads-mcp, marketing-skills, geo-seo-claude
Which topics is it in?marketing-automation, claude-code-skill, playwright, analytics, claude-skills, json, pdf, gemini, monitoring, agent-skills, codex, privacy
Creator
AgriciDaniel
Size
5.9 MB
Stars
10.1K
Updated
CommitOct 17Releasev2.1.0Oct 16
Age
8mo
Commits · 90 Days