From f85408831310abe9ccf0a6e48b547d5bc4f2f8da Mon Sep 17 00:00:00 2001 From: Codex Date: Tue, 26 May 2026 14:11:51 +0000 Subject: [PATCH 1/6] Update marketing skills to v2.0.1 --- README.md | 2 +- docs/deploy/railway.md | 42 +- docs/getting-started.md | 11 +- docs/marketing-skills-v2.0.1-audit.md | 74 +++ docs/skills.md | 20 +- pyproject.toml | 2 +- .../skills/marketing-ab-test-setup/SKILL.md | 101 +++- .../marketing-ab-test-setup/evals/evals.json | 105 ++++ .../skills/marketing-ad-creative/SKILL.md | 14 +- .../marketing-ad-creative/evals/evals.json | 90 ++++ .../references/generative-tools.md | 2 +- .../agents/skills/marketing-ai-seo/SKILL.md | 183 +++++-- .../skills/marketing-ai-seo/evals/evals.json | 90 ++++ .../references/content-types.md | 71 +++ .../marketing-analytics-tracking/SKILL.md | 12 +- .../evals/evals.json | 90 ++++ .../agents/skills/marketing-aso/SKILL.md | 312 ++++++++++++ .../skills/marketing-aso/evals/evals.json | 91 ++++ .../marketing-aso/references/apple-specs.md | 107 ++++ .../marketing-aso/references/benchmarks.md | 129 +++++ .../references/google-play-specs.md | 131 +++++ .../references/report-template.md | 213 ++++++++ .../references/scoring-criteria.md | 213 ++++++++ .../marketing-churn-prevention/SKILL.md | 24 +- .../evals/evals.json | 93 ++++ .../references/cancel-flow-patterns.md | 6 +- .../skills/marketing-co-marketing/SKILL.md | 290 +++++++++++ .../marketing-co-marketing/evals/evals.json | 84 +++ .../skills/marketing-cold-email/SKILL.md | 14 +- .../marketing-cold-email/evals/evals.json | 94 ++++ .../marketing-community-marketing/SKILL.md | 163 ++++++ .../evals/evals.json | 89 ++++ .../SKILL.md | 10 +- .../evals/evals.json | 93 ++++ .../marketing-competitor-profiling/SKILL.md | 411 +++++++++++++++ .../evals/evals.json | 85 ++++ .../references/templates.md | 167 ++++++ .../references/tool-reference.md | 179 +++++++ .../marketing-content-strategy/SKILL.md | 16 +- .../evals/evals.json | 90 ++++ .../references/headless-cms.md | 194 +++++++ .../skills/marketing-copy-editing/SKILL.md | 128 ++--- .../marketing-copy-editing/evals/evals.json | 89 ++++ .../references/checklist.md | 66 +++ .../references/content-refresh.md | 38 ++ .../skills/marketing-copywriting/SKILL.md | 16 +- .../marketing-copywriting/evals/evals.json | 111 ++++ .../marketing-customer-research/SKILL.md | 270 ++++++++++ .../evals/evals.json | 162 ++++++ .../references/source-guides.md | 401 +++++++++++++++ .../marketing-directory-submissions/SKILL.md | 381 ++++++++++++++ .../evals/evals.json | 94 ++++ .../references/directory-list.md | 477 ++++++++++++++++++ .../references/positioning-variations.md | 232 +++++++++ .../submission-tracker-template.csv | 266 ++++++++++ .../skills/marketing-email-sequence/SKILL.md | 16 +- .../marketing-email-sequence/evals/evals.json | 93 ++++ .../marketing-free-tool-strategy/SKILL.md | 15 +- .../evals/evals.json | 90 ++++ .../agents/skills/marketing-image/SKILL.md | 340 +++++++++++++ .../skills/marketing-image/evals/evals.json | 89 ++++ .../references/ai-image-prompting.md | 229 +++++++++ .../skills/marketing-launch-strategy/SKILL.md | 14 +- .../evals/evals.json | 91 ++++ .../skills/marketing-lead-magnets/SKILL.md | 310 ++++++++++++ .../marketing-lead-magnets/evals/evals.json | 87 ++++ .../references/benchmarks.md | 129 +++++ .../references/format-guide.md | 196 +++++++ .../skills/marketing-marketing-ideas/SKILL.md | 14 +- .../evals/evals.json | 90 ++++ .../agents/skills/marketing-mode/SKILL.md | 6 +- .../skills/marketing-onboarding-cro/SKILL.md | 16 +- .../marketing-onboarding-cro/evals/evals.json | 92 ++++ .../agents/skills/marketing-page-cro/SKILL.md | 23 +- .../marketing-page-cro/evals/evals.json | 111 ++++ .../marketing-page-cro/references/form.md | 422 ++++++++++++++++ .../agents/skills/marketing-paid-ads/SKILL.md | 20 +- .../marketing-paid-ads/evals/evals.json | 90 ++++ .../references/conversion-tracking.md | 361 +++++++++++++ .../marketing-paywall-upgrade-cro/SKILL.md | 14 +- .../evals/evals.json | 93 ++++ .../skills/marketing-popup-cro/SKILL.md | 19 +- .../marketing-popup-cro/evals/evals.json | 94 ++++ .../marketing-pricing-strategy/SKILL.md | 12 +- .../evals/evals.json | 90 ++++ .../SKILL.md | 18 +- .../evals/evals.json | 85 ++++ .../marketing-programmatic-seo/SKILL.md | 12 +- .../evals/evals.json | 94 ++++ .../references/playbooks.md | 2 +- .../SKILL.md | 14 +- .../marketing-psychology/evals/evals.json | 88 ++++ .../marketing-referral-program/SKILL.md | 16 +- .../evals/evals.json | 89 ++++ .../references/affiliate-programs.md | 3 + .../agents/skills/marketing-revops/SKILL.md | 18 +- .../skills/marketing-revops/evals/evals.json | 91 ++++ .../marketing-sales-enablement/SKILL.md | 24 +- .../evals/evals.json | 91 ++++ .../skills/marketing-schema-markup/SKILL.md | 8 +- .../marketing-schema-markup/evals/evals.json | 87 ++++ .../skills/marketing-seo-audit/SKILL.md | 105 +++- .../marketing-seo-audit/evals/evals.json | 136 +++++ .../references/international-seo.md | 230 +++++++++ .../skills/marketing-signup-flow-cro/SKILL.md | 18 +- .../evals/evals.json | 88 ++++ .../marketing-site-architecture/SKILL.md | 14 +- .../evals/evals.json | 88 ++++ .../agents/skills/marketing-sms/SKILL.md | 338 +++++++++++++ .../skills/marketing-sms/evals/evals.json | 100 ++++ .../marketing-sms/references/compliance.md | 202 ++++++++ .../marketing-sms/references/platforms.md | 318 ++++++++++++ .../references/sequence-templates.md | 282 +++++++++++ .../skills/marketing-social-content/SKILL.md | 155 +++++- .../marketing-social-content/evals/evals.json | 92 ++++ .../references/platform-limits.md | 110 ++++ .../references/short-form-video.md | 237 +++++++++ .../agents/skills/marketing-video/SKILL.md | 342 +++++++++++++ .../skills/marketing-video/evals/evals.json | 88 ++++ .../references/ai-video-prompting.md | 175 +++++++ 120 files changed, 13687 insertions(+), 375 deletions(-) create mode 100644 docs/marketing-skills-v2.0.1-audit.md create mode 100644 src/adclaw/agents/skills/marketing-ab-test-setup/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-ad-creative/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-ai-seo/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-ai-seo/references/content-types.md create mode 100644 src/adclaw/agents/skills/marketing-analytics-tracking/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-aso/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-aso/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-aso/references/apple-specs.md create mode 100644 src/adclaw/agents/skills/marketing-aso/references/benchmarks.md create mode 100644 src/adclaw/agents/skills/marketing-aso/references/google-play-specs.md create mode 100644 src/adclaw/agents/skills/marketing-aso/references/report-template.md create mode 100644 src/adclaw/agents/skills/marketing-aso/references/scoring-criteria.md create mode 100644 src/adclaw/agents/skills/marketing-churn-prevention/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-co-marketing/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-co-marketing/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-cold-email/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-community-marketing/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-community-marketing/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-competitor-alternatives/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-competitor-profiling/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-competitor-profiling/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-competitor-profiling/references/templates.md create mode 100644 src/adclaw/agents/skills/marketing-competitor-profiling/references/tool-reference.md create mode 100644 src/adclaw/agents/skills/marketing-content-strategy/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-content-strategy/references/headless-cms.md create mode 100644 src/adclaw/agents/skills/marketing-copy-editing/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-copy-editing/references/checklist.md create mode 100644 src/adclaw/agents/skills/marketing-copy-editing/references/content-refresh.md create mode 100644 src/adclaw/agents/skills/marketing-copywriting/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-customer-research/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-customer-research/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-customer-research/references/source-guides.md create mode 100644 src/adclaw/agents/skills/marketing-directory-submissions/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-directory-submissions/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-directory-submissions/references/directory-list.md create mode 100644 src/adclaw/agents/skills/marketing-directory-submissions/references/positioning-variations.md create mode 100644 src/adclaw/agents/skills/marketing-directory-submissions/references/submission-tracker-template.csv create mode 100644 src/adclaw/agents/skills/marketing-email-sequence/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-free-tool-strategy/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-image/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-image/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-image/references/ai-image-prompting.md create mode 100644 src/adclaw/agents/skills/marketing-launch-strategy/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-lead-magnets/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-lead-magnets/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-lead-magnets/references/benchmarks.md create mode 100644 src/adclaw/agents/skills/marketing-lead-magnets/references/format-guide.md create mode 100644 src/adclaw/agents/skills/marketing-marketing-ideas/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-onboarding-cro/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-page-cro/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-page-cro/references/form.md create mode 100644 src/adclaw/agents/skills/marketing-paid-ads/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-paid-ads/references/conversion-tracking.md create mode 100644 src/adclaw/agents/skills/marketing-paywall-upgrade-cro/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-popup-cro/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-pricing-strategy/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-product-marketing-context/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-programmatic-seo/evals/evals.json rename src/adclaw/agents/skills/{marketing-marketing-psychology => marketing-psychology}/SKILL.md (96%) create mode 100644 src/adclaw/agents/skills/marketing-psychology/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-referral-program/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-revops/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-sales-enablement/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-schema-markup/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-seo-audit/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-seo-audit/references/international-seo.md create mode 100644 src/adclaw/agents/skills/marketing-signup-flow-cro/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-site-architecture/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-sms/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-sms/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-sms/references/compliance.md create mode 100644 src/adclaw/agents/skills/marketing-sms/references/platforms.md create mode 100644 src/adclaw/agents/skills/marketing-sms/references/sequence-templates.md create mode 100644 src/adclaw/agents/skills/marketing-social-content/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-social-content/references/platform-limits.md create mode 100644 src/adclaw/agents/skills/marketing-social-content/references/short-form-video.md create mode 100644 src/adclaw/agents/skills/marketing-video/SKILL.md create mode 100644 src/adclaw/agents/skills/marketing-video/evals/evals.json create mode 100644 src/adclaw/agents/skills/marketing-video/references/ai-video-prompting.md diff --git a/README.md b/README.md index 91f298a..22ad7d3 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ - **@tag routing** in Telegram — `@researcher find AI trends` sends the message to the right agent - **Coordinator delegation** — one agent orchestrates the rest, delegating tasks automatically - **Shared memory** — agents read each other's output files for seamless collaboration -- **130+ built-in skills** — SEO (19 skills + 30 reference files), ads (18 skills + 23 reference files), content, social media, analytics, growth hacking +- **120+ built-in skills** — SEO (19 skills + 30 reference files), ads (18 skills + 23 reference files), content, social media, analytics, growth hacking - **25 built-in MCP servers** — browser automation, AI search, SEO, ads, social media, email marketing, CRM, disposable email inboxes, multimodal generation (image/video/speech/music), and more. Enable what you need from the Web UI - **52 marketing tools** via Citedy MCP server - **Instant file publishing** — upload any file to [here.now](https://here.now), get a shareable link, host static sites, use your own domain diff --git a/docs/deploy/railway.md b/docs/deploy/railway.md index 199f540..28d4c3a 100644 --- a/docs/deploy/railway.md +++ b/docs/deploy/railway.md @@ -6,7 +6,7 @@ This guide walks through deploying AdClaw — an AI marketing agent team — on ## What you get -- **130+ built-in skills** — SEO, ads, content, social, audio, music, graphics, video, browser automation +- **121 built-in skills** — SEO, ads, content, social, audio, music, graphics, video, browser automation - **Multi-agent personas** — Growth Hacker, Social Media Strategist, Content Writer, Analytics Reporter, plus your own. Coordinated by a central Coordinator. Address with `@persona-name` in chat; untagged messages route to the Coordinator. - **23 LLM providers** with 100+ models — OpenAI, Anthropic, Google Gemini, Aliyun (Qwen, GLM), Z.AI, xAI Grok, Mistral, DeepSeek, Groq, Together, OpenRouter, Cerebras, MiniMax, Baseten, Moonshot Kimi, Inception, ModelScope, DashScope, Ollama, llama.cpp, MLX, Azure OpenAI. Automatic failover between configured providers. - **Multi-channel chat** — Telegram, Discord, Feishu, DingTalk, QQ, or the built-in web console. @@ -18,14 +18,12 @@ This guide walks through deploying AdClaw — an AI marketing agent team — on > ⚠️ **Plan: Hobby or higher (≥ 2 GB RAM, 25 GB disk).** > -> AdClaw bundles a Python agent runtime + skill registry + Chromium, so -> Railway's Free plan is not enough. Use **Hobby or higher**. Hobby is -> **$5/month** and includes **$5 of monthly usage credits**. +> AdClaw bundles a Python agent runtime + skill registry + Chromium that need ≥ 600 MB on startup. The 30-day Trial 512 MB instance OOMs immediately. Hobby is **$5/month + usage**; idle AdClaw consumes about $0.50–$1/day so the included credits cover ~5 days of testing. | Plan | Works? | Notes | |---|---|---| -| Free / 0.5 GB RAM | ❌ | Not enough RAM/volume for AdClaw | -| Hobby ($5/mo) | ✅ | Recommended starter | +| Trial / 512 MB | ❌ | OOM at startup | +| Hobby ($5/mo, 2 GB) | ✅ | Recommended starter | | Pro and higher | ✅ | For multiple personas under load | You'll also need: @@ -49,7 +47,7 @@ You do **not** need a Citedy account to use AdClaw — Citedy MCP is opt-in. If you prefer to wire it up yourself: -1. **New Project → Deploy from GitHub repo** → `Citedy/adclaw`. Or **Deploy from Docker Image** → `nttylock/adclaw:1.0.7`. +1. **New Project → Deploy from GitHub repo** → `Citedy/adclaw`. Or **Deploy from Docker Image** → `nttylock/adclaw:1.0.6`. 2. **Settings → Networking** → expose port `8088`, generate the public domain. 3. **Settings → Build** → confirm builder is **Dockerfile** with path `deploy/Dockerfile` (read from `railway.json` automatically). 4. **Settings → Deploy**: @@ -88,15 +86,11 @@ If you only attach one, pick `/app/working` and accept that LLM keys live inside | Tag | Image size | Idle RAM | Best for | |---|---|---|---| -| `nttylock/adclaw:1.0.7` (default pin) | ~4.2 GB | 600–800 MB | Full feature set — Chromium for browser/scraping/social skills | -| `nttylock/adclaw:1.0.7-browser` | ~4.1 GB | similar | Browser-only, no Feishu/DingTalk channels | -| `nttylock/adclaw:1.0.7-core` | ~2.7 GB | 250–400 MB | Lightweight — no Chromium, no desktop tools | +| `nttylock/adclaw:1.0.6` (default pin) | ~4.2 GB | 600–800 MB | Full feature set — Chromium for browser/scraping/social skills | +| `nttylock/adclaw:1.0.6-browser` | ~4.1 GB | similar | Browser-only, no Feishu/DingTalk channels | +| `nttylock/adclaw:1.0.6-core` | ~2.7 GB | 250–400 MB | Lightweight — no Chromium, no desktop tools | -Switch by editing **Settings → Source** to use a Docker Image source instead of GitHub repo, then set the image to `nttylock/adclaw:1.0.7-core`. Build is skipped — deploy is ~30 s. - -If you need a reproducible release pin instead of the moving variant tags, use -the versioned aliases published by the release workflow, for example -`nttylock/adclaw:1.0.7-core` or `nttylock/adclaw:1.0.7-browser`. +Switch by editing **Settings → Source** to use a Docker Image source instead of GitHub repo, then set the image to `nttylock/adclaw:1.0.6-core`. Build is skipped — deploy is ~30 s. ## Post-deploy workflow @@ -123,20 +117,11 @@ curl https:///api/diagnostics/health Returns the status of LLM, channels, memory, AOM, MCP, and watchdog. Safe to poll from external monitors. -## Pricing note - -Railway Hobby currently costs **$5/month** and includes **$5 of monthly usage -credits**. - -For AdClaw, the important practical rule is: - -- **Free** is not enough for deployment -- **Hobby** is the minimum supported Railway plan -- if your usage goes beyond the included monthly credit, Railway charges the - overage +## Cost estimate -Set [Railway Spending Limits](https://docs.railway.com/reference/usage-limits) -if you want a hard cap. +Idle (no traffic, default config): about **$0.50–$1/day** on Hobby. +Active use (continuous chat, browser skills, frequent cron): up to **$3–5/day**. +Hobby includes $5/month — covers light usage. Set [Railway Spending Limits](https://docs.railway.com/reference/usage-limits) to cap. ## Troubleshooting @@ -158,6 +143,7 @@ if you want a hard cap. ## Source code & support - **Public repo:** https://github.com/Citedy/adclaw +- **Source of truth:** https://github.com/nttylock/AdClaw (private dev — public mirror sync on every release) - **DigitalOcean Marketplace:** https://marketplace.digitalocean.com/apps/adclaw - **Issues:** https://github.com/Citedy/adclaw/issues - **License:** Apache-2.0 diff --git a/docs/getting-started.md b/docs/getting-started.md index 969ba51..e5d9c12 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,11 +1,11 @@ # Getting Started with AdClaw -AdClaw is an AI marketing assistant powered by [Citedy](https://www.citedy.com). It comes with 130+ built-in skills (SEO, ads, content, social media, analytics, and more), 52 MCP tools, and works out of the box via Telegram or web chat. +AdClaw is an AI marketing assistant powered by [Citedy](https://www.citedy.com). It comes with 121 built-in skills (SEO, ads, content, social media, analytics, and more), 52 MCP tools, and works out of the box via Telegram or web chat. ## Quick Install ```bash -curl -sSL https://raw.githubusercontent.com/Citedy/adclaw/main/install.sh | bash +curl -sSL https://raw.githubusercontent.com/nttylock/AdClaw/main/install.sh | bash ``` Or with Docker Compose: @@ -27,15 +27,14 @@ docker run -d --name adclaw \ -v adclaw-data:/app/working \ -e CITEDY_API_KEY=your_citedy_agent_key \ -e TELEGRAM_BOT_TOKEN=your_telegram_bot_token \ - nttylock/adclaw:1.0.7 + nttylock/adclaw:1.0.6 ``` The release workflow publishes images for both `linux/amd64` and `linux/arm64`. If you are testing local source changes before the next Docker release, use Docker Compose from this repo so the image is built on -your machine. If you need a pinned published tag instead of the moving -`latest`, use `nttylock/adclaw:1.0.7`, `nttylock/adclaw:1.0.7-browser`, or -`nttylock/adclaw:1.0.7-core`. +your machine. If you prefer the moving full-variant alias after the release is +live, `nttylock/adclaw:latest` continues to track the current full line. ## First-Run Setup diff --git a/docs/marketing-skills-v2.0.1-audit.md b/docs/marketing-skills-v2.0.1-audit.md new file mode 100644 index 0000000..52614eb --- /dev/null +++ b/docs/marketing-skills-v2.0.1-audit.md @@ -0,0 +1,74 @@ +# Marketing Skills v2.0.1 Audit + +Date: 2026-05-26 + +Source package: `coreyhaines31/marketingskills` + +Installer result: `npx skills add coreyhaines31/marketingskills -y` found 41 skills. + +## Result + +- Upgraded 31 existing AdClaw built-in marketing skills by syncing v2.0.1 content into the existing `marketing-*` skill directories. +- Added 10 new AdClaw built-in marketing skills using the existing `marketing-*` naming convention. +- Left existing Citedy, SEO, ads, agency, and platform skills in place. +- Private AdClaw static skill security scan passed for all 41 v2.0.1 source skills with zero missing skills, blocked findings, or warnings. +- Targeted private validator regression tests passed: `90 passed, 1 skipped`. +- Live LLM audit was attempted through `tests/test_skill_validator_real.py`, but the test file skipped because no `QWEN_API_KEY`, `GLM_API_KEY`, or `OPENAI_API_KEY` was available in `/root/.env` or the private checkout. + +## Upgraded Existing Skills + +| v2.0.1 source | AdClaw built-in skill | +| --- | --- | +| `ab-testing` | `marketing-ab-test-setup` | +| `ad-creative` | `marketing-ad-creative` | +| `ads` | `marketing-paid-ads` | +| `ai-seo` | `marketing-ai-seo` | +| `analytics` | `marketing-analytics-tracking` | +| `churn-prevention` | `marketing-churn-prevention` | +| `cold-email` | `marketing-cold-email` | +| `competitors` | `marketing-competitor-alternatives` | +| `content-strategy` | `marketing-content-strategy` | +| `copy-editing` | `marketing-copy-editing` | +| `copywriting` | `marketing-copywriting` | +| `cro` | `marketing-page-cro` | +| `emails` | `marketing-email-sequence` | +| `free-tools` | `marketing-free-tool-strategy` | +| `launch` | `marketing-launch-strategy` | +| `marketing-ideas` | `marketing-marketing-ideas` | +| `marketing-psychology` | `marketing-psychology` | +| `onboarding` | `marketing-onboarding-cro` | +| `paywalls` | `marketing-paywall-upgrade-cro` | +| `popups` | `marketing-popup-cro` | +| `pricing` | `marketing-pricing-strategy` | +| `product-marketing` | `marketing-product-marketing-context` | +| `programmatic-seo` | `marketing-programmatic-seo` | +| `referrals` | `marketing-referral-program` | +| `revops` | `marketing-revops` | +| `sales-enablement` | `marketing-sales-enablement` | +| `schema` | `marketing-schema-markup` | +| `seo-audit` | `marketing-seo-audit` | +| `signup` | `marketing-signup-flow-cro` | +| `site-architecture` | `marketing-site-architecture` | +| `social` | `marketing-social-content` | + +## Added New Skills + +| v2.0.1 source | New AdClaw built-in skill | +| --- | --- | +| `aso` | `marketing-aso` | +| `co-marketing` | `marketing-co-marketing` | +| `community-marketing` | `marketing-community-marketing` | +| `competitor-profiling` | `marketing-competitor-profiling` | +| `customer-research` | `marketing-customer-research` | +| `directory-submissions` | `marketing-directory-submissions` | +| `image` | `marketing-image` | +| `lead-magnets` | `marketing-lead-magnets` | +| `sms` | `marketing-sms` | +| `video` | `marketing-video` | + +## Notable v2.0.1 Additions Verified + +- `marketing-image` includes the May 2026 image model lineup: Gemini Nano Banana Pro, Flux, Ideogram 3.0, ChatGPT Images 2.0 / GPT Image, Midjourney v7, Recraft V3, and Stable Diffusion. +- `marketing-video` includes the May 2026 video model lineup: Veo 3, Sora 2, Runway Gen-4, Kling 2.5/3.0, Seedance, Hailuo / MiniMax, Pika 2.x, Hunyuan Video, and Wan 2. +- `marketing-ad-creative` includes ChatGPT Images 2.0 in its generative tools reference. +- Community PR coverage is present through the new skills and references for community marketing, competitor profiling, directory submissions, AI SEO, and research workflows. diff --git a/docs/skills.md b/docs/skills.md index bb62391..29b019c 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -1,6 +1,6 @@ # Skills Library -AdClaw ships with **113 built-in skills** across 10 categories. All skills are security-scanned (208-pattern static analysis + LLM audit). +AdClaw ships with **121 built-in skills** across 10 categories. All skills are security-scanned (208-pattern static analysis + LLM audit). --- @@ -8,7 +8,7 @@ AdClaw ships with **113 built-in skills** across 10 categories. All skills are s | Category | Count | Description | |----------|-------|-------------| -| Marketing | 33 | CRO, copywriting, email, psychology, pricing, referral, launch | +| Marketing | 43 | CRO, copywriting, email, psychology, pricing, referral, launch, media, SMS, community | | SEO | 19 | Audits, backlinks, technical, local, schema, programmatic, images | | Ads | 18 | Google, Meta, LinkedIn, TikTok, YouTube, Apple, Microsoft, creative | | Citedy | 6 | SEO autopilot, content writer, video shorts, trends, leads, ingestion | @@ -17,7 +17,7 @@ AdClaw ships with **113 built-in skills** across 10 categories. All skills are s | Agency | 5 | Growth hacker, analytics reporter, app store optimizer, feedback synthesizer, trend researcher | | Office | 4 | PDF, DOCX, PPTX, XLSX | | Utility | 10 | Email, file reader, here.now publish, himalaya, cron, news, self-setup, skill-creator, GA4, GSC | -| Platform | 7 | AgentHub worker, DingTalk channel, Google Ads API, browser_visible, marketing-mode, ads-shared, seo-shared | +| Platform | 5 | AgentHub worker, DingTalk channel, Google Ads API, browser_visible, marketing-mode | --- @@ -68,7 +68,7 @@ AdClaw ships with **113 built-in skills** across 10 categories. All skills are s | `ads-tiktok` | TikTok Ads analysis (creative, tracking, bidding) | | `ads-youtube` | YouTube Ads analysis (campaign types, creative, audience) | -## Marketing Skills (33) +## Marketing Skills (43) | Skill | Description | |-------|-------------| @@ -77,18 +77,26 @@ AdClaw ships with **113 built-in skills** across 10 categories. All skills are s | `marketing-ad-creative` | Ad creative generation and iteration at scale | | `marketing-ai-seo` | Optimize for AI search engines (ChatGPT, Gemini, Perplexity) | | `marketing-analytics-tracking` | Analytics setup, event tracking, measurement | +| `marketing-aso` | App Store and Google Play listing optimization | | `marketing-churn-prevention` | Reduce churn, cancellation flows, save offers | +| `marketing-co-marketing` | Co-marketing partners and joint campaign planning | | `marketing-cold-email` | B2B cold email and follow-up sequences | +| `marketing-community-marketing` | Community strategy, advocates, and community-led growth | | `marketing-competitor-alternatives` | Competitor comparison and alternative pages | +| `marketing-competitor-profiling` | Competitor research and structured competitor profiles | | `marketing-content-strategy` | Content strategy planning and editorial calendar | | `marketing-copy-editing` | Edit and improve existing marketing copy | | `marketing-copywriting` | Write marketing copy for any page type | +| `marketing-customer-research` | Customer research, ICP, VOC, and review mining | +| `marketing-directory-submissions` | Directory submissions for launch discovery and backlinks | | `marketing-email-sequence` | Email sequences, drip campaigns, automated flows | | `marketing-form-cro` | Form optimization (lead capture, surveys, checkout) | | `marketing-free-tool-strategy` | Free tool planning for lead generation | +| `marketing-image` | Marketing image generation, editing, and optimization | | `marketing-launch-strategy` | Product launch and feature announcement planning | +| `marketing-lead-magnets` | Lead magnet strategy for gated content and downloads | | `marketing-marketing-ideas` | Marketing idea generation and brainstorming | -| `marketing-marketing-psychology` | Apply behavioral science to marketing | +| `marketing-psychology` | Apply behavioral science to marketing | | `marketing-onboarding-cro` | Post-signup onboarding and activation optimization | | `marketing-page-cro` | Landing page conversion rate optimization | | `marketing-paid-ads` | Paid advertising campaign help (Google, Meta, LinkedIn) | @@ -104,7 +112,9 @@ AdClaw ships with **113 built-in skills** across 10 categories. All skills are s | `marketing-seo-audit` | SEO audit and diagnostics | | `marketing-signup-flow-cro` | Signup and registration flow optimization | | `marketing-site-architecture` | Site hierarchy, navigation, URL structure | +| `marketing-sms` | SMS and MMS marketing flows and compliance | | `marketing-social-content` | Social media content creation and scheduling | +| `marketing-video` | AI video generation and programmatic video workflows | ## Citedy Skills (6) diff --git a/pyproject.toml b/pyproject.toml index 0addeaa..c156230 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,7 +1,7 @@ [project] name = "adclaw" dynamic = ["version"] -description = "Multi-agent AI marketing team with 117 skills, multi-channel support, and shared memory" +description = "Multi-agent AI marketing team with 121 skills, multi-channel support, and shared memory" readme = "README.md" requires-python = ">=3.10,<3.14" license = {text = "Apache-2.0"} diff --git a/src/adclaw/agents/skills/marketing-ab-test-setup/SKILL.md b/src/adclaw/agents/skills/marketing-ab-test-setup/SKILL.md index 2da0d1e..e3f9997 100644 --- a/src/adclaw/agents/skills/marketing-ab-test-setup/SKILL.md +++ b/src/adclaw/agents/skills/marketing-ab-test-setup/SKILL.md @@ -1,8 +1,8 @@ --- -name: ab-test-setup -description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking. +name: ab-testing +description: When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," "how long should I run this test," "growth experiments," "experiment velocity," "experiment backlog," "ICE score," "experimentation program," or "experiment playbook." Use this whenever someone is comparing two approaches and wants to measure which performs better, or when they want to build a systematic experimentation practice. For tracking implementation, see analytics. For page-level conversion optimization, see cro. metadata: - version: 1.1.0 + version: 2.0.0 --- # A/B Test Setup @@ -12,7 +12,7 @@ You are an expert in experimentation and A/B testing. Your goal is to help desig ## Initial Assessment **Check for product marketing context first:** -If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. Before designing a test, understand: @@ -180,7 +180,7 @@ We'll know this is true when [metrics]. - Check segment quality - Document external factors -**DON'T:** +**Avoid:** - Peek at results and stop early - Make changes to variants - Add traffic from new sources @@ -229,6 +229,93 @@ Document every test with: --- +## Growth Experimentation Program + +Individual tests are valuable. A continuous experimentation program is a compounding asset. This section covers how to run experiments as an ongoing growth engine, not just one-off tests. + +### The Experiment Loop + +``` +1. Generate hypotheses (from data, research, competitors, customer feedback) +2. Prioritize with ICE scoring +3. Design and run the test +4. Analyze results with statistical rigor +5. Promote winners to a playbook +6. Generate new hypotheses from learnings +→ Repeat +``` + +### Hypothesis Generation + +Feed your experiment backlog from multiple sources: + +| Source | What to Look For | +|--------|-----------------| +| Analytics | Drop-off points, low-converting pages, underperforming segments | +| Customer research | Pain points, confusion, unmet expectations | +| Competitor analysis | Features, messaging, or UX patterns they use that you don't | +| Support tickets | Recurring questions or complaints about conversion flows | +| Heatmaps/recordings | Where users hesitate, rage-click, or abandon | +| Past experiments | "Significant loser" tests often reveal new angles to try | + +### ICE Prioritization + +Score each hypothesis 1-10 on three dimensions: + +| Dimension | Question | +|-----------|----------| +| **Impact** | If this works, how much will it move the primary metric? | +| **Confidence** | How sure are we this will work? (Based on data, not gut.) | +| **Ease** | How fast and cheap can we ship and measure this? | + +**ICE Score** = (Impact + Confidence + Ease) / 3 + +Run highest-scoring experiments first. Re-score monthly as context changes. + +### Experiment Velocity + +Track your experimentation rate as a leading indicator of growth: + +| Metric | Target | +|--------|--------| +| Experiments launched per month | 4-8 for most teams | +| Win rate | 20-30% is common for mature programs (sustained higher rates may indicate conservative hypotheses) | +| Average test duration | 2-4 weeks | +| Backlog depth | 20+ hypotheses queued | +| Cumulative lift | Compound gains from all winners | + +### The Experiment Playbook + +When a test wins, don't just implement it — document the pattern: + +``` +## [Experiment Name] +**Date**: [date] +**Hypothesis**: [the hypothesis] +**Sample size**: [n per variant] +**Result**: [winner/loser/inconclusive] — [primary metric] changed by [X%] (95% CI: [range], p=[value]) +**Guardrails**: [any guardrail metrics and their outcomes] +**Segment deltas**: [notable differences by device, segment, or cohort] +**Why it worked/failed**: [analysis] +**Pattern**: [the reusable insight — e.g., "social proof near pricing CTAs increases plan selection"] +**Apply to**: [other pages/flows where this pattern might work] +**Status**: [implemented / parked / needs follow-up test] +``` + +Over time, your playbook becomes a library of proven growth patterns specific to your product and audience. + +### Experiment Cadence + +**Weekly (30 min)**: Review running experiments for technical issues and guardrail metrics. Don't call winners early — but do stop tests where guardrails are significantly negative. + +**Bi-weekly**: Conclude completed experiments. Analyze results, update playbook, launch next experiment from backlog. + +**Monthly (1 hour)**: Review experiment velocity, win rate, cumulative lift. Replenish hypothesis backlog. Re-prioritize with ICE. + +**Quarterly**: Audit the playbook. Which patterns have been applied broadly? Which winning patterns haven't been scaled yet? What areas of the funnel are under-tested? + +--- + ## Common Mistakes ### Test Design @@ -261,6 +348,6 @@ Document every test with: ## Related Skills -- **page-cro**: For generating test ideas based on CRO principles -- **analytics-tracking**: For setting up test measurement +- **cro**: For generating test ideas based on CRO principles +- **analytics**: For setting up test measurement - **copywriting**: For creating variant copy diff --git a/src/adclaw/agents/skills/marketing-ab-test-setup/evals/evals.json b/src/adclaw/agents/skills/marketing-ab-test-setup/evals/evals.json new file mode 100644 index 0000000..7ef70da --- /dev/null +++ b/src/adclaw/agents/skills/marketing-ab-test-setup/evals/evals.json @@ -0,0 +1,105 @@ +{ + "skill_name": "ab-testing", + "evals": [ + { + "id": 1, + "prompt": "I want to A/B test our homepage headline. We currently say 'The All-in-One Project Management Tool' and want to test something benefit-focused. We get about 15,000 visitors/month and our current signup rate is 3.2%.", + "expected_output": "Should check for product-marketing.md first. Should build a proper hypothesis using the framework: 'Because [observation], we believe [change] will cause [outcome], which we'll measure by [metric].' Should identify this as an A/B test (two variants). Should calculate or reference sample size needs based on 15,000 monthly visitors and 3.2% baseline. Should define primary metric (signup rate), secondary metrics, and guardrail metrics. Should warn about the peeking problem and recommend a fixed test duration. Should provide the test plan in the structured output format.", + "assertions": [ + "Checks for product-marketing.md", + "Uses the hypothesis framework with observation, belief, outcome, and metric", + "Identifies as A/B test type", + "Addresses sample size calculation based on traffic and baseline rate", + "Defines primary metric (signup rate)", + "Defines secondary and guardrail metrics", + "Warns about the peeking problem", + "Provides structured test plan output" + ], + "files": [] + }, + { + "id": 2, + "prompt": "we want to test like 4 different CTA button colors on our pricing page. is that a good idea?", + "expected_output": "Should trigger on casual phrasing. Should identify this as an A/B/n test (multiple variants). Should caution that testing 4 variants requires significantly more traffic than a simple A/B test. Should reference the sample size quick reference showing traffic multipliers for multiple variants. Should question whether button color alone is likely to produce meaningful lift vs testing CTA copy, placement, or surrounding context. Should recommend either reducing to 2 variants or ensuring sufficient traffic. Should still provide hypothesis framework and test setup if proceeding.", + "assertions": [ + "Triggers on casual phrasing", + "Identifies as A/B/n test (multiple variants)", + "Cautions about increased traffic needs for 4 variants", + "References sample size requirements", + "Questions whether button color alone is high-impact", + "Suggests alternative higher-impact elements to test", + "Provides hypothesis framework" + ], + "files": [] + }, + { + "id": 3, + "prompt": "Our test has been running for 3 days and Variant B is winning with 95% confidence. Should we call it?", + "expected_output": "Should immediately address the peeking problem. Should explain that checking results early inflates false positive rates. Should recommend running for the full pre-calculated duration regardless of early results. Should explain why early significance can be misleading (regression to the mean, day-of-week effects, audience mix shifts). Should provide guidance on when it IS appropriate to stop early (sequential testing methods). Should recommend the pre-test commitment to duration.", + "assertions": [ + "Addresses the peeking problem directly", + "Explains why early significance is misleading", + "Recommends running for full pre-calculated duration", + "Mentions day-of-week effects or audience mix shifts", + "Explains false positive rate inflation from peeking", + "Mentions sequential testing as alternative approach" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Help me set up a multivariate test on our landing page. I want to test the headline, hero image, and CTA button simultaneously.", + "expected_output": "Should identify this as a Multivariate Test (MVT). Should explain that MVT tests combinations of elements and requires much more traffic than A/B tests. Should calculate or reference traffic needs (combinations multiply: e.g., 2 headlines × 2 images × 2 CTAs = 8 combinations). Should recommend MVT only if traffic supports it, otherwise suggest sequential A/B tests. Should build hypotheses for each element being tested. Should define interaction effects to watch for. Should provide structured test plan.", + "assertions": [ + "Identifies as multivariate test (MVT)", + "Explains MVT tests combinations of elements", + "Addresses dramatically higher traffic requirements", + "Calculates number of combinations", + "Suggests sequential A/B tests as alternative if traffic insufficient", + "Builds hypotheses for each element", + "Provides structured test plan" + ], + "files": [] + }, + { + "id": 5, + "prompt": "What metrics should I track for an A/B test on our trial signup page? We're testing a longer form (adds company size and role fields) against the current short form.", + "expected_output": "Should apply the metrics selection framework with three tiers: primary, secondary, and guardrail metrics. Primary: form completion rate (the direct conversion metric). Secondary: lead quality metrics (SQL conversion rate, activation rate post-signup). Guardrail: overall signup volume (ensure longer form doesn't tank total signups below acceptable threshold). Should explain the tradeoff between conversion quantity and lead quality. Should note that this test needs longer observation window to measure downstream metrics.", + "assertions": [ + "Applies three-tier metric framework (primary, secondary, guardrail)", + "Identifies form completion rate as primary metric", + "Identifies lead quality as secondary metric", + "Defines guardrail metrics to protect against negative outcomes", + "Explains quantity vs quality tradeoff", + "Notes need for longer observation window for downstream metrics" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you help me write copy for our new landing page? We want to test it against the current version.", + "expected_output": "Should recognize this is primarily a copywriting task, not a test setup task. Should defer to or cross-reference the copywriting skill for writing the actual copy. May help frame the test hypothesis and setup, but should make clear that copywriting is the right skill for creating the page copy itself.", + "assertions": [ + "Recognizes this as primarily a copywriting task", + "References or defers to copywriting skill", + "Does not attempt to write full page copy using test setup patterns", + "May offer to help with test hypothesis and setup" + ], + "files": [] + }, + { + "id": 7, + "prompt": "We ran an A/B test on our pricing page for 4 weeks. Control: 2.1% conversion. Variant: 2.4% conversion. 12,000 visitors per variant. Is this statistically significant? Should we ship it?", + "expected_output": "Should evaluate the results against statistical significance criteria. Should calculate or estimate whether the sample size is sufficient to detect a 0.3 percentage point lift from a 2.1% baseline (this is a ~14% relative lift). Should reference the 95% confidence threshold. Should discuss practical significance vs statistical significance. Should recommend whether to ship, continue testing, or iterate. Should consider segment analysis if results are borderline.", + "assertions": [ + "Evaluates against statistical significance criteria", + "Addresses whether sample size is sufficient for this effect size", + "References 95% confidence threshold", + "Distinguishes statistical significance from practical significance", + "Provides clear recommendation on shipping", + "Suggests segment analysis or follow-up if borderline" + ], + "files": [] + } + ] +} diff --git a/src/adclaw/agents/skills/marketing-ad-creative/SKILL.md b/src/adclaw/agents/skills/marketing-ad-creative/SKILL.md index 7dd2709..99b483e 100644 --- a/src/adclaw/agents/skills/marketing-ad-creative/SKILL.md +++ b/src/adclaw/agents/skills/marketing-ad-creative/SKILL.md @@ -1,8 +1,8 @@ --- name: ad-creative -description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' or 'ad performance optimization.' This skill covers generating ad creative at scale, iterating based on performance data, and enforcing platform character limits. For campaign strategy and targeting, see paid-ads. For landing page copy, see copywriting." +description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting." metadata: - version: 1.1.0 + version: 2.0.0 --- # Ad Creative @@ -12,7 +12,7 @@ You are an expert performance creative strategist. Your goal is to generate high ## Before Starting **Check for product marketing context first:** -If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. Gather this context (ask if not provided): @@ -64,7 +64,7 @@ Pull performance data → Identify winning patterns → Generate new variations ## Platform Specs -**Always enforce these limits.** Never deliver creative that exceeds platform character limits. +Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering. ### Google Ads (Responsive Search Ads) @@ -320,7 +320,7 @@ For large-scale creative production (Anthropic's growth team generates 100+ vari - **Writing headlines that only work together** — RSA headlines get combined randomly - **Ignoring character limits** — Platforms truncate without warning - **All variations sound the same** — Vary angles, not just word choice -- **No CTA headlines** — Always include action-oriented headlines +- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3 - **Generic descriptions** — "Learn more about our solution" wastes the slot - **Iterating without data** — Gut feelings are less reliable than metrics - **Testing too many things at once** — Change one variable per test cycle @@ -355,8 +355,8 @@ node tools/clis/google-ads.js reports get --type ad_performance --date-range las ## Related Skills -- **paid-ads**: For campaign strategy, targeting, budgets, and optimization +- **ads**: For campaign strategy, targeting, budgets, and optimization - **copywriting**: For landing page copy (where ad traffic lands) -- **ab-test-setup**: For structuring creative tests with statistical rigor +- **ab-testing**: For structuring creative tests with statistical rigor - **marketing-psychology**: For psychological principles behind high-performing creative - **copy-editing**: For polishing ad copy before launch diff --git a/src/adclaw/agents/skills/marketing-ad-creative/evals/evals.json b/src/adclaw/agents/skills/marketing-ad-creative/evals/evals.json new file mode 100644 index 0000000..63f10a7 --- /dev/null +++ b/src/adclaw/agents/skills/marketing-ad-creative/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "ad-creative", + "evals": [ + { + "id": 1, + "prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.", + "expected_output": "Should check for product-marketing.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.", + "assertions": [ + "Checks for product-marketing.md", + "Uses angle-based generation approach", + "Identifies multiple angles (3-5)", + "Respects Meta character limits (125/40/30)", + "Generates multiple variations per angle", + "Suggests image or visual direction", + "Includes hook, body, and CTA for each", + "Recommends which angles to test first" + ], + "files": [] + }, + { + "id": 2, + "prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.", + "expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.", + "assertions": [ + "Respects Google RSA character limits (30 char headlines, 90 char descriptions)", + "Generates 10-15 headline variations", + "Generates 4+ description variations", + "Includes target keyword in headlines", + "Notes pinning should be used sparingly per skill guidance", + "Suggests ad extensions", + "Uses angle-based variation approach" + ], + "files": [] + }, + { + "id": 3, + "prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.", + "expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.", + "assertions": [ + "Activates iteration mode based on performance data", + "Analyzes CTR, CPC, and conversion rate for each ad", + "Identifies winning angles from the data", + "Recommends pausing or reworking underperforming creative", + "Generates new variations combining winning elements", + "Provides specific iterations on top performers" + ], + "files": [] + }, + { + "id": 4, + "prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.", + "expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) — more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).", + "assertions": [ + "Triggers on casual phrasing", + "Respects LinkedIn character limits (150/70/100)", + "Adapts tone for enterprise security audience", + "Uses risk-reduction and compliance language", + "Provides multiple angles relevant to security buyers", + "Suggests LinkedIn ad format recommendations" + ], + "files": [] + }, + { + "id": 5, + "prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.", + "expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.", + "assertions": [ + "Activates batch generation workflow", + "Generates for all three platforms", + "Respects each platform's character limits", + "Identifies angles that work across platforms", + "Notes TikTok needs video concepts", + "Organizes output by platform", + "Generates multiple variations per angle per platform" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.", + "expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that ads is the right skill for strategy.", + "assertions": [ + "Recognizes this as paid ads strategy, not creative generation", + "References or defers to ads skill", + "Does not attempt full campaign strategy using creative generation patterns" + ], + "files": [] + } + ] +} diff --git a/src/adclaw/agents/skills/marketing-ad-creative/references/generative-tools.md b/src/adclaw/agents/skills/marketing-ad-creative/references/generative-tools.md index e22ebce..b1e6fec 100644 --- a/src/adclaw/agents/skills/marketing-ad-creative/references/generative-tools.md +++ b/src/adclaw/agents/skills/marketing-ad-creative/references/generative-tools.md @@ -8,7 +8,7 @@ Reference for using AI image generators, video generators, and code-based video | Need | Tool Category | Best Fit | |------|---------------|----------| -| Static ad images (banners, social) | Image generation | Nano Banana Pro, Flux, Ideogram | +| Static ad images (banners, social) | Image generation | ChatGPT Images 2.0, Nano Banana Pro, Flux, Ideogram | | Ad images with text overlays | Image generation (text-capable) | Ideogram, Nano Banana Pro | | Short video ads (6-30 sec) | Video generation | Veo, Kling, Runway, Sora, Seedance | | Video ads with voiceover | Video gen + voice | Veo/Sora (native), or Runway + ElevenLabs | diff --git a/src/adclaw/agents/skills/marketing-ai-seo/SKILL.md b/src/adclaw/agents/skills/marketing-ai-seo/SKILL.md index eb864f1..320a51c 100644 --- a/src/adclaw/agents/skills/marketing-ai-seo/SKILL.md +++ b/src/adclaw/agents/skills/marketing-ai-seo/SKILL.md @@ -1,8 +1,8 @@ --- name: ai-seo -description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' or 'zero-click search.' This skill covers content optimization for AI answer engines, monitoring AI visibility, and getting cited as a source. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup." +description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema." metadata: - version: 1.1.0 + version: 2.0.1 --- # AI SEO @@ -12,7 +12,7 @@ You are an expert in AI search optimization — the practice of making content d ## Before Starting **Check for product marketing context first:** -If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. +If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task. Gather this context (ask if not provided): @@ -66,6 +66,45 @@ In traditional search, you need to rank on page 1. In AI search, a well-structur - Optimized content gets cited 3x more often than non-optimized - Statistics and citations boost visibility by 40%+ across queries +### Google's Official Stance vs. Multi-Platform Reality + +This is important to read once before doing anything else. + +**Google's position** ([AI features optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)): +> "The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems." + +Google explicitly says: +- **No special markup or files are required** for AI Overviews or AI Mode +- **Don't chunk content for AI** — write for people, organize with normal headings and paragraphs +- **Don't write separate content for AI** — that risks "scaled content abuse" spam policy +- **Helpful, reliable, people-first content** wins — same E-E-A-T standards as regular Search +- **No AI-specific Search Console reporting** — use standard SEO metrics + +**Other AI engines (ChatGPT, Claude, Perplexity, Copilot) behave differently:** +- They actively reward extractable structure — passages, FAQs, comparison tables, definition blocks +- They parse `llms.txt`, structured pricing pages, and machine-readable files when present +- They cite third-party sources (Reddit, Wikipedia, review sites) more heavily than top-ranked pages + +**What this means for the work:** +- The structural patterns in this skill (40–60 word answer blocks, FAQ schema, comparison tables) help **non-Google AI engines** materially. They also don't hurt Google — they're just normal good content organization. +- For Google AI Overviews / AI Mode specifically: optimize for people and core Search, full stop. Strong E-E-A-T, original information, semantic HTML, clean indexability. +- For ChatGPT/Claude/Perplexity: layer on the extractable structure + llms.txt + machine-readable files. + +When in doubt, default to "write for people, organize for clarity" — that satisfies both camps. + +### Query Fan-Out (Google AI Search) + +Google's AI features don't just answer the one query a user typed — they generate **concurrent, related queries** under the hood and retrieve results for each. + +Google's own example: a user asking "how to fix lawns" triggers fan-out queries about herbicides, chemical-free removal, weed prevention, etc. The AI synthesizes across all of them. + +**Implications:** +- Single-page-per-keyword targeting is less effective. Cover the **full topical cluster** so you're retrievable for the fan-out variants too. +- Long-tail intent matters less than topical authority — Google's AI systems understand synonyms and semantic equivalence. +- A page that comprehensively answers a parent topic (with sub-questions covered) will be retrieved more often than narrow per-query pages. + +**Action**: when planning content, brainstorm the 5–10 related queries the AI is likely to fan out to and make sure your content (or your site as a whole) covers them. + --- ## AI Visibility Audit @@ -226,6 +265,54 @@ AI systems don't just cite your website — they cite where you appear. - Create YouTube content for key how-to queries - Answer relevant Quora questions with depth +### Machine-Readable Files for AI Agents + +> **Google's stance**: not required for AI Overviews or AI Mode. Their guide explicitly says you don't need new markup, AI files, or markdown to appear in generative AI search. +> +> **Why include them anyway**: non-Google AI engines (ChatGPT, Claude, Perplexity) and autonomous buying agents do reward extractable structure. The files below help with those engines without harming Google. + +AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read. + +Add these machine-readable files to your site root: + +**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents + +```markdown +# Pricing — [Your Product Name] + +## Free +- Price: $0/month +- Limits: 100 emails/month, 1 user +- Features: Basic templates, API access + +## Pro +- Price: $29/month (billed annually) | $35/month (billed monthly) +- Limits: 10,000 emails/month, 5 users +- Features: Custom domains, analytics, priority support + +## Enterprise +- Price: Custom — contact sales@example.com +- Limits: Unlimited emails, unlimited users +- Features: SSO, SLA, dedicated account manager +``` + +**Why this matters now:** +- AI agents increasingly compare products programmatically before a human ever visits your site +- Opaque pricing gets filtered out of AI-mediated buying journeys +- A simple markdown file is trivially parseable by any LLM — no rendering, no JavaScript, no login walls +- Same principle as `robots.txt` (for crawlers), `llms.txt` (for AI context), and `AGENTS.md` (for agent capabilities) + +**Best practices:** +- Use consistent units (monthly vs. annual, per-seat vs. flat) +- Include specific limits and thresholds, not just feature names +- List what's included at each tier, not just what's different +- Keep it updated — stale pricing is worse than no file +- Link to it from your sitemap and main pricing page + +**`/llms.txt`** — Context file for AI systems (see [llmstxt.org](https://llmstxt.org)) + +If you don't have one yet, add an `llms.txt` that gives AI systems a quick overview of what your product does, who it's for, and links to key pages (including your pricing). + ### Schema Markup for AI Structured data helps AI systems understand your content. Key schemas: @@ -240,7 +327,32 @@ Structured data helps AI systems understand your content. Key schemas: | Reviews | `Review`, `AggregateRating` | Trust signals | | Organization | `Organization` | Entity recognition | -Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill. +Content with proper schema shows 30-40% higher AI visibility on non-Google AI engines. **Google's note**: structured data is "not required for generative AI search" but is recommended for overall SEO strategy. For implementation, use the **schema** skill. + +--- + +## Agentic Experiences + +Beyond AI search engines summarizing content, autonomous agents are starting to access sites directly — clicking, reading, comparing, even buying on behalf of users. Google's guide flags this as an emerging category to plan for. + +**How agents access your site:** +- **Visual rendering** — they screenshot/read the page like a user would +- **DOM inspection** — they parse the page's HTML structure +- **Accessibility tree** — they rely on the same semantic information assistive tech uses (labels, roles, landmarks, headings) + +**What to do:** +- **Render meaningful content without heavy JS gymnastics** — if the page is blank until 4 frameworks finish loading, agents see blank +- **Semantic HTML** — use `
`, `