From 050c42e3814d15603f36a14590887aee37bd88d1 Mon Sep 17 00:00:00 2001 From: Sergei Aronsen Date: Wed, 20 May 2026 14:26:15 +0200 Subject: [PATCH] feat(skills): bulk-mirror 40 marketing skills + migrate to canonical upstream (v6.51.0) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bulk skills-marketplace expansion: 40 marketing skills from coreyhaines31/marketingskills (29.6k★ canonical upstream, MIT) at pinned commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce. Active skills_pins jumps 23 → 61. Added (38 new): ab-testing, ad-creative, ads, ai-seo, analytics, aso, churn-prevention, co-marketing, cold-email, community-marketing, competitor-profiling, competitors, content-strategy, copy-editing, cro, customer-research, directory-submissions, emails, free-tools, image, launch, lead-magnets, marketing-ideas, marketing-psychology, onboarding, paywalls, popups, pricing, product-marketing, programmatic-seo, referrals, revops, sales-enablement, schema, signup, site-architecture, social, video Migrated (2 — upstream re-anchor): copywriting + seo-audit: upstream source changed from mysticaltech/marketingskills (246★ fork) → coreyhaines31/marketingskills (29.6k★ canonical). Mirror content + sha256 refreshed. Retained (2 — distinct names): ab-test-setup + analytics-tracking keep mysticaltech source because coreyhaines31 names them ab-testing + analytics (renamed in mysticaltech fork). Both variants coexist intentionally. Each skill mirror includes the full SKILL.md + references/*.md + evals/evals.json layout. 157 files added/modified across the 40 skill dirs. Lockstep bump: manifest.version 6.50.0 → 6.51.0, 9 installer scripts TK_TOOLKIT_REF bumped, templates/skills-catalog.json regenerated (23 → 61 entries), skills_pins_note active count 23 → 61. Co-Authored-By: Claude Opus 4.7 (1M context) --- CHANGELOG.md | 92 +++ manifest.json | 478 ++++++++++++- scripts/init-claude.sh | 2 +- scripts/install-statusline.sh | 2 +- scripts/install.sh | 2 +- scripts/migrate-to-complement.sh | 2 +- scripts/setup-council.sh | 2 +- scripts/setup-prompt-engineer.sh | 2 +- scripts/setup-security.sh | 2 +- scripts/uninstall.sh | 2 +- scripts/update-claude.sh | 2 +- templates/skills-catalog.json | 324 ++++++++- .../skills-marketplace/ab-testing/SKILL.md | 353 ++++++++++ .../ab-testing/evals/evals.json | 105 +++ .../references/sample-size-guide.md | 263 ++++++++ .../ab-testing/references/test-templates.md | 277 ++++++++ .../skills-marketplace/ad-creative/SKILL.md | 362 ++++++++++ .../ad-creative/evals/evals.json | 90 +++ .../references/generative-tools.md | 637 ++++++++++++++++++ .../ad-creative/references/platform-specs.md | 213 ++++++ templates/skills-marketplace/ads/SKILL.md | 317 +++++++++ .../skills-marketplace/ads/evals/evals.json | 90 +++ .../ads/references/ad-copy-templates.md | 207 ++++++ .../ads/references/audience-targeting.md | 243 +++++++ .../ads/references/conversion-tracking.md | 361 ++++++++++ .../references/platform-setup-checklists.md | 277 ++++++++ templates/skills-marketplace/ai-seo/SKILL.md | 485 +++++++++++++ .../ai-seo/evals/evals.json | 90 +++ .../ai-seo/references/content-patterns.md | 285 ++++++++ .../ai-seo/references/content-types.md | 71 ++ .../references/platform-ranking-factors.md | 152 +++++ .../skills-marketplace/analytics/SKILL.md | 309 +++++++++ .../analytics/evals/evals.json | 90 +++ .../analytics/references/event-library.md | 260 +++++++ .../references/ga4-implementation.md | 300 +++++++++ .../references/gtm-implementation.md | 390 +++++++++++ templates/skills-marketplace/aso/SKILL.md | 312 +++++++++ .../skills-marketplace/aso/evals/evals.json | 91 +++ .../aso/references/apple-specs.md | 107 +++ .../aso/references/benchmarks.md | 129 ++++ .../aso/references/google-play-specs.md | 131 ++++ .../aso/references/report-template.md | 213 ++++++ .../aso/references/scoring-criteria.md | 213 ++++++ .../churn-prevention/SKILL.md | 424 ++++++++++++ .../churn-prevention/evals/evals.json | 93 +++ .../references/cancel-flow-patterns.md | 316 +++++++++ .../references/dunning-playbook.md | 408 +++++++++++ .../skills-marketplace/co-marketing/SKILL.md | 290 ++++++++ .../co-marketing/evals/evals.json | 84 +++ .../skills-marketplace/cold-email/SKILL.md | 158 +++++ .../cold-email/evals/evals.json | 94 +++ .../cold-email/references/benchmarks.md | 83 +++ .../references/follow-up-sequences.md | 81 +++ .../cold-email/references/frameworks.md | 90 +++ .../cold-email/references/personalization.md | 79 +++ .../cold-email/references/subject-lines.md | 53 ++ .../community-marketing/SKILL.md | 163 +++++ .../community-marketing/evals/evals.json | 89 +++ .../competitor-profiling/SKILL.md | 411 +++++++++++ .../competitor-profiling/evals/evals.json | 85 +++ .../references/templates.md | 167 +++++ .../references/tool-reference.md | 179 +++++ .../skills-marketplace/competitors/SKILL.md | 256 +++++++ .../competitors/evals/evals.json | 93 +++ .../references/content-architecture.md | 271 ++++++++ .../competitors/references/templates.md | 223 ++++++ .../content-strategy/SKILL.md | 365 ++++++++++ .../content-strategy/evals/evals.json | 90 +++ .../references/headless-cms.md | 194 ++++++ .../skills-marketplace/copy-editing/SKILL.md | 457 +++++++++++++ .../copy-editing/evals/evals.json | 89 +++ .../copy-editing/references/checklist.md | 66 ++ .../references/content-refresh.md | 38 ++ .../references/plain-english-alternatives.md | 394 +++++++++++ .../copywriting/SKILL-LICENSE.md | 12 - .../skills-marketplace/copywriting/SKILL.md | 50 +- .../copywriting/evals/evals.json | 8 +- .../copywriting/references/copy-frameworks.md | 26 - .../references/natural-transitions.md | 4 - templates/skills-marketplace/cro/SKILL.md | 187 +++++ .../skills-marketplace/cro/evals/evals.json | 111 +++ .../cro/references/experiments.md | 248 +++++++ .../skills-marketplace/cro/references/form.md | 422 ++++++++++++ .../customer-research/SKILL.md | 270 ++++++++ .../customer-research/evals/evals.json | 162 +++++ .../references/source-guides.md | 401 +++++++++++ .../directory-submissions/SKILL.md | 381 +++++++++++ .../directory-submissions/evals/evals.json | 94 +++ .../references/directory-list.md | 477 +++++++++++++ .../references/positioning-variations.md | 232 +++++++ .../submission-tracker-template.csv | 266 ++++++++ templates/skills-marketplace/emails/SKILL.md | 311 +++++++++ .../emails/evals/evals.json | 93 +++ .../emails/references/copy-guidelines.md | 113 ++++ .../emails/references/email-types.md | 515 ++++++++++++++ .../emails/references/sequence-templates.md | 168 +++++ .../skills-marketplace/free-tools/SKILL.md | 179 +++++ .../free-tools/evals/evals.json | 90 +++ .../free-tools/references/tool-types.md | 217 ++++++ templates/skills-marketplace/image/SKILL.md | 340 ++++++++++ .../skills-marketplace/image/evals/evals.json | 89 +++ .../image/references/ai-image-prompting.md | 229 +++++++ templates/skills-marketplace/launch/SKILL.md | 353 ++++++++++ .../launch/evals/evals.json | 91 +++ .../skills-marketplace/lead-magnets/SKILL.md | 310 +++++++++ .../lead-magnets/evals/evals.json | 87 +++ .../lead-magnets/references/benchmarks.md | 129 ++++ .../lead-magnets/references/format-guide.md | 196 ++++++ .../marketing-ideas/SKILL.md | 167 +++++ .../marketing-ideas/evals/evals.json | 90 +++ .../references/ideas-by-category.md | 366 ++++++++++ .../marketing-psychology/SKILL.md | 455 +++++++++++++ .../marketing-psychology/evals/evals.json | 88 +++ .../skills-marketplace/onboarding/SKILL.md | 220 ++++++ .../onboarding/evals/evals.json | 92 +++ .../onboarding/references/experiments.md | 258 +++++++ .../skills-marketplace/paywalls/SKILL.md | 227 +++++++ .../paywalls/evals/evals.json | 93 +++ .../paywalls/references/experiments.md | 164 +++++ templates/skills-marketplace/popups/SKILL.md | 454 +++++++++++++ .../popups/evals/evals.json | 94 +++ templates/skills-marketplace/pricing/SKILL.md | 231 +++++++ .../pricing/evals/evals.json | 90 +++ .../pricing/references/research-methods.md | 152 +++++ .../pricing/references/tier-structure.md | 232 +++++++ .../product-marketing/SKILL.md | 241 +++++++ .../product-marketing/evals/evals.json | 85 +++ .../programmatic-seo/SKILL.md | 238 +++++++ .../programmatic-seo/evals/evals.json | 94 +++ .../programmatic-seo/references/playbooks.md | 308 +++++++++ .../skills-marketplace/referrals/SKILL.md | 257 +++++++ .../referrals/evals/evals.json | 89 +++ .../references/affiliate-programs.md | 167 +++++ .../referrals/references/program-examples.md | 143 ++++ templates/skills-marketplace/revops/SKILL.md | 345 ++++++++++ .../revops/evals/evals.json | 91 +++ .../revops/references/automation-playbooks.md | 290 ++++++++ .../references/lifecycle-definitions.md | 278 ++++++++ .../revops/references/routing-rules.md | 203 ++++++ .../revops/references/scoring-models.md | 247 +++++++ .../sales-enablement/SKILL.md | 359 ++++++++++ .../sales-enablement/evals/evals.json | 91 +++ .../references/deck-frameworks.md | 263 ++++++++ .../references/demo-scripts.md | 355 ++++++++++ .../references/objection-library.md | 270 ++++++++ .../references/one-pager-templates.md | 208 ++++++ templates/skills-marketplace/schema/SKILL.md | 179 +++++ .../schema/evals/evals.json | 87 +++ .../schema/references/schema-examples.md | 398 +++++++++++ .../seo-audit/SKILL-LICENSE.md | 12 - .../skills-marketplace/seo-audit/SKILL.md | 139 ++-- .../seo-audit/evals/evals.json | 8 +- .../references/ai-writing-detection.md | 8 - .../seo-audit/references/international-seo.md | 230 +++++++ templates/skills-marketplace/signup/SKILL.md | 359 ++++++++++ .../signup/evals/evals.json | 88 +++ .../site-architecture/SKILL.md | 357 ++++++++++ .../site-architecture/evals/evals.json | 88 +++ .../references/mermaid-templates.md | 216 ++++++ .../references/navigation-patterns.md | 305 +++++++++ .../references/site-type-templates.md | 293 ++++++++ templates/skills-marketplace/social/SKILL.md | 409 +++++++++++ .../social/evals/evals.json | 92 +++ .../social/references/platform-limits.md | 110 +++ .../social/references/platforms.md | 170 +++++ .../social/references/post-templates.md | 177 +++++ .../social/references/reverse-engineering.md | 195 ++++++ .../social/references/short-form-video.md | 237 +++++++ templates/skills-marketplace/video/SKILL.md | 342 ++++++++++ .../skills-marketplace/video/evals/evals.json | 88 +++ .../video/references/ai-video-prompting.md | 175 +++++ 171 files changed, 33747 insertions(+), 189 deletions(-) create mode 100644 templates/skills-marketplace/ab-testing/SKILL.md create mode 100644 templates/skills-marketplace/ab-testing/evals/evals.json create mode 100644 templates/skills-marketplace/ab-testing/references/sample-size-guide.md create mode 100644 templates/skills-marketplace/ab-testing/references/test-templates.md create mode 100644 templates/skills-marketplace/ad-creative/SKILL.md create mode 100644 templates/skills-marketplace/ad-creative/evals/evals.json create mode 100644 templates/skills-marketplace/ad-creative/references/generative-tools.md create mode 100644 templates/skills-marketplace/ad-creative/references/platform-specs.md create mode 100644 templates/skills-marketplace/ads/SKILL.md create mode 100644 templates/skills-marketplace/ads/evals/evals.json create mode 100644 templates/skills-marketplace/ads/references/ad-copy-templates.md create mode 100644 templates/skills-marketplace/ads/references/audience-targeting.md create mode 100644 templates/skills-marketplace/ads/references/conversion-tracking.md create mode 100644 templates/skills-marketplace/ads/references/platform-setup-checklists.md create mode 100644 templates/skills-marketplace/ai-seo/SKILL.md create mode 100644 templates/skills-marketplace/ai-seo/evals/evals.json create mode 100644 templates/skills-marketplace/ai-seo/references/content-patterns.md create mode 100644 templates/skills-marketplace/ai-seo/references/content-types.md create mode 100644 templates/skills-marketplace/ai-seo/references/platform-ranking-factors.md create mode 100644 templates/skills-marketplace/analytics/SKILL.md create mode 100644 templates/skills-marketplace/analytics/evals/evals.json create mode 100644 templates/skills-marketplace/analytics/references/event-library.md create mode 100644 templates/skills-marketplace/analytics/references/ga4-implementation.md create mode 100644 templates/skills-marketplace/analytics/references/gtm-implementation.md create mode 100644 templates/skills-marketplace/aso/SKILL.md create mode 100644 templates/skills-marketplace/aso/evals/evals.json create mode 100644 templates/skills-marketplace/aso/references/apple-specs.md create mode 100644 templates/skills-marketplace/aso/references/benchmarks.md create mode 100644 templates/skills-marketplace/aso/references/google-play-specs.md create mode 100644 templates/skills-marketplace/aso/references/report-template.md create mode 100644 templates/skills-marketplace/aso/references/scoring-criteria.md create mode 100644 templates/skills-marketplace/churn-prevention/SKILL.md create mode 100644 templates/skills-marketplace/churn-prevention/evals/evals.json create mode 100644 templates/skills-marketplace/churn-prevention/references/cancel-flow-patterns.md create mode 100644 templates/skills-marketplace/churn-prevention/references/dunning-playbook.md create mode 100644 templates/skills-marketplace/co-marketing/SKILL.md create mode 100644 templates/skills-marketplace/co-marketing/evals/evals.json create mode 100644 templates/skills-marketplace/cold-email/SKILL.md create mode 100644 templates/skills-marketplace/cold-email/evals/evals.json create mode 100644 templates/skills-marketplace/cold-email/references/benchmarks.md create mode 100644 templates/skills-marketplace/cold-email/references/follow-up-sequences.md create mode 100644 templates/skills-marketplace/cold-email/references/frameworks.md create mode 100644 templates/skills-marketplace/cold-email/references/personalization.md create mode 100644 templates/skills-marketplace/cold-email/references/subject-lines.md create mode 100644 templates/skills-marketplace/community-marketing/SKILL.md create mode 100644 templates/skills-marketplace/community-marketing/evals/evals.json create mode 100644 templates/skills-marketplace/competitor-profiling/SKILL.md create mode 100644 templates/skills-marketplace/competitor-profiling/evals/evals.json create mode 100644 templates/skills-marketplace/competitor-profiling/references/templates.md create mode 100644 templates/skills-marketplace/competitor-profiling/references/tool-reference.md create mode 100644 templates/skills-marketplace/competitors/SKILL.md create mode 100644 templates/skills-marketplace/competitors/evals/evals.json create mode 100644 templates/skills-marketplace/competitors/references/content-architecture.md create mode 100644 templates/skills-marketplace/competitors/references/templates.md create mode 100644 templates/skills-marketplace/content-strategy/SKILL.md create mode 100644 templates/skills-marketplace/content-strategy/evals/evals.json create mode 100644 templates/skills-marketplace/content-strategy/references/headless-cms.md create mode 100644 templates/skills-marketplace/copy-editing/SKILL.md create mode 100644 templates/skills-marketplace/copy-editing/evals/evals.json create mode 100644 templates/skills-marketplace/copy-editing/references/checklist.md create mode 100644 templates/skills-marketplace/copy-editing/references/content-refresh.md create mode 100644 templates/skills-marketplace/copy-editing/references/plain-english-alternatives.md delete mode 100644 templates/skills-marketplace/copywriting/SKILL-LICENSE.md create mode 100644 templates/skills-marketplace/cro/SKILL.md create mode 100644 templates/skills-marketplace/cro/evals/evals.json create mode 100644 templates/skills-marketplace/cro/references/experiments.md create mode 100644 templates/skills-marketplace/cro/references/form.md create mode 100644 templates/skills-marketplace/customer-research/SKILL.md create mode 100644 templates/skills-marketplace/customer-research/evals/evals.json create mode 100644 templates/skills-marketplace/customer-research/references/source-guides.md create mode 100644 templates/skills-marketplace/directory-submissions/SKILL.md create mode 100644 templates/skills-marketplace/directory-submissions/evals/evals.json create mode 100644 templates/skills-marketplace/directory-submissions/references/directory-list.md create mode 100644 templates/skills-marketplace/directory-submissions/references/positioning-variations.md create mode 100644 templates/skills-marketplace/directory-submissions/references/submission-tracker-template.csv create mode 100644 templates/skills-marketplace/emails/SKILL.md create mode 100644 templates/skills-marketplace/emails/evals/evals.json create mode 100644 templates/skills-marketplace/emails/references/copy-guidelines.md create mode 100644 templates/skills-marketplace/emails/references/email-types.md create mode 100644 templates/skills-marketplace/emails/references/sequence-templates.md create mode 100644 templates/skills-marketplace/free-tools/SKILL.md create mode 100644 templates/skills-marketplace/free-tools/evals/evals.json create mode 100644 templates/skills-marketplace/free-tools/references/tool-types.md create mode 100644 templates/skills-marketplace/image/SKILL.md create mode 100644 templates/skills-marketplace/image/evals/evals.json create mode 100644 templates/skills-marketplace/image/references/ai-image-prompting.md create mode 100644 templates/skills-marketplace/launch/SKILL.md create mode 100644 templates/skills-marketplace/launch/evals/evals.json create mode 100644 templates/skills-marketplace/lead-magnets/SKILL.md create mode 100644 templates/skills-marketplace/lead-magnets/evals/evals.json create mode 100644 templates/skills-marketplace/lead-magnets/references/benchmarks.md create mode 100644 templates/skills-marketplace/lead-magnets/references/format-guide.md create mode 100644 templates/skills-marketplace/marketing-ideas/SKILL.md create mode 100644 templates/skills-marketplace/marketing-ideas/evals/evals.json create mode 100644 templates/skills-marketplace/marketing-ideas/references/ideas-by-category.md create mode 100644 templates/skills-marketplace/marketing-psychology/SKILL.md create mode 100644 templates/skills-marketplace/marketing-psychology/evals/evals.json create mode 100644 templates/skills-marketplace/onboarding/SKILL.md create mode 100644 templates/skills-marketplace/onboarding/evals/evals.json create mode 100644 templates/skills-marketplace/onboarding/references/experiments.md create mode 100644 templates/skills-marketplace/paywalls/SKILL.md create mode 100644 templates/skills-marketplace/paywalls/evals/evals.json create mode 100644 templates/skills-marketplace/paywalls/references/experiments.md create mode 100644 templates/skills-marketplace/popups/SKILL.md create mode 100644 templates/skills-marketplace/popups/evals/evals.json create mode 100644 templates/skills-marketplace/pricing/SKILL.md create mode 100644 templates/skills-marketplace/pricing/evals/evals.json create mode 100644 templates/skills-marketplace/pricing/references/research-methods.md create mode 100644 templates/skills-marketplace/pricing/references/tier-structure.md create mode 100644 templates/skills-marketplace/product-marketing/SKILL.md create mode 100644 templates/skills-marketplace/product-marketing/evals/evals.json create mode 100644 templates/skills-marketplace/programmatic-seo/SKILL.md create mode 100644 templates/skills-marketplace/programmatic-seo/evals/evals.json create mode 100644 templates/skills-marketplace/programmatic-seo/references/playbooks.md create mode 100644 templates/skills-marketplace/referrals/SKILL.md create mode 100644 templates/skills-marketplace/referrals/evals/evals.json create mode 100644 templates/skills-marketplace/referrals/references/affiliate-programs.md create mode 100644 templates/skills-marketplace/referrals/references/program-examples.md create mode 100644 templates/skills-marketplace/revops/SKILL.md create mode 100644 templates/skills-marketplace/revops/evals/evals.json create mode 100644 templates/skills-marketplace/revops/references/automation-playbooks.md create mode 100644 templates/skills-marketplace/revops/references/lifecycle-definitions.md create mode 100644 templates/skills-marketplace/revops/references/routing-rules.md create mode 100644 templates/skills-marketplace/revops/references/scoring-models.md create mode 100644 templates/skills-marketplace/sales-enablement/SKILL.md create mode 100644 templates/skills-marketplace/sales-enablement/evals/evals.json create mode 100644 templates/skills-marketplace/sales-enablement/references/deck-frameworks.md create mode 100644 templates/skills-marketplace/sales-enablement/references/demo-scripts.md create mode 100644 templates/skills-marketplace/sales-enablement/references/objection-library.md create mode 100644 templates/skills-marketplace/sales-enablement/references/one-pager-templates.md create mode 100644 templates/skills-marketplace/schema/SKILL.md create mode 100644 templates/skills-marketplace/schema/evals/evals.json create mode 100644 templates/skills-marketplace/schema/references/schema-examples.md delete mode 100644 templates/skills-marketplace/seo-audit/SKILL-LICENSE.md create mode 100644 templates/skills-marketplace/seo-audit/references/international-seo.md create mode 100644 templates/skills-marketplace/signup/SKILL.md create mode 100644 templates/skills-marketplace/signup/evals/evals.json create mode 100644 templates/skills-marketplace/site-architecture/SKILL.md create mode 100644 templates/skills-marketplace/site-architecture/evals/evals.json create mode 100644 templates/skills-marketplace/site-architecture/references/mermaid-templates.md create mode 100644 templates/skills-marketplace/site-architecture/references/navigation-patterns.md create mode 100644 templates/skills-marketplace/site-architecture/references/site-type-templates.md create mode 100644 templates/skills-marketplace/social/SKILL.md create mode 100644 templates/skills-marketplace/social/evals/evals.json create mode 100644 templates/skills-marketplace/social/references/platform-limits.md create mode 100644 templates/skills-marketplace/social/references/platforms.md create mode 100644 templates/skills-marketplace/social/references/post-templates.md create mode 100644 templates/skills-marketplace/social/references/reverse-engineering.md create mode 100644 templates/skills-marketplace/social/references/short-form-video.md create mode 100644 templates/skills-marketplace/video/SKILL.md create mode 100644 templates/skills-marketplace/video/evals/evals.json create mode 100644 templates/skills-marketplace/video/references/ai-video-prompting.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 34f5c386..fda29ea8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,98 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [6.51.0] - 2026-05-20 + +Bulk skills-marketplace expansion: 40 marketing skills from the canonical +`coreyhaines31/marketingskills` repo (29.6k★ upstream, MIT). Active +`skills_pins` count jumps `23 → 61` — the largest single skills shipment +since `v6.44.0`. + +### Added + +- **38 new marketing skills** mirrored from + [`coreyhaines31/marketingskills`](https://github.com/coreyhaines31/marketingskills) + at upstream commit `114587831efbe7ac5c0a86afcb69e9cca6f728ce`: + `ab-testing`, `ad-creative`, `ads`, `ai-seo`, `analytics`, `aso`, + `churn-prevention`, `co-marketing`, `cold-email`, `community-marketing`, + `competitor-profiling`, `competitors`, `content-strategy`, `copy-editing`, + `cro`, `customer-research`, `directory-submissions`, `emails`, + `free-tools`, `image`, `launch`, `lead-magnets`, `marketing-ideas`, + `marketing-psychology`, `onboarding`, `paywalls`, `popups`, `pricing`, + `product-marketing`, `programmatic-seo`, `referrals`, `revops`, + `sales-enablement`, `schema`, `signup`, `site-architecture`, `social`, + `video`. +- Each skill mirror includes its full `references/*.md` + `evals/evals.json` + layout (not just `SKILL.md`). +- 38 new entries in `manifest.json:skills_pins` (sha256-pinned with + reproducible `scripts/lib/skill-checksum.sh` hashing). +- 38 new entries in `files.skills_marketplace` so the skills install via + `init-claude.sh` / `update-claude.sh`. + +### Migrated + +- **`copywriting` skill** — upstream source migrated from the + `mysticaltech/marketingskills` downstream fork (246★) to the canonical + `coreyhaines31/marketingskills` upstream (29.6k★). Mirror content + refreshed; sha256 updated. +- **`seo-audit` skill** — same migration as above. The two repos diverged + in content over time; this release re-anchors on the canonical source. + +The existing `ab-test-setup` and `analytics-tracking` pins keep their +`mysticaltech/marketingskills` source — the corresponding `coreyhaines31` +skills are pinned under different names (`ab-testing`, `analytics`) +because mysticaltech renamed them during its fork. Both variants coexist +intentionally. + +### Why + +- `coreyhaines31/marketingskills` is the canonical upstream (29.6k★, MIT, + active development). The `mysticaltech` fork was used during v6.44.0 + because its README advertised "pre-built `.skill` files for easy + installation"; subsequent inspection showed that no `.skill` packaging + benefit applies inside the toolkit's mirror model (we ship the raw + `SKILL.md` + `references/*` tree). Re-anchoring on the upstream gives: + - direct drift tracking against the source of truth + - access to upstream's full skill catalog (40 vs mysticaltech's 25) + - first-class compatibility with future `references/` schema changes +- The 38 new skills fill major gaps in the toolkit's solo-developer + marketing surface: CRO (popups, paywalls, signup, onboarding), content + (content-strategy, programmatic-seo, ai-seo, schema), acquisition + (ads, cold-email, directory-submissions, free-tools), monetization + (pricing, paywalls), retention (churn-prevention, emails, referrals), + research (customer-research, competitor-profiling, competitors, + marketing-psychology). + +### Files changed + +- New: 38 mirror dirs under `templates/skills-marketplace//` plus + refreshed `copywriting/` and `seo-audit/` (157 total files across the + 40 skill dirs). +- Updated: `manifest.json` — version `6.50.0` → `6.51.0`, 38 new + `skills_pins` entries, 2 migrated `skills_pins` entries + (`copywriting`, `seo-audit`), 40 new `files.skills_marketplace` + entries, `skills_pins_note` count `22 → 61 active`. +- Updated: 9 installer scripts — `TK_TOOLKIT_REF` bumped to `v6.51.0`. +- Regenerated: `templates/skills-catalog.json` (`23 → 61` entries). + +### Upgrade path + +- End users: `/update-toolkit` pulls all 38 new skill mirrors + the + refreshed `copywriting` + `seo-audit` content. Skills appear in + Claude's skills discovery surface immediately. +- The mirror size grows by ~5 MB (skills-marketplace was ~1.5 MB, now + ~6.7 MB). Update time may be ~2x longer than usual on slow networks. + +### Compatibility + +- **No breaking changes** on the manifest schema or the + `skills_marketplace` install path. +- **Soft breaking on content** for users who depended on the exact + prior `copywriting` or `seo-audit` text — the canonical-upstream + content differs from the mysticaltech version. Behavior remains + semantically equivalent (both fork lineages share the same + `coreyhaines31` ancestor). + ## [6.50.0] - 2026-05-20 Two small additions: `humanizer` skill from `blader/humanizer` (Wikipedia diff --git a/manifest.json b/manifest.json index f5141aa3..337f2191 100644 --- a/manifest.json +++ b/manifest.json @@ -1,6 +1,6 @@ { "manifest_version": 2, - "version": "6.50.0", + "version": "6.51.0", "updated": "2026-05-20", "build_date": "2026-05-20", "description": "Claude Code Toolkit manifest for smart updates", @@ -63,8 +63,35 @@ "mirror_subset": "design-md//DESIGN.md (71 brands; README.md per brand intentionally not mirrored)" } }, - "skills_pins_note": "Pinned upstream HEAD of mirrored marketplace skills. Used by scripts/update-deps.sh probe_skill_pin to detect drift between this mirror and the canonical upstream repo. Current state (v6.50.0, 2026-05-20): 23 active pins + 1 no-upstream-found (memo-skill, exhaustive gh search yielded no canonical upstream \u2014 possibly toolkit-original or upstream deleted). Schema fields: repo, path (optional, for monorepo subpath probes via GitHub API), tag, commit, pinned_at, sha256 (mirror content checksum, reproducible across BSD/GNU via scripts/lib/skill-checksum.sh), _status \u2208 {active, no-upstream-found}. Trajectory: v6.35.0 (2 pins) \u2192 v6.37.0 (+path field, +3 anthropics monorepo) \u2192 v6.41.0 (+4 vercel/firecrawl) \u2192 v6.44.0 (+12 confirmed via gh code search + majiayu000/claude-skill-registry cross-reference) \u2192 v6.46.0 (+sha256 field, closed-loop sync, mirror\u2194manifest drift detection) \u2192 v6.47.0 (hardened sync: tab/newline-safe checksum, atomic mirror swap, post-checkout SHA verification, 3-way CLEAN/SOFT/DRIFT classification via --normalize so markdownlint-style cosmetic diffs do not trip --strict CI gate). Add new entries one at a time as upstream URLs are confirmed; do not invent. validate-manifest.py enforces note\u2194data consistency: any count referenced here must match the live skills_pins map AND every mirror sha256 must match the manifest-declared sha256.", + "skills_pins_note": "Pinned upstream HEAD of mirrored marketplace skills. Used by scripts/update-deps.sh probe_skill_pin to detect drift between this mirror and the canonical upstream repo. Current state (v6.51.0, 2026-05-20): 61 active pins + 1 no-upstream-found (memo-skill, exhaustive gh search yielded no canonical upstream \u2014 possibly toolkit-original or upstream deleted). Schema fields: repo, path (optional, for monorepo subpath probes via GitHub API), tag, commit, pinned_at, sha256 (mirror content checksum, reproducible across BSD/GNU via scripts/lib/skill-checksum.sh), _status \u2208 {active, no-upstream-found}. Trajectory: v6.35.0 (2 pins) \u2192 v6.37.0 (+path field, +3 anthropics monorepo) \u2192 v6.41.0 (+4 vercel/firecrawl) \u2192 v6.44.0 (+12 confirmed via gh code search + majiayu000/claude-skill-registry cross-reference) \u2192 v6.46.0 (+sha256 field, closed-loop sync, mirror\u2194manifest drift detection) \u2192 v6.47.0 (hardened sync: tab/newline-safe checksum, atomic mirror swap, post-checkout SHA verification, 3-way CLEAN/SOFT/DRIFT classification via --normalize so markdownlint-style cosmetic diffs do not trip --strict CI gate). Add new entries one at a time as upstream URLs are confirmed; do not invent. validate-manifest.py enforces note\u2194data consistency: any count referenced here must match the live skills_pins map AND every mirror sha256 must match the manifest-declared sha256.", "skills_pins": { + "ab-testing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/ab-testing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "9009bb5ce5b03267013a8f7b08d51cbf1ed5ba71218f10e0a553fc7c6e12d82b" + }, + "ad-creative": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/ad-creative", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "dcc14221a2b93f8ebb5333f46066a84bd664d1982070ed42f17dd39abe291384" + }, + "ads": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/ads", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "7025b6a6d5743742a0a251f3a78c0c47a64a79e60a81f4c98cf6c9d36268ad4f" + }, "ai-models": { "repo": "https://github.com/artofrawr/claude-control", "path": "plugins/learning/skills/ai-models", @@ -74,6 +101,24 @@ "_status": "active", "sha256": "ce4b7854d7d552b2ef5d8928532d321197277e6f15b2c224fc31f463225f442e" }, + "ai-seo": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/ai-seo", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "23f1727540159172e1864cd2d98e4d7555aef2a4cf1ddc9dd6ad7290e8746cc7" + }, + "analytics": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/analytics", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "0795c6546402694ab2a294fd00f03fd0f5092f5ae1d2b6832561916843b4414e" + }, "analytics-tracking": { "repo": "https://github.com/mysticaltech/marketingskills", "path": "skills/analytics-tracking", @@ -83,6 +128,15 @@ "_status": "active", "sha256": "1b401662f84f2ee72ea41dafa3f38a0de1be502c6043f815ac804551200592e6" }, + "aso": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/aso", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "1c6d894e9cd0b9a96fb2b9e5c065ccbe326c40ac95db86bf5dc75a005c3803bc" + }, "chrome-extension-development": { "repo": "https://github.com/Mindrally/skills", "path": "chrome-extension-development", @@ -92,14 +146,113 @@ "_status": "active", "sha256": "488dd06fc70ccdb3559a0ec6b42f0741a6f51ebfb02184152caa97f21ee385d3" }, + "churn-prevention": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/churn-prevention", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "29dfca240fdacf7d184190252fe89a1062624231ec1b119fecfae38ccce87a35" + }, + "co-marketing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/co-marketing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "53ff5ea9bd86300efbc470bb3278dcc289dc73e7fa4ab3bfa73748cde35c0bbb" + }, + "cold-email": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/cold-email", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "ffe3414375aaaba93859cc3f3b9bd37994236f5b48b5fb06f493b4ec3c8d8396" + }, + "community-marketing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/community-marketing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "1023e3b8e880e705ab90b478a1b58d7ce24b3c5eecd9c86ad2ee8f686cde7f96" + }, + "competitor-profiling": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/competitor-profiling", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "f67069814787cc1957771202ded70e84e5735287f1db2ff7c34c64b0694a3097" + }, + "competitors": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/competitors", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "4cb0a8c4f13254f8589a8b2d336e192e031360932d88f87627f934042abbd3d6" + }, + "content-strategy": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/content-strategy", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "3d446d4c8ed04d75e2d49bf0f1cb2a8133c25c13fe04c9841589ae423766eeca" + }, + "copy-editing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/copy-editing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "13b741dee5e784bed9e147a1508d4194916a80234bc3c2abb2dd394a771620dc" + }, "copywriting": { - "repo": "https://github.com/mysticaltech/marketingskills", + "repo": "https://github.com/coreyhaines31/marketingskills", "path": "skills/copywriting", "tag": null, - "commit": "2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96", - "pinned_at": "2026-05-18", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "8478f37d5bcec0193dd60335c611f590a3e33ac253c59e8b83912d2bb6385acb" + }, + "cro": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/cro", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", "_status": "active", - "sha256": "71f3560cdeb63fc3459e8f5f753ad83495d12edea4a9127ff45bedab407d102c" + "sha256": "e42ee2dc680fd189be9d6e2f925d5eaf133c655ff72bdbe57a83c741e80879ce" + }, + "customer-research": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/customer-research", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "5a36513965767de8571da89858f9dd4b250b55c84eeab3690087aae44714f577" + }, + "directory-submissions": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/directory-submissions", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "0852d65fdafe26a9e675bb7ff495367807132a59c693dbbfdb9a420593c19e9b" }, "docx": { "repo": "https://github.com/anthropics/skills", @@ -110,6 +263,15 @@ "_status": "active", "sha256": "950befc5c3ed716f839a362429debea9edbda31c15563281498d36dafbcbd4c5" }, + "emails": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/emails", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "24c90c52cef336d879894d224e4fc53cbfd94b1a4e5be68b05337d8d3ba8c942" + }, "find-skills": { "repo": "https://github.com/vercel-labs/skills", "path": "skills/find-skills", @@ -128,6 +290,15 @@ "_status": "active", "sha256": "22ba67a196d80ea7995ddd61813f5731541ff5c1284c2d45f50696c24ef2c145" }, + "free-tools": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/free-tools", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "dc4c7c5579df6913e5ae5b642050912679877e4ecfab30b61475db054c586ff4" + }, "huashu-design": { "repo": "https://github.com/alchaincyf/huashu-design", "tag": null, @@ -153,6 +324,51 @@ "_status": "active", "sha256": "94f314e313012c4890691dba715d5329ec43c924ea2a181bde41c4b572fdf555" }, + "image": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/image", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "42a893607914277914911e63b4b1b022884178cd2001b875890b086336b667fd" + }, + "launch": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/launch", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "1d164df86f70835a581e636f053674654acb9c29821f8bd636bd76a2be245b33" + }, + "lead-magnets": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/lead-magnets", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "ae0e160a0737925c8c7ac6c462cf6f4537c974c996f41170f632dbf7ea2e3769" + }, + "marketing-ideas": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/marketing-ideas", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "cd727687848e584e567591a1b6a541cbb31c89b1080c4838f087b45f35849b78" + }, + "marketing-psychology": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/marketing-psychology", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "2f68a8835df49c02625039fd261bff53dcdac7ecdfddb3c3266cd6793a9e4d7e" + }, "memo-skill": { "repo": null, "path": null, @@ -181,6 +397,24 @@ "_status": "active", "sha256": "7f8c056fe1af124cb881d92b246496f521e1c7901d8b4a6bb804185727bd9c19" }, + "onboarding": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/onboarding", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "da8da1e826f491fb1d695eb0a3e39464635de7fce229853f5a787ecde0b810de" + }, + "paywalls": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/paywalls", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "87b2848f12c56d45e856736b0e48280dcd196112bc3a3d887fc74328c3535d86" + }, "pdf": { "repo": "https://github.com/anthropics/skills", "path": "skills/pdf", @@ -190,6 +424,51 @@ "_status": "active", "sha256": "840f21cf5c10cf8d854517028640840d267f0731fd38d901a3bd66ebef64024e" }, + "popups": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/popups", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "2bdd26873cdc84b40a769de50c1f434caa31c2ce47b75c1670a5bed01d151b65" + }, + "pricing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/pricing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "7dfda3055e70c16dbae746c165077e7870a5f6dda786ab765e5d0e284f1da2a7" + }, + "product-marketing": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/product-marketing", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "5cf2f74031f37e20bf383e22f41537e52b3aeb320dc1f00528e79df4f4fccbfa" + }, + "programmatic-seo": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/programmatic-seo", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "b2085fc199b2edec28ededb47b93ab2a7651ef870225f15a91a8165a823aecd4" + }, + "referrals": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/referrals", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "37a78417289c99b1a66e7aeed84c473ec167d12df07407a1f3f49a2e906bbb61" + }, "resend": { "repo": "https://github.com/resend/resend-skills", "tag": null, @@ -198,14 +477,41 @@ "_status": "active", "sha256": "213e2e0f6544fd395b18c2f7f3b17f99c324745b1dd4a5435455e0b006180b41" }, + "revops": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/revops", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "5998b4927e228aa5574c4053adf692512ef582868d73527d896ceb70e93d362b" + }, + "sales-enablement": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/sales-enablement", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "75b94cc50e7250936fd30ce8da7a32b83a21c19b6abcff71780cb9cb9fee8b59" + }, + "schema": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/schema", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "180e4e02902d851442357692d7f01aeb617f79f1d558c84e9212d7980a360937" + }, "seo-audit": { - "repo": "https://github.com/mysticaltech/marketingskills", + "repo": "https://github.com/coreyhaines31/marketingskills", "path": "skills/seo-audit", "tag": null, - "commit": "2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96", - "pinned_at": "2026-05-18", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", "_status": "active", - "sha256": "9358974cf6c35647c5dc732fcf3c70f37d701d6bf7f1a5ae5affef17915a956c" + "sha256": "f9228a5eb52764638260c4dd796b04389ca6a3a58ebd2fdc092b4e8c86e2dbeb" }, "shadcn": { "repo": "https://github.com/shadcn-ui/ui", @@ -216,6 +522,33 @@ "_status": "active", "sha256": "4b80e50c1c367cd968eff79cacd5d17a57d8893ef9a7b25e2c7f69be64dc640a" }, + "signup": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/signup", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "87b28adbc35debc5dc6ba43b8c14569f68d5bf71920212aa77d0ce9c25f19bdc" + }, + "site-architecture": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/site-architecture", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "5f63cafad2f677ea44db6be461eb11ef3719009af6c7cafb0ee7f59878ddfddc" + }, + "social": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/social", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "be9341844d79a4379c4d5f8b736c4ffdac261aa9fcd717e7dce91da72cd361b3" + }, "stripe-best-practices": { "repo": "https://github.com/stripe/ai", "path": "skills/stripe-best-practices", @@ -270,6 +603,15 @@ "_status": "active", "sha256": "58e1f8a6a3f11113d2e55e485e4ad7892a0c9c69fd80b21386de311c131a8211" }, + "video": { + "repo": "https://github.com/coreyhaines31/marketingskills", + "path": "skills/video", + "tag": null, + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "pinned_at": "2026-05-20", + "_status": "active", + "sha256": "811dacf66382f2c5f527fd552920636f4b91c5f0ffa142e46316e9a77264e7f9" + }, "webapp-testing": { "repo": "https://github.com/anthropics/skills", "path": "skills/webapp-testing", @@ -617,27 +959,84 @@ } ], "skills_marketplace": [ + { + "path": "templates/skills-marketplace/ab-testing" + }, + { + "path": "templates/skills-marketplace/ad-creative" + }, + { + "path": "templates/skills-marketplace/ads" + }, { "path": "templates/skills-marketplace/ai-models" }, + { + "path": "templates/skills-marketplace/ai-seo" + }, + { + "path": "templates/skills-marketplace/analytics" + }, { "path": "templates/skills-marketplace/analytics-tracking" }, + { + "path": "templates/skills-marketplace/aso" + }, { "path": "templates/skills-marketplace/chrome-extension-development" }, + { + "path": "templates/skills-marketplace/churn-prevention" + }, + { + "path": "templates/skills-marketplace/co-marketing" + }, + { + "path": "templates/skills-marketplace/cold-email" + }, + { + "path": "templates/skills-marketplace/community-marketing" + }, + { + "path": "templates/skills-marketplace/competitor-profiling" + }, + { + "path": "templates/skills-marketplace/competitors" + }, + { + "path": "templates/skills-marketplace/content-strategy" + }, + { + "path": "templates/skills-marketplace/copy-editing" + }, { "path": "templates/skills-marketplace/copywriting" }, + { + "path": "templates/skills-marketplace/cro" + }, + { + "path": "templates/skills-marketplace/customer-research" + }, + { + "path": "templates/skills-marketplace/directory-submissions" + }, { "path": "templates/skills-marketplace/docx" }, + { + "path": "templates/skills-marketplace/emails" + }, { "path": "templates/skills-marketplace/find-skills" }, { "path": "templates/skills-marketplace/firecrawl" }, + { + "path": "templates/skills-marketplace/free-tools" + }, { "path": "templates/skills-marketplace/huashu-design" }, @@ -647,6 +1046,21 @@ { "path": "templates/skills-marketplace/i18n-localization" }, + { + "path": "templates/skills-marketplace/image" + }, + { + "path": "templates/skills-marketplace/launch" + }, + { + "path": "templates/skills-marketplace/lead-magnets" + }, + { + "path": "templates/skills-marketplace/marketing-ideas" + }, + { + "path": "templates/skills-marketplace/marketing-psychology" + }, { "path": "templates/skills-marketplace/memo-skill" }, @@ -656,18 +1070,57 @@ { "path": "templates/skills-marketplace/notebooklm" }, + { + "path": "templates/skills-marketplace/onboarding" + }, + { + "path": "templates/skills-marketplace/paywalls" + }, { "path": "templates/skills-marketplace/pdf" }, + { + "path": "templates/skills-marketplace/popups" + }, + { + "path": "templates/skills-marketplace/pricing" + }, + { + "path": "templates/skills-marketplace/product-marketing" + }, + { + "path": "templates/skills-marketplace/programmatic-seo" + }, + { + "path": "templates/skills-marketplace/referrals" + }, { "path": "templates/skills-marketplace/resend" }, + { + "path": "templates/skills-marketplace/revops" + }, + { + "path": "templates/skills-marketplace/sales-enablement" + }, + { + "path": "templates/skills-marketplace/schema" + }, { "path": "templates/skills-marketplace/seo-audit" }, { "path": "templates/skills-marketplace/shadcn" }, + { + "path": "templates/skills-marketplace/signup" + }, + { + "path": "templates/skills-marketplace/site-architecture" + }, + { + "path": "templates/skills-marketplace/social" + }, { "path": "templates/skills-marketplace/stripe-best-practices" }, @@ -686,6 +1139,9 @@ { "path": "templates/skills-marketplace/vercel-react-best-practices" }, + { + "path": "templates/skills-marketplace/video" + }, { "path": "templates/skills-marketplace/webapp-testing" } @@ -788,4 +1244,4 @@ "path": "templates/rails" } } -} \ No newline at end of file +} diff --git a/scripts/init-claude.sh b/scripts/init-claude.sh index 63773a4c..b2c35362 100755 --- a/scripts/init-claude.sh +++ b/scripts/init-claude.sh @@ -35,7 +35,7 @@ NC='\033[0m' # `raw.githubusercontent.com/.../v6.24.5/.../init-claude.sh`), leave # TK_TOOLKIT_REF unset and it inherits the bundled default below — # guaranteeing every file in the install comes from the same tag. -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/install-statusline.sh b/scripts/install-statusline.sh index 2831736b..af267313 100755 --- a/scripts/install-statusline.sh +++ b/scripts/install-statusline.sh @@ -33,7 +33,7 @@ done : "${YES}" # silence shellcheck SC2034 — no-op stub today # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/install.sh b/scripts/install.sh index 2d17566e..3f89decc 100644 --- a/scripts/install.sh +++ b/scripts/install.sh @@ -40,7 +40,7 @@ export TK_TOOLKIT_REF TK_USER_AGENT # Config # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`); TK_REPO_URL # remains the highest-priority override (full URL with ref baked in). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/migrate-to-complement.sh b/scripts/migrate-to-complement.sh index 2d45ca2f..79ba0fc4 100755 --- a/scripts/migrate-to-complement.sh +++ b/scripts/migrate-to-complement.sh @@ -57,7 +57,7 @@ CYAN='\033[0;36m' NC='\033[0m' # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/setup-council.sh b/scripts/setup-council.sh index 435b1009..6f97084e 100644 --- a/scripts/setup-council.sh +++ b/scripts/setup-council.sh @@ -16,7 +16,7 @@ CYAN='\033[0;36m' NC='\033[0m' # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/setup-prompt-engineer.sh b/scripts/setup-prompt-engineer.sh index 453202cc..0b2fbf5b 100755 --- a/scripts/setup-prompt-engineer.sh +++ b/scripts/setup-prompt-engineer.sh @@ -18,7 +18,7 @@ NC='\033[0m' # TK_TOOLKIT_REF pins to a tag/SHA (default `main`). Mirrors setup-council.sh # to keep allowlist + curl conventions identical. -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" if ! [[ "$TK_TOOLKIT_REF" =~ ^[A-Za-z0-9._/-]+$ ]] || [[ "$TK_TOOLKIT_REF" == *..* ]]; then echo "Error: TK_TOOLKIT_REF must match [A-Za-z0-9._/-]+ and must not contain '..' (got: $TK_TOOLKIT_REF)" >&2 exit 1 diff --git a/scripts/setup-security.sh b/scripts/setup-security.sh index 449e28fa..85b333ca 100755 --- a/scripts/setup-security.sh +++ b/scripts/setup-security.sh @@ -46,7 +46,7 @@ done : "${YES}" # silence shellcheck SC2034 — YES consumed by future read blocks # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/uninstall.sh b/scripts/uninstall.sh index feb07936..e4d6b3c3 100755 --- a/scripts/uninstall.sh +++ b/scripts/uninstall.sh @@ -104,7 +104,7 @@ fi # ───────── constants + log helpers ───────── # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/scripts/update-claude.sh b/scripts/update-claude.sh index 11a1f3e3..7dc93520 100755 --- a/scripts/update-claude.sh +++ b/scripts/update-claude.sh @@ -73,7 +73,7 @@ CYAN='\033[0;36m' NC='\033[0m' # Audit H5: TK_TOOLKIT_REF pins to a tag/SHA (default `main`). -TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.50.0}" +TK_TOOLKIT_REF="${TK_TOOLKIT_REF:-v6.51.0}" # Audit INF-MED-2 (2026-04-30 deep): allowlist guard — TK_TOOLKIT_REF flows # raw into curl URLs. Reject anything outside the tag/SHA charset, plus any # `..` traversal sequence. Tags / branches / SHAs do not contain `..`. diff --git a/templates/skills-catalog.json b/templates/skills-catalog.json index a5a72b6e..40b2875c 100644 --- a/templates/skills-catalog.json +++ b/templates/skills-catalog.json @@ -2,9 +2,33 @@ "schema_version": 1, "generated_from": "manifest.json:skills_pins", "generated_at": "2026-05-20", - "toolkit_version": "6.50.0", - "skills_count": 23, + "toolkit_version": "6.51.0", + "skills_count": 61, "skills": [ + { + "name": "ab-testing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/ab-testing", + "sha256": "9009bb5ce5b03267013a8f7b08d51cbf1ed5ba71218f10e0a553fc7c6e12d82b", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/ab-testing" + }, + { + "name": "ad-creative", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/ad-creative", + "sha256": "dcc14221a2b93f8ebb5333f46066a84bd664d1982070ed42f17dd39abe291384", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/ad-creative" + }, + { + "name": "ads", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/ads", + "sha256": "7025b6a6d5743742a0a251f3a78c0c47a64a79e60a81f4c98cf6c9d36268ad4f", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/ads" + }, { "name": "ai-models", "upstream": "https://github.com/artofrawr/claude-control", @@ -13,6 +37,22 @@ "sha256": "ce4b7854d7d552b2ef5d8928532d321197277e6f15b2c224fc31f463225f442e", "install_cmd": "claude-skills install --from-github https://github.com/artofrawr/claude-control --commit 5e8f37f650efa223150c2643991b409d3af324ea --path plugins/learning/skills/ai-models" }, + { + "name": "ai-seo", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/ai-seo", + "sha256": "23f1727540159172e1864cd2d98e4d7555aef2a4cf1ddc9dd6ad7290e8746cc7", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/ai-seo" + }, + { + "name": "analytics", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/analytics", + "sha256": "0795c6546402694ab2a294fd00f03fd0f5092f5ae1d2b6832561916843b4414e", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/analytics" + }, { "name": "analytics-tracking", "upstream": "https://github.com/mysticaltech/marketingskills", @@ -21,6 +61,14 @@ "sha256": "1b401662f84f2ee72ea41dafa3f38a0de1be502c6043f815ac804551200592e6", "install_cmd": "claude-skills install --from-github https://github.com/mysticaltech/marketingskills --commit 2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96 --path skills/analytics-tracking" }, + { + "name": "aso", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/aso", + "sha256": "1c6d894e9cd0b9a96fb2b9e5c065ccbe326c40ac95db86bf5dc75a005c3803bc", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/aso" + }, { "name": "chrome-extension-development", "upstream": "https://github.com/Mindrally/skills", @@ -29,13 +77,101 @@ "sha256": "488dd06fc70ccdb3559a0ec6b42f0741a6f51ebfb02184152caa97f21ee385d3", "install_cmd": "claude-skills install --from-github https://github.com/Mindrally/skills --commit 47f47c12e62f62b5e171bd5af61d0fc24b329701 --path chrome-extension-development" }, + { + "name": "churn-prevention", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/churn-prevention", + "sha256": "29dfca240fdacf7d184190252fe89a1062624231ec1b119fecfae38ccce87a35", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/churn-prevention" + }, + { + "name": "co-marketing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/co-marketing", + "sha256": "53ff5ea9bd86300efbc470bb3278dcc289dc73e7fa4ab3bfa73748cde35c0bbb", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/co-marketing" + }, + { + "name": "cold-email", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/cold-email", + "sha256": "ffe3414375aaaba93859cc3f3b9bd37994236f5b48b5fb06f493b4ec3c8d8396", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/cold-email" + }, + { + "name": "community-marketing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/community-marketing", + "sha256": "1023e3b8e880e705ab90b478a1b58d7ce24b3c5eecd9c86ad2ee8f686cde7f96", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/community-marketing" + }, + { + "name": "competitor-profiling", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/competitor-profiling", + "sha256": "f67069814787cc1957771202ded70e84e5735287f1db2ff7c34c64b0694a3097", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/competitor-profiling" + }, + { + "name": "competitors", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/competitors", + "sha256": "4cb0a8c4f13254f8589a8b2d336e192e031360932d88f87627f934042abbd3d6", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/competitors" + }, + { + "name": "content-strategy", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/content-strategy", + "sha256": "3d446d4c8ed04d75e2d49bf0f1cb2a8133c25c13fe04c9841589ae423766eeca", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/content-strategy" + }, + { + "name": "copy-editing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/copy-editing", + "sha256": "13b741dee5e784bed9e147a1508d4194916a80234bc3c2abb2dd394a771620dc", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/copy-editing" + }, { "name": "copywriting", - "upstream": "https://github.com/mysticaltech/marketingskills", - "commit": "2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", "path": "skills/copywriting", - "sha256": "71f3560cdeb63fc3459e8f5f753ad83495d12edea4a9127ff45bedab407d102c", - "install_cmd": "claude-skills install --from-github https://github.com/mysticaltech/marketingskills --commit 2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96 --path skills/copywriting" + "sha256": "8478f37d5bcec0193dd60335c611f590a3e33ac253c59e8b83912d2bb6385acb", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/copywriting" + }, + { + "name": "cro", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/cro", + "sha256": "e42ee2dc680fd189be9d6e2f925d5eaf133c655ff72bdbe57a83c741e80879ce", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/cro" + }, + { + "name": "customer-research", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/customer-research", + "sha256": "5a36513965767de8571da89858f9dd4b250b55c84eeab3690087aae44714f577", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/customer-research" + }, + { + "name": "directory-submissions", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/directory-submissions", + "sha256": "0852d65fdafe26a9e675bb7ff495367807132a59c693dbbfdb9a420593c19e9b", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/directory-submissions" }, { "name": "docx", @@ -45,6 +181,14 @@ "sha256": "950befc5c3ed716f839a362429debea9edbda31c15563281498d36dafbcbd4c5", "install_cmd": "claude-skills install --from-github https://github.com/anthropics/skills --commit 3d59511518591fa82e6cfcf0438d68dd5dad3e76 --path skills/docx" }, + { + "name": "emails", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/emails", + "sha256": "24c90c52cef336d879894d224e4fc53cbfd94b1a4e5be68b05337d8d3ba8c942", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/emails" + }, { "name": "find-skills", "upstream": "https://github.com/vercel-labs/skills", @@ -61,6 +205,14 @@ "sha256": "22ba67a196d80ea7995ddd61813f5731541ff5c1284c2d45f50696c24ef2c145", "install_cmd": "claude-skills install --from-github https://github.com/firecrawl/cli --commit f873e5bfd2ee090aefc4c5c304570334666f6b2a --path skills/firecrawl-cli" }, + { + "name": "free-tools", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/free-tools", + "sha256": "dc4c7c5579df6913e5ae5b642050912679877e4ecfab30b61475db054c586ff4", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/free-tools" + }, { "name": "huashu-design", "upstream": "https://github.com/alchaincyf/huashu-design", @@ -83,6 +235,46 @@ "sha256": "94f314e313012c4890691dba715d5329ec43c924ea2a181bde41c4b572fdf555", "install_cmd": "claude-skills install --from-github https://github.com/sickn33/antigravity-awesome-skills --commit 2138ff8fd03e70a03e116098923de0bdab3d2748 --path skills/i18n-localization" }, + { + "name": "image", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/image", + "sha256": "42a893607914277914911e63b4b1b022884178cd2001b875890b086336b667fd", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/image" + }, + { + "name": "launch", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/launch", + "sha256": "1d164df86f70835a581e636f053674654acb9c29821f8bd636bd76a2be245b33", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/launch" + }, + { + "name": "lead-magnets", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/lead-magnets", + "sha256": "ae0e160a0737925c8c7ac6c462cf6f4537c974c996f41170f632dbf7ea2e3769", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/lead-magnets" + }, + { + "name": "marketing-ideas", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/marketing-ideas", + "sha256": "cd727687848e584e567591a1b6a541cbb31c89b1080c4838f087b45f35849b78", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/marketing-ideas" + }, + { + "name": "marketing-psychology", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/marketing-psychology", + "sha256": "2f68a8835df49c02625039fd261bff53dcdac7ecdfddb3c3266cd6793a9e4d7e", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/marketing-psychology" + }, { "name": "next-best-practices", "upstream": "https://github.com/Jackiexiao/jackie-skills-cn-top50", @@ -98,6 +290,22 @@ "sha256": "7f8c056fe1af124cb881d92b246496f521e1c7901d8b4a6bb804185727bd9c19", "install_cmd": "claude-skills install --from-github https://github.com/PleasePrompto/notebooklm-skill --commit eea5cb28ba79ab8b078a1eaa44ce9ec44f75dbf8" }, + { + "name": "onboarding", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/onboarding", + "sha256": "da8da1e826f491fb1d695eb0a3e39464635de7fce229853f5a787ecde0b810de", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/onboarding" + }, + { + "name": "paywalls", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/paywalls", + "sha256": "87b2848f12c56d45e856736b0e48280dcd196112bc3a3d887fc74328c3535d86", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/paywalls" + }, { "name": "pdf", "upstream": "https://github.com/anthropics/skills", @@ -106,6 +314,46 @@ "sha256": "840f21cf5c10cf8d854517028640840d267f0731fd38d901a3bd66ebef64024e", "install_cmd": "claude-skills install --from-github https://github.com/anthropics/skills --commit 1ed29a03dc852d30fa6ef2ca53a67dc2c2c2c563 --path skills/pdf" }, + { + "name": "popups", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/popups", + "sha256": "2bdd26873cdc84b40a769de50c1f434caa31c2ce47b75c1670a5bed01d151b65", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/popups" + }, + { + "name": "pricing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/pricing", + "sha256": "7dfda3055e70c16dbae746c165077e7870a5f6dda786ab765e5d0e284f1da2a7", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/pricing" + }, + { + "name": "product-marketing", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/product-marketing", + "sha256": "5cf2f74031f37e20bf383e22f41537e52b3aeb320dc1f00528e79df4f4fccbfa", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/product-marketing" + }, + { + "name": "programmatic-seo", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/programmatic-seo", + "sha256": "b2085fc199b2edec28ededb47b93ab2a7651ef870225f15a91a8165a823aecd4", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/programmatic-seo" + }, + { + "name": "referrals", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/referrals", + "sha256": "37a78417289c99b1a66e7aeed84c473ec167d12df07407a1f3f49a2e906bbb61", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/referrals" + }, { "name": "resend", "upstream": "https://github.com/resend/resend-skills", @@ -113,13 +361,37 @@ "sha256": "213e2e0f6544fd395b18c2f7f3b17f99c324745b1dd4a5435455e0b006180b41", "install_cmd": "claude-skills install --from-github https://github.com/resend/resend-skills --commit 78469829399beec62b8f815f109ebfcfa3b0680b" }, + { + "name": "revops", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/revops", + "sha256": "5998b4927e228aa5574c4053adf692512ef582868d73527d896ceb70e93d362b", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/revops" + }, + { + "name": "sales-enablement", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/sales-enablement", + "sha256": "75b94cc50e7250936fd30ce8da7a32b83a21c19b6abcff71780cb9cb9fee8b59", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/sales-enablement" + }, + { + "name": "schema", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/schema", + "sha256": "180e4e02902d851442357692d7f01aeb617f79f1d558c84e9212d7980a360937", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/schema" + }, { "name": "seo-audit", - "upstream": "https://github.com/mysticaltech/marketingskills", - "commit": "2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", "path": "skills/seo-audit", - "sha256": "9358974cf6c35647c5dc732fcf3c70f37d701d6bf7f1a5ae5affef17915a956c", - "install_cmd": "claude-skills install --from-github https://github.com/mysticaltech/marketingskills --commit 2bbd1b6af3eb658dce42ddb6538abe60ab4e0d96 --path skills/seo-audit" + "sha256": "f9228a5eb52764638260c4dd796b04389ca6a3a58ebd2fdc092b4e8c86e2dbeb", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/seo-audit" }, { "name": "shadcn", @@ -129,6 +401,30 @@ "sha256": "4b80e50c1c367cd968eff79cacd5d17a57d8893ef9a7b25e2c7f69be64dc640a", "install_cmd": "claude-skills install --from-github https://github.com/shadcn-ui/ui --commit ea6086cbcc33b359bb876651374e26f643ea85b1 --path skills/shadcn" }, + { + "name": "signup", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/signup", + "sha256": "87b28adbc35debc5dc6ba43b8c14569f68d5bf71920212aa77d0ce9c25f19bdc", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/signup" + }, + { + "name": "site-architecture", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/site-architecture", + "sha256": "5f63cafad2f677ea44db6be461eb11ef3719009af6c7cafb0ee7f59878ddfddc", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/site-architecture" + }, + { + "name": "social", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/social", + "sha256": "be9341844d79a4379c4d5f8b736c4ffdac261aa9fcd717e7dce91da72cd361b3", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/social" + }, { "name": "stripe-best-practices", "upstream": "https://github.com/stripe/ai", @@ -177,6 +473,14 @@ "sha256": "58e1f8a6a3f11113d2e55e485e4ad7892a0c9c69fd80b21386de311c131a8211", "install_cmd": "claude-skills install --from-github https://github.com/vercel-labs/agent-skills --commit dc8367e6f91c022d83361f03c3313fa05e848ee5 --path skills/react-best-practices" }, + { + "name": "video", + "upstream": "https://github.com/coreyhaines31/marketingskills", + "commit": "114587831efbe7ac5c0a86afcb69e9cca6f728ce", + "path": "skills/video", + "sha256": "811dacf66382f2c5f527fd552920636f4b91c5f0ffa142e46316e9a77264e7f9", + "install_cmd": "claude-skills install --from-github https://github.com/coreyhaines31/marketingskills --commit 114587831efbe7ac5c0a86afcb69e9cca6f728ce --path skills/video" + }, { "name": "webapp-testing", "upstream": "https://github.com/anthropics/skills", diff --git a/templates/skills-marketplace/ab-testing/SKILL.md b/templates/skills-marketplace/ab-testing/SKILL.md new file mode 100644 index 00000000..e3f99971 --- /dev/null +++ b/templates/skills-marketplace/ab-testing/SKILL.md @@ -0,0 +1,353 @@ +--- +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: 2.0.0 +--- + +# A/B Test Setup + +You are an expert in experimentation and A/B testing. Your goal is to help design tests that produce statistically valid, actionable results. + +## Initial Assessment + +**Check for product marketing context first:** +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: + +1. **Test Context** - What are you trying to improve? What change are you considering? +2. **Current State** - Baseline conversion rate? Current traffic volume? +3. **Constraints** - Technical complexity? Timeline? Tools available? + +--- + +## Core Principles + +### 1. Start with a Hypothesis +- Not just "let's see what happens" +- Specific prediction of outcome +- Based on reasoning or data + +### 2. Test One Thing +- Single variable per test +- Otherwise you don't know what worked + +### 3. Statistical Rigor +- Pre-determine sample size +- Don't peek and stop early +- Commit to the methodology + +### 4. Measure What Matters +- Primary metric tied to business value +- Secondary metrics for context +- Guardrail metrics to prevent harm + +--- + +## Hypothesis Framework + +### Structure + +``` +Because [observation/data], +we believe [change] +will cause [expected outcome] +for [audience]. +We'll know this is true when [metrics]. +``` + +### Example + +**Weak**: "Changing the button color might increase clicks." + +**Strong**: "Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start." + +--- + +## Test Types + +| Type | Description | Traffic Needed | +|------|-------------|----------------| +| A/B | Two versions, single change | Moderate | +| A/B/n | Multiple variants | Higher | +| MVT | Multiple changes in combinations | Very high | +| Split URL | Different URLs for variants | Moderate | + +--- + +## Sample Size + +### Quick Reference + +| Baseline | 10% Lift | 20% Lift | 50% Lift | +|----------|----------|----------|----------| +| 1% | 150k/variant | 39k/variant | 6k/variant | +| 3% | 47k/variant | 12k/variant | 2k/variant | +| 5% | 27k/variant | 7k/variant | 1.2k/variant | +| 10% | 12k/variant | 3k/variant | 550/variant | + +**Calculators:** +- [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) +- [Optimizely's](https://www.optimizely.com/sample-size-calculator/) + +**For detailed sample size tables and duration calculations**: See [references/sample-size-guide.md](references/sample-size-guide.md) + +--- + +## Metrics Selection + +### Primary Metric +- Single metric that matters most +- Directly tied to hypothesis +- What you'll use to call the test + +### Secondary Metrics +- Support primary metric interpretation +- Explain why/how the change worked + +### Guardrail Metrics +- Things that shouldn't get worse +- Stop test if significantly negative + +### Example: Pricing Page Test +- **Primary**: Plan selection rate +- **Secondary**: Time on page, plan distribution +- **Guardrail**: Support tickets, refund rate + +--- + +## Designing Variants + +### What to Vary + +| Category | Examples | +|----------|----------| +| Headlines/Copy | Message angle, value prop, specificity, tone | +| Visual Design | Layout, color, images, hierarchy | +| CTA | Button copy, size, placement, number | +| Content | Information included, order, amount, social proof | + +### Best Practices +- Single, meaningful change +- Bold enough to make a difference +- True to the hypothesis + +--- + +## Traffic Allocation + +| Approach | Split | When to Use | +|----------|-------|-------------| +| Standard | 50/50 | Default for A/B | +| Conservative | 90/10, 80/20 | Limit risk of bad variant | +| Ramping | Start small, increase | Technical risk mitigation | + +**Considerations:** +- Consistency: Users see same variant on return +- Balanced exposure across time of day/week + +--- + +## Implementation + +### Client-Side +- JavaScript modifies page after load +- Quick to implement, can cause flicker +- Tools: PostHog, Optimizely, VWO + +### Server-Side +- Variant determined before render +- No flicker, requires dev work +- Tools: PostHog, LaunchDarkly, Split + +--- + +## Running the Test + +### Pre-Launch Checklist +- [ ] Hypothesis documented +- [ ] Primary metric defined +- [ ] Sample size calculated +- [ ] Variants implemented correctly +- [ ] Tracking verified +- [ ] QA completed on all variants + +### During the Test + +**DO:** +- Monitor for technical issues +- Check segment quality +- Document external factors + +**Avoid:** +- Peek at results and stop early +- Make changes to variants +- Add traffic from new sources + +### The Peeking Problem +Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. Pre-commit to sample size and trust the process. + +--- + +## Analyzing Results + +### Statistical Significance +- 95% confidence = p-value < 0.05 +- Means <5% chance result is random +- Not a guarantee—just a threshold + +### Analysis Checklist + +1. **Reach sample size?** If not, result is preliminary +2. **Statistically significant?** Check confidence intervals +3. **Effect size meaningful?** Compare to MDE, project impact +4. **Secondary metrics consistent?** Support the primary? +5. **Guardrail concerns?** Anything get worse? +6. **Segment differences?** Mobile vs. desktop? New vs. returning? + +### Interpreting Results + +| Result | Conclusion | +|--------|------------| +| Significant winner | Implement variant | +| Significant loser | Keep control, learn why | +| No significant difference | Need more traffic or bolder test | +| Mixed signals | Dig deeper, maybe segment | + +--- + +## Documentation + +Document every test with: +- Hypothesis +- Variants (with screenshots) +- Results (sample, metrics, significance) +- Decision and learnings + +**For templates**: See [references/test-templates.md](references/test-templates.md) + +--- + +## 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 +- Testing too small a change (undetectable) +- Testing too many things (can't isolate) +- No clear hypothesis + +### Execution +- Stopping early +- Changing things mid-test +- Not checking implementation + +### Analysis +- Ignoring confidence intervals +- Cherry-picking segments +- Over-interpreting inconclusive results + +--- + +## Task-Specific Questions + +1. What's your current conversion rate? +2. How much traffic does this page get? +3. What change are you considering and why? +4. What's the smallest improvement worth detecting? +5. What tools do you have for testing? +6. Have you tested this area before? + +--- + +## Related Skills + +- **cro**: For generating test ideas based on CRO principles +- **analytics**: For setting up test measurement +- **copywriting**: For creating variant copy diff --git a/templates/skills-marketplace/ab-testing/evals/evals.json b/templates/skills-marketplace/ab-testing/evals/evals.json new file mode 100644 index 00000000..7ef70da5 --- /dev/null +++ b/templates/skills-marketplace/ab-testing/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/templates/skills-marketplace/ab-testing/references/sample-size-guide.md b/templates/skills-marketplace/ab-testing/references/sample-size-guide.md new file mode 100644 index 00000000..3e35e6c1 --- /dev/null +++ b/templates/skills-marketplace/ab-testing/references/sample-size-guide.md @@ -0,0 +1,263 @@ +# Sample Size Guide + +Reference for calculating sample sizes and test duration. + +## Contents +- Sample Size Fundamentals (required inputs, what these mean) +- Sample Size Quick Reference Tables +- Duration Calculator (formula, examples, minimum duration rules, maximum duration guidelines) +- Online Calculators +- Adjusting for Multiple Variants +- Common Sample Size Mistakes +- When Sample Size Requirements Are Too High +- Sequential Testing +- Quick Decision Framework + +## Sample Size Fundamentals + +### Required Inputs + +1. **Baseline conversion rate**: Your current rate +2. **Minimum detectable effect (MDE)**: Smallest change worth detecting +3. **Statistical significance level**: Usually 95% (α = 0.05) +4. **Statistical power**: Usually 80% (β = 0.20) + +### What These Mean + +**Baseline conversion rate**: If your page converts at 5%, that's your baseline. + +**MDE (Minimum Detectable Effect)**: The smallest improvement you care about detecting. Set this based on: +- Business impact (is a 5% lift meaningful?) +- Implementation cost (worth the effort?) +- Realistic expectations (what have past tests shown?) + +**Statistical significance (95%)**: Means there's less than 5% chance the observed difference is due to random chance. + +**Statistical power (80%)**: Means if there's a real effect of size MDE, you have 80% chance of detecting it. + +--- + +## Sample Size Quick Reference Tables + +### Conversion Rate: 1% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (1% → 1.05%) | 1,500,000 | 3,000,000 | +| 10% (1% → 1.1%) | 380,000 | 760,000 | +| 20% (1% → 1.2%) | 97,000 | 194,000 | +| 50% (1% → 1.5%) | 16,000 | 32,000 | +| 100% (1% → 2%) | 4,200 | 8,400 | + +### Conversion Rate: 3% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (3% → 3.15%) | 480,000 | 960,000 | +| 10% (3% → 3.3%) | 120,000 | 240,000 | +| 20% (3% → 3.6%) | 31,000 | 62,000 | +| 50% (3% → 4.5%) | 5,200 | 10,400 | +| 100% (3% → 6%) | 1,400 | 2,800 | + +### Conversion Rate: 5% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (5% → 5.25%) | 280,000 | 560,000 | +| 10% (5% → 5.5%) | 72,000 | 144,000 | +| 20% (5% → 6%) | 18,000 | 36,000 | +| 50% (5% → 7.5%) | 3,100 | 6,200 | +| 100% (5% → 10%) | 810 | 1,620 | + +### Conversion Rate: 10% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (10% → 10.5%) | 130,000 | 260,000 | +| 10% (10% → 11%) | 34,000 | 68,000 | +| 20% (10% → 12%) | 8,700 | 17,400 | +| 50% (10% → 15%) | 1,500 | 3,000 | +| 100% (10% → 20%) | 400 | 800 | + +### Conversion Rate: 20% + +| Lift to Detect | Sample per Variant | Total Sample | +|----------------|-------------------|--------------| +| 5% (20% → 21%) | 60,000 | 120,000 | +| 10% (20% → 22%) | 16,000 | 32,000 | +| 20% (20% → 24%) | 4,000 | 8,000 | +| 50% (20% → 30%) | 700 | 1,400 | +| 100% (20% → 40%) | 200 | 400 | + +--- + +## Duration Calculator + +### Formula + +``` +Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × % exposed) +``` + +### Examples + +**Scenario 1: High-traffic page** +- Need: 10,000 per variant (2 variants = 20,000 total) +- Daily traffic: 5,000 visitors +- 100% exposed to test +- Duration: 20,000 / 5,000 = **4 days** + +**Scenario 2: Medium-traffic page** +- Need: 30,000 per variant (60,000 total) +- Daily traffic: 2,000 visitors +- 100% exposed +- Duration: 60,000 / 2,000 = **30 days** + +**Scenario 3: Low-traffic with partial exposure** +- Need: 15,000 per variant (30,000 total) +- Daily traffic: 500 visitors +- 50% exposed to test +- Effective daily: 250 +- Duration: 30,000 / 250 = **120 days** (too long!) + +### Minimum Duration Rules + +Even with sufficient sample size, run tests for at least: +- **1 full week**: To capture day-of-week variation +- **2 business cycles**: If B2B (weekday vs. weekend patterns) +- **Through paydays**: If e-commerce (beginning/end of month) + +### Maximum Duration Guidelines + +Avoid running tests longer than 4-8 weeks: +- Novelty effects wear off +- External factors intervene +- Opportunity cost of other tests + +--- + +## Online Calculators + +### Recommended Tools + +**Evan Miller's Calculator** +https://www.evanmiller.org/ab-testing/sample-size.html +- Simple interface +- Bookmark-worthy + +**Optimizely's Calculator** +https://www.optimizely.com/sample-size-calculator/ +- Business-friendly language +- Duration estimates + +**AB Test Guide Calculator** +https://www.abtestguide.com/calc/ +- Includes Bayesian option +- Multiple test types + +**VWO Duration Calculator** +https://vwo.com/tools/ab-test-duration-calculator/ +- Duration-focused +- Good for planning + +--- + +## Adjusting for Multiple Variants + +With more than 2 variants (A/B/n tests), you need more sample: + +| Variants | Multiplier | +|----------|------------| +| 2 (A/B) | 1x | +| 3 (A/B/C) | ~1.5x | +| 4 (A/B/C/D) | ~2x | +| 5+ | Consider reducing variants | + +**Why?** More comparisons increase chance of false positives. You're comparing: +- A vs B +- A vs C +- B vs C (sometimes) + +Apply Bonferroni correction or use tools that handle this automatically. + +--- + +## Common Sample Size Mistakes + +### 1. Underpowered tests +**Problem**: Not enough sample to detect realistic effects +**Fix**: Be realistic about MDE, get more traffic, or don't test + +### 2. Overpowered tests +**Problem**: Waiting for sample size when you already have significance +**Fix**: This is actually fine—you committed to sample size, honor it + +### 3. Wrong baseline rate +**Problem**: Using wrong conversion rate for calculation +**Fix**: Use the specific metric and page, not site-wide averages + +### 4. Ignoring segments +**Problem**: Calculating for full traffic, then analyzing segments +**Fix**: If you plan segment analysis, calculate sample for smallest segment + +### 5. Testing too many things +**Problem**: Dividing traffic too many ways +**Fix**: Prioritize ruthlessly, run fewer concurrent tests + +--- + +## When Sample Size Requirements Are Too High + +Options when you can't get enough traffic: + +1. **Increase MDE**: Accept only detecting larger effects (20%+ lift) +2. **Lower confidence**: Use 90% instead of 95% (risky, document it) +3. **Reduce variants**: Test only the most promising variant +4. **Combine traffic**: Test across multiple similar pages +5. **Test upstream**: Test earlier in funnel where traffic is higher +6. **Don't test**: Make decision based on qualitative data instead +7. **Longer test**: Accept longer duration (weeks/months) + +--- + +## Sequential Testing + +If you must check results before reaching sample size: + +### What is it? +Statistical method that adjusts for multiple looks at data. + +### When to use +- High-risk changes +- Need to stop bad variants early +- Time-sensitive decisions + +### Tools that support it +- Optimizely (Stats Accelerator) +- VWO (SmartStats) +- PostHog (Bayesian approach) + +### Tradeoff +- More flexibility to stop early +- Slightly larger sample size requirement +- More complex analysis + +--- + +## Quick Decision Framework + +### Can I run this test? + +``` +Daily traffic to page: _____ +Baseline conversion rate: _____ +MDE I care about: _____ + +Sample needed per variant: _____ (from tables above) +Days to run: Sample / Daily traffic = _____ + +If days > 60: Consider alternatives +If days > 30: Acceptable for high-impact tests +If days < 14: Likely feasible +If days < 7: Easy to run, consider running longer anyway +``` diff --git a/templates/skills-marketplace/ab-testing/references/test-templates.md b/templates/skills-marketplace/ab-testing/references/test-templates.md new file mode 100644 index 00000000..1c517d88 --- /dev/null +++ b/templates/skills-marketplace/ab-testing/references/test-templates.md @@ -0,0 +1,277 @@ +# A/B Test Templates Reference + +Templates for planning, documenting, and analyzing experiments. + +## Contents +- Test Plan Template +- Results Documentation Template +- Test Repository Entry Template +- Quick Test Brief Template +- Stakeholder Update Template +- Experiment Prioritization Scorecard +- Hypothesis Bank Template + +## Test Plan Template + +```markdown +# A/B Test: [Name] + +## Overview +- **Owner**: [Name] +- **Test ID**: [ID in testing tool] +- **Page/Feature**: [What's being tested] +- **Planned dates**: [Start] - [End] + +## Hypothesis + +Because [observation/data], +we believe [change] +will cause [expected outcome] +for [audience]. +We'll know this is true when [metrics]. + +## Test Design + +| Element | Details | +|---------|---------| +| Test type | A/B / A/B/n / MVT | +| Duration | X weeks | +| Sample size | X per variant | +| Traffic allocation | 50/50 | +| Tool | [Tool name] | +| Implementation | Client-side / Server-side | + +## Variants + +### Control (A) +[Screenshot] +- Current experience +- [Key details about current state] + +### Variant (B) +[Screenshot or mockup] +- [Specific change #1] +- [Specific change #2] +- Rationale: [Why we think this will win] + +## Metrics + +### Primary +- **Metric**: [metric name] +- **Definition**: [how it's calculated] +- **Current baseline**: [X%] +- **Minimum detectable effect**: [X%] + +### Secondary +- [Metric 1]: [what it tells us] +- [Metric 2]: [what it tells us] +- [Metric 3]: [what it tells us] + +### Guardrails +- [Metric that shouldn't get worse] +- [Another safety metric] + +## Segment Analysis Plan +- Mobile vs. desktop +- New vs. returning visitors +- Traffic source +- [Other relevant segments] + +## Success Criteria +- Winner: [Primary metric improves by X% with 95% confidence] +- Loser: [Primary metric decreases significantly] +- Inconclusive: [What we'll do if no significant result] + +## Pre-Launch Checklist +- [ ] Hypothesis documented and reviewed +- [ ] Primary metric defined and trackable +- [ ] Sample size calculated +- [ ] Test duration estimated +- [ ] Variants implemented correctly +- [ ] Tracking verified in all variants +- [ ] QA completed on all variants +- [ ] Stakeholders informed +- [ ] Calendar hold for analysis date +``` + +--- + +## Results Documentation Template + +```markdown +# A/B Test Results: [Name] + +## Summary +| Element | Value | +|---------|-------| +| Test ID | [ID] | +| Dates | [Start] - [End] | +| Duration | X days | +| Result | Winner / Loser / Inconclusive | +| Decision | [What we're doing] | + +## Hypothesis (Reminder) +[Copy from test plan] + +## Results + +### Sample Size +| Variant | Target | Actual | % of target | +|---------|--------|--------|-------------| +| Control | X | Y | Z% | +| Variant | X | Y | Z% | + +### Primary Metric: [Metric Name] +| Variant | Value | 95% CI | vs. Control | +|---------|-------|--------|-------------| +| Control | X% | [X%, Y%] | — | +| Variant | X% | [X%, Y%] | +X% | + +**Statistical significance**: p = X.XX (95% = sig / not sig) +**Practical significance**: [Is this lift meaningful for the business?] + +### Secondary Metrics + +| Metric | Control | Variant | Change | Significant? | +|--------|---------|---------|--------|--------------| +| [Metric 1] | X | Y | +Z% | Yes/No | +| [Metric 2] | X | Y | +Z% | Yes/No | + +### Guardrail Metrics + +| Metric | Control | Variant | Change | Concern? | +|--------|---------|---------|--------|----------| +| [Metric 1] | X | Y | +Z% | Yes/No | + +### Segment Analysis + +**Mobile vs. Desktop** +| Segment | Control | Variant | Lift | +|---------|---------|---------|------| +| Mobile | X% | Y% | +Z% | +| Desktop | X% | Y% | +Z% | + +**New vs. Returning** +| Segment | Control | Variant | Lift | +|---------|---------|---------|------| +| New | X% | Y% | +Z% | +| Returning | X% | Y% | +Z% | + +## Interpretation + +### What happened? +[Explanation of results in plain language] + +### Why do we think this happened? +[Analysis and reasoning] + +### Caveats +[Any limitations, external factors, or concerns] + +## Decision + +**Winner**: [Control / Variant] + +**Action**: [Implement variant / Keep control / Re-test] + +**Timeline**: [When changes will be implemented] + +## Learnings + +### What we learned +- [Key insight 1] +- [Key insight 2] + +### What to test next +- [Follow-up test idea 1] +- [Follow-up test idea 2] + +### Impact +- **Projected lift**: [X% improvement in Y metric] +- **Business impact**: [Revenue, conversions, etc.] +``` + +--- + +## Test Repository Entry Template + +For tracking all tests in a central location: + +```markdown +| Test ID | Name | Page | Dates | Primary Metric | Result | Lift | Link | +|---------|------|------|-------|----------------|--------|------|------| +| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] | +| 002 | Pricing table layout | Pricing | 1/10-1/31 | Plan selection | Loser | -5% | [Link] | +| 003 | Signup form fields | Signup | 2/1-2/14 | Completion | Inconclusive | +2% | [Link] | +``` + +--- + +## Quick Test Brief Template + +For simple tests that don't need full documentation: + +```markdown +## [Test Name] + +**What**: [One sentence description] +**Why**: [One sentence hypothesis] +**Metric**: [Primary metric] +**Duration**: [X weeks] +**Result**: [TBD / Winner / Loser / Inconclusive] +**Learnings**: [Key takeaway] +``` + +--- + +## Stakeholder Update Template + +```markdown +## A/B Test Update: [Name] + +**Status**: Running / Complete +**Days remaining**: X (or complete) +**Current sample**: X% of target + +### Preliminary observations +[What we're seeing - without making decisions yet] + +### Next steps +[What happens next] + +### Timeline +- [Date]: Analysis complete +- [Date]: Decision and recommendation +- [Date]: Implementation (if winner) +``` + +--- + +## Experiment Prioritization Scorecard + +For deciding which tests to run: + +| Factor | Weight | Test A | Test B | Test C | +|--------|--------|--------|--------|--------| +| Potential impact | 30% | | | | +| Confidence in hypothesis | 25% | | | | +| Ease of implementation | 20% | | | | +| Risk if wrong | 15% | | | | +| Strategic alignment | 10% | | | | +| **Total** | | | | | + +Scoring: 1-5 (5 = best) + +--- + +## Hypothesis Bank Template + +For collecting test ideas: + +```markdown +| ID | Page/Area | Observation | Hypothesis | Potential Impact | Status | +|----|-----------|-------------|------------|------------------|--------| +| H1 | Homepage | Low scroll depth | Shorter hero will increase scroll | High | Testing | +| H2 | Pricing | Users compare plans | Comparison table will help | Medium | Backlog | +| H3 | Signup | Drop-off at email | Social login will increase completion | Medium | Backlog | +``` diff --git a/templates/skills-marketplace/ad-creative/SKILL.md b/templates/skills-marketplace/ad-creative/SKILL.md new file mode 100644 index 00000000..99b483ea --- /dev/null +++ b/templates/skills-marketplace/ad-creative/SKILL.md @@ -0,0 +1,362 @@ +--- +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,' '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: 2.0.0 +--- + +# Ad Creative + +You are an expert performance creative strategist. Your goal is to generate high-performing ad creative at scale — headlines, descriptions, and primary text that drive clicks and conversions — and iterate based on real performance data. + +## Before Starting + +**Check for product marketing context first:** +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): + +### 1. Platform & Format +- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X) +- What ad format? (Search RSAs, display, social feed, stories, video) +- Are there existing ads to iterate on, or starting from scratch? + +### 2. Product & Offer +- What are you promoting? (Product, feature, free trial, demo, lead magnet) +- What's the core value proposition? +- What makes this different from competitors? + +### 3. Audience & Intent +- Who is the target audience? +- What stage of awareness? (Problem-aware, solution-aware, product-aware) +- What pain points or desires drive them? + +### 4. Performance Data (if iterating) +- What creative is currently running? +- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS) +- Which are underperforming? +- What angles or themes have been tested? + +### 5. Constraints +- Brand voice guidelines or words to avoid? +- Compliance requirements? (Industry regulations, platform policies) +- Any mandatory elements? (Brand name, trademark symbols, disclaimers) + +--- + +## How This Skill Works + +This skill supports two modes: + +### Mode 1: Generate from Scratch +When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices. + +### Mode 2: Iterate from Performance Data +When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles. + +The core loop: + +``` +Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver +``` + +--- + +## Platform Specs + +Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering. + +### Google Ads (Responsive Search Ads) + +| Element | Limit | Quantity | +|---------|-------|----------| +| Headline | 30 characters | Up to 15 | +| Description | 90 characters | Up to 4 | +| Display URL path | 15 characters each | 2 paths | + +**RSA rules:** +- Headlines must make sense independently and in any combination +- Pin headlines to positions only when necessary (reduces optimization) +- Include at least one keyword-focused headline +- Include at least one benefit-focused headline +- Include at least one CTA headline + +### Meta Ads (Facebook/Instagram) + +| Element | Limit | Notes | +|---------|-------|-------| +| Primary text | 125 chars visible (up to 2,200) | Front-load the hook | +| Headline | 40 characters recommended | Below the image | +| Description | 30 characters recommended | Below headline | +| URL display link | 40 characters | Optional | + +### LinkedIn Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Intro text | 150 chars recommended (600 max) | Above the image | +| Headline | 70 chars recommended (200 max) | Below the image | +| Description | 100 chars recommended (300 max) | Appears in some placements | + +### TikTok Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Ad text | 80 chars recommended (100 max) | Above the video | +| Display name | 40 characters | Brand name | + +### Twitter/X Ads + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 characters | The ad copy | +| Headline | 70 characters | Card headline | +| Description | 200 characters | Card description | + +For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md). + +--- + +## Generating Ad Visuals + +For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering: + +- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images +- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads +- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual +- **Code-based video** — Remotion for templated, data-driven video at scale +- **Platform image specs** — Correct dimensions for every ad placement +- **Cost comparison** — Pricing for 100+ ad variations across tools + +**Recommended workflow for scaled production:** +1. Generate hero creative with AI tools (exploratory, high-quality) +2. Build Remotion templates based on winning patterns +3. Batch produce variations with Remotion using data feeds +4. Iterate — AI for new angles, Remotion for scale + +--- + +## Generating Ad Copy + +### Step 1: Define Your Angles + +Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation. + +**Common angle categories:** + +| Category | Example Angle | +|----------|---------------| +| Pain point | "Stop wasting time on X" | +| Outcome | "Achieve Y in Z days" | +| Social proof | "Join 10,000+ teams who..." | +| Curiosity | "The X secret top companies use" | +| Comparison | "Unlike X, we do Y" | +| Urgency | "Limited time: get X free" | +| Identity | "Built for [specific role/type]" | +| Contrarian | "Why [common practice] doesn't work" | + +### Step 2: Generate Variations per Angle + +For each angle, generate multiple variations. Vary: +- **Word choice** — synonyms, active vs. passive +- **Specificity** — numbers vs. general claims +- **Tone** — direct vs. question vs. command +- **Structure** — short punch vs. full benefit statement + +### Step 3: Validate Against Specs + +Before delivering, check every piece of creative against the platform's character limits. Flag anything that's over and provide a trimmed alternative. + +### Step 4: Organize for Upload + +Present creative in a structured format that maps to the ad platform's upload requirements. + +--- + +## Iterating from Performance Data + +When the user provides performance data, follow this process: + +### Step 1: Analyze Winners + +Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify: + +- **Winning themes** — What topics or pain points appear in top performers? +- **Winning structures** — Questions? Statements? Commands? Numbers? +- **Winning word patterns** — Specific words or phrases that recur? +- **Character utilization** — Are top performers shorter or longer? + +### Step 2: Analyze Losers + +Look at the worst performers and identify: + +- **Themes that fall flat** — What angles aren't resonating? +- **Common patterns in low performers** — Too generic? Too long? Wrong tone? + +### Step 3: Generate New Variations + +Create new creative that: +- **Doubles down** on winning themes with fresh phrasing +- **Extends** winning angles into new variations +- **Tests** 1-2 new angles not yet explored +- **Avoids** patterns found in underperformers + +### Step 4: Document the Iteration + +Track what was learned and what's being tested: + +``` +## Iteration Log +- Round: [number] +- Date: [date] +- Top performers: [list with metrics] +- Winning patterns: [summary] +- New variations: [count] headlines, [count] descriptions +- New angles being tested: [list] +- Angles retired: [list] +``` + +--- + +## Writing Quality Standards + +### Headlines That Click + +**Strong headlines:** +- Specific ("Cut reporting time 75%") over vague ("Save time") +- Benefits ("Ship code faster") over features ("CI/CD pipeline") +- Active voice ("Automate your reports") over passive ("Reports are automated") +- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams") + +**Avoid:** +- Jargon the audience won't recognize +- Claims without specificity ("Best," "Leading," "Top") +- All caps or excessive punctuation +- Clickbait that the landing page can't deliver on + +### Descriptions That Convert + +Descriptions should complement headlines, not repeat them. Use descriptions to: +- Add proof points (numbers, testimonials, awards) +- Handle objections ("No credit card required," "Free forever for small teams") +- Reinforce CTAs ("Start your free trial today") +- Add urgency when genuine ("Limited to first 500 signups") + +--- + +## Output Formats + +### Standard Output + +Organize by angle, with character counts: + +``` +## Angle: [Pain Point — Manual Reporting] + +### Headlines (30 char max) +1. "Stop Building Reports by Hand" (29) +2. "Automate Your Weekly Reports" (28) +3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below + -> "Reports in 5 Min, Not 5 Hrs" (27) + +### Descriptions (90 char max) +1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73) +2. "Connect your data sources once. Get automated reports forever. No code required." (80) +``` + +### Bulk CSV Output + +When generating at scale (10+ variations), offer CSV format for direct upload: + +```csv +headline_1,headline_2,headline_3,description_1,description_2,platform +"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads" +``` + +### Iteration Report + +When iterating, include a summary: + +``` +## Performance Summary +- Analyzed: [X] headlines, [Y] descriptions +- Top performer: "[headline]" — [metric]: [value] +- Worst performer: "[headline]" — [metric]: [value] +- Pattern: [observation] + +## New Creative +[organized variations] + +## Recommendations +- [What to pause, what to scale, what to test next] +``` + +--- + +## Batch Generation Workflow + +For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle): + +### 1. Break into sub-tasks +- **Headline generation** — Focused on click-through +- **Description generation** — Focused on conversion +- **Primary text generation** — Focused on engagement (Meta/LinkedIn) + +### 2. Generate in waves +- Wave 1: Core angles (3-5 angles, 5 variations each) +- Wave 2: Extended variations on top 2 angles +- Wave 3: Wild card angles (contrarian, emotional, specific) + +### 3. Quality filter +- Remove anything over character limit +- Remove duplicates or near-duplicates +- Flag anything that might violate platform policies +- Ensure headline/description combinations make sense together + +--- + +## Common Mistakes + +- **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** — 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 +- **Retiring creative too early** — Allow 1,000+ impressions before judging + +--- + +## Tool Integrations + +For pulling performance data and managing campaigns, see the [tools registry](../../tools/REGISTRY.md). + +| Platform | Pull Performance Data | Manage Campaigns | Guide | +|----------|:---------------------:|:----------------:|-------| +| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) | +| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) | +| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) | +| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) | + +### Workflow: Pull Data, Analyze, Generate + +```bash +# 1. Pull recent ad performance +node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days + +# 2. Analyze output (identify top/bottom performers) +# 3. Feed winning patterns into this skill +# 4. Generate new variations +# 5. Upload to platform +``` + +--- + +## Related Skills + +- **ads**: For campaign strategy, targeting, budgets, and optimization +- **copywriting**: For landing page copy (where ad traffic lands) +- **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/templates/skills-marketplace/ad-creative/evals/evals.json b/templates/skills-marketplace/ad-creative/evals/evals.json new file mode 100644 index 00000000..63f10a73 --- /dev/null +++ b/templates/skills-marketplace/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/templates/skills-marketplace/ad-creative/references/generative-tools.md b/templates/skills-marketplace/ad-creative/references/generative-tools.md new file mode 100644 index 00000000..b1e6fec2 --- /dev/null +++ b/templates/skills-marketplace/ad-creative/references/generative-tools.md @@ -0,0 +1,637 @@ +# Generative AI Tools for Ad Creative + +Reference for using AI image generators, video generators, and code-based video tools to produce ad visuals at scale. + +--- + +## When to Use Generative Tools + +| Need | Tool Category | Best Fit | +|------|---------------|----------| +| 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 | +| Voiceover tracks for ads | Voice generation | ElevenLabs, OpenAI TTS, Cartesia | +| Multi-language ad versions | Voice generation | ElevenLabs, PlayHT | +| Brand voice cloning | Voice generation | ElevenLabs, Resemble AI | +| Product mockups and variations | Image generation + references | Flux (multi-image reference) | +| Templated video ads at scale | Code-based video | Remotion | +| Personalized video (name, data) | Code-based video | Remotion | +| Brand-consistent variations | Image gen + style refs | Flux, Ideogram, Nano Banana Pro | + +--- + +## Image Generation + +### Nano Banana Pro (Gemini) + +Google DeepMind's image generation model, available through the Gemini API. + +**Best for:** High-quality ad images, product visuals, text rendering +**API:** Gemini API (Google AI Studio, Vertex AI) +**Pricing:** ~$0.04/image (Gemini 2.5 Flash Image), ~$0.24/4K image (Nano Banana Pro) + +**Strengths:** +- Strong text rendering in images (logos, headlines) +- Native image editing (modify existing images with prompts) +- Available through the same Gemini API used for text generation +- Supports both generation and editing in one model + +**Ad creative use cases:** +- Generate social media ad images from text descriptions +- Create product mockup variations +- Edit existing ad images (swap backgrounds, change colors) +- Generate images with headline text baked in + +**API example:** +```bash +# Using the Gemini API for image generation +curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \ + -H "Content-Type: application/json" \ + -H "x-goog-api-key: $GEMINI_API_KEY" \ + -d '{ + "contents": [{"parts": [{"text": "Create a clean, modern social media ad image for a project management tool. Show a laptop with a kanban board interface. Bright, professional, 16:9 ratio."}]}], + "generationConfig": {"responseModalities": ["TEXT", "IMAGE"]} + }' +``` + +**Docs:** [Gemini Image Generation](https://ai.google.dev/gemini-api/docs/image-generation) + +--- + +### Flux (Black Forest Labs) + +Open-weight image generation models with API access through Replicate and BFL's native API. + +**Best for:** Photorealistic images, brand-consistent variations, multi-reference generation +**API:** Replicate, BFL API, fal.ai +**Pricing:** ~$0.01-0.06/image depending on model and resolution + +**Model variants:** +| Model | Speed | Quality | Cost | Best For | +|-------|-------|---------|------|----------| +| Flux 2 Pro | ~6 sec | Highest | $0.015/MP | Final production assets | +| Flux 2 Flex | ~22 sec | High + editing | $0.06/MP | Iterative editing | +| Flux 2 Dev | ~2.5 sec | Good | $0.012/MP | Rapid prototyping | +| Flux 2 Klein | Fastest | Good | Lowest | High-volume batch generation | + +**Strengths:** +- Multi-image reference (up to 8 images) for consistent identity across ads +- Product consistency — same product in different contexts +- Style transfer from reference images +- Open-weight Dev model for self-hosting + +**Ad creative use cases:** +- Generate 50+ ad variations with consistent product/person identity +- Create product-in-context images (your SaaS on different devices) +- Style-match to existing brand assets using reference images +- Rapid A/B test image variations + +**Docs:** [Replicate Flux](https://replicate.com/black-forest-labs/flux-2-pro), [BFL API](https://docs.bfl.ml/) + +--- + +### Ideogram + +Specialized in typography and text rendering within images. + +**Best for:** Ad banners with text, branded graphics, social ad images with headlines +**API:** Ideogram API, Runware +**Pricing:** ~$0.06/image (API), ~$0.009/image (subscription) + +**Strengths:** +- Best-in-class text rendering (~90% accuracy vs ~30% for most tools) +- Style reference system (upload up to 3 reference images) +- 4.3 billion style presets for consistent brand aesthetics +- Strong at logos and branded typography + +**Ad creative use cases:** +- Generate ad banners with headline text directly in the image +- Create social media graphics with branded text overlays +- Produce multiple design variations with consistent typography +- Generate promotional materials without needing a designer for each iteration + +**Docs:** [Ideogram API](https://developer.ideogram.ai/), [Ideogram](https://ideogram.ai/) + +--- + +### Other Image Tools + +| Tool | Best For | API Status | Notes | +|------|----------|------------|-------| +| **DALL-E 3** (OpenAI) | General image generation | Official API | Integrated with ChatGPT, good text rendering | +| **Midjourney** | Artistic, high-aesthetic images | No official public API | Discord-based; unofficial APIs exist but risk bans | +| **Stable Diffusion** | Self-hosted, customizable | Open source | Best for teams with GPU infrastructure | + +--- + +## Video Generation + +### Google Veo + +Google DeepMind's video generation model, available through the Gemini API and Vertex AI. + +**Best for:** High-quality video ads with native audio, vertical video for social +**API:** Gemini API, Vertex AI +**Pricing:** ~$0.15/sec (Veo 3.1 Fast), ~$0.40/sec (Veo 3.1 Standard) + +**Capabilities:** +- Up to 60 seconds at 1080p +- Native audio generation (dialogue, sound effects, ambient) +- Vertical 9:16 output for Stories/Reels/Shorts +- Upscale to 4K +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Generate short video ads (15-30 sec) from text descriptions +- Create vertical video ads for TikTok, Reels, Shorts +- Produce product demos with voiceover +- Generate multiple video variations from the same prompt with different styles + +**Docs:** [Veo on Vertex AI](https://cloud.google.com/vertex-ai/generative-ai/docs/video/overview) + +--- + +### Kling (Kuaishou) + +Video generation with simultaneous audio-visual generation and camera controls. + +**Best for:** Cinematic video ads, longer-form content, audio-synced video +**API:** Kling API, PiAPI, fal.ai +**Pricing:** ~$0.09/sec (via fal.ai third-party) + +**Capabilities:** +- Up to 3 minutes at 1080p/30-48fps +- Simultaneous audio-visual generation (Kling 2.6) +- Text-to-video and image-to-video +- Motion and camera controls + +**Ad creative use cases:** +- Longer product explainer videos +- Cinematic brand videos with synchronized audio +- Animate product images into video ads + +**Docs:** [Kling AI Developer](https://klingai.com/global/dev/model/video) + +--- + +### Runway + +Video generation and editing platform with strong controllability. + +**Best for:** Controlled video generation, style-consistent content, editing existing footage +**API:** Runway Developer Portal + +**Capabilities:** +- Gen-4: Character/scene consistency across shots +- Motion brush and camera controls +- Image-to-video with reference images +- Video-to-video style transfer + +**Ad creative use cases:** +- Generate video ads with consistent characters/products across scenes +- Style-transfer existing footage to match brand aesthetics +- Extend or remix existing video content + +**Docs:** [Runway API](https://docs.dev.runwayml.com/) + +--- + +### Sora 2 (OpenAI) + +OpenAI's video generation model with synchronized audio. + +**Best for:** High-fidelity video with dialogue and sound +**API:** OpenAI API +**Pricing:** Free tier available; Pro from $0.10-0.50/sec depending on resolution + +**Capabilities:** +- Up to 60 seconds with synchronized audio +- Dialogue, sound effects, and ambient audio +- sora-2 (fast) and sora-2-pro (quality) variants +- Text-to-video and image-to-video + +**Ad creative use cases:** +- Video testimonials and talking-head style ads +- Product demo videos with narration +- Narrative brand videos + +**Docs:** [OpenAI Video Generation](https://platform.openai.com/docs/guides/video-generation) + +--- + +### Seedance 2.0 (ByteDance) + +ByteDance's video generation model with simultaneous audio-visual generation and multimodal inputs. + +**Best for:** Fast, affordable video ads with native audio, multimodal reference inputs +**API:** BytePlus (official), Replicate, WaveSpeedAI, fal.ai (third-party); OpenAI-compatible API format +**Pricing:** ~$0.10-0.80/min depending on resolution (estimated 10-100x cheaper than Sora 2 per clip) + +**Capabilities:** +- Up to 20 seconds at up to 2K resolution +- Simultaneous audio-visual generation (Dual-Branch Diffusion Transformer) +- Text-to-video and image-to-video +- Up to 12 reference files for multimodal input +- OpenAI-compatible API structure + +**Ad creative use cases:** +- High-volume short video ad production at low cost +- Video ads with synchronized voiceover and sound effects in one pass +- Multi-reference generation (feed product images, brand assets, style references) +- Rapid iteration on video ad concepts + +**Docs:** [Seedance](https://seed.bytedance.com/en/seedance2_0) + +--- + +### Higgsfield + +Full-stack video creation platform with cinematic camera controls. + +**Best for:** Social video ads, cinematic style, mobile-first content +**Platform:** [higgsfield.ai](https://higgsfield.ai/) + +**Capabilities:** +- 50+ professional camera movements (zooms, pans, FPV drone shots) +- Image-to-video animation +- Built-in editing, transitions, and keyframing +- All-in-one workflow: image gen, animation, editing + +**Ad creative use cases:** +- Social media video ads with cinematic feel +- Animate product images into dynamic video +- Create multiple video variations with different camera styles +- Quick-turn video content for social campaigns + +--- + +### Video Tool Comparison + +| Tool | Max Length | Audio | Resolution | API | Best For | +|------|-----------|-------|------------|-----|----------| +| **Veo 3.1** | 60 sec | Native | 1080p/4K | Gemini | Vertical social video | +| **Kling 2.6** | 3 min | Native | 1080p | Third-party | Longer cinematic | +| **Runway Gen-4** | 10 sec | No | 1080p | Official | Controlled, consistent | +| **Sora 2** | 60 sec | Native | 1080p | Official | Dialogue-heavy | +| **Seedance 2.0** | 20 sec | Native | 2K | Official + third-party | Affordable high-volume | +| **Higgsfield** | Varies | Yes | 1080p | Web-based | Social, mobile-first | + +--- + +## Voice & Audio Generation + +For layering realistic voiceovers onto video ads, adding narration to product demos, or generating audio for Remotion-rendered videos. These tools turn ad scripts into natural-sounding voice tracks. + +### When to Use Voice Tools + +Many video generators (Veo, Kling, Sora, Seedance) now include native audio. Use standalone voice tools when you need: + +- **Voiceover on silent video** — Runway Gen-4 and Remotion produce silent output +- **Brand voice consistency** — Clone a specific voice for all ads +- **Multi-language versions** — Same ad script in 20+ languages +- **Script iteration** — Re-record voiceover without reshooting video +- **Precise control** — Exact timing, emotion, and pacing + +--- + +### ElevenLabs + +The market leader in realistic voice generation and voice cloning. + +**Best for:** Most natural-sounding voiceovers, brand voice cloning, multilingual +**API:** REST API with streaming support +**Pricing:** ~$0.12-0.30 per 1,000 characters depending on plan; starts at $5/month + +**Capabilities:** +- 29+ languages with natural accent and intonation +- Voice cloning from short audio clips (instant) or longer recordings (professional) +- Emotion and style control +- Streaming for real-time generation +- Voice library with hundreds of pre-built voices + +**Ad creative use cases:** +- Generate voiceover tracks for video ads +- Clone your brand spokesperson's voice for all ad variations +- Produce the same ad in 10+ languages from one script +- A/B test different voice styles (authoritative vs. friendly vs. urgent) + +**API example:** +```bash +curl -X POST "https://api.elevenlabs.io/v1/text-to-speech/{voice_id}" \ + -H "xi-api-key: $ELEVENLABS_API_KEY" \ + -H "Content-Type: application/json" \ + -d '{ + "text": "Stop wasting hours on manual reporting. Try DataFlow free for 14 days.", + "model_id": "eleven_multilingual_v2", + "voice_settings": {"stability": 0.5, "similarity_boost": 0.75} + }' --output voiceover.mp3 +``` + +**Docs:** [ElevenLabs API](https://elevenlabs.io/docs/api-reference/text-to-speech) + +--- + +### OpenAI TTS + +Simple, affordable text-to-speech built into the OpenAI API. + +**Best for:** Quick voiceovers, cost-effective at scale, simple integration +**API:** OpenAI API (same SDK as GPT/DALL-E) +**Pricing:** $15/million chars (standard), $30/million chars (HD); ~$0.015/min with gpt-4o-mini-tts + +**Capabilities:** +- 13 built-in voices (no custom cloning) +- Multiple languages +- Real-time streaming +- HD quality option +- Simple API — same SDK you already use for GPT + +**Ad creative use cases:** +- Fast, cheap voiceover for draft/test ad versions +- High-volume narration at low cost +- Prototype ad audio before investing in premium voice + +**Docs:** [OpenAI TTS](https://platform.openai.com/docs/guides/text-to-speech) + +--- + +### Cartesia Sonic + +Ultra-low latency voice generation built for real-time applications. + +**Best for:** Real-time voice, lowest latency, emotional expressiveness +**API:** REST + WebSocket streaming +**Pricing:** Starts at $5/month; pay-as-you-go from $0.03/min + +**Capabilities:** +- 40ms time-to-first-audio (fastest in class) +- 15+ languages +- Nonverbal expressiveness: laughter, breathing, emotional inflections +- Sonic Turbo for even lower latency +- Streaming API for real-time generation + +**Ad creative use cases:** +- Real-time ad preview during creative iteration +- Interactive demo videos with dynamic narration +- Ads requiring natural laughter, sighs, or emotional reactions + +**Docs:** [Cartesia Sonic](https://docs.cartesia.ai/build-with-cartesia/tts-models/latest) + +--- + +### Voicebox (Open Source) + +Free, local-first voice synthesis studio powered by Qwen3-TTS. The open-source alternative to ElevenLabs. + +**Best for:** Free voice cloning, local/private generation, zero-cost batch production +**API:** Local REST API at `http://localhost:8000` +**Pricing:** Free (MIT license). Runs entirely on your machine. +**Stack:** Tauri (Rust) + React + FastAPI (Python) + +**Capabilities:** +- Voice cloning from short audio samples via Qwen3-TTS +- Multi-language support (English, Chinese, more planned) +- Multi-track timeline editor for composing conversations +- 4-5x faster inference on Apple Silicon via MLX Metal acceleration +- Local REST API for programmatic generation +- No cloud dependency — all processing on-device + +**Ad creative use cases:** +- Free voice cloning for brand spokesperson across all ad variations +- Batch generate voiceovers without per-character costs +- Private/local generation when ad content is sensitive or pre-launch +- Prototype voice variations before committing to a paid service + +**API example:** +```bash +curl -X POST http://localhost:8000/generate \ + -H "Content-Type: application/json" \ + -d '{"text": "Stop wasting hours on manual reporting.", "profile_id": "abc123", "language": "en"}' +``` + +**Install:** Desktop apps for macOS and Windows at [voicebox.sh](https://voicebox.sh), or build from source: +```bash +git clone https://github.com/jamiepine/voicebox.git +cd voicebox && make setup && make dev +``` + +**Docs:** [GitHub](https://github.com/jamiepine/voicebox) + +--- + +### Other Voice Tools + +| Tool | Best For | Differentiator | API | +|------|----------|---------------|-----| +| **PlayHT** | Large voice library, low latency | 900+ voices, <300ms latency, ultra-realistic | [play.ht](https://play.ht/) | +| **Resemble AI** | Enterprise voice cloning | On-premise deployment, real-time speech-to-speech | [resemble.ai](https://www.resemble.ai/) | +| **WellSaid Labs** | Ethical, commercial-safe voices | Voices from compensated actors, safe for commercial use | [wellsaid.io](https://www.wellsaid.io/) | +| **Fish Audio** | Budget-friendly, emotion control | ~50-70% cheaper than ElevenLabs, emotion tags | [fish.audio](https://fish.audio/) | +| **Murf AI** | Non-technical teams | Browser-based studio, 200+ voices | [murf.ai](https://murf.ai/) | +| **Google Cloud TTS** | Google ecosystem, scale | 220+ voices, 40+ languages, enterprise SLAs | [Google TTS](https://cloud.google.com/text-to-speech) | +| **Amazon Polly** | AWS ecosystem, cost | Neural voices, SSML control, cheap at volume | [Amazon Polly](https://aws.amazon.com/polly/) | + +--- + +### Voice Tool Comparison + +| Tool | Quality | Cloning | Languages | Latency | Price/1K chars | +|------|---------|---------|-----------|---------|----------------| +| **ElevenLabs** | Best | Yes (instant + pro) | 29+ | ~200ms | $0.12-0.30 | +| **OpenAI TTS** | Good | No | 13+ | ~300ms | $0.015-0.030 | +| **Cartesia Sonic** | Very good | No | 15+ | ~40ms | ~$0.03/min | +| **PlayHT** | Very good | Yes | 140+ | <300ms | ~$0.10-0.20 | +| **Fish Audio** | Good | Yes | 13+ | ~200ms | ~$0.05-0.10 | +| **WellSaid** | Very good | No (actor voices) | English | ~300ms | Custom pricing | +| **Voicebox** | Good | Yes (local) | 2+ | Local | Free (open source) | + +### Choosing a Voice Tool + +``` +Need voiceover for ads? +├── Need to clone a specific brand voice? +│ ├── Best quality → ElevenLabs +│ ├── Enterprise/on-premise → Resemble AI +│ └── Budget-friendly → Fish Audio, PlayHT +├── Need multilingual (same ad, many languages)? +│ ├── Most languages → PlayHT (140+) +│ └── Best quality → ElevenLabs (29+) +├── Need free / open source / local? +│ └── Voicebox (MIT, runs on your machine) +├── Need cheap, fast, good-enough? +│ └── OpenAI TTS ($0.015/min) +├── Need commercially-safe licensing? +│ └── WellSaid Labs (actor-compensated voices) +└── Need real-time/interactive? + └── Cartesia Sonic (40ms TTFA) +``` + +### Workflow: Voice + Video + +``` +1. Write ad script (use ad-creative skill for copy) +2. Generate voiceover with ElevenLabs/OpenAI TTS +3. Generate or render video: + a. Silent video from Runway/Remotion → layer voice track + b. Or use Veo/Sora/Seedance with native audio (skip separate VO) +4. Combine with ffmpeg if layering separately: + ffmpeg -i video.mp4 -i voiceover.mp3 -c:v copy -c:a aac output.mp4 +5. Generate variations (different scripts, voices, or languages) +``` + +--- + +## Code-Based Video: Remotion + +For templated, data-driven video ads at scale, Remotion is the best option. Unlike AI video generators that produce unique video from prompts, Remotion uses React code to render deterministic, brand-perfect video from templates and data. + +**Best for:** Templated ad variations, personalized video, brand-consistent production +**Stack:** React + TypeScript +**Pricing:** Free for individuals/small teams; commercial license required for 4+ employees +**Docs:** [remotion.dev](https://www.remotion.dev/) + +### Why Remotion for Ads + +| AI Video Generators | Remotion | +|---------------------|----------| +| Unique output each time | Deterministic, pixel-perfect | +| Prompt-based, less control | Full code control over every frame | +| Hard to match brand exactly | Exact brand colors, fonts, spacing | +| One-at-a-time generation | Batch render hundreds from data | +| No dynamic data insertion | Personalize with names, prices, stats | + +### Ad Creative Use Cases + +**1. Dynamic product ads** +Feed a JSON array of products and render a unique video ad for each: +```tsx +// Simplified Remotion component for product ads +export const ProductAd: React.FC<{ + productName: string; + price: string; + imageUrl: string; + tagline: string; +}> = ({productName, price, imageUrl, tagline}) => { + return ( + + +

{productName}

+

{tagline}

+
{price}
+
Shop Now
+ + ); +}; +``` + +**2. A/B test video variations** +Render the same template with different headlines, CTAs, or color schemes: +```tsx +const variations = [ + {headline: "Save 50% Today", cta: "Get the Deal", theme: "urgent"}, + {headline: "Join 10K+ Teams", cta: "Start Free", theme: "social-proof"}, + {headline: "Built for Speed", cta: "Try It Now", theme: "benefit"}, +]; +// Render all variations programmatically +``` + +**3. Personalized outreach videos** +Generate videos addressing prospects by name for cold outreach or sales. + +**4. Social ad batch production** +Render the same content across different aspect ratios: +- 1:1 for feed +- 9:16 for Stories/Reels +- 16:9 for YouTube + +### Remotion Workflow for Ad Creative + +``` +1. Design template in React (or use AI to generate the component) +2. Define data schema (products, headlines, CTAs, images) +3. Feed data array into template +4. Batch render all variations +5. Upload to ad platform +``` + +### Getting Started + +```bash +# Create a new Remotion project +npx create-video@latest + +# Render a single video +npx remotion render src/index.ts MyComposition out/video.mp4 + +# Batch render from data +npx remotion render src/index.ts MyComposition --props='{"data": [...]}' +``` + +--- + +## Choosing the Right Tool + +### Decision Tree + +``` +Need video ads? +├── Templated, data-driven (same structure, different data) +│ └── Use Remotion +├── Unique creative from prompts (exploratory) +│ ├── Need dialogue/voiceover? → Sora 2, Veo 3.1, Kling 2.6, Seedance 2.0 +│ ├── Need consistency across scenes? → Runway Gen-4 +│ ├── Need vertical social video? → Veo 3.1 (native 9:16) +│ ├── Need high volume at low cost? → Seedance 2.0 +│ └── Need cinematic camera work? → Higgsfield, Kling +└── Both → Use AI gen for hero creative, Remotion for variations + +Need image ads? +├── Need text/headlines in image? → Ideogram +├── Need product consistency across variations? → Flux (multi-ref) +├── Need quick iterations on existing images? → Nano Banana Pro +├── Need highest visual quality? → Flux Pro, Midjourney +└── Need high volume at low cost? → Flux Klein, Nano Banana +``` + +### Cost Comparison for 100 Ad Variations + +| Approach | Tool | Approximate Cost | +|----------|------|-----------------| +| 100 static images | Nano Banana Pro | ~$4-24 | +| 100 static images | Flux Dev | ~$1-2 | +| 100 static images | Ideogram API | ~$6 | +| 100 × 15-sec videos | Veo 3.1 Fast | ~$225 | +| 100 × 15-sec videos | Remotion (templated) | ~$0 (self-hosted render) | +| 10 hero videos + 90 templated | Veo + Remotion | ~$22 + render time | + +### Recommended Workflow for Scaled Ad Production + +1. **Generate hero creative** with AI (Nano Banana, Flux, Veo) — high-quality, exploratory +2. **Build templates** in Remotion based on winning creative patterns +3. **Batch produce variations** with Remotion using data (products, headlines, CTAs) +4. **Iterate** — use AI tools for new angles, Remotion for scale + +This hybrid approach gives you the creative exploration of AI generators and the consistency and scale of code-based rendering. + +--- + +## Platform-Specific Image Specs + +When generating images for ads, request the correct dimensions: + +| Platform | Placement | Aspect Ratio | Recommended Size | +|----------|-----------|-------------|-----------------| +| Meta Feed | Single image | 1:1 | 1080x1080 | +| Meta Stories/Reels | Vertical | 9:16 | 1080x1920 | +| Meta Carousel | Square | 1:1 | 1080x1080 | +| Google Display | Landscape | 1.91:1 | 1200x628 | +| Google Display | Square | 1:1 | 1200x1200 | +| LinkedIn Feed | Landscape | 1.91:1 | 1200x627 | +| LinkedIn Feed | Square | 1:1 | 1200x1200 | +| TikTok Feed | Vertical | 9:16 | 1080x1920 | +| Twitter/X Feed | Landscape | 16:9 | 1200x675 | +| Twitter/X Card | Landscape | 1.91:1 | 800x418 | + +Include these dimensions in your generation prompts to avoid needing to crop or resize. diff --git a/templates/skills-marketplace/ad-creative/references/platform-specs.md b/templates/skills-marketplace/ad-creative/references/platform-specs.md new file mode 100644 index 00000000..c9a3c4a5 --- /dev/null +++ b/templates/skills-marketplace/ad-creative/references/platform-specs.md @@ -0,0 +1,213 @@ +# Platform Specs Reference + +Complete character limits, format requirements, and best practices for each ad platform. + +--- + +## Google Ads + +### Responsive Search Ads (RSAs) + +| Element | Character Limit | Required | Notes | +|---------|----------------|----------|-------| +| Headline | 30 chars | 3 minimum, 15 max | Any 3 may be shown together | +| Description | 90 chars | 2 minimum, 4 max | Any 2 may be shown together | +| Display path 1 | 15 chars | Optional | Appears after domain in URL | +| Display path 2 | 15 chars | Optional | Appears after path 1 | +| Final URL | No limit | Required | Landing page URL | + +**Combination rules:** +- Google selects up to 3 headlines and 2 descriptions to show +- Headlines appear separated by " | " or stacked +- Any headline can appear in any position unless pinned +- Pinning reduces Google's ability to optimize — use sparingly + +**Pinning strategy:** +- Pin your brand name to position 1 if brand guidelines require it +- Pin your strongest CTA to position 2 or 3 +- Leave most headlines unpinned for machine learning + +**Headline mix recommendation (15 headlines):** +- 3-4 keyword-focused (match search intent) +- 3-4 benefit-focused (what they get) +- 2-3 social proof (numbers, awards, customers) +- 2-3 CTA-focused (action to take) +- 1-2 differentiators (why you over competitors) +- 1 brand name headline + +**Description mix recommendation (4 descriptions):** +- 1 benefit + proof point +- 1 feature + outcome +- 1 social proof + CTA +- 1 urgency/offer + CTA (if applicable) + +### Performance Max + +| Element | Character Limit | Notes | +|---------|----------------|-------| +| Headline | 30 chars (5 required) | Short headlines for various placements | +| Long headline | 90 chars (5 required) | Used in display, video, discover | +| Description | 90 chars (1 required, 5 max) | Accompany various ad formats | +| Business name | 25 chars | Required | + +### Display Ads + +| Element | Character Limit | +|---------|----------------| +| Headline | 30 chars | +| Long headline | 90 chars | +| Description | 90 chars | +| Business name | 25 chars | + +--- + +## Meta Ads (Facebook & Instagram) + +### Single Image / Video / Carousel + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Primary text | 125 chars | 2,200 chars | Text above image; truncated after ~125 | +| Headline | 40 chars | 255 chars | Below image; truncated after ~40 | +| Description | 30 chars | 255 chars | Below headline; may not show | +| URL display link | 40 chars | N/A | Optional custom display URL | + +**Placement-specific notes:** +- **Feed**: All elements show; primary text most visible +- **Stories/Reels**: Primary text overlaid; keep under 72 chars +- **Right column**: Only headline visible; skip description +- **Audience Network**: Varies by publisher + +**Best practices:** +- Front-load the hook in primary text (first 125 chars) +- Use line breaks for readability in longer primary text +- Emojis: test, but don't overuse — 1-2 per ad max +- Questions in primary text increase engagement +- Headline should be a clear CTA or value statement + +### Lead Ads (Instant Form) + +| Element | Limit | +|---------|-------| +| Greeting headline | 60 chars | +| Greeting description | 360 chars | +| Privacy policy text | 200 chars | + +--- + +## LinkedIn Ads + +### Single Image Ad + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Intro text | 150 chars | 600 chars | Above the image; truncated after ~150 | +| Headline | 70 chars | 200 chars | Below the image | +| Description | 100 chars | 300 chars | Only shows on Audience Network | + +### Carousel Ad + +| Element | Limit | +|---------|-------| +| Intro text | 255 chars | +| Card headline | 45 chars | +| Card count | 2-10 cards | + +### Message Ad (InMail) + +| Element | Limit | +|---------|-------| +| Subject line | 60 chars | +| Message body | 1,500 chars | +| CTA button | 20 chars | + +### Text Ad + +| Element | Limit | +|---------|-------| +| Headline | 25 chars | +| Description | 75 chars | + +**LinkedIn-specific guidelines:** +- Professional tone, but not boring +- Use job-specific language the audience recognizes +- Statistics and data points perform well +- Avoid consumer-style hype ("Amazing!" "Incredible!") +- First-person testimonials from peers resonate + +--- + +## TikTok Ads + +### In-Feed Ads + +| Element | Recommended | Maximum | Notes | +|---------|-------------|---------|-------| +| Ad text | 80 chars | 100 chars | Above the video | +| Display name | N/A | 40 chars | Brand name | +| CTA button | Platform options | Predefined | Select from TikTok's options | + +### Spark Ads (Boosted Organic) + +| Element | Notes | +|---------|-------| +| Caption | Uses original post caption | +| CTA button | Added by advertiser | +| Display name | Original creator's handle | + +**TikTok-specific guidelines:** +- Native content outperforms polished ads +- First 2 seconds determine if they watch +- Use trending sounds and formats +- Text overlay is essential (most watch with sound off) +- Vertical video only (9:16) + +--- + +## Twitter/X Ads + +### Promoted Tweets + +| Element | Limit | Notes | +|---------|-------|-------| +| Tweet text | 280 chars | Full tweet with image/video | +| Card headline | 70 chars | Website card | +| Card description | 200 chars | Website card | + +### Website Cards + +| Element | Limit | +|---------|-------| +| Headline | 70 chars | +| Description | 200 chars | + +**Twitter/X-specific guidelines:** +- Conversational, casual tone +- Short sentences work best +- One clear message per tweet +- Hashtags: 1-2 max (0 is often better for ads) +- Threads can work for consideration-stage content + +--- + +## Character Counting Tips + +- **Spaces count** as characters on all platforms +- **Emojis** count as 1-2 characters depending on platform +- **Special characters** (|, &, etc.) count as 1 character +- **URLs** in body text count against limits +- **Dynamic keyword insertion** (`{KeyWord:default}`) can exceed limits — set safe defaults +- Always verify in the platform's ad preview before launching + +--- + +## Multi-Platform Creative Adaptation + +When creating for multiple platforms simultaneously, start with the most restrictive format: + +1. **Google Search headlines** (30 chars) — forces the tightest messaging +2. **Expand to Meta headlines** (40 chars) — add a word or two +3. **Expand to LinkedIn intro text** (150 chars) — add context and proof +4. **Expand to Meta primary text** (125+ chars) — full hook and value prop + +This cascading approach ensures your core message works everywhere, then gets enriched for platforms that allow more space. diff --git a/templates/skills-marketplace/ads/SKILL.md b/templates/skills-marketplace/ads/SKILL.md new file mode 100644 index 00000000..7d9c4e60 --- /dev/null +++ b/templates/skills-marketplace/ads/SKILL.md @@ -0,0 +1,317 @@ +--- +name: ads +description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see cro." +metadata: + version: 2.0.0 +--- + +# Paid Ads + +You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition. + +## Before Starting + +**Check for product marketing context first:** +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): + +### 1. Campaign Goals +- What's the primary objective? (Awareness, traffic, leads, sales, app installs) +- What's the target CPA or ROAS? +- What's the monthly/weekly budget? +- Any constraints? (Brand guidelines, compliance, geographic) + +### 2. Product & Offer +- What are you promoting? (Product, free trial, lead magnet, demo) +- What's the landing page URL? +- What makes this offer compelling? + +### 3. Audience +- Who is the ideal customer? +- What problem does your product solve for them? +- What are they searching for or interested in? +- Do you have existing customer data for lookalikes? + +### 4. Current State +- Have you run ads before? What worked/didn't? +- Do you have existing pixel/conversion data? +- What's your current funnel conversion rate? + +--- + +## Platform Selection Guide + +| Platform | Best For | Use When | +|----------|----------|----------| +| **Google Ads** | High-intent search traffic | People actively search for your solution | +| **Meta** | Demand generation, visual products | Creating demand, strong creative assets | +| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters, higher price points | +| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X, timely content | +| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity | + +--- + +## Campaign Structure Best Practices + +### Account Organization + +``` +Account +├── Campaign 1: [Objective] - [Audience/Product] +│ ├── Ad Set 1: [Targeting variation] +│ │ ├── Ad 1: [Creative variation A] +│ │ ├── Ad 2: [Creative variation B] +│ │ └── Ad 3: [Creative variation C] +│ └── Ad Set 2: [Targeting variation] +└── Campaign 2... +``` + +### Naming Conventions + +``` +[Platform]_[Objective]_[Audience]_[Offer]_[Date] + +Examples: +META_Conv_Lookalike-Customers_FreeTrial_2024Q1 +GOOG_Search_Brand_Demo_Ongoing +LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24 +``` + +### Budget Allocation + +**Testing phase (first 2-4 weeks):** +- 70% to proven/safe campaigns +- 30% to testing new audiences/creative + +**Scaling phase:** +- Consolidate budget into winning combinations +- Increase budgets 20-30% at a time +- Wait 3-5 days between increases for algorithm learning + +--- + +## Ad Copy Frameworks + +### Key Formulas + +**Problem-Agitate-Solve (PAS):** +> [Problem] → [Agitate the pain] → [Introduce solution] → [CTA] + +**Before-After-Bridge (BAB):** +> [Current painful state] → [Desired future state] → [Your product as bridge] + +**Social Proof Lead:** +> [Impressive stat or testimonial] → [What you do] → [CTA] + +**For detailed templates and headline formulas**: See [references/ad-copy-templates.md](references/ad-copy-templates.md) + +--- + +## Audience Targeting Overview + +### Platform Strengths + +| Platform | Key Targeting | Best Signals | +|----------|---------------|--------------| +| Google | Keywords, search intent | What they're searching | +| Meta | Interests, behaviors, lookalikes | Engagement patterns | +| LinkedIn | Job titles, companies, industries | Professional identity | + +### Key Concepts + +- **Lookalikes**: Base on best customers (by LTV), not all customers +- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners) +- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend + +**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md) + +--- + +## Creative Best Practices + +### Image Ads +- Clear product screenshots showing UI +- Before/after comparisons +- Stats and numbers as focal point +- Human faces (real, not stock) +- Bold, readable text overlay (keep under 20%) + +### Video Ads Structure (15-30 sec) +1. Hook (0-3 sec): Pattern interrupt, question, or bold statement +2. Problem (3-8 sec): Relatable pain point +3. Solution (8-20 sec): Show product/benefit +4. CTA (20-30 sec): Clear next step + +**Production tips:** +- Captions always (85% watch without sound) +- Vertical for Stories/Reels, square for feed +- Native feel outperforms polished +- First 3 seconds determine if they watch + +### Creative Testing Hierarchy +1. Concept/angle (biggest impact) +2. Hook/headline +3. Visual style +4. Body copy +5. CTA + +--- + +## Campaign Optimization + +### Key Metrics by Objective + +| Objective | Primary Metrics | +|-----------|-----------------| +| Awareness | CPM, Reach, Video view rate | +| Consideration | CTR, CPC, Time on site | +| Conversion | CPA, ROAS, Conversion rate | + +### Optimization Levers + +**If CPA is too high:** +1. Check landing page (is the problem post-click?) +2. Tighten audience targeting +3. Test new creative angles +4. Improve ad relevance/quality score +5. Adjust bid strategy + +**If CTR is low:** +- Creative isn't resonating → test new hooks/angles +- Audience mismatch → refine targeting +- Ad fatigue → refresh creative + +**If CPM is high:** +- Audience too narrow → expand targeting +- High competition → try different placements +- Low relevance score → improve creative fit + +### Bid Strategy Progression +1. Start with manual or cost caps +2. Gather conversion data (50+ conversions) +3. Switch to automated with targets based on historical data +4. Monitor and adjust targets based on results + +--- + +## Retargeting Strategies + +### Funnel-Based Approach + +| Funnel Stage | Audience | Message | Goal | +|--------------|----------|---------|------| +| Top | Blog readers, video viewers | Educational, social proof | Move to consideration | +| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision | +| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert | + +### Retargeting Windows + +| Stage | Window | Frequency Cap | +|-------|--------|---------------| +| Hot (cart/trial) | 1-7 days | Higher OK | +| Warm (key pages) | 7-30 days | 3-5x/week | +| Cold (any visit) | 30-90 days | 1-2x/week | + +### Exclusions to Set Up +- Existing customers (unless upsell) +- Recent converters (7-14 day window) +- Bounced visitors (<10 sec) +- Irrelevant pages (careers, support) + +--- + +## Reporting & Analysis + +### Weekly Review +- Spend vs. budget pacing +- CPA/ROAS vs. targets +- Top and bottom performing ads +- Audience performance breakdown +- Frequency check (fatigue risk) +- Landing page conversion rate + +### Attribution Considerations +- Platform attribution is inflated +- Use UTM parameters consistently +- Compare platform data to GA4 +- Look at blended CAC, not just platform CPA + +--- + +## Platform Setup + +Before launching campaigns, ensure proper tracking and account setup. + +**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md) + +**For conversion pixel installation and event setup**: See [references/conversion-tracking.md](references/conversion-tracking.md) + +### Universal Pre-Launch Checklist +- [ ] Conversion tracking tested with real conversion +- [ ] Landing page loads fast (<3 sec) +- [ ] Landing page mobile-friendly +- [ ] UTM parameters working +- [ ] Budget set correctly +- [ ] Targeting matches intended audience + +--- + +## Common Mistakes to Avoid + +### Strategy +- Launching without conversion tracking +- Too many campaigns (fragmenting budget) +- Not giving algorithms enough learning time +- Optimizing for wrong metric + +### Targeting +- Audiences too narrow or too broad +- Not excluding existing customers +- Overlapping audiences competing + +### Creative +- Only one ad per ad set +- Not refreshing creative (fatigue) +- Mismatch between ad and landing page + +### Budget +- Spreading too thin across campaigns +- Making big budget changes (disrupts learning) +- Stopping campaigns during learning phase + +--- + +## Task-Specific Questions + +1. What platform(s) are you currently running or want to start with? +2. What's your monthly ad budget? +3. What does a successful conversion look like (and what's it worth)? +4. Do you have existing creative assets or need to create them? +5. What landing page will ads point to? +6. Do you have pixel/conversion tracking set up? + +--- + +## Tool Integrations + +For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms: + +| Platform | Best For | MCP | Guide | +|----------|----------|:---:|-------| +| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) | +| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) | +| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) | +| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) | + +For tracking setup, see [references/conversion-tracking.md](references/conversion-tracking.md), [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md) + +--- + +## Related Skills + +- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale +- **copywriting**: For landing page copy that converts ad traffic +- **analytics**: For proper conversion tracking setup +- **ab-testing**: For landing page testing to improve ROAS +- **cro**: For optimizing post-click conversion rates diff --git a/templates/skills-marketplace/ads/evals/evals.json b/templates/skills-marketplace/ads/evals/evals.json new file mode 100644 index 00000000..17c11eb2 --- /dev/null +++ b/templates/skills-marketplace/ads/evals/evals.json @@ -0,0 +1,90 @@ +{ + "skill_name": "ads", + "evals": [ + { + "id": 1, + "prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?", + "expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.", + "assertions": [ + "Checks for product-marketing.md", + "Applies platform selection guide", + "Recommends platforms appropriate for B2B HR audience", + "Recommends campaign structure with naming conventions", + "Defines audience targeting per platform", + "Sets budget allocation across platforms", + "Defines success metrics", + "Recommends starting structure and scaling plan" + ], + "files": [] + }, + { + "id": 2, + "prompt": "Our Google Ads CPC is $12 and our cost per lead is $180. Is that good? We're getting about 80 leads/month from a $15k budget.", + "expected_output": "Should evaluate the metrics in context. Should assess: $12 CPC for B2B (reasonable depending on industry), $180 CPL (depends on LTV — need to compare against customer lifetime value), 80 leads/month from $15k (math checks out). Should apply the campaign optimization framework: check quality score, search term relevance, landing page conversion rate, negative keywords. Should recommend specific optimization levers to reduce CPC and CPL. Should frame performance against industry benchmarks if applicable. Should ask about downstream conversion rates (lead → demo → customer).", + "assertions": [ + "Evaluates metrics in context", + "Compares CPL against LTV considerations", + "Applies campaign optimization framework", + "Recommends specific optimization levers", + "Asks about downstream conversion rates", + "Provides industry context for benchmarking" + ], + "files": [] + }, + { + "id": 3, + "prompt": "we want to run retargeting ads for people who visited our site but didn't convert. how should we set this up?", + "expected_output": "Should trigger on casual phrasing. Should apply the retargeting strategies section, specifically the funnel-based approach. Should recommend audience segments: all visitors (broad), pricing page visitors (high intent), blog readers (lower intent), and cart/signup abandoners (highest intent). Should recommend different messaging and offers for each segment. Should address frequency capping to avoid ad fatigue. Should recommend retargeting platforms (Meta, Google Display, LinkedIn). Should include duration windows for each audience.", + "assertions": [ + "Triggers on casual phrasing", + "Applies funnel-based retargeting approach", + "Recommends audience segments by intent level", + "Recommends different messaging per segment", + "Addresses frequency capping", + "Recommends retargeting platforms", + "Includes audience duration windows" + ], + "files": [] + }, + { + "id": 4, + "prompt": "Should we advertise on TikTok? We sell accounting software to small businesses. Our current ads are on Google and Meta.", + "expected_output": "Should apply the platform selection guide for TikTok specifically. Should evaluate TikTok fit for accounting software + small business audience: likely a weaker fit than Google/Meta for this category (lower purchase intent, younger skewing audience, less B2B targeting). Should discuss when TikTok CAN work for B2B (brand awareness, creative content, younger business owners). Should provide an honest recommendation with caveats. Should suggest a small test budget approach if they want to try.", + "assertions": [ + "Applies platform selection guide for TikTok", + "Evaluates fit for accounting + small business audience", + "Provides honest assessment of likely weaker fit", + "Discusses when TikTok can work for B2B", + "Suggests small test budget if proceeding", + "Compares to their existing Google/Meta performance" + ], + "files": [] + }, + { + "id": 5, + "prompt": "How do we structure our Google Ads campaigns? We have 50+ keywords we want to target for our CRM product.", + "expected_output": "Should apply the campaign structure and naming conventions framework. Should recommend organizing campaigns by theme/intent (brand, competitor, product features, pain points). Should recommend ad group structure (tightly themed, 5-15 keywords per group). Should define naming conventions for campaigns and ad groups. Should recommend match types strategy. Should include negative keyword lists. Should provide a sample campaign structure.", + "assertions": [ + "Applies campaign structure framework", + "Organizes campaigns by theme/intent", + "Recommends tight ad group structure", + "Defines naming conventions", + "Recommends match types strategy", + "Includes negative keyword lists", + "Provides sample campaign structure" + ], + "files": [] + }, + { + "id": 6, + "prompt": "Can you write some ad copy for our Facebook ads? We need headlines and descriptions for 5 different angles.", + "expected_output": "Should recognize this is an ad creative generation task, not campaign strategy. Should defer to or cross-reference the ad-creative skill, which handles platform-specific ad copy generation with character limits, angle-based variation, and batch generation. May provide brief ad copy framework guidance but should make clear that ad-creative is the right skill for generating ad copy at scale.", + "assertions": [ + "Recognizes this as ad creative generation", + "References or defers to ad-creative skill", + "Does not attempt bulk ad copy generation using campaign strategy patterns" + ], + "files": [] + } + ] +} diff --git a/templates/skills-marketplace/ads/references/ad-copy-templates.md b/templates/skills-marketplace/ads/references/ad-copy-templates.md new file mode 100644 index 00000000..04818406 --- /dev/null +++ b/templates/skills-marketplace/ads/references/ad-copy-templates.md @@ -0,0 +1,207 @@ +# Ad Copy Templates Reference + +Detailed formulas and templates for writing high-converting ad copy. + +## Contents +- Primary Text Formulas (Problem-Agitate-Solve, Before-After-Bridge, Social Proof Lead, Feature-Benefit Bridge, Direct Response) +- Headline Formulas (For Search Ads, For Social Ads) +- CTA Variations (Soft CTAs, Hard CTAs, Urgency CTAs, Action-Oriented CTAs) +- Platform-Specific Copy Guidelines (Google Search Ads, Meta Ads, LinkedIn Ads) +- Copy Testing Priority + +## Primary Text Formulas + +### Problem-Agitate-Solve (PAS) + +``` +[Problem statement] +[Agitate the pain] +[Introduce solution] +[CTA] +``` + +**Example:** +> Spending hours on manual reporting every week? +> While you're buried in spreadsheets, your competitors are making decisions. +> [Product] automates your reports in minutes. +> Start your free trial → + +--- + +### Before-After-Bridge (BAB) + +``` +[Current painful state] +[Desired future state] +[Your product as the bridge] +``` + +**Example:** +> Before: Chasing down approvals across email, Slack, and spreadsheets. +> After: Every approval tracked, automated, and on time. +> [Product] connects your tools and keeps projects moving. + +--- + +### Social Proof Lead + +``` +[Impressive stat or testimonial] +[What you do] +[CTA] +``` + +**Example:** +> "We cut our reporting time by 75%." — Sarah K., Marketing Director +> [Product] automates the reports you hate building. +> See how it works → + +--- + +### Feature-Benefit Bridge + +``` +[Feature] +[So that...] +[Which means...] +``` + +**Example:** +> Real-time collaboration on documents +> So your team always works from the latest version +> Which means no more version confusion or lost work + +--- + +### Direct Response + +``` +[Bold claim/outcome] +[Proof point] +[CTA with urgency if genuine] +``` + +**Example:** +> Cut your reporting time by 80% +> Join 5,000+ marketing teams already using [Product] +> Start free → First month 50% off + +--- + +## Headline Formulas + +### For Search Ads + +| Formula | Example | +|---------|---------| +| [Keyword] + [Benefit] | "Project Management That Teams Actually Use" | +| [Action] + [Outcome] | "Automate Reports \| Save 10 Hours Weekly" | +| [Question] | "Tired of Manual Data Entry?" | +| [Number] + [Benefit] | "500+ Teams Trust [Product] for [Outcome]" | +| [Keyword] + [Differentiator] | "CRM Built for Small Teams" | +| [Price/Offer] + [Keyword] | "Free Project Management \| No Credit Card" | + +### For Social Ads + +| Type | Example | +|------|---------| +| Outcome hook | "How we 3x'd our conversion rate" | +| Curiosity hook | "The reporting hack no one talks about" | +| Contrarian hook | "Why we stopped using [common tool]" | +| Specificity hook | "The exact template we use for..." | +| Question hook | "What if you could cut your admin time in half?" | +| Number hook | "7 ways to improve your workflow today" | +| Story hook | "We almost gave up. Then we found..." | + +--- + +## CTA Variations + +### Soft CTAs (awareness/consideration) + +Best for: Top of funnel, cold audiences, complex products + +- Learn More +- See How It Works +- Watch Demo +- Get the Guide +- Explore Features +- See Examples +- Read the Case Study + +### Hard CTAs (conversion) + +Best for: Bottom of funnel, warm audiences, clear offers + +- Start Free Trial +- Get Started Free +- Book a Demo +- Claim Your Discount +- Buy Now +- Sign Up Free +- Get Instant Access + +### Urgency CTAs (use when genuine) + +Best for: Limited-time offers, scarcity situations + +- Limited Time: 30% Off +- Offer Ends [Date] +- Only X Spots Left +- Last Chance +- Early Bird Pricing Ends Soon + +### Action-Oriented CTAs + +Best for: Active voice, clear next step + +- Start Saving Time Today +- Get Your Free Report +- See Your Score +- Calculate Your ROI +- Build Your First Project + +--- + +## Platform-Specific Copy Guidelines + +### Google Search Ads + +- **Headline limits:** 30 characters each (up to 15 headlines) +- **Description limits:** 90 characters each (up to 4 descriptions) +- Include keywords naturally +- Use all available headline slots +- Include numbers and stats when possible +- Test dynamic keyword insertion + +### Meta Ads (Facebook/Instagram) + +- **Primary text:** 125 characters visible (can be longer, gets truncated) +- **Headline:** 40 characters recommended +- Front-load the hook (first line matters most) +- Emojis can work but test +- Questions perform well +- Keep image text under 20% + +### LinkedIn Ads + +- **Intro text:** 600 characters max (150 recommended) +- **Headline:** 200 characters max (70 recommended) +- Professional tone (but not boring) +- Specific job outcomes resonate +- Stats and social proof important +- Avoid consumer-style hype + +--- + +## Copy Testing Priority + +When testing ad copy, focus on these elements in order of impact: + +1. **Hook/angle** (biggest impact on performance) +2. **Headline** +3. **Primary benefit** +4. **CTA** +5. **Supporting proof points** + +Test one element at a time for clean data. diff --git a/templates/skills-marketplace/ads/references/audience-targeting.md b/templates/skills-marketplace/ads/references/audience-targeting.md new file mode 100644 index 00000000..00dc42bb --- /dev/null +++ b/templates/skills-marketplace/ads/references/audience-targeting.md @@ -0,0 +1,243 @@ +# Audience Targeting Reference + +Detailed targeting strategies for each major ad platform. + +## Contents +- Google Ads Audiences (Search Campaign Targeting, Display/YouTube Targeting) +- Meta Audiences (Core Audiences, Custom Audiences, Lookalike Audiences) +- LinkedIn Audiences (Job-Based Targeting, Company-Based Targeting, High-Performing Combinations) +- Twitter/X Audiences +- TikTok Audiences +- Audience Size Guidelines +- Exclusion Strategy + +## Google Ads Audiences + +### Search Campaign Targeting + +**Keywords:** +- Exact match: [keyword] — most precise, lower volume +- Phrase match: "keyword" — moderate precision and volume +- Broad match: keyword — highest volume, use with smart bidding + +**Audience layering:** +- Add audiences in "observation" mode first +- Analyze performance by audience +- Switch to "targeting" mode for high performers + +**RLSA (Remarketing Lists for Search Ads):** +- Bid higher on past visitors searching your terms +- Show different ads to returning searchers +- Exclude converters from prospecting campaigns + +### Display/YouTube Targeting + +**Custom intent audiences:** +- Based on recent search behavior +- Create from your converting keywords +- High intent, good for prospecting + +**In-market audiences:** +- People actively researching solutions +- Pre-built by Google +- Layer with demographics for precision + +**Affinity audiences:** +- Based on interests and habits +- Better for awareness +- Broad but can exclude irrelevant + +**Customer match:** +- Upload email lists +- Retarget existing customers +- Create lookalikes from best customers + +**Similar/lookalike audiences:** +- Based on your customer match lists +- Expand reach while maintaining relevance +- Best when source list is high-quality customers + +--- + +## Meta Audiences + +### Core Audiences (Interest/Demographic) + +**Interest targeting tips:** +- Layer interests with AND logic for precision +- Use Audience Insights to research interests +- Start broad, let algorithm optimize +- Exclude existing customers always + +**Demographic targeting:** +- Age and gender (if product-specific) +- Location (down to zip/postal code) +- Language +- Education and work (limited data now) + +**Behavior targeting:** +- Purchase behavior +- Device usage +- Travel patterns +- Life events + +### Custom Audiences + +**Website visitors:** +- All visitors (last 180 days max) +- Specific page visitors +- Time on site thresholds +- Frequency (visited X times) + +**Customer list:** +- Upload emails/phone numbers +- Match rate typically 30-70% +- Refresh regularly for accuracy + +**Engagement audiences:** +- Video viewers (25%, 50%, 75%, 95%) +- Page/profile engagers +- Form openers +- Instagram engagers + +**App activity:** +- App installers +- In-app events +- Purchase events + +### Lookalike Audiences + +**Source audience quality matters:** +- Use high-LTV customers, not all customers +- Purchasers > leads > all visitors +- Minimum 100 source users, ideally 1,000+ + +**Size recommendations:** +- 1% — most similar, smallest reach +- 1-3% — good balance for most +- 3-5% — broader, good for scale +- 5-10% — very broad, awareness only + +**Layering strategies:** +- Lookalike + interest = more precision early +- Test lookalike-only as you scale +- Exclude the source audience + +--- + +## LinkedIn Audiences + +### Job-Based Targeting + +**Job titles:** +- Be specific (CMO vs. "Marketing") +- LinkedIn normalizes titles, but verify +- Stack related titles +- Exclude irrelevant titles + +**Job functions:** +- Broader than titles +- Combine with seniority level +- Good for awareness campaigns + +**Seniority levels:** +- Entry, Senior, Manager, Director, VP, CXO, Partner +- Layer with function for precision + +**Skills:** +- Self-reported, less reliable +- Good for technical roles +- Use as expansion layer + +### Company-Based Targeting + +**Company size:** +- 1-10, 11-50, 51-200, 201-500, 501-1000, 1001-5000, 5000+ +- Key filter for B2B + +**Industry:** +- Based on company classification +- Can be broad, layer with other criteria + +**Company names (ABM):** +- Upload target account list +- Minimum 300 companies recommended +- Match rate varies + +**Company growth rate:** +- Hiring rapidly = budget available +- Good signal for timing + +### High-Performing Combinations + +| Use Case | Targeting Combination | +|----------|----------------------| +| Enterprise sales | Company size 1000+ + VP/CXO + Industry | +| SMB sales | Company size 11-200 + Manager/Director + Function | +| Developer tools | Skills + Job function + Company type | +| ABM campaigns | Company list + Decision-maker titles | +| Broad awareness | Industry + Seniority + Geography | + +--- + +## Twitter/X Audiences + +### Targeting options: +- Follower lookalikes (accounts similar to followers of X) +- Interest categories +- Keywords (in tweets) +- Conversation topics +- Events +- Tailored audiences (your lists) + +### Best practices: +- Follower lookalikes of relevant accounts work well +- Keyword targeting catches active conversations +- Lower CPMs than LinkedIn/Meta +- Less precise, better for awareness + +--- + +## TikTok Audiences + +### Targeting options: +- Demographics (age, gender, location) +- Interests (TikTok's categories) +- Behaviors (video interactions) +- Device (iOS/Android, connection type) +- Custom audiences (pixel, customer file) +- Lookalike audiences + +### Best practices: +- Younger skew (18-34 primarily) +- Interest targeting is broad +- Creative matters more than targeting +- Let algorithm optimize with broad targeting + +--- + +## Audience Size Guidelines + +| Platform | Minimum Recommended | Ideal Range | +|----------|-------------------|-------------| +| Google Search | 1,000+ searches/mo | 5,000-50,000 | +| Google Display | 100,000+ | 500K-5M | +| Meta | 100,000+ | 500K-10M | +| LinkedIn | 50,000+ | 100K-500K | +| Twitter/X | 50,000+ | 100K-1M | +| TikTok | 100,000+ | 1M+ | + +Too narrow = expensive, slow learning +Too broad = wasted spend, poor relevance + +--- + +## Exclusion Strategy + +Always exclude: +- Existing customers (unless upsell) +- Recent converters (7-14 days) +- Bounced visitors (<10 sec) +- Employees (by company or email list) +- Irrelevant page visitors (careers, support) +- Competitors (if identifiable) diff --git a/templates/skills-marketplace/ads/references/conversion-tracking.md b/templates/skills-marketplace/ads/references/conversion-tracking.md new file mode 100644 index 00000000..1817f469 --- /dev/null +++ b/templates/skills-marketplace/ads/references/conversion-tracking.md @@ -0,0 +1,361 @@ +# Conversion Tracking Setup + +How to set up conversion tracking pixels across ad platforms. This guide covers installation, event configuration, and validation — everything a marketer needs to ensure ad spend is properly attributed. + +--- + +## Why This Matters + +Without conversion tracking: +- Ad platforms can't optimize for your actual goals +- You're flying blind on ROAS and CPA +- Retargeting audiences can't be built +- You'll waste budget on impressions that don't convert + +Get tracking right before spending a dollar on ads. + +--- + +## Platform Pixels Overview + +| Platform | Pixel/Tag Name | Events API | Key Events | +|----------|---------------|:----------:|------------| +| **Google Ads** | Google tag (gtag.js) | Enhanced Conversions | purchase, sign_up, generate_lead | +| **Meta** | Meta Pixel + CAPI | Conversions API | Purchase, Lead, ViewContent, AddToCart | +| **LinkedIn** | Insight Tag | Conversions API | conversion (URL or event-based) | +| **TikTok** | TikTok Pixel | Events API | Purchase, ViewContent, AddToCart, CompleteRegistration | +| **Twitter/X** | Twitter Pixel | - | Purchase, SignUp, Download | + +--- + +## Google Ads + +### Install the Google tag + +Add to every page, in ``: + +```html + + +``` + +Replace `AW-XXXXXXXXX` with your Conversion ID from Google Ads > Tools > Conversions. + +### Set up conversion actions + +In Google Ads > Goals > Conversions > New conversion action: + +| Conversion | Category | Value | Count | +|-----------|----------|-------|-------| +| Purchase | Purchase | Dynamic (order value) | Every | +| Sign up / Lead | Sign-up | Fixed ($X estimated value) | One | +| Demo request | Lead | Fixed ($X estimated value) | One | +| Free trial start | Sign-up | Fixed ($X estimated value) | One | + +### Fire conversion events + +```javascript +// Purchase +gtag('event', 'conversion', { + 'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL', + 'value': 99.00, + 'currency': 'USD', + 'transaction_id': 'ORDER-123' +}); + +// Lead / Sign up +gtag('event', 'conversion', { + 'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL', + 'value': 50.00, + 'currency': 'USD' +}); +``` + +### Enhanced Conversions + +Sends hashed first-party data (email, phone) to improve attribution after cookie restrictions. Enable in Google Ads > Goals > Settings > Enhanced conversions. + +```javascript +gtag('set', 'user_data', { + 'email': 'user@example.com', // auto-hashed by gtag + 'phone_number': '+11234567890' +}); +``` + +### Google Tag Manager alternative + +If using GTM instead of inline gtag.js: +1. Install GTM container on all pages +2. Create Google Ads conversion tags in GTM +3. Set triggers for conversion events (form submissions, purchases) +4. Use the Data Layer to pass dynamic values (order amount, transaction ID) +5. Test with GTM Preview mode before publishing + +--- + +## Meta (Facebook/Instagram) + +### Install the Meta Pixel + +Add to every page, in ``: + +```html + +``` + +Replace `YOUR_PIXEL_ID` from Meta Events Manager. + +### Standard events + +```javascript +// View a product or key page +fbq('track', 'ViewContent', { + content_name: 'Pro Plan', + content_category: 'Pricing', + value: 29.00, + currency: 'USD' +}); + +// Lead capture (form submit, demo request) +fbq('track', 'Lead', { + content_name: 'Demo Request', + value: 50.00, + currency: 'USD' +}); + +// Purchase +fbq('track', 'Purchase', { + value: 99.00, + currency: 'USD', + content_type: 'product', + contents: [{ id: 'pro-plan', quantity: 1 }] +}); + +// Add to cart (e-commerce) +fbq('track', 'AddToCart', { + content_ids: ['SKU-123'], + content_type: 'product', + value: 49.00, + currency: 'USD' +}); +``` + +### Conversions API (CAPI) + +Server-side tracking that works alongside the pixel. Required for accurate tracking after iOS 14+ and cookie restrictions. + +Set up via: +- **Direct integration** — send events from your server to Meta's API +- **Partner integrations** — Shopify, WooCommerce, Segment, etc. have built-in CAPI support +- **Conversions API Gateway** — Meta's managed solution via AWS + +Key: send the same events from both pixel (browser) AND CAPI (server), with a shared `event_id` for deduplication. + +### Aggregated Event Measurement + +Required for iOS 14+ tracking. In Events Manager > Aggregated Event Measurement: +1. Verify your domain +2. Configure and prioritize your top 8 events in order of business importance +3. Purchase should typically be #1, Lead #2 + +--- + +## LinkedIn + +### Install the Insight Tag + +Add to every page, before ``: + +```html + +``` + +### Conversion tracking + +LinkedIn supports two methods: + +**URL-based**: Fires when someone visits a specific URL (e.g., `/thank-you`). +Set up in Campaign Manager > Analyze > Conversion Tracking > Create Conversion. + +**Event-based**: Fire manually on specific actions: + +```javascript +window.lintrk('track', { conversion_id: YOUR_CONVERSION_ID }); +``` + +### LinkedIn CAPI + +For server-side tracking, LinkedIn offers a Conversions API. Set up via partner integrations (Segment, Tealium) or direct API calls. Deduplicates with the Insight Tag automatically when configured correctly. + +--- + +## TikTok + +### Install the TikTok Pixel + +Add to every page, in ``: + +```html + +``` + +### Standard events + +```javascript +// View content +ttq.track('ViewContent', { + content_id: 'pro-plan', + content_type: 'product', + content_name: 'Pro Plan', + value: 29.00, + currency: 'USD' +}); + +// Complete registration / sign up +ttq.track('CompleteRegistration', { + content_name: 'Free Trial' +}); + +// Purchase +ttq.track('Purchase', { + content_id: 'pro-plan', + content_type: 'product', + value: 99.00, + currency: 'USD', + quantity: 1 +}); + +// Add to cart +ttq.track('AddToCart', { + content_id: 'SKU-123', + content_type: 'product', + value: 49.00, + currency: 'USD' +}); +``` + +### Events API (server-side) + +TikTok's Events API works like Meta's CAPI — send the same events from your server for better attribution. Use `event_id` for deduplication with browser pixel events. + +### Advanced Matching + +Pass hashed user data for better attribution: + +```javascript +ttq.identify({ + email: 'user@example.com', // auto-hashed + phone_number: '+11234567890' +}); +``` + +--- + +## Validation Checklist + +After installing any pixel, verify before going live: + +### Browser-side checks + +- [ ] Pixel fires on every page (check via browser extension) +- [ ] Conversion events fire at the right moment (after confirmed action, not on button click) +- [ ] Event parameters contain correct values (currency, amount, content IDs) +- [ ] No duplicate events firing on the same action +- [ ] Events fire on both desktop and mobile + +### Platform-side checks + +- [ ] Events appear in the platform's event manager/diagnostics +- [ ] Test conversions show correct values +- [ ] Event match quality is acceptable (Meta: score > 6) +- [ ] Server-side events are deduplicating with browser events (not double-counting) + +### Debugging tools + +| Platform | Tool | +|----------|------| +| Google | Google Tag Assistant, Chrome DevTools Network tab | +| Meta | Meta Pixel Helper (Chrome extension), Events Manager Test Events | +| LinkedIn | Insight Tag Validator in Campaign Manager | +| TikTok | TikTok Pixel Helper (Chrome extension), Events Manager | +| All | GTM Preview Mode (if using Google Tag Manager) | + +--- + +## Common Mistakes + +- **Firing purchase events on button click instead of confirmed payment** — always fire on the success/thank-you page or after server confirmation +- **Missing deduplication between pixel and server events** — without a shared `event_id`, you'll double-count conversions +- **Not testing on mobile** — many pixels break on mobile browsers or in-app webviews +- **Hardcoded test values** — remove test transaction amounts before going live +- **Forgetting to exclude internal traffic** — your team's visits inflate conversion data +- **Installing pixels without consent management** — GDPR/CCPA require user consent before firing tracking pixels in applicable regions +- **Pixel installed but no conversion actions created** — the pixel collects data, but the ad platform won't optimize without defined conversion actions + +--- + +## When to Use Server-Side Tracking + +Browser-only tracking is increasingly unreliable due to: +- iOS 14+ App Tracking Transparency +- Third-party cookie deprecation +- Ad blockers (30%+ of tech audiences) + +**Use server-side (CAPI/Events API) when:** +- Running Meta or TikTok ads (strongly recommended) +- Your audience is tech-savvy (higher ad blocker usage) +- You need accurate purchase/revenue attribution +- You're spending >$5K/month on any platform + +**Server-side is optional when:** +- Running Google Ads only (Enhanced Conversions covers most gaps) +- Low ad spend / testing phase +- B2B with LinkedIn only (Insight Tag is still reliable) diff --git a/templates/skills-marketplace/ads/references/platform-setup-checklists.md b/templates/skills-marketplace/ads/references/platform-setup-checklists.md new file mode 100644 index 00000000..5e663a5e --- /dev/null +++ b/templates/skills-marketplace/ads/references/platform-setup-checklists.md @@ -0,0 +1,277 @@ +# Platform Setup Checklists + +Complete setup checklists for major ad platforms. + +## Contents +- Google Ads Setup (Account Foundation, Conversion Tracking, Analytics Integration, Audience Setup, Campaign Readiness, Ad Extensions, Brand Protection) +- Meta Ads Setup (Business Manager Foundation, Pixel & Tracking, Domain & Aggregated Events, Audience Setup, Catalog, Creative Assets, Compliance) +- LinkedIn Ads Setup (Campaign Manager Foundation, Insight Tag & Tracking, Audience Setup, Lead Gen Forms, Document Ads, Creative Assets, Budget Considerations) +- Twitter/X Ads Setup (Account Foundation, Tracking, Audience Setup, Creative) +- TikTok Ads Setup (Account Foundation, Pixel & Tracking, Audience Setup, Creative) +- Universal Pre-Launch Checklist + +## Google Ads Setup + +### Account Foundation + +- [ ] Google Ads account created and verified +- [ ] Billing information added +- [ ] Time zone and currency set correctly +- [ ] Account access granted to team members + +### Conversion Tracking + +- [ ] Google tag installed on all pages +- [ ] Conversion actions created (purchase, lead, signup) +- [ ] Conversion values assigned (if applicable) +- [ ] Enhanced conversions enabled +- [ ] Test conversions firing correctly +- [ ] Import conversions from GA4 (optional) + +### Analytics Integration + +- [ ] Google Analytics 4 linked +- [ ] Auto-tagging enabled +- [ ] GA4 audiences available in Google Ads +- [ ] Cross-domain tracking set up (if multiple domains) + +### Audience Setup + +- [ ] Remarketing tag verified +- [ ] Website visitor audiences created: + - All visitors (180 days) + - Key page visitors (pricing, demo, features) + - Converters (for exclusion) +- [ ] Customer match lists uploaded +- [ ] Similar audiences enabled + +### Campaign Readiness + +- [ ] Negative keyword lists created: + - Universal negatives (free, jobs, careers, reviews, complaints) + - Competitor negatives (if needed) + - Irrelevant industry terms +- [ ] Location targeting set (include/exclude) +- [ ] Language targeting set +- [ ] Ad schedule configured (if B2B, business hours) +- [ ] Device bid adjustments considered + +### Ad Extensions + +- [ ] Sitelinks (4-6 relevant pages) +- [ ] Callouts (key benefits, offers) +- [ ] Structured snippets (features, types, services) +- [ ] Call extension (if phone leads valuable) +- [ ] Lead form extension (if using) +- [ ] Price extensions (if applicable) +- [ ] Image extensions (where available) + +### Brand Protection + +- [ ] Brand campaign running (protect branded terms) +- [ ] Competitor campaigns considered +- [ ] Brand terms in negative lists for non-brand campaigns + +--- + +## Meta Ads Setup + +### Business Manager Foundation + +- [ ] Business Manager created +- [ ] Business verified (if running certain ad types) +- [ ] Ad account created within Business Manager +- [ ] Payment method added +- [ ] Team access configured with proper roles + +### Pixel & Tracking + +- [ ] Meta Pixel installed on all pages +- [ ] Standard events configured: + - PageView (automatic) + - ViewContent (product/feature pages) + - Lead (form submissions) + - Purchase (conversions) + - AddToCart (if e-commerce) + - InitiateCheckout (if e-commerce) +- [ ] Conversions API (CAPI) set up for server-side tracking +- [ ] Event Match Quality score > 6 +- [ ] Test events in Events Manager + +### Domain & Aggregated Events + +- [ ] Domain verified in Business Manager +- [ ] Aggregated Event Measurement configured +- [ ] Top 8 events prioritized in order of importance +- [ ] Web events prioritized for iOS 14+ tracking + +### Audience Setup + +- [ ] Custom audiences created: + - Website visitors (all, 30/60/90/180 days) + - Key page visitors + - Video viewers (25%, 50%, 75%, 95%) + - Page/Instagram engagers + - Customer list uploaded +- [ ] Lookalike audiences created (1%, 1-3%) +- [ ] Saved audiences for common targeting + +### Catalog (E-commerce) + +- [ ] Product catalog connected +- [ ] Product feed updating correctly +- [ ] Catalog sales campaigns enabled +- [ ] Dynamic product ads configured + +### Creative Assets + +- [ ] Images in correct sizes: + - Feed: 1080x1080 (1:1) + - Stories/Reels: 1080x1920 (9:16) + - Landscape: 1200x628 (1.91:1) +- [ ] Videos in correct formats +- [ ] Ad copy variations ready +- [ ] UTM parameters in all destination URLs + +### Compliance + +- [ ] Special Ad Categories declared (if housing, credit, employment, politics) +- [ ] Landing page complies with Meta policies +- [ ] No prohibited content in ads + +--- + +## LinkedIn Ads Setup + +### Campaign Manager Foundation + +- [ ] Campaign Manager account created +- [ ] Company Page connected +- [ ] Billing information added +- [ ] Team access configured + +### Insight Tag & Tracking + +- [ ] LinkedIn Insight Tag installed on all pages +- [ ] Tag verified and firing +- [ ] Conversion tracking configured: + - URL-based conversions + - Event-specific conversions +- [ ] Conversion values set (if applicable) + +### Audience Setup + +- [ ] Matched Audiences created: + - Website retargeting audiences + - Company list uploaded (for ABM) + - Contact list uploaded +- [ ] Lookalike audiences created +- [ ] Saved audiences for common targeting + +### Lead Gen Forms (if using) + +- [ ] Lead gen form templates created +- [ ] Form fields selected (minimize for conversion) +- [ ] Privacy policy URL added +- [ ] Thank you message configured +- [ ] CRM integration set up (or CSV export process) + +### Document Ads (if using) + +- [ ] Documents uploaded (PDF, PowerPoint) +- [ ] Gating configured (full gate or preview) +- [ ] Lead gen form connected + +### Creative Assets + +- [ ] Single image ads: 1200x627 (1.91:1) or 1080x1080 (1:1) +- [ ] Carousel images ready +- [ ] Video specs met (if using) +- [ ] Ad copy within character limits: + - Intro text: 600 max, 150 recommended + - Headline: 200 max, 70 recommended + +### Budget Considerations + +- [ ] Budget realistic for LinkedIn CPCs ($8-15+ typical) +- [ ] Audience size validated (50K+ recommended) +- [ ] Daily vs. lifetime budget decided +- [ ] Bid strategy selected + +--- + +## Twitter/X Ads Setup + +### Account Foundation + +- [ ] Ads account created +- [ ] Payment method added +- [ ] Account verified (if required) + +### Tracking + +- [ ] Twitter Pixel installed +- [ ] Conversion events created +- [ ] Website tag verified + +### Audience Setup + +- [ ] Tailored audiences created: + - Website visitors + - Customer lists +- [ ] Follower lookalikes identified +- [ ] Interest and keyword targets researched + +### Creative + +- [ ] Tweet copy within 280 characters +- [ ] Images: 1200x675 (1.91:1) or 1200x1200 (1:1) +- [ ] Video specs met (if using) +- [ ] Cards configured (website, app, etc.) + +--- + +## TikTok Ads Setup + +### Account Foundation + +- [ ] TikTok Ads Manager account created +- [ ] Business verification completed +- [ ] Payment method added + +### Pixel & Tracking + +- [ ] TikTok Pixel installed +- [ ] Events configured (ViewContent, Purchase, etc.) +- [ ] Events API set up (recommended) + +### Audience Setup + +- [ ] Custom audiences created +- [ ] Lookalike audiences created +- [ ] Interest categories identified + +### Creative + +- [ ] Vertical video (9:16) ready +- [ ] Native-feeling content (not too polished) +- [ ] First 3 seconds are compelling hooks +- [ ] Captions added (most watch without sound) +- [ ] Music/sounds selected (licensed if needed) + +--- + +## Universal Pre-Launch Checklist + +Before launching any campaign: + +- [ ] Conversion tracking tested with real conversion +- [ ] Landing page loads fast (<3 sec) +- [ ] Landing page mobile-friendly +- [ ] UTM parameters working +- [ ] Budget set correctly (daily vs. lifetime) +- [ ] Start/end dates correct +- [ ] Targeting matches intended audience +- [ ] Ad creative approved +- [ ] Team notified of launch +- [ ] Reporting dashboard ready diff --git a/templates/skills-marketplace/ai-seo/SKILL.md b/templates/skills-marketplace/ai-seo/SKILL.md new file mode 100644 index 00000000..320a51c8 --- /dev/null +++ b/templates/skills-marketplace/ai-seo/SKILL.md @@ -0,0 +1,485 @@ +--- +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,' '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: 2.0.1 +--- + +# AI SEO + +You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers. + +## Before Starting + +**Check for product marketing context first:** +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): + +### 1. Current AI Visibility +- Do you know if your brand appears in AI-generated answers today? +- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries? +- What queries matter most to your business? + +### 2. Content & Domain +- What type of content do you produce? (Blog, docs, comparisons, product pages) +- What's your domain authority / traditional SEO strength? +- Do you have existing structured data (schema markup)? + +### 3. Goals +- Get cited as a source in AI answers? +- Appear in Google AI Overviews for specific queries? +- Compete with specific brands already getting cited? +- Optimize existing content or create new AI-optimized content? + +### 4. Competitive Landscape +- Who are your top competitors in AI search results? +- Are they being cited where you're not? + +--- + +## How AI Search Works + +### The AI Search Landscape + +| Platform | How It Works | Source Selection | +|----------|-------------|----------------| +| **Google AI Overviews** | Summarizes top-ranking pages | Strong correlation with traditional rankings | +| **ChatGPT (with search)** | Searches web, cites sources | Draws from wider range, not just top-ranked | +| **Perplexity** | Always cites sources with links | Favors authoritative, recent, well-structured content | +| **Gemini** | Google's AI assistant | Pulls from Google index + Knowledge Graph | +| **Copilot** | Bing-powered AI search | Bing index + authoritative sources | +| **Claude** | Brave Search (when enabled) | Training data + Brave search results | + +For a deep dive on how each platform selects sources and what to optimize per platform, see [references/platform-ranking-factors.md](references/platform-ranking-factors.md). + +### Key Difference from Traditional SEO + +Traditional SEO gets you ranked. AI SEO gets you **cited**. + +In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position. + +**Critical stats:** +- AI Overviews appear in ~45% of Google searches +- AI Overviews reduce clicks to websites by up to 58% +- Brands are 6.5x more likely to be cited via third-party sources than their own domains +- 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 + +Before optimizing, assess your current AI search presence. + +### Step 1: Check AI Answers for Your Key Queries + +Test 10-20 of your most important queries across platforms: + +| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? | +|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:| +| [query 1] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | +| [query 2] | Yes/No | Yes/No | Yes/No | Yes/No | [who] | + +**Query types to test:** +- "What is [your product category]?" +- "Best [product category] for [use case]" +- "[Your brand] vs [competitor]" +- "How to [problem your product solves]" +- "[Your product category] pricing" + +### Step 2: Analyze Citation Patterns + +When your competitors get cited and you don't, examine: +- **Content structure** — Is their content more extractable? +- **Authority signals** — Do they have more citations, stats, expert quotes? +- **Freshness** — Is their content more recently updated? +- **Schema markup** — Do they have structured data you're missing? +- **Third-party presence** — Are they cited via Wikipedia, Reddit, review sites? + +### Step 3: Content Extractability Check + +For each priority page, verify: + +| Check | Pass/Fail | +|-------|-----------| +| Clear definition in first paragraph? | | +| Self-contained answer blocks (work without surrounding context)? | | +| Statistics with sources cited? | | +| Comparison tables for "[X] vs [Y]" queries? | | +| FAQ section with natural-language questions? | | +| Schema markup (FAQ, HowTo, Article, Product)? | | +| Expert attribution (author name, credentials)? | | +| Recently updated (within 6 months)? | | +| Heading structure matches query patterns? | | +| AI bots allowed in robots.txt? | | + +### Step 4: AI Bot Access Check + +Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and blocking it means that platform can't cite you: + +- **GPTBot** and **ChatGPT-User** — OpenAI (ChatGPT) +- **PerplexityBot** — Perplexity +- **ClaudeBot** and **anthropic-ai** — Anthropic (Claude) +- **Google-Extended** — Google Gemini and AI Overviews +- **Bingbot** — Microsoft Copilot (via Bing) + +Check your robots.txt for `Disallow` rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers (like **CCBot** from Common Crawl) while allowing the search bots listed above. + +See [references/platform-ranking-factors.md](references/platform-ranking-factors.md) for the full robots.txt configuration. + +--- + +## Optimization Strategy + +### The Three Pillars + +``` +1. Structure (make it extractable) +2. Authority (make it citable) +3. Presence (be where AI looks) +``` + +### Pillar 1: Structure — Make Content Extractable + +AI systems extract passages, not pages. Every key claim should work as a standalone statement. + +**Content block patterns:** +- **Definition blocks** for "What is X?" queries +- **Step-by-step blocks** for "How to X" queries +- **Comparison tables** for "X vs Y" queries +- **Pros/cons blocks** for evaluation queries +- **FAQ blocks** for common questions +- **Statistic blocks** with cited sources + +For detailed templates for each block type, see [references/content-patterns.md](references/content-patterns.md). + +**Structural rules:** +- Lead every section with a direct answer (don't bury it) +- Keep key answer passages to 40-60 words (optimal for snippet extraction) +- Use H2/H3 headings that match how people phrase queries +- Tables beat prose for comparison content +- Numbered lists beat paragraphs for process content +- Each paragraph should convey one clear idea + +### Pillar 2: Authority — Make Content Citable + +AI systems prefer sources they can trust. Build citation-worthiness. + +**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods: + +| Method | Visibility Boost | How to Apply | +|--------|:---------------:|--------------| +| **Cite sources** | +40% | Add authoritative references with links | +| **Add statistics** | +37% | Include specific numbers with sources | +| **Add quotations** | +30% | Expert quotes with name and title | +| **Authoritative tone** | +25% | Write with demonstrated expertise | +| **Improve clarity** | +20% | Simplify complex concepts | +| **Technical terms** | +18% | Use domain-specific terminology | +| **Unique vocabulary** | +15% | Increase word diversity | +| **Fluency optimization** | +15-30% | Improve readability and flow | +| ~~Keyword stuffing~~ | **-10%** | **Actively hurts AI visibility** | + +**Best combination:** Fluency + Statistics = maximum boost. Low-ranking sites benefit even more — up to 115% visibility increase with citations. + +**Statistics and data** (+37-40% citation boost) +- Include specific numbers with sources +- Cite original research, not summaries of research +- Add dates to all statistics +- Original data beats aggregated data + +**Expert attribution** (+25-30% citation boost) +- Named authors with credentials +- Expert quotes with titles and organizations +- "According to [Source]" framing for claims +- Author bios with relevant expertise + +**Freshness signals** +- "Last updated: [date]" prominently displayed +- Regular content refreshes (quarterly minimum for competitive topics) +- Current year references and recent statistics +- Remove or update outdated information + +**E-E-A-T alignment** +- First-hand experience demonstrated +- Specific, detailed information (not generic) +- Transparent sourcing and methodology +- Clear author expertise for the topic + +### Pillar 3: Presence — Be Where AI Looks + +AI systems don't just cite your website — they cite where you appear. + +**Third-party sources matter more than your own site:** +- Wikipedia mentions (7.8% of all ChatGPT citations) +- Reddit discussions (1.8% of ChatGPT citations) +- Industry publications and guest posts +- Review sites (G2, Capterra, TrustRadius for B2B SaaS) +- YouTube (frequently cited by Google AI Overviews) +- Quora answers + +**Actions:** +- Ensure your Wikipedia page is accurate and current +- Participate authentically in Reddit communities +- Get featured in industry roundups and comparison articles +- Maintain updated profiles on relevant review platforms +- 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: + +| Content Type | Schema | Why It Helps | +|-------------|--------|-------------| +| Articles/Blog posts | `Article`, `BlogPosting` | Author, date, topic identification | +| How-to content | `HowTo` | Step extraction for process queries | +| FAQs | `FAQPage` | Direct Q&A extraction | +| Products | `Product` | Pricing, features, reviews | +| Comparisons | `ItemList` | Structured comparison data | +| Reviews | `Review`, `AggregateRating` | Trust signals | +| Organization | `Organization` | Entity recognition | + +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 `
`, `