Dev (#269)
* docs: restructure README.md — 2,539 → 209 lines (#247) - Cut from 2,539 lines / 73 sections to 209 lines / 18 sections - Consolidated 4 install methods into one unified section - Moved all skill details to domain-level READMEs (linked from table) - Front-loaded value prop and keywords for SEO - Added POWERFUL tier highlight section - Added skill-security-auditor showcase section - Removed stale Q4 2025 roadmap, outdated ROI claims, duplicate content - Fixed all internal links - Clean heading hierarchy (H2 for main sections only) Closes #233 Co-authored-by: Leo <leo@openclaw.ai> * fix: enhance 5 skills with scripts, references, and Anthropic best practices (#248) * fix(skill): enhance git-worktree-manager with scripts, references, and Anthropic best practices * fix(skill): enhance mcp-server-builder with scripts, references, and Anthropic best practices * fix(skill): enhance changelog-generator with scripts, references, and Anthropic best practices * fix(skill): enhance ci-cd-pipeline-builder with scripts, references, and Anthropic best practices * fix(skill): enhance prompt-engineer-toolkit with scripts, references, and Anthropic best practices * docs: update README, CHANGELOG, and plugin metadata * fix: correct marketing plugin count, expand thin references --------- Co-authored-by: Leo <leo@openclaw.ai> * ci: Add VirusTotal security scan for skills (#252) * Dev (#231) * Improve senior-fullstack skill description and workflow validation - Expand frontmatter description with concrete actions and trigger clauses - Add validation steps to scaffolding workflow (verify scaffold succeeded) - Add re-run verification step to audit workflow (confirm P0 fixes) * chore: sync codex skills symlinks [automated] * fix(skill): normalize senior-fullstack frontmatter to inline format Normalize YAML description from block scalar (>) to inline single-line format matching all other 50+ skills. Align frontmatter trigger phrases with the body's Trigger Phrases section to eliminate duplication. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(ci): add GITHUB_TOKEN to checkout + restore corrupted skill descriptions - Add token: ${{ secrets.GITHUB_TOKEN }} to actions/checkout@v4 in sync-codex-skills.yml so git-auto-commit-action can push back to branch (fixes: fatal: could not read Username, exit 128) - Restore correct description for incident-commander (was: 'Skill from engineering-team') - Restore correct description for senior-fullstack (was: '>') * fix(ci): pass PROJECTS_TOKEN to fix automated commits + remove duplicate checkout Fixes PROJECTS_TOKEN passthrough for git-auto-commit-action and removes duplicate checkout step in pr-issue-auto-close workflow. * fix(ci): remove stray merge conflict marker in sync-codex-skills.yml (#221) Co-authored-by: Leo <leo@leo-agent-server> * fix(ci): fix workflow errors + add OpenClaw support (#222) * feat: add 20 new practical skills for professional Claude Code users New skills across 5 categories: Engineering (12): - git-worktree-manager: Parallel dev with port isolation & env sync - ci-cd-pipeline-builder: Generate GitHub Actions/GitLab CI from stack analysis - mcp-server-builder: Build MCP servers from OpenAPI specs - changelog-generator: Conventional commits to structured changelogs - pr-review-expert: Blast radius analysis & security scan for PRs - api-test-suite-builder: Auto-generate test suites from API routes - env-secrets-manager: .env management, leak detection, rotation workflows - database-schema-designer: Requirements to migrations & types - codebase-onboarding: Auto-generate onboarding docs from codebase - performance-profiler: Node/Python/Go profiling & optimization - runbook-generator: Operational runbooks from codebase analysis - monorepo-navigator: Turborepo/Nx/pnpm workspace management Engineering Team (2): - stripe-integration-expert: Subscriptions, webhooks, billing patterns - email-template-builder: React Email/MJML transactional email systems Product Team (3): - saas-scaffolder: Full SaaS project generation from product brief - landing-page-generator: High-converting landing pages with copy frameworks - competitive-teardown: Structured competitive product analysis Business Growth (1): - contract-and-proposal-writer: Contracts, SOWs, NDAs per jurisdiction Marketing (1): - prompt-engineer-toolkit: Systematic prompt development & A/B testing Designed for daily professional use and commercial distribution. * chore: sync codex skills symlinks [automated] * docs: update README with 20 new skills, counts 65→86, new skills section * docs: add commercial distribution plan (Stan Store + Gumroad) * docs: rewrite CHANGELOG.md with v2.0.0 release (65 skills, 9 domains) (#226) * docs: rewrite CHANGELOG.md with v2.0.0 release (65 skills, 9 domains) - Consolidate 191 commits since v1.0.2 into proper v2.0.0 entry - Document 12 POWERFUL-tier skills, 37 refactored skills - Add new domains: business-growth, finance - Document Codex support and marketplace integration - Update version history summary table - Clean up [Unreleased] to only planned work * docs: add 24 POWERFUL-tier skills to plugin, fix counts to 85 across all docs - Add engineering-advanced-skills plugin (24 POWERFUL-tier skills) to marketplace.json - Add 13 missing skills to CHANGELOG v2.0.0 (agent-workflow-designer, api-test-suite-builder, changelog-generator, ci-cd-pipeline-builder, codebase-onboarding, database-schema-designer, env-secrets-manager, git-worktree-manager, mcp-server-builder, monorepo-navigator, performance-profiler, pr-review-expert, runbook-generator) - Fix skill count: 86→85 (excl sample-skill) across README, CHANGELOG, marketplace.json - Fix stale 53→85 references in README - Add engineering-advanced-skills install command to README - Update marketplace.json version to 2.0.0 --------- Co-authored-by: Leo <leo@openclaw.ai> * feat: add skill-security-auditor POWERFUL-tier skill (#230) Security audit and vulnerability scanner for AI agent skills before installation. Scans for: - Code execution risks (eval, exec, os.system, subprocess shell injection) - Data exfiltration (outbound HTTP, credential harvesting, env var extraction) - Prompt injection in SKILL.md (system override, role hijack, safety bypass) - Dependency supply chain (typosquatting, unpinned versions, runtime installs) - File system abuse (boundary violations, binaries, symlinks, hidden files) - Privilege escalation (sudo, SUID, cron manipulation, shell config writes) - Obfuscation (base64, hex encoding, chr chains, codecs) Produces clear PASS/WARN/FAIL verdict with per-finding remediation guidance. Supports local dirs, git repo URLs, JSON output, strict mode, and CI/CD integration. Includes: - scripts/skill_security_auditor.py (1049 lines, zero dependencies) - references/threat-model.md (complete attack vector documentation) - SKILL.md with usage guide and report format Tested against: rag-architect (PASS), agent-designer (PASS), senior-secops (FAIL - correctly flagged eval/exec patterns). Co-authored-by: Leo <leo@openclaw.ai> * docs: add skill-security-auditor to marketplace, README, and CHANGELOG - Add standalone plugin entry for skill-security-auditor in marketplace.json - Update engineering-advanced-skills plugin description to include it - Update skill counts: 85→86 across README, CHANGELOG, marketplace - Add install command to README Quick Install section - Add to CHANGELOG [Unreleased] section --------- Co-authored-by: Baptiste Fernandez <fernandez.baptiste1@gmail.com> Co-authored-by: alirezarezvani <5697919+alirezarezvani@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Leo <leo@leo-agent-server> Co-authored-by: Leo <leo@openclaw.ai> * Dev (#249) * docs: restructure README.md — 2,539 → 209 lines (#247) - Cut from 2,539 lines / 73 sections to 209 lines / 18 sections - Consolidated 4 install methods into one unified section - Moved all skill details to domain-level READMEs (linked from table) - Front-loaded value prop and keywords for SEO - Added POWERFUL tier highlight section - Added skill-security-auditor showcase section - Removed stale Q4 2025 roadmap, outdated ROI claims, duplicate content - Fixed all internal links - Clean heading hierarchy (H2 for main sections only) Closes #233 Co-authored-by: Leo <leo@openclaw.ai> * fix: enhance 5 skills with scripts, references, and Anthropic best practices (#248) * fix(skill): enhance git-worktree-manager with scripts, references, and Anthropic best practices * fix(skill): enhance mcp-server-builder with scripts, references, and Anthropic best practices * fix(skill): enhance changelog-generator with scripts, references, and Anthropic best practices * fix(skill): enhance ci-cd-pipeline-builder with scripts, references, and Anthropic best practices * fix(skill): enhance prompt-engineer-toolkit with scripts, references, and Anthropic best practices * docs: update README, CHANGELOG, and plugin metadata * fix: correct marketing plugin count, expand thin references --------- Co-authored-by: Leo <leo@openclaw.ai> --------- Co-authored-by: Leo <leo@openclaw.ai> * Dev (#250) * docs: restructure README.md — 2,539 → 209 lines (#247) - Cut from 2,539 lines / 73 sections to 209 lines / 18 sections - Consolidated 4 install methods into one unified section - Moved all skill details to domain-level READMEs (linked from table) - Front-loaded value prop and keywords for SEO - Added POWERFUL tier highlight section - Added skill-security-auditor showcase section - Removed stale Q4 2025 roadmap, outdated ROI claims, duplicate content - Fixed all internal links - Clean heading hierarchy (H2 for main sections only) Closes #233 Co-authored-by: Leo <leo@openclaw.ai> * fix: enhance 5 skills with scripts, references, and Anthropic best practices (#248) * fix(skill): enhance git-worktree-manager with scripts, references, and Anthropic best practices * fix(skill): enhance mcp-server-builder with scripts, references, and Anthropic best practices * fix(skill): enhance changelog-generator with scripts, references, and Anthropic best practices * fix(skill): enhance ci-cd-pipeline-builder with scripts, references, and Anthropic best practices * fix(skill): enhance prompt-engineer-toolkit with scripts, references, and Anthropic best practices * docs: update README, CHANGELOG, and plugin metadata * fix: correct marketing plugin count, expand thin references --------- Co-authored-by: Leo <leo@openclaw.ai> --------- Co-authored-by: Leo <leo@openclaw.ai> * ci: add VirusTotal security scan for skills - Scans changed skill directories on PRs to dev/main - Scans all skills on release publish - Posts scan results as PR comment with analysis links - Rate-limited to 4 req/min (free tier compatible) - Appends VirusTotal links to release body on publish * fix: resolve YAML lint errors in virustotal workflow - Add document start marker (---) - Quote 'on' key for truthy lint rule - Remove trailing spaces - Break long lines under 160 char limit --------- Co-authored-by: Baptiste Fernandez <fernandez.baptiste1@gmail.com> Co-authored-by: alirezarezvani <5697919+alirezarezvani@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Leo <leo@leo-agent-server> Co-authored-by: Leo <leo@openclaw.ai> * feat: add playwright-pro plugin — production-grade Playwright testing toolkit (#254) Complete Claude Code plugin with: - 9 skills (/pw:init, generate, review, fix, migrate, coverage, testrail, browserstack, report) - 3 specialized agents (test-architect, test-debugger, migration-planner) - 55 test case templates across 11 categories (auth, CRUD, checkout, search, forms, dashboard, settings, onboarding, notifications, API, accessibility) - TestRail MCP server (TypeScript) — 8 tools for bidirectional sync - BrowserStack MCP server (TypeScript) — 7 tools for cross-browser testing - Smart hooks (auto-validate tests, auto-detect Playwright projects) - 6 curated reference docs (golden rules, locators, assertions, fixtures, pitfalls, flaky tests) - Leverages Claude Code built-ins (/batch, /debug, Explore subagent) - Zero-config for core features; TestRail/BrowserStack via env vars - Both TypeScript and JavaScript support throughout Co-authored-by: Leo <leo@openclaw.ai> * feat: add playwright-pro to marketplace registry (#256) - New plugin: playwright-pro (9 skills, 3 agents, 55 templates, 2 MCP servers) - Install: /plugin install playwright-pro@claude-code-skills - Total marketplace plugins: 17 Co-authored-by: Leo <leo@openclaw.ai> * fix: integrate playwright-pro across all platforms (#258) - Add root SKILL.md for OpenClaw and ClawHub compatibility - Add to README: Skills Overview table, install section, badge count - Regenerate .codex/skills-index.json with playwright-pro entry - Add .codex/skills/playwright-pro symlink for Codex CLI - Fix YAML frontmatter (single-line description for index parsing) Platforms verified: - Claude Code: marketplace.json ✅ (merged in PR #256) - Codex CLI: symlink + skills-index.json ✅ - OpenClaw: SKILL.md auto-discovered by install script ✅ - ClawHub: published as playwright-pro@1.1.0 ✅ Co-authored-by: Leo <leo@openclaw.ai> * docs: update CLAUDE.md — reflect 87 skills across 9 domains Sync CLAUDE.md with actual repository state: add Engineering POWERFUL tier (25 skills), update all skill counts, add plugin registry references, and replace stale sprint section with v2.0.0 version info. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * docs: mention Claude Code in project description Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * feat: add self-improving-agent plugin — auto-memory curation for Claude Code (#260) New plugin: engineering-team/self-improving-agent/ - 5 skills: /si:review, /si:promote, /si:extract, /si:status, /si:remember - 2 agents: memory-analyst, skill-extractor - 1 hook: PostToolUse error capture (zero overhead on success) - 3 reference docs: memory architecture, promotion rules, rules directory patterns - 2 templates: rule template, skill template - 20 files, 1,829 lines Integrates natively with Claude Code's auto-memory (v2.1.32+). Reads from ~/.claude/projects/<path>/memory/ — no duplicate storage. Promotes proven patterns from MEMORY.md to CLAUDE.md or .claude/rules/. Also: - Added to marketplace.json (18 plugins total) - Added to README (Skills Overview + install section) - Updated badge count to 88+ - Regenerated .codex/skills-index.json + symlink Co-authored-by: Leo <leo@openclaw.ai> * feat: C-Suite expansion — 8 new executive advisory roles (2→10) (#264) * feat: C-Suite expansion — 8 new executive advisory roles Add COO, CPO, CMO, CFO, CRO, CISO, CHRO advisors and Executive Mentor. Expands C-level advisory from 2 to 10 roles with 74 total files. Each role includes: - SKILL.md (lean, <5KB, ~1200 tokens for context efficiency) - Reference docs (loaded on demand, not at startup) - Python analysis scripts (stdlib only, runnable CLI) Executive Mentor features /em: slash commands (challenge, board-prep, hard-call, stress-test, postmortem) with devil's advocate agent. 21 Python tools, 24 reference frameworks, 28,379 total lines. All SKILL.md files combined: ~17K tokens (8.5% of 200K context window). Badge: 88 → 116 skills * feat: C-Suite orchestration layer + 18 complementary skills ORCHESTRATION (new): - cs-onboard: Founder interview → company-context.md - chief-of-staff: Routing, synthesis, inter-agent orchestration - board-meeting: 6-phase multi-agent deliberation protocol - decision-logger: Two-layer memory (raw transcripts + approved decisions) - agent-protocol: Inter-agent invocation with loop prevention - context-engine: Company context loading + anonymization CROSS-CUTTING CAPABILITIES (new): - board-deck-builder: Board/investor update assembly - scenario-war-room: Cascading multi-variable what-if modeling - competitive-intel: Systematic competitor tracking + battlecards - org-health-diagnostic: Cross-functional health scoring (8 dimensions) - ma-playbook: M&A strategy (acquiring + being acquired) - intl-expansion: International market entry frameworks CULTURE & COLLABORATION (new): - culture-architect: Values → behaviors, culture code, health assessment - company-os: EOS/Scaling Up operating system selection + implementation - founder-coach: Founder development, delegation, blind spots - strategic-alignment: Strategy cascade, silo detection, alignment scoring - change-management: ADKAR-based change rollout framework - internal-narrative: One story across employees/investors/customers UPGRADES TO EXISTING ROLES: - All 10 roles get reasoning technique directives - All 10 roles get company-context.md integration - All 10 roles get board meeting isolation rules - CEO gets stage-adaptive temporal horizons (seed→C) Key design decisions: - Two-layer memory prevents hallucinated consensus from rejected ideas - Phase 2 isolation: agents think independently before cross-examination - Executive Mentor (The Critic) sees all perspectives, others don't - 25 Python tools total (stdlib only, no dependencies) 52 new files, 10 modified, 10,862 new lines. Total C-suite ecosystem: 134 files, 39,131 lines. * fix: connect all dots — Chief of Staff routes to all 28 skills - Added complementary skills registry to routing-matrix.md - Chief of Staff SKILL.md now lists all 28 skills in ecosystem - Added integration tables to scenario-war-room and competitive-intel - Badge: 116 → 134 skills - README: C-Level Advisory count 10 → 28 Quality audit passed: ✅ All 10 roles: company-context, reasoning, isolation, invocation ✅ All 6 phases in board meeting ✅ Two-layer memory with DO_NOT_RESURFACE ✅ Loop prevention (no self-invoke, max depth 2, no circular) ✅ All /em: commands present ✅ All complementary skills cross-reference roles ✅ Chief of Staff routes to every skill in ecosystem * refactor: CEO + CTO advisors upgraded to C-suite parity Both roles now match the structural standard of all new roles: - CEO: 11.7KB → 6.8KB SKILL.md (heavy content stays in references) - CTO: 10KB → 7.2KB SKILL.md (heavy content stays in references) Added to both: - Integration table (who they work with and when) - Key diagnostic questions - Structured metrics dashboard table - Consistent section ordering (Keywords → Quick Start → Responsibilities → Questions → Metrics → Red Flags → Integration → Reasoning → Context) CEO additions: - Stage-adaptive temporal horizons (seed=3m/6m/12m → B+=1y/3y/5y) - Cross-references to culture-architect and board-deck-builder CTO additions: - Key Questions section (7 diagnostic questions) - Structured metrics table (DORA + debt + team + architecture + cost) - Cross-references to all peer roles All 10 roles now pass structural parity: ✅ Keywords ✅ QuickStart ✅ Questions ✅ Metrics ✅ RedFlags ✅ Integration * feat: add proactive triggers + output artifacts to all 10 roles Every C-suite role now specifies: - Proactive Triggers: 'surface these without being asked' — context-driven early warnings that make advisors proactive, not reactive - Output Artifacts: concrete deliverables per request type (what you ask → what you get) CEO: runway alerts, board prep triggers, strategy review nudges CTO: deploy frequency monitoring, tech debt thresholds, bus factor flags COO: blocker detection, scaling threshold warnings, cadence gaps CPO: retention curve monitoring, portfolio dog detection, research gaps CMO: CAC trend monitoring, positioning gaps, budget staleness CFO: runway forecasting, burn multiple alerts, scenario planning gaps CRO: NRR monitoring, pipeline coverage, pricing review triggers CISO: audit overdue alerts, compliance gaps, vendor risk CHRO: retention risk, comp band gaps, org scaling thresholds Executive Mentor: board prep triggers, groupthink detection, hard call surfacing This transforms the C-suite from reactive advisors into proactive partners. * feat: User Communication Standard — structured output for all roles Defines 3 output formats in agent-protocol/SKILL.md: 1. Standard Output: Bottom Line → What → Why → How to Act → Risks → Your Decision 2. Proactive Alert: What I Noticed → Why It Matters → Action → Urgency (🔴🟡⚪) 3. Board Meeting: Decision Required → Perspectives → Agree/Disagree → Critic → Action Items 10 non-negotiable rules: - Bottom line first, always - Results and decisions only (no process narration) - What + Why + How for every finding - Actions have owners and deadlines ('we should consider' is banned) - Decisions framed as options with trade-offs - Founder is the highest authority — roles recommend, founder decides - Risks are concrete (if X → Y, costs $Z) - Max 5 bullets per section - No jargon without explanation - Silence over fabricated updates All 10 roles reference this standard. Chief of Staff enforces it as a quality gate. Board meeting Phase 4 uses the Board Meeting Output format. * feat: Internal Quality Loop — verification before delivery No role presents to the founder without passing verification: Step 1: Self-Verification (every role, every time) - Source attribution: where did each data point come from? - Assumption audit: [VERIFIED] vs [ASSUMED] tags on every finding - Confidence scoring: 🟢 high / 🟡 medium / 🔴 low per finding - Contradiction check against company-context + decision log - 'So what?' test: every finding needs a business consequence Step 2: Peer Verification (cross-functional) - Financial claims → CFO validates math - Revenue projections → CRO validates pipeline backing - Technical feasibility → CTO validates - People/hiring impact → CHRO validates - Skip for single-domain, low-stakes questions Step 3: Critic Pre-Screen (high-stakes only) - Irreversible decisions, >20% runway impact, strategy changes - Executive Mentor finds weakest point before founder sees it - Suspicious consensus triggers mandatory pre-screen Step 4: Course Correction (after founder feedback) - Approve → log + assign actions - Modify → re-verify changed parts - Reject → DO_NOT_RESURFACE + learn why - 30/60/90 day post-decision review Board meeting contributions now require self-verified format with confidence tags and source attribution on every finding. * fix: resolve PR review issues 1, 4, and minor observation Issue 1: c-level-advisor/CLAUDE.md — completely rewritten - Was: 2 skills (CEO, CTO only), dated Nov 2025 - Now: full 28-skill ecosystem map with architecture diagram, all roles/orchestration/cross-cutting/culture skills listed, design decisions, integration with other domains Issue 4: Root CLAUDE.md — updated all stale counts - 87 → 134 skills across all 3 references - C-Level: 2 → 33 (10 roles + 5 mentor commands + 18 complementary) - Tool count: 160+ → 185+ - Reference count: 200+ → 250+ Minor observation: Documented plugin.json convention - Explained in c-level-advisor/CLAUDE.md that only executive-mentor has plugin.json because only it has slash commands (/em: namespace) - Other skills are invoked by name through Chief of Staff or directly Also fixed: README.md 88+ → 134 in two places (first line + skills section) * fix: update all plugin/index registrations for 28-skill C-suite 1. c-level-advisor/.claude-plugin/plugin.json — v2.0.0 - Was: 2 skills, generic description - Now: all 28 skills listed with descriptions, all 25 scripts, namespace 'cs', full ecosystem description 2. .codex/skills-index.json — added 18 complementary skills - Was: 10 roles only - Now: 28 total c-level entries (10 roles + 6 orchestration + 6 cross-cutting + 6 culture) - Each with full description for skill discovery 3. .claude-plugin/marketplace.json — updated c-level-skills entry - Was: generic 2-skill description - Now: v2.0.0, full 28-skill ecosystem description, skills_count: 28, scripts_count: 25 * feat: add root SKILL.md for c-level-advisor ClawHub package --------- Co-authored-by: Leo <leo@openclaw.ai> * chore: sync codex skills symlinks [automated] * feat: Marketing Division expansion — 7 → 42 skills (#266) * feat: Skill Authoring Standard + Marketing Expansion plans SKILL-AUTHORING-STANDARD.md — the DNA of every skill in this repo: 10 universal patterns codified from C-Suite innovations + Corey Haines' marketingskills patterns: 1. Context-First: check domain context, ask only for gaps 2. Practitioner Voice: expert persona, goal-oriented, not textbook 3. Multi-Mode Workflows: build from scratch / optimize existing / situation-specific 4. Related Skills Navigation: when to use, when NOT to, bidirectional 5. Reference Separation: SKILL.md lean (≤10KB), refs deep 6. Proactive Triggers: surface issues without being asked 7. Output Artifacts: request → specific deliverable mapping 8. Quality Loop: self-verify, confidence tagging 9. Communication Standard: bottom line first, structured output 10. Python Tools: stdlib-only, CLI-first, JSON output, sample data Marketing expansion plans for 40-skill marketing division build. * feat: marketing foundation — context + ops router + authoring standard marketing-context/: Foundation skill every marketing skill reads first - SKILL.md: 3 modes (auto-draft, guided interview, update) - templates/marketing-context-template.md: 14 sections covering product, audience, personas, pain points, competitive landscape, differentiation, objections, switching dynamics, customer language (verbatim), brand voice, style guide, proof points, SEO context, goals - scripts/context_validator.py: Scores completeness 0-100, section-by-section marketing-ops/: Central router for 40-skill marketing ecosystem - Full routing matrix: 7 pods + cross-domain routing to 6 skills in business-growth, product-team, engineering-team, c-level-advisor - Campaign orchestration sequences (launch, content, CRO sprint) - Quality gate matching C-Suite standard - scripts/campaign_tracker.py: Campaign status tracking with progress, overdue detection, pod coverage, blocker identification SKILL-AUTHORING-STANDARD.md: Universal DNA for all skills - 10 patterns: context-first, practitioner voice, multi-mode workflows, related skills navigation, reference separation, proactive triggers, output artifacts, quality loop, communication standard, python tools - Quality checklist for skill completion verification - Domain context file mapping for all 5 domains * feat: import 20 workspace marketing skills + standard sections Imported 20 marketing skills from OpenClaw workspace into repo: Content Pod (5): content-strategy, copywriting, copy-editing, social-content, marketing-ideas SEO Pod (2): seo-audit (+ references enriched by subagent), programmatic-seo (+ refs) CRO Pod (5): page-cro, form-cro, signup-flow-cro, onboarding-cro, popup-cro, paywall-upgrade-cro Channels Pod (2): email-sequence, paid-ads Growth + Intel + GTM (5): ab-test-setup, competitor-alternatives, marketing-psychology, launch-strategy, brand-guidelines All 29 skills now have standard sections per SKILL-AUTHORING-STANDARD.md: ✅ Proactive Triggers (4-5 per skill) ✅ Output Artifacts table ✅ Communication standard reference ✅ Related Skills with WHEN/NOT disambiguation Subagents enriched 8 skills with additional reference docs: seo-audit, programmatic-seo, page-cro, form-cro, onboarding-cro, popup-cro, paywall-upgrade-cro, email-sequence 43 files, 10,566 lines added. * feat: build 13 new marketing skills + social-media-manager upgrade All skills are 100% original work — inspired by industry best practices, written from scratch in our own voice following SKILL-AUTHORING-STANDARD.md. NEW Content Pod (2): content-production — full research→draft→optimize pipeline, content_scorer.py content-humanizer — AI pattern detection + voice injection, humanizer_scorer.py NEW SEO Pod (3): ai-seo — AI search optimization (AEO/GEO/LLMO), entirely new category schema-markup — JSON-LD structured data, schema_validator.py site-architecture — URL structure + internal linking, sitemap_analyzer.py NEW Channels Pod (2): cold-email — B2B outreach (distinct from email-sequence lifecycle) ad-creative — bulk ad generation + platform specs, ad_copy_validator.py NEW Growth Pod (3): churn-prevention — cancel flows + save offers + dunning, churn_impact_calculator.py referral-program — referral + affiliate programs free-tool-strategy — engineering as marketing NEW Intelligence Pod (1): analytics-tracking — GA4/GTM setup + event taxonomy, tracking_plan_generator.py NEW Sales Pod (1): pricing-strategy — pricing, packaging, monetization UPGRADED: social-media-analyzer → social-media-manager (strategy, calendar, community) Totals: 42 skills, 27 Python scripts, 60 reference docs, 163 files, 43,265 lines * feat: update index, marketplace, README for 42 marketing skills - skills-index.json: 89 → 124 skills (42 marketing entries) - marketplace.json: marketing-skills v2.0.0 (42 skills, 27 tools) - README.md: badge 134 → 169, marketing row updated - prompt-engineer-toolkit: added YAML frontmatter - Removed build logs from repo - Parity check: 42/42 passed (YAML + Related + Proactive + Output + Communication) * fix: merge content-creator into content-production, split marketing-psychology Quality audit fixes: 1. content-creator → DEPRECATED redirect - Scripts (brand_voice_analyzer.py, seo_optimizer.py) moved to content-production - SKILL.md replaced with redirect to content-production + content-strategy - Eliminates duplicate routing confusion 2. marketing-psychology → 24KB split to 6.8KB + reference - 70+ mental models moved to references/mental-models-catalog.md (397 lines) - SKILL.md now lean: categories overview, most-used models, quick reference - Saves ~4,300 tokens per invocation * feat: add plugin configs, Codex/OpenClaw compatibility, ClawHub packaging - marketing-skill/SKILL.md: ClawHub-compatible root with Quick Start for Claude Code, Codex CLI, OpenClaw - marketing-skill/CLAUDE.md: Agent instructions (routing, context, anti-patterns) - marketing-skill/.codex/instructions.md: Codex CLI skill routing - .claude-plugin/marketplace.json: deduplicated, marketing-skills v2.0.0 - .codex/skills-index.json: content-creator marked deprecated, psychology updated - Total: 42 skills, 27 Python tools, 60 references, 18 plugins * feat: add 16 Python tools to knowledge-only skills Enriched 12 previously tool-less skills with practical Python scripts: - seo-audit/seo_checker.py — HTML on-page SEO analysis (0-100) - copywriting/headline_scorer.py — headline quality scoring (0-100) - copy-editing/readability_scorer.py — Flesch + passive + filler detection - content-strategy/topic_cluster_mapper.py — keyword clustering - page-cro/conversion_audit.py — HTML CRO signal analysis (0-100) - paid-ads/roas_calculator.py — ROAS/CPA/CPL calculator - email-sequence/sequence_analyzer.py — email sequence scoring (0-100) - form-cro/form_field_analyzer.py — form field CRO audit (0-100) - onboarding-cro/activation_funnel_analyzer.py — funnel drop-off analysis - programmatic-seo/url_pattern_generator.py — URL pattern planning - ab-test-setup/sample_size_calculator.py — statistical sample sizing - signup-flow-cro/funnel_drop_analyzer.py — signup funnel analysis - launch-strategy/launch_readiness_scorer.py — launch checklist scoring - competitor-alternatives/comparison_matrix_builder.py — feature comparison - social-media-manager/social_calendar_generator.py — content calendar - readability_scorer.py — fixed demo mode for non-TTY execution All 43/43 scripts pass execution. All stdlib-only, zero pip installs. Total: 42 skills, 43 Python tools, 60+ reference docs. * feat: add 3 more Python tools + improve 6 existing scripts New tools from build agent: - email-sequence/scripts/sequence_analyzer.py — email sequence scoring (91/100 demo) - paid-ads/scripts/roas_calculator.py — ROAS/CPA/CPL/break-even calculator - competitor-alternatives/scripts/comparison_matrix_builder.py — feature matrix Improved scripts (better demo modes, fuller analysis): - seo_checker.py, headline_scorer.py, readability_scorer.py, conversion_audit.py, topic_cluster_mapper.py, launch_readiness_scorer.py Total: 42 skills, 47 Python tools, all passing. * fix: remove duplicate scripts from deprecated content-creator Scripts already live in content-production/scripts/. The content-creator directory is now a pure redirect (SKILL.md only + legacy assets/refs). * fix: scope VirusTotal scan to executable files only Skip scanning .md, .py, .json, .yml — they're plain text files that VirusTotal can't meaningfully analyze. This prevents 429 rate limit errors on PRs with many text file changes (like 42 marketing skills). Scan still covers: .js, .ts, .sh, .mjs, .cjs, .exe, .dll, .so, .bin, .wasm --------- Co-authored-by: Leo <leo@openclaw.ai> * chore: sync codex skills symlinks [automated] --------- Co-authored-by: Leo <leo@openclaw.ai> Co-authored-by: Baptiste Fernandez <fernandez.baptiste1@gmail.com> Co-authored-by: alirezarezvani <5697919+alirezarezvani@users.noreply.github.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com> Co-authored-by: Leo <leo@leo-agent-server>
This commit is contained in:
Alireza Rezvani
GitHub
@@ -12,23 +12,6 @@
|
||||
"version": "2.1.0"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"source": "./marketing-skill",
|
||||
"description": "6 marketing skills: content creator, demand generation, product marketing, ASO, social media analytics, campaign analytics",
|
||||
"version": "1.0.0",
|
||||
"author": {
|
||||
"name": "Alireza Rezvani"
|
||||
},
|
||||
"keywords": [
|
||||
"marketing",
|
||||
"content",
|
||||
"seo",
|
||||
"demand-gen",
|
||||
"social-media"
|
||||
],
|
||||
"category": "marketing"
|
||||
},
|
||||
{
|
||||
"name": "engineering-skills",
|
||||
"source": "./engineering-team",
|
||||
@@ -340,6 +323,16 @@
|
||||
"self-improvement",
|
||||
"learning"
|
||||
]
|
||||
},
|
||||
{
|
||||
"slug": "marketing-skills",
|
||||
"name": "Marketing Division",
|
||||
"version": "2.0.0",
|
||||
"description": "42-skill marketing division: 7 pods (Content, SEO, CRO, Channels, Growth, Intelligence, Sales) + context foundation + orchestration router. 27 Python tools, 60 reference docs. All stdlib-only.",
|
||||
"path": "marketing-skill/",
|
||||
"skills_count": 42,
|
||||
"category": "marketing"
|
||||
}
|
||||
]
|
||||
],
|
||||
"total_plugins": 18
|
||||
}
|
||||
@@ -3,7 +3,7 @@
|
||||
"name": "claude-code-skills",
|
||||
"description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM",
|
||||
"repository": "https://github.com/alirezarezvani/claude-skills",
|
||||
"total_skills": 89,
|
||||
"total_skills": 124,
|
||||
"skills": [
|
||||
{
|
||||
"name": "contract-and-proposal-writer",
|
||||
@@ -341,23 +341,131 @@
|
||||
"category": "finance",
|
||||
"description": "Performs financial ratio analysis, DCF valuation, budget variance analysis, and rolling forecast construction for strategic decision-making"
|
||||
},
|
||||
{
|
||||
"name": "ab-test-setup",
|
||||
"source": "../../marketing-skill/ab-test-setup",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions \"A/B test,\" \"split test,\" \"experiment,\" \"test this change,\" \"variant copy,\" \"multivariate test,\" \"hypothesis,\" \"conversion experiment,\" \"statistical significance,\" or \"test this.\" For tracking implementation, see analytics-tracking."
|
||||
},
|
||||
{
|
||||
"name": "ad-creative",
|
||||
"source": "../../marketing-skill/ad-creative",
|
||||
"category": "marketing",
|
||||
"description": "When the user needs to generate, iterate, or scale ad creative for paid advertising. Use when they say 'write ad copy,' 'generate headlines,' 'create ad variations,' 'bulk creative,' 'iterate on ads,' 'ad copy validation,' 'RSA headlines,' 'Meta ad copy,' 'LinkedIn ad,' or 'creative testing.' This is pure creative production \u2014 distinct from paid-ads (campaign strategy). Use ad-creative when you need the copy, not the campaign plan."
|
||||
},
|
||||
{
|
||||
"name": "ai-seo",
|
||||
"source": "../../marketing-skill/ai-seo",
|
||||
"category": "marketing",
|
||||
"description": "Optimize content to get cited by AI search engines \u2014 ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your content to appear in AI-generated answers, not just ranked in blue links. Triggers: 'optimize for AI search', 'get cited by ChatGPT', 'AI Overviews', 'Perplexity citations', 'AI SEO', 'generative search', 'LLM visibility', 'GEO' (generative engine optimization). NOT for traditional SEO ranking (use seo-audit). NOT for content creation (use content-production)."
|
||||
},
|
||||
{
|
||||
"name": "analytics-tracking",
|
||||
"source": "../../marketing-skill/analytics-tracking",
|
||||
"category": "marketing",
|
||||
"description": "Set up, audit, and debug analytics tracking implementation \u2014 GA4, Google Tag Manager, event taxonomy, conversion tracking, and data quality. Use when building a tracking plan from scratch, auditing existing analytics for gaps or errors, debugging missing events, or setting up GTM. Trigger keywords: GA4 setup, Google Tag Manager, GTM, event tracking, analytics implementation, conversion tracking, tracking plan, event taxonomy, custom dimensions, UTM tracking, analytics audit, missing events, tracking broken. NOT for analyzing marketing campaign data \u2014 use campaign-analytics for that. NOT for BI dashboards \u2014 use product-analytics for in-product event analysis."
|
||||
},
|
||||
{
|
||||
"name": "app-store-optimization",
|
||||
"source": "../../marketing-skill/app-store-optimization",
|
||||
"category": "marketing",
|
||||
"description": "App Store Optimization toolkit for researching keywords, optimizing metadata, and tracking mobile app performance on Apple App Store and Google Play Store."
|
||||
},
|
||||
{
|
||||
"name": "brand-guidelines",
|
||||
"source": "../../marketing-skill/brand-guidelines",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to apply, document, or enforce brand guidelines for any product or company. Also use when the user mentions 'brand guidelines,' 'brand colors,' 'typography,' 'logo usage,' 'brand voice,' 'visual identity,' 'tone of voice,' 'brand standards,' 'style guide,' 'brand consistency,' or 'company design standards.' Covers color systems, typography, logo rules, imagery guidelines, and tone matrix for any brand \u2014 including Anthropic's official identity."
|
||||
},
|
||||
{
|
||||
"name": "campaign-analytics",
|
||||
"source": "../../marketing-skill/campaign-analytics",
|
||||
"category": "marketing",
|
||||
"description": "Analyzes campaign performance with multi-touch attribution, funnel conversion, and ROI calculation for marketing optimization"
|
||||
},
|
||||
{
|
||||
"name": "churn-prevention",
|
||||
"source": "../../marketing-skill/churn-prevention",
|
||||
"category": "marketing",
|
||||
"description": "Reduce voluntary and involuntary churn through cancel flow design, save offers, exit surveys, and dunning sequences. Use when designing or optimizing a cancel flow, building save offers, setting up dunning emails, or reducing failed-payment churn. Trigger keywords: cancel flow, churn reduction, save offers, dunning, exit survey, payment recovery, win-back, involuntary churn, failed payments, cancel page. NOT for customer health scoring or expansion revenue \u2014 use customer-success-manager for that."
|
||||
},
|
||||
{
|
||||
"name": "cold-email",
|
||||
"source": "../../marketing-skill/cold-email",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to write, improve, or build a sequence of B2B cold outreach emails to prospects who haven't asked to hear from them. Use when the user mentions 'cold email,' 'cold outreach,' 'prospecting emails,' 'SDR emails,' 'sales emails,' 'first touch email,' 'follow-up sequence,' or 'email prospecting.' Also use when they share an email draft that sounds too sales-y and needs to be humanized. Distinct from email-sequence (lifecycle/nurture to opted-in subscribers) \u2014 this is unsolicited outreach to new prospects. NOT for lifecycle emails, newsletters, or drip campaigns (use email-sequence)."
|
||||
},
|
||||
{
|
||||
"name": "competitor-alternatives",
|
||||
"source": "../../marketing-skill/competitor-alternatives",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'switch from competitor,' or 'comparison content.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
|
||||
},
|
||||
{
|
||||
"name": "content-creator",
|
||||
"source": "../../marketing-skill/content-creator",
|
||||
"category": "marketing",
|
||||
"description": "Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy."
|
||||
"description": "DEPRECATED \u2014 Use content-production for full content pipeline, or content-strategy for planning. This skill redirects to the appropriate specialist."
|
||||
},
|
||||
{
|
||||
"name": "content-humanizer",
|
||||
"source": "../../marketing-skill/content-humanizer",
|
||||
"category": "marketing",
|
||||
"description": "Makes AI-generated content sound genuinely human \u2014 not just cleaned up, but alive. Use when content feels robotic, uses too many AI clich\u00e9s, lacks personality, or reads like it was written by committee. Triggers: 'this sounds like AI', 'make it more human', 'add personality', 'it feels generic', 'sounds robotic', 'fix AI writing', 'inject our voice'. NOT for initial content creation (use content-production). NOT for SEO optimization (use content-production Mode 3)."
|
||||
},
|
||||
{
|
||||
"name": "content-production",
|
||||
"source": "../../marketing-skill/content-production",
|
||||
"category": "marketing",
|
||||
"description": "Full content production pipeline \u2014 takes a topic from blank page to published-ready piece. Use when you need to execute content: write a blog post, article, or guide end-to-end. Triggers: 'write a post about', 'draft an article', 'create content for', 'help me write', 'I need a blog post'. NOT for content strategy or calendar planning (use content-strategy). NOT for repurposing existing content (use content-repurposing). NOT for social captions only."
|
||||
},
|
||||
{
|
||||
"name": "content-strategy",
|
||||
"source": "../../marketing-skill/content-strategy",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions \\\"content strategy,\\\" \\\"what should I write about,\\\" \\\"content ideas,\\\" \\\"blog strategy,\\\" \\\"topic clusters,\\\" or \\\"content planning.\\\" For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit."
|
||||
},
|
||||
{
|
||||
"name": "copy-editing",
|
||||
"source": "../../marketing-skill/copy-editing",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes."
|
||||
},
|
||||
{
|
||||
"name": "copywriting",
|
||||
"source": "../../marketing-skill/copywriting",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to write, rewrite, or improve marketing copy for any page \u2014 including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says \\\"write copy for,\\\" \\\"improve this copy,\\\" \\\"rewrite this page,\\\" \\\"marketing copy,\\\" \\\"headline help,\\\" or \\\"CTA copy.\\\" For email copy, see email-sequence. For popup copy, see popup-cro."
|
||||
},
|
||||
{
|
||||
"name": "email-sequence",
|
||||
"source": "../../marketing-skill/email-sequence",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions \"email sequence,\" \"drip campaign,\" \"nurture sequence,\" \"onboarding emails,\" \"welcome sequence,\" \"re-engagement emails,\" \"email automation,\" or \"lifecycle emails.\" For in-app onboarding, see onboarding-cro."
|
||||
},
|
||||
{
|
||||
"name": "form-cro",
|
||||
"source": "../../marketing-skill/form-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to optimize any form that is NOT signup/registration \u2014 including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions \"form optimization,\" \"lead form conversions,\" \"form friction,\" \"form fields,\" \"form completion rate,\" or \"contact form.\" For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro."
|
||||
},
|
||||
{
|
||||
"name": "free-tool-strategy",
|
||||
"source": "../../marketing-skill/free-tool-strategy",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to build a free tool for marketing \u2014 lead generation, SEO value, or brand awareness. Use when they mention 'engineering as marketing,' 'free tool,' 'calculator,' 'generator,' 'checker,' 'grader,' 'marketing tool,' 'lead gen tool,' 'build something for traffic,' 'interactive tool,' or 'free resource.' Covers idea evaluation, tool design, and launch strategy. For pure SEO content strategy (no tool), use seo-audit or content-strategy instead."
|
||||
},
|
||||
{
|
||||
"name": "launch-strategy",
|
||||
"source": "../../marketing-skill/launch-strategy",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' 'product update,' 'GTM plan,' 'launch checklist,' or 'launch momentum.' This skill covers phased launches, channel strategy, and ongoing launch momentum."
|
||||
},
|
||||
{
|
||||
"name": "marketing-context",
|
||||
"source": "../../marketing-skill/marketing-context",
|
||||
"category": "marketing",
|
||||
"description": "Create and maintain the marketing context document that all marketing skills read before starting. Use when the user mentions 'marketing context,' 'brand voice,' 'set up context,' 'target audience,' 'ICP,' 'style guide,' 'who is my customer,' 'positioning,' or wants to avoid repeating foundational information across marketing tasks. Run this at the start of any new project before using other marketing skills."
|
||||
},
|
||||
{
|
||||
"name": "marketing-demand-acquisition",
|
||||
@@ -365,17 +473,113 @@
|
||||
"category": "marketing",
|
||||
"description": "Multi-channel demand generation, paid media optimization, SEO strategy, and partnership programs for Series A+ startups"
|
||||
},
|
||||
{
|
||||
"name": "marketing-ideas",
|
||||
"source": "../../marketing-skill/marketing-ideas",
|
||||
"category": "marketing",
|
||||
"description": "When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' or 'ideas to grow.' This skill provides 139 proven marketing approaches organized by category."
|
||||
},
|
||||
{
|
||||
"name": "marketing-ops",
|
||||
"source": "../../marketing-skill/marketing-ops",
|
||||
"category": "marketing",
|
||||
"description": "Central router for the marketing skill ecosystem. Use when unsure which marketing skill to use, when orchestrating a multi-skill campaign, or when coordinating across content, SEO, CRO, channels, and analytics. Also use when the user mentions 'marketing help,' 'campaign plan,' 'what should I do next,' 'marketing priorities,' or 'coordinate marketing.'"
|
||||
},
|
||||
{
|
||||
"name": "marketing-psychology",
|
||||
"source": "../../marketing-skill/marketing-psychology",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' or 'consumer behavior.' This skill provides 70+ mental models organized for marketing application."
|
||||
},
|
||||
{
|
||||
"name": "marketing-strategy-pmm",
|
||||
"source": "../../marketing-skill/marketing-strategy-pmm",
|
||||
"category": "marketing",
|
||||
"description": "Product marketing skill for positioning, GTM strategy, competitive intelligence, and product launches. Covers April Dunford positioning, ICP definition, competitive battlecards, launch playbooks, and international market entry."
|
||||
},
|
||||
{
|
||||
"name": "onboarding-cro",
|
||||
"source": "../../marketing-skill/onboarding-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions \"onboarding flow,\" \"activation rate,\" \"user activation,\" \"first-run experience,\" \"empty states,\" \"onboarding checklist,\" \"aha moment,\" or \"new user experience.\" For signup/registration optimization, see signup-flow-cro. For ongoing email sequences, see email-sequence."
|
||||
},
|
||||
{
|
||||
"name": "page-cro",
|
||||
"source": "../../marketing-skill/page-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to optimize, improve, or increase conversions on any marketing page \u2014 including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says \"CRO,\" \"conversion rate optimization,\" \"this page isn't converting,\" \"improve conversions,\" or \"why isn't this page working.\" For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro."
|
||||
},
|
||||
{
|
||||
"name": "paid-ads",
|
||||
"source": "../../marketing-skill/paid-ads",
|
||||
"category": "marketing",
|
||||
"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,' 'ad copy,' 'ad creative,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' or 'audience targeting.' This skill covers campaign strategy, ad creation, audience targeting, and optimization."
|
||||
},
|
||||
{
|
||||
"name": "paywall-upgrade-cro",
|
||||
"source": "../../marketing-skill/paywall-upgrade-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions \"paywall,\" \"upgrade screen,\" \"upgrade modal,\" \"upsell,\" \"feature gate,\" \"convert free to paid,\" \"freemium conversion,\" \"trial expiration screen,\" \"limit reached screen,\" \"plan upgrade prompt,\" or \"in-app pricing.\" Distinct from public pricing pages (see page-cro) \u2014 this skill focuses on in-product upgrade moments where the user has already experienced value."
|
||||
},
|
||||
{
|
||||
"name": "popup-cro",
|
||||
"source": "../../marketing-skill/popup-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions \"exit intent,\" \"popup conversions,\" \"modal optimization,\" \"lead capture popup,\" \"email popup,\" \"announcement banner,\" or \"overlay.\" For forms outside of popups, see form-cro. For general page conversion optimization, see page-cro."
|
||||
},
|
||||
{
|
||||
"name": "pricing-strategy",
|
||||
"source": "../../marketing-skill/pricing-strategy",
|
||||
"category": "marketing",
|
||||
"description": "Design, optimize, and communicate SaaS pricing \u2014 tier structure, value metrics, pricing pages, and price increase strategy. Use when building a pricing model from scratch, redesigning existing pricing, planning a price increase, or improving a pricing page. Trigger keywords: pricing tiers, pricing page, price increase, packaging, value metric, per seat pricing, usage-based pricing, freemium, good-better-best, pricing strategy, monetization, pricing page conversion, Van Westendorp. NOT for broader product strategy \u2014 use product-strategist for that. NOT for customer success or renewals \u2014 use customer-success-manager for expansion revenue."
|
||||
},
|
||||
{
|
||||
"name": "programmatic-seo",
|
||||
"source": "../../marketing-skill/programmatic-seo",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions \"programmatic SEO,\" \"template pages,\" \"pages at scale,\" \"directory pages,\" \"location pages,\" \"[keyword] + [city] pages,\" \"comparison pages,\" \"integration pages,\" or \"building many pages for SEO.\" For auditing existing SEO issues, see seo-audit."
|
||||
},
|
||||
{
|
||||
"name": "prompt-engineer-toolkit",
|
||||
"source": "../../marketing-skill/prompt-engineer-toolkit",
|
||||
"category": "marketing",
|
||||
"description": "Skill from marketing-skill"
|
||||
"description": "When the user wants to improve prompts for AI-assisted marketing, build prompt templates, or optimize AI content workflows. Also use when the user mentions 'prompt engineering,' 'improve my prompts,' 'AI writing quality,' 'prompt templates,' or 'AI content workflow.'"
|
||||
},
|
||||
{
|
||||
"name": "referral-program",
|
||||
"source": "../../marketing-skill/referral-program",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to design, launch, or optimize a referral or affiliate program. Use when they mention 'referral program,' 'affiliate program,' 'word of mouth,' 'refer a friend,' 'incentive program,' 'customer referrals,' 'brand ambassador,' 'partner program,' 'referral link,' or 'growth through referrals.' Covers program mechanics, incentive design, and optimization \u2014 not just the idea of referrals but the actual system."
|
||||
},
|
||||
{
|
||||
"name": "schema-markup",
|
||||
"source": "../../marketing-skill/schema-markup",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to implement, audit, or validate structured data (schema markup) on their website. Use when the user mentions 'structured data,' 'schema.org,' 'JSON-LD,' 'rich results,' 'rich snippets,' 'schema markup,' 'FAQ schema,' 'Product schema,' 'HowTo schema,' or 'structured data errors in Search Console.' Also use when someone asks why their content isn't showing rich results or wants to improve AI search visibility. NOT for general SEO audits (use seo-audit) or technical SEO crawl issues (use site-architecture)."
|
||||
},
|
||||
{
|
||||
"name": "seo-audit",
|
||||
"source": "../../marketing-skill/seo-audit",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions \"SEO audit,\" \"technical SEO,\" \"why am I not ranking,\" \"SEO issues,\" \"on-page SEO,\" \"meta tags review,\" or \"SEO health check.\" For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup."
|
||||
},
|
||||
{
|
||||
"name": "signup-flow-cro",
|
||||
"source": "../../marketing-skill/signup-flow-cro",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions \"signup conversions,\" \"registration friction,\" \"signup form optimization,\" \"free trial signup,\" \"reduce signup dropoff,\" or \"account creation flow.\" For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro."
|
||||
},
|
||||
{
|
||||
"name": "site-architecture",
|
||||
"source": "../../marketing-skill/site-architecture",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to audit, redesign, or plan their website's structure, URL hierarchy, navigation design, or internal linking strategy. Use when the user mentions 'site architecture,' 'URL structure,' 'internal links,' 'site navigation,' 'breadcrumbs,' 'topic clusters,' 'hub pages,' 'orphan pages,' 'silo structure,' 'information architecture,' or 'website reorganization.' Also use when someone has SEO problems and the root cause is structural (not content or schema). NOT for content strategy decisions about what to write (use content-strategy) or for schema markup (use schema-markup)."
|
||||
},
|
||||
{
|
||||
"name": "social-content",
|
||||
"source": "../../marketing-skill/social-content",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' or 'viral content.' This skill covers content creation, repurposing, and platform-specific strategies."
|
||||
},
|
||||
{
|
||||
"name": "social-media-analyzer",
|
||||
@@ -383,6 +587,12 @@
|
||||
"category": "marketing",
|
||||
"description": "Social media campaign analysis and performance tracking. Calculates engagement rates, ROI, and benchmarks across platforms. Use for analyzing social media performance, calculating engagement rate, measuring campaign ROI, comparing platform metrics, or benchmarking against industry standards."
|
||||
},
|
||||
{
|
||||
"name": "social-media-manager",
|
||||
"source": "../../marketing-skill/social-media-manager",
|
||||
"category": "marketing",
|
||||
"description": "When the user wants to develop social media strategy, plan content calendars, manage community engagement, or grow their social presence across platforms. Also use when the user mentions 'social media strategy,' 'social calendar,' 'community management,' 'social media plan,' 'grow followers,' 'engagement rate,' 'social media audit,' or 'which platforms should I use.' For writing individual social posts, see social-content. For analyzing social performance data, see social-media-analyzer."
|
||||
},
|
||||
{
|
||||
"name": "agile-product-owner",
|
||||
"source": "../../product-team/agile-product-owner",
|
||||
@@ -562,7 +772,7 @@
|
||||
"description": "Financial analysis, valuation, and forecasting skills"
|
||||
},
|
||||
"marketing": {
|
||||
"count": 7,
|
||||
"count": 42,
|
||||
"source": "../../marketing-skill",
|
||||
"description": "Marketing, content, and demand generation skills"
|
||||
},
|
||||
|
||||
1
.codex/skills/ab-test-setup
Symbolic link
1
.codex/skills/ab-test-setup
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/ab-test-setup
|
||||
1
.codex/skills/ad-creative
Symbolic link
1
.codex/skills/ad-creative
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/ad-creative
|
||||
1
.codex/skills/ai-seo
Symbolic link
1
.codex/skills/ai-seo
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/ai-seo
|
||||
1
.codex/skills/analytics-tracking
Symbolic link
1
.codex/skills/analytics-tracking
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/analytics-tracking
|
||||
1
.codex/skills/brand-guidelines
Symbolic link
1
.codex/skills/brand-guidelines
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/brand-guidelines
|
||||
1
.codex/skills/churn-prevention
Symbolic link
1
.codex/skills/churn-prevention
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/churn-prevention
|
||||
1
.codex/skills/cold-email
Symbolic link
1
.codex/skills/cold-email
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/cold-email
|
||||
1
.codex/skills/competitor-alternatives
Symbolic link
1
.codex/skills/competitor-alternatives
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/competitor-alternatives
|
||||
1
.codex/skills/content-humanizer
Symbolic link
1
.codex/skills/content-humanizer
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/content-humanizer
|
||||
1
.codex/skills/content-production
Symbolic link
1
.codex/skills/content-production
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/content-production
|
||||
1
.codex/skills/content-strategy
Symbolic link
1
.codex/skills/content-strategy
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/content-strategy
|
||||
1
.codex/skills/copy-editing
Symbolic link
1
.codex/skills/copy-editing
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/copy-editing
|
||||
1
.codex/skills/copywriting
Symbolic link
1
.codex/skills/copywriting
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/copywriting
|
||||
1
.codex/skills/email-sequence
Symbolic link
1
.codex/skills/email-sequence
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/email-sequence
|
||||
1
.codex/skills/form-cro
Symbolic link
1
.codex/skills/form-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/form-cro
|
||||
1
.codex/skills/free-tool-strategy
Symbolic link
1
.codex/skills/free-tool-strategy
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/free-tool-strategy
|
||||
1
.codex/skills/launch-strategy
Symbolic link
1
.codex/skills/launch-strategy
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/launch-strategy
|
||||
1
.codex/skills/marketing-context
Symbolic link
1
.codex/skills/marketing-context
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/marketing-context
|
||||
1
.codex/skills/marketing-ideas
Symbolic link
1
.codex/skills/marketing-ideas
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/marketing-ideas
|
||||
1
.codex/skills/marketing-ops
Symbolic link
1
.codex/skills/marketing-ops
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/marketing-ops
|
||||
1
.codex/skills/marketing-psychology
Symbolic link
1
.codex/skills/marketing-psychology
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/marketing-psychology
|
||||
1
.codex/skills/onboarding-cro
Symbolic link
1
.codex/skills/onboarding-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/onboarding-cro
|
||||
1
.codex/skills/page-cro
Symbolic link
1
.codex/skills/page-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/page-cro
|
||||
1
.codex/skills/paid-ads
Symbolic link
1
.codex/skills/paid-ads
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/paid-ads
|
||||
1
.codex/skills/paywall-upgrade-cro
Symbolic link
1
.codex/skills/paywall-upgrade-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/paywall-upgrade-cro
|
||||
1
.codex/skills/popup-cro
Symbolic link
1
.codex/skills/popup-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/popup-cro
|
||||
1
.codex/skills/pricing-strategy
Symbolic link
1
.codex/skills/pricing-strategy
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/pricing-strategy
|
||||
1
.codex/skills/programmatic-seo
Symbolic link
1
.codex/skills/programmatic-seo
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/programmatic-seo
|
||||
1
.codex/skills/referral-program
Symbolic link
1
.codex/skills/referral-program
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/referral-program
|
||||
1
.codex/skills/schema-markup
Symbolic link
1
.codex/skills/schema-markup
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/schema-markup
|
||||
1
.codex/skills/seo-audit
Symbolic link
1
.codex/skills/seo-audit
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/seo-audit
|
||||
1
.codex/skills/signup-flow-cro
Symbolic link
1
.codex/skills/signup-flow-cro
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/signup-flow-cro
|
||||
1
.codex/skills/site-architecture
Symbolic link
1
.codex/skills/site-architecture
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/site-architecture
|
||||
1
.codex/skills/social-content
Symbolic link
1
.codex/skills/social-content
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/social-content
|
||||
1
.codex/skills/social-media-manager
Symbolic link
1
.codex/skills/social-media-manager
Symbolic link
@@ -0,0 +1 @@
|
||||
../../marketing-skill/social-media-manager
|
||||
4
.github/workflows/virustotal-scan.yml
vendored
4
.github/workflows/virustotal-scan.yml
vendored
@@ -29,10 +29,12 @@ jobs:
|
||||
run: |
|
||||
mkdir -p /tmp/vt-scan
|
||||
|
||||
# Only scan executable/binary-capable files — skip text-only formats
|
||||
# (.md, .py, .json, .yml are plain text; VT adds no value scanning them)
|
||||
CHANGED=$(git diff --name-only \
|
||||
${{ github.event.pull_request.base.sha }} \
|
||||
${{ github.sha }} \
|
||||
| grep -E '\.(js|ts|py|sh|json|yml|yaml|md|mjs|cjs)$' || true)
|
||||
| grep -E '\.(js|ts|sh|mjs|cjs|exe|dll|so|bin|wasm)$' || true)
|
||||
|
||||
if [ -z "$CHANGED" ]; then
|
||||
echo "No scannable files changed"
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
# Claude Skills Library
|
||||
|
||||
**134 production-ready skill packages for Claude Code, OpenAI Codex, and OpenClaw** — reusable expertise bundles that transform AI agents into specialized professionals across engineering, product, marketing, compliance, and more.
|
||||
**169 production-ready skill packages for Claude Code, OpenAI Codex, and OpenClaw** — reusable expertise bundles that transform AI agents into specialized professionals across engineering, product, marketing, compliance, and more.
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](#skills-overview)
|
||||
[](#skills-overview)
|
||||
[](https://github.com/alirezarezvani/claude-skills/stargazers)
|
||||
[](https://getskillcheck.com)
|
||||
|
||||
@@ -31,7 +31,7 @@ Skills are modular instruction packages that give AI agents domain expertise the
|
||||
/plugin install engineering-skills@claude-code-skills # 21 core engineering
|
||||
/plugin install engineering-advanced-skills@claude-code-skills # 25 POWERFUL-tier
|
||||
/plugin install product-skills@claude-code-skills # 8 product skills
|
||||
/plugin install marketing-skills@claude-code-skills # 7 marketing skills
|
||||
/plugin install marketing-skills@claude-code-skills # 42 marketing skills
|
||||
/plugin install ra-qm-skills@claude-code-skills # 12 regulatory/quality
|
||||
/plugin install pm-skills@claude-code-skills # 6 project management
|
||||
/plugin install c-level-skills@claude-code-skills # 10 C-level advisory (full C-suite)
|
||||
@@ -78,7 +78,7 @@ git clone https://github.com/alirezarezvani/claude-skills.git
|
||||
| **🧠 Self-Improving Agent** | 5+2 | Auto-memory curation, pattern promotion, skill extraction, memory health | [engineering-team/self-improving-agent](engineering-team/self-improving-agent/) |
|
||||
| **⚡ Engineering — POWERFUL** | 25 | Agent designer, RAG architect, database designer, CI/CD builder, security auditor, MCP builder | [engineering/](engineering/) |
|
||||
| **🎯 Product** | 8 | Product manager, agile PO, strategist, UX researcher, UI design, landing pages, SaaS scaffolder | [product-team/](product-team/) |
|
||||
| **📣 Marketing** | 7 | Content creator, demand gen, PMM strategy, ASO, social media, campaign analytics, prompt engineering | [marketing-skill/](marketing-skill/) |
|
||||
| **📣 Marketing** | 42 | 7 pods: Content (8), SEO (5), CRO (6), Channels (5), Growth (4), Intelligence (4), Sales (2) + context foundation + orchestration router. 27 Python tools. | [marketing-skill/](marketing-skill/) |
|
||||
| **📋 Project Management** | 6 | Senior PM, scrum master, Jira, Confluence, Atlassian admin, templates | [project-management/](project-management/) |
|
||||
| **🏥 Regulatory & QM** | 12 | ISO 13485, MDR 2017/745, FDA, ISO 27001, GDPR, CAPA, risk management | [ra-qm-team/](ra-qm-team/) |
|
||||
| **💼 C-Level Advisory** | 28 | Full C-suite (10 roles) + orchestration + board meetings + culture & collaboration | [c-level-advisor/](c-level-advisor/) |
|
||||
|
||||
458
SKILL-AUTHORING-STANDARD.md
Normal file
458
SKILL-AUTHORING-STANDARD.md
Normal file
@@ -0,0 +1,458 @@
|
||||
# Skill Authoring Standard
|
||||
|
||||
The DNA of every skill in this repository. Follow this standard when creating new skills or upgrading existing ones.
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md Template
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: "When to use this skill. Include trigger keywords and phrases users might say. Mention related skills for disambiguation."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: domain-name
|
||||
updated: YYYY-MM-DD
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
You are an expert in [domain]. Your goal is [specific outcome for the user].
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `[domain]-context.md` exists, 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 State
|
||||
- What exists today?
|
||||
- What's working / not working?
|
||||
|
||||
### 2. Goals
|
||||
- What outcome do they want?
|
||||
- What constraints exist?
|
||||
|
||||
### 3. [Domain-Specific Context]
|
||||
- [Questions specific to this skill]
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
This skill supports [N] modes:
|
||||
|
||||
### Mode 1: Build from Scratch
|
||||
When starting fresh — no existing [artifact] to work with.
|
||||
|
||||
### Mode 2: Optimize Existing
|
||||
When improving something that already exists. Analyze what's working, identify gaps, recommend changes.
|
||||
|
||||
### Mode 3: [Situation-Specific]
|
||||
When [specific scenario that needs a different approach].
|
||||
|
||||
## [Core Content Sections]
|
||||
|
||||
[Action-oriented workflow. Not a textbook — a practitioner guiding you through it.]
|
||||
|
||||
[Tables for structured information. Checklists for processes. Examples for clarity.]
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these issues WITHOUT being asked when you notice them in context:
|
||||
|
||||
- [Trigger 1: specific condition → what to flag]
|
||||
- [Trigger 2: specific condition → what to flag]
|
||||
- [Trigger 3: specific condition → what to flag]
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| [Common request 1] | [Specific deliverable with format] |
|
||||
| [Common request 2] | [Specific deliverable with format] |
|
||||
| [Common request 3] | [Specific deliverable with format] |
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding has all three
|
||||
- **Actions have owners and deadlines** — no "we should consider"
|
||||
- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
- **skill-name**: Use when [specific scenario]. NOT for [disambiguation].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## The 10 Patterns
|
||||
|
||||
### Pattern 1: Context-First
|
||||
|
||||
Every skill checks for domain context before asking questions. Only ask for what's missing.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions.
|
||||
Use that context and only ask for information not already covered.
|
||||
```
|
||||
|
||||
**Domain context files:**
|
||||
|
||||
| Domain | Context File | Created By |
|
||||
|--------|-------------|-----------|
|
||||
| C-Suite | `company-context.md` | `/cs:setup` (cs-onboard skill) |
|
||||
| Marketing | `marketing-context.md` | marketing-context skill |
|
||||
| Engineering | `project-context.md` | codebase-onboarding skill |
|
||||
| Product | `product-context.md` | product-strategist skill |
|
||||
| RA/QM | `regulatory-context.md` | regulatory-affairs-head skill |
|
||||
|
||||
**Rules:**
|
||||
- If context exists → read it, use it, only ask for gaps
|
||||
- If context doesn't exist → offer to create it (auto-draft from available info)
|
||||
- Never dump all questions at once — conversational, one section at a time
|
||||
- Push for verbatim language — exact customer/user phrases beat polished descriptions
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Practitioner Voice
|
||||
|
||||
Every skill opens with an expert persona and clear goal. Not a textbook — a senior practitioner coaching you.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
You are an expert in [domain]. Your goal is [outcome].
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Write as someone who has done this 100 times
|
||||
- Use contractions, direct language
|
||||
- If something sounds like a Wikipedia article, rewrite it
|
||||
- Opinionated > neutral. State what works and what doesn't.
|
||||
- "Do X" beats "You might consider X"
|
||||
- Industry jargon is fine when talking to practitioners — explain when talking to founders
|
||||
|
||||
**Anti-patterns:**
|
||||
- ❌ "This skill provides comprehensive coverage of..."
|
||||
- ❌ "The following section outlines the various approaches to..."
|
||||
- ❌ "It is recommended that one should consider..."
|
||||
- ✅ "You are an expert in SaaS pricing. Your goal is to help design pricing that captures value."
|
||||
- ✅ "Lead with their world, not yours."
|
||||
- ✅ "If it sounds like marketing copy, rewrite it."
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Multi-Mode Workflows
|
||||
|
||||
Most skills have 2-3 natural entry points. Design for all of them.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Build from Scratch
|
||||
When starting fresh — [describe the greenfield scenario].
|
||||
|
||||
### Mode 2: Optimize Existing
|
||||
When [artifact] exists but isn't performing. Analyze → identify gaps → recommend.
|
||||
|
||||
### Mode 3: [Situation-Specific]
|
||||
When [edge case or specific scenario that needs a different approach].
|
||||
```
|
||||
|
||||
**Common mode pairs:**
|
||||
|
||||
| Skill Type | Mode 1 | Mode 2 | Mode 3 |
|
||||
|-----------|--------|--------|--------|
|
||||
| CRO skills | Audit a page | Redesign flow | A/B test specific element |
|
||||
| Content skills | Write new | Rewrite/optimize | Repurpose for channel |
|
||||
| SEO skills | Full audit | Fix specific issue | Competitive gap analysis |
|
||||
| Strategy skills | Create plan | Review/critique plan | Pivot existing plan |
|
||||
| Analytics skills | Set up tracking | Debug tracking | Analyze data |
|
||||
|
||||
**Rules:**
|
||||
- Mode 2 (optimize) should ask for current performance data
|
||||
- If user has performance data → use it to inform recommendations
|
||||
- Each mode should be self-contained (don't assume they read the other modes)
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: Related Skills Navigation
|
||||
|
||||
Every skill ends with a curated list of related skills. Not just links — **when to use each and when NOT to.**
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For landing page and web copy. NOT for email sequences or ad copy.
|
||||
- **page-cro**: For optimizing any marketing page. NOT for signup flows (use signup-flow-cro).
|
||||
- **email-sequence**: For lifecycle/nurture emails. NOT for cold outreach (use cold-email).
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Include 3-7 related skills (not all of them — curate)
|
||||
- Each entry: skill name + WHEN to use + WHEN NOT TO (disambiguation)
|
||||
- Cross-references must be bidirectional (A mentions B, B mentions A)
|
||||
- Include cross-domain references when relevant (e.g., marketing skill → business-growth skill)
|
||||
- Group by relationship type if >5: "Works with", "Instead of", "After this"
|
||||
|
||||
---
|
||||
|
||||
### Pattern 5: Reference Separation
|
||||
|
||||
SKILL.md is the workflow. Reference docs are the knowledge base. Keep them separate.
|
||||
|
||||
**Implementation:**
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # ≤10KB — what to do, how to decide, when to act
|
||||
├── references/
|
||||
│ ├── frameworks.md # Deep framework catalog
|
||||
│ ├── benchmarks.md # Industry data and benchmarks
|
||||
│ ├── platform-specs.md # Platform-specific details
|
||||
│ └── examples.md # Real-world examples
|
||||
├── templates/
|
||||
│ └── template.md # User-fillable templates
|
||||
└── scripts/
|
||||
└── tool.py # Python automation
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- SKILL.md ≤10KB — if it's longer, move content to references
|
||||
- SKILL.md links to references inline: `See [references/frameworks.md](references/frameworks.md) for the full catalog.`
|
||||
- References are loaded on demand — zero startup cost
|
||||
- Each reference doc is self-contained (can be read independently)
|
||||
- Templates are user-fillable files with clear placeholder markers
|
||||
|
||||
---
|
||||
|
||||
### Pattern 6: Proactive Triggers
|
||||
|
||||
Skills surface issues without being asked when they detect patterns in context.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **[Condition]** → [What to flag and why]
|
||||
- **[Condition]** → [What to flag and why]
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- 4-6 triggers per skill
|
||||
- Each trigger: specific condition + business consequence
|
||||
- Triggers should be things the user wouldn't think to ask about
|
||||
- Format: condition → flag → recommended action
|
||||
- Don't trigger on obvious things — trigger on hidden risks
|
||||
|
||||
**Examples:**
|
||||
- SEO: "Keyword cannibalization detected — two pages targeting the same term" → flag
|
||||
- Pricing: "Conversion rate >40% — likely underpriced" → flag
|
||||
- Content: "No content updated in 6+ months" → flag
|
||||
- CRO: "Form has >7 fields with no multi-step" → flag
|
||||
|
||||
---
|
||||
|
||||
### Pattern 7: Output Artifacts
|
||||
|
||||
Map common requests to specific, concrete deliverables.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| "Help with pricing" | Pricing recommendation with tier structure, value metrics, and competitive positioning |
|
||||
| "Audit my SEO" | SEO scorecard (0-100) with prioritized fixes and quick wins |
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- 4-6 artifacts per skill
|
||||
- Each artifact has a specific format (scorecard, matrix, plan, audit, template)
|
||||
- Artifacts are actionable — not just analysis, but recommendations with next steps
|
||||
- Include what the output looks like (table? checklist? narrative?)
|
||||
|
||||
---
|
||||
|
||||
### Pattern 8: Quality Loop
|
||||
|
||||
Skills self-verify before presenting findings.
|
||||
|
||||
**Implementation:**
|
||||
```markdown
|
||||
## Communication
|
||||
|
||||
All output passes quality verification:
|
||||
- Self-verify: source attribution, assumption audit, confidence scoring
|
||||
- Peer-verify: cross-functional claims validated by the owning skill
|
||||
- Output format: Bottom Line → What (with confidence) → Why → How to Act → Your Decision
|
||||
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Every finding tagged with confidence level
|
||||
- Assumptions explicitly marked as assumptions
|
||||
- "I don't know" > fake confidence
|
||||
- Cross-functional claims reference the relevant skill
|
||||
- High-stakes recommendations get extra scrutiny
|
||||
|
||||
---
|
||||
|
||||
### Pattern 9: Communication Standard
|
||||
|
||||
Structured output format for all skill output.
|
||||
|
||||
**Standard output:**
|
||||
```
|
||||
BOTTOM LINE: [One sentence answer]
|
||||
|
||||
WHAT:
|
||||
• [Finding 1] — 🟢/🟡/🔴
|
||||
• [Finding 2] — 🟢/🟡/🔴
|
||||
|
||||
WHY THIS MATTERS: [Business impact]
|
||||
|
||||
HOW TO ACT:
|
||||
1. [Action] → [Owner] → [Deadline]
|
||||
|
||||
YOUR DECISION (if needed):
|
||||
Option A: [Description] — [Trade-off]
|
||||
Option B: [Description] — [Trade-off]
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Bottom line first — always
|
||||
- Max 5 bullets per section
|
||||
- Actions have owners and deadlines
|
||||
- Decisions framed as options with trade-offs
|
||||
- No process narration ("First I analyzed...") — results only
|
||||
|
||||
---
|
||||
|
||||
### Pattern 10: Python Tools
|
||||
|
||||
Stdlib-only automation that provides quantitative analysis.
|
||||
|
||||
**Implementation:**
|
||||
```python
|
||||
#!/usr/bin/env python3
|
||||
"""Tool description — what it does in one line."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
from collections import Counter
|
||||
|
||||
def main():
|
||||
# Accept input from file arg or stdin
|
||||
# Process with stdlib only
|
||||
# Output JSON for programmatic use
|
||||
# Also print human-readable summary
|
||||
pass
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- **stdlib-only** — zero external dependencies (no pip install)
|
||||
- **CLI-first** — run from command line with file args or stdin
|
||||
- **JSON output** — structured output for integration
|
||||
- **Sample data embedded** — runs with zero config for demo/testing
|
||||
- **One tool, one job** — focused, not Swiss Army knife
|
||||
- **Scoring tools output 0-100** — consistent scale across all tools
|
||||
|
||||
**Naming convention:** `snake_case_verb_noun.py` (e.g., `seo_checker.py`, `headline_scorer.py`, `churn_risk_scorer.py`)
|
||||
|
||||
---
|
||||
|
||||
## File Structure Standard
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md # ≤10KB — workflow, decisions, actions
|
||||
├── references/ # Deep knowledge (loaded on demand)
|
||||
│ ├── [topic]-guide.md # Comprehensive guide
|
||||
│ ├── [topic]-benchmarks.md # Industry data
|
||||
│ └── [topic]-examples.md # Real-world examples
|
||||
├── templates/ # User-fillable templates
|
||||
│ └── [artifact]-template.md # With placeholder markers
|
||||
└── scripts/ # Python automation
|
||||
└── [verb]_[noun].py # Stdlib-only, CLI-first
|
||||
```
|
||||
|
||||
**Naming rules:**
|
||||
- Skill folder: `kebab-case`
|
||||
- Python scripts: `snake_case.py`
|
||||
- Reference docs: `kebab-case.md`
|
||||
- Templates: `kebab-case-template.md`
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before a skill is considered done:
|
||||
|
||||
### Structure
|
||||
- [ ] YAML frontmatter with name, description (trigger keywords), version
|
||||
- [ ] Practitioner voice — "You are an expert in X. Your goal is Y."
|
||||
- [ ] Context-first — checks domain context before asking questions
|
||||
- [ ] Multi-mode — at least 2 workflows (build/optimize)
|
||||
- [ ] SKILL.md ≤10KB — heavy content in references/
|
||||
|
||||
### Content
|
||||
- [ ] Action-oriented — tells you what to do, not just what exists
|
||||
- [ ] Opinionated — states what works, not just options
|
||||
- [ ] Tables for structured comparisons
|
||||
- [ ] Checklists for processes
|
||||
- [ ] Examples for clarity
|
||||
|
||||
### Integration
|
||||
- [ ] Related Skills section with WHEN/NOT disambiguation
|
||||
- [ ] Cross-references are bidirectional
|
||||
- [ ] Listed in domain CLAUDE.md
|
||||
- [ ] Listed in `.codex/skills-index.json`
|
||||
- [ ] Listed in `.claude-plugin/marketplace.json`
|
||||
|
||||
### Quality Standard
|
||||
- [ ] Proactive Triggers (4-6 per skill)
|
||||
- [ ] Output Artifacts table (4-6 per skill)
|
||||
- [ ] Communication standard reference
|
||||
- [ ] Confidence tagging on findings
|
||||
|
||||
### Automation (if applicable)
|
||||
- [ ] Python tool(s) — stdlib-only, CLI-first, JSON output
|
||||
- [ ] Sample data embedded — runs with zero config
|
||||
- [ ] Scoring uses 0-100 scale
|
||||
|
||||
---
|
||||
|
||||
## Domain Context Files
|
||||
|
||||
| Domain | File | Sections |
|
||||
|--------|------|----------|
|
||||
| **C-Suite** | `company-context.md` | Stage, team, burn rate, competitive landscape, strategic priorities |
|
||||
| **Marketing** | `marketing-context.md` | Brand voice, style guide, target keywords, internal links map, competitor analysis, audience personas, writing examples, customer language |
|
||||
| **Engineering** | `project-context.md` | Tech stack, architecture, conventions, CI/CD, testing strategy |
|
||||
| **Product** | `product-context.md` | Roadmap, personas, metrics, feature priorities, user research |
|
||||
| **RA/QM** | `regulatory-context.md` | Device classification, applicable standards, audit schedule, SOUP list |
|
||||
|
||||
Each domain's context skill creates this file via guided interview + auto-draft from available information.
|
||||
|
||||
---
|
||||
|
||||
*This standard applies to all new skills and skill upgrades across the entire repository.*
|
||||
*Version: 1.0.0 | Created: 2026-03-06*
|
||||
42
marketing-skill/.codex/instructions.md
Normal file
42
marketing-skill/.codex/instructions.md
Normal file
@@ -0,0 +1,42 @@
|
||||
# Marketing Skills — Codex CLI Instructions
|
||||
|
||||
When working on marketing tasks, use the marketing skill system:
|
||||
|
||||
## Routing
|
||||
|
||||
1. **First**, read `marketing-skill/marketing-ops/SKILL.md` to identify the right specialist skill
|
||||
2. **Then**, read the specialist skill's SKILL.md for detailed instructions
|
||||
3. **If this is a first-time user**, recommend running `marketing-context` first
|
||||
|
||||
## Context
|
||||
|
||||
If `marketing-context.md` exists in the project root, read it before any marketing task. It contains brand voice, audience personas, and competitive landscape.
|
||||
|
||||
## Python Tools
|
||||
|
||||
All scripts in `marketing-skill/*/scripts/` are stdlib-only and CLI-first. Run them directly:
|
||||
|
||||
```bash
|
||||
python3 marketing-skill/content-production/scripts/content_scorer.py <file>
|
||||
python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py <file>
|
||||
python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py <file>
|
||||
```
|
||||
|
||||
## Key Skills by Task
|
||||
|
||||
| Task | Skill |
|
||||
|------|-------|
|
||||
| Write content | content-production |
|
||||
| Plan content | content-strategy |
|
||||
| SEO audit | seo-audit |
|
||||
| AI search optimization | ai-seo |
|
||||
| Page conversion | page-cro |
|
||||
| Email sequences | email-sequence |
|
||||
| Pricing | pricing-strategy |
|
||||
| Launch planning | launch-strategy |
|
||||
|
||||
## Rules
|
||||
|
||||
- Never load all 42 skills at once — route to 1-2 per request
|
||||
- Check marketing-context.md before starting
|
||||
- Use Python tools for scoring and validation, not manual judgment
|
||||
@@ -1,334 +1,38 @@
|
||||
# Marketing Skills - Claude Code Guidance
|
||||
# Marketing Skills — Agent Instructions
|
||||
|
||||
This guide covers the 4 production-ready marketing skills and their Python automation tools.
|
||||
## For All Agents (Claude Code, Codex CLI, OpenClaw)
|
||||
|
||||
## Marketing Skills Overview
|
||||
This directory contains 42 marketing skills organized into specialist pods.
|
||||
|
||||
**Available Skills:**
|
||||
1. **content-creator/** - Content creation, brand voice, SEO optimization (2 Python tools)
|
||||
2. **marketing-demand-acquisition/** - Demand generation and customer acquisition (1 Python tool)
|
||||
3. **marketing-strategy-pmm/** - Product marketing and go-to-market strategy
|
||||
4. **campaign-analytics/** - Multi-touch attribution, funnel conversion analysis, campaign ROI calculation (3 Python tools)
|
||||
### How to Use
|
||||
|
||||
**Total Tools:** 6 Python automation tools, 9+ knowledge bases, 15+ templates
|
||||
1. **Start with routing:** Read `marketing-ops/SKILL.md` — it has a routing matrix that maps user requests to the right skill.
|
||||
2. **Check context:** If `marketing-context.md` exists, read it first. It has brand voice, personas, and competitive landscape.
|
||||
3. **Load ONE skill:** Read only the specialist SKILL.md you need. Never bulk-load.
|
||||
|
||||
## Python Automation Tools
|
||||
### Skill Map
|
||||
|
||||
### 1. Brand Voice Analyzer (`content-creator/scripts/brand_voice_analyzer.py`)
|
||||
- `marketing-context/` — Run first to capture brand context
|
||||
- `marketing-ops/` — Router (read this to know where to go)
|
||||
- `content-production/` — Write content (blog posts, articles, guides)
|
||||
- `content-strategy/` — Plan what content to create
|
||||
- `ai-seo/` — Optimize for AI search engines (ChatGPT, Perplexity, Google AI)
|
||||
- `seo-audit/` — Traditional SEO audit
|
||||
- `page-cro/` — Conversion rate optimization
|
||||
- `pricing-strategy/` — Pricing and packaging
|
||||
- `content-humanizer/` — Fix AI-sounding content
|
||||
|
||||
**Purpose:** Analyzes text for formality, tone, perspective, and readability
|
||||
### Python Tools
|
||||
|
||||
**Features:**
|
||||
- Formality analysis (formal vs casual language patterns)
|
||||
- Tone detection (professional, conversational, technical)
|
||||
- Perspective analysis (1st person, 2nd person, 3rd person)
|
||||
- Readability scoring (Flesch Reading Ease formula)
|
||||
- Output formats: JSON or human-readable
|
||||
|
||||
**Usage:**
|
||||
27 scripts, all stdlib-only. Run directly:
|
||||
```bash
|
||||
# Basic analysis
|
||||
python content-creator/scripts/brand_voice_analyzer.py content.txt
|
||||
|
||||
# JSON output for integrations
|
||||
python content-creator/scripts/brand_voice_analyzer.py content.txt json
|
||||
python3 <skill>/scripts/<tool>.py [args]
|
||||
```
|
||||
No pip install needed. Scripts include embedded samples for demo mode (run with no args).
|
||||
|
||||
**Output Example:**
|
||||
```
|
||||
Brand Voice Analysis Results:
|
||||
- Formality Score: 65/100 (Semi-formal)
|
||||
- Tone: Professional with conversational elements
|
||||
- Perspective: 2nd person (you-focused)
|
||||
- Readability: 72 (College level)
|
||||
```
|
||||
### Anti-Patterns
|
||||
|
||||
**Implementation Notes:**
|
||||
- Pure Python (standard library only)
|
||||
- No external API calls or ML models
|
||||
- Fast local processing (<1 second for typical content)
|
||||
- Works offline
|
||||
|
||||
### 2. SEO Optimizer (`content-creator/scripts/seo_optimizer.py`)
|
||||
|
||||
**Purpose:** Comprehensive SEO analysis with actionable recommendations
|
||||
|
||||
**Features:**
|
||||
- Keyword density analysis (primary + secondary keywords)
|
||||
- Content structure evaluation (headings, paragraphs, lists)
|
||||
- Meta tag validation (title, description)
|
||||
- Readability assessment
|
||||
- SEO score calculation (0-100)
|
||||
- Actionable improvement recommendations
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
# Basic SEO analysis
|
||||
python content-creator/scripts/seo_optimizer.py article.md "primary keyword"
|
||||
|
||||
# With secondary keywords
|
||||
python content-creator/scripts/seo_optimizer.py article.md "primary keyword" "secondary,keywords,here"
|
||||
|
||||
# JSON output
|
||||
python content-creator/scripts/seo_optimizer.py article.md "keyword" --json
|
||||
```
|
||||
|
||||
**Output Example:**
|
||||
```
|
||||
SEO Analysis Results:
|
||||
- Overall SEO Score: 78/100
|
||||
- Primary Keyword Density: 1.8% (target: 1-2%)
|
||||
- Secondary Keyword Usage: 5/7 keywords present
|
||||
- Content Structure: Good (H2, H3 hierarchy)
|
||||
- Meta Description: Present (145 chars)
|
||||
|
||||
Recommendations:
|
||||
1. Add primary keyword to H2 heading
|
||||
2. Increase secondary keyword "conversion" usage
|
||||
3. Add alt text to 2 images
|
||||
```
|
||||
|
||||
**Implementation Notes:**
|
||||
- 419 lines of pure algorithmic analysis
|
||||
- No LLM calls or external APIs
|
||||
- CLI-first design for automation
|
||||
- Supports markdown and HTML input
|
||||
|
||||
### 3. Demand Generation Analyzer (`marketing-demand-acquisition/scripts/`)
|
||||
|
||||
**Purpose:** Analyze demand generation campaigns and acquisition funnels
|
||||
|
||||
**Features:**
|
||||
- Campaign performance analysis
|
||||
- Acquisition channel evaluation
|
||||
- Conversion funnel metrics
|
||||
- ROI calculation
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python marketing-demand-acquisition/scripts/demand_gen_analyzer.py campaign-data.csv
|
||||
```
|
||||
|
||||
### Campaign Analytics Tools
|
||||
|
||||
#### 4. Attribution Analyzer (`campaign-analytics/scripts/attribution_analyzer.py`)
|
||||
|
||||
**Purpose:** Multi-touch attribution modeling across marketing channels
|
||||
|
||||
**Features:**
|
||||
- Five attribution models (first-touch, last-touch, linear, time-decay, position-based)
|
||||
- Configurable time-decay half-life
|
||||
- Per-channel credit allocation and revenue attribution
|
||||
- Conversion and non-conversion journey analysis
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python campaign-analytics/scripts/attribution_analyzer.py campaign_data.json
|
||||
python campaign-analytics/scripts/attribution_analyzer.py campaign_data.json --model time-decay --half-life 14
|
||||
python campaign-analytics/scripts/attribution_analyzer.py campaign_data.json --format json
|
||||
```
|
||||
|
||||
#### 5. Funnel Analyzer (`campaign-analytics/scripts/funnel_analyzer.py`)
|
||||
|
||||
**Purpose:** Conversion funnel analysis with bottleneck detection
|
||||
|
||||
**Features:**
|
||||
- Stage-to-stage conversion rates and drop-off percentages
|
||||
- Automatic bottleneck identification (largest absolute and relative drops)
|
||||
- Overall funnel conversion rate
|
||||
- Segment comparison when multiple segments provided
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python campaign-analytics/scripts/funnel_analyzer.py funnel_data.json
|
||||
python campaign-analytics/scripts/funnel_analyzer.py funnel_data.json --format json
|
||||
```
|
||||
|
||||
#### 6. Campaign ROI Calculator (`campaign-analytics/scripts/campaign_roi_calculator.py`)
|
||||
|
||||
**Purpose:** Calculate comprehensive campaign ROI metrics with benchmarking
|
||||
|
||||
**Features:**
|
||||
- ROI, ROAS, CPA, CPL, CAC calculation
|
||||
- CTR and conversion rate metrics
|
||||
- Industry benchmark comparison
|
||||
- Underperformance flagging
|
||||
|
||||
**Usage:**
|
||||
```bash
|
||||
python campaign-analytics/scripts/campaign_roi_calculator.py campaign_data.json
|
||||
python campaign-analytics/scripts/campaign_roi_calculator.py campaign_data.json --format json
|
||||
```
|
||||
|
||||
## Knowledge Bases
|
||||
|
||||
### Content Creator References
|
||||
|
||||
**Location:** `content-creator/references/`
|
||||
|
||||
1. **brand_guidelines.md** - Brand voice framework
|
||||
- 5 personality archetypes (Expert, Friend, Innovator, Guide, Motivator)
|
||||
- Voice characteristics matrix
|
||||
- Brand consistency checklist
|
||||
- Industry-specific adaptations
|
||||
|
||||
2. **content_frameworks.md** - 15+ content templates
|
||||
- Blog post structures (how-to, listicle, case study)
|
||||
- Email campaign frameworks
|
||||
- Social media content patterns
|
||||
- Video script templates
|
||||
- Landing page copy structure
|
||||
|
||||
3. **social_media_optimization.md** - Platform-specific best practices
|
||||
- LinkedIn: Professional tone, 1,300 chars, hashtag strategy
|
||||
- Twitter/X: Concise, 280 chars, thread patterns
|
||||
- Instagram: Visual-first, captions, hashtag limits
|
||||
- Facebook: Conversational, engagement tactics
|
||||
- TikTok: Short-form video, trending sounds
|
||||
|
||||
### Campaign Analytics References
|
||||
|
||||
**Location:** `campaign-analytics/references/`
|
||||
|
||||
1. **attribution-models-guide.md** - Deep dive into 5 attribution models with formulas, pros/cons, selection criteria
|
||||
2. **campaign-metrics-benchmarks.md** - Industry benchmarks by channel and vertical for CTR, CPC, CPM, CPA, ROAS
|
||||
3. **funnel-optimization-framework.md** - Stage-by-stage optimization strategies, common bottlenecks, best practices
|
||||
|
||||
## User Templates
|
||||
|
||||
### Content Creator Assets
|
||||
|
||||
**Location:** `content-creator/assets/`
|
||||
|
||||
- Content calendar template
|
||||
- SEO checklist
|
||||
- Social media posting schedule
|
||||
- Content brief template
|
||||
- Campaign planning worksheet
|
||||
|
||||
**Usage:** Copy template and customize for your needs
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### Pattern 1: Content Quality Workflow
|
||||
|
||||
```bash
|
||||
# 1. Create draft content
|
||||
vim blog-post.md
|
||||
|
||||
# 2. Analyze brand voice
|
||||
python content-creator/scripts/brand_voice_analyzer.py blog-post.md
|
||||
|
||||
# 3. Optimize for SEO
|
||||
python content-creator/scripts/seo_optimizer.py blog-post.md "target keyword"
|
||||
|
||||
# 4. Refine based on feedback
|
||||
|
||||
# 5. Publish
|
||||
```
|
||||
|
||||
### Pattern 2: Campaign Planning
|
||||
|
||||
```bash
|
||||
# 1. Reference frameworks
|
||||
cat content-creator/references/content_frameworks.md
|
||||
|
||||
# 2. Draft campaign content
|
||||
|
||||
# 3. Validate against brand guidelines
|
||||
cat content-creator/references/brand_guidelines.md
|
||||
|
||||
# 4. Analyze performance
|
||||
python marketing-demand-acquisition/scripts/demand_gen_analyzer.py campaign-results.csv
|
||||
```
|
||||
|
||||
### Pattern 3: Campaign Performance Analysis
|
||||
|
||||
```bash
|
||||
# 1. Analyze multi-touch attribution
|
||||
python campaign-analytics/scripts/attribution_analyzer.py journey_data.json
|
||||
|
||||
# 2. Identify funnel bottlenecks
|
||||
python campaign-analytics/scripts/funnel_analyzer.py funnel_data.json
|
||||
|
||||
# 3. Calculate campaign ROI
|
||||
python campaign-analytics/scripts/campaign_roi_calculator.py campaign_data.json
|
||||
|
||||
# 4. Document findings using templates
|
||||
# Reference: campaign-analytics/assets/campaign_report_template.md
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
```bash
|
||||
# Content analysis
|
||||
python content-creator/scripts/brand_voice_analyzer.py content.txt
|
||||
python content-creator/scripts/brand_voice_analyzer.py content.txt json
|
||||
|
||||
# SEO optimization
|
||||
python content-creator/scripts/seo_optimizer.py article.md "main keyword"
|
||||
python content-creator/scripts/seo_optimizer.py article.md "main keyword" "secondary,keywords"
|
||||
|
||||
# Demand generation
|
||||
python marketing-demand-acquisition/scripts/demand_gen_analyzer.py data.csv
|
||||
|
||||
# Campaign analytics
|
||||
python campaign-analytics/scripts/attribution_analyzer.py campaign_data.json
|
||||
python campaign-analytics/scripts/funnel_analyzer.py funnel_data.json
|
||||
python campaign-analytics/scripts/campaign_roi_calculator.py campaign_data.json
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
**All marketing Python tools must:**
|
||||
- Use standard library only (no external dependencies)
|
||||
- Support both JSON and human-readable output
|
||||
- Provide clear error messages
|
||||
- Return appropriate exit codes
|
||||
- Process files locally (no API calls)
|
||||
|
||||
## Roadmap
|
||||
|
||||
**Current (Phase 1-2):** 4 skills deployed
|
||||
- ✅ Content creator (brand voice + SEO)
|
||||
- ✅ Demand generation & acquisition
|
||||
- ✅ Product marketing strategy
|
||||
- ✅ Campaign analytics (attribution, funnel, ROI)
|
||||
|
||||
**Phase 3 (Q2 2026):** Marketing expansion
|
||||
- SEO content optimizer (advanced)
|
||||
- Social media manager (multi-platform)
|
||||
- Email marketing automation
|
||||
|
||||
**Phase 4 (Q3 2026):** Growth marketing
|
||||
- Growth hacking frameworks
|
||||
- Viral content analyzer
|
||||
- Influencer collaboration tools
|
||||
|
||||
See `marketing_skills_roadmap.md` for detailed expansion plans.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **Product Team:** User research, persona generation → `../product-team/`
|
||||
- **Engineering:** Web analytics integration → `../engineering-team/`
|
||||
- **C-Level:** Strategic marketing planning → `../c-level-advisor/`
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Brand Consistency** - Always reference brand_guidelines.md before creating content
|
||||
2. **SEO-First** - Run seo_optimizer.py on all published content
|
||||
3. **Data-Driven** - Use analytics to inform content strategy
|
||||
4. **Platform-Specific** - Adapt content using social_media_optimization.md guidelines
|
||||
5. **Iterative** - Analyze, optimize, republish
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- **Marketing Roadmap:** `marketing_skills_roadmap.md`
|
||||
- **Team Overview:** `README.md`
|
||||
- **Main Documentation:** `../CLAUDE.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** February 2026
|
||||
**Skills Deployed:** 4/4 marketing skills production-ready
|
||||
**Total Tools:** 6 Python automation tools
|
||||
❌ Don't read all 42 SKILL.md files
|
||||
❌ Don't skip marketing-context.md if it exists
|
||||
❌ Don't use content-creator (deprecated → use content-production)
|
||||
❌ Don't install pip packages for Python tools
|
||||
|
||||
334
marketing-skill/MARKETING-EXECUTION-PLAN.md
Normal file
334
marketing-skill/MARKETING-EXECUTION-PLAN.md
Normal file
@@ -0,0 +1,334 @@
|
||||
# Marketing Team Expansion — Execution Plan
|
||||
|
||||
## Final Architecture
|
||||
|
||||
```
|
||||
CMO Advisor (c-level-advisor/cmo-advisor/)
|
||||
│
|
||||
│ reads company-context.md + marketing-context.md
|
||||
│
|
||||
Marketing Ops (router + orchestrator)
|
||||
│
|
||||
├── Content Pod (8)
|
||||
│ ├── content-creator .......... [UPGRADE] add context integration, quality loop
|
||||
│ ├── content-strategy ......... [IMPORT] from workspace
|
||||
│ ├── copywriting .............. [IMPORT] from workspace
|
||||
│ ├── copy-editing ............. [IMPORT] from workspace
|
||||
│ ├── social-content ........... [IMPORT] from workspace
|
||||
│ ├── marketing-ideas .......... [IMPORT] from workspace
|
||||
│ ├── content-production ....... [NEW] research→write→optimize pipeline
|
||||
│ └── content-humanizer ........ [NEW] AI watermark removal, voice injection
|
||||
│
|
||||
├── SEO Pod (5)
|
||||
│ ├── seo-audit ................ [IMPORT] from workspace + add seo_checker.py
|
||||
│ ├── programmatic-seo ......... [IMPORT] from workspace
|
||||
│ ├── ai-seo ................... [NEW] AEO, GEO, LLMO optimization
|
||||
│ ├── schema-markup ............ [NEW] JSON-LD, structured data
|
||||
│ └── site-architecture ........ [NEW] URL structure, nav, internal linking
|
||||
│
|
||||
├── CRO Pod (6)
|
||||
│ ├── page-cro ................. [IMPORT] from workspace
|
||||
│ ├── form-cro ................. [IMPORT] from workspace
|
||||
│ ├── signup-flow-cro .......... [IMPORT] from workspace
|
||||
│ ├── onboarding-cro ........... [IMPORT] from workspace
|
||||
│ ├── popup-cro ................ [IMPORT] from workspace
|
||||
│ └── paywall-upgrade-cro ...... [IMPORT] from workspace
|
||||
│
|
||||
├── Channels Pod (5)
|
||||
│ ├── email-sequence ........... [IMPORT] from workspace
|
||||
│ ├── paid-ads ................. [IMPORT] from workspace
|
||||
│ ├── social-media-manager ..... [UPGRADE] rename + expand from social-media-analyzer
|
||||
│ ├── cold-email ............... [NEW] B2B outreach sequences
|
||||
│ └── ad-creative .............. [NEW] bulk ad generation + iteration
|
||||
│
|
||||
├── Growth Pod (3)
|
||||
│ ├── ab-test-setup ............ [IMPORT] from workspace
|
||||
│ ├── referral-program ......... [NEW] referral + affiliate programs
|
||||
│ └── free-tool-strategy ....... [NEW] engineering as marketing
|
||||
│
|
||||
├── Intelligence Pod (4)
|
||||
│ ├── campaign-analytics ....... [UPGRADE] add cross-channel synthesis
|
||||
│ ├── competitor-alternatives .. [IMPORT] from workspace
|
||||
│ ├── marketing-psychology ..... [IMPORT] from workspace
|
||||
│ └── analytics-tracking ....... [NEW] GA4, GTM, event tracking setup
|
||||
│
|
||||
└── Sales & GTM Pod (2)
|
||||
├── launch-strategy .......... [IMPORT] from workspace
|
||||
└── pricing-strategy ......... [NEW] pricing, packaging, monetization
|
||||
|
||||
Standalone (keep in place, no pod):
|
||||
├── marketing-demand-acquisition . [KEEP] already in repo
|
||||
├── marketing-strategy-pmm ....... [KEEP] already in repo
|
||||
├── app-store-optimization ....... [KEEP] already in repo
|
||||
└── prompt-engineer-toolkit ...... [KEEP] already in repo
|
||||
|
||||
Cross-Domain References (marketing-ops routes to these):
|
||||
├── business-growth/revenue-operations/ (RevOps)
|
||||
├── business-growth/sales-engineer/ (Sales Enablement)
|
||||
├── business-growth/customer-success-manager/ (Churn Prevention)
|
||||
├── product-team/landing-page-generator/ (Landing Pages)
|
||||
├── product-team/competitive-teardown/ (Competitive Analysis)
|
||||
└── engineering-team/email-template-builder/ (Email Templates)
|
||||
```
|
||||
|
||||
## Totals
|
||||
|
||||
| Action | Count |
|
||||
|--------|-------|
|
||||
| Import from workspace | 20 |
|
||||
| Upgrade existing | 3 |
|
||||
| Build new | 13 |
|
||||
| Keep as-is | 4 |
|
||||
| Cross-domain refs | 6 |
|
||||
| **Total marketing skills** | **39** |
|
||||
| **New Python tools** | ~20 |
|
||||
| **New reference docs** | ~25 |
|
||||
| **New agents** | 5-8 |
|
||||
|
||||
---
|
||||
|
||||
## Iteration 1: Foundation + Import (20 workspace skills + 2 new)
|
||||
|
||||
### 1A: Create branch and foundation skills
|
||||
|
||||
**marketing-context/** (NEW — the foundation every skill reads)
|
||||
```
|
||||
marketing-context/
|
||||
├── SKILL.md # How to use, interview flow
|
||||
├── templates/
|
||||
│ ├── brand-voice.md # Voice pillars, tone by content type, terminology
|
||||
│ ├── style-guide.md # Grammar, formatting, capitalization
|
||||
│ ├── target-keywords.md # Keyword clusters, search intent, current rankings
|
||||
│ ├── internal-links-map.md # Key pages, anchor text, topic clusters
|
||||
│ ├── competitor-analysis.md # Primary competitors, strategies, gaps
|
||||
│ ├── writing-examples.md # 3-5 exemplary pieces with annotations
|
||||
│ └── audience-personas.md # ICP, segments, pain points, buying triggers
|
||||
└── scripts/
|
||||
└── context_validator.py # Validates completeness of context files
|
||||
```
|
||||
Inspired by: SEO Machine's 8 context files + marketingskills' product-marketing-context
|
||||
Key difference: Templates (user fills in), not static files. Validator script checks completeness.
|
||||
|
||||
**marketing-ops/** (NEW — the router)
|
||||
```
|
||||
marketing-ops/
|
||||
├── SKILL.md # Router logic, pod assignments, escalation
|
||||
├── references/
|
||||
│ ├── routing-matrix.md # Trigger keywords → skill mapping (all 39 + 6 cross-domain)
|
||||
│ ├── campaign-workflow.md # End-to-end campaign orchestration steps
|
||||
│ └── quality-checklist.md # Pre-delivery quality gate (mirrors C-Suite standard)
|
||||
└── scripts/
|
||||
└── campaign_tracker.py # Track campaign status, tasks, owners, deadlines
|
||||
```
|
||||
|
||||
### 1B: Import 20 workspace skills
|
||||
|
||||
For each imported skill:
|
||||
1. Copy from `~/.openclaw/workspace/skills/{name}/` to `marketing-skill/{name}/`
|
||||
2. Verify YAML frontmatter (name, description, license, metadata)
|
||||
3. Add `## Related Skills` section with cross-references
|
||||
4. Add `## Integration` table (which pod, which skills it works with, cross-domain refs)
|
||||
5. Add `## Communication` section (references marketing quality standard)
|
||||
|
||||
**Import batch (parallel — 4 subagents):**
|
||||
|
||||
| Subagent | Skills | Pod |
|
||||
|----------|--------|-----|
|
||||
| content-importer | content-strategy, copywriting, copy-editing, social-content, marketing-ideas | Content |
|
||||
| seo-cro-importer | seo-audit, programmatic-seo, page-cro, form-cro, signup-flow-cro | SEO + CRO |
|
||||
| cro-channel-importer | onboarding-cro, popup-cro, paywall-upgrade-cro, email-sequence, paid-ads | CRO + Channels |
|
||||
| growth-intel-importer | ab-test-setup, competitor-alternatives, marketing-psychology, launch-strategy, brand-guidelines | Growth + Intel + GTM |
|
||||
|
||||
Each subagent:
|
||||
- Copies skill folder
|
||||
- Adds Related Skills section
|
||||
- Adds Integration table
|
||||
- Adds Communication standard reference
|
||||
- Standardizes YAML frontmatter
|
||||
- Does NOT add Python tools yet (that's Iteration 3)
|
||||
|
||||
### 1C: Upgrade 3 existing skills
|
||||
|
||||
| Skill | Changes |
|
||||
|-------|---------|
|
||||
| content-creator | Add context integration (reads marketing-context), Related Skills, Communication standard |
|
||||
| social-media-analyzer → social-media-manager | Rename, expand SKILL.md from analyzer to full manager (scheduling, strategy, community) |
|
||||
| campaign-analytics | Add cross-channel synthesis section, Related Skills, Communication standard |
|
||||
|
||||
### 1D: Update CLAUDE.md + marketplace + skills-index
|
||||
|
||||
- Rewrite `marketing-skill/CLAUDE.md` (like we did for C-Suite)
|
||||
- Update `.claude-plugin/marketplace.json`
|
||||
- Update `.codex/skills-index.json`
|
||||
- Update root `CLAUDE.md` skill counts
|
||||
- Update `README.md` badge + counts
|
||||
|
||||
### Iteration 1 Deliverables
|
||||
- [ ] Branch `feat/marketing-expansion`
|
||||
- [ ] marketing-context/ (foundation)
|
||||
- [ ] marketing-ops/ (router)
|
||||
- [ ] 20 imported skills (standardized)
|
||||
- [ ] 3 upgraded skills
|
||||
- [ ] Updated CLAUDE.md, marketplace, skills-index
|
||||
- [ ] PR opened
|
||||
|
||||
---
|
||||
|
||||
## Iteration 2: Build 13 New Skills (parallel subagents)
|
||||
|
||||
### 2A: Content + SEO batch (5 skills — 2 subagents)
|
||||
|
||||
**Subagent: content-builder**
|
||||
| Skill | Key Deliverables |
|
||||
|-------|-----------------|
|
||||
| content-production | SKILL.md, references/production-pipeline.md, references/content-brief-template.md, scripts/content_scorer.py (readability + SEO + humanity score), scripts/outline_generator.py |
|
||||
| content-humanizer | SKILL.md, references/ai-patterns-checklist.md, references/voice-injection-guide.md, scripts/humanizer_scorer.py (detect AI patterns: em-dashes, filler, passive, hedging) |
|
||||
|
||||
**Subagent: seo-builder**
|
||||
| Skill | Key Deliverables |
|
||||
|-------|-----------------|
|
||||
| ai-seo | SKILL.md, references/aeo-guide.md (answer engine optimization), references/llm-citation-tactics.md, references/ai-search-landscape.md |
|
||||
| schema-markup | SKILL.md, references/schema-types-guide.md, references/implementation-patterns.md, scripts/schema_validator.py (validates JSON-LD) |
|
||||
| site-architecture | SKILL.md, references/url-structure-guide.md, references/internal-linking-strategy.md, scripts/sitemap_analyzer.py |
|
||||
|
||||
### 2B: Channels + Growth batch (4 skills — 2 subagents)
|
||||
|
||||
**Subagent: channels-builder**
|
||||
| Skill | Key Deliverables |
|
||||
|-------|-----------------|
|
||||
| cold-email | SKILL.md, references/outreach-frameworks.md (AIDA, PAS, BAB), references/deliverability-guide.md, templates/sequence-templates.md, scripts/email_sequence_analyzer.py |
|
||||
| ad-creative | SKILL.md, references/ad-frameworks.md (by platform), references/creative-testing-guide.md, scripts/headline_scorer.py, scripts/ad_copy_generator.py |
|
||||
|
||||
**Subagent: growth-builder**
|
||||
| Skill | Key Deliverables |
|
||||
|-------|-----------------|
|
||||
| referral-program | SKILL.md, references/referral-mechanics.md, references/program-types.md (one-sided, two-sided, tiered), scripts/referral_roi_calculator.py |
|
||||
| free-tool-strategy | SKILL.md, references/tool-types.md (calculators, generators, analyzers, checkers), references/build-vs-buy.md, scripts/tool_roi_estimator.py |
|
||||
|
||||
### 2C: Intelligence + Sales batch (4 skills — 2 subagents)
|
||||
|
||||
**Subagent: intel-builder**
|
||||
| Skill | Key Deliverables |
|
||||
|-------|-----------------|
|
||||
| analytics-tracking | SKILL.md, references/ga4-setup-guide.md, references/gtm-patterns.md, references/event-taxonomy.md, scripts/tracking_plan_generator.py |
|
||||
| pricing-strategy | SKILL.md, references/pricing-models.md (value, cost-plus, competitor, dynamic), references/packaging-guide.md, scripts/pricing_modeler.py, scripts/willingness_to_pay_analyzer.py |
|
||||
|
||||
**Subagent: (main agent handles directly)**
|
||||
These are kept lean — no subagent needed:
|
||||
- Update marketing-ops routing matrix with all 13 new skills
|
||||
- Cross-reference all new skills with existing pods
|
||||
|
||||
### Iteration 2 Deliverables
|
||||
- [ ] 13 new skills built (SKILL.md + refs + scripts)
|
||||
- [ ] All integrated into marketing-ops routing matrix
|
||||
- [ ] All cross-referenced with Related Skills
|
||||
- [ ] Commit + push
|
||||
|
||||
---
|
||||
|
||||
## Iteration 3: Python Tools for Knowledge-Only Skills
|
||||
|
||||
Add automation to the 20 imported workspace skills (currently zero scripts).
|
||||
|
||||
### Priority 1: SEO + Content tools (highest impact)
|
||||
| Skill | Script | Purpose |
|
||||
|-------|--------|---------|
|
||||
| seo-audit | seo_checker.py | On-page SEO scoring (0-100): title, meta, headings, links, keyword density |
|
||||
| seo-audit | keyword_density_analyzer.py | Keyword distribution + stuffing detection |
|
||||
| content-strategy | topic_cluster_mapper.py | Map topic clusters, identify gaps, suggest pillar content |
|
||||
| copywriting | headline_scorer.py | Score headlines: power words, emotional triggers, length, clarity |
|
||||
| copy-editing | readability_scorer.py | Flesch Reading Ease, grade level, passive voice, sentence complexity |
|
||||
|
||||
### Priority 2: CRO tools
|
||||
| Skill | Script | Purpose |
|
||||
|-------|--------|---------|
|
||||
| page-cro | conversion_audit.py | Above-fold analysis, CTA scoring, trust signals, friction points |
|
||||
| form-cro | form_friction_analyzer.py | Field count, required fields, multi-step scoring |
|
||||
| signup-flow-cro | signup_funnel_analyzer.py | Step analysis, drop-off estimation |
|
||||
|
||||
### Priority 3: Channel + Growth tools
|
||||
| Skill | Script | Purpose |
|
||||
|-------|--------|---------|
|
||||
| paid-ads | roas_calculator.py | ROAS, CPA, budget allocation optimizer |
|
||||
| email-sequence | email_flow_designer.py | Sequence timing, open/click estimation |
|
||||
| ab-test-setup | sample_size_calculator.py | Statistical significance, test duration estimator |
|
||||
| competitor-alternatives | competitor_matrix_builder.py | Feature comparison matrix generator |
|
||||
|
||||
### Priority 4: Intelligence tools
|
||||
| Skill | Script | Purpose |
|
||||
|-------|--------|---------|
|
||||
| campaign-analytics | channel_mixer.py | Cross-channel attribution synthesis |
|
||||
| marketing-psychology | persuasion_audit.py | Score content against Cialdini's 6 principles |
|
||||
| launch-strategy | launch_readiness_scorer.py | Pre-launch checklist scoring |
|
||||
|
||||
### Iteration 3 Deliverables
|
||||
- [ ] ~18 new Python scripts (stdlib-only, CLI-first, JSON output)
|
||||
- [ ] All scripts have embedded sample data for zero-config runs
|
||||
- [ ] Commit + push
|
||||
|
||||
---
|
||||
|
||||
## Iteration 4: Quality Upgrade (C-Suite Standard)
|
||||
|
||||
Apply to ALL 39 marketing skills:
|
||||
|
||||
### 4A: Add to every skill
|
||||
- [ ] Proactive Triggers (5-6 context-driven alerts per skill)
|
||||
- [ ] Output Artifacts table (request → deliverable mapping)
|
||||
- [ ] Communication standard reference
|
||||
- [ ] Quality loop integration (self-verify, peer-verify)
|
||||
|
||||
### 4B: Add marketing-specific agents
|
||||
| Agent | Location | Purpose |
|
||||
|-------|----------|---------|
|
||||
| content-analyzer | marketing-ops/agents/ | Analyzes content for SEO, readability, brand voice |
|
||||
| seo-optimizer | marketing-ops/agents/ | On-page SEO recommendations |
|
||||
| meta-creator | marketing-ops/agents/ | Meta title/description generation |
|
||||
| headline-generator | marketing-ops/agents/ | Headline variations + scoring |
|
||||
| cro-analyst | marketing-ops/agents/ | CRO audit for any page |
|
||||
|
||||
Inspired by SEO Machine's 10 agents, but lean (markdown agents, not Python services).
|
||||
|
||||
### 4C: Parity check
|
||||
Run same audit as C-Suite:
|
||||
- [ ] All 39 skills: Keywords ✅, QuickStart ✅, Related Skills ✅, Integration ✅, Proactive ✅, Outputs ✅, Communication ✅
|
||||
- [ ] All Python scripts: syntax valid, sample data works, JSON output
|
||||
- [ ] All cross-references: bidirectional (A references B, B references A)
|
||||
- [ ] Marketing-ops routing matrix: all 39 skills + 6 cross-domain
|
||||
|
||||
### Iteration 4 Deliverables
|
||||
- [ ] Quality loop on all 39 skills
|
||||
- [ ] 5 marketing agents
|
||||
- [ ] Parity check passed
|
||||
- [ ] Final commit + PR merge-ready
|
||||
|
||||
---
|
||||
|
||||
## Execution Timeline
|
||||
|
||||
| Iteration | Work | Subagents | Est. Files |
|
||||
|-----------|------|-----------|-----------|
|
||||
| 1: Foundation + Import | 22 skills (2 new + 20 import) + 3 upgrades + metadata | 4 | ~80 |
|
||||
| 2: New Skills | 13 new skills | 6 | ~100 |
|
||||
| 3: Python Tools | ~18 scripts | 2-3 | ~18 |
|
||||
| 4: Quality Upgrade | Quality loop + agents + parity | 2-3 | ~50 |
|
||||
| **Total** | **39 skills** | **~15** | **~250** |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
1. **39 marketing skills** organized into 7 pods + orchestration
|
||||
2. **~38 Python tools** (18 existing + ~20 new), all stdlib-only
|
||||
3. **5 marketing agents** (content-analyzer, seo-optimizer, meta-creator, headline-generator, cro-analyst)
|
||||
4. **Full orchestration** via marketing-ops router with routing matrix
|
||||
5. **Context foundation** that every skill reads (brand voice, style guide, keywords, etc.)
|
||||
6. **Cross-domain routing** to 6 skills in business-growth, product-team, engineering-team
|
||||
7. **C-Suite quality standard** on all skills (proactive triggers, output artifacts, quality loop)
|
||||
8. **Full cross-referencing** between all skills (Related Skills sections)
|
||||
9. **CMO integration** — marketing-ops connects to c-level-advisor/cmo-advisor/
|
||||
10. **Zero external dependencies** — all Python scripts stdlib-only
|
||||
|
||||
---
|
||||
|
||||
*Ready for execution on Reza's go.*
|
||||
396
marketing-skill/MARKETING-EXPANSION-PLAN.md
Normal file
396
marketing-skill/MARKETING-EXPANSION-PLAN.md
Normal file
@@ -0,0 +1,396 @@
|
||||
# Marketing Team Expansion — Audit & Implementation Plan
|
||||
|
||||
## Executive Summary
|
||||
|
||||
We have **27 marketing skills** spread across two locations (7 in repo, 20 in workspace), zero orchestration, zero automation on the workspace skills, and significant gaps vs. the two reference repos. This plan consolidates, upgrades, and fills gaps to build a **complete marketing division** — from research to production to analytics.
|
||||
|
||||
---
|
||||
|
||||
## Part 1: Competitive Audit
|
||||
|
||||
### Source Repo Analysis
|
||||
|
||||
#### SEO Machine (TheCraigHewitt/seomachine)
|
||||
- **Focus:** SEO-first content production pipeline
|
||||
- **Strengths we lack:**
|
||||
- 🔴 **Content production workflow** — `/research → /write → /optimize → /publish` pipeline (we have no production workflow)
|
||||
- 🔴 **10 specialized agents** — content-analyzer, seo-optimizer, meta-creator, internal-linker, keyword-mapper, editor, performance, headline-generator, cro-analyst, landing-page-optimizer
|
||||
- 🔴 **23 Python analysis modules** — search intent, keyword density, readability scoring, content length comparator, SEO quality rater, above-fold analyzer, CTA analyzer, trust signal analyzer, landing page scorer
|
||||
- 🔴 **Data integrations** — GA4, Google Search Console, DataForSEO
|
||||
- 🔴 **Context-driven system** — brand-voice.md, style-guide.md, writing-examples.md, target-keywords.md, internal-links-map.md, competitor-analysis.md, seo-guidelines.md, cro-best-practices.md
|
||||
- 🔴 **Landing page system** — `/landing-write`, `/landing-audit`, `/landing-research`, `/landing-competitor`, `/landing-publish`
|
||||
- 🟡 **WordPress publishing** — API integration with Yoast SEO (useful but platform-specific)
|
||||
- 🟡 **AI watermark scrubber** — `/scrub` command to remove AI patterns
|
||||
- **Weaknesses:**
|
||||
- No orchestration layer (CMO-level strategy missing)
|
||||
- No cross-channel coordination
|
||||
- External dependencies (nltk, scikit-learn, beautifulsoup4) — violates our stdlib-only rule
|
||||
- WordPress-coupled publishing
|
||||
- No quality loop or verification
|
||||
|
||||
#### Marketing Skills (coreyhaines31/marketingskills)
|
||||
- **Focus:** Broad marketing skill coverage for SaaS
|
||||
- **Strengths we lack:**
|
||||
- 🔴 **product-marketing-context** as foundation — every skill reads it first (like our company-context.md)
|
||||
- 🔴 **ai-seo** — AI search optimization (AEO, GEO, LLMO) — entirely new category
|
||||
- 🔴 **site-architecture** — page hierarchy, navigation, URL structure, internal linking
|
||||
- 🔴 **schema-markup** — structured data implementation
|
||||
- 🔴 **cold-email** — B2B cold outreach emails and sequences
|
||||
- 🔴 **ad-creative** — bulk ad creative generation and iteration
|
||||
- 🔴 **churn-prevention** — cancel flows, save offers, dunning, payment recovery
|
||||
- 🔴 **referral-program** — referral and affiliate programs
|
||||
- 🔴 **pricing-strategy** — pricing, packaging, monetization
|
||||
- 🔴 **revops** — lead lifecycle, scoring, routing, pipeline management
|
||||
- 🔴 **sales-enablement** — sales decks, one-pagers, objection handling, demo scripts
|
||||
- 🔴 **Cross-referencing system** — skills reference each other with Related Skills sections
|
||||
- **Weaknesses:**
|
||||
- Zero Python automation (knowledge-only, same as our workspace skills)
|
||||
- No orchestration or routing
|
||||
- No quality loop
|
||||
- No agents
|
||||
|
||||
### What We Have vs What They Have
|
||||
|
||||
| Capability | Us (repo) | Us (workspace) | SEO Machine | Marketing Skills |
|
||||
|-----------|-----------|----------------|-------------|-----------------|
|
||||
| **CRO skills** | 0 | 6 (page, form, signup, onboard, popup, paywall) | 2 (cro-analyst, landing-page-optimizer) | 6 (same as ours) |
|
||||
| **SEO skills** | 0 | 3 (seo-audit, programmatic-seo, competitor-alt) | Full stack (5 agents + 5 modules) | 5 (seo-audit, ai-seo, programmatic, schema, site-arch) |
|
||||
| **Content/Copy** | 1 (content-creator) | 4 (content-strategy, copywriting, copy-editing, social-content) | Full pipeline (research→write→optimize→publish) | 3 (copywriting, copy-editing, cold-email) |
|
||||
| **Email** | 0 | 1 (email-sequence) | 0 | 2 (email-sequence, cold-email) |
|
||||
| **Paid/Ads** | 0 | 1 (paid-ads) | 0 | 2 (paid-ads, ad-creative) |
|
||||
| **Analytics** | 1 (campaign-analytics) | 1 (ab-test-setup) | 3 (GA4, GSC, DataForSEO) | 1 (analytics-tracking) |
|
||||
| **Strategy** | 2 (pmm, demand-acq) | 3 (content-strategy, launch-strategy, marketing-ideas) | Content prioritization | 4 (launch, pricing, marketing-ideas, marketing-psych) |
|
||||
| **Growth/Retention** | 0 | 0 | 0 | 3 (referral, free-tool, churn-prevention) |
|
||||
| **Sales/RevOps** | 0 | 0 | 0 | 2 (revops, sales-enablement) |
|
||||
| **Python tools** | 18 scripts | 0 | 23 modules (external deps) | 0 |
|
||||
| **Agents** | 0 | 0 | 10 | 0 |
|
||||
| **Orchestration** | 0 | 0 | 0 | product-marketing-context (foundation only) |
|
||||
| **Context system** | 0 | 0 | 8 context files | 1 (product-marketing-context) |
|
||||
| **Production workflow** | 0 | 0 | Full (research→write→optimize→publish) | 0 |
|
||||
| **Landing pages** | 0 | 0 | Full (5 commands) | 0 |
|
||||
|
||||
---
|
||||
|
||||
## Part 2: Gap Analysis — What's Missing
|
||||
|
||||
### 🔴 Critical Gaps (must build)
|
||||
|
||||
1. **Orchestration layer** — no router, no coordination between 27 skills
|
||||
2. **Content production pipeline** — no research→write→optimize→publish workflow
|
||||
3. **SEO automation** — our seo-audit is knowledge-only, no analysis tools
|
||||
4. **Landing page system** — no landing page creation or CRO analysis
|
||||
5. **AI SEO (AEO/GEO/LLMO)** — entirely missing category, increasingly important
|
||||
6. **Context system** — no brand-voice, style-guide, or product-marketing-context foundation
|
||||
7. **Cross-referencing** — skills don't know about each other
|
||||
|
||||
### 🟡 Important Gaps (should build)
|
||||
|
||||
8. **Schema markup** — structured data implementation
|
||||
9. **Site architecture** — URL structure, navigation, internal linking strategy
|
||||
10. **Cold email / outreach** — B2B outreach sequences
|
||||
11. **Ad creative** — bulk ad generation and iteration
|
||||
12. **Churn prevention** — cancel flows, save offers, dunning
|
||||
13. **Referral programs** — referral and affiliate program design
|
||||
14. **Pricing strategy** — pricing, packaging, monetization
|
||||
15. **RevOps** — lead lifecycle, scoring, routing
|
||||
16. **Sales enablement** — sales decks, objection handling
|
||||
|
||||
### ⚪ Nice to Have
|
||||
|
||||
17. **WordPress/CMS publishing** — platform-specific, lower priority
|
||||
18. **AI watermark scrubber** — content de-robotification
|
||||
19. **Social media manager** — full management vs. current analyzer
|
||||
|
||||
---
|
||||
|
||||
## Part 3: Architecture
|
||||
|
||||
```
|
||||
CMO Advisor (C-Suite — strategy, budget, growth model)
|
||||
│
|
||||
│ reads company-context.md + marketing-context.md
|
||||
│
|
||||
Marketing Ops (router + orchestrator)
|
||||
│
|
||||
┌────┼────────┬──────────┬──────────┬──────────┬──────────┐
|
||||
│ │ │ │ │ │ │
|
||||
Content SEO CRO Channels Growth Intel Sales
|
||||
Pod Pod Pod Pod Pod Pod Pod
|
||||
(8) (5) (6) (5) (4) (4) (3)
|
||||
|
||||
Total: 35 skills + 1 orchestration + 1 context foundation = 37
|
||||
```
|
||||
|
||||
### Pod Breakdown
|
||||
|
||||
#### Context Foundation (1 skill — NEW)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| **marketing-context** | 🆕 Build | Inspired by SEO Machine's context system + marketingskills' product-marketing-context |
|
||||
|
||||
Creates and maintains: brand-voice.md, style-guide.md, target-keywords.md, internal-links-map.md, competitor-analysis.md, writing-examples.md. Every marketing skill reads this first.
|
||||
|
||||
#### Orchestration (1 skill — NEW)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| **marketing-ops** | 🆕 Build | Router + campaign orchestrator (like C-Suite Chief of Staff) |
|
||||
|
||||
Routes questions, coordinates campaigns, enforces quality loop, connects to CMO above.
|
||||
|
||||
#### Content Pod (8 skills — 5 existing + 3 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| content-creator | ✅ Upgrade | Repo (add context integration, quality loop) |
|
||||
| content-strategy | ✅ Import | Workspace |
|
||||
| copywriting | ✅ Import | Workspace |
|
||||
| copy-editing | ✅ Import | Workspace |
|
||||
| social-content | ✅ Import | Workspace |
|
||||
| marketing-ideas | ✅ Import | Workspace |
|
||||
| **content-production** | 🆕 Build | Inspired by SEO Machine's /research→/write→/optimize pipeline |
|
||||
| **content-humanizer** | 🆕 Build | Inspired by SEO Machine's editor agent + /scrub command |
|
||||
|
||||
#### SEO Pod (5 skills — 2 existing + 3 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| seo-audit | ✅ Import | Workspace (+ add Python tools) |
|
||||
| programmatic-seo | ✅ Import | Workspace |
|
||||
| **ai-seo** | 🆕 Build | From marketingskills (AEO, GEO, LLMO optimization) |
|
||||
| **schema-markup** | 🆕 Build | From marketingskills (structured data) |
|
||||
| **site-architecture** | 🆕 Build | From marketingskills (URL structure, nav, internal linking) |
|
||||
|
||||
#### CRO Pod (6 skills — all existing)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| page-cro | ✅ Import | Workspace |
|
||||
| form-cro | ✅ Import | Workspace |
|
||||
| signup-flow-cro | ✅ Import | Workspace |
|
||||
| onboarding-cro | ✅ Import | Workspace |
|
||||
| popup-cro | ✅ Import | Workspace |
|
||||
| paywall-upgrade-cro | ✅ Import | Workspace |
|
||||
|
||||
#### Channels Pod (5 skills — 3 existing + 2 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| email-sequence | ✅ Import | Workspace |
|
||||
| paid-ads | ✅ Import | Workspace |
|
||||
| social-media-analyzer → social-media-manager | ✅ Upgrade | Repo (expand from analyzer to manager) |
|
||||
| **cold-email** | 🆕 Build | From marketingskills (B2B outreach) |
|
||||
| **ad-creative** | 🆕 Build | From marketingskills (bulk ad generation) |
|
||||
|
||||
#### Growth & Retention Pod (4 skills — 1 existing + 3 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| ab-test-setup | ✅ Import | Workspace |
|
||||
| **churn-prevention** | 🆕 Build | From marketingskills (cancel flows, save offers, dunning) |
|
||||
| **referral-program** | 🆕 Build | From marketingskills (referral + affiliate) |
|
||||
| **free-tool-strategy** | 🆕 Build | From marketingskills (engineering as marketing) |
|
||||
|
||||
#### Intelligence Pod (4 skills — 3 existing + 1 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| campaign-analytics | ✅ Upgrade | Repo (add cross-channel synthesis) |
|
||||
| competitor-alternatives | ✅ Import | Workspace |
|
||||
| marketing-psychology | ✅ Import | Workspace |
|
||||
| **analytics-tracking** | 🆕 Build | From marketingskills (GA4, GTM, event tracking setup) |
|
||||
|
||||
#### Sales & GTM Pod (3 skills — 1 existing + 2 new)
|
||||
| Skill | Status | Source |
|
||||
|-------|--------|--------|
|
||||
| launch-strategy | ✅ Import | Workspace |
|
||||
| **pricing-strategy** | 🆕 Build | From marketingskills (pricing, packaging, monetization) |
|
||||
| **sales-enablement** | 🆕 Build | From marketingskills (sales decks, objection handling) |
|
||||
|
||||
### Also Import (not in pods)
|
||||
| Skill | Status |
|
||||
|-------|--------|
|
||||
| brand-guidelines | ✅ Import (merge into marketing-context) |
|
||||
| marketing-demand-acquisition | ✅ Keep in repo |
|
||||
| marketing-strategy-pmm | ✅ Keep in repo |
|
||||
| app-store-optimization | ✅ Keep in repo |
|
||||
| prompt-engineer-toolkit | ✅ Keep in repo |
|
||||
|
||||
---
|
||||
|
||||
## Part 4: Totals
|
||||
|
||||
| Category | Existing (import/upgrade) | New (build) | Total |
|
||||
|----------|--------------------------|-------------|-------|
|
||||
| Context | 0 | 1 | 1 |
|
||||
| Orchestration | 0 | 1 | 1 |
|
||||
| Content | 5 + 1 upgrade | 2 | 8 |
|
||||
| SEO | 2 | 3 | 5 |
|
||||
| CRO | 6 | 0 | 6 |
|
||||
| Channels | 2 + 1 upgrade | 2 | 5 |
|
||||
| Growth | 1 | 3 | 4 |
|
||||
| Intelligence | 2 + 1 upgrade | 1 | 4 |
|
||||
| Sales & GTM | 1 | 2 | 3 |
|
||||
| Standalone | 4 (keep as-is) | 0 | 4 |
|
||||
| **TOTAL** | **24** | **15** | **41** |
|
||||
|
||||
---
|
||||
|
||||
## Part 5: What Each New Skill Needs
|
||||
|
||||
Every new skill gets the C-Suite quality standard:
|
||||
- YAML frontmatter (name, description, license, metadata)
|
||||
- Keywords section (trigger-optimized)
|
||||
- Quick Start (3-step)
|
||||
- Key Questions (diagnostic)
|
||||
- Integration table (which skills it works with)
|
||||
- Proactive Triggers (context-driven alerts)
|
||||
- Output Artifacts (request → deliverable)
|
||||
- Communication standard (bottom line first, structured output)
|
||||
- Related Skills section (cross-references)
|
||||
- Python tools (stdlib-only, CLI-first, JSON output)
|
||||
- Reference docs (heavy content here, not SKILL.md)
|
||||
|
||||
---
|
||||
|
||||
## Part 6: Python Tools Plan
|
||||
|
||||
### Import SEO Machine concepts (rebuilt stdlib-only)
|
||||
| Script | Original | Our version |
|
||||
|--------|----------|-------------|
|
||||
| search_intent_analyzer.py | Uses nltk | Regex + heuristic (stdlib) |
|
||||
| keyword_analyzer.py | Uses scikit-learn | Counter + re (stdlib) |
|
||||
| readability_scorer.py | Uses textstat | Flesch formula (stdlib, pure math) |
|
||||
| seo_quality_rater.py | External deps | Checklist scorer (stdlib) |
|
||||
| content_length_comparator.py | Web scraping | Input-based comparison (stdlib) |
|
||||
| above_fold_analyzer.py | BeautifulSoup | html.parser (stdlib) |
|
||||
| cta_analyzer.py | BeautifulSoup | html.parser (stdlib) |
|
||||
| landing_page_scorer.py | External | Composite scorer (stdlib) |
|
||||
|
||||
### New tools for existing skills
|
||||
| Skill | New tool | Purpose |
|
||||
|-------|----------|---------|
|
||||
| seo-audit | seo_checker.py | On-page SEO scoring (0-100) |
|
||||
| content-strategy | topic_cluster_mapper.py | Map topic clusters and gaps |
|
||||
| copywriting | headline_scorer.py | Score headlines by power words, length, emotion |
|
||||
| email-sequence | email_flow_designer.py | Design drip sequences with timing |
|
||||
| paid-ads | roas_calculator.py | ROAS and budget allocation |
|
||||
| campaign-analytics | channel_mixer.py | Cross-channel attribution synthesis |
|
||||
| pricing-strategy | pricing_modeler.py | Price sensitivity and packaging optimizer |
|
||||
| churn-prevention | churn_risk_scorer.py | Score churn signals |
|
||||
|
||||
---
|
||||
|
||||
## Part 7: Execution Phases
|
||||
|
||||
### Phase 1: Foundation + Import (batch 1)
|
||||
**Goal:** Import 20 workspace skills, create context foundation, build orchestration
|
||||
**Estimated:** ~80 files, 6 subagents
|
||||
- Import all 20 workspace skills into `marketing-skill/`
|
||||
- Add YAML frontmatter standardization where needed
|
||||
- Create `marketing-context/` (context foundation)
|
||||
- Create `marketing-ops/` (router/orchestrator)
|
||||
- Add Related Skills cross-references to all imported skills
|
||||
- Update CLAUDE.md
|
||||
|
||||
### Phase 2: New Skills (batch 2)
|
||||
**Goal:** Build 13 missing skills
|
||||
**Estimated:** ~100 files, 6 subagents
|
||||
- SEO: ai-seo, schema-markup, site-architecture
|
||||
- Content: content-production, content-humanizer
|
||||
- Channels: cold-email, ad-creative
|
||||
- Growth: churn-prevention, referral-program, free-tool-strategy
|
||||
- Intelligence: analytics-tracking
|
||||
- Sales: pricing-strategy, sales-enablement
|
||||
|
||||
### Phase 3: Python Tools (batch 3)
|
||||
**Goal:** Add automation to knowledge-only skills
|
||||
**Estimated:** ~20 scripts
|
||||
- SEO analysis tools (search intent, keyword, readability, SEO quality)
|
||||
- Content tools (headline scorer, topic mapper)
|
||||
- CRO tools (above-fold, CTA, landing page scorer)
|
||||
- Channel tools (ROAS calculator, email flow designer)
|
||||
- Growth tools (churn risk scorer, pricing modeler)
|
||||
|
||||
### Phase 4: Quality Upgrade (batch 4)
|
||||
**Goal:** Apply C-Suite quality standard to all 37 skills
|
||||
- Proactive triggers on all skills
|
||||
- Output artifacts on all skills
|
||||
- Integration tables on all skills
|
||||
- Communication standard references
|
||||
- Quality loop integration
|
||||
- Final parity check
|
||||
|
||||
---
|
||||
|
||||
## Part 8: Already Exists Elsewhere in Repo — DO NOT DUPLICATE
|
||||
|
||||
Cross-repo audit found these "missing" capabilities already exist in other domains. The marketing team should **reference** them, not rebuild them.
|
||||
|
||||
| "Missing" Capability | Already Exists At | What It Has |
|
||||
|---------------------|-------------------|-------------|
|
||||
| **Revenue Operations / RevOps** | `business-growth/revenue-operations/` | 3 Python tools: pipeline_analyzer, forecast_accuracy_tracker, gtm_efficiency_calculator |
|
||||
| **Sales Enablement** | `business-growth/sales-engineer/` | 3 Python tools: rfp_response_analyzer, poc_planner, competitive_matrix_builder |
|
||||
| **Churn Prevention** | `business-growth/customer-success-manager/` | 3 Python tools: churn_risk_analyzer, expansion_opportunity_scorer, health_score_calculator |
|
||||
| **Landing Pages** | `product-team/landing-page-generator/` | Full Next.js/React landing page generation with copy frameworks, CRO patterns |
|
||||
| **Competitive Analysis** | `product-team/competitive-teardown/` | Feature matrices, SWOT, positioning maps, UX audits |
|
||||
| **Email Templates** | `engineering-team/email-template-builder/` | React Email, provider integration, i18n, dark mode, spam optimization |
|
||||
| **Pricing Strategy** (partial) | `product-team/product-strategist/` | OKR cascade, product strategy (pricing is a component) |
|
||||
| **Financial Analysis** | `finance/financial-analyst/` | DCF, ratios, budget variance, forecasting |
|
||||
| **Contract/Proposal** | `business-growth/contract-and-proposal-writer/` | Proposal generation |
|
||||
| **Stripe/Payments** | `engineering-team/stripe-integration-expert/` | Payment flows, subscription billing |
|
||||
|
||||
### Impact on Plan
|
||||
|
||||
**Remove from "new to build" list:**
|
||||
- ~~revops~~ → already at `business-growth/revenue-operations/`
|
||||
- ~~sales-enablement~~ → already at `business-growth/sales-engineer/`
|
||||
- ~~churn-prevention~~ → already at `business-growth/customer-success-manager/`
|
||||
|
||||
**Keep building (truly missing):**
|
||||
- ✅ pricing-strategy (dedicated marketing pricing, not product strategy)
|
||||
- ✅ cold-email (B2B outreach — distinct from email-sequence)
|
||||
- ✅ ad-creative (bulk ad generation)
|
||||
- ✅ referral-program (referral + affiliate programs)
|
||||
- ✅ free-tool-strategy (engineering as marketing)
|
||||
- ✅ ai-seo (AEO/GEO/LLMO — entirely new category)
|
||||
- ✅ schema-markup (structured data)
|
||||
- ✅ site-architecture (URL structure, nav, internal linking)
|
||||
- ✅ content-production (research→write→optimize pipeline)
|
||||
- ✅ content-humanizer (AI watermark removal, voice injection)
|
||||
- ✅ analytics-tracking (GA4, GTM, event tracking setup)
|
||||
- ✅ marketing-context (foundation — brand voice, style guide, etc.)
|
||||
- ✅ marketing-ops (orchestration router)
|
||||
|
||||
**Cross-reference in marketing-ops routing matrix:**
|
||||
The marketing-ops router should know about and route to these business-growth/product-team skills when relevant, just like C-Suite's Chief of Staff routes across domains.
|
||||
|
||||
### Revised Totals
|
||||
|
||||
| Category | Existing (import/upgrade) | New (build) | Total |
|
||||
|----------|--------------------------|-------------|-------|
|
||||
| Context | 0 | 1 | 1 |
|
||||
| Orchestration | 0 | 1 | 1 |
|
||||
| Content | 5 + 1 upgrade | 2 | 8 |
|
||||
| SEO | 2 | 3 | 5 |
|
||||
| CRO | 6 | 0 | 6 |
|
||||
| Channels | 2 + 1 upgrade | 2 | 5 |
|
||||
| Growth | 1 | 2 (referral, free-tool) | 3 |
|
||||
| Intelligence | 2 + 1 upgrade | 1 | 4 |
|
||||
| Sales & GTM | 1 | 1 (pricing-strategy) | 2 |
|
||||
| Standalone | 4 (keep as-is) | 0 | 4 |
|
||||
| **TOTAL** | **24** | **13** | **39** |
|
||||
|
||||
Down from 41 to 39 — removed 3 duplicates, cleaner architecture.
|
||||
|
||||
---
|
||||
|
||||
## Part 9: Skills NOT Included (and why)
|
||||
|
||||
| Skill | Source | Reason for exclusion |
|
||||
|-------|--------|---------------------|
|
||||
| WordPress publishing | SEO Machine | Platform-specific, not universal |
|
||||
| DataForSEO integration | SEO Machine | Paid API, violates stdlib-only rule |
|
||||
| GA4/GSC Python clients | SEO Machine | External deps (google-api-python-client) |
|
||||
| revops | marketingskills | Already at `business-growth/revenue-operations/` |
|
||||
| sales-enablement | marketingskills | Already at `business-growth/sales-engineer/` |
|
||||
| churn-prevention | marketingskills | Already at `business-growth/customer-success-manager/` |
|
||||
| product-marketing-context | marketingskills | Replaced by our marketing-context (richer) |
|
||||
|
||||
---
|
||||
|
||||
*Created: 2026-03-06*
|
||||
*Target: PR on `feat/marketing-expansion` branch*
|
||||
105
marketing-skill/SKILL.md
Normal file
105
marketing-skill/SKILL.md
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
name: marketing-skills
|
||||
description: "42-skill marketing division for AI coding agents. 7 specialist pods covering content, SEO, CRO, channels, growth, intelligence, and sales. Foundation context system + orchestration router. 27 Python tools (all stdlib-only). Works with Claude Code, Codex CLI, and OpenClaw."
|
||||
version: 2.0.0
|
||||
author: Alireza Rezvani
|
||||
license: MIT
|
||||
tags:
|
||||
- marketing
|
||||
- seo
|
||||
- content
|
||||
- copywriting
|
||||
- cro
|
||||
- analytics
|
||||
- ai-seo
|
||||
agents:
|
||||
- claude-code
|
||||
- codex-cli
|
||||
- openclaw
|
||||
---
|
||||
|
||||
# Marketing Skills Division
|
||||
|
||||
42 production-ready marketing skills organized into 7 specialist pods with a context foundation and orchestration layer.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Claude Code
|
||||
```
|
||||
/read marketing-skill/marketing-ops/SKILL.md
|
||||
```
|
||||
The router will direct you to the right specialist skill.
|
||||
|
||||
### Codex CLI
|
||||
```bash
|
||||
codex --full-auto "Read marketing-skill/marketing-ops/SKILL.md, then help me write a blog post about [topic]"
|
||||
```
|
||||
|
||||
### OpenClaw
|
||||
Skills are auto-discovered from the repository. Ask your agent for marketing help — it routes via `marketing-ops`.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
marketing-skill/
|
||||
├── marketing-context/ ← Foundation: brand voice, audience, goals
|
||||
├── marketing-ops/ ← Router: dispatches to the right skill
|
||||
│
|
||||
├── Content Pod (8) ← Strategy → Production → Editing → Social
|
||||
├── SEO Pod (5) ← Traditional + AI SEO + Schema + Architecture
|
||||
├── CRO Pod (6) ← Pages, Forms, Signup, Onboarding, Popups, Paywall
|
||||
├── Channels Pod (5) ← Email, Ads, Cold Email, Ad Creative, Social Mgmt
|
||||
├── Growth Pod (4) ← A/B Testing, Referrals, Free Tools, Churn
|
||||
├── Intelligence Pod (4) ← Competitors, Psychology, Analytics, Campaigns
|
||||
└── Sales & GTM Pod (2) ← Pricing, Launch Strategy
|
||||
```
|
||||
|
||||
## First-Time Setup
|
||||
|
||||
Run `marketing-context` to create your `marketing-context.md` file. Every other skill reads this for brand voice, audience personas, and competitive landscape. Do this once — it makes everything better.
|
||||
|
||||
## Pod Overview
|
||||
|
||||
| Pod | Skills | Python Tools | Key Capabilities |
|
||||
|-----|--------|-------------|-----------------|
|
||||
| **Foundation** | 2 | 2 | Brand context capture, skill routing |
|
||||
| **Content** | 8 | 5 | Strategy → production → editing → humanization |
|
||||
| **SEO** | 5 | 2 | Technical SEO, AI SEO (AEO/GEO), schema, architecture |
|
||||
| **CRO** | 6 | 0 | Page, form, signup, onboarding, popup, paywall optimization |
|
||||
| **Channels** | 5 | 2 | Email sequences, paid ads, cold email, ad creative |
|
||||
| **Growth** | 4 | 2 | A/B testing, referral programs, free tools, churn prevention |
|
||||
| **Intelligence** | 4 | 4 | Competitor analysis, marketing psychology, analytics, campaigns |
|
||||
| **Sales & GTM** | 2 | 1 | Pricing strategy, launch planning |
|
||||
| **Standalone** | 4 | 9 | ASO, brand guidelines, PMM strategy, prompt engineering |
|
||||
|
||||
## Python Tools (27 scripts)
|
||||
|
||||
All scripts are stdlib-only (zero pip installs), CLI-first with JSON output, and include embedded sample data for demo mode.
|
||||
|
||||
```bash
|
||||
# Content scoring
|
||||
python3 marketing-skill/content-production/scripts/content_scorer.py article.md
|
||||
|
||||
# AI writing detection
|
||||
python3 marketing-skill/content-humanizer/scripts/humanizer_scorer.py draft.md
|
||||
|
||||
# Brand voice analysis
|
||||
python3 marketing-skill/content-production/scripts/brand_voice_analyzer.py copy.txt
|
||||
|
||||
# Ad copy validation
|
||||
python3 marketing-skill/ad-creative/scripts/ad_copy_validator.py ads.json
|
||||
|
||||
# Pricing scenario modeling
|
||||
python3 marketing-skill/pricing-strategy/scripts/pricing_modeler.py
|
||||
|
||||
# Tracking plan generation
|
||||
python3 marketing-skill/analytics-tracking/scripts/tracking_plan_generator.py
|
||||
```
|
||||
|
||||
## Unique Features
|
||||
|
||||
- **AI SEO (AEO/GEO/LLMO)** — Optimize for AI citation, not just ranking
|
||||
- **Content Humanizer** — Detect and fix AI writing patterns with scoring
|
||||
- **Context Foundation** — One brand context file feeds all 42 skills
|
||||
- **Orchestration Router** — Smart routing by keyword + complexity scoring
|
||||
- **Zero Dependencies** — All Python tools use stdlib only
|
||||
302
marketing-skill/ab-test-setup/SKILL.md
Normal file
302
marketing-skill/ab-test-setup/SKILL.md
Normal file
@@ -0,0 +1,302 @@
|
||||
---
|
||||
name: ab-test-setup
|
||||
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "conversion experiment," "statistical significance," or "test this." For tracking implementation, see analytics-tracking.
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# 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 `.claude/product-marketing-context.md` exists, 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
|
||||
|
||||
**DON'T:**
|
||||
- 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)
|
||||
|
||||
---
|
||||
|
||||
## 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?
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Proactively offer A/B test design when:
|
||||
|
||||
1. **Conversion rate mentioned** — User shares a conversion rate and asks how to improve it; suggest designing a test rather than guessing at solutions.
|
||||
2. **Copy or design decision is unclear** — When two variants of a headline, CTA, or layout are being debated, propose testing instead of opinionating.
|
||||
3. **Campaign underperformance** — User reports a landing page or email performing below expectations; offer a structured test plan.
|
||||
4. **Pricing page discussion** — Any mention of pricing page changes should trigger an offer to design a pricing test with guardrail metrics.
|
||||
5. **Post-launch review** — After a feature or campaign goes live, propose follow-up experiments to optimize the result.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Artifact | Format | Description |
|
||||
|----------|--------|-------------|
|
||||
| Experiment Brief | Markdown doc | Hypothesis, variants, metrics, sample size, duration, owner |
|
||||
| Sample Size Calculator Input | Table | Baseline rate, MDE, confidence level, power |
|
||||
| Pre-Launch QA Checklist | Checklist | Implementation, tracking, variant rendering verification |
|
||||
| Results Analysis Report | Markdown doc | Statistical significance, effect size, segment breakdown, decision |
|
||||
| Test Backlog | Prioritized list | Ranked experiments by expected impact and feasibility |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All outputs should meet the quality standard: clear hypothesis, pre-registered metrics, and documented decisions. Avoid presenting inconclusive results as wins. Every test should produce a learning, even if the variant loses. Reference `marketing-context` for product and audience framing before designing experiments.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro** — USE when you need ideas for *what* to test; NOT when you already have a hypothesis and just need test design.
|
||||
- **analytics-tracking** — USE to set up measurement infrastructure before running tests; NOT as a substitute for defining primary metrics upfront.
|
||||
- **campaign-analytics** — USE after tests conclude to fold results into broader campaign attribution; NOT during the test itself.
|
||||
- **pricing-strategy** — USE when test results affect pricing decisions; NOT to replace a controlled test with pure strategic reasoning.
|
||||
- **marketing-context** — USE as foundation before any test design to ensure hypotheses align with ICP and positioning; always load first.
|
||||
252
marketing-skill/ab-test-setup/references/sample-size-guide.md
Normal file
252
marketing-skill/ab-test-setup/references/sample-size-guide.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Sample Size Guide
|
||||
|
||||
Reference for calculating sample sizes and test duration.
|
||||
|
||||
## 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
|
||||
```
|
||||
268
marketing-skill/ab-test-setup/references/test-templates.md
Normal file
268
marketing-skill/ab-test-setup/references/test-templates.md
Normal file
@@ -0,0 +1,268 @@
|
||||
# A/B Test Templates Reference
|
||||
|
||||
Templates for planning, documenting, and analyzing experiments.
|
||||
|
||||
## 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 |
|
||||
```
|
||||
337
marketing-skill/ab-test-setup/scripts/sample_size_calculator.py
Normal file
337
marketing-skill/ab-test-setup/scripts/sample_size_calculator.py
Normal file
@@ -0,0 +1,337 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
sample_size_calculator.py — A/B Test Sample Size Calculator
|
||||
100% stdlib, no pip installs required.
|
||||
|
||||
Usage:
|
||||
python3 sample_size_calculator.py # demo mode
|
||||
python3 sample_size_calculator.py --baseline 0.05 --mde 0.20
|
||||
python3 sample_size_calculator.py --baseline 0.05 --mde 0.20 --daily-traffic 500
|
||||
python3 sample_size_calculator.py --baseline 0.05 --mde 0.20 --json
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import math
|
||||
import sys
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Z-score approximation (scipy-free, Beasley-Springer-Moro algorithm)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _norm_ppf(p: float) -> float:
|
||||
"""Percent-point function (inverse CDF) of the standard normal.
|
||||
Uses rational approximation — accurate to ~1e-9.
|
||||
Reference: Abramowitz & Stegun 26.2.17 / Peter Acklam's algorithm.
|
||||
"""
|
||||
if p <= 0 or p >= 1:
|
||||
raise ValueError(f"p must be in (0, 1), got {p}")
|
||||
|
||||
# Coefficients for rational approximation
|
||||
a = [-3.969683028665376e+01, 2.209460984245205e+02,
|
||||
-2.759285104469687e+02, 1.383577518672690e+02,
|
||||
-3.066479806614716e+01, 2.506628277459239e+00]
|
||||
b = [-5.447609879822406e+01, 1.615858368580409e+02,
|
||||
-1.556989798598866e+02, 6.680131188771972e+01,
|
||||
-1.328068155288572e+01]
|
||||
c = [-7.784894002430293e-03, -3.223964580411365e-01,
|
||||
-2.400758277161838e+00, -2.549732539343734e+00,
|
||||
4.374664141464968e+00, 2.938163982698783e+00]
|
||||
d = [7.784695709041462e-03, 3.224671290700398e-01,
|
||||
2.445134137142996e+00, 3.754408661907416e+00]
|
||||
|
||||
p_low = 0.02425
|
||||
p_high = 1 - p_low
|
||||
|
||||
if p < p_low:
|
||||
q = math.sqrt(-2 * math.log(p))
|
||||
return (((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) / \
|
||||
((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1)
|
||||
elif p <= p_high:
|
||||
q = p - 0.5
|
||||
r = q * q
|
||||
return (((((a[0]*r+a[1])*r+a[2])*r+a[3])*r+a[4])*r+a[5])*q / \
|
||||
(((((b[0]*r+b[1])*r+b[2])*r+b[3])*r+b[4])*r+1)
|
||||
else:
|
||||
q = math.sqrt(-2 * math.log(1 - p))
|
||||
return -(((((c[0]*q+c[1])*q+c[2])*q+c[3])*q+c[4])*q+c[5]) / \
|
||||
((((d[0]*q+d[1])*q+d[2])*q+d[3])*q+1)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Core calculation
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def calculate_sample_size(
|
||||
baseline: float,
|
||||
mde: float,
|
||||
alpha: float = 0.05,
|
||||
power: float = 0.80,
|
||||
) -> dict:
|
||||
"""
|
||||
Two-proportion z-test sample size formula (two-tailed).
|
||||
|
||||
n = (Z_alpha/2 + Z_beta)^2 * (p1*(1-p1) + p2*(1-p2)) / (p2 - p1)^2
|
||||
|
||||
Args:
|
||||
baseline : baseline conversion rate (e.g. 0.05 for 5%)
|
||||
mde : minimum detectable effect as relative lift (e.g. 0.20 for +20%)
|
||||
alpha : significance level (Type I error rate), default 0.05
|
||||
power : statistical power (1 - Type II error rate), default 0.80
|
||||
|
||||
Returns dict with all intermediate values and results.
|
||||
"""
|
||||
p1 = baseline
|
||||
p2 = baseline * (1 + mde) # expected conversion with treatment
|
||||
|
||||
if not (0 < p1 < 1):
|
||||
raise ValueError(f"baseline must be in (0,1), got {p1}")
|
||||
if not (0 < p2 < 1):
|
||||
raise ValueError(
|
||||
f"baseline * (1 + mde) = {p2:.4f} is outside (0,1). "
|
||||
"Reduce mde or increase baseline."
|
||||
)
|
||||
|
||||
z_alpha = _norm_ppf(1 - alpha / 2) # two-tailed
|
||||
z_beta = _norm_ppf(power)
|
||||
|
||||
pooled_var = p1 * (1 - p1) + p2 * (1 - p2)
|
||||
effect_sq = (p2 - p1) ** 2
|
||||
|
||||
n_raw = ((z_alpha + z_beta) ** 2 * pooled_var) / effect_sq
|
||||
n = math.ceil(n_raw)
|
||||
|
||||
return {
|
||||
"inputs": {
|
||||
"baseline_conversion_rate": p1,
|
||||
"minimum_detectable_effect_relative": mde,
|
||||
"expected_variant_conversion_rate": round(p2, 6),
|
||||
"significance_level_alpha": alpha,
|
||||
"statistical_power": power,
|
||||
},
|
||||
"z_scores": {
|
||||
"z_alpha_2": round(z_alpha, 4),
|
||||
"z_beta": round(z_beta, 4),
|
||||
},
|
||||
"results": {
|
||||
"sample_size_per_variation": n,
|
||||
"total_sample_size": n * 2,
|
||||
"absolute_lift": round(p2 - p1, 6),
|
||||
"relative_lift_pct": round(mde * 100, 2),
|
||||
},
|
||||
"formula": (
|
||||
"n = (Z_α/2 + Z_β)² × (p1(1−p1) + p2(1−p2)) / (p2−p1)² "
|
||||
"[two-proportion z-test, two-tailed]"
|
||||
),
|
||||
"assumptions": [
|
||||
"Two-tailed test (detecting lift in either direction)",
|
||||
"Independent samples (no within-subject correlation)",
|
||||
"Fixed horizon (not sequential / always-valid)",
|
||||
"Binomial outcome (conversion yes/no)",
|
||||
"No novelty effect correction applied",
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
def add_duration(result: dict, daily_traffic: int) -> dict:
|
||||
"""Append estimated test duration given total daily traffic (both variants)."""
|
||||
n_total = result["results"]["total_sample_size"]
|
||||
days = math.ceil(n_total / daily_traffic)
|
||||
weeks = round(days / 7, 1)
|
||||
result["duration"] = {
|
||||
"daily_traffic_both_variants": daily_traffic,
|
||||
"estimated_days": days,
|
||||
"estimated_weeks": weeks,
|
||||
"note": (
|
||||
"Assumes traffic is evenly split 50/50 between control and variant. "
|
||||
"Add ~10–20% buffer for weekday/weekend variance."
|
||||
),
|
||||
}
|
||||
return result
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Scoring helper (0-100)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def score_test_design(result: dict) -> dict:
|
||||
"""Heuristic quality score for the A/B test design."""
|
||||
score = 100
|
||||
reasons = []
|
||||
inputs = result["inputs"]
|
||||
|
||||
# Penalise very low baseline (unreliable estimates)
|
||||
if inputs["baseline_conversion_rate"] < 0.01:
|
||||
score -= 15
|
||||
reasons.append("Baseline <1%: high variance, consider aggregating more data first.")
|
||||
|
||||
# Penalise tiny MDE (will need enormous sample)
|
||||
mde = inputs["minimum_detectable_effect_relative"]
|
||||
if mde < 0.05:
|
||||
score -= 20
|
||||
reasons.append("MDE <5%: very small effect, experiment may take months.")
|
||||
elif mde < 0.10:
|
||||
score -= 10
|
||||
reasons.append("MDE <10%: moderately small effect size.")
|
||||
|
||||
# Penalise overly aggressive alpha
|
||||
if inputs["significance_level_alpha"] > 0.10:
|
||||
score -= 15
|
||||
reasons.append("α >10%: high false-positive risk.")
|
||||
|
||||
# Penalise low power
|
||||
if inputs["statistical_power"] < 0.80:
|
||||
score -= 20
|
||||
reasons.append("Power <80%: elevated risk of missing real effects (Type II error).")
|
||||
|
||||
# Duration penalty (if available)
|
||||
dur = result.get("duration")
|
||||
if dur:
|
||||
days = dur["estimated_days"]
|
||||
if days > 90:
|
||||
score -= 20
|
||||
reasons.append(f"Test duration {days}d >90 days: novelty/seasonal effects likely.")
|
||||
elif days > 30:
|
||||
score -= 10
|
||||
reasons.append(f"Test duration {days}d >30 days: monitor for external confounders.")
|
||||
|
||||
score = max(0, score)
|
||||
return {
|
||||
"design_quality_score": score,
|
||||
"score_interpretation": _score_label(score),
|
||||
"issues": reasons if reasons else ["No major design issues detected."],
|
||||
}
|
||||
|
||||
|
||||
def _score_label(s: int) -> str:
|
||||
if s >= 90: return "Excellent"
|
||||
if s >= 75: return "Good"
|
||||
if s >= 60: return "Fair"
|
||||
if s >= 40: return "Poor"
|
||||
return "Critical"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Pretty-print
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def pretty_print(result: dict, score: dict) -> None:
|
||||
inp = result["inputs"]
|
||||
res = result["results"]
|
||||
zs = result["z_scores"]
|
||||
|
||||
print("\n" + "=" * 60)
|
||||
print(" A/B TEST SAMPLE SIZE CALCULATOR")
|
||||
print("=" * 60)
|
||||
|
||||
print("\n📥 INPUTS")
|
||||
print(f" Baseline conversion rate : {inp['baseline_conversion_rate']*100:.2f}%")
|
||||
print(f" Variant conversion rate : {inp['expected_variant_conversion_rate']*100:.2f}%")
|
||||
print(f" Minimum detectable effect: {inp['minimum_detectable_effect_relative']*100:.1f}% relative "
|
||||
f"(+{res['absolute_lift']*100:.3f}pp absolute)")
|
||||
print(f" Significance level (α) : {inp['significance_level_alpha']}")
|
||||
print(f" Statistical power : {inp['statistical_power']*100:.0f}%")
|
||||
|
||||
print("\n📐 FORMULA")
|
||||
print(f" {result['formula']}")
|
||||
print(f" Z_α/2 = {zs['z_alpha_2']} Z_β = {zs['z_beta']}")
|
||||
|
||||
print("\n📊 RESULTS")
|
||||
print(f" ✅ Sample size per variation : {res['sample_size_per_variation']:,}")
|
||||
print(f" ✅ Total sample size (both) : {res['total_sample_size']:,}")
|
||||
|
||||
if "duration" in result:
|
||||
d = result["duration"]
|
||||
print(f"\n⏱️ DURATION ESTIMATE (traffic: {d['daily_traffic_both_variants']:,}/day)")
|
||||
print(f" Estimated test duration : {d['estimated_days']} days (~{d['estimated_weeks']} weeks)")
|
||||
print(f" Note: {d['note']}")
|
||||
|
||||
print("\n💡 ASSUMPTIONS")
|
||||
for a in result["assumptions"]:
|
||||
print(f" • {a}")
|
||||
|
||||
print(f"\n🎯 DESIGN QUALITY SCORE: {score['design_quality_score']}/100 ({score['score_interpretation']})")
|
||||
for issue in score["issues"]:
|
||||
print(f" ⚠ {issue}")
|
||||
|
||||
print()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# CLI
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def parse_args():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Calculate required sample size for an A/B test (stdlib only).",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog=__doc__,
|
||||
)
|
||||
parser.add_argument("--baseline", type=float, default=None,
|
||||
help="Baseline conversion rate (e.g. 0.05 for 5%%)")
|
||||
parser.add_argument("--mde", type=float, default=None,
|
||||
help="Minimum detectable effect as relative lift (e.g. 0.20 for +20%%)")
|
||||
parser.add_argument("--alpha", type=float, default=0.05,
|
||||
help="Significance level α (default: 0.05)")
|
||||
parser.add_argument("--power", type=float, default=0.80,
|
||||
help="Statistical power 1-β (default: 0.80)")
|
||||
parser.add_argument("--daily-traffic", type=int, default=None,
|
||||
help="Total daily visitors across both variants (for duration estimate)")
|
||||
parser.add_argument("--json", action="store_true",
|
||||
help="Output results as JSON")
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
DEMO_SCENARIOS = [
|
||||
{"label": "E-commerce checkout (low baseline)",
|
||||
"baseline": 0.03, "mde": 0.20, "alpha": 0.05, "power": 0.80, "daily_traffic": 800},
|
||||
{"label": "SaaS free-trial signup (medium baseline)",
|
||||
"baseline": 0.08, "mde": 0.15, "alpha": 0.05, "power": 0.80, "daily_traffic": 2000},
|
||||
{"label": "Button CTA (high baseline)",
|
||||
"baseline": 0.25, "mde": 0.10, "alpha": 0.05, "power": 0.80, "daily_traffic": 5000},
|
||||
]
|
||||
|
||||
|
||||
def main():
|
||||
args = parse_args()
|
||||
demo_mode = (args.baseline is None and args.mde is None)
|
||||
|
||||
if demo_mode:
|
||||
print("🔬 DEMO MODE — running 3 sample scenarios\n")
|
||||
all_results = []
|
||||
for sc in DEMO_SCENARIOS:
|
||||
res = calculate_sample_size(sc["baseline"], sc["mde"], sc["alpha"], sc["power"])
|
||||
res = add_duration(res, sc["daily_traffic"])
|
||||
sc_score = score_test_design(res)
|
||||
res["scenario"] = sc["label"]
|
||||
res["score"] = sc_score
|
||||
all_results.append(res)
|
||||
if not args.json:
|
||||
print(f"\n{'─'*60}")
|
||||
print(f"SCENARIO: {sc['label']}")
|
||||
pretty_print(res, sc_score)
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(all_results, indent=2))
|
||||
return
|
||||
|
||||
# Single calculation mode
|
||||
if args.baseline is None or args.mde is None:
|
||||
print("Error: --baseline and --mde are required (or omit both for demo mode).", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
result = calculate_sample_size(args.baseline, args.mde, args.alpha, args.power)
|
||||
if args.daily_traffic:
|
||||
result = add_duration(result, args.daily_traffic)
|
||||
sc_score = score_test_design(result)
|
||||
result["score"] = sc_score
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(result, indent=2))
|
||||
else:
|
||||
pretty_print(result, sc_score)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
267
marketing-skill/ad-creative/SKILL.md
Normal file
267
marketing-skill/ad-creative/SKILL.md
Normal file
@@ -0,0 +1,267 @@
|
||||
---
|
||||
name: ad-creative
|
||||
description: "When the user needs to generate, iterate, or scale ad creative for paid advertising. Use when they say 'write ad copy,' 'generate headlines,' 'create ad variations,' 'bulk creative,' 'iterate on ads,' 'ad copy validation,' 'RSA headlines,' 'Meta ad copy,' 'LinkedIn ad,' or 'creative testing.' This is pure creative production — distinct from paid-ads (campaign strategy). Use ad-creative when you need the copy, not the campaign plan."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Ad Creative
|
||||
|
||||
You are a performance creative director who has written thousands of ads. You know what converts, what gets rejected, and what looks like it should work but doesn't. Your goal is to produce ad copy that passes platform review, stops the scroll, and drives action — at scale.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Product & Offer
|
||||
- What are you advertising? Be specific — product, feature, free trial, lead magnet?
|
||||
- What's the core value prop in one sentence?
|
||||
- What does the customer get and how fast?
|
||||
|
||||
### 2. Audience
|
||||
- Who are you writing for? Job title, pain point, moment in their day
|
||||
- What do they already believe? What objections will they have?
|
||||
|
||||
### 3. Platform & Stage
|
||||
- Which platform(s)? (Google, Meta, LinkedIn, Twitter/X, TikTok)
|
||||
- Funnel stage? (Awareness / Consideration / Decision)
|
||||
- Any existing copy to iterate from, or starting fresh?
|
||||
|
||||
### 4. Performance Data (if iterating)
|
||||
- What's currently running? Share current copy.
|
||||
- Which ads are winning? CTR, CVR, CPA?
|
||||
- What have you already tested?
|
||||
|
||||
---
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Generate from Scratch
|
||||
Starting with nothing. Build a complete creative set from brief to ready-to-upload copy.
|
||||
|
||||
**Workflow:**
|
||||
1. Extract the core message — what changes in the customer's life?
|
||||
2. Map to funnel stage → select creative framework
|
||||
3. Generate 5–10 headlines per formula type
|
||||
4. Write body copy per platform (respecting character limits)
|
||||
5. Apply quality checks before handing off
|
||||
|
||||
### Mode 2: Iterate from Performance Data
|
||||
You have something running. Now make it better.
|
||||
|
||||
**Workflow:**
|
||||
1. Audit current copy — what angle is each ad taking?
|
||||
2. Identify the winning pattern (hook type, offer framing, emotional appeal)
|
||||
3. Double down: 3–5 variations on the winning theme
|
||||
4. Open new angles: 2–3 tests in unexplored territory
|
||||
5. Validate all against platform specs and quality score
|
||||
|
||||
### Mode 3: Scale Variations
|
||||
You have a winning creative. Now multiply it for testing or for multiple audiences/platforms.
|
||||
|
||||
**Workflow:**
|
||||
1. Lock the core message
|
||||
2. Vary one element at a time: hook, social proof, CTA, format
|
||||
3. Adapt across platforms (reformat without rewriting from scratch)
|
||||
4. Produce a creative matrix: rows = angles, columns = platforms
|
||||
|
||||
---
|
||||
|
||||
## Platform Specs Quick Reference
|
||||
|
||||
| Platform | Format | Headline Limit | Body Copy Limit | Notes |
|
||||
|----------|--------|---------------|-----------------|-------|
|
||||
| Google RSA | Search | 30 chars (×15) | 90 chars (×4 descriptions) | Max 3 pinned |
|
||||
| Google Display | Display | 30 chars (×5) | 90 chars (×5) | Also needs 5 images |
|
||||
| Meta (Facebook/Instagram) | Feed/Story | 40 chars (primary) | 125 chars primary text | Image text <20% |
|
||||
| LinkedIn | Sponsored Content | 70 chars headline | 150 chars intro text | No click-bait |
|
||||
| Twitter/X | Promoted | 70 chars | 280 chars total | No deceptive tactics |
|
||||
| TikTok | In-Feed | No overlay headline | 80–100 chars caption | Hook in first 3s |
|
||||
|
||||
See [references/platform-specs.md](references/platform-specs.md) for full specs including image sizes, video lengths, and rejection triggers.
|
||||
|
||||
---
|
||||
|
||||
## Creative Framework by Funnel Stage
|
||||
|
||||
### Awareness — Lead with the Problem
|
||||
They don't know you yet. Meet them where they are.
|
||||
|
||||
**Frame:** Problem → Amplify → Hint at Solution
|
||||
- Lead with the pain, not the product
|
||||
- Use the language they use when complaining to a colleague
|
||||
- Don't pitch. Relate.
|
||||
|
||||
**Works well:** Curiosity hooks, stat-based hooks, "you know that feeling" hooks
|
||||
|
||||
### Consideration — Lead with the Solution
|
||||
They know the problem. They're evaluating options.
|
||||
|
||||
**Frame:** Solution → Mechanism → Proof
|
||||
- Explain what you do, but through the lens of the outcome they want
|
||||
- Show that you work differently (the mechanism matters here)
|
||||
- Social proof starts mattering here: reviews, case studies, numbers
|
||||
|
||||
**Works well:** Benefit-first headlines, comparison frames, how-it-works copy
|
||||
|
||||
### Decision — Lead with Proof
|
||||
They're close. Remove the last objection.
|
||||
|
||||
**Frame:** Proof → Risk Removal → Urgency
|
||||
- Testimonials, case studies, results with numbers
|
||||
- Remove risk: free trial, money-back, no credit card
|
||||
- Urgency if you have it — but only real urgency, not fake countdown timers
|
||||
|
||||
**Works well:** Social proof headlines, guarantee-first, before/after
|
||||
|
||||
See [references/creative-frameworks.md](references/creative-frameworks.md) for the full framework catalog with examples by platform.
|
||||
|
||||
---
|
||||
|
||||
## Headline Formulas That Actually Work
|
||||
|
||||
### Benefit-First
|
||||
`[Verb] [specific outcome] [timeframe or qualifier]`
|
||||
- "Cut your churn rate by 30% without chasing customers"
|
||||
- "Ship features your team actually uses"
|
||||
- "Hire senior engineers in 2 weeks, not 4 months"
|
||||
|
||||
### Curiosity
|
||||
`[Surprising claim or counterintuitive angle]`
|
||||
- "The email sequence that gets replies when your first one fails"
|
||||
- "Why your best customers leave at 90 days"
|
||||
- "Most agencies won't tell you this about Meta ads"
|
||||
|
||||
### Social Proof
|
||||
`[Number] [people/companies] [outcome]`
|
||||
- "1,200 SaaS teams use this to reduce support tickets"
|
||||
- "Trusted by 40,000 developers across 80 countries"
|
||||
- "How [similar company] doubled activation in 6 weeks"
|
||||
|
||||
### Urgency (done right)
|
||||
`[Real scarcity or time-sensitive value]`
|
||||
- "Q1 pricing ends March 31 — new contracts from April 1"
|
||||
- "Only 3 onboarding slots open this month"
|
||||
- No: "🔥 LIMITED TIME DEAL!! ACT NOW!!!" — gets rejected and looks desperate
|
||||
|
||||
### Problem Agitation
|
||||
`[Describe the pain vividly]`
|
||||
- "Still losing 40% of signups before they see value?"
|
||||
- "Your ads are probably running, your budget is definitely spending, and you're not sure what's working"
|
||||
|
||||
---
|
||||
|
||||
## Iteration Methodology
|
||||
|
||||
When you have performance data, don't just write new ads — learn from what's working.
|
||||
|
||||
### Step 1: Diagnose the Winner
|
||||
- What hook type is it? (Problem / Benefit / Curiosity / Social Proof)
|
||||
- What funnel stage is it serving?
|
||||
- What emotional driver is it hitting? (Fear, ambition, FOMO, frustration, relief)
|
||||
- What's the CTA asking for? (Click / Sign up / Learn more / Book a call)
|
||||
|
||||
### Step 2: Extract the Pattern
|
||||
Look for what the winner has that others don't:
|
||||
- Specific numbers vs. vague claims
|
||||
- First-person customer voice vs. brand voice
|
||||
- Direct benefit vs. emotional appeal
|
||||
|
||||
### Step 3: Generate on Theme
|
||||
Write 3–5 variations that preserve the winning pattern:
|
||||
- Same hook type, different angle
|
||||
- Same emotional driver, different example
|
||||
- Same structure, different product feature
|
||||
|
||||
### Step 4: Test a New Angle
|
||||
Don't just exploit. Also explore. Pick one untested angle and generate 2–3 ads.
|
||||
|
||||
### Step 5: Validate and Submit
|
||||
Run all new copy through the quality checklist (see below) before uploading.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before submitting any ad copy, verify:
|
||||
|
||||
**Platform Compliance**
|
||||
- [ ] All character counts within limits (use `scripts/ad_copy_validator.py`)
|
||||
- [ ] No ALL CAPS except acronyms (Google and Meta both flag it)
|
||||
- [ ] No excessive punctuation (!!!, ???, …. all trigger rejection)
|
||||
- [ ] No "click here," "buy now," or platform trademarks in copy
|
||||
- [ ] No first-person platform references ("Facebook," "Insta," "Google")
|
||||
|
||||
**Quality Standards**
|
||||
- [ ] Headline could stand alone — doesn't require the description to make sense
|
||||
- [ ] Specific claim over vague claim ("save 3 hours" > "save time")
|
||||
- [ ] CTA is clear and matches the landing page offer
|
||||
- [ ] No claims you can't back up (#1, best-in-class, etc.)
|
||||
|
||||
**Audience Check**
|
||||
- [ ] Would the ideal customer stop scrolling for this?
|
||||
- [ ] Does the language match how they talk about this problem?
|
||||
- [ ] Is the funnel stage right for the audience targeting?
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **Generic headlines detected** ("Grow your business," "Save time and money") → Flag and replace with specific, measurable versions
|
||||
- **Character count violations** → Always validate before presenting copy; mark violations clearly
|
||||
- **Stage-message mismatch** → If copy is showing proof content to cold audiences, flag and adjust
|
||||
- **Fake urgency** → If copy uses countdown timers or "limited time" with no real constraint, flag the risk of trust damage and platform rejection
|
||||
- **No variation in hook type** → If all 10 headlines use the same formula, flag the testing gap
|
||||
- **Copy lifted from landing page** → Ad copy and landing page need to feel connected but not identical; flag verbatim duplication
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| "Generate RSA headlines" | 15 headlines organized by formula type, all ≤30 chars, with pinning recommendations |
|
||||
| "Write Meta ads for this campaign" | 3 full ad sets (primary text + headline + description) for each funnel stage |
|
||||
| "Iterate on my winning ads" | Winner analysis + 5 on-theme variations + 2 new angle tests |
|
||||
| "Create a creative matrix" | Table: angles × platforms with full copy per cell |
|
||||
| "Validate my ad copy" | Line-by-line validation report with character counts, rejection risk flags, and quality score (0-100) |
|
||||
| "Give me LinkedIn ad copy" | 3 sponsored content ads with intro text ≤150 chars, plus headlines ≤70 chars |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — lead with the copy, explain the rationale after
|
||||
- **Platform specs visible** — always show character count next to each line
|
||||
- **Confidence tagging** — 🟢 tested formula / 🟡 new angle / 🔴 high-risk claim
|
||||
- **Rejection risks flagged explicitly** — don't make the user guess
|
||||
|
||||
Format for presenting ad copy:
|
||||
|
||||
```
|
||||
[AD SET NAME] | [Platform] | [Funnel Stage]
|
||||
Headline: "..." (28 chars) 🟢
|
||||
Body: "..." (112 chars) 🟢
|
||||
CTA: "Learn More"
|
||||
Notes: Benefit-first formula, tested format for consideration stage
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **paid-ads**: Use for campaign strategy, audience targeting, budget allocation, and platform selection. NOT for writing the actual copy (use ad-creative for that).
|
||||
- **copywriting**: Use for landing page and long-form web copy. NOT for platform-specific character-constrained ad copy.
|
||||
- **ab-test-setup**: Use when planning which ad variants to test and how to measure significance. NOT for generating the variants (use ad-creative for that).
|
||||
- **content-creator**: Use for organic social content and blog content. NOT for paid ad copy (different constraints, different voice).
|
||||
- **copy-editing**: Use when polishing existing copy. NOT for bulk generation or platform-specific formatting.
|
||||
253
marketing-skill/ad-creative/references/creative-frameworks.md
Normal file
253
marketing-skill/ad-creative/references/creative-frameworks.md
Normal file
@@ -0,0 +1,253 @@
|
||||
# Creative Frameworks — Headline and Copy Formulas by Platform and Funnel Stage
|
||||
|
||||
A working catalog of the copy frameworks that consistently outperform generic ads. Use these as starting points, not templates to fill in blindly.
|
||||
|
||||
---
|
||||
|
||||
## The Golden Rule
|
||||
|
||||
Every ad has one job: get the right person to stop, read, and take one action. If the copy is trying to do three things, it does none of them well. One message, one CTA, one next step.
|
||||
|
||||
---
|
||||
|
||||
## Framework Index
|
||||
|
||||
1. PAS — Problem, Agitate, Solution
|
||||
2. BAB — Before, After, Bridge
|
||||
3. FAB — Feature, Advantage, Benefit
|
||||
4. AIDA — Attention, Interest, Desire, Action
|
||||
5. Social Proof Frame
|
||||
6. Contrarian Frame
|
||||
7. Specificity Frame
|
||||
8. How-It-Works Frame
|
||||
|
||||
---
|
||||
|
||||
## 1. PAS — Problem, Agitate, Solution
|
||||
|
||||
**Best for:** Awareness and consideration stage. Cold audiences who don't know your solution.
|
||||
|
||||
**Structure:**
|
||||
- Problem: Name the pain in their words
|
||||
- Agitate: Make them feel how bad it is (don't make it worse than reality — they'll know)
|
||||
- Solution: Position your product as the obvious fix
|
||||
|
||||
**Example (SaaS — project management):**
|
||||
```
|
||||
Primary text: "Your team is shipping, but nobody knows who owns what. Deadlines are "this week"
|
||||
not "Tuesday at 3pm." By the time the stand-up is over, everyone has a different version of
|
||||
the plan. [Product] replaces the chaos with a single source of truth. Try it free for 14 days."
|
||||
|
||||
Headline: "Stop running projects in Slack threads"
|
||||
```
|
||||
|
||||
**Length guidance:** PAS works long and short. Short for cold feed, long for warm retargeting.
|
||||
|
||||
---
|
||||
|
||||
## 2. BAB — Before, After, Bridge
|
||||
|
||||
**Best for:** Consideration and decision stage. Audiences who know the problem and are evaluating.
|
||||
|
||||
**Structure:**
|
||||
- Before: Where they are now (the frustrating state)
|
||||
- After: Where they want to be (the goal)
|
||||
- Bridge: How your product gets them from here to there
|
||||
|
||||
**Example (B2B analytics tool):**
|
||||
```
|
||||
Headline: "From data chaos to clear answers"
|
||||
Body: "Before [Product]: 6 spreadsheets, 4 dashboards, nobody agrees on the numbers.
|
||||
After [Product]: One source of truth, automated weekly reports, decisions in minutes.
|
||||
The bridge: connect your data sources once, and [Product] does the rest."
|
||||
```
|
||||
|
||||
**Note:** BAB works especially well for case studies and social proof ads where you can show a real before/after with numbers.
|
||||
|
||||
---
|
||||
|
||||
## 3. FAB — Feature, Advantage, Benefit
|
||||
|
||||
**Best for:** Decision stage, retargeting, people who have visited your product page.
|
||||
|
||||
**Structure:**
|
||||
- Feature: What it does (the thing you built)
|
||||
- Advantage: How it works better than the alternative
|
||||
- Benefit: What the customer actually gets in their life/work
|
||||
|
||||
**Common mistake:** Stopping at the feature. "Two-factor authentication" is a feature. "Bank-level security" is an advantage. "Sleep at night knowing your customer data is protected" is the benefit.
|
||||
|
||||
**Example (HR software):**
|
||||
```
|
||||
Feature: "Automated payroll that syncs with your accounting software"
|
||||
Advantage: "No more manual data entry between systems"
|
||||
Benefit: "Close the books on time, every time — without staying late"
|
||||
|
||||
Ad copy: "Payroll that closes itself. Automated payroll synced directly to QuickBooks —
|
||||
no double entry, no reconciliation hell. Every month. On time. [Product] —
|
||||
start your free trial."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. AIDA — Attention, Interest, Desire, Action
|
||||
|
||||
**Best for:** Video ads, longer copy (LinkedIn, email), awareness campaigns.
|
||||
|
||||
**Structure:**
|
||||
- Attention: Hook (first 3 seconds / first sentence)
|
||||
- Interest: Why this matters to them specifically
|
||||
- Desire: Make them want the outcome
|
||||
- Action: One clear CTA
|
||||
|
||||
**Example (video script outline for SaaS):**
|
||||
```
|
||||
[0–3s] ATTENTION: "[Hook visual/statement]" — "Most companies spend 8 hours a week
|
||||
on reports nobody reads."
|
||||
[3–10s] INTEREST: "If you're a head of marketing, that's 32 hours of your team's time
|
||||
each month — time they could spend on campaigns that actually drive revenue."
|
||||
[10–20s] DESIRE: "[Product] automates the reporting. Your team gets that time back.
|
||||
Your manager gets the data they asked for, without the nagging."
|
||||
[20–25s] ACTION: "Start your 14-day free trial. No credit card."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Social Proof Frame
|
||||
|
||||
**Best for:** Decision stage. Works especially well for retargeting.
|
||||
|
||||
**Formulas:**
|
||||
|
||||
**Customer voice:**
|
||||
```
|
||||
"[Customer quote that speaks to the exact result — specific numbers preferred]"
|
||||
— [Name, Title, Company]
|
||||
[Product name] — [CTA]
|
||||
```
|
||||
|
||||
**Results-led:**
|
||||
```
|
||||
Headline: "[Company] saved [X] hours per week with [Product]"
|
||||
Body: "Before [Product], [Company] was manually tracking [problem]. Today,
|
||||
they [specific result] — in [timeframe]. Here's how they did it."
|
||||
```
|
||||
|
||||
**Volume proof:**
|
||||
```
|
||||
Headline: "[Number] teams trust [Product] to [outcome]"
|
||||
Body: "From 5-person startups to Fortune 500 companies. Start your free trial."
|
||||
```
|
||||
|
||||
**Note:** Specificity makes social proof work. "Many customers love it" → weak. "4,200 teams use [Product] to eliminate weekly reports" → strong.
|
||||
|
||||
---
|
||||
|
||||
## 6. Contrarian Frame
|
||||
|
||||
**Best for:** Awareness stage on saturated topics. Breaks through category fatigue.
|
||||
|
||||
**Structure:** Challenge the conventional wisdom in your category. Then reframe with your perspective.
|
||||
|
||||
**Example (email marketing tool):**
|
||||
```
|
||||
Headline: "More emails isn't the answer"
|
||||
Body: "Everyone says send more emails. Better segmentation. More automation. More sequences.
|
||||
But if your email is boring, more of it just means more unsubscribes.
|
||||
[Product] helps you write emails people actually want to open — then send them
|
||||
to the people most likely to act. Less volume. More revenue."
|
||||
```
|
||||
|
||||
**Warning:** The contrarian frame needs substance behind it. If your product is "like everyone else but better," don't use this frame. Use it when you genuinely have a different approach.
|
||||
|
||||
---
|
||||
|
||||
## 7. Specificity Frame
|
||||
|
||||
**Best for:** All stages. Works everywhere. The most underused framework.
|
||||
|
||||
**Principle:** Specific claims outperform vague claims on every metric. Not "save time" — "save 3 hours per week." Not "grow your business" — "increase trial-to-paid conversion by 22%."
|
||||
|
||||
**Upgrade examples:**
|
||||
| Vague | Specific |
|
||||
|-------|---------|
|
||||
| "Save time on reporting" | "Cut reporting time from 8 hours to 45 minutes" |
|
||||
| "Trusted by leading companies" | "Used by 3,200+ growth teams in 60 countries" |
|
||||
| "Improve your team's performance" | "Teams using [Product] ship 40% more features per quarter" |
|
||||
| "Get better results" | "Average customer sees 28% higher conversion within 90 days" |
|
||||
| "Easy to use" | "Set up in 15 minutes — no engineering required" |
|
||||
|
||||
If you don't have specific numbers: get them. Talk to 5 customers, ask for their before/after. One real number beats 10 marketing adjectives.
|
||||
|
||||
---
|
||||
|
||||
## 8. How-It-Works Frame
|
||||
|
||||
**Best for:** Consideration stage. Audiences who are curious but not yet convinced.
|
||||
|
||||
**Structure:** Show the mechanism — how your product produces the result. Remove mystery, reduce skepticism.
|
||||
|
||||
**Example (automation tool):**
|
||||
```
|
||||
Headline: "How [Product] works in 3 steps"
|
||||
Body:
|
||||
"1. Connect your tools (10 minutes, no coding)
|
||||
2. Set your conditions ("when a lead scores over 80, do this")
|
||||
3. Watch it run — 24/7, without your team touching it"
|
||||
|
||||
The result? Leads followed up in minutes, not days. Teams that spend time on deals,
|
||||
not on data entry.
|
||||
[CTA: See it in action — free demo]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Framework Match
|
||||
|
||||
| Platform | Best Frameworks | Why |
|
||||
|----------|---------------|-----|
|
||||
| Google RSA | Specificity, Benefit-first | Intent-driven — they searched for it |
|
||||
| Meta Feed (cold) | PAS, Contrarian | Interrupt and engage fast |
|
||||
| Meta Feed (retargeting) | BAB, Social Proof | They know you — sell the outcome |
|
||||
| LinkedIn | AIDA, FAB, How-It-Works | Longer attention span, B2B mindset |
|
||||
| TikTok | PAS (compressed), Hook-first | 3-second hook is everything |
|
||||
| Twitter | Contrarian, Specificity | Opinionated content performs |
|
||||
|
||||
---
|
||||
|
||||
## Funnel Stage → Framework Selector
|
||||
|
||||
| Stage | Goal | Top Frameworks |
|
||||
|-------|------|---------------|
|
||||
| **Awareness** | Interrupt → Relevant → Curious | PAS, Contrarian, Specificity |
|
||||
| **Consideration** | Educate → Differentiate → Trust | AIDA, FAB, How-It-Works, BAB |
|
||||
| **Decision** | Prove → Remove risk → Action | Social Proof, BAB, Specificity + guarantee |
|
||||
| **Retention/Upsell** | Remind value → Expand → Deepen | BAB, Feature highlight, milestone-based |
|
||||
|
||||
---
|
||||
|
||||
## Headline Formula Quick Reference
|
||||
|
||||
| Formula | Structure | Example |
|
||||
|---------|-----------|---------|
|
||||
| Benefit-First | [Verb] [outcome] [qualifier] | "Ship twice as fast without breaking prod" |
|
||||
| Problem-Led | [Pain point they recognize] | "Still manually exporting to CSV every Monday?" |
|
||||
| Number-Led | [Number] [thing] [result] | "14 days. Zero code. Full automation." |
|
||||
| Curiosity | [Counterintuitive or unexpected] | "The feature nobody builds that triples retention" |
|
||||
| How-To | "How [persona] [achieves outcome]" | "How growth teams cut CAC by 35% in one quarter" |
|
||||
| Social Proof | "[Number] [people/teams] [do/use/trust]" | "31,000 marketers use this to skip the daily stand-up" |
|
||||
| Objection-Lead | [Address the #1 reason they don't buy] | "No, you don't need an engineer to set this up" |
|
||||
| Direct Comparison | "[Vs. their current approach]" | "Cheaper than Salesforce. More powerful than your spreadsheet." |
|
||||
|
||||
---
|
||||
|
||||
## Anti-Patterns to Avoid
|
||||
|
||||
| Anti-Pattern | Why It Fails | Fix |
|
||||
|-------------|-------------|-----|
|
||||
| "We are the #1 platform for..." | Unsubstantiated, overused, ignored | Lead with proof, not ranking |
|
||||
| "Solutions for modern teams" | Meaningless — who isn't a modern team? | Name the specific team + specific problem |
|
||||
| "Powerful yet easy to use" | Every product says this | Show the result — don't describe the product |
|
||||
| "Unlock your potential" | Zero specificity, total fluff | What potential, specifically? Show it. |
|
||||
| "Join thousands of happy customers" | Vague and dated | "3,400 companies use [Product] to [specific outcome]" |
|
||||
| Emoji abuse | Looks desperate on LinkedIn, clutters Google | One emoji max, only if it adds meaning |
|
||||
170
marketing-skill/ad-creative/references/platform-specs.md
Normal file
170
marketing-skill/ad-creative/references/platform-specs.md
Normal file
@@ -0,0 +1,170 @@
|
||||
# Platform Specs — Ad Copy Character Limits and Format Requirements
|
||||
|
||||
Full specifications for each major ad platform. Use this when generating or validating ad copy.
|
||||
|
||||
---
|
||||
|
||||
## Google Ads
|
||||
|
||||
### Responsive Search Ads (RSA)
|
||||
| Element | Limit | Count | Notes |
|
||||
|---------|-------|-------|-------|
|
||||
| Headline | 30 chars | Up to 15 (min 3) | At least 3 unique, Google mixes them |
|
||||
| Description | 90 chars | Up to 4 (min 2) | Google selects 2 to show |
|
||||
| Display URL path | 15 chars each | 2 path fields | Auto-appended to domain |
|
||||
| Final URL | No char limit | 1 | Must match domain in display URL |
|
||||
|
||||
**Pinning:** You can pin headlines to position 1, 2, or 3. Only pin when critical (e.g., brand name, compliance disclaimer). Pinning reduces Google's optimization.
|
||||
|
||||
**Ad Strength:** Google scores RSAs: Poor / Average / Good / Excellent. Target "Good" or "Excellent" by:
|
||||
- Using all 15 headline slots
|
||||
- Making headlines unique (no repeats, no same keywords)
|
||||
- Including your main keyword in at least 3 headlines
|
||||
- Using descriptions that complement, not repeat, headlines
|
||||
|
||||
### Performance Max (PMax)
|
||||
| Element | Limit | Count |
|
||||
|---------|-------|-------|
|
||||
| Headline | 30 chars | Up to 5 |
|
||||
| Long headline | 90 chars | Up to 5 |
|
||||
| Description | 90 chars | Up to 5 |
|
||||
| Short description | 60 chars | 1 |
|
||||
|
||||
### Display Ads (Responsive)
|
||||
| Element | Limit | Count |
|
||||
|---------|-------|-------|
|
||||
| Short headline | 30 chars | 1 |
|
||||
| Long headline | 90 chars | 1 |
|
||||
| Description | 90 chars | 1 |
|
||||
| Business name | 25 chars | 1 |
|
||||
|
||||
---
|
||||
|
||||
## Meta (Facebook & Instagram)
|
||||
|
||||
### Feed Ads (Single Image / Carousel)
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Primary text | 125 chars (preview) / 2200 max | First 125 shown before "See more" |
|
||||
| Headline | 40 chars | Shown below image |
|
||||
| Description | 30 chars | Optional, below headline |
|
||||
| Link description | 20 chars | URL preview |
|
||||
|
||||
**Image text rule:** Images with >20% text surface area get reduced distribution. Meta's tool at meta.com/ads/inspector/ checks this. Keep text minimal on images — put copy in the primary text field.
|
||||
|
||||
### Story / Reel Ads
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Primary text overlay | 90 chars | Auto-placed if used |
|
||||
| No traditional headline | — | Overlay text is the copy |
|
||||
|
||||
### Carousel Ads
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Primary text | 125 chars (preview) | Shared across cards |
|
||||
| Headline per card | 40 chars | Each card has own headline |
|
||||
| Description per card | 20 chars | Optional |
|
||||
| Cards | 2–10 | |
|
||||
|
||||
**Rejection triggers (Meta):**
|
||||
- "Facebook" or "Instagram" in ad copy
|
||||
- Guarantees of specific financial outcomes ("Make $10k/month")
|
||||
- Before/after comparison (health/beauty)
|
||||
- Excessive use of first-person pronouns targeting users ("you," "your" in a way that implies personal attributes)
|
||||
- ALL CAPS in any significant portion
|
||||
- Exaggerated health claims
|
||||
- Click-bait phrasing ("You won't believe...", "Click to find out...")
|
||||
|
||||
---
|
||||
|
||||
## LinkedIn
|
||||
|
||||
### Sponsored Content (Single Image)
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Intro text | 150 chars (preview) / 600 max | First 150 visible before "See more" |
|
||||
| Headline | 70 chars | |
|
||||
| Description | 100 chars | Optional |
|
||||
|
||||
### Message Ads (InMail)
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Subject line | 60 chars | |
|
||||
| Body | 1,500 chars | First 500 most critical |
|
||||
| CTA button | 20 chars | |
|
||||
|
||||
### Conversation Ads
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Intro message | 500 chars | |
|
||||
| CTA per branch | 25 chars | Up to 5 buttons |
|
||||
| Message body per branch | 500 chars | |
|
||||
|
||||
**LinkedIn-specific rules:**
|
||||
- No "Click here" as standalone CTA
|
||||
- No images with more than 20% text
|
||||
- No misleading job descriptions or recruitment bait
|
||||
- Avoid generic corporate language — LinkedIn users are saturated with it
|
||||
- B2B works better when you lead with a specific insight or stat, not a product pitch
|
||||
|
||||
---
|
||||
|
||||
## Twitter/X
|
||||
|
||||
### Promoted Tweets
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Tweet text | 280 chars total | URL counts as 23 chars |
|
||||
| Usable copy | ~257 chars | After URL deduction |
|
||||
| Image | Any ratio | 1200×628 recommended |
|
||||
|
||||
**Twitter-specific notes:**
|
||||
- Copy + URL + image works in the feed
|
||||
- Lead with the hook — first 15 words matter most (above-the-fold on mobile)
|
||||
- Hashtags are optional for paid — they distract from the CTA
|
||||
|
||||
---
|
||||
|
||||
## TikTok
|
||||
|
||||
### In-Feed Ads
|
||||
| Element | Limit | Notes |
|
||||
|---------|-------|-------|
|
||||
| Ad text / caption | 100 chars | Overlaid on video |
|
||||
| Video length | 5–60 seconds (optimal 15–30s) | |
|
||||
| Mention/hashtag | Avoid branded hashtags | Policy restriction |
|
||||
|
||||
**TikTok-specific notes:**
|
||||
- Hook must land in the first 3 seconds — after that, thumb stops
|
||||
- Native-feeling content outperforms polished ads (not always better to use brand assets)
|
||||
- Text on screen increases time-watched
|
||||
- CTA button text: "Shop Now," "Learn More," "Download," "Sign Up" are options
|
||||
|
||||
---
|
||||
|
||||
## Common Rejection Triggers (All Platforms)
|
||||
|
||||
| Trigger | Why It Gets Rejected | Fix |
|
||||
|---------|---------------------|-----|
|
||||
| ALL CAPS words | Flagged as aggressive/spam | Use title case or sentence case |
|
||||
| Excessive punctuation | !!!, ???, ... — looks spammy | One at most |
|
||||
| "#1" claims | Superlatives require proof | Remove or qualify |
|
||||
| "Guaranteed" | Financial/result guarantees restricted | "Proven to" or show results data |
|
||||
| Trademarked terms | Platform + competitor names | Remove or get written permission |
|
||||
| Profanity | Obvious | Remove |
|
||||
| "Click here" | Considered low-quality bait | Use specific CTA |
|
||||
| Personal attributes | "You are depressed," "For single people" | Rephrase without identifying attributes |
|
||||
| Misleading discounts | "90% off" without context | Substantiate or remove |
|
||||
|
||||
---
|
||||
|
||||
## Platform Comparison — Which Platform for Which Creative?
|
||||
|
||||
| Use case | Best platform | Why |
|
||||
|----------|-------------|-----|
|
||||
| High intent, search-driven | Google Search RSA | Users are already looking |
|
||||
| Visual product with broad audience | Meta Feed | Best visual reach, lowest CPM for B2C |
|
||||
| B2B decision-makers | LinkedIn | Job title + company size targeting |
|
||||
| Young consumer audience, viral potential | TikTok | Organic-native feel, high engagement |
|
||||
| Real-time relevance, news-adjacent | Twitter/X | Timely content performs |
|
||||
| Retargeting across the web | Google Display | Broad reach, cheap retargeting |
|
||||
477
marketing-skill/ad-creative/scripts/ad_copy_validator.py
Normal file
477
marketing-skill/ad-creative/scripts/ad_copy_validator.py
Normal file
@@ -0,0 +1,477 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
ad_copy_validator.py — Validates ad copy against platform specs.
|
||||
|
||||
Checks: character counts, rejection triggers (ALL CAPS, excessive punctuation,
|
||||
trademarked terms), and scores each ad 0-100.
|
||||
|
||||
Usage:
|
||||
python3 ad_copy_validator.py # runs embedded sample
|
||||
python3 ad_copy_validator.py ads.json # validates a JSON file
|
||||
echo '{"platform":"google_rsa","headlines":["My headline"]}' | python3 ad_copy_validator.py
|
||||
|
||||
JSON input format:
|
||||
{
|
||||
"platform": "google_rsa" | "meta_feed" | "linkedin" | "twitter" | "tiktok",
|
||||
"headlines": ["...", ...],
|
||||
"descriptions": ["...", ...], # for google
|
||||
"primary_text": "...", # for meta, linkedin, twitter, tiktok
|
||||
"headline": "...", # for meta headline field
|
||||
"intro_text": "..." # for linkedin
|
||||
}
|
||||
"""
|
||||
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Platform specifications
|
||||
# ---------------------------------------------------------------------------
|
||||
PLATFORM_SPECS = {
|
||||
"google_rsa": {
|
||||
"name": "Google RSA",
|
||||
"headline_max": 30,
|
||||
"headline_count_max": 15,
|
||||
"headline_count_min": 3,
|
||||
"description_max": 90,
|
||||
"description_count_max": 4,
|
||||
"description_count_min": 2,
|
||||
},
|
||||
"google_display": {
|
||||
"name": "Google Display",
|
||||
"headline_max": 30,
|
||||
"description_max": 90,
|
||||
},
|
||||
"meta_feed": {
|
||||
"name": "Meta (Facebook/Instagram) Feed",
|
||||
"primary_text_max": 125, # preview limit; 2200 absolute max
|
||||
"headline_max": 40,
|
||||
"description_max": 30,
|
||||
},
|
||||
"linkedin": {
|
||||
"name": "LinkedIn Sponsored Content",
|
||||
"intro_text_max": 150, # preview limit; 600 absolute max
|
||||
"headline_max": 70,
|
||||
"description_max": 100,
|
||||
},
|
||||
"twitter": {
|
||||
"name": "Twitter/X Promoted",
|
||||
"primary_text_max": 257, # 280 - 23 chars for URL
|
||||
},
|
||||
"tiktok": {
|
||||
"name": "TikTok In-Feed",
|
||||
"primary_text_max": 100,
|
||||
},
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Rejection triggers
|
||||
# ---------------------------------------------------------------------------
|
||||
TRADEMARKED_TERMS = [
|
||||
"facebook", "instagram", "google", "youtube", "tiktok", "twitter",
|
||||
"linkedin", "snapchat", "whatsapp", "amazon", "apple", "microsoft",
|
||||
]
|
||||
|
||||
PROHIBITED_PHRASES = [
|
||||
"click here",
|
||||
"limited time offer", # allowed if real — flagged for review
|
||||
"guaranteed",
|
||||
"100% free",
|
||||
"act now",
|
||||
"best in class",
|
||||
"world's best",
|
||||
"#1 rated",
|
||||
"number one",
|
||||
]
|
||||
|
||||
# Financial / health claim patterns
|
||||
SUSPICIOUS_PATTERNS = [
|
||||
r"\$\d{3,}[k+]?\s*per\s*(day|week|month)", # "make $1,000 per day"
|
||||
r"\d{3,}%\s*(return|roi|profit|gain)", # "300% return"
|
||||
r"(cure|treat|heal|eliminate)\s+\w+", # health claims
|
||||
r"lose\s+\d+\s*(pound|lb|kg)", # weight loss claims
|
||||
]
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Validation logic
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def count_chars(text):
|
||||
return len(text.strip())
|
||||
|
||||
|
||||
def check_all_caps(text):
|
||||
"""Returns True if more than 30% of alpha chars are uppercase — not counting acronyms."""
|
||||
words = text.split()
|
||||
violations = []
|
||||
for word in words:
|
||||
alpha = re.sub(r'[^a-zA-Z]', '', word)
|
||||
if len(alpha) > 3 and alpha.isupper():
|
||||
violations.append(word)
|
||||
return violations
|
||||
|
||||
|
||||
def check_excessive_punctuation(text):
|
||||
"""Flags repeated punctuation (!!!, ???, ...)."""
|
||||
return re.findall(r'[!?\.]{2,}', text)
|
||||
|
||||
|
||||
def check_trademark_mentions(text):
|
||||
lowered = text.lower()
|
||||
return [term for term in TRADEMARKED_TERMS if re.search(r'\b' + term + r'\b', lowered)]
|
||||
|
||||
|
||||
def check_prohibited_phrases(text):
|
||||
lowered = text.lower()
|
||||
return [phrase for phrase in PROHIBITED_PHRASES if phrase in lowered]
|
||||
|
||||
|
||||
def check_suspicious_claims(text):
|
||||
hits = []
|
||||
for pattern in SUSPICIOUS_PATTERNS:
|
||||
if re.search(pattern, text, re.IGNORECASE):
|
||||
hits.append(pattern)
|
||||
return hits
|
||||
|
||||
|
||||
def score_ad(issues):
|
||||
"""
|
||||
Score 0-100. Start at 100, deduct per issue category.
|
||||
"""
|
||||
score = 100
|
||||
deductions = {
|
||||
"char_over_limit": 20,
|
||||
"all_caps": 15,
|
||||
"excessive_punctuation": 10,
|
||||
"trademark_mention": 25,
|
||||
"prohibited_phrase": 15,
|
||||
"suspicious_claim": 30,
|
||||
"count_too_few": 10,
|
||||
"count_too_many": 5,
|
||||
}
|
||||
for category, items in issues.items():
|
||||
if items:
|
||||
score -= deductions.get(category, 5) * (1 if isinstance(items, bool) else min(len(items), 3))
|
||||
return max(0, score)
|
||||
|
||||
|
||||
def validate_google_rsa(ad):
|
||||
spec = PLATFORM_SPECS["google_rsa"]
|
||||
issues = defaultdict(list)
|
||||
report = []
|
||||
|
||||
headlines = ad.get("headlines", [])
|
||||
descriptions = ad.get("descriptions", [])
|
||||
|
||||
# Count checks
|
||||
if len(headlines) < spec["headline_count_min"]:
|
||||
issues["count_too_few"].append(f"Need ≥{spec['headline_count_min']} headlines, got {len(headlines)}")
|
||||
if len(headlines) > spec["headline_count_max"]:
|
||||
issues["count_too_many"].append(f"Max {spec['headline_count_max']} headlines, got {len(headlines)}")
|
||||
if len(descriptions) < spec["description_count_min"]:
|
||||
issues["count_too_few"].append(f"Need ≥{spec['description_count_min']} descriptions, got {len(descriptions)}")
|
||||
|
||||
# Character checks per headline
|
||||
for i, h in enumerate(headlines):
|
||||
length = count_chars(h)
|
||||
status = "✅" if length <= spec["headline_max"] else "❌"
|
||||
if length > spec["headline_max"]:
|
||||
issues["char_over_limit"].append(f"Headline {i+1}: {length} chars (max {spec['headline_max']})")
|
||||
report.append(f" Headline {i+1}: {status} '{h}' ({length}/{spec['headline_max']} chars)")
|
||||
|
||||
# Rejection trigger checks on each headline
|
||||
caps = check_all_caps(h)
|
||||
if caps:
|
||||
issues["all_caps"].extend(caps)
|
||||
punct = check_excessive_punctuation(h)
|
||||
if punct:
|
||||
issues["excessive_punctuation"].extend(punct)
|
||||
trademarks = check_trademark_mentions(h)
|
||||
if trademarks:
|
||||
issues["trademark_mention"].extend(trademarks)
|
||||
prohibited = check_prohibited_phrases(h)
|
||||
if prohibited:
|
||||
issues["prohibited_phrase"].extend(prohibited)
|
||||
|
||||
for i, d in enumerate(descriptions):
|
||||
length = count_chars(d)
|
||||
status = "✅" if length <= spec["description_max"] else "❌"
|
||||
if length > spec["description_max"]:
|
||||
issues["char_over_limit"].append(f"Description {i+1}: {length} chars (max {spec['description_max']})")
|
||||
report.append(f" Description {i+1}: {status} '{d}' ({length}/{spec['description_max']} chars)")
|
||||
|
||||
suspicious = check_suspicious_claims(d)
|
||||
if suspicious:
|
||||
issues["suspicious_claim"].extend(suspicious)
|
||||
|
||||
return report, dict(issues)
|
||||
|
||||
|
||||
def validate_meta_feed(ad):
|
||||
spec = PLATFORM_SPECS["meta_feed"]
|
||||
issues = defaultdict(list)
|
||||
report = []
|
||||
|
||||
primary = ad.get("primary_text", "")
|
||||
headline = ad.get("headline", "")
|
||||
|
||||
if primary:
|
||||
length = count_chars(primary)
|
||||
status = "✅" if length <= spec["primary_text_max"] else "⚠️ (preview truncated)"
|
||||
report.append(f" Primary text: {status} ({length}/{spec['primary_text_max']} preview chars)")
|
||||
if length > spec["primary_text_max"]:
|
||||
issues["char_over_limit"].append(f"Primary text {length} chars exceeds {spec['primary_text_max']}-char preview")
|
||||
|
||||
for check_fn, key in [
|
||||
(check_all_caps, "all_caps"),
|
||||
(check_excessive_punctuation, "excessive_punctuation"),
|
||||
(check_trademark_mentions, "trademark_mention"),
|
||||
(check_prohibited_phrases, "prohibited_phrase"),
|
||||
(check_suspicious_claims, "suspicious_claim"),
|
||||
]:
|
||||
result = check_fn(primary)
|
||||
if result:
|
||||
issues[key].extend(result if isinstance(result, list) else [str(result)])
|
||||
|
||||
if headline:
|
||||
length = count_chars(headline)
|
||||
status = "✅" if length <= spec["headline_max"] else "❌"
|
||||
if length > spec["headline_max"]:
|
||||
issues["char_over_limit"].append(f"Headline {length} chars (max {spec['headline_max']})")
|
||||
report.append(f" Headline: {status} '{headline}' ({length}/{spec['headline_max']} chars)")
|
||||
|
||||
return report, dict(issues)
|
||||
|
||||
|
||||
def validate_linkedin(ad):
|
||||
spec = PLATFORM_SPECS["linkedin"]
|
||||
issues = defaultdict(list)
|
||||
report = []
|
||||
|
||||
intro = ad.get("intro_text", ad.get("primary_text", ""))
|
||||
headline = ad.get("headline", "")
|
||||
|
||||
if intro:
|
||||
length = count_chars(intro)
|
||||
status = "✅" if length <= spec["intro_text_max"] else "⚠️ (preview truncated)"
|
||||
report.append(f" Intro text: {status} ({length}/{spec['intro_text_max']} preview chars)")
|
||||
if length > spec["intro_text_max"]:
|
||||
issues["char_over_limit"].append(f"Intro text {length} chars exceeds {spec['intro_text_max']}-char preview")
|
||||
|
||||
for check_fn, key in [
|
||||
(check_all_caps, "all_caps"),
|
||||
(check_excessive_punctuation, "excessive_punctuation"),
|
||||
(check_trademark_mentions, "trademark_mention"),
|
||||
]:
|
||||
result = check_fn(intro)
|
||||
if result:
|
||||
issues[key].extend(result if isinstance(result, list) else [str(result)])
|
||||
|
||||
if headline:
|
||||
length = count_chars(headline)
|
||||
status = "✅" if length <= spec["headline_max"] else "❌"
|
||||
if length > spec["headline_max"]:
|
||||
issues["char_over_limit"].append(f"Headline {length} chars (max {spec['headline_max']})")
|
||||
report.append(f" Headline: {status} '{headline}' ({length}/{spec['headline_max']} chars)")
|
||||
|
||||
return report, dict(issues)
|
||||
|
||||
|
||||
def validate_generic(ad, platform_key):
|
||||
spec = PLATFORM_SPECS.get(platform_key, {})
|
||||
issues = defaultdict(list)
|
||||
report = []
|
||||
|
||||
text = ad.get("primary_text", ad.get("text", ""))
|
||||
max_chars = spec.get("primary_text_max", 280)
|
||||
|
||||
if text:
|
||||
length = count_chars(text)
|
||||
status = "✅" if length <= max_chars else "❌"
|
||||
if length > max_chars:
|
||||
issues["char_over_limit"].append(f"Text {length} chars (max {max_chars})")
|
||||
report.append(f" Text: {status} ({length}/{max_chars} chars)")
|
||||
|
||||
for check_fn, key in [
|
||||
(check_all_caps, "all_caps"),
|
||||
(check_excessive_punctuation, "excessive_punctuation"),
|
||||
(check_trademark_mentions, "trademark_mention"),
|
||||
(check_prohibited_phrases, "prohibited_phrase"),
|
||||
]:
|
||||
result = check_fn(text)
|
||||
if result:
|
||||
issues[key].extend(result if isinstance(result, list) else [str(result)])
|
||||
|
||||
return report, dict(issues)
|
||||
|
||||
|
||||
def validate_ad(ad):
|
||||
platform = ad.get("platform", "").lower()
|
||||
|
||||
if platform == "google_rsa":
|
||||
return validate_google_rsa(ad)
|
||||
elif platform == "meta_feed":
|
||||
return validate_meta_feed(ad)
|
||||
elif platform == "linkedin":
|
||||
return validate_linkedin(ad)
|
||||
elif platform in ("twitter", "tiktok"):
|
||||
return validate_generic(ad, platform)
|
||||
else:
|
||||
return [f" ⚠️ Unknown platform '{platform}' — using generic validation"], {}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Reporting
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def format_report(ad, char_lines, issues):
|
||||
platform = ad.get("platform", "unknown")
|
||||
spec = PLATFORM_SPECS.get(platform, {})
|
||||
platform_name = spec.get("name", platform.upper())
|
||||
|
||||
score = score_ad(issues)
|
||||
grade = "🟢 Excellent" if score >= 85 else "🟡 Needs Work" if score >= 60 else "🔴 High Risk"
|
||||
|
||||
lines = []
|
||||
lines.append(f"\n{'='*60}")
|
||||
lines.append(f"Platform: {platform_name}")
|
||||
lines.append(f"Quality Score: {score}/100 {grade}")
|
||||
lines.append(f"{'='*60}")
|
||||
|
||||
lines.append("\nCharacter Counts:")
|
||||
lines.extend(char_lines)
|
||||
|
||||
if issues:
|
||||
lines.append("\nIssues Found:")
|
||||
category_labels = {
|
||||
"char_over_limit": "❌ Over character limit",
|
||||
"all_caps": "⚠️ ALL CAPS words",
|
||||
"excessive_punctuation": "⚠️ Excessive punctuation",
|
||||
"trademark_mention": "🚫 Trademarked term",
|
||||
"prohibited_phrase": "🚫 Prohibited phrase",
|
||||
"suspicious_claim": "🚨 Suspicious claim (review required)",
|
||||
"count_too_few": "⚠️ Too few elements",
|
||||
"count_too_many": "⚠️ Too many elements",
|
||||
}
|
||||
for category, items in issues.items():
|
||||
label = category_labels.get(category, category)
|
||||
lines.append(f" {label}: {', '.join(str(i) for i in items)}")
|
||||
else:
|
||||
lines.append("\n✅ No rejection triggers found.")
|
||||
|
||||
lines.append("")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Sample data (embedded — runs with zero config)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
SAMPLE_ADS = [
|
||||
{
|
||||
"platform": "google_rsa",
|
||||
"headlines": [
|
||||
"Cut Reporting Time by 80%", # 26 chars ✅
|
||||
"Automated Reports, Zero Effort", # 31 chars ❌ over limit
|
||||
"Your Data. Your Way. Every Week.", # 33 chars ❌ over limit
|
||||
"Save 8 Hours Per Week on Reports", # 32 chars ❌ over limit
|
||||
"Try Free for 14 Days", # 21 chars ✅
|
||||
"No Code. No Complexity. Just Results.", # 38 chars ❌
|
||||
"5,000 Teams Use This", # 21 chars ✅
|
||||
"Replace Your Weekly Standup Deck", # 32 chars ❌
|
||||
"Connect Your Tools in 15 Minutes", # 32 chars ❌
|
||||
"Instant Dashboards for Your Team", # 32 chars ❌
|
||||
"Start Free — No Credit Card", # 28 chars ✅
|
||||
"Built for Growth Teams", # 22 chars ✅
|
||||
"See Your KPIs at a Glance", # 25 chars ✅
|
||||
"Data-Driven Decisions, Made Easy", # 32 chars ❌
|
||||
"GUARANTEED Results — Try Now!!!", # 31 chars ❌ + ALL CAPS + excessive punct
|
||||
],
|
||||
"descriptions": [
|
||||
"Connect your tools, set your KPIs, and let the platform handle the weekly reporting. Free 14-day trial.", # 103 chars ❌
|
||||
"Stop wasting Monday mornings on spreadsheets. Automated reports your whole team actually reads.", # 94 chars ❌
|
||||
],
|
||||
},
|
||||
{
|
||||
"platform": "meta_feed",
|
||||
"primary_text": "Your team is shipping features, but nobody can see the impact. [Product] connects your tools and shows you exactly what's working — in one dashboard, updated automatically. Start free today.",
|
||||
"headline": "See Your Impact, Automatically",
|
||||
},
|
||||
{
|
||||
"platform": "linkedin",
|
||||
"intro_text": "Growth teams at 3,200+ companies use [Product] to replace their manual weekly reports with automated dashboards.",
|
||||
"headline": "Automated Reporting for Growth Teams",
|
||||
},
|
||||
{
|
||||
"platform": "twitter",
|
||||
"primary_text": "Stop spending 8 hours on a report nobody reads. [Product] automates it — connect your tools, set your KPIs, and it runs itself. Free trial → [link]",
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Main
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def main():
|
||||
# Load from file or stdin, else use sample
|
||||
ads = None
|
||||
|
||||
if len(sys.argv) > 1:
|
||||
try:
|
||||
with open(sys.argv[1]) as f:
|
||||
data = json.load(f)
|
||||
ads = data if isinstance(data, list) else [data]
|
||||
except Exception as e:
|
||||
print(f"Error reading file: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
elif not sys.stdin.isatty():
|
||||
raw = sys.stdin.read().strip()
|
||||
if raw:
|
||||
try:
|
||||
data = json.loads(raw)
|
||||
ads = data if isinstance(data, list) else [data]
|
||||
except Exception as e:
|
||||
print(f"Error reading stdin: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
else:
|
||||
print("No input provided — running embedded sample ads.\n")
|
||||
ads = SAMPLE_ADS
|
||||
else:
|
||||
print("No input provided — running embedded sample ads.\n")
|
||||
ads = SAMPLE_ADS
|
||||
|
||||
# Aggregate results for JSON output
|
||||
results = []
|
||||
all_output = []
|
||||
|
||||
for ad in ads:
|
||||
char_lines, issues = validate_ad(ad)
|
||||
score = score_ad(issues)
|
||||
report_text = format_report(ad, char_lines, issues)
|
||||
all_output.append(report_text)
|
||||
results.append({
|
||||
"platform": ad.get("platform"),
|
||||
"score": score,
|
||||
"issues": {k: v for k, v in issues.items()},
|
||||
"passed": score >= 70,
|
||||
})
|
||||
|
||||
# Human-readable output
|
||||
for block in all_output:
|
||||
print(block)
|
||||
|
||||
# Summary
|
||||
avg_score = sum(r["score"] for r in results) / len(results) if results else 0
|
||||
passed = sum(1 for r in results if r["passed"])
|
||||
print(f"\nSUMMARY: {passed}/{len(results)} ads passed (avg score: {avg_score:.0f}/100)")
|
||||
|
||||
# JSON output to stdout (for programmatic use) — write to separate section
|
||||
print("\n--- JSON Output ---")
|
||||
print(json.dumps(results, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
331
marketing-skill/ai-seo/SKILL.md
Normal file
331
marketing-skill/ai-seo/SKILL.md
Normal file
@@ -0,0 +1,331 @@
|
||||
---
|
||||
name: ai-seo
|
||||
description: "Optimize content to get cited by AI search engines — ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, Copilot. Use when you want your content to appear in AI-generated answers, not just ranked in blue links. Triggers: 'optimize for AI search', 'get cited by ChatGPT', 'AI Overviews', 'Perplexity citations', 'AI SEO', 'generative search', 'LLM visibility', 'GEO' (generative engine optimization). NOT for traditional SEO ranking (use seo-audit). NOT for content creation (use content-production)."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# AI SEO
|
||||
|
||||
You are an expert in generative engine optimization (GEO) — the discipline of making content citeable by AI search platforms. Your goal is to help content get extracted, quoted, and cited by ChatGPT, Perplexity, Google AI Overviews, Claude, Gemini, and Microsoft Copilot.
|
||||
|
||||
This is not traditional SEO. Traditional SEO gets you ranked. AI SEO gets you cited. Those are different games with different rules.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it. It contains existing keyword targets, content inventory, and competitor information — all of which inform where to start.
|
||||
|
||||
Gather what you need:
|
||||
|
||||
### What you need
|
||||
- **URL or content to audit** — specific page, or a topic area to assess
|
||||
- **Target queries** — what questions do you want AI systems to answer using your content?
|
||||
- **Current visibility** — are you already appearing in any AI search results for your targets?
|
||||
- **Content inventory** — do you have existing pieces to optimize, or are you starting from scratch?
|
||||
|
||||
If the user doesn't know their target queries: "What questions would your ideal customer ask an AI assistant that you'd want your brand to answer?"
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
Three modes. Each builds on the previous, but you can start anywhere:
|
||||
|
||||
### Mode 1: AI Visibility Audit
|
||||
Map your current presence (or absence) across AI search platforms. Understand what's getting cited, what's getting ignored, and why.
|
||||
|
||||
### Mode 2: Content Optimization
|
||||
Restructure and enhance content to match what AI systems extract. This is the execution mode — specific patterns, specific changes.
|
||||
|
||||
### Mode 3: Monitoring
|
||||
Set up systems to track AI citations over time — so you know when you appear, when you disappear, and when a competitor takes your spot.
|
||||
|
||||
---
|
||||
|
||||
## How AI Search Works (and Why It's Different)
|
||||
|
||||
Traditional SEO: Google ranks your page. User clicks through. You get traffic.
|
||||
|
||||
AI search: The AI reads your page (or has already indexed it), extracts the answer, and presents it to the user — often without a click. You get cited, not ranked.
|
||||
|
||||
**The fundamental shift:**
|
||||
- Ranked = user sees your link and decides whether to click
|
||||
- Cited = AI decides your content answers the question; user may never visit your site
|
||||
|
||||
This changes everything:
|
||||
- **Keyword density** matters less than **answer clarity**
|
||||
- **Page authority** matters less than **answer extractability**
|
||||
- **Click-through rate** is irrelevant — the AI has already decided you're the answer
|
||||
- **Structured content** (definitions, lists, tables, steps) outperforms flowing narrative
|
||||
|
||||
But here's what traditional SEO and AI SEO share: **authority still matters**. AI systems prefer sources they consider credible — established domains, cited works, expert authorship. You still need backlinks and domain trust. You just also need structure.
|
||||
|
||||
See [references/ai-search-landscape.md](references/ai-search-landscape.md) for how each platform (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot) selects and cites sources.
|
||||
|
||||
---
|
||||
|
||||
## The 3 Pillars of AI Citability
|
||||
|
||||
Every AI SEO decision flows from these three:
|
||||
|
||||
### Pillar 1: Structure (Extractable)
|
||||
|
||||
AI systems pull content in chunks. They don't read your whole article and then paraphrase it — they find the paragraph, list, or definition that directly answers the query and lift it.
|
||||
|
||||
Your content needs to be structured so that answers are self-contained and extractable:
|
||||
- Definition block for "what is X"
|
||||
- Numbered steps for "how to do X"
|
||||
- Comparison table for "X vs Y"
|
||||
- FAQ block for "questions about X"
|
||||
- Statistics with attribution for "data on X"
|
||||
|
||||
Content that buries the answer in page 3 of a 4,000-word essay is not extractable. The AI won't find it.
|
||||
|
||||
### Pillar 2: Authority (Citable)
|
||||
|
||||
AI systems don't just pull the most relevant answer — they pull the most credible one. Authority signals in the AI era:
|
||||
|
||||
- **Domain authority**: High-DA domains get preferential treatment (traditional SEO signal still applies)
|
||||
- **Author attribution**: Named authors with credentials beat anonymous pages
|
||||
- **Citation chain**: Your content cites credible sources → you're seen as credible in turn
|
||||
- **Recency**: AI systems prefer current information for time-sensitive queries
|
||||
- **Original data**: Pages with proprietary research, surveys, or studies get cited more — AI systems value unique data they can't get elsewhere
|
||||
|
||||
### Pillar 3: Presence (Discoverable)
|
||||
|
||||
AI systems need to be able to find and index your content. This is the technical layer:
|
||||
|
||||
- **Bot access**: AI crawlers must be allowed in robots.txt (GPTBot, PerplexityBot, ClaudeBot, etc.)
|
||||
- **Crawlability**: Fast page load, clean HTML, no JavaScript-only content
|
||||
- **Schema markup**: Structured data (Article, FAQPage, HowTo, Product) helps AI systems understand your content type
|
||||
- **Canonical signals**: Duplicate content confuses AI systems even more than traditional search
|
||||
- **HTTPS and security**: AI crawlers won't index pages with security warnings
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: AI Visibility Audit
|
||||
|
||||
### Step 1 — Bot Access Check
|
||||
|
||||
First: confirm AI crawlers can access your site.
|
||||
|
||||
**Check robots.txt** at `yourdomain.com/robots.txt`. Verify these bots are NOT blocked:
|
||||
|
||||
```
|
||||
# Should NOT be blocked (allow AI indexing):
|
||||
GPTBot # OpenAI / ChatGPT
|
||||
PerplexityBot # Perplexity
|
||||
ClaudeBot # Anthropic / Claude
|
||||
Google-Extended # Google AI Overviews
|
||||
anthropic-ai # Anthropic (alternate identifier)
|
||||
Applebot-Extended # Apple Intelligence
|
||||
cohere-ai # Cohere
|
||||
```
|
||||
|
||||
If any AI bot is blocked, flag it. That's an immediate visibility killer for that platform.
|
||||
|
||||
**robots.txt to allow all AI bots:**
|
||||
```
|
||||
User-agent: GPTBot
|
||||
Allow: /
|
||||
|
||||
User-agent: PerplexityBot
|
||||
Allow: /
|
||||
|
||||
User-agent: ClaudeBot
|
||||
Allow: /
|
||||
|
||||
User-agent: Google-Extended
|
||||
Allow: /
|
||||
```
|
||||
|
||||
To block specific AI training while allowing search: use `Disallow:` selectively, but understand that blocking training ≠ blocking citation — they're often the same crawl.
|
||||
|
||||
### Step 2 — Current Citation Audit
|
||||
|
||||
Manually test your target queries on each platform:
|
||||
|
||||
| Platform | How to test |
|
||||
|---|---|
|
||||
| Perplexity | Search your target query at perplexity.ai — check Sources panel |
|
||||
| ChatGPT | Search with web browsing enabled — check citations |
|
||||
| Google AI Overviews | Google your query — check if AI Overview appears, who's cited |
|
||||
| Microsoft Copilot | Search at copilot.microsoft.com — check source cards |
|
||||
|
||||
For each query, document:
|
||||
- Are you cited? (yes/no)
|
||||
- Which competitors are cited?
|
||||
- What content type gets cited? (definition? list? stats?)
|
||||
- How is the answer structured?
|
||||
|
||||
This tells you the pattern that's currently winning. Build toward it.
|
||||
|
||||
### Step 3 — Content Structure Audit
|
||||
|
||||
Review your key pages against the Extractability Checklist:
|
||||
|
||||
- [ ] Does the page have a clear, answerable definition of its core concept in the first 200 words?
|
||||
- [ ] Are there numbered lists or step-by-step sections for process-oriented queries?
|
||||
- [ ] Does the page have a FAQ section with direct Q&A pairs?
|
||||
- [ ] Are statistics and data points cited with source name and year?
|
||||
- [ ] Are comparisons done in table format (not narrative)?
|
||||
- [ ] Is the page's H1 phrased as the answer to a question, or as a statement?
|
||||
- [ ] Does schema markup exist? (FAQPage, HowTo, Article, etc.)
|
||||
|
||||
Score: 0-3 checks = needs major restructuring. 4-5 = good baseline. 6-7 = strong.
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Content Optimization
|
||||
|
||||
### The Content Patterns That Get Cited
|
||||
|
||||
These are the block types AI systems reliably extract. Add at least 2-3 per key page.
|
||||
|
||||
See [references/content-patterns.md](references/content-patterns.md) for ready-to-use templates for each pattern.
|
||||
|
||||
**Pattern 1: Definition Block**
|
||||
The AI's answer to "what is X" almost always comes from a tight, self-contained definition. Format:
|
||||
|
||||
> **[Term]** is [concise definition in 1-2 sentences]. [One sentence of context or why it matters].
|
||||
|
||||
Placed within the first 300 words of the page. No hedging, no preamble. Just the definition.
|
||||
|
||||
**Pattern 2: Numbered Steps (How-To)**
|
||||
For process queries ("how do I X"), AI systems pull numbered steps almost universally. Requirements:
|
||||
- Steps are numbered
|
||||
- Each step is actionable (verb-first)
|
||||
- Each step is self-contained (could be quoted alone and still make sense)
|
||||
- 5-10 steps maximum (AI truncates longer lists)
|
||||
|
||||
**Pattern 3: Comparison Table**
|
||||
"X vs Y" queries almost always result in table citations. Two-column tables comparing features, costs, pros/cons — these get extracted verbatim. Format matters: clean markdown table with headers wins.
|
||||
|
||||
**Pattern 4: FAQ Block**
|
||||
Explicit Q&A pairs signal to AI: "this is the question, this is the answer." Mark up with FAQPage schema. Questions should exactly match how people phrase queries (voice search, question-style).
|
||||
|
||||
**Pattern 5: Statistics With Attribution**
|
||||
"According to [Source Name] ([Year]), X% of [population] [finding]." This format is extractable because it has a complete citation. Naked statistics without attribution get deprioritized — the AI can't verify the source.
|
||||
|
||||
**Pattern 6: Expert Quote Block**
|
||||
Attributed quotes from named experts get cited. The AI picks up: "According to [Name], [Role at Organization]: '[quote]'" as a citable unit. Build in a few of these per key piece.
|
||||
|
||||
### Rewriting for Extractability
|
||||
|
||||
When optimizing existing content:
|
||||
|
||||
1. **Lead with the answer** — The first paragraph should contain the core answer to the target query. Don't save it for the conclusion.
|
||||
|
||||
2. **Self-contained sections** — Every H2 section should be answerable as a standalone excerpt. If you have to read the introduction to understand a section, it's not self-contained.
|
||||
|
||||
3. **Specific over vague** — "Response time improved by 40%" beats "significant improvement." AI systems prefer citable specifics.
|
||||
|
||||
4. **Plain language summaries** — After complex explanations, add a 1-2 sentence plain language summary. This is what AI often lifts.
|
||||
|
||||
5. **Named sources** — Replace "experts say" with "[Researcher Name], [Year]." Replace "studies show" with "[Organization] found in their [Year] survey."
|
||||
|
||||
### Schema Markup for AI Discoverability
|
||||
|
||||
Schema doesn't directly make you appear in AI results — but it helps AI systems understand your content type and structure. Priority schemas:
|
||||
|
||||
| Schema Type | Use When | Impact |
|
||||
|---|---|---|
|
||||
| `Article` | Any editorial content | Establishes content as authoritative information |
|
||||
| `FAQPage` | You have FAQ section | High — AI extracts Q&A pairs directly |
|
||||
| `HowTo` | Step-by-step guides | High — AI uses step structure for process queries |
|
||||
| `Product` | Product pages | Medium — appears in product comparison queries |
|
||||
| `Organization` | Company pages | Medium — establishes entity authority |
|
||||
| `Person` | Author pages | Medium — author credibility signal |
|
||||
|
||||
Implement via JSON-LD in the page `<head>`. Validate at schema.org/validator.
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Monitoring
|
||||
|
||||
AI search is volatile. Citations change. Track them.
|
||||
|
||||
### Manual Citation Tracking
|
||||
|
||||
Weekly: test your top 10 target queries on Perplexity and ChatGPT. Log:
|
||||
- Were you cited? (yes/no)
|
||||
- Rank in citations (1st source, 2nd, etc.)
|
||||
- What text was used?
|
||||
|
||||
This takes ~20 minutes/week. Do it before automated solutions exist (they don't yet, not reliably).
|
||||
|
||||
### Google Search Console for AI Overviews
|
||||
|
||||
Google Search Console now shows impressions in AI Overviews under "Search type: AI Overviews" filter. Check:
|
||||
- Which queries trigger AI Overview impressions for your site
|
||||
- Click-through rate from AI Overviews (typically 50-70% lower than organic)
|
||||
- Which pages get cited
|
||||
|
||||
### Visibility Signals to Track
|
||||
|
||||
| Signal | Tool | Frequency |
|
||||
|---|---|---|
|
||||
| Perplexity citations | Manual query testing | Weekly |
|
||||
| ChatGPT citations | Manual query testing | Weekly |
|
||||
| Google AI Overviews | Google Search Console | Weekly |
|
||||
| Copilot citations | Manual query testing | Monthly |
|
||||
| AI bot crawl activity | Server logs or Cloudflare | Monthly |
|
||||
| Competitor AI citations | Manual query testing | Monthly |
|
||||
|
||||
See [references/monitoring-guide.md](references/monitoring-guide.md) for the full tracking setup and templates.
|
||||
|
||||
### When Your Citations Drop
|
||||
|
||||
If you were cited and suddenly aren't:
|
||||
1. Check if competitors published something more extractable on the same topic
|
||||
2. Check if your robots.txt changed (block AI bots = instant disappearance)
|
||||
3. Check if your page structure changed significantly (restructuring can break citation patterns)
|
||||
4. Check if your domain authority dropped (backlink loss affects AI citation too)
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Flag these without being asked:
|
||||
|
||||
- **AI bots blocked in robots.txt** — If GPTBot, PerplexityBot, or ClaudeBot are blocked, flag it immediately. Zero AI visibility is possible until fixed, and it's a 5-minute fix. This trumps everything else.
|
||||
- **No definition block on target pages** — If the page targets informational queries but has no self-contained definition in the first 300 words, it won't win definitional AI Overviews. Flag before doing anything else.
|
||||
- **Unattributed statistics** — If key pages contain statistics without named sources and years, they're less citable than competitor pages that do. Flag all naked stats.
|
||||
- **Schema markup absent** — If the site has no FAQPage or HowTo schema on relevant pages, flag it as a quick structural win with asymmetric impact for process and FAQ queries.
|
||||
- **JavaScript-rendered content** — If important content only appears after JavaScript execution, AI crawlers may not see it at all. Flag content that's hidden behind JS rendering.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---|---|
|
||||
| AI visibility audit | Platform-by-platform citation test results + robots.txt check + content structure scorecard |
|
||||
| Page optimization | Rewritten page with definition block, extractable patterns, schema markup spec, and comparison to original |
|
||||
| robots.txt fix | Updated robots.txt with correct AI bot allow rules + explanation of what each bot is |
|
||||
| Schema markup | JSON-LD implementation code for FAQPage, HowTo, or Article — ready to paste |
|
||||
| Monitoring setup | Weekly tracking template + Google Search Console filter guide + citation log spreadsheet structure |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding includes all three
|
||||
- **Actions have owners and deadlines** — no "consider reviewing..."
|
||||
- **Confidence tagging** — 🟢 verified (confirmed by citation test) / 🟡 medium (pattern-based) / 🔴 assumed (extrapolated from limited data)
|
||||
|
||||
AI SEO is still a young field. Be honest about confidence levels. What gets cited can change as platforms evolve. State what's proven vs. what's pattern-matching.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **content-production**: Use to create the underlying content before optimizing for AI citation. Good AI SEO requires good content first.
|
||||
- **content-humanizer**: Use after writing for AI SEO. AI-sounding content ironically performs worse in AI citation — AI systems prefer content that reads credibly, which usually means human-sounding.
|
||||
- **seo-audit**: Use for traditional search ranking optimization. Run both — AI SEO and traditional SEO are complementary, not competing. Many signals overlap.
|
||||
- **content-strategy**: Use when deciding which topics and queries to target for AI visibility. Strategy first, then optimize.
|
||||
191
marketing-skill/ai-seo/references/ai-search-landscape.md
Normal file
191
marketing-skill/ai-seo/references/ai-search-landscape.md
Normal file
@@ -0,0 +1,191 @@
|
||||
# AI Search Landscape
|
||||
|
||||
How each major AI search platform selects, weights, and cites sources. Use this to calibrate your optimization strategy per platform.
|
||||
|
||||
Last updated: 2026-03 — this landscape changes fast. Verify platform behavior with manual testing before making major decisions.
|
||||
|
||||
---
|
||||
|
||||
## The Fundamental Model
|
||||
|
||||
Every AI search platform follows the same broad pipeline:
|
||||
|
||||
1. **Index** — Crawl and store web content (or use a third-party index)
|
||||
2. **Retrieve** — For a given query, retrieve candidate documents
|
||||
3. **Extract** — Pull the most relevant passages from those documents
|
||||
4. **Generate** — Synthesize an answer, often citing the sources
|
||||
5. **Present** — Show the answer to the user, with or without sources visible
|
||||
|
||||
Your leverage points are steps 1-3. By the time generation happens, you've either been selected or you haven't.
|
||||
|
||||
---
|
||||
|
||||
## Platform-by-Platform Breakdown
|
||||
|
||||
### Google AI Overviews
|
||||
|
||||
**What it is:** AI-generated answer boxes appearing above organic search results. Rollout expanded globally in 2024-2025.
|
||||
|
||||
**How it selects sources:**
|
||||
- Uses Google's own index (you must rank in traditional Google search first — this is NOT optional)
|
||||
- Strongly prefers pages that already rank in the top 10 for the query
|
||||
- Favors content with structured data (FAQPage, HowTo schemas)
|
||||
- The featured passage is typically lifted from a page's most extractable paragraph — usually a definition or a direct answer near the top
|
||||
- Recency matters more here than elsewhere for news-adjacent queries
|
||||
|
||||
**Citation behavior:**
|
||||
- Shows 3-7 source links typically
|
||||
- Cited sources don't always correlate with position 1-3 in organic results
|
||||
- Pages that had featured snippets before AI Overviews launched tend to appear in AI Overviews
|
||||
|
||||
**What to prioritize for Google AI Overviews:**
|
||||
1. Rank in traditional search first (prerequisite)
|
||||
2. Add FAQPage schema
|
||||
3. Put a direct answer in the first 200 words
|
||||
4. Get backlinks from high-authority sites (still matters)
|
||||
5. Set `Google-Extended` to Allow in robots.txt
|
||||
|
||||
**Monitoring:** Google Search Console → Performance → Search type: AI Overviews
|
||||
|
||||
---
|
||||
|
||||
### ChatGPT (with Browsing / Search)
|
||||
|
||||
**What it is:** OpenAI's ChatGPT has web browsing capability (via Bing) plus its own live search product. When users ask factual questions or enable browsing, it retrieves and cites web sources.
|
||||
|
||||
**How it selects sources:**
|
||||
- Uses Bing's index (Microsoft partnership) — Bing crawl and indexing quality matters
|
||||
- GPTBot also crawls independently for training data (distinct from search citations)
|
||||
- For search-backed answers: pulls several sources, synthesizes, cites inline
|
||||
- Prefers authoritative domains — news outlets, Wikipedia, academic sources, established company blogs
|
||||
- Content with clear, extractable answers wins over dense narrative
|
||||
|
||||
**Citation behavior:**
|
||||
- Inline citations in the answer ("according to [Source]")
|
||||
- Sources panel at the bottom
|
||||
- Not all cited sources get equal weight in the synthesis
|
||||
|
||||
**What to prioritize for ChatGPT:**
|
||||
1. Ensure Bing has indexed your pages (submit to Bing Webmaster Tools)
|
||||
2. Allow `GPTBot` in robots.txt
|
||||
3. Structure content with explicit definition and step patterns
|
||||
4. Author attribution with credentials helps — include author bylines
|
||||
5. Original data and research get preferential citation
|
||||
|
||||
**Bing indexing check:** Bing Webmaster Tools → URL Inspection
|
||||
|
||||
---
|
||||
|
||||
### Perplexity
|
||||
|
||||
**What it is:** AI-native search engine built on real-time web retrieval. Every answer cites sources with a numbered reference panel. Among the most transparent about citation.
|
||||
|
||||
**How it selects sources:**
|
||||
- Has its own crawler (PerplexityBot) plus access to third-party indexes
|
||||
- Real-time retrieval for every query — very current
|
||||
- Strongly rewards structural clarity: numbered lists, definition blocks, tables
|
||||
- Tends to pull from multiple perspectives on a query (shows variety in citations)
|
||||
- Recency bias is strong — old content competes poorly against recent content on current topics
|
||||
|
||||
**Citation behavior:**
|
||||
- Numbers every cited source
|
||||
- Shows the exact passage it pulled from (if you inspect carefully)
|
||||
- Citations appear inline and in a source panel
|
||||
|
||||
**What to prioritize for Perplexity:**
|
||||
1. Allow `PerplexityBot` in robots.txt (critical)
|
||||
2. Use numbered lists, definition blocks, and tables extensively
|
||||
3. Keep content current — update pages when information changes
|
||||
4. For competitive topics, publish comprehensive pieces that cover the query more completely than alternatives
|
||||
5. Include specific data with dates ("In Q1 2025, X% of...") — Perplexity responds strongly to timestamped specifics
|
||||
|
||||
**Tracking:** Perplexity doesn't offer a publisher dashboard. Manual testing is the only method currently.
|
||||
|
||||
---
|
||||
|
||||
### Claude (Anthropic)
|
||||
|
||||
**What it is:** Claude.ai now has web search capability. When users ask questions that require current information, Claude retrieves and cites sources.
|
||||
|
||||
**How it selects sources:**
|
||||
- Uses a third-party search index (search partnership)
|
||||
- ClaudeBot crawls for training purposes — separate from search citations
|
||||
- Prefers clearly structured, credible content
|
||||
- High-authority domains get preference
|
||||
- Technical and expert-authored content performs well given Claude's user base
|
||||
|
||||
**Citation behavior:**
|
||||
- Inline citations in responses
|
||||
- Source list at end of response
|
||||
- Tends toward fewer, higher-quality citations vs. showing many sources
|
||||
|
||||
**What to prioritize for Claude:**
|
||||
1. Allow `ClaudeBot` and `anthropic-ai` in robots.txt
|
||||
2. Focus on content quality and accuracy — Claude's users are often technical and will notice errors
|
||||
3. Expert authorship and institutional credibility matter here
|
||||
4. Long-form, well-researched pieces tend to perform better than thin listicles
|
||||
|
||||
---
|
||||
|
||||
### Google Gemini
|
||||
|
||||
**What it is:** Google's AI assistant, separate from Google Search but increasingly integrated. Uses Google's web index.
|
||||
|
||||
**How it selects sources:**
|
||||
- Full access to Google's index
|
||||
- Similar selection criteria to Google AI Overviews but different interface
|
||||
- Schema markup influences what Gemini can understand about your content type
|
||||
- Prefers content that directly answers conversational queries
|
||||
|
||||
**What to prioritize for Gemini:**
|
||||
- Same fundamentals as Google AI Overviews (they share the index)
|
||||
- Conversational phrasing in your content helps — Gemini handles voice/chat-style queries
|
||||
- Allow `Google-Extended` in robots.txt (covers both AI Overviews and Gemini)
|
||||
|
||||
---
|
||||
|
||||
### Microsoft Copilot
|
||||
|
||||
**What it is:** Microsoft's AI assistant integrated into Bing, Windows, Office 365, and Edge. Uses Bing's index.
|
||||
|
||||
**How it selects sources:**
|
||||
- Bing index (same as ChatGPT browsing)
|
||||
- Integrated into productivity contexts — Office documents, business queries
|
||||
- B2B and professional content performs particularly well
|
||||
- Bing's relevance signals apply
|
||||
|
||||
**Citation behavior:**
|
||||
- Source cards in the Copilot interface
|
||||
- Inline citations in longer answers
|
||||
|
||||
**What to prioritize for Copilot:**
|
||||
- Ensure strong Bing indexing (submit to Bing Webmaster Tools, build Bing-friendly signals)
|
||||
- For B2B companies: professional tone and industry-specific expertise matters more here
|
||||
- FAQ and definition patterns work well for business query types
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Summary
|
||||
|
||||
| Signal | Google AI Overviews | ChatGPT | Perplexity | Claude | Copilot |
|
||||
|---|---|---|---|---|---|
|
||||
| Must rank in traditional search | ✅ Yes | Bing only | No | No | Bing only |
|
||||
| Bot to allow | Google-Extended | GPTBot | PerplexityBot | ClaudeBot | (via Bing) |
|
||||
| Schema markup impact | High | Medium | Low | Medium | Medium |
|
||||
| Content recency weight | High | Medium | Very high | Medium | Medium |
|
||||
| Original data advantage | High | High | High | High | High |
|
||||
| FAQ pattern extraction | Very high | High | High | Medium | High |
|
||||
| Numbered steps extraction | High | High | Very high | High | High |
|
||||
| Author attribution impact | Medium | High | Low | High | Medium |
|
||||
|
||||
---
|
||||
|
||||
## What No Platform Does (Yet)
|
||||
|
||||
Things that are widely assumed but not confirmed:
|
||||
|
||||
- **Direct "opt-in to citations" programs**: None of the major platforms have a verified publisher program that guarantees citation
|
||||
- **Predictable citation ranking**: Even with perfect structure, citations are non-deterministic — the same query on the same platform can produce different citations on consecutive days
|
||||
- **Real-time citation tracking**: No platform offers publishers a dashboard showing when they're cited and for which queries (Google Search Console for AI Overviews is the closest, and it's limited)
|
||||
|
||||
Plan your AI SEO strategy for influence, not for guaranteed outcomes. Maximize your signal quality, then track and iterate.
|
||||
276
marketing-skill/ai-seo/references/content-patterns.md
Normal file
276
marketing-skill/ai-seo/references/content-patterns.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# Content Patterns for AI Citability
|
||||
|
||||
Ready-to-use block templates for each content pattern that AI search engines reliably extract and cite. Copy, adapt, and embed in your pages.
|
||||
|
||||
---
|
||||
|
||||
## Why Patterns Matter
|
||||
|
||||
AI systems don't read pages the way humans do. They scan for extractable chunks — self-contained passages that can be pulled out and quoted without losing meaning.
|
||||
|
||||
The patterns below are structured to be self-contained by design. If the AI pulls paragraph 3 without paragraph 2, the citation should still make sense.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: Definition Block
|
||||
|
||||
**Used for:** "What is X" queries — the most common AI Overview trigger.
|
||||
|
||||
**Requirements:**
|
||||
- First sentence: direct definition
|
||||
- Second sentence: why it matters or how it works
|
||||
- Third sentence (optional): example or context
|
||||
- Placed in first 300 words of the page
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**[Term]** is [precise definition — what it is, what it does, who uses it].
|
||||
[One sentence on why it matters or what problem it solves].
|
||||
[Optional: one sentence example — "For example, a SaaS company might use X to..."].
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
**Churn rate** is the percentage of customers who cancel or stop using a service within a given period, typically measured monthly or annually. It directly impacts recurring revenue — a 5% monthly churn means losing over half your customer base each year. For subscription SaaS, a healthy monthly churn rate is typically below 2%.
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Bold the term on its first use
|
||||
- Don't start with "In the world of..." or "When it comes to..."
|
||||
- The definition should work even if the reader knows nothing about the topic
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Numbered Steps (How-To)
|
||||
|
||||
**Used for:** "How to X" and "How do I X" queries.
|
||||
|
||||
**Requirements:**
|
||||
- Numbered list (not bulleted)
|
||||
- Each step starts with an action verb
|
||||
- Each step is self-contained (can be cited alone)
|
||||
- 5-10 steps maximum
|
||||
- Pair with HowTo schema markup
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
## How to [Task]
|
||||
|
||||
1. **[Verb phrase]** — [1-2 sentence explanation of this specific step]
|
||||
2. **[Verb phrase]** — [1-2 sentence explanation]
|
||||
3. **[Verb phrase]** — [1-2 sentence explanation]
|
||||
4. **[Verb phrase]** — [1-2 sentence explanation]
|
||||
5. **[Verb phrase]** — [1-2 sentence explanation]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
## How to Reduce SaaS Churn
|
||||
|
||||
1. **Define your activation event** — Identify the specific action that signals a user has experienced core product value. For Slack, it's 2,000 messages sent. For Dropbox, it's saving the first file.
|
||||
2. **Instrument the activation funnel** — Add event tracking from signup to activation. Find the step where most users drop off — that's your highest-leverage point.
|
||||
3. **Build a customer health score** — Combine login frequency, feature adoption, and support ticket volume into a single score. Customers below 40 get proactive outreach.
|
||||
4. **Segment churn by cohort** — Not all churn looks the same. Compare churn rates by acquisition channel, onboarding path, and company size to find patterns.
|
||||
5. **Interview churned customers** — The customers who left quietly are more valuable than the ones who complained. Call 10 churned accounts per month and ask what they were trying to accomplish.
|
||||
```
|
||||
|
||||
**Schema markup (JSON-LD):**
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "HowTo",
|
||||
"name": "How to [Task]",
|
||||
"step": [
|
||||
{"@type": "HowToStep", "name": "Step 1 name", "text": "Step 1 explanation"},
|
||||
{"@type": "HowToStep", "name": "Step 2 name", "text": "Step 2 explanation"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: Comparison Table
|
||||
|
||||
**Used for:** "X vs Y" and "best X for Y" queries.
|
||||
|
||||
**Requirements:**
|
||||
- Header row with category names
|
||||
- First column: feature or criterion
|
||||
- Remaining columns: the things being compared
|
||||
- Keep it focused — 5-10 rows maximum
|
||||
- Don't try to cover everything; cover what matters most
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
| Feature | [Option A] | [Option B] | [Option C] |
|
||||
|---|---|---|---|
|
||||
| [Criterion 1] | [Value] | [Value] | [Value] |
|
||||
| [Criterion 2] | [Value] | [Value] | [Value] |
|
||||
| [Criterion 3] | [Value] | [Value] | [Value] |
|
||||
| Best for | [Audience A] | [Audience B] | [Audience C] |
|
||||
| Pricing | [Range] | [Range] | [Range] |
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Put the most important criteria first
|
||||
- Use simple values — "Yes / No / Partial" beats long prose in cells
|
||||
- Include a "Best for" row — AI systems use this for recommendation queries
|
||||
- Add a sentence below the table summarizing the verdict: "X is best for teams that need A; Y is better when B matters more."
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: FAQ Block
|
||||
|
||||
**Used for:** Question-style queries, People Also Ask queries, voice search.
|
||||
|
||||
**Requirements:**
|
||||
- Question phrased exactly as someone would ask it (natural language)
|
||||
- Answer is complete in 2-4 sentences (no "read more in section 3")
|
||||
- 5-10 FAQs per block
|
||||
- Pair with FAQPage schema markup
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
## Frequently Asked Questions
|
||||
|
||||
**What is [X]?**
|
||||
[2-4 sentence complete answer]
|
||||
|
||||
**How does [X] work?**
|
||||
[2-4 sentence complete answer]
|
||||
|
||||
**What's the difference between [X] and [Y]?**
|
||||
[2-4 sentence complete answer]
|
||||
|
||||
**How much does [X] cost?**
|
||||
[2-4 sentence complete answer]
|
||||
|
||||
**Is [X] right for [audience]?**
|
||||
[2-4 sentence complete answer]
|
||||
```
|
||||
|
||||
**Schema markup (JSON-LD):**
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "FAQPage",
|
||||
"mainEntity": [
|
||||
{
|
||||
"@type": "Question",
|
||||
"name": "What is [X]?",
|
||||
"acceptedAnswer": {
|
||||
"@type": "Answer",
|
||||
"text": "Complete answer text here"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Write questions the way users actually type or speak them — use Google's "People Also Ask" as a source
|
||||
- Answers should be complete without needing context from anywhere else on the page
|
||||
- Don't start answers with "Great question" or "That's a common question" — just answer
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: Statistic with Attribution
|
||||
|
||||
**Used for:** Data queries, "how many" queries, research-backed claims.
|
||||
|
||||
**Requirements:**
|
||||
- Named source (not "a study" — the actual organization name)
|
||||
- Year of the data
|
||||
- Specific number (not "many" or "most")
|
||||
- Context (what the number means)
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
According to [Organization Name]'s [Report Name] ([Year]), [specific statistic with units]. [One sentence on what this means or why it matters].
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
According to the Baymard Institute's 2024 UX benchmarking study, 69.8% of online shopping carts are abandoned before purchase. For a $1M/month ecommerce store, recovering just 5% of abandoned carts represents $35,000 in monthly revenue.
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Link to the original source (AI systems and readers both benefit)
|
||||
- If data is from your own research, say so: "In our 2025 survey of 500 SaaS founders..."
|
||||
- Proprietary data is the highest-value citation target — AI systems actively seek original research
|
||||
|
||||
---
|
||||
|
||||
## Pattern 6: Expert Quote Block
|
||||
|
||||
**Used for:** Authority building, "what do experts say" queries.
|
||||
|
||||
**Requirements:**
|
||||
- Full name of the person quoted
|
||||
- Their title and organization
|
||||
- A quote that's substantive (not a generic endorsement)
|
||||
- Brief context sentence before the quote
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
[Context sentence explaining why this person's view matters.]
|
||||
|
||||
"[Direct quote — specific, substantive, something only they would say]," says [Full Name], [Title] at [Organization].
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```markdown
|
||||
Patrick Campbell, founder of ProfitWell (acquired by Paddle), studied pricing data from over 30,000 SaaS companies before reaching a counterintuitive conclusion about churn.
|
||||
|
||||
"Most churn that looks like pricing dissatisfaction is actually failed onboarding," says Campbell. "The customer never saw the value that justified the price. That's a different problem than being too expensive."
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Don't use generic quotes ("innovation is key to success") — they add nothing
|
||||
- Quotes should contain a specific claim, data point, or perspective
|
||||
- If quoting your own team: "[Name], [Title] at [Company Name]" is still valid
|
||||
- Live quotes (from interviews or primary research) outperform secondary quotes from other articles
|
||||
|
||||
---
|
||||
|
||||
## Pattern 7: Quick-Scan Summary Box
|
||||
|
||||
**Used for:** Queries where users want the TL;DR before committing to the full article.
|
||||
|
||||
**Requirements:**
|
||||
- Placed near the top of the article (after the intro)
|
||||
- 3-7 key takeaways
|
||||
- Each bullet stands alone — no context required
|
||||
- Labeled clearly ("Key Takeaways" or "Quick Summary")
|
||||
|
||||
**Template:**
|
||||
```markdown
|
||||
**Key Takeaways**
|
||||
- [Specific, complete takeaway — could be read as a tweet]
|
||||
- [Specific, complete takeaway]
|
||||
- [Specific, complete takeaway]
|
||||
- [Specific, complete takeaway]
|
||||
- [Specific, complete takeaway]
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- This is often the block AI systems extract for "summary" type queries
|
||||
- Make each bullet specific: "Monthly churn below 2% is considered healthy for most SaaS" beats "Churn should be low"
|
||||
- Don't repeat the article intro verbatim — these should be the most actionable insights
|
||||
|
||||
---
|
||||
|
||||
## Combining Patterns
|
||||
|
||||
The most citable pages combine multiple patterns throughout the piece:
|
||||
|
||||
**Recommended page structure for maximum AI extractability:**
|
||||
1. Definition block (first 300 words)
|
||||
2. Quick summary box (right after intro)
|
||||
3. Body sections with numbered steps or subsections
|
||||
4. Data points with full attribution throughout
|
||||
5. Comparison table (if competitive topic)
|
||||
6. FAQ block (before conclusion)
|
||||
7. Expert quote (to add authority)
|
||||
|
||||
A page with all 7 patterns has significantly more extractable surface area than a page with prose only. The AI has more options to pull from and a higher probability of finding something that perfectly matches the query.
|
||||
208
marketing-skill/ai-seo/references/monitoring-guide.md
Normal file
208
marketing-skill/ai-seo/references/monitoring-guide.md
Normal file
@@ -0,0 +1,208 @@
|
||||
# AI Visibility Monitoring Guide
|
||||
|
||||
How to track whether your content is getting cited by AI search engines — and what to do when citations change.
|
||||
|
||||
The honest truth: AI citation monitoring is immature. There's no Google Search Console equivalent for Perplexity or ChatGPT. Most tracking is manual today. This guide covers what works now and what to watch for as tooling matures.
|
||||
|
||||
---
|
||||
|
||||
## What You're Tracking
|
||||
|
||||
**Goal:** Know when you appear in AI answers, for which queries, on which platforms — and detect changes before your traffic is affected.
|
||||
|
||||
**The challenge:** Most AI search platforms don't give publishers visibility into their citation data. You're reverse-engineering your presence through manual testing and indirect signals.
|
||||
|
||||
**Four things to track:**
|
||||
1. Citation presence — are you appearing at all?
|
||||
2. Citation consistency — do you appear most of the time or occasionally?
|
||||
3. Competitor citations — who else is cited for your target queries?
|
||||
4. Traffic signals — is AI-driven traffic changing?
|
||||
|
||||
---
|
||||
|
||||
## Platform-by-Platform Monitoring
|
||||
|
||||
### Google AI Overviews — Best Current Tooling
|
||||
|
||||
Google Search Console is the best data source available for any AI platform:
|
||||
|
||||
**Setup:**
|
||||
1. Open Google Search Console → Performance → Search results
|
||||
2. Add filter: "Search type" → "AI Overviews"
|
||||
3. Set date range to last 90 days minimum
|
||||
|
||||
**What you see:**
|
||||
- Queries where your pages appeared in AI Overviews
|
||||
- Impressions from AI Overviews
|
||||
- Clicks from AI Overviews (usually much lower than organic — users get the answer in the AI box)
|
||||
- CTR from AI Overviews
|
||||
|
||||
**What to do with it:**
|
||||
- Sort by impressions: these are your current AI Overview presences
|
||||
- Sort by clicks: these are the queries where users still clicked through (high-value)
|
||||
- Identify queries where you have impressions but zero clicks — consider whether that's acceptable or if you need to gate more value behind the click
|
||||
- Watch for queries where impressions drop sharply — you may have lost an AI Overview position
|
||||
|
||||
**Frequency:** Weekly check. Pull a CSV monthly for trend analysis.
|
||||
|
||||
---
|
||||
|
||||
### Perplexity — Manual Testing Protocol
|
||||
|
||||
Perplexity has no publisher dashboard. Manual testing is the only reliable method.
|
||||
|
||||
**Weekly test protocol:**
|
||||
1. Identify your 10-20 highest-priority target queries
|
||||
2. Search each query on perplexity.ai in an incognito window
|
||||
3. Check the Sources panel on the right side
|
||||
4. Record: cited (yes/no), position in sources (1st, 2nd, 3rd...), which page was cited
|
||||
|
||||
**What to record in your tracking log:**
|
||||
|
||||
| Date | Query | Cited? | Position | Cited URL | Top Competitor |
|
||||
|---|---|---|---|---|---|
|
||||
| 2026-03-06 | "how to reduce SaaS churn" | Yes | 2 | /blog/churn-reduction | competitor.com |
|
||||
| 2026-03-06 | "SaaS churn rate benchmark" | No | — | — | competitor.com |
|
||||
|
||||
**Patterns to watch for:**
|
||||
- Same query cited 4/4 weeks → stable citation (protect it)
|
||||
- Citation appearing intermittently (2 out of 4 weeks) → fragile position (strengthen the page)
|
||||
- Consistent non-citation → gap to fill (page missing extractable patterns)
|
||||
|
||||
**Frequency:** Weekly for top 10 queries. Monthly for the full list.
|
||||
|
||||
---
|
||||
|
||||
### ChatGPT — Manual Testing Protocol
|
||||
|
||||
**Requirements:** ChatGPT Plus (for web browsing) or ChatGPT with Search enabled.
|
||||
|
||||
**Test protocol:**
|
||||
1. Start a new conversation (fresh context window)
|
||||
2. Enable browsing / search mode
|
||||
3. Ask your target query as a natural question
|
||||
4. Check citations in the response
|
||||
5. Click through to verify which pages are cited
|
||||
|
||||
**Note:** ChatGPT citations vary by session. The same query may cite different sources on consecutive days. This is by design — treat it as probabilistic. Your goal is to appear in the citation set, not to appear every time.
|
||||
|
||||
**What to test:**
|
||||
- Exact keyword queries ("best email marketing software")
|
||||
- Natural question queries ("what's the best email marketing software for small teams?")
|
||||
- Comparison queries ("mailchimp vs klaviyo")
|
||||
|
||||
**Frequency:** Monthly (due to variability, weekly is too noisy to be useful).
|
||||
|
||||
---
|
||||
|
||||
### Microsoft Copilot — Manual Testing Protocol
|
||||
|
||||
Access at copilot.microsoft.com or via Edge sidebar.
|
||||
|
||||
Same protocol as ChatGPT. Look for source cards that appear with citations. Copilot integrates Bing's index, so if your Bing presence is strong, Copilot citations follow.
|
||||
|
||||
**Bing indexing check:**
|
||||
- Submit sitemap to Bing Webmaster Tools
|
||||
- Run URL inspection to verify pages are indexed
|
||||
- Check Bing Webmaster Tools for crawl errors on key pages
|
||||
|
||||
**Frequency:** Monthly.
|
||||
|
||||
---
|
||||
|
||||
## Traffic Analysis for AI Citation Signals
|
||||
|
||||
Even without direct citation data, traffic patterns can signal AI search activity:
|
||||
|
||||
### Zero-Click Traffic Signals
|
||||
|
||||
When AI answers queries, fewer users click through. Watch for:
|
||||
|
||||
**Impression growth + traffic decline:** If Google Search Console shows impressions growing for a keyword but organic clicks dropping, an AI Overview may be answering the query. You're being cited but not visited.
|
||||
|
||||
**Query pattern in GSC:** If informational queries show impression growth but navigational/commercial queries stay flat, AI Overviews are likely answering the informational queries.
|
||||
|
||||
### Direct Traffic Anomalies
|
||||
|
||||
Some AI platforms (Claude, Gemini) show traffic as "direct" since users often copy/paste URLs rather than clicking. An increase in direct traffic to specific content pages (not your homepage) can signal AI-driven attention.
|
||||
|
||||
### Referral Traffic from AI Platforms
|
||||
|
||||
Perplexity, ChatGPT, and Claude all send some referral traffic when users click cited sources. Set up in Google Analytics 4:
|
||||
|
||||
1. Create a custom dimension tracking referral source
|
||||
2. Filter for: `perplexity.ai`, `chat.openai.com`, `claude.ai`, `copilot.microsoft.com`
|
||||
3. Track monthly — expect low absolute numbers but high engagement (these visitors are already pre-qualified)
|
||||
|
||||
---
|
||||
|
||||
## Tracking Template
|
||||
|
||||
**Weekly AI Citation Tracker (copy this structure):**
|
||||
|
||||
```
|
||||
Week of: [DATE]
|
||||
|
||||
GOOGLE AI OVERVIEWS (from Search Console):
|
||||
- New queries with AI Overview impressions: [list]
|
||||
- Queries that dropped out: [list]
|
||||
- Top performing query: [query] — [# impressions] impressions
|
||||
|
||||
PERPLEXITY (manual tests):
|
||||
Query: [query 1] → Cited: Y/N → Position: [#] → Competitor: [domain]
|
||||
Query: [query 2] → Cited: Y/N → Position: [#] → Competitor: [domain]
|
||||
Query: [query 3] → Cited: Y/N → Position: [#] → Competitor: [domain]
|
||||
|
||||
NOTABLE CHANGES:
|
||||
- [Describe any significant wins or losses]
|
||||
|
||||
ACTIONS FROM LAST WEEK:
|
||||
- [What we optimized] → [Result this week]
|
||||
|
||||
ACTIONS FOR NEXT WEEK:
|
||||
- [Page to optimize]: [Specific change to make]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## When Citations Drop
|
||||
|
||||
### Immediate Diagnostic
|
||||
|
||||
If you notice a citation you had has disappeared:
|
||||
|
||||
1. **Check robots.txt** — Did someone accidentally block an AI crawler? Check `yourdomain.com/robots.txt` and test each bot.
|
||||
|
||||
2. **Check the page itself** — Did the page structure change? Was the definition block moved? Was the FAQ section deleted in an edit?
|
||||
|
||||
3. **Check competitor pages** — Did a competitor publish a more extractable version of the same content? Search the query and see who now appears.
|
||||
|
||||
4. **Check page performance** — Is the page load slower? Did it get added to a noindex? Did canonical tags change?
|
||||
|
||||
5. **Check domain authority signals** — Did you lose significant backlinks? Authority drops can affect AI citations on competitive queries.
|
||||
|
||||
### Response Playbook
|
||||
|
||||
| Root cause | Fix |
|
||||
|---|---|
|
||||
| AI bot blocked | Update robots.txt — typically resolves in 1-4 weeks |
|
||||
| Page restructured (patterns removed) | Restore extractable patterns (definition block, FAQ, steps) |
|
||||
| Competitor outranked you | Strengthen the page: more specific data, better structure, schema markup |
|
||||
| Authority drop | Rebuild backlinks; also check for manual penalty in Google Search Console |
|
||||
| Page went slow | Fix Core Web Vitals — AI crawlers deprioritize slow pages |
|
||||
| Content became outdated | Update with current data and year |
|
||||
|
||||
---
|
||||
|
||||
## Emerging Tools to Watch
|
||||
|
||||
The AI citation monitoring space is early-stage. Tools being developed as of early 2026:
|
||||
|
||||
- **Semrush AI toolkit** — Testing AI Overview tracking features
|
||||
- **Ahrefs AI Overviews** — Added to their rank tracker
|
||||
- **Perplexity publisher analytics** — Announced but not launched at time of writing
|
||||
- **OpenAI publisher program** — Rumored; no confirmed release date
|
||||
|
||||
Track announcements from these vendors. First-mover advantage on publisher analytics will be significant.
|
||||
|
||||
**Until then:** Manual testing + Google Search Console is the most reliable stack available. Don't let perfect be the enemy of done — weekly manual testing surfaces 80% of what you need to know.
|
||||
371
marketing-skill/analytics-tracking/SKILL.md
Normal file
371
marketing-skill/analytics-tracking/SKILL.md
Normal file
@@ -0,0 +1,371 @@
|
||||
---
|
||||
name: analytics-tracking
|
||||
description: "Set up, audit, and debug analytics tracking implementation — GA4, Google Tag Manager, event taxonomy, conversion tracking, and data quality. Use when building a tracking plan from scratch, auditing existing analytics for gaps or errors, debugging missing events, or setting up GTM. Trigger keywords: GA4 setup, Google Tag Manager, GTM, event tracking, analytics implementation, conversion tracking, tracking plan, event taxonomy, custom dimensions, UTM tracking, analytics audit, missing events, tracking broken. NOT for analyzing marketing campaign data — use campaign-analytics for that. NOT for BI dashboards — use product-analytics for in-product event analysis."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Analytics Tracking
|
||||
|
||||
You are an expert in analytics implementation. Your goal is to make sure every meaningful action in the customer journey is captured accurately, consistently, and in a way that can actually be used for decisions — not just for the sake of having data.
|
||||
|
||||
Bad tracking is worse than no tracking. Duplicate events, missing parameters, unconsented data, and broken conversions lead to decisions made on bad data. This skill is about building it right the first time, or finding what's broken and fixing it.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing.
|
||||
|
||||
Gather this context:
|
||||
|
||||
### 1. Current State
|
||||
- Do you have GA4 and/or GTM already set up? If so, what's broken or missing?
|
||||
- What's your tech stack? (React SPA, Next.js, WordPress, custom, etc.)
|
||||
- Do you have a consent management platform (CMP)? Which one?
|
||||
- What events are you currently tracking (if any)?
|
||||
|
||||
### 2. Business Context
|
||||
- What are your primary conversion actions? (signup, purchase, lead form, free trial start)
|
||||
- What are your key micro-conversions? (pricing page view, feature discovery, demo request)
|
||||
- Do you run paid campaigns? (Google Ads, Meta, LinkedIn — affects conversion tracking needs)
|
||||
|
||||
### 3. Goals
|
||||
- Building from scratch, auditing existing, or debugging a specific issue?
|
||||
- Do you need cross-domain tracking? Multiple properties or subdomains?
|
||||
- Server-side tagging requirement? (GDPR-sensitive markets, performance concerns)
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Set Up From Scratch
|
||||
No analytics in place — we'll build the tracking plan, implement GA4 and GTM, define the event taxonomy, and configure conversions.
|
||||
|
||||
### Mode 2: Audit Existing Tracking
|
||||
Tracking exists but you don't trust the data, coverage is incomplete, or you're adding new goals. We'll audit what's there, gap-fill, and clean up.
|
||||
|
||||
### Mode 3: Debug Tracking Issues
|
||||
Specific events are missing, conversion numbers don't add up, or GTM preview shows events firing but GA4 isn't recording them. Structured debugging workflow.
|
||||
|
||||
---
|
||||
|
||||
## Event Taxonomy Design
|
||||
|
||||
Get this right before touching GA4 or GTM. Retrofitting taxonomy is painful.
|
||||
|
||||
### Naming Convention
|
||||
|
||||
**Format:** `object_action` (snake_case, verb at the end)
|
||||
|
||||
| ✅ Good | ❌ Bad |
|
||||
|--------|--------|
|
||||
| `form_submit` | `submitForm`, `FormSubmitted`, `form-submit` |
|
||||
| `plan_selected` | `clickPricingPlan`, `selected_plan`, `PlanClick` |
|
||||
| `video_started` | `videoPlay`, `StartVideo`, `VideoStart` |
|
||||
| `checkout_completed` | `purchase`, `buy_complete`, `checkoutDone` |
|
||||
|
||||
**Rules:**
|
||||
- Always `noun_verb` not `verb_noun`
|
||||
- Lowercase + underscores only — no camelCase, no hyphens
|
||||
- Be specific enough to be unambiguous, not so verbose it's a sentence
|
||||
- Consistent tense: `_started`, `_completed`, `_failed` (not mix of past/present)
|
||||
|
||||
### Standard Parameters
|
||||
|
||||
Every event should include these where applicable:
|
||||
|
||||
| Parameter | Type | Example | Purpose |
|
||||
|-----------|------|---------|---------|
|
||||
| `page_location` | string | `https://app.co/pricing` | Auto-captured by GA4 |
|
||||
| `page_title` | string | `Pricing - Acme` | Auto-captured by GA4 |
|
||||
| `user_id` | string | `usr_abc123` | Link to your CRM/DB |
|
||||
| `plan_name` | string | `Professional` | Segment by plan |
|
||||
| `value` | number | `99` | Revenue/order value |
|
||||
| `currency` | string | `USD` | Required with value |
|
||||
| `content_group` | string | `onboarding` | Group pages/flows |
|
||||
| `method` | string | `google_oauth` | How (signup method, etc.) |
|
||||
|
||||
### Event Taxonomy for SaaS
|
||||
|
||||
**Core funnel events:**
|
||||
```
|
||||
visitor_arrived (page view — automatic in GA4)
|
||||
signup_started (user clicked "Sign up")
|
||||
signup_completed (account created successfully)
|
||||
trial_started (free trial began)
|
||||
onboarding_step_completed (param: step_name, step_number)
|
||||
feature_activated (param: feature_name)
|
||||
plan_selected (param: plan_name, billing_period)
|
||||
checkout_started (param: value, currency, plan_name)
|
||||
checkout_completed (param: value, currency, transaction_id)
|
||||
subscription_cancelled (param: cancel_reason, plan_name)
|
||||
```
|
||||
|
||||
**Micro-conversion events:**
|
||||
```
|
||||
pricing_viewed
|
||||
demo_requested (param: source)
|
||||
form_submitted (param: form_name, form_location)
|
||||
content_downloaded (param: content_name, content_type)
|
||||
video_started (param: video_title)
|
||||
video_completed (param: video_title, percent_watched)
|
||||
chat_opened
|
||||
help_article_viewed (param: article_name)
|
||||
```
|
||||
|
||||
See [references/event-taxonomy-guide.md](references/event-taxonomy-guide.md) for the full taxonomy catalog with custom dimension recommendations.
|
||||
|
||||
---
|
||||
|
||||
## GA4 Setup
|
||||
|
||||
### Data Stream Configuration
|
||||
|
||||
1. **Create property** in GA4 → Admin → Properties → Create
|
||||
2. **Add web data stream** with your domain
|
||||
3. **Enhanced Measurement** — enable all, then review:
|
||||
- ✅ Page views (keep)
|
||||
- ✅ Scrolls (keep)
|
||||
- ✅ Outbound clicks (keep)
|
||||
- ✅ Site search (keep if you have search)
|
||||
- ⚠️ Video engagement (disable if you'll track videos manually — avoid duplicates)
|
||||
- ⚠️ File downloads (disable if you'll track these in GTM for better parameters)
|
||||
4. **Configure domains** — add all subdomains used in your funnel
|
||||
|
||||
### Custom Events in GA4
|
||||
|
||||
For any event not auto-collected, create it in GTM (preferred) or via gtag directly:
|
||||
|
||||
**Via gtag:**
|
||||
```javascript
|
||||
gtag('event', 'signup_completed', {
|
||||
method: 'email',
|
||||
user_id: 'usr_abc123',
|
||||
plan_name: 'trial'
|
||||
});
|
||||
```
|
||||
|
||||
**Via GTM data layer (preferred — see GTM section):**
|
||||
```javascript
|
||||
window.dataLayer.push({
|
||||
event: 'signup_completed',
|
||||
signup_method: 'email',
|
||||
user_id: 'usr_abc123'
|
||||
});
|
||||
```
|
||||
|
||||
### Conversions Configuration
|
||||
|
||||
Mark these events as conversions in GA4 → Admin → Conversions:
|
||||
- `signup_completed`
|
||||
- `checkout_completed`
|
||||
- `demo_requested`
|
||||
- `trial_started` (if separate from signup)
|
||||
|
||||
**Rules:**
|
||||
- Max 30 conversion events per property — curate, don't mark everything
|
||||
- Conversions are retroactive in GA4 — turning one on applies to 6 months of history
|
||||
- Don't mark micro-conversions as conversions unless you're optimizing ad campaigns for them
|
||||
|
||||
---
|
||||
|
||||
## Google Tag Manager Setup
|
||||
|
||||
### Container Structure
|
||||
|
||||
```
|
||||
GTM Container
|
||||
├── Tags
|
||||
│ ├── GA4 Configuration (fires on all pages)
|
||||
│ ├── GA4 Event — [event_name] (one tag per event)
|
||||
│ ├── Google Ads Conversion (per conversion action)
|
||||
│ └── Meta Pixel (if running Meta ads)
|
||||
├── Triggers
|
||||
│ ├── All Pages
|
||||
│ ├── DOM Ready
|
||||
│ ├── Data Layer Event — [event_name]
|
||||
│ └── Custom Element Click — [selector]
|
||||
└── Variables
|
||||
├── Data Layer Variables (dlv — for each dL key)
|
||||
├── Constant — GA4 Measurement ID
|
||||
└── JavaScript Variables (computed values)
|
||||
```
|
||||
|
||||
### Tag Patterns for SaaS
|
||||
|
||||
**Pattern 1: Data Layer Push (most reliable)**
|
||||
|
||||
Your app pushes to dataLayer → GTM picks it up → sends to GA4.
|
||||
|
||||
```javascript
|
||||
// In your app code (on event):
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
window.dataLayer.push({
|
||||
event: 'signup_completed',
|
||||
signup_method: 'email',
|
||||
user_id: userId,
|
||||
plan_name: 'trial'
|
||||
});
|
||||
```
|
||||
|
||||
```
|
||||
GTM Tag: GA4 Event
|
||||
Event Name: {{DLV - event}} OR hardcode "signup_completed"
|
||||
Parameters:
|
||||
signup_method: {{DLV - signup_method}}
|
||||
user_id: {{DLV - user_id}}
|
||||
plan_name: {{DLV - plan_name}}
|
||||
Trigger: Custom Event - "signup_completed"
|
||||
```
|
||||
|
||||
**Pattern 2: CSS Selector Click**
|
||||
|
||||
For events triggered by UI elements without app-level hooks.
|
||||
|
||||
```
|
||||
GTM Trigger:
|
||||
Type: Click - All Elements
|
||||
Conditions: Click Element matches CSS selector [data-track="demo-cta"]
|
||||
|
||||
GTM Tag: GA4 Event
|
||||
Event Name: demo_requested
|
||||
Parameters:
|
||||
page_location: {{Page URL}}
|
||||
```
|
||||
|
||||
See [references/gtm-patterns.md](references/gtm-patterns.md) for full configuration templates.
|
||||
|
||||
---
|
||||
|
||||
## Conversion Tracking: Platform-Specific
|
||||
|
||||
### Google Ads
|
||||
|
||||
1. Create conversion action in Google Ads → Tools → Conversions
|
||||
2. Import GA4 conversions (recommended — single source of truth) OR use the Google Ads tag
|
||||
3. Set attribution model: **Data-driven** (if >50 conversions/month), otherwise **Last click**
|
||||
4. Conversion window: 30 days for lead gen, 90 days for high-consideration purchases
|
||||
|
||||
### Meta (Facebook/Instagram) Pixel
|
||||
|
||||
1. Install Meta Pixel base code via GTM
|
||||
2. Standard events: `PageView`, `Lead`, `CompleteRegistration`, `Purchase`
|
||||
3. Conversions API (CAPI) strongly recommended — client-side pixel loses ~30% of conversions due to ad blockers and iOS
|
||||
4. CAPI requires server-side implementation (Meta's docs or GTM server-side)
|
||||
|
||||
---
|
||||
|
||||
## Cross-Platform Tracking
|
||||
|
||||
### UTM Strategy
|
||||
|
||||
Enforce strict UTM conventions or your channel data becomes noise.
|
||||
|
||||
| Parameter | Convention | Example |
|
||||
|-----------|-----------|---------|
|
||||
| `utm_source` | Platform name (lowercase) | `google`, `linkedin`, `newsletter` |
|
||||
| `utm_medium` | Traffic type | `cpc`, `email`, `social`, `organic` |
|
||||
| `utm_campaign` | Campaign ID or name | `q1-trial-push`, `brand-awareness` |
|
||||
| `utm_content` | Ad/creative variant | `hero-cta-blue`, `text-link` |
|
||||
| `utm_term` | Paid keyword | `saas-analytics` |
|
||||
|
||||
**Rule:** Never tag organic or direct traffic with UTMs. UTMs override GA4's automatic source/medium attribution.
|
||||
|
||||
### Attribution Windows
|
||||
|
||||
| Platform | Default Window | Recommended for SaaS |
|
||||
|---------|---------------|---------------------|
|
||||
| GA4 | 30 days | 30-90 days depending on sales cycle |
|
||||
| Google Ads | 30 days | 30 days (trial), 90 days (enterprise) |
|
||||
| Meta | 7-day click, 1-day view | 7-day click only |
|
||||
| LinkedIn | 30 days | 30 days |
|
||||
|
||||
### Cross-Domain Tracking
|
||||
|
||||
For funnels that cross domains (e.g., `acme.com` → `app.acme.com`):
|
||||
|
||||
1. In GA4 → Admin → Data Streams → Configure tag settings → List unwanted referrals → Add both domains
|
||||
2. In GTM → GA4 Configuration tag → Cross-domain measurement → Add both domains
|
||||
3. Test: visit domain A, click link to domain B, check GA4 DebugView — session should not restart
|
||||
|
||||
---
|
||||
|
||||
## Data Quality
|
||||
|
||||
### Deduplication
|
||||
|
||||
**Events firing twice?** Common causes:
|
||||
- GTM tag + hardcoded gtag both firing
|
||||
- Enhanced Measurement + custom GTM tag for same event
|
||||
- SPA router firing pageview on every route change AND GTM page view tag
|
||||
|
||||
Fix: Audit GTM Preview for double-fires. Check Network tab in DevTools for duplicate hits.
|
||||
|
||||
### Bot Filtering
|
||||
|
||||
GA4 filters known bots automatically. For internal traffic:
|
||||
1. GA4 → Admin → Data Filters → Internal Traffic
|
||||
2. Add your office IPs and developer IPs
|
||||
3. Enable filter (starts as testing mode — activate it)
|
||||
|
||||
### Consent Management Impact
|
||||
|
||||
Under GDPR/ePrivacy, analytics may require consent. Plan for this:
|
||||
|
||||
| Consent Mode setting | Impact |
|
||||
|---------------------|--------|
|
||||
| **No consent mode** | Visitors who decline cookies → zero data |
|
||||
| **Basic consent mode** | Visitors who decline → zero data |
|
||||
| **Advanced consent mode** | Visitors who decline → modeled data (GA4 estimates using consented users) |
|
||||
|
||||
**Recommendation:** Implement Advanced Consent Mode via GTM. Requires CMP integration (Cookiebot, OneTrust, Usercentrics, etc.).
|
||||
|
||||
Expected consent rate by region: 60-75% EU, 85-95% US.
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **Events firing on every page load** → Symptom of misconfigured trigger. Flag: duplicate data inflation.
|
||||
- **No user_id being passed** → You can't connect analytics to your CRM or understand cohorts. Flag for fix.
|
||||
- **Conversions not matching GA4 vs Ads** → Attribution window mismatch or pixel duplication. Flag for audit.
|
||||
- **No consent mode configured in EU markets** → Legal exposure and underreported data. Flag immediately.
|
||||
- **All pages showing as "/(not set)" or generic paths** → SPA routing not handled. GA4 is recording wrong pages.
|
||||
- **UTM source showing as "direct" for paid campaigns** → UTMs missing or being stripped. Traffic attribution is broken.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|--------------------|-----------|
|
||||
| "Build a tracking plan" | Event taxonomy table (events + parameters + triggers), GA4 configuration checklist, GTM container structure |
|
||||
| "Audit my tracking" | Gap analysis vs. standard SaaS funnel, data quality scorecard (0-100), prioritized fix list |
|
||||
| "Set up GTM" | Tag/trigger/variable configuration for each event, container setup checklist |
|
||||
| "Debug missing events" | Structured debugging steps using GTM Preview + GA4 DebugView + Network tab |
|
||||
| "Set up conversion tracking" | Conversion action configuration for GA4 + Google Ads + Meta |
|
||||
| "Generate tracking plan" | Run `scripts/tracking_plan_generator.py` with your inputs |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — what's broken or what needs building before methodology
|
||||
- **What + Why + How** — every finding has all three
|
||||
- **Actions have owners and deadlines** — no vague "consider implementing"
|
||||
- **Confidence tagging** — 🟢 verified / 🟡 estimated / 🔴 assumed
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **campaign-analytics**: Use for analyzing marketing performance and channel ROI. NOT for implementation — use this skill for tracking setup.
|
||||
- **ab-test-setup**: Use when designing experiments. NOT for event tracking setup (though this skill's events feed A/B tests).
|
||||
- **analytics-tracking** (this skill): covers setup only. For dashboards and reporting, use campaign-analytics.
|
||||
- **seo-audit**: Use for technical SEO. NOT for analytics tracking (though both use GA4 data).
|
||||
- **gdpr-dsgvo-expert**: Use for GDPR compliance posture. This skill covers consent mode implementation; that skill covers the full compliance framework.
|
||||
@@ -0,0 +1,224 @@
|
||||
# Tracking Debug Playbook
|
||||
|
||||
Step-by-step methodology for diagnosing and fixing analytics tracking issues.
|
||||
|
||||
---
|
||||
|
||||
## The Debug Mindset
|
||||
|
||||
Analytics bugs are harder than code bugs because:
|
||||
1. They fail silently — no error thrown, just missing data
|
||||
2. They often only appear in production
|
||||
3. They can be caused by timing, consent, ad blockers, or just configuration
|
||||
|
||||
Work systematically. Don't guess. Verify at each layer before moving to the next.
|
||||
|
||||
---
|
||||
|
||||
## The Debug Stack (Bottom-Up)
|
||||
|
||||
```
|
||||
Layer 5: GA4 Reports / DebugView ← what you see
|
||||
Layer 4: GA4 Data Processing ← where it lands
|
||||
Layer 3: Network Request ← what was sent
|
||||
Layer 2: GTM / Tag firing ← what GTM did
|
||||
Layer 1: dataLayer / App code ← what your app pushed
|
||||
```
|
||||
|
||||
When something's missing at Layer 5, start at Layer 1 and verify each layer before going up.
|
||||
|
||||
---
|
||||
|
||||
## Tool Setup
|
||||
|
||||
### GTM Preview Mode
|
||||
|
||||
1. GTM → Preview (top right)
|
||||
2. Enter your site URL → Connect
|
||||
3. A blue bar appears at the bottom of your site: "Google Tag Manager"
|
||||
4. GTM Preview panel opens in a separate tab
|
||||
5. Perform the action you're debugging
|
||||
6. Check: did the expected tag fire?
|
||||
|
||||
**Reading GTM Preview:**
|
||||
- Left panel: events as they occur (Page View, Click, Custom Event, etc.)
|
||||
- Middle panel: Tags fired / Tags NOT fired for selected event
|
||||
- Right panel: Variables values at the time of the event
|
||||
|
||||
### GA4 DebugView
|
||||
|
||||
1. GA4 → Admin → DebugView
|
||||
2. Enable debug mode via:
|
||||
- GTM: add `debug_mode: true` to your GA4 Event tag parameters
|
||||
- Extension: install "GA Debugger" Chrome extension
|
||||
- URL parameter: add `?_gl=` or use GA4 debug parameter
|
||||
3. Perform actions on your site
|
||||
4. Watch events appear in real-time (10-15 second delay)
|
||||
|
||||
### Chrome DevTools — Network Tab
|
||||
|
||||
1. Open DevTools → Network
|
||||
2. Filter by: `collect` or `google-analytics` or `analytics`
|
||||
3. Perform the action
|
||||
4. Look for requests to `https://www.google-analytics.com/g/collect`
|
||||
5. Click the request → Payload tab → view parameters
|
||||
|
||||
---
|
||||
|
||||
## Common Issues and Fixes
|
||||
|
||||
### Issue: Event fires in GTM Preview but not in GA4
|
||||
|
||||
**Possible causes:**
|
||||
|
||||
1. **Consent mode blocking** — user is in denied state
|
||||
- Check: In GTM Preview, look at Variables → `Analytics Storage` — is it `denied`?
|
||||
- Fix: Test with consent granted, or implement Advanced Consent Mode
|
||||
|
||||
2. **Filters blocking data** — internal traffic filter is active
|
||||
- Check: GA4 → Admin → Data Filters — is "Internal Traffic" filter active?
|
||||
- Fix: Disable filter temporarily, test, then re-enable and exclude your IP correctly
|
||||
|
||||
3. **Debug mode not enabled** — DebugView only shows debug-mode traffic
|
||||
- Check: Is `debug_mode: true` parameter on the GA4 Event tag?
|
||||
- Fix: Add it, or use the GA4 Debugger Chrome extension
|
||||
|
||||
4. **Wrong property** — you're looking at a different GA4 property
|
||||
- Check: Confirm Measurement ID in GTM matches the GA4 property you're viewing
|
||||
- Fix: Compare `G-XXXXXXXXXX` in GTM vs. GA4 Data Stream settings
|
||||
|
||||
5. **Duplicate GA4 configuration tags** — two config tags = double sessions + weird data
|
||||
- Check: GTM → Tags → filter by "GA4 Configuration" — more than one?
|
||||
- Fix: Delete duplicates, keep one with All Pages trigger
|
||||
|
||||
---
|
||||
|
||||
### Issue: Event not firing in GTM Preview at all
|
||||
|
||||
**Diagnosis path:**
|
||||
|
||||
**Step 1:** Check the trigger
|
||||
- Is the trigger for this tag listed under the action in GTM Preview?
|
||||
- If not: the trigger didn't fire
|
||||
|
||||
**Step 2:** Check trigger conditions
|
||||
- Open the trigger in GTM
|
||||
- Reproduce the exact scenario step by step
|
||||
- In GTM Preview, check Variables at the moment the action happened
|
||||
- Do the variable values match your trigger conditions?
|
||||
|
||||
**Step 3:** dataLayer issue (for Custom Event triggers)
|
||||
- In GTM Preview → select the relevant event in left panel → Variables tab
|
||||
- Scroll to find `event` — what's the value?
|
||||
- If event name doesn't match trigger exactly: it won't fire (case-sensitive, exact match)
|
||||
|
||||
**Step 4:** Timing issue
|
||||
- If using "Page View" trigger and element doesn't exist yet: switch to "DOM Ready" or "Window Loaded"
|
||||
- If SPA: route changes may not trigger "Page View" — use History Change instead
|
||||
|
||||
---
|
||||
|
||||
### Issue: Parameters showing as (not set) or undefined in GA4
|
||||
|
||||
**Step 1:** Verify parameter is in the network request
|
||||
- DevTools → Network → find GA4 collect request → Payload
|
||||
- Search for the parameter name (e.g., `plan_name`)
|
||||
- If not there: GTM variable isn't resolving correctly
|
||||
|
||||
**Step 2:** Check the GTM variable
|
||||
- GTM Preview → find the event → Variables tab
|
||||
- Find the variable for this parameter (e.g., `DLV - plan_name`)
|
||||
- What's its value? If `undefined`: the dataLayer push didn't include this key, or key name is wrong
|
||||
|
||||
**Step 3:** Check dataLayer push in your app code
|
||||
- DevTools → Console → type: `dataLayer.filter(e => e.event === 'your_event_name')`
|
||||
- Inspect the object — is the parameter key present and spelled correctly?
|
||||
|
||||
**Step 4:** Check GA4 custom dimension registration
|
||||
- Some parameters require a registered custom dimension in GA4 to appear in reports
|
||||
- GA4 → Admin → Custom Definitions → Custom Dimensions
|
||||
- If parameter isn't registered here: it'll exist in raw data but won't show in Explore reports
|
||||
|
||||
---
|
||||
|
||||
### Issue: Duplicate events (event fires 2x per action)
|
||||
|
||||
**Find the duplicates:**
|
||||
- GTM Preview → find the action → how many tags with the same name fired?
|
||||
- DevTools → Network → filter by `collect` → count hits for the action
|
||||
|
||||
**Common causes:**
|
||||
|
||||
1. **Enhanced Measurement + manual GTM tag**
|
||||
- e.g., Enhanced Measurement tracks outbound clicks, GTM also has an outbound click tag
|
||||
- Fix: disable the Enhanced Measurement setting OR remove the GTM tag
|
||||
|
||||
2. **Two GTM Configuration tags**
|
||||
- Each sends its own hits
|
||||
- Fix: delete one, keep one
|
||||
|
||||
3. **SPA router fires pageview + History Change trigger also fires**
|
||||
- Fix: disable Enhanced Measurement pageview, use only History Change tag
|
||||
|
||||
4. **Event fires on multiple triggers that both match**
|
||||
- Fix: make triggers more specific — add exclusion conditions
|
||||
|
||||
---
|
||||
|
||||
### Issue: Sessions/users look wrong (too high or too low)
|
||||
|
||||
**Too many sessions:**
|
||||
- Multiple GA4 Configuration tags
|
||||
- History Change trigger firing + Enhanced Measurement pageview on SPA
|
||||
- Client ID not persisting (cookie being blocked or cleared)
|
||||
|
||||
**Too few sessions / users:**
|
||||
- Consent blocking analytics for non-consenting users (expected under strict consent mode)
|
||||
- Bot filtering too aggressive
|
||||
- GA4 tags firing on wrong pages only
|
||||
|
||||
**Sessions reset unexpectedly (user shows as new on every page):**
|
||||
- Cross-domain tracking not configured
|
||||
- Cookie domain mismatch
|
||||
- GTM cookie settings incorrect
|
||||
|
||||
---
|
||||
|
||||
### Issue: Conversions not matching between GA4 and Google Ads
|
||||
|
||||
**Check 1: Attribution window mismatch**
|
||||
- GA4 default: 30-day last click
|
||||
- Google Ads: check conversion action settings for window
|
||||
- These legitimately produce different numbers
|
||||
|
||||
**Check 2: Conversion event names**
|
||||
- In Google Ads → Tools → Conversions → imported from GA4
|
||||
- Does the linked event name exactly match the GA4 event?
|
||||
|
||||
**Check 3: Import is linked**
|
||||
- Google Ads → Tools → Linked Accounts → Google Analytics 4
|
||||
- Is the correct GA4 property linked and synced?
|
||||
- Sync can take 24-48 hours after changes
|
||||
|
||||
**Check 4: Enhanced Conversions**
|
||||
- If GA4 uses a user_id or email parameter, Enhanced Conversions can improve matching
|
||||
- Google Ads → Conversions → Enhanced Conversions for Web → Enable
|
||||
|
||||
---
|
||||
|
||||
## Debug Checklist Template
|
||||
|
||||
Use this for any new tracking issue:
|
||||
|
||||
```
|
||||
[ ] Confirmed exact event name and parameters expected
|
||||
[ ] Verified app code is pushing to dataLayer (console: dataLayer)
|
||||
[ ] GTM Preview: trigger fires at correct moment
|
||||
[ ] GTM Preview: parameters resolve to correct values (not undefined)
|
||||
[ ] Network: GA4 collect request appears with correct payload
|
||||
[ ] GA4 DebugView: event appears within 30 seconds
|
||||
[ ] GA4 DebugView: parameters present and correct
|
||||
[ ] GA4 Reports: event appears (24-48h delay for standard reports)
|
||||
[ ] Consent check: tested with analytics consent granted
|
||||
[ ] Filter check: internal traffic filter not blocking test traffic
|
||||
```
|
||||
@@ -0,0 +1,203 @@
|
||||
# Event Taxonomy Guide
|
||||
|
||||
Complete reference for naming conventions, event structure, and parameter standards.
|
||||
|
||||
---
|
||||
|
||||
## Why Taxonomy Matters
|
||||
|
||||
Analytics data is only as good as its naming consistency. A tracking system with `FormSubmit`, `form_submit`, `form-submitted`, and `formSubmitted` as four separate "events" is useless for aggregation. One naming standard, enforced from day one, avoids months of cleanup later.
|
||||
|
||||
This guide is the reference for that standard.
|
||||
|
||||
---
|
||||
|
||||
## Naming Convention: Full Specification
|
||||
|
||||
### Format
|
||||
|
||||
```
|
||||
[object]_[action]
|
||||
```
|
||||
|
||||
**Object** = the thing being acted upon (noun)
|
||||
**Action** = what happened (verb, past tense or gerund)
|
||||
|
||||
### Casing & Characters
|
||||
|
||||
| Rule | ✅ Correct | ❌ Wrong |
|
||||
|------|-----------|---------|
|
||||
| Lowercase only | `video_started` | `Video_Started`, `VIDEO_STARTED` |
|
||||
| Underscores only | `form_submit` | `form-submit`, `formSubmit` |
|
||||
| Noun before verb | `plan_selected` | `selected_plan` |
|
||||
| Past tense or clear state | `checkout_completed` | `checkout_complete`, `checkoutDone` |
|
||||
| Specific > generic | `trial_started` | `event_triggered` |
|
||||
| Max 4 words | `onboarding_step_completed` | `user_completed_an_onboarding_step_in_the_flow` |
|
||||
|
||||
### Action Vocabulary (Standard Verbs)
|
||||
|
||||
Use these verbs consistently — don't invent synonyms:
|
||||
|
||||
| Verb | Use for |
|
||||
|------|---------|
|
||||
| `_started` | Beginning of a multi-step process |
|
||||
| `_completed` | Successful completion of a process |
|
||||
| `_failed` | An attempt that errored out |
|
||||
| `_submitted` | Form or data submission |
|
||||
| `_viewed` | Passive view of a page, modal, or content |
|
||||
| `_clicked` | Direct click on a specific element |
|
||||
| `_selected` | Choosing from options (plan, variant, filter) |
|
||||
| `_opened` | Modal, drawer, chat window opened |
|
||||
| `_closed` | Modal, drawer, chat window closed |
|
||||
| `_downloaded` | File download |
|
||||
| `_activated` | Feature turned on for first time |
|
||||
| `_upgraded` | Plan or feature upgrade |
|
||||
| `_cancelled` | Intentional termination |
|
||||
| `_dismissed` | User explicitly closed/ignored a prompt |
|
||||
| `_searched` | Search query submitted |
|
||||
|
||||
---
|
||||
|
||||
## Complete SaaS Event Catalog
|
||||
|
||||
### Acquisition Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `ad_clicked` | `utm_source`, `utm_campaign` | `utm_content`, `utm_term` |
|
||||
| `landing_page_viewed` | `page_location`, `utm_source` | `variant` (A/B) |
|
||||
| `pricing_viewed` | `page_location` | `referrer_page` |
|
||||
| `demo_requested` | `source` (page slug or section) | `plan_interest` |
|
||||
| `content_downloaded` | `content_name`, `content_type` | `gated` (boolean) |
|
||||
|
||||
### Acquisition → Registration
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `signup_started` | — | `plan_name`, `method` |
|
||||
| `signup_completed` | `method` | `user_id`, `plan_name` |
|
||||
| `email_verified` | — | `method` |
|
||||
| `trial_started` | `plan_name` | `trial_length_days` |
|
||||
| `invitation_accepted` | `inviter_user_id` | `plan_name` |
|
||||
|
||||
### Onboarding Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `onboarding_started` | — | `onboarding_variant` |
|
||||
| `onboarding_step_completed` | `step_name`, `step_number` | `time_spent_seconds` |
|
||||
| `onboarding_completed` | `steps_total` | `time_to_complete_seconds` |
|
||||
| `onboarding_skipped` | `step_name` | `step_number` |
|
||||
| `feature_activated` | `feature_name` | `activation_method` |
|
||||
| `integration_connected` | `integration_name` | `integration_type` |
|
||||
| `team_member_invited` | — | `invite_method` |
|
||||
|
||||
### Conversion Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `plan_selected` | `plan_name`, `billing_period` | `previous_plan` |
|
||||
| `checkout_started` | `plan_name`, `value`, `currency` | `billing_period` |
|
||||
| `checkout_completed` | `plan_name`, `value`, `currency`, `transaction_id` | `billing_period`, `coupon_code` |
|
||||
| `checkout_failed` | `plan_name`, `error_reason` | `value`, `currency` |
|
||||
| `upgrade_completed` | `from_plan`, `to_plan`, `value`, `currency` | `trigger` |
|
||||
| `coupon_applied` | `coupon_code`, `discount_value` | `plan_name` |
|
||||
|
||||
### Engagement Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `feature_used` | `feature_name` | `feature_area`, `usage_count` |
|
||||
| `search_performed` | `search_term` | `results_count`, `search_area` |
|
||||
| `filter_applied` | `filter_name`, `filter_value` | `result_count` |
|
||||
| `export_completed` | `export_type`, `export_format` | `record_count` |
|
||||
| `report_generated` | `report_name` | `date_range` |
|
||||
| `notification_clicked` | `notification_type` | `notification_id` |
|
||||
|
||||
### Retention Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `subscription_cancelled` | `cancel_reason` | `plan_name`, `save_offer_shown`, `save_offer_accepted` |
|
||||
| `save_offer_accepted` | `offer_type` | `plan_name`, `discount_pct` |
|
||||
| `subscription_paused` | `pause_duration_days` | `pause_reason` |
|
||||
| `subscription_reactivated` | — | `plan_name`, `days_since_cancel` |
|
||||
| `churn_risk_detected` | — | `risk_score`, `risk_signals` |
|
||||
|
||||
### Support / Help Events
|
||||
|
||||
| Event | Required Parameters | Optional Parameters |
|
||||
|-------|-------------------|-------------------|
|
||||
| `help_article_viewed` | `article_name` | `article_id`, `source` |
|
||||
| `chat_opened` | — | `page_location`, `trigger` |
|
||||
| `support_ticket_submitted` | `ticket_category` | `severity` |
|
||||
| `error_encountered` | `error_type`, `error_message` | `page_location`, `feature_name` |
|
||||
|
||||
---
|
||||
|
||||
## Custom Dimensions & Metrics
|
||||
|
||||
GA4 limits: 50 custom dimensions (event-scoped), 25 user-scoped, 50 item-scoped.
|
||||
Prioritize the ones that matter for segmentation.
|
||||
|
||||
### Recommended User-Scoped Dimensions
|
||||
|
||||
| Dimension Name | Parameter | Example Values |
|
||||
|---------------|-----------|---------------|
|
||||
| User ID | `user_id` | `usr_abc123` |
|
||||
| Plan Name | `plan_name` | `starter`, `professional`, `enterprise` |
|
||||
| Billing Period | `billing_period` | `monthly`, `annual` |
|
||||
| Account Created Date | `account_created_date` | `2024-03-15` |
|
||||
| Onboarding Completed | `onboarding_completed` | `true`, `false` |
|
||||
| Company Size | `company_size` | `1-10`, `11-50`, `51-200` |
|
||||
|
||||
### Recommended Event-Scoped Dimensions
|
||||
|
||||
| Dimension Name | Parameter | Used In |
|
||||
|---------------|-----------|---------|
|
||||
| Cancel Reason | `cancel_reason` | `subscription_cancelled` |
|
||||
| Feature Name | `feature_name` | `feature_used`, `feature_activated` |
|
||||
| Content Name | `content_name` | `content_downloaded` |
|
||||
| Signup Method | `method` | `signup_completed` |
|
||||
| Error Type | `error_type` | `error_encountered` |
|
||||
|
||||
---
|
||||
|
||||
## Taxonomy Governance
|
||||
|
||||
### The Tracking Plan Document
|
||||
|
||||
Maintain a single tracking plan document (Google Sheet or Notion table) with:
|
||||
|
||||
| Column | Values |
|
||||
|--------|--------|
|
||||
| Event Name | e.g., `checkout_completed` |
|
||||
| Trigger | "User completes Stripe checkout" |
|
||||
| Parameters | `{value, currency, plan_name, transaction_id}` |
|
||||
| Implemented In | GTM / App code / server |
|
||||
| Status | Draft / Implemented / Verified |
|
||||
| Owner | Engineering / Marketing / Product |
|
||||
|
||||
### Change Protocol
|
||||
|
||||
1. New events → add to tracking plan first, get sign-off before implementing
|
||||
2. Rename events → use a deprecation period (keep old + add new for 30 days, then remove old)
|
||||
3. Remove events → archive in tracking plan, don't delete — historical data reference
|
||||
4. Add parameters → non-breaking, implement immediately and update tracking plan
|
||||
5. Remove parameters → treat as rename (deprecation period)
|
||||
|
||||
### Versioning
|
||||
|
||||
Include `schema_version` as a parameter on critical events if your taxonomy evolves rapidly:
|
||||
|
||||
```javascript
|
||||
window.dataLayer.push({
|
||||
event: 'checkout_completed',
|
||||
schema_version: 'v2',
|
||||
value: 99,
|
||||
currency: 'USD',
|
||||
// ...
|
||||
});
|
||||
```
|
||||
|
||||
This allows filtering old vs. new schema during migrations.
|
||||
298
marketing-skill/analytics-tracking/references/gtm-patterns.md
Normal file
298
marketing-skill/analytics-tracking/references/gtm-patterns.md
Normal file
@@ -0,0 +1,298 @@
|
||||
# GTM Patterns for SaaS
|
||||
|
||||
Common Google Tag Manager configurations for SaaS applications.
|
||||
|
||||
---
|
||||
|
||||
## Container Architecture
|
||||
|
||||
### Naming Convention
|
||||
|
||||
Use consistent naming or GTM becomes a black box within 6 months.
|
||||
|
||||
```
|
||||
Tags: [Platform] - [Event Name] e.g., "GA4 - signup_completed"
|
||||
Triggers: [Type] - [Description] e.g., "DL Event - signup_completed"
|
||||
Variables: [Type] - [Parameter Name] e.g., "DLV - plan_name"
|
||||
```
|
||||
|
||||
### Required Variables (Create These First)
|
||||
|
||||
| Variable Name | Type | Value |
|
||||
|--------------|------|-------|
|
||||
| `CON - GA4 Measurement ID` | Constant | `G-XXXXXXXXXX` |
|
||||
| `CON - Environment` | Constant | `production` |
|
||||
| `JS - Page Path` | Custom JavaScript | `function() { return window.location.pathname; }` |
|
||||
| `JS - User ID` | Custom JavaScript | `function() { return window.currentUserId || undefined; }` |
|
||||
|
||||
### GA4 Configuration Tag
|
||||
|
||||
**One tag, fires on All Pages:**
|
||||
|
||||
```
|
||||
Tag Type: Google Analytics: GA4 Configuration
|
||||
Measurement ID: {{CON - GA4 Measurement ID}}
|
||||
Fields to Set:
|
||||
- user_id: {{JS - User ID}}
|
||||
Trigger: All Pages
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Library
|
||||
|
||||
### Pattern 1: Data Layer Push Event
|
||||
|
||||
The most reliable pattern. Your app pushes structured data; GTM listens.
|
||||
|
||||
**In your application code:**
|
||||
```javascript
|
||||
// Call this function on any trackable event
|
||||
function trackEvent(eventName, parameters) {
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
window.dataLayer.push({
|
||||
event: eventName,
|
||||
...parameters
|
||||
});
|
||||
}
|
||||
|
||||
// Example: after successful signup
|
||||
trackEvent('signup_completed', {
|
||||
signup_method: 'email',
|
||||
user_id: newUser.id,
|
||||
plan_name: 'trial'
|
||||
});
|
||||
```
|
||||
|
||||
**In GTM:**
|
||||
|
||||
1. Create Data Layer Variables for each parameter:
|
||||
- `DLV - signup_method` → Data Layer Variable → `signup_method`
|
||||
- `DLV - user_id` → Data Layer Variable → `user_id`
|
||||
- `DLV - plan_name` → Data Layer Variable → `plan_name`
|
||||
|
||||
2. Create Trigger:
|
||||
- Type: Custom Event
|
||||
- Event Name: `signup_completed`
|
||||
- Name: `DL Event - signup_completed`
|
||||
|
||||
3. Create Tag:
|
||||
- Type: Google Analytics: GA4 Event
|
||||
- Configuration Tag: GA4 Config tag
|
||||
- Event Name: `signup_completed`
|
||||
- Event Parameters:
|
||||
- `method`: `{{DLV - signup_method}}`
|
||||
- `user_id`: `{{DLV - user_id}}`
|
||||
- `plan_name`: `{{DLV - plan_name}}`
|
||||
- Trigger: `DL Event - signup_completed`
|
||||
|
||||
---
|
||||
|
||||
### Pattern 2: Click Event on Specific Element
|
||||
|
||||
Use when you can't modify app code and need to track a specific CTA.
|
||||
|
||||
**GTM Setup:**
|
||||
|
||||
1. Enable `Click - All Elements` built-in variables (if not enabled):
|
||||
- GTM → Variables → Configure → Enable: Click Element, Click ID, Click Classes, Click Text
|
||||
|
||||
2. Create Trigger:
|
||||
- Type: Click - All Elements
|
||||
- Fire On: Some Clicks
|
||||
- Conditions:
|
||||
- Click Element matches CSS selector: `[data-track="demo-cta"]`
|
||||
OR
|
||||
- Click Text equals "Request a Demo"
|
||||
- Name: `Click - Demo CTA`
|
||||
|
||||
3. Create Tag:
|
||||
- Type: GA4 Event
|
||||
- Event Name: `demo_requested`
|
||||
- Event Parameters:
|
||||
- `page_location`: `{{Page URL}}`
|
||||
- `click_text`: `{{Click Text}}`
|
||||
- Trigger: `Click - Demo CTA`
|
||||
|
||||
**Best practice:** Add `data-track` attributes to important elements in your HTML rather than relying on brittle CSS selectors or text matching.
|
||||
|
||||
```html
|
||||
<button data-track="demo-cta" data-track-source="pricing-hero">
|
||||
Request a Demo
|
||||
</button>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 3: Form Submission Tracking
|
||||
|
||||
Two approaches depending on whether the form submits via JavaScript or full page reload.
|
||||
|
||||
**For JavaScript-handled forms (AJAX/fetch):**
|
||||
- Use Pattern 1 (dataLayer push) after successful form submission callback
|
||||
|
||||
**For traditional form submit:**
|
||||
|
||||
1. Create Trigger:
|
||||
- Type: Form Submission
|
||||
- Check Validation: ✅ (only fires if form passes HTML5 validation)
|
||||
- Enable History Change: ✅ (for SPAs)
|
||||
- Fire On: Some Forms
|
||||
- Conditions: Form ID equals `contact-form` OR Form Classes contains `js-track-form`
|
||||
- Name: `Form Submit - Contact`
|
||||
|
||||
2. Create Tag:
|
||||
- Type: GA4 Event
|
||||
- Event Name: `form_submitted`
|
||||
- Parameters:
|
||||
- `form_name`: `contact`
|
||||
- `page_location`: `{{Page URL}}`
|
||||
- Trigger: `Form Submit - Contact`
|
||||
|
||||
---
|
||||
|
||||
### Pattern 4: SPA Page View Tracking
|
||||
|
||||
Single-page apps often don't trigger standard page view events on route changes.
|
||||
|
||||
**Approach A: History Change trigger (simplest)**
|
||||
|
||||
1. Create Trigger:
|
||||
- Type: History Change
|
||||
- Name: `History Change - Route`
|
||||
|
||||
2. Create Tag:
|
||||
- Type: GA4 Event
|
||||
- Event Name: `page_view`
|
||||
- Parameters:
|
||||
- `page_location`: `{{Page URL}}`
|
||||
- `page_title`: `{{Page Title}}`
|
||||
- Trigger: `History Change - Route`
|
||||
|
||||
**Important:** Disable the default pageview in your GA4 Configuration tag if using this, or you'll get duplicates on initial load.
|
||||
|
||||
**Approach B: dataLayer push from router (more reliable)**
|
||||
|
||||
```javascript
|
||||
// In your router's navigation handler:
|
||||
router.afterEach((to, from) => {
|
||||
window.dataLayer.push({
|
||||
event: 'page_view',
|
||||
page_path: to.path,
|
||||
page_title: document.title
|
||||
});
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Pattern 5: Scroll Depth Tracking
|
||||
|
||||
For content engagement measurement:
|
||||
|
||||
**Option A: Use GA4 Enhanced Measurement (90% depth only)**
|
||||
- Enable in GA4 → Data Streams → Enhanced Measurement → Scrolls
|
||||
- Fires when user scrolls 90% down the page
|
||||
- No GTM configuration needed
|
||||
|
||||
**Option B: Custom milestones via GTM**
|
||||
|
||||
1. Create Trigger for each depth:
|
||||
- Type: Scroll Depth
|
||||
- Vertical Scroll Depths: 25, 50, 75, 100 (percent)
|
||||
- Enable for: Some Pages → Page Path contains `/blog/`
|
||||
- Name: `Scroll Depth - Blog`
|
||||
|
||||
2. Create Tag:
|
||||
- Type: GA4 Event
|
||||
- Event Name: `content_scrolled`
|
||||
- Parameters:
|
||||
- `scroll_depth_pct`: `{{Scroll Depth Threshold}}`
|
||||
- `page_location`: `{{Page URL}}`
|
||||
- Trigger: `Scroll Depth - Blog`
|
||||
|
||||
---
|
||||
|
||||
### Pattern 6: Consent Mode Integration
|
||||
|
||||
For GDPR compliance — connect your CMP to GTM.
|
||||
|
||||
**Basic Consent Mode (blocks all when declined):**
|
||||
|
||||
```javascript
|
||||
// In your CMP callback:
|
||||
window.dataLayer.push({
|
||||
event: 'cookie_consent_update',
|
||||
ad_storage: 'denied', // or 'granted'
|
||||
analytics_storage: 'denied', // or 'granted'
|
||||
functionality_storage: 'denied',
|
||||
personalization_storage: 'denied',
|
||||
security_storage: 'granted' // always granted
|
||||
});
|
||||
```
|
||||
|
||||
**Advanced Consent Mode (modeled data for declined users):**
|
||||
|
||||
Add to `<head>` BEFORE GTM loads:
|
||||
```javascript
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
function gtag(){dataLayer.push(arguments);}
|
||||
|
||||
// Default all to denied
|
||||
gtag('consent', 'default', {
|
||||
ad_storage: 'denied',
|
||||
analytics_storage: 'denied',
|
||||
wait_for_update: 500 // ms to wait for CMP to initialize
|
||||
});
|
||||
```
|
||||
|
||||
Then update when user consents:
|
||||
```javascript
|
||||
gtag('consent', 'update', {
|
||||
analytics_storage: 'granted'
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GTM Version Control
|
||||
|
||||
### Version Naming Convention
|
||||
|
||||
```
|
||||
v1.0 - Initial setup: GA4 + core events
|
||||
v1.1 - Add: checkout tracking
|
||||
v1.2 - Fix: duplicate pageview on SPA
|
||||
v2.0 - Overhaul: new event taxonomy + Meta Pixel
|
||||
```
|
||||
|
||||
### Publishing Protocol
|
||||
|
||||
1. Test in GTM Preview mode — verify events fire correctly
|
||||
2. Test in GA4 DebugView — confirm parameters are captured
|
||||
3. Test with GTM's "What changed?" diff view
|
||||
4. Add version notes (what changed + why)
|
||||
5. Publish to production
|
||||
6. Verify in GA4 Realtime view post-publish
|
||||
|
||||
### Environments
|
||||
|
||||
Create a staging environment in GTM (Admin → Environments):
|
||||
- Development: test changes without affecting production
|
||||
- Staging: validate before publish
|
||||
- Production: live
|
||||
|
||||
Share staging GTM snippet with your dev team so they test against the same container.
|
||||
|
||||
---
|
||||
|
||||
## Common GTM Mistakes
|
||||
|
||||
| Mistake | Symptom | Fix |
|
||||
|---------|---------|-----|
|
||||
| Tag fires on "All Pages" when it should be scoped | Inflated event counts | Add page conditions to trigger |
|
||||
| Data Layer Variable path is wrong | Parameter shows as `undefined` | Use GTM Preview to inspect dataLayer structure |
|
||||
| GA4 Configuration tag fires multiple times | Duplicate sessions/users | Check all triggers — should be one trigger, "All Pages" |
|
||||
| Enhanced Measurement conflicts with custom tags | Duplicate outbound click events | Disable conflicting Enhanced Measurement settings |
|
||||
| Trigger fires before DOM ready | Element not found errors | Change trigger type from "Page View" to "DOM Ready" or "Window Loaded" |
|
||||
| Form trigger doesn't fire | Form uses AJAX or custom submit | Switch to dataLayer push after submit callback |
|
||||
@@ -0,0 +1,371 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Tracking plan generator — produces event taxonomy, GTM config, and GA4 dimension recommendations."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
|
||||
SAMPLE_INPUT = {
|
||||
"business_type": "saas",
|
||||
"key_pages": [
|
||||
{"name": "Homepage", "path": "/"},
|
||||
{"name": "Pricing", "path": "/pricing"},
|
||||
{"name": "Signup", "path": "/signup"},
|
||||
{"name": "Dashboard", "path": "/app/dashboard"},
|
||||
{"name": "Onboarding", "path": "/app/onboarding"}
|
||||
],
|
||||
"conversion_actions": [
|
||||
{"name": "Signup", "type": "registration", "value": 0},
|
||||
{"name": "Trial Start", "type": "trial", "value": 0},
|
||||
{"name": "Subscription Purchase", "type": "purchase", "value": 99},
|
||||
{"name": "Demo Request", "type": "lead", "value": 0}
|
||||
],
|
||||
"paid_channels": ["google_ads", "meta"],
|
||||
"consent_required": True
|
||||
}
|
||||
|
||||
|
||||
EVENT_TEMPLATES = {
|
||||
"saas": {
|
||||
"acquisition": [
|
||||
{
|
||||
"event": "pricing_viewed",
|
||||
"trigger": "User navigates to /pricing",
|
||||
"parameters": ["page_location", "utm_source", "referrer_page"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "demo_requested",
|
||||
"trigger": "User submits demo request form",
|
||||
"parameters": ["source", "page_location", "form_name"],
|
||||
"priority": "high",
|
||||
"is_conversion": True
|
||||
},
|
||||
{
|
||||
"event": "content_downloaded",
|
||||
"trigger": "User downloads gated content",
|
||||
"parameters": ["content_name", "content_type", "gated"],
|
||||
"priority": "medium"
|
||||
}
|
||||
],
|
||||
"registration": [
|
||||
{
|
||||
"event": "signup_started",
|
||||
"trigger": "User clicks primary signup CTA",
|
||||
"parameters": ["page_location", "cta_text", "plan_name"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "signup_completed",
|
||||
"trigger": "User account successfully created",
|
||||
"parameters": ["method", "user_id", "plan_name"],
|
||||
"priority": "critical",
|
||||
"is_conversion": True
|
||||
},
|
||||
{
|
||||
"event": "trial_started",
|
||||
"trigger": "Free trial begins",
|
||||
"parameters": ["plan_name", "trial_length_days", "user_id"],
|
||||
"priority": "critical",
|
||||
"is_conversion": True
|
||||
}
|
||||
],
|
||||
"onboarding": [
|
||||
{
|
||||
"event": "onboarding_started",
|
||||
"trigger": "User enters onboarding flow",
|
||||
"parameters": ["user_id", "onboarding_variant"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "onboarding_step_completed",
|
||||
"trigger": "User completes each onboarding step",
|
||||
"parameters": ["step_name", "step_number", "user_id", "time_spent_seconds"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "onboarding_completed",
|
||||
"trigger": "User completes full onboarding",
|
||||
"parameters": ["steps_total", "user_id", "time_to_complete_seconds"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "feature_activated",
|
||||
"trigger": "User activates a key feature for first time",
|
||||
"parameters": ["feature_name", "user_id", "activation_method"],
|
||||
"priority": "medium"
|
||||
}
|
||||
],
|
||||
"conversion": [
|
||||
{
|
||||
"event": "plan_selected",
|
||||
"trigger": "User clicks on a pricing plan",
|
||||
"parameters": ["plan_name", "billing_period", "value"],
|
||||
"priority": "critical"
|
||||
},
|
||||
{
|
||||
"event": "checkout_started",
|
||||
"trigger": "User enters checkout flow",
|
||||
"parameters": ["plan_name", "value", "currency", "billing_period"],
|
||||
"priority": "critical"
|
||||
},
|
||||
{
|
||||
"event": "checkout_completed",
|
||||
"trigger": "Payment successfully processed",
|
||||
"parameters": ["plan_name", "value", "currency", "transaction_id", "billing_period"],
|
||||
"priority": "critical",
|
||||
"is_conversion": True
|
||||
}
|
||||
],
|
||||
"retention": [
|
||||
{
|
||||
"event": "subscription_cancelled",
|
||||
"trigger": "User confirms cancellation",
|
||||
"parameters": ["cancel_reason", "plan_name", "save_offer_shown", "save_offer_accepted"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "subscription_reactivated",
|
||||
"trigger": "Cancelled user reactivates",
|
||||
"parameters": ["plan_name", "days_since_cancel"],
|
||||
"priority": "high"
|
||||
}
|
||||
]
|
||||
},
|
||||
"ecommerce": {
|
||||
"acquisition": [
|
||||
{
|
||||
"event": "product_viewed",
|
||||
"trigger": "User views a product page",
|
||||
"parameters": ["item_id", "item_name", "item_category", "value"],
|
||||
"priority": "high"
|
||||
},
|
||||
{
|
||||
"event": "search_performed",
|
||||
"trigger": "User submits a search query",
|
||||
"parameters": ["search_term", "results_count"],
|
||||
"priority": "medium"
|
||||
}
|
||||
],
|
||||
"conversion": [
|
||||
{
|
||||
"event": "add_to_cart",
|
||||
"trigger": "User adds item to cart",
|
||||
"parameters": ["item_id", "item_name", "value", "currency", "quantity"],
|
||||
"priority": "critical"
|
||||
},
|
||||
{
|
||||
"event": "checkout_started",
|
||||
"trigger": "User begins checkout",
|
||||
"parameters": ["value", "currency", "num_items"],
|
||||
"priority": "critical"
|
||||
},
|
||||
{
|
||||
"event": "checkout_completed",
|
||||
"trigger": "Order placed successfully",
|
||||
"parameters": ["transaction_id", "value", "currency", "tax", "shipping"],
|
||||
"priority": "critical",
|
||||
"is_conversion": True
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
CUSTOM_DIMENSIONS = {
|
||||
"user_scoped": [
|
||||
{"name": "User ID", "parameter": "user_id", "description": "Internal user identifier"},
|
||||
{"name": "Plan Name", "parameter": "plan_name", "description": "Current subscription plan"},
|
||||
{"name": "Billing Period", "parameter": "billing_period", "description": "Monthly or annual"},
|
||||
{"name": "Signup Method", "parameter": "signup_method", "description": "Email, Google, SSO"},
|
||||
{"name": "Onboarding Status", "parameter": "onboarding_completed", "description": "Boolean: completed onboarding?"}
|
||||
],
|
||||
"event_scoped": [
|
||||
{"name": "Cancel Reason", "parameter": "cancel_reason", "description": "Exit survey selection"},
|
||||
{"name": "Feature Name", "parameter": "feature_name", "description": "Feature being used/activated"},
|
||||
{"name": "Form Name", "parameter": "form_name", "description": "Which form was submitted"},
|
||||
{"name": "Content Name", "parameter": "content_name", "description": "Downloaded/viewed content"},
|
||||
{"name": "Error Type", "parameter": "error_type", "description": "Type of error encountered"}
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
def generate_tracking_plan(inputs):
|
||||
biz_type = inputs.get("business_type", "saas")
|
||||
templates = EVENT_TEMPLATES.get(biz_type, EVENT_TEMPLATES["saas"])
|
||||
paid = inputs.get("paid_channels", [])
|
||||
consent = inputs.get("consent_required", False)
|
||||
conversions = inputs.get("conversion_actions", [])
|
||||
|
||||
# Build event taxonomy
|
||||
all_events = []
|
||||
for category, events in templates.items():
|
||||
for ev in events:
|
||||
all_events.append({**ev, "category": category})
|
||||
|
||||
# Add conversion-specific events from input
|
||||
conversion_events = []
|
||||
for ca in conversions:
|
||||
if ca["type"] == "purchase":
|
||||
for ev in all_events:
|
||||
if ev["event"] == "checkout_completed":
|
||||
ev["value_hint"] = ca["value"]
|
||||
conversion_events.append("checkout_completed")
|
||||
elif ca["type"] == "registration":
|
||||
conversion_events.append("signup_completed")
|
||||
elif ca["type"] == "lead":
|
||||
conversion_events.append("demo_requested")
|
||||
elif ca["type"] == "trial":
|
||||
conversion_events.append("trial_started")
|
||||
|
||||
# GTM tag configuration
|
||||
gtm_tags = []
|
||||
for ev in all_events:
|
||||
gtm_tags.append({
|
||||
"tag_name": f"GA4 - {ev['event']}",
|
||||
"tag_type": "ga4_event",
|
||||
"event_name": ev["event"],
|
||||
"trigger": f"DL Event - {ev['event']}",
|
||||
"parameters": ev["parameters"],
|
||||
"priority": ev.get("priority", "medium")
|
||||
})
|
||||
|
||||
# Add platform-specific tags
|
||||
if "google_ads" in paid:
|
||||
for ev in all_events:
|
||||
if ev.get("is_conversion"):
|
||||
gtm_tags.append({
|
||||
"tag_name": f"Google Ads - {ev['event']}",
|
||||
"tag_type": "google_ads_conversion",
|
||||
"event_name": ev["event"],
|
||||
"trigger": f"DL Event - {ev['event']}",
|
||||
"note": "Import from GA4 conversions (preferred) or configure conversion ID"
|
||||
})
|
||||
|
||||
if "meta" in paid:
|
||||
gtm_tags.append({
|
||||
"tag_name": "Meta Pixel - Base",
|
||||
"tag_type": "html_tag",
|
||||
"trigger": "All Pages",
|
||||
"note": "Meta base pixel — fires on all pages. Add Standard Events separately."
|
||||
})
|
||||
|
||||
# Consent configuration
|
||||
consent_config = None
|
||||
if consent:
|
||||
consent_config = {
|
||||
"mode": "advanced",
|
||||
"defaults": {
|
||||
"analytics_storage": "denied",
|
||||
"ad_storage": "denied",
|
||||
"functionality_storage": "denied"
|
||||
},
|
||||
"update_trigger": "cookie_consent_update",
|
||||
"note": "Implement before GTM loads. Requires CMP integration (Cookiebot, OneTrust, etc.)."
|
||||
}
|
||||
|
||||
return {
|
||||
"event_taxonomy": [
|
||||
{
|
||||
"category": ev["category"],
|
||||
"event": ev["event"],
|
||||
"trigger": ev["trigger"],
|
||||
"parameters": ev["parameters"],
|
||||
"priority": ev.get("priority", "medium"),
|
||||
"is_conversion": ev.get("is_conversion", False)
|
||||
}
|
||||
for ev in all_events
|
||||
],
|
||||
"conversion_events": list(set(conversion_events)),
|
||||
"gtm_configuration": {
|
||||
"tags": gtm_tags,
|
||||
"variable_count": len(set(p for ev in all_events for p in ev["parameters"])),
|
||||
"trigger_count": len(all_events)
|
||||
},
|
||||
"ga4_custom_dimensions": CUSTOM_DIMENSIONS,
|
||||
"consent_mode": consent_config,
|
||||
"implementation_order": [
|
||||
"1. Register custom dimensions in GA4 (Admin > Custom Definitions)",
|
||||
"2. Set up GTM container structure (variables first, then triggers, then tags)",
|
||||
"3. Implement dataLayer pushes in application code",
|
||||
"4. Test each event in GTM Preview + GA4 DebugView",
|
||||
"5. Mark conversion events in GA4 (Admin > Conversions)",
|
||||
"6. Link GA4 to Google Ads if running paid search",
|
||||
"7. Enable internal traffic filter",
|
||||
"8. Implement consent mode if required"
|
||||
]
|
||||
}
|
||||
|
||||
|
||||
def print_report(result, inputs):
|
||||
print("\n" + "="*65)
|
||||
print(" TRACKING PLAN GENERATOR")
|
||||
print("="*65)
|
||||
|
||||
print(f"\n📋 BUSINESS TYPE: {inputs.get('business_type', 'saas').upper()}")
|
||||
|
||||
events = result["event_taxonomy"]
|
||||
by_priority = defaultdict(list)
|
||||
for ev in events:
|
||||
by_priority[ev["priority"]].append(ev)
|
||||
|
||||
print(f"\n📊 EVENT TAXONOMY ({len(events)} events)")
|
||||
for priority in ["critical", "high", "medium", "low"]:
|
||||
evs = by_priority.get(priority, [])
|
||||
if evs:
|
||||
marker = "🔴" if priority == "critical" else "🟡" if priority == "high" else "⚪"
|
||||
print(f"\n {marker} {priority.upper()} ({len(evs)} events)")
|
||||
for ev in evs:
|
||||
conv = " ← CONVERSION" if ev["is_conversion"] else ""
|
||||
print(f" {ev['event']}{conv}")
|
||||
print(f" Params: {', '.join(ev['parameters'][:4])}" +
|
||||
(f"... +{len(ev['parameters'])-4} more" if len(ev['parameters']) > 4 else ""))
|
||||
|
||||
conversions = result["conversion_events"]
|
||||
print(f"\n🎯 CONVERSION EVENTS ({len(conversions)})")
|
||||
for ev in conversions:
|
||||
print(f" • {ev}")
|
||||
|
||||
dims = result["ga4_custom_dimensions"]
|
||||
print(f"\n📐 CUSTOM DIMENSIONS")
|
||||
print(f" User-scoped ({len(dims['user_scoped'])}): " +
|
||||
", ".join(d["parameter"] for d in dims["user_scoped"]))
|
||||
print(f" Event-scoped ({len(dims['event_scoped'])}): " +
|
||||
", ".join(d["parameter"] for d in dims["event_scoped"]))
|
||||
|
||||
gtm = result["gtm_configuration"]
|
||||
print(f"\n🏷️ GTM CONFIGURATION")
|
||||
print(f" Tags to create: {len(gtm['tags'])}")
|
||||
print(f" Triggers to create: {gtm['trigger_count']}")
|
||||
print(f" Variables to create:{gtm['variable_count']}")
|
||||
|
||||
if result["consent_mode"]:
|
||||
print(f"\n🔒 CONSENT MODE: Advanced (required)")
|
||||
print(f" Default state: analytics_storage=denied, ad_storage=denied")
|
||||
|
||||
print(f"\n📋 IMPLEMENTATION ORDER")
|
||||
for step in result["implementation_order"]:
|
||||
print(f" {step}")
|
||||
|
||||
print("\n" + "="*65)
|
||||
print(" Run with --json flag to output full config as JSON")
|
||||
print("="*65 + "\n")
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) > 1 and sys.argv[1] != "--json":
|
||||
with open(sys.argv[1]) as f:
|
||||
inputs = json.load(f)
|
||||
else:
|
||||
if "--json" not in sys.argv:
|
||||
print("No input file provided. Running with sample data...\n")
|
||||
inputs = SAMPLE_INPUT
|
||||
|
||||
result = generate_tracking_plan(inputs)
|
||||
print_report(result, inputs)
|
||||
|
||||
if "--json" in sys.argv:
|
||||
print(json.dumps(result, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -493,3 +493,25 @@ Trusted by 500,000+ professionals.
|
||||
| [content-creator](../content-creator/) | App description copywriting |
|
||||
| [marketing-demand-acquisition](../marketing-demand-acquisition/) | Launch promotion campaigns |
|
||||
| [marketing-strategy-pmm](../marketing-strategy-pmm/) | Go-to-market planning |
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
- **No keyword optimization in title** → App title is the #1 ranking factor. Include top keyword.
|
||||
- **Screenshots don't show value** → Screenshots should tell a story, not show UI.
|
||||
- **No ratings strategy** → Below 4.0 stars kills conversion. Implement in-app rating prompts.
|
||||
- **Description keyword-stuffed** → Natural language with keywords beats keyword stuffing.
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| "ASO audit" | Full app store listing audit with prioritized fixes |
|
||||
| "Keyword research" | Keyword list with search volume and difficulty scores |
|
||||
| "Optimize my listing" | Rewritten title, subtitle, description, keyword field |
|
||||
|
||||
## Communication
|
||||
|
||||
All output passes quality verification:
|
||||
- Self-verify: source attribution, assumption audit, confidence scoring
|
||||
- Output format: Bottom Line → What (with confidence) → Why → How to Act
|
||||
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
|
||||
|
||||
351
marketing-skill/brand-guidelines/SKILL.md
Normal file
351
marketing-skill/brand-guidelines/SKILL.md
Normal file
@@ -0,0 +1,351 @@
|
||||
---
|
||||
name: brand-guidelines
|
||||
description: "When the user wants to apply, document, or enforce brand guidelines for any product or company. Also use when the user mentions 'brand guidelines,' 'brand colors,' 'typography,' 'logo usage,' 'brand voice,' 'visual identity,' 'tone of voice,' 'brand standards,' 'style guide,' 'brand consistency,' or 'company design standards.' Covers color systems, typography, logo rules, imagery guidelines, and tone matrix for any brand — including Anthropic's official identity."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Brand Guidelines
|
||||
|
||||
You are an expert in brand identity and visual design standards. Your goal is to help teams apply brand guidelines consistently across all marketing materials, products, and communications — whether working with an established brand system or building one from scratch.
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before applying brand standards. Use that context to tailor recommendations to the specific brand.
|
||||
|
||||
When helping users:
|
||||
1. Identify whether they need to *apply* existing guidelines or *create* new ones
|
||||
2. For Anthropic artifacts, use the Anthropic identity system below
|
||||
3. For other brands, use the framework sections to assess and document their system
|
||||
4. Always check for consistency before creativity
|
||||
|
||||
---
|
||||
|
||||
## Anthropic Brand Identity
|
||||
|
||||
### Overview
|
||||
|
||||
Anthropic's brand identity is clean, precise, and intellectually grounded. It communicates trustworthiness and technical sophistication without feeling cold or corporate.
|
||||
|
||||
### Color System
|
||||
|
||||
**Primary Palette:**
|
||||
|
||||
| Name | Hex | RGB | Use |
|
||||
|------|-----|-----|-----|
|
||||
| Dark | `#141413` | 20, 20, 19 | Primary text, dark backgrounds |
|
||||
| Light | `#faf9f5` | 250, 249, 245 | Light backgrounds, text on dark |
|
||||
| Mid Gray | `#b0aea5` | 176, 174, 165 | Secondary elements, dividers |
|
||||
| Light Gray | `#e8e6dc` | 232, 230, 220 | Subtle backgrounds, borders |
|
||||
|
||||
**Accent Palette:**
|
||||
|
||||
| Name | Hex | RGB | Use |
|
||||
|------|-----|-----|-----|
|
||||
| Orange | `#d97757` | 217, 119, 87 | Primary accent, CTAs |
|
||||
| Blue | `#6a9bcc` | 106, 155, 204 | Secondary accent, links |
|
||||
| Green | `#788c5d` | 120, 140, 93 | Tertiary accent, success states |
|
||||
|
||||
**Color Application Rules:**
|
||||
- Never use accent colors as large background fills — use them for emphasis only
|
||||
- Dark on Light or Light on Dark — avoid mixing Dark on Mid Gray for body text
|
||||
- Accent colors cycle: Orange (primary CTA) → Blue (supporting) → Green (tertiary)
|
||||
- When in doubt, default to Dark + Light with one accent
|
||||
|
||||
### Typography
|
||||
|
||||
**Type Scale:**
|
||||
|
||||
| Role | Font | Fallback | Weight | Size Range |
|
||||
|------|------|----------|--------|------------|
|
||||
| Display / H1 | Poppins | Arial | 600–700 | 32pt+ |
|
||||
| Headings H2–H4 | Poppins | Arial | 500–600 | 20–31pt |
|
||||
| Body | Lora | Georgia | 400 | 14–18pt |
|
||||
| Caption / Label | Poppins | Arial | 400–500 | 10–13pt |
|
||||
| Code / Mono | Courier New | monospace | 400 | 12–14pt |
|
||||
|
||||
**Typography Rules:**
|
||||
- Never set body copy in Poppins — it's a display/heading font
|
||||
- Minimum body size: 14pt for print, 16px for web
|
||||
- Line height: 1.5–1.6 for body, 1.1–1.2 for headings
|
||||
- Letter spacing: -0.5px to -1px for large headings; 0 for body
|
||||
|
||||
**Font Installation:**
|
||||
- Poppins: Available on Google Fonts (`fonts.google.com/specimen/Poppins`)
|
||||
- Lora: Available on Google Fonts (`fonts.google.com/specimen/Lora`)
|
||||
- Both should be pre-installed in design environments for best results
|
||||
|
||||
### Logo Usage
|
||||
|
||||
**Clear Space:**
|
||||
Maintain minimum clear space equal to the cap-height of the wordmark on all sides. No other elements should intrude on this zone.
|
||||
|
||||
**Minimum Size:**
|
||||
- Digital: 120px wide minimum
|
||||
- Print: 25mm wide minimum
|
||||
|
||||
**Approved Variations:**
|
||||
- Dark logo on Light background (primary)
|
||||
- Light logo on Dark background (inverted)
|
||||
- Single-color Dark on any light neutral
|
||||
- Single-color Light on any dark surface
|
||||
|
||||
**Prohibited Uses:**
|
||||
- Do not stretch or distort the logo
|
||||
- Do not apply drop shadows, gradients, or outlines
|
||||
- Do not place on busy photographic backgrounds without a color block
|
||||
- Do not use accent colors as the logo fill
|
||||
- Do not rotate the logo
|
||||
|
||||
### Imagery Guidelines
|
||||
|
||||
**Photography Style:**
|
||||
- Clean, well-lit, minimal post-processing
|
||||
- Subjects: people at work, abstract technical concepts, precise objects
|
||||
- Avoid: stock photo clichés, overly emotive poses, heavy filters
|
||||
- Color treatment: neutral tones preferred; desaturate if needed to match palette
|
||||
|
||||
**Illustration Style:**
|
||||
- Geometric, precise line work
|
||||
- Limited palette: use brand colors only
|
||||
- Avoid: cartoonish characters, heavy gradients, 3D renders
|
||||
|
||||
**Iconography:**
|
||||
- Stroke-based, consistent weight (2px at 24px size)
|
||||
- Rounded caps preferred; sharp corners acceptable for technical contexts
|
||||
- Use Mid Gray or Dark; accent color only for active/selected states
|
||||
|
||||
---
|
||||
|
||||
## Universal Brand Guidelines Framework
|
||||
|
||||
Use this section when building or auditing guidelines for *any* brand (not Anthropic-specific).
|
||||
|
||||
### 1. Brand Foundation
|
||||
|
||||
Before any visual decisions, the brand foundation must exist:
|
||||
|
||||
| Element | Definition |
|
||||
|---------|-----------|
|
||||
| **Mission** | Why the company exists beyond making money |
|
||||
| **Vision** | The future state the brand is working toward |
|
||||
| **Values** | 3–5 core principles that drive decisions |
|
||||
| **Positioning** | What you are, for whom, against what alternative |
|
||||
| **Personality** | How the brand behaves — adjectives that guide tone |
|
||||
|
||||
A visual identity without a foundation is decoration. The foundation drives every downstream decision.
|
||||
|
||||
---
|
||||
|
||||
### 2. Color System
|
||||
|
||||
#### Primary Palette (2–3 colors)
|
||||
- One dominant neutral (background or text)
|
||||
- One strong brand color (most recognition, hero elements)
|
||||
- One supporting color (secondary backgrounds, dividers)
|
||||
|
||||
#### Accent Palette (2–4 colors)
|
||||
- Used sparingly for emphasis, CTAs, states
|
||||
- Must pass WCAG AA contrast against backgrounds they appear on
|
||||
|
||||
#### Color Rules to Document:
|
||||
- Which color for CTAs vs. informational links
|
||||
- Background color combinations that are approved
|
||||
- Colors that should never appear together
|
||||
- Dark mode equivalents
|
||||
|
||||
#### Accessibility Requirements:
|
||||
- Normal text (< 18pt): minimum 4.5:1 contrast ratio (WCAG AA)
|
||||
- Large text (≥ 18pt): minimum 3:1 contrast ratio
|
||||
- UI components: minimum 3:1 against adjacent colors
|
||||
- Test: `webaim.org/resources/contrastchecker`
|
||||
|
||||
---
|
||||
|
||||
### 3. Typography System
|
||||
|
||||
#### Type Roles to Define:
|
||||
|
||||
| Role | Font | Size Range | Weight | Line Height |
|
||||
|------|------|-----------|--------|-------------|
|
||||
| Display | — | 40pt+ | Bold | 1.1 |
|
||||
| H1 | — | 28–40pt | SemiBold | 1.15 |
|
||||
| H2 | — | 22–28pt | SemiBold | 1.2 |
|
||||
| H3 | — | 18–22pt | Medium | 1.25 |
|
||||
| Body | — | 15–18pt | Regular | 1.5–1.6 |
|
||||
| Small / Caption | — | 12–14pt | Regular | 1.4 |
|
||||
| Label / UI | — | 11–13pt | Medium | 1.2 |
|
||||
|
||||
#### Font Selection Criteria:
|
||||
- Max 2 typeface families (one serif or slab, one sans-serif)
|
||||
- Both must be available in all required weights
|
||||
- Must render well at small sizes on screen
|
||||
- Licensing must cover all intended uses (web, print, app)
|
||||
|
||||
---
|
||||
|
||||
### 4. Logo System
|
||||
|
||||
#### Variations Required:
|
||||
- **Primary**: full color on white/light
|
||||
- **Inverted**: light version on dark backgrounds
|
||||
- **Monochrome**: single color for single-color applications
|
||||
- **Mark only**: icon/symbol without wordmark (for small sizes)
|
||||
- **Horizontal + Stacked**: where layout demands both
|
||||
|
||||
#### Usage Rules to Document:
|
||||
- Minimum size (px for digital, mm for print)
|
||||
- Clear space formula
|
||||
- Approved background colors
|
||||
- Prohibited modifications (distortion, recoloring, shadows)
|
||||
- Co-branding rules (partner logo sizing, spacing)
|
||||
|
||||
---
|
||||
|
||||
### 5. Imagery Guidelines
|
||||
|
||||
#### Photography Criteria:
|
||||
| Dimension | Guideline |
|
||||
|-----------|-----------|
|
||||
| **People** | Authentic, diverse, action-oriented — not posed stock |
|
||||
| **Lighting** | Clean and directional; avoid heavy shadows or blown highlights |
|
||||
| **Color treatment** | Align to brand palette; desaturate or tint if necessary |
|
||||
| **Subjects** | Match brand values — avoid anything that conflicts with positioning |
|
||||
|
||||
#### Illustration Style:
|
||||
- Define: flat vs. 3D, line vs. filled, abstract vs. representational
|
||||
- Set a palette limit: brand colors only, or approved expanded set
|
||||
- Define stroke weight and corner radius standards
|
||||
|
||||
#### Do / Don't Matrix (customize per brand):
|
||||
|
||||
| ✅ Do | ❌ Don't |
|
||||
|-------|---------|
|
||||
| Show real customers and use cases | Use generic multicultural stock |
|
||||
| Use natural lighting | Use heavy vignettes or HDR |
|
||||
| Keep backgrounds clean | Place subjects on clashing colors |
|
||||
| Match brand palette tones | Use heavy Instagram-style filters |
|
||||
|
||||
---
|
||||
|
||||
### 6. Tone of Voice & Tone Matrix
|
||||
|
||||
Brand voice is consistent; tone adapts to context.
|
||||
|
||||
#### Voice Attributes (define 4–6):
|
||||
|
||||
| Attribute | What It Means | What It's Not |
|
||||
|-----------|---------------|---------------|
|
||||
| Example: **Direct** | Say what you mean; no filler | Blunt or dismissive |
|
||||
| Example: **Curious** | Ask questions, show genuine interest | Condescending or know-it-all |
|
||||
| Example: **Precise** | Specific language, no vague claims | Technical jargon that excludes |
|
||||
| Example: **Warm** | Human and approachable | Overly casual or unprofessional |
|
||||
|
||||
#### Tone Matrix by Context:
|
||||
|
||||
| Context | Tone Dial | Example Shift |
|
||||
|---------|-----------|--------------|
|
||||
| Error messages | Calm, helpful, matter-of-fact | Less formal than marketing |
|
||||
| Marketing headlines | Confident, energetic | More punchy than support |
|
||||
| Legal / compliance | Precise, neutral | Less personality |
|
||||
| Support / help content | Patient, empathetic | More warmth than ads |
|
||||
| Social media | Conversational, light | More informal than web |
|
||||
| Executive communications | Authoritative, measured | More formal than blog |
|
||||
|
||||
#### Words to Use / Avoid (document per brand):
|
||||
|
||||
| ✅ Use | ❌ Avoid |
|
||||
|-------|---------|
|
||||
| "We" (inclusive) | "Leverage" (jargon) |
|
||||
| Specific numbers | "Best-in-class" (vague) |
|
||||
| Active voice | Passive constructions |
|
||||
| Short sentences | Run-on complexity |
|
||||
|
||||
---
|
||||
|
||||
### 7. Application Examples
|
||||
|
||||
#### Digital
|
||||
- **Web**: Primary palette for backgrounds; accent for CTAs; Poppins/brand heading font for H1–H3
|
||||
- **Email**: Inline styles only; web-safe font fallbacks always specified; logo as linked image
|
||||
- **Social**: Platform-specific safe zones; brand colors dominant; minimal text on images
|
||||
|
||||
#### Print
|
||||
- Always use CMYK values for print production (never RGB or hex)
|
||||
- Bleed: 3mm on all sides; keep critical content 5mm from trim
|
||||
- Proof against Pantone reference before bulk print runs
|
||||
|
||||
#### Presentations
|
||||
- Cover slide: brand dark + brand light with single accent
|
||||
- Body slides: white backgrounds with brand accent headers
|
||||
- No custom fonts in share files — embed or substitute
|
||||
|
||||
---
|
||||
|
||||
## Quick Audit Checklist
|
||||
|
||||
Use this to rapidly assess brand consistency across any asset:
|
||||
|
||||
- [ ] Colors match approved palette (no off-brand variations)
|
||||
- [ ] Fonts are correct typeface and weight
|
||||
- [ ] Logo has proper clear space and is an approved variation
|
||||
- [ ] Body text meets minimum size and contrast requirements
|
||||
- [ ] Imagery style matches brand guidelines
|
||||
- [ ] Tone matches brand voice attributes
|
||||
- [ ] No prohibited uses present (gradients on logo, wrong accent color, etc.)
|
||||
- [ ] Co-branding (if any) follows partner logo rules
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. Are you applying existing guidelines or creating new ones?
|
||||
2. What's the output format? (Digital, print, presentation, social)
|
||||
3. Do you have existing brand assets? (Logo files, color codes, fonts)
|
||||
4. Is there a brand foundation document? (Mission, values, positioning)
|
||||
5. What's the specific inconsistency or gap you're trying to fix?
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Proactively apply brand guidelines when:
|
||||
|
||||
1. **Any visual asset requested** — Before creating any poster, slide, email, or social graphic, check if brand guidelines exist; if not, offer to establish a minimal system first.
|
||||
2. **Copy review touches tone** — When reviewing copy, cross-check against voice attributes and tone matrix, not just grammar.
|
||||
3. **New channel launch** — When a new marketing channel (TikTok, newsletter, podcast) is being set up, offer to apply the brand guidelines to that channel's specific format requirements.
|
||||
4. **Design feedback session** — When a user shares a design for feedback, run through the quick audit checklist before giving subjective opinions.
|
||||
5. **Partner or co-branded material** — Any co-branding situation should immediately trigger a review of logo clear space, sizing ratios, and color dominance rules.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Artifact | Format | Description |
|
||||
|----------|--------|-------------|
|
||||
| Brand Audit Report | Markdown doc | Asset-by-asset compliance check against all brand dimensions |
|
||||
| Color System Reference | Table | Full palette with hex, RGB, CMYK, Pantone, and usage rules |
|
||||
| Tone Matrix | Table | Voice attributes × context combinations with example phrases |
|
||||
| Typography Scale | Table | All type roles with font, size, weight, and line-height specifications |
|
||||
| Brand Guidelines Mini-Doc | Markdown doc | Condensed brand guide covering all 7 dimensions, ready to share with contractors |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
Brand consistency is not a design preference — it's a trust signal. Every deviation from guidelines erodes recognition. When auditing or creating brand materials, be specific: name the exact color code, font weight, and pixel measurement rather than giving subjective feedback. Reference `marketing-context` to ensure brand voice recommendations align with the ICP and product positioning. Quality bar: brand outputs should be specific enough that a contractor who has never worked with the brand could produce on-brand work from the artifact alone.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **marketing-context** — USE as the brand foundation layer; brand voice and visual decisions must align with ICP, positioning, and messaging; always load first.
|
||||
- **copywriting** — USE when brand voice guidelines need to be applied to specific page or campaign copy; NOT as a substitute for defining voice attributes.
|
||||
- **content-humanizer** — USE when existing content needs to be rewritten to match brand tone without losing information; NOT for structural content work.
|
||||
- **social-content** — USE when applying brand guidelines to social-specific formats and platform constraints; NOT for cross-channel brand system design.
|
||||
- **canvas-design** — USE when brand guidelines need to be applied to visual design artifacts (posters, PDFs, graphics); NOT for copy-only brand work.
|
||||
@@ -214,3 +214,32 @@ Calculates comprehensive ROI metrics with industry benchmarking:
|
||||
- **Single-currency** -- All monetary values assumed to be in the same currency. No currency conversion support.
|
||||
- **Simplified time-decay** -- Uses exponential decay based on configurable half-life. Does not account for weekday/weekend or seasonal patterns.
|
||||
- **No cross-device tracking** -- Attribution operates on provided journey data as-is. Cross-device identity resolution must be handled upstream.
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
- **Attribution model not set** → Last-click attribution misses 60%+ of the journey. Use multi-touch.
|
||||
- **No baseline metrics documented** → Can't measure improvement without baselines.
|
||||
- **Data discrepancy between tools** → GA4 and ad platform numbers rarely match. Document the gap.
|
||||
- **Vanity metrics dominating reports** → Pageviews don't matter. Focus on conversion metrics.
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| "Campaign report" | Cross-channel performance report with attribution analysis |
|
||||
| "Channel comparison" | Channel-by-channel ROI with budget reallocation recommendations |
|
||||
| "What's working?" | Top 5 performers + bottom 5 drains with specific actions |
|
||||
|
||||
## Communication
|
||||
|
||||
All output passes quality verification:
|
||||
- Self-verify: source attribution, assumption audit, confidence scoring
|
||||
- Output format: Bottom Line → What (with confidence) → Why → How to Act
|
||||
- Results only. Every finding tagged: 🟢 verified, 🟡 medium, 🔴 assumed.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **analytics-tracking**: For setting up tracking. NOT for analyzing data (that's this skill).
|
||||
- **ab-test-setup**: For designing experiments to test what analytics reveals.
|
||||
- **marketing-ops**: For routing insights to the right execution skill.
|
||||
- **paid-ads**: For optimizing ad spend based on analytics findings.
|
||||
|
||||
240
marketing-skill/churn-prevention/SKILL.md
Normal file
240
marketing-skill/churn-prevention/SKILL.md
Normal file
@@ -0,0 +1,240 @@
|
||||
---
|
||||
name: churn-prevention
|
||||
description: "Reduce voluntary and involuntary churn through cancel flow design, save offers, exit surveys, and dunning sequences. Use when designing or optimizing a cancel flow, building save offers, setting up dunning emails, or reducing failed-payment churn. Trigger keywords: cancel flow, churn reduction, save offers, dunning, exit survey, payment recovery, win-back, involuntary churn, failed payments, cancel page. NOT for customer health scoring or expansion revenue — use customer-success-manager for that."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Churn Prevention
|
||||
|
||||
You are an expert in SaaS retention and churn prevention. Your goal is to reduce both voluntary churn (customers who decide to leave) and involuntary churn (customers who leave because their payment failed) through smart flow design, targeted save offers, and systematic payment recovery.
|
||||
|
||||
Churn is a revenue leak you can plug. A 20% save rate on voluntary churners and a 30% recovery rate on involuntary churners can recover 5-8% of lost MRR monthly. That compounds.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions. Use that context and only ask for what's missing.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Current State
|
||||
- Do you have a cancel flow today, or is cancellation instant/via support?
|
||||
- What's your current monthly churn rate? (voluntary vs. involuntary split if known)
|
||||
- What payment processor are you on? (Stripe, Braintree, Paddle, etc.)
|
||||
- Do you collect exit reasons today?
|
||||
|
||||
### 2. Business Context
|
||||
- SaaS model: self-serve or sales-assisted?
|
||||
- Price points and plan structure
|
||||
- Average contract length and billing cycle (monthly/annual)
|
||||
- Current MRR
|
||||
|
||||
### 3. Goals
|
||||
- Which problem is primary: too many cancellations, or failed payment churn?
|
||||
- Do you have a save offer budget (discounts, extensions)?
|
||||
- Any constraints on cancel flow friction? (some platforms penalize dark patterns)
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Build Cancel Flow
|
||||
Starting from scratch — no cancel flow exists, or cancellation is immediate. We'll design the full flow from trigger to post-cancel.
|
||||
|
||||
### Mode 2: Optimize Existing Flow
|
||||
You have a cancel flow but save rates are low or you're not capturing good exit data. We'll audit what's there, identify the gaps, and rebuild what's underperforming.
|
||||
|
||||
### Mode 3: Set Up Dunning
|
||||
Involuntary churn from failed payments is your priority. We'll build the retry logic, notification sequence, and recovery emails.
|
||||
|
||||
---
|
||||
|
||||
## Cancel Flow Design
|
||||
|
||||
A cancel flow is not a dark pattern — it's a structured conversation. The goal is to understand why they're leaving and offer something genuinely useful. If they still want to cancel, let them.
|
||||
|
||||
### The 5-Stage Flow
|
||||
|
||||
```
|
||||
[Cancel Trigger] → [Exit Survey] → [Dynamic Save Offer] → [Confirmation] → [Post-Cancel]
|
||||
```
|
||||
|
||||
**Stage 1 — Cancel Trigger**
|
||||
- Show cancel option clearly (no hiding it — dark patterns burn trust)
|
||||
- At the moment they click cancel, begin the flow — don't take them to a dead-end form
|
||||
- Mobile: make this work on touch
|
||||
|
||||
**Stage 2 — Exit Survey (1 question, required)**
|
||||
- Ask ONE question: "What's the main reason you're cancelling?"
|
||||
- Keep it multiple choice (6-8 reasons max) — open text is optional, not required
|
||||
- This answer drives the save offer — it must be collected before showing the offer
|
||||
|
||||
**Stage 3 — Dynamic Save Offer**
|
||||
- Match the offer to the reason (see Exit Survey → Save Offer Mapping below)
|
||||
- Don't show a generic discount — it signals your pricing was fake
|
||||
- One offer per attempt. If they decline, let them cancel.
|
||||
|
||||
**Stage 4 — Confirmation**
|
||||
- Clear summary of what happens when they cancel (access, data, billing)
|
||||
- Explicit confirmation button — "Yes, cancel my account"
|
||||
- No pre-checked boxes, no confusing language
|
||||
|
||||
**Stage 5 — Post-Cancel**
|
||||
- Immediate confirmation email with: cancellation date, data retention policy, reactivation link
|
||||
- 7-day re-engagement email: single CTA, no pressure, reactivation link
|
||||
- 30-day win-back if warranted (product update or relevant offer)
|
||||
|
||||
---
|
||||
|
||||
## Exit Survey Design
|
||||
|
||||
The survey is your most valuable data source. Design it to generate usable intelligence, not just categories.
|
||||
|
||||
### Recommended Reason Categories
|
||||
|
||||
| Reason | Save Offer | Signal |
|
||||
|--------|-----------|--------|
|
||||
| Too expensive / price | Discount or downgrade | Price sensitivity |
|
||||
| Not using it enough | Usage tips + pause option | Adoption failure |
|
||||
| Missing a feature | Roadmap share + workaround | Product gap |
|
||||
| Switching to competitor | Competitive comparison | Market position |
|
||||
| Project ended / seasonal | Pause option | Temporary need |
|
||||
| Too complicated | Onboarding help + human support | UX friction |
|
||||
| Just testing / never needed | No offer — let go | Wrong fit |
|
||||
|
||||
**Implementation rule:** Each reason must map to exactly one save offer type. Ambiguous mapping = generic offer = low save rate.
|
||||
|
||||
---
|
||||
|
||||
## Save Offer Playbook
|
||||
|
||||
Match the offer to the reason. Each offer type has a right and wrong time to use it.
|
||||
|
||||
| Offer Type | When to Use | When NOT to Use |
|
||||
|-----------|------------|-----------------|
|
||||
| **Discount** (1-3 months) | Price objection | Adoption or feature issues |
|
||||
| **Pause** (1-3 months) | Seasonal, project ended, not using | Price objection |
|
||||
| **Downgrade** | Too expensive, light usage | Feature objection |
|
||||
| **Extended trial** | Hasn't explored full value | Power user churning |
|
||||
| **Feature unlock** | Missing feature that exists on higher plan | Wrong plan fit |
|
||||
| **Human support** | Complicated, stuck, frustrated | Price objection (don't waste CS time) |
|
||||
|
||||
**Offer presentation rules:**
|
||||
- One clear headline: "Before you go — [offer]"
|
||||
- Quantify the value: "Save $X" not "Get a discount"
|
||||
- No countdown timers unless it's genuinely expiring
|
||||
- Clear CTA: "Claim this offer" vs. "Continue cancelling"
|
||||
|
||||
See [references/cancel-flow-playbook.md](references/cancel-flow-playbook.md) for full decision trees and flow templates.
|
||||
|
||||
---
|
||||
|
||||
## Involuntary Churn: Dunning Setup
|
||||
|
||||
Failed payments cause 20-40% of total churn at most SaaS companies. Most of it is recoverable.
|
||||
|
||||
### Recovery Stack
|
||||
|
||||
**1. Smart Retry Logic**
|
||||
Don't retry immediately — failed cards often recover within 3-7 days:
|
||||
- Retry 1: 3 days after failure (most recoveries happen here)
|
||||
- Retry 2: 5 days after retry 1
|
||||
- Retry 3: 7 days after retry 2
|
||||
- Final: 3 days after retry 3, then cancel
|
||||
|
||||
**2. Card Updater Services**
|
||||
- Stripe: Account Updater (automatic, enabled by default in most plans)
|
||||
- Braintree: Account Updater (must enable)
|
||||
- These update expired/replaced cards before the next charge — use them
|
||||
|
||||
**3. Dunning Email Sequence**
|
||||
|
||||
| Day | Email | Tone | CTA |
|
||||
|----|-------|------|-----|
|
||||
| Day 0 | "Payment failed" | Neutral, factual | Update card |
|
||||
| Day 3 | "Action needed" | Mild urgency | Update card |
|
||||
| Day 7 | "Account at risk" | Higher urgency | Update card |
|
||||
| Day 12 | "Final notice" | Urgent | Update card + support link |
|
||||
| Day 15 | "Account paused/cancelled" | Matter-of-fact | Reactivate |
|
||||
|
||||
**Email rules:**
|
||||
- Subject lines: specific over vague ("Your [Product] payment failed" not "Action required")
|
||||
- No guilt. No shame. Card failures happen — treat customers like adults.
|
||||
- Every email links directly to the payment update page — not the dashboard
|
||||
|
||||
See [references/dunning-guide.md](references/dunning-guide.md) for full email sequences and retry configuration examples.
|
||||
|
||||
---
|
||||
|
||||
## Metrics & Benchmarks
|
||||
|
||||
Track these weekly, review monthly:
|
||||
|
||||
| Metric | Formula | Benchmark |
|
||||
|--------|---------|-----------|
|
||||
| **Save rate** | Customers saved / cancel attempts | 10-15% good, 20%+ excellent |
|
||||
| **Voluntary churn rate** | Voluntary cancels / total customers | <2% monthly |
|
||||
| **Involuntary churn rate** | Failed payment cancels / total customers | <1% monthly |
|
||||
| **Recovery rate** | Failed payments recovered / total failed | 25-35% good |
|
||||
| **Win-back rate** | Reactivations / post-cancel 90 days | 5-10% |
|
||||
| **Exit survey completion** | Surveys completed / cancel attempts | >80% |
|
||||
|
||||
**Red flags:**
|
||||
- Save rate <5% → offers aren't matching reasons
|
||||
- Exit survey completion <70% → survey is too long or optional
|
||||
- Recovery rate <20% → retry logic or emails need work
|
||||
|
||||
Use the churn impact calculator to model what improving each metric is worth:
|
||||
|
||||
```bash
|
||||
python3 scripts/churn_impact_calculator.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **Instant cancellation flow** → Revenue is leaking immediately. Any friction saves money — flag for priority fix.
|
||||
- **Single generic save offer** → A discount shown to everyone depresses average revenue and trains customers to wait for deals. Map offers to exit reasons.
|
||||
- **No dunning sequence** → If payment fails and nothing happens, that's 20-40% of churn going unaddressed. Flag immediately.
|
||||
- **Exit survey is optional** → <70% completion = bad data. Make it required (one question, fast).
|
||||
- **No post-cancel reactivation email** → The 7-day window is the highest win-back moment. Missing it leaves money on the table.
|
||||
- **Churn rate >5% monthly** → At this rate, the company is likely contracting. Churn prevention alone won't fix it — flag for product/ICP review alongside retention work.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|--------------------|-----------|
|
||||
| "Design a cancel flow" | 5-stage flow diagram (text) with copy for each stage, save offer map, and confirmation email template |
|
||||
| "Audit my cancel flow" | Scorecard (0-100) with gaps, save rate benchmarks, and prioritized fixes |
|
||||
| "Set up dunning" | Retry schedule, 5-email sequence with subject lines and body copy, card updater setup checklist |
|
||||
| "Design an exit survey" | 6-8 reason categories with save offer mapping table |
|
||||
| "Model churn impact" | Run churn_impact_calculator.py with your inputs — monthly MRR saved and annual impact |
|
||||
| "Write win-back emails" | 2-email win-back sequence (7-day and 30-day) with subject lines |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — save rate estimate or recovery potential before methodology
|
||||
- **What + Why + How** — every recommendation has all three
|
||||
- **Actions have owners and deadlines** — no vague suggestions
|
||||
- **Confidence tagging** — 🟢 verified benchmark / 🟡 estimated / 🔴 assumed
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **customer-success-manager**: Use for health scoring, QBRs, and expansion revenue. NOT for cancel flow or dunning.
|
||||
- **email-sequence**: Use for lifecycle nurture and onboarding emails. NOT for dunning (use this skill for dunning).
|
||||
- **pricing-strategy**: Use when churn root cause is pricing or packaging mismatch. NOT for save offer design (use this skill).
|
||||
- **campaign-analytics**: Use for analyzing which acquisition channels produce high-churn customers. NOT for setting up retention tracking.
|
||||
- **signup-flow-cro**: Use for reducing drop-off at signup. NOT for post-signup retention.
|
||||
@@ -0,0 +1,254 @@
|
||||
# Cancel Flow Playbook
|
||||
|
||||
Complete reference for designing, building, and auditing cancel flows.
|
||||
|
||||
---
|
||||
|
||||
## The Cancel Flow Decision Tree
|
||||
|
||||
```
|
||||
Customer clicks "Cancel" or "Cancel Subscription"
|
||||
│
|
||||
▼
|
||||
[Show Exit Survey]
|
||||
"What's the main reason you're cancelling?"
|
||||
│
|
||||
┌────┴─────────────────────────────────────────┐
|
||||
│ │
|
||||
Price/Value Other Reasons
|
||||
│ │
|
||||
▼ ▼
|
||||
Discount offer Match to reason category
|
||||
(1-3 month, 20-30%) (see mapping table)
|
||||
│ │
|
||||
▼ ▼
|
||||
[Accept?]──Yes──► Charge updated [Accept?]──Yes──► Apply offer
|
||||
│ │
|
||||
No No
|
||||
│ │
|
||||
▼ ▼
|
||||
[Confirm Cancel] [Confirm Cancel]
|
||||
│ │
|
||||
▼ ▼
|
||||
[Post-cancel page + email] [Post-cancel page + email]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage-by-Stage Templates
|
||||
|
||||
### Stage 1: Pre-Cancel Intercept
|
||||
|
||||
**When triggered:** User lands on cancel/subscription page, clicks "Cancel plan", or navigates to billing settings.
|
||||
|
||||
**What to show:** Brief value reminder (not a wall of guilt) + "Tell us why" framing.
|
||||
|
||||
**Copy template:**
|
||||
```
|
||||
Headline: Before you go, we want to understand
|
||||
Body: Your feedback helps us improve. Take 30 seconds to tell us why
|
||||
you're cancelling — and we might have a solution you haven't tried.
|
||||
CTA: Continue to cancellation →
|
||||
```
|
||||
|
||||
**Rules:**
|
||||
- Don't block the cancel path
|
||||
- Don't show this more than once per session
|
||||
- Mobile: single screen, no scrolling required
|
||||
|
||||
---
|
||||
|
||||
### Stage 2: Exit Survey
|
||||
|
||||
**Design specs:**
|
||||
- Single question, required
|
||||
- Radio buttons (not checkboxes)
|
||||
- 6-8 options maximum
|
||||
- Optional open text at bottom: "Anything else we should know?"
|
||||
- Submit advances to Stage 3 — don't show offer yet
|
||||
|
||||
**Copy template:**
|
||||
```
|
||||
What's the main reason you're cancelling?
|
||||
|
||||
○ It's too expensive for what I get
|
||||
○ I'm not using it enough to justify the cost
|
||||
○ It's missing a feature I need
|
||||
○ I'm switching to a different tool
|
||||
○ My project or need ended
|
||||
○ It's too complicated or hard to use
|
||||
○ I was just testing it out
|
||||
○ Other: [text field]
|
||||
|
||||
[Continue →]
|
||||
```
|
||||
|
||||
**Data capture:** Store the reason against the customer record. This is your product feedback goldmine.
|
||||
|
||||
---
|
||||
|
||||
### Stage 3: Dynamic Save Offer
|
||||
|
||||
**Offer-to-reason mapping (full):**
|
||||
|
||||
| Selected Reason | Primary Offer | Secondary (if declined) | Skip Offer |
|
||||
|----------------|--------------|------------------------|------------|
|
||||
| Too expensive | 30% off for 3 months | Downgrade plan | — |
|
||||
| Not using it enough | 1-month pause | Usage coaching call | — |
|
||||
| Missing a feature | Feature roadmap share + workaround | Human support call | If feature genuinely doesn't exist and won't exist soon |
|
||||
| Switching to competitor | Competitive comparison one-pager | — | If they've clearly made the decision |
|
||||
| Project ended | 2-month pause | — | — |
|
||||
| Too complicated | Free onboarding session | 1:1 support call | — |
|
||||
| Just testing | — | — | Always skip — wrong fit, let them go |
|
||||
| Other | Human support call | — | — |
|
||||
|
||||
**Offer presentation template:**
|
||||
|
||||
```
|
||||
[For price objection:]
|
||||
Headline: Keep [Product] for less
|
||||
Body: We'd hate to see you go over price. Here's what we can do:
|
||||
Get 30% off your next 3 months — that's [calculated dollar amount] saved.
|
||||
After 3 months, your plan returns to [original price].
|
||||
CTA (accept): Claim my discount →
|
||||
CTA (decline): No thanks, continue cancelling →
|
||||
|
||||
[For not using it enough:]
|
||||
Headline: No charge for 60 days — pause your account
|
||||
Body: Life gets busy. Put [Product] on hold for up to 60 days.
|
||||
Your data stays intact, and you can resume any time. No charge during pause.
|
||||
CTA (accept): Pause my account →
|
||||
CTA (decline): No thanks, continue cancelling →
|
||||
```
|
||||
|
||||
**Offer rules:**
|
||||
- One offer per cancel attempt — never show multiple
|
||||
- If they decline, go straight to Stage 4
|
||||
- Don't re-show the same offer if they return to cancel within 30 days
|
||||
- Track which offer was shown and whether it was accepted
|
||||
|
||||
---
|
||||
|
||||
### Stage 4: Cancellation Confirmation
|
||||
|
||||
**What to include:**
|
||||
- Explicit confirmation of what will happen
|
||||
- Access end date (specific date, not "end of billing period")
|
||||
- Data retention policy (how long data is kept)
|
||||
- Support contact in case they change their mind
|
||||
- Confirmation button with clear copy
|
||||
|
||||
**Copy template:**
|
||||
```
|
||||
Your subscription will be cancelled.
|
||||
|
||||
Here's what happens next:
|
||||
• Access continues until [specific date]
|
||||
• Your data is retained for 90 days after cancellation
|
||||
• After 90 days, your account data is deleted
|
||||
• You can reactivate any time before [90-day date]
|
||||
|
||||
If you change your mind, contact [email] or reactivate at [reactivation URL].
|
||||
|
||||
[Confirm Cancellation] [Go back]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Stage 5: Post-Cancel Sequence
|
||||
|
||||
**Immediate: Cancellation Confirmation Email**
|
||||
|
||||
```
|
||||
Subject: Your [Product] subscription has been cancelled
|
||||
|
||||
Hi [Name],
|
||||
|
||||
Your [Product] subscription has been cancelled as requested.
|
||||
|
||||
What happens next:
|
||||
- Access continues until [date]
|
||||
- Your data is saved for 90 days (until [date])
|
||||
- To reactivate, visit: [reactivation link]
|
||||
|
||||
If this was a mistake or you have questions, reply to this email or visit [support link].
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Day 7: Re-engagement Email**
|
||||
|
||||
```
|
||||
Subject: Your [Product] account is still here
|
||||
|
||||
Hi [Name],
|
||||
|
||||
It's been a week since you cancelled. Your account and data are still intact
|
||||
until [date].
|
||||
|
||||
If anything changed, you can reactivate in one click — no re-setup required.
|
||||
|
||||
[Reactivate my account →]
|
||||
|
||||
No pressure — just wanted to make sure you knew the door's open.
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Day 30: Win-Back Email (send only if triggered by product update or relevant offer)**
|
||||
|
||||
```
|
||||
Subject: [Product] update: [specific feature they mentioned or relevant improvement]
|
||||
|
||||
Hi [Name],
|
||||
|
||||
Since you left, we shipped [specific update relevant to their cancel reason].
|
||||
[2-3 sentence description of what changed.]
|
||||
|
||||
If [their specific problem] was why you left, it might be worth another look.
|
||||
|
||||
[See what's new →] or [Reactivate →]
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cancel Flow Audit Scorecard
|
||||
|
||||
Rate your existing flow on each dimension (0-10):
|
||||
|
||||
| Dimension | 0 pts | 5 pts | 10 pts |
|
||||
|-----------|-------|-------|--------|
|
||||
| **Accessibility** | Cancel requires support ticket | Cancel in settings, but buried | Cancel clearly visible in billing settings |
|
||||
| **Exit survey** | None | Optional, multi-question | Required, single question, maps to offers |
|
||||
| **Save offers** | None or generic discount | Offers exist but not mapped | Offers matched to exit reasons |
|
||||
| **Confirmation clarity** | Confusing terms | Mentions access end date | Clear date, data policy, reactivation path |
|
||||
| **Post-cancel sequence** | Nothing | One generic email | Immediate confirmation + 7-day re-engagement |
|
||||
| **Dunning** | None | Basic retry only | Retry + email sequence + card updater |
|
||||
| **Analytics** | No tracking | Basic cancellation count | Reason tracking, save rate, recovery rate |
|
||||
|
||||
**Score interpretation:**
|
||||
- 60-70: Solid foundation. Fix the 0-5 rated dimensions.
|
||||
- 40-59: Material revenue leaking. Prioritize survey + offer mapping.
|
||||
- <40: Major opportunity. Build from scratch using this playbook.
|
||||
|
||||
---
|
||||
|
||||
## Platform Implementation Notes
|
||||
|
||||
### Stripe
|
||||
- Use Customer Portal for cancel flow (customizable via Stripe Dashboard)
|
||||
- Enable Stripe Billing webhooks: `customer.subscription.deleted`, `invoice.payment_failed`
|
||||
- Stripe Radar helps filter bot-initiated failures from real card failures
|
||||
- Account Updater: enabled by default on most plans — verify in Dashboard > Settings
|
||||
|
||||
### Chargebee / Recurly
|
||||
- Both have native cancel flow builders with reason collection
|
||||
- Dunning sequences configurable in-product
|
||||
- Connect to your email provider (Intercom, Customer.io, etc.) via webhook
|
||||
|
||||
### Custom / Homegrown Billing
|
||||
- Build cancel flow as a separate route (not inline in settings)
|
||||
- Store `cancel_reason`, `save_offer_shown`, `save_offer_accepted` per customer
|
||||
- Retry logic: implement as a background job with delay queue
|
||||
276
marketing-skill/churn-prevention/references/dunning-guide.md
Normal file
276
marketing-skill/churn-prevention/references/dunning-guide.md
Normal file
@@ -0,0 +1,276 @@
|
||||
# Dunning Guide
|
||||
|
||||
Payment recovery strategies, retry logic, and email sequences for involuntary churn.
|
||||
|
||||
---
|
||||
|
||||
## Why Involuntary Churn Matters
|
||||
|
||||
At most SaaS companies, 20-40% of all churn comes from failed payments — not customer decisions. The customer didn't choose to leave. Their card expired, got replaced, hit a limit, or was flagged by their bank. Most of these situations are recoverable within 7-14 days.
|
||||
|
||||
**The math:**
|
||||
- 1,000 active customers
|
||||
- 3% monthly churn rate = 30 churned per month
|
||||
- If 30% of that is involuntary = 9 customers/month from failed payments
|
||||
- Recovery rate of 40% = 3.6 customers saved/month
|
||||
- At $100 MRR: $360/month recovered, $4,320/year — from just fixing dunning
|
||||
|
||||
That's before touching voluntary churn.
|
||||
|
||||
---
|
||||
|
||||
## Failure Mode Taxonomy
|
||||
|
||||
Not all payment failures are equal. Categorize before deciding how to retry:
|
||||
|
||||
| Failure Type | Decline Code | Recovery Approach |
|
||||
|-------------|-------------|-------------------|
|
||||
| **Insufficient funds** | `insufficient_funds` | Retry in 3-5 days (balance usually replenishes) |
|
||||
| **Card expired** | `expired_card` | Card updater first; email to update card |
|
||||
| **Card replaced** | `card_not_supported`, network updated | Card updater handles this automatically |
|
||||
| **Do not honor** | `do_not_honor` | Retry once in 3 days; email to contact bank |
|
||||
| **Fraud flagged** | `fraudulent` | Email immediately; don't retry — let customer resolve |
|
||||
| **Card lost/stolen** | `lost_card`, `stolen_card` | Email immediately; do not retry |
|
||||
| **Generic decline** | `generic_decline` | Retry 2x over 7 days; then email |
|
||||
|
||||
**Rule:** Never retry fraudulent, lost, or stolen card declines. It increases chargeback risk.
|
||||
|
||||
---
|
||||
|
||||
## Retry Schedule
|
||||
|
||||
Optimal timing based on card network research:
|
||||
|
||||
```
|
||||
Day 0: Payment fails (initial charge)
|
||||
Day 3: Retry 1 — highest recovery rate (3-7 days is the sweet spot)
|
||||
Day 8: Retry 2 — catches monthly paycycle refills
|
||||
Day 13: Retry 3 — final automated attempt
|
||||
Day 16: Cancel subscription (if not recovered)
|
||||
```
|
||||
|
||||
**Stripe-specific configuration:**
|
||||
|
||||
In Stripe Billing settings (Dashboard > Billing > Subscriptions and emails):
|
||||
```
|
||||
Smart Retries: Enable (Stripe uses ML to pick retry timing)
|
||||
OR
|
||||
Manual schedule: 3 days, 5 days, 7 days
|
||||
Subscription behavior after all retries: Cancel subscription
|
||||
```
|
||||
|
||||
**Alternative for maximum recovery:**
|
||||
If using Smart Retries (Stripe), disable manual schedule — they conflict.
|
||||
Smart Retries uses real-time card network data and typically outperforms fixed schedules.
|
||||
|
||||
---
|
||||
|
||||
## Card Updater Services
|
||||
|
||||
These services update card details automatically when banks issue new cards:
|
||||
|
||||
| Provider | Service Name | Config Required |
|
||||
|---------|-------------|-----------------|
|
||||
| Stripe | Account Updater | Enabled by default. Verify in Dashboard > Settings > Card account updater |
|
||||
| Braintree | Account Updater | Must enable in Control Panel > Processing > Account Updater |
|
||||
| Recurly | Account Updater | Available on Professional and above |
|
||||
| Chargebee | Smart Dunning | Bundled with Chargebee; enable in configuration |
|
||||
|
||||
**Expected impact:** 15-25% of involuntary churn prevented before dunning emails are needed.
|
||||
|
||||
---
|
||||
|
||||
## Dunning Email Sequence
|
||||
|
||||
Five emails. Each one escalates slightly in urgency. No guilt, no shame — these are operational communications.
|
||||
|
||||
---
|
||||
|
||||
### Email 1 — Day 0: "Payment failed"
|
||||
|
||||
**Goal:** Inform, make it easy to fix.
|
||||
|
||||
```
|
||||
Subject: Your [Product] payment didn't go through
|
||||
|
||||
Hi [Name],
|
||||
|
||||
We weren't able to process your [Product] subscription payment of [amount].
|
||||
|
||||
This happens sometimes — an expired card, a temporary issue with your bank,
|
||||
or a card limit. Easy to fix.
|
||||
|
||||
Update your payment details here:
|
||||
[Update payment method →]
|
||||
|
||||
If you need help, reply to this email.
|
||||
|
||||
[Product] Team
|
||||
|
||||
---
|
||||
Payment amount: [amount]
|
||||
Billing date: [date]
|
||||
Next retry: [date + 3 days]
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Send within 1 hour of failure
|
||||
- Include specific amount and date — vague emails get ignored
|
||||
- Mention the next retry date — some customers will wait for the retry to see if it clears
|
||||
|
||||
---
|
||||
|
||||
### Email 2 — Day 3: "Retry coming up"
|
||||
|
||||
**Goal:** Catch people before the retry so they can update the card first.
|
||||
|
||||
```
|
||||
Subject: [Product] — we'll try your payment again tomorrow
|
||||
|
||||
Hi [Name],
|
||||
|
||||
We're going to attempt your [Product] payment of [amount] again tomorrow
|
||||
([specific date]).
|
||||
|
||||
If your card details have changed, update them now so the retry goes through:
|
||||
[Update payment method →]
|
||||
|
||||
If the retry fails, we'll reach out again.
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Send day before the retry, not day of
|
||||
- Short email — one job, one CTA
|
||||
- Some payment processors let you trigger a manual retry immediately after card update — mention this if yours does
|
||||
|
||||
---
|
||||
|
||||
### Email 3 — Day 7: "We tried again — still failing"
|
||||
|
||||
**Goal:** Add urgency, soften tone, offer help.
|
||||
|
||||
```
|
||||
Subject: [Product] payment still failing — action needed
|
||||
|
||||
Hi [Name],
|
||||
|
||||
We've attempted to process your [Product] subscription twice now,
|
||||
and the payment hasn't gone through.
|
||||
|
||||
Your account is still active, but we'll need to resolve this soon to
|
||||
avoid any interruption.
|
||||
|
||||
A few common fixes:
|
||||
• Check if your card has expired and update it
|
||||
• Contact your bank if the card is being declined unexpectedly
|
||||
• Use a different card if this one is no longer working
|
||||
|
||||
Update payment details:
|
||||
[Update payment method →]
|
||||
|
||||
Still having trouble? Reply to this email and we'll help you sort it out.
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Shift from notification to problem-solving
|
||||
- List common causes — helps customers self-diagnose
|
||||
- Offer human help — some people have legitimate confusion
|
||||
|
||||
---
|
||||
|
||||
### Email 4 — Day 12: "Final notice"
|
||||
|
||||
**Goal:** Create urgency without being threatening. Be clear about what happens.
|
||||
|
||||
```
|
||||
Subject: [Product] account at risk — payment needed by [specific date]
|
||||
|
||||
Hi [Name],
|
||||
|
||||
We've made multiple attempts to process your [Product] subscription,
|
||||
and we haven't been able to reach your card.
|
||||
|
||||
Your account will be cancelled on [specific date] if we don't receive payment.
|
||||
|
||||
Here's what you'll lose access to:
|
||||
• [Key feature / data point]
|
||||
• [Key feature / data point]
|
||||
• Your [X] months of [data/history/usage]
|
||||
|
||||
This is our last reminder before cancellation.
|
||||
|
||||
Update payment now:
|
||||
[Update payment method →]
|
||||
|
||||
Need to talk to someone? [Book a call] or reply here.
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- Use a specific date — "soon" doesn't create urgency, "March 15" does
|
||||
- List what they lose — tangible is more motivating than abstract
|
||||
- Offer human escalation — some churn at this stage is recoverable by a support person
|
||||
|
||||
---
|
||||
|
||||
### Email 5 — Day 16: "Account cancelled"
|
||||
|
||||
**Goal:** Inform, leave the door open, make reactivation easy.
|
||||
|
||||
```
|
||||
Subject: Your [Product] account has been cancelled
|
||||
|
||||
Hi [Name],
|
||||
|
||||
We've cancelled your [Product] subscription as of today. Your card could
|
||||
not be charged for [amount] after multiple attempts.
|
||||
|
||||
Your data is saved for 90 days (until [date]).
|
||||
|
||||
To reactivate:
|
||||
[Reactivate my account →]
|
||||
|
||||
You'll be able to pick up where you left off — all your data will be intact.
|
||||
|
||||
If you think this was an error, reply to this email and we'll sort it out.
|
||||
|
||||
[Product] Team
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- No blame, no guilt — this is a notification, not a scolding
|
||||
- Make reactivation frictionless — one click, not a new signup flow
|
||||
- Data retention timeline gives them a reason to act within 90 days
|
||||
|
||||
---
|
||||
|
||||
## Dunning Metrics to Track
|
||||
|
||||
| Metric | What it measures | Target |
|
||||
|--------|-----------------|--------|
|
||||
| **Recovery rate** | Failed payments recovered / total failed | 25-40% |
|
||||
| **Recovery by email** | Which email in the sequence converts most | Track per email |
|
||||
| **Recovery by retry** | Which retry attempt succeeds most | Usually retry 1 (day 3) |
|
||||
| **Time to recovery** | Days from first failure to payment | <10 days is good |
|
||||
| **Card updater hit rate** | Cards auto-updated before manual outreach | 15-25% of failures |
|
||||
|
||||
---
|
||||
|
||||
## Third-Party Dunning Tools
|
||||
|
||||
For teams who want plug-and-play dunning without building it:
|
||||
|
||||
| Tool | Best For | Pricing Model |
|
||||
|------|---------|--------------|
|
||||
| **Churnkey** | Stripe users, full cancel flow + dunning | Revenue share |
|
||||
| **ProfitWell Retain** | Stripe + Braintree, analytics-heavy | % of recovered revenue |
|
||||
| **Stunning** | Stripe-native, email-focused | Flat monthly |
|
||||
| **Recurly** | Already on Recurly | Built-in |
|
||||
| **Chargebee Smart Dunning** | Already on Chargebee | Built-in |
|
||||
|
||||
**When to use a third-party tool:** If you're <$500k MRR and don't have engineering bandwidth to build retry logic + email sequences, a tool pays for itself quickly. Above that threshold, build it in-house for more control.
|
||||
@@ -0,0 +1,185 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Churn impact calculator — models revenue impact of churn reduction improvements."""
|
||||
|
||||
import json
|
||||
import sys
|
||||
|
||||
|
||||
SAMPLE_INPUT = {
|
||||
"mrr": 50000,
|
||||
"monthly_churn_rate_pct": 4.5,
|
||||
"voluntary_churn_pct": 65,
|
||||
"current_save_rate_pct": 8,
|
||||
"target_save_rate_pct": 20,
|
||||
"current_recovery_rate_pct": 15,
|
||||
"target_recovery_rate_pct": 35,
|
||||
"avg_customer_mrr": 150
|
||||
}
|
||||
|
||||
|
||||
def calculate(inputs):
|
||||
mrr = inputs["mrr"]
|
||||
churn_rate = inputs["monthly_churn_rate_pct"] / 100
|
||||
voluntary_pct = inputs["voluntary_churn_pct"] / 100
|
||||
involuntary_pct = 1 - voluntary_pct
|
||||
current_save = inputs["current_save_rate_pct"] / 100
|
||||
target_save = inputs["target_save_rate_pct"] / 100
|
||||
current_recovery = inputs["current_recovery_rate_pct"] / 100
|
||||
target_recovery = inputs["target_recovery_rate_pct"] / 100
|
||||
avg_customer_mrr = inputs["avg_customer_mrr"]
|
||||
|
||||
# Total MRR churned per month
|
||||
total_churned_mrr = mrr * churn_rate
|
||||
voluntary_churned_mrr = total_churned_mrr * voluntary_pct
|
||||
involuntary_churned_mrr = total_churned_mrr * involuntary_pct
|
||||
|
||||
# Current saves/recoveries
|
||||
current_saves_mrr = voluntary_churned_mrr * current_save
|
||||
current_recoveries_mrr = involuntary_churned_mrr * current_recovery
|
||||
current_total_saved = current_saves_mrr + current_recoveries_mrr
|
||||
|
||||
# Target saves/recoveries
|
||||
target_saves_mrr = voluntary_churned_mrr * target_save
|
||||
target_recoveries_mrr = involuntary_churned_mrr * target_recovery
|
||||
target_total_saved = target_saves_mrr + target_recoveries_mrr
|
||||
|
||||
# Incremental gains
|
||||
incremental_monthly = target_total_saved - current_total_saved
|
||||
incremental_annual = incremental_monthly * 12
|
||||
|
||||
# Customer counts
|
||||
voluntary_churned_customers = voluntary_churned_mrr / avg_customer_mrr
|
||||
involuntary_churned_customers = involuntary_churned_mrr / avg_customer_mrr
|
||||
additional_saves = (target_save - current_save) * voluntary_churned_customers
|
||||
additional_recoveries = (target_recovery - current_recovery) * involuntary_churned_customers
|
||||
total_additional_customers = additional_saves + additional_recoveries
|
||||
|
||||
# LTV impact (assuming 24-month average tenure at current churn rate)
|
||||
implied_ltv_months = 1 / churn_rate
|
||||
ltv_per_customer = avg_customer_mrr * implied_ltv_months
|
||||
ltv_impact = total_additional_customers * ltv_per_customer
|
||||
|
||||
return {
|
||||
"baseline": {
|
||||
"mrr": mrr,
|
||||
"monthly_churn_rate_pct": inputs["monthly_churn_rate_pct"],
|
||||
"total_churned_mrr_monthly": round(total_churned_mrr, 0),
|
||||
"voluntary_churned_mrr": round(voluntary_churned_mrr, 0),
|
||||
"involuntary_churned_mrr": round(involuntary_churned_mrr, 0),
|
||||
},
|
||||
"current_performance": {
|
||||
"save_rate_pct": inputs["current_save_rate_pct"],
|
||||
"recovery_rate_pct": inputs["current_recovery_rate_pct"],
|
||||
"monthly_saved_mrr": round(current_total_saved, 0),
|
||||
"annual_saved_mrr": round(current_total_saved * 12, 0),
|
||||
},
|
||||
"target_performance": {
|
||||
"save_rate_pct": inputs["target_save_rate_pct"],
|
||||
"recovery_rate_pct": inputs["target_recovery_rate_pct"],
|
||||
"monthly_saved_mrr": round(target_total_saved, 0),
|
||||
"annual_saved_mrr": round(target_total_saved * 12, 0),
|
||||
},
|
||||
"improvement_impact": {
|
||||
"incremental_mrr_monthly": round(incremental_monthly, 0),
|
||||
"incremental_mrr_annual": round(incremental_annual, 0),
|
||||
"additional_customers_saved_monthly": round(total_additional_customers, 1),
|
||||
"implied_ltv_per_customer": round(ltv_per_customer, 0),
|
||||
"ltv_impact_of_saved_customers": round(ltv_impact, 0),
|
||||
},
|
||||
"priorities": _prioritize(
|
||||
voluntary_churned_mrr, involuntary_churned_mrr,
|
||||
current_save, target_save,
|
||||
current_recovery, target_recovery
|
||||
)
|
||||
}
|
||||
|
||||
|
||||
def _prioritize(vol_mrr, inv_mrr, cur_save, tgt_save, cur_rec, tgt_rec):
|
||||
save_opportunity = vol_mrr * (tgt_save - cur_save)
|
||||
rec_opportunity = inv_mrr * (tgt_rec - cur_rec)
|
||||
|
||||
if save_opportunity > rec_opportunity * 1.5:
|
||||
primary = "cancel-flow-and-save-offers"
|
||||
secondary = "dunning"
|
||||
elif rec_opportunity > save_opportunity * 1.5:
|
||||
primary = "dunning-and-payment-recovery"
|
||||
secondary = "cancel-flow"
|
||||
else:
|
||||
primary = "both-roughly-equal"
|
||||
secondary = "start-with-dunning-easier-to-implement"
|
||||
|
||||
return {
|
||||
"voluntary_save_opportunity_mrr": round(save_opportunity, 0),
|
||||
"involuntary_recovery_opportunity_mrr": round(rec_opportunity, 0),
|
||||
"recommendation": primary,
|
||||
"note": secondary
|
||||
}
|
||||
|
||||
|
||||
def print_report(result):
|
||||
b = result["baseline"]
|
||||
cur = result["current_performance"]
|
||||
tgt = result["target_performance"]
|
||||
imp = result["improvement_impact"]
|
||||
pri = result["priorities"]
|
||||
|
||||
print("\n" + "="*60)
|
||||
print(" CHURN IMPACT CALCULATOR")
|
||||
print("="*60)
|
||||
|
||||
print(f"\n📊 BASELINE")
|
||||
print(f" MRR: ${b['mrr']:,.0f}")
|
||||
print(f" Monthly churn rate: {b['monthly_churn_rate_pct']}%")
|
||||
print(f" Total MRR churned/mo: ${b['total_churned_mrr_monthly']:,.0f}")
|
||||
print(f" └─ Voluntary: ${b['voluntary_churned_mrr']:,.0f}")
|
||||
print(f" └─ Involuntary: ${b['involuntary_churned_mrr']:,.0f}")
|
||||
|
||||
print(f"\n📉 CURRENT PERFORMANCE")
|
||||
print(f" Save rate: {cur['save_rate_pct']}%")
|
||||
print(f" Payment recovery rate: {cur['recovery_rate_pct']}%")
|
||||
print(f" MRR saved monthly: ${cur['monthly_saved_mrr']:,.0f}")
|
||||
print(f" MRR saved annually: ${cur['annual_saved_mrr']:,.0f}")
|
||||
|
||||
print(f"\n🎯 TARGET PERFORMANCE")
|
||||
print(f" Save rate: {tgt['save_rate_pct']}%")
|
||||
print(f" Payment recovery rate: {tgt['recovery_rate_pct']}%")
|
||||
print(f" MRR saved monthly: ${tgt['monthly_saved_mrr']:,.0f}")
|
||||
print(f" MRR saved annually: ${tgt['annual_saved_mrr']:,.0f}")
|
||||
|
||||
print(f"\n💰 INCREMENTAL IMPACT")
|
||||
print(f" Additional MRR/month: ${imp['incremental_mrr_monthly']:,.0f}")
|
||||
print(f" Additional MRR/year: ${imp['incremental_mrr_annual']:,.0f}")
|
||||
print(f" Customers saved/month: {imp['additional_customers_saved_monthly']}")
|
||||
print(f" Implied LTV/customer: ${imp['implied_ltv_per_customer']:,.0f}")
|
||||
print(f" LTV impact: ${imp['ltv_impact_of_saved_customers']:,.0f}")
|
||||
|
||||
print(f"\n🔍 PRIORITY RECOMMENDATION")
|
||||
print(f" Voluntary opportunity: ${pri['voluntary_save_opportunity_mrr']:,.0f}/mo")
|
||||
print(f" Involuntary opportunity: ${pri['involuntary_recovery_opportunity_mrr']:,.0f}/mo")
|
||||
print(f" Focus on: {pri['recommendation'].replace('-', ' ').title()}")
|
||||
if pri['note']:
|
||||
print(f" Note: {pri['note'].replace('-', ' ')}")
|
||||
|
||||
print("\n" + "="*60 + "\n")
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) > 1:
|
||||
with open(sys.argv[1]) as f:
|
||||
inputs = json.load(f)
|
||||
else:
|
||||
print("No input file provided. Running with sample data...\n")
|
||||
print("Sample input:")
|
||||
print(json.dumps(SAMPLE_INPUT, indent=2))
|
||||
inputs = SAMPLE_INPUT
|
||||
|
||||
result = calculate(inputs)
|
||||
print_report(result)
|
||||
|
||||
# Also dump JSON for programmatic use
|
||||
if "--json" in sys.argv:
|
||||
print(json.dumps(result, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
272
marketing-skill/cold-email/SKILL.md
Normal file
272
marketing-skill/cold-email/SKILL.md
Normal file
@@ -0,0 +1,272 @@
|
||||
---
|
||||
name: cold-email
|
||||
description: "When the user wants to write, improve, or build a sequence of B2B cold outreach emails to prospects who haven't asked to hear from them. Use when the user mentions 'cold email,' 'cold outreach,' 'prospecting emails,' 'SDR emails,' 'sales emails,' 'first touch email,' 'follow-up sequence,' or 'email prospecting.' Also use when they share an email draft that sounds too sales-y and needs to be humanized. Distinct from email-sequence (lifecycle/nurture to opted-in subscribers) — this is unsolicited outreach to new prospects. NOT for lifecycle emails, newsletters, or drip campaigns (use email-sequence)."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Cold Email Outreach
|
||||
|
||||
You are an expert in B2B cold email outreach. Your goal is to help write, build, and iterate on cold email sequences that sound like they came from a thoughtful human — not a sales machine — and actually get replies.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions.
|
||||
|
||||
Gather this context:
|
||||
|
||||
### 1. The Sender
|
||||
- Who are they at this company? (Role, seniority — affects how they write)
|
||||
- What do they sell and who buys it?
|
||||
- Do they have any real customer results or proof points they can reference?
|
||||
- Are they sending as an individual or as a company?
|
||||
|
||||
### 2. The Prospect
|
||||
- Who is the target? (Job title, company type, company size)
|
||||
- What problem does this person likely have that the sender can solve?
|
||||
- Is there a specific trigger or reason to reach out now? (funding, hiring, news, tech stack signal)
|
||||
- Do they have specific names and companies to personalize to, or is this a template for a segment?
|
||||
|
||||
### 3. The Ask
|
||||
- What's the goal of the first email? (Book a call? Get a reply? Get a referral?)
|
||||
- How aggressive is the timeline? (SDR with daily send volume vs founder doing targeted outreach)
|
||||
|
||||
---
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
### Mode 1: Write the First Email
|
||||
When they need a single first-touch email or a template for a segment.
|
||||
|
||||
1. Understand the ICP, the problem, and the trigger
|
||||
2. Choose the right framework (see `references/frameworks.md`)
|
||||
3. Draft first email: subject line, opener, body, CTA
|
||||
4. Review against the principles below — cut anything that doesn't earn its place
|
||||
5. Deliver: email copy + 2-3 subject line variants + brief rationale
|
||||
|
||||
### Mode 2: Build a Follow-Up Sequence
|
||||
When they need a multi-email sequence (typically 4-6 emails).
|
||||
|
||||
1. Start with the first email (Mode 1)
|
||||
2. Plan follow-up angles — each email needs a different angle, not just a nudge
|
||||
3. Set the gap cadence (Day 1, Day 4, Day 9, Day 16, Day 25)
|
||||
4. Write each follow-up with a standalone hook that doesn't require reading previous emails
|
||||
5. End with a breakup email that closes the loop professionally
|
||||
6. Deliver: full sequence with send gaps, subject lines, and brief on what each email does
|
||||
|
||||
### Mode 3: Iterate from Performance Data
|
||||
When they have an active sequence and want to improve it.
|
||||
|
||||
1. Review their current sequence emails and performance (open rate, reply rate)
|
||||
2. Diagnose: is the problem subject lines (low open rate), email body (opens but no replies), or CTA (replies but wrong outcome)?
|
||||
3. Rewrite the underperforming element
|
||||
4. Deliver: revised emails + diagnosis + test recommendation
|
||||
|
||||
---
|
||||
|
||||
## Core Writing Principles
|
||||
|
||||
### 1. Write Like a Peer, Not a Vendor
|
||||
|
||||
The moment your email sounds like marketing copy, it's over. Think about how you'd actually email a smart colleague at another company who you want to have a conversation with.
|
||||
|
||||
**The test:** Would a friend send this to another friend in business? If the answer is no — rewrite it.
|
||||
|
||||
- ❌ "I'm reaching out because our platform helps companies like yours achieve unprecedented growth..."
|
||||
- ✅ "Noticed you're scaling your SDR team — timing question: are you doing outbound email in-house or using an agency?"
|
||||
|
||||
### 2. Every Sentence Earns Its Place
|
||||
|
||||
Cold email is the wrong place to be thorough. Every sentence should do one of these jobs: create curiosity, establish relevance, build credibility, or drive to the ask. If a sentence doesn't do one of those — cut it.
|
||||
|
||||
Read your draft aloud. The moment you hear yourself droning, stop and cut.
|
||||
|
||||
### 3. Personalization Must Connect to the Problem
|
||||
|
||||
Generic personalization is worse than none. "I saw you went to MIT" followed by a pitch has nothing to do with MIT. That's fake personalization.
|
||||
|
||||
Real personalization: "I saw you're hiring three SDRs — usually a signal that you're trying to scale cold outreach. That's exactly the challenge we help with."
|
||||
|
||||
The personalization must connect to the reason you're reaching out.
|
||||
|
||||
### 4. Lead With Their World, Not Yours
|
||||
|
||||
The opener should be about them — their situation, their problem, their context. Not about you or your product.
|
||||
|
||||
- ❌ "We're a sales intelligence platform that..."
|
||||
- ✅ "Your recent TechCrunch piece mentioned you're entering the SMB market — that transition is notoriously hard to do with an enterprise-built playbook."
|
||||
|
||||
### 5. One Ask Per Email
|
||||
|
||||
Don't ask them to book a call, watch a demo, read a case study, AND reply with their timeline. Pick one ask. The more you ask for, the less likely any of it happens.
|
||||
|
||||
---
|
||||
|
||||
## Voice Calibration by Audience
|
||||
|
||||
Adjust tone, length, and specificity based on who you're writing to:
|
||||
|
||||
| Audience | Length | Tone | Subject Line Style | What Works |
|
||||
|----------|--------|------|-------------------|------------|
|
||||
| C-suite (CEO, CRO, CMO) | 3-4 sentences | Ultra-brief, peer-level, strategic | Short, vague, internal-looking | Big problem → relevant proof → one question |
|
||||
| VP / Director | 5-7 sentences | Direct, metrics-conscious | Slightly more specific | Specific observation + clear business angle |
|
||||
| Mid-level (Manager, Analyst) | 7-10 sentences | Practical, shows you did homework | Can be more descriptive | Specific problem + practical value + easy CTA |
|
||||
| Technical (Engineer, Architect) | 7-10 sentences | Precise, no fluff | Technical specificity | Exact problem → precise solution → low-friction ask |
|
||||
|
||||
The higher up the org chart, the shorter your email needs to be. A CEO gets 100+ emails per day. Three sentences and a clear question is a gift, not a slight.
|
||||
|
||||
---
|
||||
|
||||
## Subject Lines: The Anti-Marketing Approach
|
||||
|
||||
The goal of a subject line is to get the email opened — not to convey value, not to be clever, not to impress anyone. Just open it.
|
||||
|
||||
The best cold email subject lines look like internal emails. They're short, slightly vague, and create just enough curiosity to click.
|
||||
|
||||
### What Works
|
||||
|
||||
| Pattern | Example | Why It Works |
|
||||
|---------|---------|-------------|
|
||||
| Two or three words | `quick question` | Looks like an actual email from a colleague |
|
||||
| Specific trigger + question | `your TechCrunch piece` | Specific enough to not look like spam |
|
||||
| Shared context | `re: Series B` | Feels like a follow-up, not cold |
|
||||
| Observation | `your ATS setup` | Specific, relevant, not salesy |
|
||||
| Referral hook | `[mutual name] suggested I reach out` | Social proof front-loaded |
|
||||
|
||||
### What Kills Opens
|
||||
|
||||
- ALL CAPS anything
|
||||
- Emojis in subject lines (polarizing, often spam-filtered)
|
||||
- Fake Re: or Fwd: (people have learned this trick — it damages trust)
|
||||
- Asking a question in the subject line (e.g., "Are you struggling with X?") — sounds like an ad
|
||||
- Mentioning your company name ("Acme Corp: helping you achieve...")
|
||||
- Numbers that feel like blog headlines ("5 ways to improve your...")
|
||||
|
||||
---
|
||||
|
||||
## Follow-Up Strategy
|
||||
|
||||
Most deals happen in follow-ups. Most follow-ups are useless. The difference is whether the follow-up adds value or just creates noise.
|
||||
|
||||
### Cadence
|
||||
|
||||
| Email | Send Day | Gap |
|
||||
|-------|----------|-----|
|
||||
| Email 1 | Day 1 | — |
|
||||
| Email 2 | Day 4 | +3 days |
|
||||
| Email 3 | Day 9 | +5 days |
|
||||
| Email 4 | Day 16 | +7 days |
|
||||
| Email 5 | Day 25 | +9 days |
|
||||
| Breakup | Day 35 | +10 days |
|
||||
|
||||
Gaps increase over time. You're persistent but not annoying.
|
||||
|
||||
### Follow-Up Rules
|
||||
|
||||
**Each follow-up must have a new angle.** Rotate through:
|
||||
- New piece of evidence (case study, data point, recent result)
|
||||
- New angle on the problem (a different pain point in their world)
|
||||
- Related insight (something you noticed about their industry, tech stack, or news)
|
||||
- Direct question (just ask plainly — sometimes clarity cuts through)
|
||||
- Reverse ask (ask for referral to the right person if you can't reach them)
|
||||
|
||||
**Never "just check in."** "Just following up to see if you had a chance to read my last email" is a waste of both your time and theirs. If you have nothing new to add, don't send the email.
|
||||
|
||||
**Don't reference all previous emails.** Each follow-up should stand alone. The prospect doesn't remember your earlier emails. Don't make them scroll.
|
||||
|
||||
### The Breakup Email
|
||||
|
||||
The last email in a sequence should close the loop professionally. It signals this is the last one — which paradoxically increases reply rate because people don't like loose ends.
|
||||
|
||||
Example breakup:
|
||||
> "I'll stop cluttering your inbox after this one. If [problem] ever becomes a priority, happy to reconnect — just reply here and I'll pick it up.
|
||||
>
|
||||
> If there's someone else at [Company] I should speak with, a name would go a long way.
|
||||
>
|
||||
> Either way — good luck with [whatever's relevant]."
|
||||
|
||||
See `references/follow-up-playbook.md` for full cadence templates and angle rotation guide.
|
||||
|
||||
---
|
||||
|
||||
## What to Avoid
|
||||
|
||||
These are not suggestions — they're patterns that mark you as a non-human and kill reply rates:
|
||||
|
||||
| ❌ Avoid | Why It Fails |
|
||||
|----------|-------------|
|
||||
| "I hope this email finds you well" | Instant tell that this is templated. Cut it. |
|
||||
| "I wanted to reach out because..." | 3-word delay before actually saying anything |
|
||||
| Feature dump in email 1 | Nobody cares about features when they don't trust you yet |
|
||||
| HTML templates with logos and colors | Looks like marketing, gets spam-filtered |
|
||||
| Fake Re:/Fwd: subject lines | Feels deceptive — kills trust before the first word |
|
||||
| "Just checking in" follow-ups | Adds no value, removes credibility |
|
||||
| Opening with "My name is X and I work at Y" | They can see your name. Start with something interesting. |
|
||||
| Social proof that doesn't connect to their problem | "We work with 500 companies" means nothing without context |
|
||||
| Long-form case study in email 1 | Save it for follow-up when they've shown interest |
|
||||
| Passive CTAs ("Let me know if you're interested") | Weak. Ask a direct question or propose a specific next step. |
|
||||
|
||||
---
|
||||
|
||||
## Deliverability Basics
|
||||
|
||||
A great email sent from a flagged domain never lands. Basics you need to have in place:
|
||||
|
||||
- **Dedicated sending domain** — don't send cold email from your primary domain. Use `mail.yourdomain.com` or `outreach.yourdomain.com`.
|
||||
- **SPF, DKIM, DMARC** — all three must be configured and passing. Use mail-tester.com to verify.
|
||||
- **Domain warmup** — new domains need 4-6 weeks of warmup (start with 20/day, ramp up over time).
|
||||
- **Plain text emails** — or minimal HTML. Heavy HTML triggers spam filters.
|
||||
- **Unsubscribe mechanism** — required legally (CAN-SPAM, GDPR). Include a simple opt-out.
|
||||
- **Sending limits** — stay under 100-200 emails/day per domain until established reputation.
|
||||
- **Bounce rate** — above 5% hurts deliverability. Verify email lists before sending.
|
||||
|
||||
See `references/deliverability-guide.md` for domain warmup schedule, SPF/DKIM setup, and spam trigger word list.
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these without being asked:
|
||||
|
||||
- **Email opens with "My name is" or "I'm reaching out because"** → rewrite the opener. These are dead-on-arrival openers. Flag and offer an alternative that leads with their world.
|
||||
- **First email is longer than 150 words** → almost certainly too long. Flag word count and offer to trim.
|
||||
- **No personalization beyond first name** → templated feel will hurt reply rates. Ask if there's a trigger or signal they can work with.
|
||||
- **Follow-up says "just checking in" or "circling back"** → useless follow-up. Ask what new angle or value they can bring to that touchpoint.
|
||||
- **HTML email template** → recommend plain text. Plain text emails have higher deliverability and look less like marketing blasts.
|
||||
- **CTA asks for 30-45 minute meeting in email 1** → too high-friction for cold outreach. Recommend a lower-commitment ask (a 15-minute call, or just a question to gauge interest first).
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| Write a cold email | First-touch email + 3 subject line variants + brief rationale for structure choices |
|
||||
| Build a sequence | 5-6 email sequence with send gaps, subject lines per email, and angle summary for each follow-up |
|
||||
| Critique my email | Line-by-line assessment + rewrite + explanation of each change |
|
||||
| Write follow-ups only | Follow-up emails 2-6 with unique angles per email + breakup email |
|
||||
| Analyze sequence performance | Diagnosis of where the sequence breaks (subject/body/CTA) + specific rewrite recommendations |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding has all three
|
||||
- **Actions have owners and deadlines** — no "we should consider"
|
||||
- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **email-sequence**: For lifecycle and nurture emails to opted-in subscribers. Use email-sequence for onboarding flows, re-engagement campaigns, and automated drips. NOT for cold outreach — that's cold-email.
|
||||
- **copywriting**: For marketing page copy. Principles overlap, but cold email has different constraints — shorter, no CTAs like buttons, must feel personal.
|
||||
- **content-strategy**: For creating the content assets (case studies, guides) you reference in cold email follow-ups. Good follow-up sequences often link to content.
|
||||
- **marketing-strategy-pmm**: For positioning and ICP definition. If you don't know who you're targeting and why, cold email is the wrong tool to figure that out.
|
||||
225
marketing-skill/cold-email/references/deliverability-guide.md
Normal file
225
marketing-skill/cold-email/references/deliverability-guide.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Deliverability Guide
|
||||
|
||||
A cold email that lands in spam is worse than no email at all — it damages your sender reputation for future sends. Get deliverability right before you worry about copy.
|
||||
|
||||
---
|
||||
|
||||
## The Deliverability Stack
|
||||
|
||||
Email deliverability is a layer cake. Every layer has to be correct:
|
||||
|
||||
```
|
||||
Domain reputation (is your domain trusted by inbox providers?)
|
||||
↓
|
||||
Authentication (SPF, DKIM, DMARC — are you who you say you are?)
|
||||
↓
|
||||
Sending infrastructure (IP reputation, sending limits, ramp-up)
|
||||
↓
|
||||
List quality (are you sending to real, active addresses?)
|
||||
↓
|
||||
Email content (does the content look like spam?)
|
||||
↓
|
||||
Engagement signals (opens, replies, not-spam clicks)
|
||||
```
|
||||
|
||||
Fix problems from the bottom up. No point perfecting copy if your domain is blacklisted.
|
||||
|
||||
---
|
||||
|
||||
## Domain Setup
|
||||
|
||||
### Use a Dedicated Sending Domain
|
||||
|
||||
Never send cold email from your primary company domain (`acme.com`). If your cold email domain gets flagged or blacklisted, you lose your main domain's email reputation.
|
||||
|
||||
**Setup options:**
|
||||
- `mail.acme.com` — subdomain of main domain
|
||||
- `acme-hq.com` — separate domain with similar name
|
||||
- `getacme.com` / `tryacme.com` — common pattern for SaaS
|
||||
|
||||
**Rules for the sending domain:**
|
||||
- Set up a proper website (even a simple redirect to main site) — bare domains look suspicious
|
||||
- Match the company name visually — unrelated domains look like phishing
|
||||
- Get a G Suite / Microsoft 365 mailbox on it — shared hosting email servers have worse reputation
|
||||
|
||||
### SPF Record
|
||||
|
||||
SPF (Sender Policy Framework) tells receiving servers which IP addresses are allowed to send email from your domain. Without it, your emails look unauthenticated.
|
||||
|
||||
**DNS TXT record:**
|
||||
```
|
||||
v=spf1 include:_spf.google.com ~all
|
||||
```
|
||||
|
||||
Replace `_spf.google.com` with your sending provider's SPF include. Check your provider's documentation for the exact value (Google Workspace, SendGrid, Mailgun, etc. all have their own).
|
||||
|
||||
**Important:** Only have ONE SPF record per domain. If you have multiple, they conflict and authentication fails.
|
||||
|
||||
### DKIM
|
||||
|
||||
DKIM (DomainKeys Identified Mail) adds a cryptographic signature to your emails, proving they weren't tampered with in transit.
|
||||
|
||||
Setup is done through your email provider — they give you a DNS TXT record to add. It looks like:
|
||||
|
||||
```
|
||||
google._domainkey.yourdomain.com IN TXT "v=DKIM1; k=rsa; p=MIGfMA0..."
|
||||
```
|
||||
|
||||
The public key in that record lets receiving servers verify your email's signature.
|
||||
|
||||
### DMARC
|
||||
|
||||
DMARC ties SPF and DKIM together and tells receiving servers what to do when authentication fails.
|
||||
|
||||
**Starter DMARC record (monitoring mode):**
|
||||
```
|
||||
_dmarc.yourdomain.com IN TXT "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"
|
||||
```
|
||||
|
||||
`p=none` means monitor but don't block — good to start with. Once you've confirmed SPF and DKIM are working cleanly, move to `p=quarantine` or `p=reject`.
|
||||
|
||||
### Verify Everything
|
||||
|
||||
Use **mail-tester.com**: send a test email to their address, then check your score. 9/10 or higher means your authentication is clean. Below 7/10 means something is broken.
|
||||
|
||||
---
|
||||
|
||||
## Domain Warmup
|
||||
|
||||
A brand new domain has no sending reputation. Email providers don't trust it. If you start sending 200 emails/day on day one, you will be flagged.
|
||||
|
||||
Warmup = building reputation gradually by sending low volumes and getting positive engagement.
|
||||
|
||||
### Warmup Schedule
|
||||
|
||||
| Week | Emails/Day | Focus |
|
||||
|------|-----------|-------|
|
||||
| 1 | 5-10 | Real conversations only — send to colleagues, get replies |
|
||||
| 2 | 20-30 | Small cold outreach batches — highly targeted, good lists |
|
||||
| 3 | 40-60 | Expand slightly — maintain >30% open rate |
|
||||
| 4 | 80-100 | Normal volume — watch bounce and spam complaint rates |
|
||||
| 5+ | Up to 200 | Full volume — monitor daily |
|
||||
|
||||
**Warning signs that warmup is failing:**
|
||||
- Open rate drops below 20%
|
||||
- Bounce rate above 3%
|
||||
- Spam complaint rate above 0.1%
|
||||
- Emails landing in Gmail Promotions tab
|
||||
|
||||
**Manual warmup vs tools:** Tools like Lemwarm, Warmup Inbox, or Mailreach automate warmup by sending emails to a network of inboxes that automatically open and engage. These help build reputation faster. They're worth it for new domains.
|
||||
|
||||
---
|
||||
|
||||
## List Quality
|
||||
|
||||
Sending to bad email addresses destroys your sender reputation. Every hard bounce tells inbox providers your list is dirty.
|
||||
|
||||
### Before Sending
|
||||
|
||||
1. **Verify email addresses** — Use a verification tool (NeverBounce, ZeroBounce, Hunter's verify, etc.) before importing any list. Remove invalid, catch-all, and risky emails.
|
||||
|
||||
2. **Target bounce rate:** Keep it below 2%. Above 5% is dangerous territory.
|
||||
|
||||
3. **Remove catch-all domains carefully** — Catch-all domains accept any email regardless of whether the mailbox exists. Your emails won't hard-bounce, but they may go nowhere.
|
||||
|
||||
4. **Never buy lists** — Purchased lists are old, dirty, unverified, and frequently include spam traps (addresses placed by inbox providers to catch spammers). One spam trap hit can blacklist your domain.
|
||||
|
||||
### Ongoing Hygiene
|
||||
|
||||
- Remove anyone who hasn't opened in 90 days from your sequence (move to a re-engagement campaign or suppress)
|
||||
- Remove unsubscribes immediately — required legally and good for reputation
|
||||
- Remove bounces from all future sends automatically
|
||||
|
||||
---
|
||||
|
||||
## Content That Hurts Deliverability
|
||||
|
||||
Spam filters evaluate content alongside authentication and reputation. These patterns trigger filters:
|
||||
|
||||
### Spam Trigger Words to Avoid
|
||||
|
||||
High-risk words and phrases (use sparingly or avoid):
|
||||
- "Free" (especially in subject lines)
|
||||
- "Guaranteed" / "100% guaranteed"
|
||||
- "No obligation"
|
||||
- "Act now" / "Limited time"
|
||||
- "Congratulations"
|
||||
- "You've been selected"
|
||||
- "Click here"
|
||||
- "Earn money" / "Make money"
|
||||
- "Risk-free"
|
||||
- "Special offer"
|
||||
- Excessive exclamation points!!!
|
||||
- ALL CAPS words
|
||||
|
||||
These don't automatically spam-filter you, but they're additive — the more of them in a single email, the higher the spam score.
|
||||
|
||||
### Content Rules
|
||||
|
||||
| Do | Don't |
|
||||
|----|-------|
|
||||
| Plain text or minimal HTML | Heavy HTML with complex tables, images |
|
||||
| One link max per email | 5+ links — looks like phishing or newsletter |
|
||||
| Personalized subject lines | Batch-blasted "LAST CHANCE" subject lines |
|
||||
| Unsubscribe link | No unsubscribe mechanism |
|
||||
| Consistent from name | Rotating from names |
|
||||
| Short emails | Wall-of-text emails |
|
||||
|
||||
### The HTML Question
|
||||
|
||||
Plain text emails consistently get better deliverability than HTML emails for cold outreach. They look like real emails from real people — because they are.
|
||||
|
||||
If you need to include your company logo and a fancy template: don't. Save that for newsletters to opted-in subscribers. Cold email = plain text, signed like a person.
|
||||
|
||||
---
|
||||
|
||||
## Sending Limits by Platform
|
||||
|
||||
| Platform | Safe Daily Volume | Notes |
|
||||
|----------|------------------|-------|
|
||||
| Google Workspace (paid) | 500/day | Shared across all outgoing |
|
||||
| Google Workspace + Warmup | Up to 2000/day | After full warmup |
|
||||
| Microsoft 365 | 10,000/day | Generous, but still subject to reputation |
|
||||
| SendGrid | Depends on plan | IP reputation matters at scale |
|
||||
| Mailgun | Depends on plan | Good for transactional, OK for cold |
|
||||
| Lemlist / Instantly / Apollo | Platform-managed | Warmup built in, use their sending infrastructure |
|
||||
|
||||
For cold outreach at scale (>500/day), dedicated sending platforms are better than Google/Microsoft direct — they're designed to manage reputation across many users.
|
||||
|
||||
---
|
||||
|
||||
## Checking Your Reputation
|
||||
|
||||
If you suspect deliverability problems, check these:
|
||||
|
||||
1. **Mail-tester.com** — Authentication and content score (10/10 is perfect)
|
||||
2. **MXToolbox Blacklist Check** — Check if your domain or IP is on any blacklists
|
||||
3. **Google Postmaster Tools** — Shows your domain reputation with Gmail (spam rate, auth failures)
|
||||
4. **Microsoft SNDS** — Similar to Google Postmaster for Outlook/Hotmail
|
||||
|
||||
**If you're on a blacklist:**
|
||||
- Stop sending immediately from that domain
|
||||
- Identify the cause (bad list, spam complaints, warmup failure)
|
||||
- Follow the blacklist's delisting process (each has its own)
|
||||
- Consider using a new domain while the old one recovers
|
||||
|
||||
---
|
||||
|
||||
## Legal Requirements
|
||||
|
||||
Cold email has legal requirements in most markets. Breaking them isn't just unethical — it's fined.
|
||||
|
||||
| Regulation | Where | Key Requirements |
|
||||
|-----------|-------|-----------------|
|
||||
| CAN-SPAM | USA | Honest subject line, physical address, unsubscribe mechanism |
|
||||
| CASL | Canada | Requires express or implied consent — much stricter than CAN-SPAM |
|
||||
| GDPR | EU/EEA | Legitimate interest basis required; no soft opt-in |
|
||||
| PECR | UK | Similar to GDPR; ICO enforcement |
|
||||
|
||||
**Minimum compliance for most cold email:**
|
||||
- Include your company name and physical address in every email
|
||||
- Provide a working unsubscribe link or reply-to-unsubscribe instruction
|
||||
- Honor unsubscribes within 10 business days (CAN-SPAM) or immediately (GDPR best practice)
|
||||
- Don't use misleading subject lines or from names
|
||||
|
||||
**Disclaimer:** This is practical guidance, not legal advice. For EU/Canada outreach, consult a lawyer who specializes in email marketing law — GDPR and CASL are stricter than most people realize.
|
||||
225
marketing-skill/cold-email/references/follow-up-playbook.md
Normal file
225
marketing-skill/cold-email/references/follow-up-playbook.md
Normal file
@@ -0,0 +1,225 @@
|
||||
# Follow-Up Playbook
|
||||
|
||||
Full cadence guide, angle rotation, and breakup email templates. The goal: stay persistent without becoming noise.
|
||||
|
||||
---
|
||||
|
||||
## The Core Problem with Follow-Ups
|
||||
|
||||
Most follow-up emails are a form of wishful thinking: "Maybe they missed it. I'll send it again." They didn't miss it. They read it, didn't feel urgency, and moved on. Another "just checking in" doesn't create urgency — it signals that you have nothing new to offer.
|
||||
|
||||
The only follow-up worth sending is one that adds something: a new angle, a new proof point, a new question, or a new frame.
|
||||
|
||||
---
|
||||
|
||||
## The Full Cadence
|
||||
|
||||
| Email | Label | Day | Gap | Purpose |
|
||||
|-------|-------|-----|-----|---------|
|
||||
| 1 | First touch | Day 1 | — | Lead with their world, establish relevance |
|
||||
| 2 | New angle | Day 4 | +3 | Different problem angle or social proof |
|
||||
| 3 | Value add | Day 9 | +5 | Resource, insight, or data point |
|
||||
| 4 | Direct question | Day 16 | +7 | Cut through with a plain, direct ask |
|
||||
| 5 | Reverse | Day 25 | +9 | Ask for referral to the right person |
|
||||
| 6 | Breakup | Day 35 | +10 | Close the loop, leave door open |
|
||||
|
||||
Gaps increase over time. You're persistent but not desperate.
|
||||
|
||||
6 emails is the upper limit for most cold outreach. For very high-value accounts (ABM-style), you might go to 8. For volume prospecting, 4-5 is often more practical.
|
||||
|
||||
---
|
||||
|
||||
## Email-by-Email Guide
|
||||
|
||||
### Email 1: First Touch
|
||||
Already covered in `frameworks.md`. The anchor of the sequence.
|
||||
|
||||
**What it needs:**
|
||||
- Specific, relevant opener
|
||||
- Clear connection between their situation and what you do
|
||||
- One ask, low friction
|
||||
|
||||
---
|
||||
|
||||
### Email 2: New Angle (Day 4)
|
||||
|
||||
This is where most sequences fail — they send a "following up" reminder. Don't.
|
||||
|
||||
Email 2 should approach the problem from a different angle than Email 1. If Email 1 was about their hiring signal, Email 2 might be about the operational risk that follows from rapid hiring. Different angle, same direction.
|
||||
|
||||
**Angle options for Email 2:**
|
||||
- Different pain point in the same domain
|
||||
- Social proof / customer story that's highly relevant to their context
|
||||
- An industry trend that makes the problem more urgent
|
||||
- A specific, relevant statistic you haven't mentioned yet
|
||||
|
||||
**Template structure:**
|
||||
```
|
||||
[New angle or observation — 1-2 sentences]
|
||||
[Expand on why it matters for their situation — 1-2 sentences]
|
||||
[Soft CTA — question or invitation]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> A lot of the teams I talk to at your stage are hitting the same wall: the ramp time on new SDRs has stretched from 3 months to 5+ months because the playbook that worked at 5 reps doesn't scale to 15.
|
||||
>
|
||||
> It's not a hiring problem — it's an enablement infrastructure problem that doesn't become visible until you're already in it.
|
||||
>
|
||||
> Is that a challenge you're actively working on, or is it on the radar for later?
|
||||
|
||||
---
|
||||
|
||||
### Email 3: Value Add (Day 9)
|
||||
|
||||
Give something useful before asking again. This builds goodwill and separates you from the other 30 emails in their inbox that only ask.
|
||||
|
||||
**What counts as value:**
|
||||
- A relevant guide, benchmark report, or template (if you have one)
|
||||
- A specific insight about their market or competitor landscape
|
||||
- A practical suggestion based on what you know about their situation
|
||||
- A useful question that helps them think about their problem differently
|
||||
|
||||
**Template structure:**
|
||||
```
|
||||
[Reference to something specific about them — 1 sentence]
|
||||
[The value: insight, resource, or useful observation — 2-3 sentences]
|
||||
[Low-friction CTA: "useful?" or "happy to elaborate" or specific ask]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> We just published a benchmark of SDR ramp times across 40 SaaS companies by stage — the data is pretty surprising (the fastest don't hire the most experienced reps, they do onboarding completely differently).
|
||||
>
|
||||
> Thought of your situation when reviewing it. Happy to share the relevant section if useful — no strings, just might be helpful context for where you're headed.
|
||||
|
||||
---
|
||||
|
||||
### Email 4: Direct Question (Day 16)
|
||||
|
||||
By Email 4, subtlety has run its course. Sometimes the most effective move is to ask a direct, plain question. No setup, no story.
|
||||
|
||||
This email is short. Often just two or three lines.
|
||||
|
||||
**Options:**
|
||||
- Ask what's getting in the way
|
||||
- Ask if your assumption about their problem is wrong
|
||||
- Ask if the timing just isn't right
|
||||
- Ask who the right person to talk to is
|
||||
|
||||
**Template structure:**
|
||||
```
|
||||
[One direct question — sometimes that's all this email needs to be]
|
||||
[Optional: one sentence of context if needed]
|
||||
[Nothing else]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> Is SDR ramp time actually a priority for you right now, or is the timing just off?
|
||||
>
|
||||
> No judgment either way — just helps me know whether it's worth staying in touch.
|
||||
|
||||
Or even shorter:
|
||||
> Am I reaching the wrong person here — is there someone else on your team who owns sales enablement?
|
||||
|
||||
---
|
||||
|
||||
### Email 5: Reverse / Referral (Day 25)
|
||||
|
||||
If you haven't reached the right person, this email shifts to asking for the referral. If you have reached the right person but they haven't replied, the referral ask sometimes unlocks a conversation because it's a different and lower-commitment request.
|
||||
|
||||
**Template structure:**
|
||||
```
|
||||
[Acknowledge you may not be reaching the right person — 1 sentence]
|
||||
[Who you're actually looking for — specific role or function — 1 sentence]
|
||||
[Referral ask — 1 sentence]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> I might be reaching out to the wrong person — the conversations I typically have are with whoever owns sales onboarding and enablement, which may not be you.
|
||||
>
|
||||
> If there's a name you could point me toward, I'd really appreciate it. And if it is you — totally understand if the timing isn't right.
|
||||
|
||||
---
|
||||
|
||||
### Email 6: Breakup (Day 35)
|
||||
|
||||
The last email. Its job is to close the loop professionally and leave the relationship in a better place than if you'd just gone silent.
|
||||
|
||||
The breakup email often generates the highest reply rate of the entire sequence — people don't like unanswered threads.
|
||||
|
||||
**What makes a good breakup:**
|
||||
- Signals clearly that this is the last one (without being dramatic about it)
|
||||
- Leaves the door open — no hard feelings
|
||||
- Offers one final path to action (reply, referral, or reconnect later)
|
||||
- Keeps it under 5 sentences
|
||||
|
||||
**Template:**
|
||||
```
|
||||
[Signal this is your last email — 1 sentence]
|
||||
[Genuine offer to reconnect when timing changes — 1 sentence]
|
||||
[Referral ask as a final option — 1 sentence]
|
||||
[Warm close — 1 sentence]
|
||||
```
|
||||
|
||||
**Example:**
|
||||
> I'll stop cluttering your inbox after this one.
|
||||
>
|
||||
> If scaling your outbound motion ever becomes a priority, happy to pick this back up — just reply here and I'll be there.
|
||||
>
|
||||
> If there's someone else at [Company] who owns this, a name would be genuinely helpful.
|
||||
>
|
||||
> Either way, good luck with the Berlin expansion.
|
||||
|
||||
**What to avoid in the breakup:**
|
||||
- Passive-aggressive tone ("I've tried to reach you several times now...")
|
||||
- Fake urgency ("This is your last chance to...")
|
||||
- Asking for feedback on why they didn't reply (annoying, not useful)
|
||||
|
||||
---
|
||||
|
||||
## Angle Rotation Guide
|
||||
|
||||
Never repeat the same angle twice. Here are enough angles for a full 6-email sequence on any B2B topic:
|
||||
|
||||
| Angle | Description | Example |
|
||||
|-------|------------|---------|
|
||||
| Trigger event | The specific reason you reached out | "Saw the funding announcement..." |
|
||||
| Adjacent pain | A related problem they also likely have | "The challenge after that usually is..." |
|
||||
| Social proof | Customer story or result | "We helped a team in your situation..." |
|
||||
| Industry trend | External force making the problem more urgent | "EMEA data residency rules are tightening..." |
|
||||
| Data/benchmark | A specific number that reframes the problem | "The average ramp time in your segment is 4.2 months..." |
|
||||
| Counterintuitive insight | Something most people in their role get wrong | "Most teams solve this by hiring more, which makes it worse..." |
|
||||
| Resource offer | Something genuinely useful, no strings | "We just published a guide on exactly this..." |
|
||||
| Direct question | Plain, honest ask | "Is this even a priority right now?" |
|
||||
| Referral ask | Ask for the right person if not them | "Am I talking to the right person here?" |
|
||||
| Breakup | Close the loop | "I'll stop after this one..." |
|
||||
|
||||
Sequence design tip: never use two heavy asks back to back. Pattern: trigger → social proof → value → direct → referral → breakup works better than ask → ask → ask → ask → ask → breakup.
|
||||
|
||||
---
|
||||
|
||||
## Short Sequence Variations
|
||||
|
||||
### 3-Email Sequence (High-Volume SDR)
|
||||
1. Day 1: OPPA framework (trigger + problem + proof + ask)
|
||||
2. Day 5: Value add (resource, insight, or data point)
|
||||
3. Day 12: Breakup
|
||||
|
||||
### 4-Email Sequence (Balanced)
|
||||
1. Day 1: First touch
|
||||
2. Day 4: New angle / social proof
|
||||
3. Day 10: Direct question
|
||||
4. Day 20: Breakup
|
||||
|
||||
### 6-Email Sequence (ABM / High-Value Accounts)
|
||||
Full sequence as described above.
|
||||
|
||||
---
|
||||
|
||||
## What Never to Send
|
||||
|
||||
- **"Just following up"** — Adds nothing. Deletes itself.
|
||||
- **"Did you see my last email?"** — They saw it. This is passive-aggressive.
|
||||
- **"I wanted to make sure this didn't get lost"** — Patronizing.
|
||||
- **"I know you're busy but..."** — Everyone's busy. Don't invoke it.
|
||||
- **A forwarded copy of the original email** — They have the original. This is lazy.
|
||||
- **Back-to-back emails on the same day** — Unless it's a clear error correction.
|
||||
217
marketing-skill/cold-email/references/frameworks.md
Normal file
217
marketing-skill/cold-email/references/frameworks.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# Cold Email Outreach Frameworks
|
||||
|
||||
Three frameworks that work, when to use each, and how to apply them with examples.
|
||||
|
||||
---
|
||||
|
||||
## How to Use This Guide
|
||||
|
||||
A framework is a structure, not a script. Use it to organize your thinking, then write in your own voice. If an email sounds like it was written from a template, the framework failed.
|
||||
|
||||
Each framework works best in specific situations — the mismatch between framework and context is why most cold emails fall flat.
|
||||
|
||||
---
|
||||
|
||||
## Framework 1: Observation → Problem → Proof → Ask (OPPA)
|
||||
|
||||
**Best for:** Prospects where you have a specific, real observation (trigger event, signal, public info). This is the most versatile framework and the default for most B2B cold email.
|
||||
|
||||
**What it does:** Starts with something real and specific about them, connects it to a problem they likely have, brings in credibility, and asks a focused question.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Observation]: Something specific and true about them right now.
|
||||
[Problem]: The logical challenge or risk that creates.
|
||||
[Proof]: One concrete piece of evidence you can solve it.
|
||||
[Ask]: A single, low-friction question or request.
|
||||
```
|
||||
|
||||
### How to Write Each Part
|
||||
|
||||
**Observation** — This must be:
|
||||
- Specific (not "I see you're in the software industry")
|
||||
- Recent (not something from 2 years ago)
|
||||
- Relevant to the problem you're about to raise
|
||||
- Non-creepy (public info: LinkedIn, press, job postings, tech stack signals)
|
||||
|
||||
Good observations:
|
||||
- "Saw the announcement that you're opening a Berlin office."
|
||||
- "Noticed you're hiring 4 SDRs simultaneously — unusual to scale the team that fast."
|
||||
- "Your last three blog posts have all been about compliance — guessing that's a pressure point right now."
|
||||
|
||||
**Problem** — This should feel like something they already know is true, not something you're trying to convince them of.
|
||||
|
||||
- ❌ "Companies like yours struggle with X."
|
||||
- ✅ "That scale-up usually surfaces a bunch of process gaps that are invisible when you're smaller."
|
||||
|
||||
**Proof** — Keep it tight. One result, one customer name (if allowed), or one specific claim. Not a list.
|
||||
|
||||
- ❌ "We work with 300+ companies and have won 7 awards."
|
||||
- ✅ "We helped a similar-sized team in fintech cut SDR ramp time by 40% in the first quarter."
|
||||
|
||||
**Ask** — One ask. Low friction. Makes it easy to say yes or no.
|
||||
|
||||
- ❌ "Would you be open to a 45-minute product walkthrough with our sales team?"
|
||||
- ✅ "Worth 15 minutes to compare notes on how you're handling this?"
|
||||
|
||||
### Full Example
|
||||
|
||||
**Subject:** your Berlin expansion
|
||||
|
||||
> Congrats on the Berlin announcement — Series B followed by a new market in the same quarter is a big move.
|
||||
>
|
||||
> The part that usually bites teams at this stage: the go-to-market motion that worked for your home market rarely translates directly, especially if you're dealing with different buyer personas and a cold pipeline.
|
||||
>
|
||||
> We've helped three B2B SaaS teams with exactly this transition — the fastest got pipeline moving in Germany within 90 days. Happy to share what worked.
|
||||
>
|
||||
> Worth a 20-minute call to compare notes?
|
||||
|
||||
---
|
||||
|
||||
## Framework 2: Question → Value → Ask (QVA)
|
||||
|
||||
**Best for:** Situations where you don't have a strong trigger event, but you understand the prospect's world well enough to lead with a sharp insight or question. Good for segmented outreach to a persona with a known, common pain.
|
||||
|
||||
**What it does:** Opens with a question that creates cognitive engagement — they can't help but answer it in their head. Then delivers value before asking for anything.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Question]: A question they're probably already asking themselves.
|
||||
[Value]: An insight, reframe, or resource that helps them — before they've agreed to anything.
|
||||
[Ask]: Low-friction request to continue the conversation.
|
||||
```
|
||||
|
||||
### How to Write Each Part
|
||||
|
||||
**Question** — Not a rhetorical sales question ("Are you struggling with X?"). An actual, thoughtful question they'd ask at a team meeting.
|
||||
|
||||
- ❌ "Are you struggling to hit your pipeline targets?"
|
||||
- ✅ "What's your current approach to EMEA expansion — inside sales, channel, or hybrid?"
|
||||
|
||||
The question works because it's specific enough that only a relevant person can answer it, and answering it in their head pulls them into the email.
|
||||
|
||||
**Value** — Give something before asking for anything. This is the differentiator. Options:
|
||||
- A useful insight from your experience working in their space
|
||||
- A specific data point or benchmark they probably don't have
|
||||
- A framework or reframe that's genuinely useful
|
||||
- A short, actionable observation about their situation
|
||||
|
||||
This doesn't need to be long. Two sentences of genuine value beats two paragraphs of soft selling.
|
||||
|
||||
**Ask** — Same rules as OPPA. One ask, low friction, specific.
|
||||
|
||||
### Full Example
|
||||
|
||||
**Subject:** EMEA expansion approach
|
||||
|
||||
> Quick question — are you planning to open EMEA with a field sales team, or running it remotely from the US for the first 12 months?
|
||||
>
|
||||
> I ask because we've seen both approaches play out across about 30 SaaS companies doing this move, and the one that consistently underperforms is the "remote first, hire local later" model — not because of the sales motion, but because of the support/onboarding gap that follows when you close enterprise deals in a timezone you don't cover.
|
||||
>
|
||||
> Happy to share a quick breakdown of what the fastest-scaling teams do differently if that's useful. 15 minutes?
|
||||
|
||||
---
|
||||
|
||||
## Framework 3: Trigger → Insight → Ask (TIA)
|
||||
|
||||
**Best for:** When you have a very specific, time-sensitive trigger event and want to move fast. Great for sales teams with intent signals, tech stack changes, funding news, leadership changes, or industry regulatory shifts.
|
||||
|
||||
**What it does:** Names the trigger directly, provides a non-obvious insight about what that trigger means, and asks a focused question while the timing is relevant.
|
||||
|
||||
### Structure
|
||||
|
||||
```
|
||||
[Trigger]: Name the specific event/signal you observed.
|
||||
[Insight]: Something non-obvious about what that trigger typically means/leads to.
|
||||
[Ask]: Direct, time-aware request.
|
||||
```
|
||||
|
||||
### How to Write Each Part
|
||||
|
||||
**Trigger** — Be specific and direct. Don't be coy about why you're reaching out.
|
||||
|
||||
- ❌ "I was browsing LinkedIn and happened to notice..."
|
||||
- ✅ "Saw the funding announcement this morning."
|
||||
|
||||
**Insight** — The non-obvious part is what separates this from lazy trigger-based outreach. You're not just saying "congrats on the funding" — you're showing you understand what that trigger means operationally.
|
||||
|
||||
Pattern: "That usually means [specific operational challenge] that most [their role] underestimate."
|
||||
|
||||
- ❌ "Congrats! We'd love to help you grow."
|
||||
- ✅ "Series A typically means the first real pressure to build repeatable pipeline — and most companies at this stage haven't yet figured out which channels actually scale."
|
||||
|
||||
**Ask** — Frame the timing as genuine, not manufactured urgency.
|
||||
|
||||
- ❌ "Act now before it's too late!"
|
||||
- ✅ "First 60 days post-funding is when this gets set up or doesn't — worth a quick call?"
|
||||
|
||||
### Full Example
|
||||
|
||||
**Subject:** post-Series A pipeline
|
||||
|
||||
> Saw the Series A close — congrats.
|
||||
>
|
||||
> The next 90 days are when pipeline architecture either gets built properly or gets bolted together in a way that causes problems at Series B. Most founders don't realize until 18 months later that they're paying for shortcuts made now.
|
||||
>
|
||||
> We work specifically with post-Series A B2B SaaS teams setting up their outbound motion for the first time. Happy to do a no-strings 20-minute call on what works and what doesn't at your stage.
|
||||
>
|
||||
> Useful?
|
||||
|
||||
---
|
||||
|
||||
## Choosing the Right Framework
|
||||
|
||||
| Situation | Use |
|
||||
|-----------|-----|
|
||||
| Strong trigger event (funding, hiring, news, tech change) | TIA |
|
||||
| Good persona understanding, no specific trigger | QVA |
|
||||
| Mix of trigger + problem knowledge | OPPA |
|
||||
| Referral or warm intro context | OPPA with referral opener |
|
||||
| Re-engaging a past prospect | QVA with callback to previous context |
|
||||
|
||||
## Combining Frameworks
|
||||
|
||||
These frameworks aren't rigid. In practice, the best emails blend elements:
|
||||
- TIA trigger + OPPA proof
|
||||
- QVA question + TIA timing
|
||||
- OPPA observation + QVA value
|
||||
|
||||
What you can't blend: two questions, two proof points, or two asks. One of each, always.
|
||||
|
||||
---
|
||||
|
||||
## Subject Line Frameworks
|
||||
|
||||
Subject lines have their own logic — separate from the email body.
|
||||
|
||||
### The Blank Subject
|
||||
Two or three words, no capitalization, feels like an internal message.
|
||||
- `quick question`
|
||||
- `cold outreach`
|
||||
- `your q3 pipeline`
|
||||
|
||||
### The Named Trigger
|
||||
Specific enough to signal you did research, vague enough to create curiosity.
|
||||
- `your Series A`
|
||||
- `Berlin office`
|
||||
- `your ATS stack`
|
||||
|
||||
### The Shared Context
|
||||
Implies a pre-existing relationship or shared frame.
|
||||
- `re: EMEA expansion`
|
||||
- `following up on the hiring spike`
|
||||
|
||||
### The Named Person (Referral)
|
||||
Only use if the referral is real — never fake this.
|
||||
- `[Mutual Name] suggested I reach out`
|
||||
- `[Name] mentioned you're building out your SDR team`
|
||||
|
||||
### Never Use
|
||||
- `Quick question about your [product category] strategy!`
|
||||
- `Revolutionize your [function] with [product name]`
|
||||
- `[FIRST NAME], we have a special offer for you`
|
||||
- Emojis
|
||||
- ALL CAPS
|
||||
- Question marks (feels like an ad)
|
||||
504
marketing-skill/cold-email/scripts/email_sequence_analyzer.py
Normal file
504
marketing-skill/cold-email/scripts/email_sequence_analyzer.py
Normal file
@@ -0,0 +1,504 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
email_sequence_analyzer.py — Analyzes a cold email sequence for quality signals.
|
||||
|
||||
Evaluates each email on:
|
||||
- Word count (shorter is usually better for cold email)
|
||||
- Reading level estimate (Flesch-Kincaid approximation via avg sentence/word length)
|
||||
- Personalization density (signals of specific, targeted writing)
|
||||
- CTA clarity (is there a clear ask?)
|
||||
- Spam trigger words (words that hurt deliverability)
|
||||
- Subject line analysis (length, warning patterns)
|
||||
- Overall score: 0-100
|
||||
|
||||
Usage:
|
||||
python3 email_sequence_analyzer.py [sequence.json]
|
||||
cat sequence.json | python3 email_sequence_analyzer.py
|
||||
|
||||
If no file provided, runs on embedded sample sequence.
|
||||
|
||||
Input format (JSON):
|
||||
[
|
||||
{
|
||||
"email": 1,
|
||||
"subject": "...",
|
||||
"body": "..."
|
||||
},
|
||||
...
|
||||
]
|
||||
|
||||
Stdlib only — no external dependencies.
|
||||
"""
|
||||
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
import math
|
||||
import select
|
||||
from typing import List, Dict, Any
|
||||
|
||||
|
||||
# ─── Spam trigger words ───────────────────────────────────────────────────────
|
||||
|
||||
SPAM_TRIGGERS = [
|
||||
"free", "guaranteed", "no obligation", "act now", "limited time",
|
||||
"click here", "earn money", "make money", "risk-free", "special offer",
|
||||
"no cost", "winner", "congratulations", "you've been selected",
|
||||
"once in a lifetime", "urgent", "don't miss out", "buy now",
|
||||
"order now", "100%", "best price", "lowest price", "incredible deal",
|
||||
"amazing offer", "cash bonus", "extra cash", "fast cash",
|
||||
"you have been chosen", "exclusive deal", "as seen on",
|
||||
"dear friend", "valued customer",
|
||||
]
|
||||
|
||||
# ─── Personalization signals ──────────────────────────────────────────────────
|
||||
|
||||
PERSONALIZATION_SIGNALS = [
|
||||
# Direct references to "you"
|
||||
r'\byou(?:r|rs|\'re|\'ve|\'d|\'ll)?\b',
|
||||
# Trigger references
|
||||
r'\b(?:saw|noticed|read|heard|saw|found|noted)\b',
|
||||
# Named observation patterns
|
||||
r'\b(?:your team|your company|your role|your work|your recent|your post)\b',
|
||||
# Industry/role-specific references
|
||||
r'\b(?:as a|in your|at your|given your)\b',
|
||||
# Specific numbers or facts
|
||||
r'\b\d{4}\b', # years — often a sign of specific research
|
||||
r'\$\d+|\d+%', # numbers with $ or %
|
||||
]
|
||||
|
||||
# ─── Dead opener phrases ──────────────────────────────────────────────────────
|
||||
|
||||
DEAD_OPENERS = [
|
||||
"i hope this email finds you well",
|
||||
"i hope this finds you",
|
||||
"i wanted to reach out",
|
||||
"i am reaching out",
|
||||
"my name is",
|
||||
"i'm writing to",
|
||||
"i am writing to",
|
||||
"hope you're doing well",
|
||||
"i hope you are doing well",
|
||||
"just following up",
|
||||
"just checking in",
|
||||
"circling back",
|
||||
"touching base",
|
||||
"per my last email",
|
||||
"as per my previous",
|
||||
]
|
||||
|
||||
# ─── Weak CTA patterns ────────────────────────────────────────────────────────
|
||||
|
||||
WEAK_CTA = [
|
||||
"let me know if you're interested",
|
||||
"let me know if you would be interested",
|
||||
"feel free to",
|
||||
"please don't hesitate",
|
||||
"if you have any questions",
|
||||
"looking forward to hearing from you",
|
||||
"i look forward to connecting",
|
||||
"hope we can connect",
|
||||
]
|
||||
|
||||
# ─── Strong CTA signals ───────────────────────────────────────────────────────
|
||||
|
||||
STRONG_CTA_PATTERNS = [
|
||||
r'\b(?:15|20|30|45|60)[\s-]?minute\b', # time-specific meeting ask
|
||||
r'\b(?:call|chat|talk|speak|connect|meet)\b.*\?', # question + meeting word
|
||||
r'worth\s+(?:a|an)\b', # "worth a call?"
|
||||
r'\?$', # ends with question
|
||||
r'\buseful\b\s*\?', # "useful?"
|
||||
r'\b(?:reply|respond)\b', # explicit reply ask
|
||||
]
|
||||
|
||||
|
||||
# ─── Text utilities ───────────────────────────────────────────────────────────
|
||||
|
||||
def count_words(text: str) -> int:
|
||||
return len(text.split())
|
||||
|
||||
|
||||
def count_sentences(text: str) -> int:
|
||||
"""Rough sentence count by terminal punctuation."""
|
||||
sentences = re.split(r'[.!?]+', text)
|
||||
return max(1, len([s for s in sentences if s.strip()]))
|
||||
|
||||
|
||||
def avg_words_per_sentence(text: str) -> float:
|
||||
words = count_words(text)
|
||||
sentences = count_sentences(text)
|
||||
return words / sentences if sentences else words
|
||||
|
||||
|
||||
def avg_chars_per_word(text: str) -> float:
|
||||
words = text.split()
|
||||
if not words:
|
||||
return 0
|
||||
return sum(len(w.strip('.,!?;:')) for w in words) / len(words)
|
||||
|
||||
|
||||
def flesch_reading_ease(text: str) -> float:
|
||||
"""
|
||||
Approximate Flesch Reading Ease score.
|
||||
206.835 - 1.015 * (words/sentences) - 84.6 * (syllables/words)
|
||||
We approximate syllables as: max(1, len(word) * 0.4) for each word.
|
||||
"""
|
||||
words = text.split()
|
||||
if not words:
|
||||
return 0
|
||||
sentences = count_sentences(text)
|
||||
syllables = sum(max(1, int(len(re.sub(r'[^aeiouAEIOU]', '', w)) * 1.2) or 1) for w in words)
|
||||
asl = len(words) / sentences # avg sentence length
|
||||
asw = syllables / len(words) # avg syllables per word
|
||||
score = 206.835 - (1.015 * asl) - (84.6 * asw)
|
||||
return max(0, min(100, score))
|
||||
|
||||
|
||||
def grade_reading_level(fre_score: float) -> str:
|
||||
"""Convert Flesch Reading Ease to a human label."""
|
||||
if fre_score >= 70:
|
||||
return "Easy (conversational)"
|
||||
if fre_score >= 60:
|
||||
return "Plain English"
|
||||
if fre_score >= 50:
|
||||
return "Fairly difficult"
|
||||
return "Difficult (too complex for cold email)"
|
||||
|
||||
|
||||
# ─── Analysis functions ───────────────────────────────────────────────────────
|
||||
|
||||
def analyze_subject_line(subject: str) -> Dict:
|
||||
issues = []
|
||||
warnings = []
|
||||
|
||||
if not subject:
|
||||
return {"length": 0, "issues": ["No subject line provided"], "score": 0}
|
||||
|
||||
length = len(subject)
|
||||
|
||||
if length > 60:
|
||||
issues.append(f"Too long ({length} chars) — aim for under 50")
|
||||
if length > 50:
|
||||
warnings.append("Subject is getting long — shorter subjects get more opens")
|
||||
|
||||
if subject.isupper():
|
||||
issues.append("All caps subject lines trigger spam filters")
|
||||
|
||||
if re.search(r'!!!|!{2,}', subject):
|
||||
issues.append("Multiple exclamation points look like spam")
|
||||
|
||||
if subject.startswith("Re:") or subject.startswith("Fwd:"):
|
||||
lower = subject.lower()
|
||||
if lower.startswith("re:") or lower.startswith("fwd:"):
|
||||
warnings.append("Fake Re:/Fwd: subjects feel deceptive — people have learned this trick")
|
||||
|
||||
if re.search(r'[A-Z]{4,}', subject) and not subject.isupper():
|
||||
warnings.append("SHOUTING words in subject lines look like spam")
|
||||
|
||||
if re.search(r'[\U0001F600-\U0001FFFF]', subject):
|
||||
warnings.append("Emojis in subject lines are polarizing and often spam-filtered for B2B")
|
||||
|
||||
if '?' in subject:
|
||||
warnings.append("Question mark in subject can feel like an ad — test without")
|
||||
|
||||
# Spam trigger check in subject
|
||||
subject_lower = subject.lower()
|
||||
triggered = [w for w in SPAM_TRIGGERS if w in subject_lower]
|
||||
if triggered:
|
||||
issues.append(f"Spam trigger words in subject: {', '.join(triggered)}")
|
||||
|
||||
# Score
|
||||
score = 100
|
||||
score -= len(issues) * 20
|
||||
score -= len(warnings) * 10
|
||||
score = max(0, min(100, score))
|
||||
|
||||
return {
|
||||
"length": length,
|
||||
"issues": issues,
|
||||
"warnings": warnings,
|
||||
"score": score,
|
||||
}
|
||||
|
||||
|
||||
def analyze_body(body: str) -> Dict:
|
||||
body_lower = body.lower()
|
||||
findings = []
|
||||
deductions = []
|
||||
|
||||
word_count = count_words(body)
|
||||
fre = flesch_reading_ease(body)
|
||||
reading_level = grade_reading_level(fre)
|
||||
avg_wps = avg_words_per_sentence(body)
|
||||
|
||||
# Word count scoring
|
||||
if word_count > 200:
|
||||
deductions.append(("word_count", 15, f"Too long ({word_count} words) — cold emails should be under 150"))
|
||||
elif word_count > 150:
|
||||
deductions.append(("word_count", 5, f"Getting long ({word_count} words) — aim for under 150"))
|
||||
elif word_count < 30:
|
||||
deductions.append(("word_count", 10, f"Very short ({word_count} words) — may lack enough context"))
|
||||
|
||||
# Sentence length
|
||||
if avg_wps > 25:
|
||||
deductions.append(("readability", 10, f"Sentences average {avg_wps:.0f} words — too complex, aim for 15-20"))
|
||||
|
||||
# Dead opener check
|
||||
for opener in DEAD_OPENERS:
|
||||
if opener in body_lower:
|
||||
deductions.append(("opener", 20, f"Dead opener detected: '{opener}' — rewrite the opening"))
|
||||
break
|
||||
|
||||
# Personalization density
|
||||
pers_matches = 0
|
||||
for pattern in PERSONALIZATION_SIGNALS:
|
||||
matches = re.findall(pattern, body_lower)
|
||||
pers_matches += len(matches)
|
||||
|
||||
pers_density = pers_matches / word_count * 100 if word_count else 0
|
||||
if pers_density < 5:
|
||||
deductions.append(("personalization", 10, "Low personalization signals — email may feel generic"))
|
||||
|
||||
# Spam trigger words in body
|
||||
triggered = [w for w in SPAM_TRIGGERS if w in body_lower]
|
||||
if triggered:
|
||||
deductions.append(("spam", len(triggered) * 5, f"Spam trigger words: {', '.join(triggered[:5])}"))
|
||||
|
||||
# Weak CTA check
|
||||
for weak in WEAK_CTA:
|
||||
if weak in body_lower:
|
||||
deductions.append(("cta", 10, f"Weak CTA: '{weak}' — be more direct"))
|
||||
break
|
||||
|
||||
# Strong CTA check
|
||||
has_strong_cta = any(re.search(p, body_lower) for p in STRONG_CTA_PATTERNS)
|
||||
if not has_strong_cta:
|
||||
deductions.append(("cta", 15, "No clear CTA detected — every cold email needs a single, direct ask"))
|
||||
|
||||
# HTML check
|
||||
if re.search(r'<html|<body|<table|<div|style="|font-family:', body_lower):
|
||||
deductions.append(("format", 20, "HTML detected — plain text emails get better deliverability for cold outreach"))
|
||||
|
||||
# Multiple links
|
||||
links = re.findall(r'https?://', body)
|
||||
if len(links) > 2:
|
||||
deductions.append(("links", 10, f"{len(links)} links detected — keep to 1-2 max for cold email"))
|
||||
|
||||
# Calculate score
|
||||
total_deduction = sum(d[1] for d in deductions)
|
||||
score = max(0, min(100, 100 - total_deduction))
|
||||
|
||||
return {
|
||||
"word_count": word_count,
|
||||
"reading_ease_score": round(fre, 1),
|
||||
"reading_level": reading_level,
|
||||
"avg_words_per_sentence": round(avg_wps, 1),
|
||||
"personalization_density": round(pers_density, 1),
|
||||
"has_strong_cta": has_strong_cta,
|
||||
"spam_triggers": triggered,
|
||||
"deductions": [(d[2], d[1]) for d in deductions],
|
||||
"score": score,
|
||||
}
|
||||
|
||||
|
||||
# ─── Report printer ───────────────────────────────────────────────────────────
|
||||
|
||||
def grade(score: int) -> str:
|
||||
if score >= 85:
|
||||
return "🟢 Strong"
|
||||
if score >= 65:
|
||||
return "🟡 Decent"
|
||||
if score >= 45:
|
||||
return "🟠 Needs work"
|
||||
return "🔴 Rewrite"
|
||||
|
||||
|
||||
def print_report(results: List[Dict]) -> None:
|
||||
print("\n" + "═" * 64)
|
||||
print(" COLD EMAIL SEQUENCE ANALYSIS")
|
||||
print("═" * 64)
|
||||
|
||||
scores = []
|
||||
for r in results:
|
||||
email_num = r["email"]
|
||||
subj = r["subject_analysis"]
|
||||
body = r["body_analysis"]
|
||||
overall = r["overall_score"]
|
||||
scores.append(overall)
|
||||
|
||||
print(f"\n── Email {email_num}: \"{r['subject']}\" ──")
|
||||
print(f" Overall: {overall}/100 {grade(overall)}")
|
||||
|
||||
print(f"\n Subject ({subj['length']} chars): {subj['score']}/100")
|
||||
for issue in subj.get("issues", []):
|
||||
print(f" ❌ {issue}")
|
||||
for warn in subj.get("warnings", []):
|
||||
print(f" ⚠️ {warn}")
|
||||
|
||||
print(f"\n Body Analysis:")
|
||||
print(f" Words: {body['word_count']} | "
|
||||
f"Reading: {body['reading_level']} | "
|
||||
f"Avg sentence: {body['avg_words_per_sentence']} words | "
|
||||
f"Personalization density: {body['personalization_density']}%")
|
||||
print(f" CTA: {'✅ Clear ask detected' if body['has_strong_cta'] else '❌ No clear CTA found'}")
|
||||
|
||||
if body.get("spam_triggers"):
|
||||
print(f" ⚠️ Spam triggers: {', '.join(body['spam_triggers'])}")
|
||||
|
||||
if body.get("deductions"):
|
||||
print(f"\n Issues found:")
|
||||
for desc, pts in body["deductions"]:
|
||||
print(f" [-{pts:2d}] {desc}")
|
||||
|
||||
avg = sum(scores) // len(scores) if scores else 0
|
||||
print(f"\n{'═' * 64}")
|
||||
print(f" SEQUENCE OVERALL: {avg}/100 {grade(avg)}")
|
||||
print(f" Emails analyzed: {len(results)}")
|
||||
|
||||
# Sequence-level observations
|
||||
print("\n Sequence observations:")
|
||||
word_counts = [r["body_analysis"]["word_count"] for r in results]
|
||||
if all(abs(word_counts[i] - word_counts[i-1]) < 20 for i in range(1, len(word_counts))):
|
||||
print(" ⚠️ All emails are similar length — vary length across sequence")
|
||||
|
||||
if len(results) > 1:
|
||||
last_body = results[-1]["body_analysis"]
|
||||
if last_body["word_count"] > 100:
|
||||
print(" ⚠️ Final email (breakup) should be shorter — 3-5 sentences max")
|
||||
|
||||
print("═" * 64 + "\n")
|
||||
|
||||
|
||||
# ─── Sample data ──────────────────────────────────────────────────────────────
|
||||
|
||||
SAMPLE_SEQUENCE = [
|
||||
{
|
||||
"email": 1,
|
||||
"subject": "your SDR team expansion",
|
||||
"body": (
|
||||
"Saw you're hiring four SDRs simultaneously — that's a significant scale-up.\n\n"
|
||||
"The challenge most teams hit at this stage isn't recruiting — it's ramp time. "
|
||||
"When you're adding four people at once, the gaps in your onboarding process "
|
||||
"become very expensive very fast. The average ramp in your segment is around "
|
||||
"4.5 months; the fastest teams we've seen get it to 2.5.\n\n"
|
||||
"We've helped three similar-sized SaaS teams compress that gap. Happy to share "
|
||||
"what worked if it's useful.\n\n"
|
||||
"Worth 15 minutes to compare notes?"
|
||||
),
|
||||
},
|
||||
{
|
||||
"email": 2,
|
||||
"subject": "re: your onboarding stack",
|
||||
"body": (
|
||||
"I hope this email finds you well. I wanted to follow up on my previous email.\n\n"
|
||||
"Just checking in to see if you had a chance to review what I sent. "
|
||||
"As mentioned, our platform offers a comprehensive suite of tools designed to "
|
||||
"help sales teams of all sizes achieve unprecedented growth through our "
|
||||
"revolutionary AI-powered onboarding solution.\n\n"
|
||||
"I'd love to schedule a 45-minute product demo at your earliest convenience. "
|
||||
"Please don't hesitate to reach out if you have any questions. "
|
||||
"I look forward to hearing from you!\n\n"
|
||||
"Click here to book a time: https://calendly.com/example"
|
||||
),
|
||||
},
|
||||
{
|
||||
"email": 3,
|
||||
"subject": "SDR ramp benchmark",
|
||||
"body": (
|
||||
"One data point that might be useful: across the 40 SaaS teams we've benchmarked, "
|
||||
"the ones with the fastest SDR ramp time don't hire the most experienced reps — "
|
||||
"they invest more heavily in structured onboarding in the first 30 days.\n\n"
|
||||
"Happy to share the full breakdown. No catch — just thought it might be relevant "
|
||||
"given where you're headed.\n\n"
|
||||
"Useful?"
|
||||
),
|
||||
},
|
||||
{
|
||||
"email": 4,
|
||||
"subject": "quick question",
|
||||
"body": (
|
||||
"Is SDR onboarding actually a priority right now, or is the timing just off?\n\n"
|
||||
"No judgment either way — just helps me know whether it's worth staying in touch."
|
||||
),
|
||||
},
|
||||
{
|
||||
"email": 5,
|
||||
"subject": "last one",
|
||||
"body": (
|
||||
"I'll stop cluttering your inbox after this one.\n\n"
|
||||
"If scaling your SDR ramp time ever becomes a priority, happy to reconnect — "
|
||||
"just reply here.\n\n"
|
||||
"If there's someone else at your company who owns sales enablement, "
|
||||
"a name would go a long way.\n\n"
|
||||
"Either way, good luck with the expansion."
|
||||
),
|
||||
},
|
||||
]
|
||||
|
||||
|
||||
# ─── Main ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
def main():
|
||||
if len(sys.argv) > 1:
|
||||
arg = sys.argv[1]
|
||||
if arg == "-":
|
||||
sequence = json.load(sys.stdin)
|
||||
else:
|
||||
try:
|
||||
with open(arg, "r", encoding="utf-8") as f:
|
||||
sequence = json.load(f)
|
||||
except FileNotFoundError:
|
||||
print(f"Error: File not found: {arg}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Error: Invalid JSON: {e}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
else:
|
||||
print("No file provided — running on embedded sample sequence.\n")
|
||||
sequence = SAMPLE_SEQUENCE
|
||||
|
||||
results = []
|
||||
for email in sequence:
|
||||
subject = email.get("subject", "")
|
||||
body = email.get("body", "")
|
||||
email_num = email.get("email", len(results) + 1)
|
||||
|
||||
subject_analysis = analyze_subject_line(subject)
|
||||
body_analysis = analyze_body(body)
|
||||
|
||||
# Overall score: 30% subject, 70% body
|
||||
overall = int(subject_analysis["score"] * 0.3 + body_analysis["score"] * 0.7)
|
||||
|
||||
results.append({
|
||||
"email": email_num,
|
||||
"subject": subject,
|
||||
"subject_analysis": subject_analysis,
|
||||
"body_analysis": body_analysis,
|
||||
"overall_score": overall,
|
||||
})
|
||||
|
||||
print_report(results)
|
||||
|
||||
# JSON output for programmatic use
|
||||
summary = {
|
||||
"emails_analyzed": len(results),
|
||||
"average_score": sum(r["overall_score"] for r in results) // len(results) if results else 0,
|
||||
"results": [
|
||||
{
|
||||
"email": r["email"],
|
||||
"subject": r["subject"],
|
||||
"score": r["overall_score"],
|
||||
"word_count": r["body_analysis"]["word_count"],
|
||||
"has_strong_cta": r["body_analysis"]["has_strong_cta"],
|
||||
"spam_triggers": r["body_analysis"]["spam_triggers"],
|
||||
"subject_score": r["subject_analysis"]["score"],
|
||||
}
|
||||
for r in results
|
||||
],
|
||||
}
|
||||
print("── JSON Output ──")
|
||||
print(json.dumps(summary, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
290
marketing-skill/competitor-alternatives/SKILL.md
Normal file
290
marketing-skill/competitor-alternatives/SKILL.md
Normal file
@@ -0,0 +1,290 @@
|
||||
---
|
||||
name: competitor-alternatives
|
||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'switch from competitor,' or 'comparison content.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Competitor & Alternative Pages
|
||||
|
||||
You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before creating competitor pages, understand:
|
||||
|
||||
1. **Your Product**
|
||||
- Core value proposition
|
||||
- Key differentiators
|
||||
- Ideal customer profile
|
||||
- Pricing model
|
||||
- Strengths and honest weaknesses
|
||||
|
||||
2. **Competitive Landscape**
|
||||
- Direct competitors
|
||||
- Indirect/adjacent competitors
|
||||
- Market positioning of each
|
||||
- Search volume for competitor terms
|
||||
|
||||
3. **Goals**
|
||||
- SEO traffic capture
|
||||
- Sales enablement
|
||||
- Conversion from competitor users
|
||||
- Brand positioning
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Honesty Builds Trust
|
||||
- Acknowledge competitor strengths
|
||||
- Be accurate about your limitations
|
||||
- Don't misrepresent competitor features
|
||||
- Readers are comparing—they'll verify claims
|
||||
|
||||
### 2. Depth Over Surface
|
||||
- Go beyond feature checklists
|
||||
- Explain *why* differences matter
|
||||
- Include use cases and scenarios
|
||||
- Show, don't just tell
|
||||
|
||||
### 3. Help Them Decide
|
||||
- Different tools fit different needs
|
||||
- Be clear about who you're best for
|
||||
- Be clear about who competitor is best for
|
||||
- Reduce evaluation friction
|
||||
|
||||
### 4. Modular Content Architecture
|
||||
- Competitor data should be centralized
|
||||
- Updates propagate to all pages
|
||||
- Single source of truth per competitor
|
||||
|
||||
---
|
||||
|
||||
## Page Formats
|
||||
|
||||
### Format 1: [Competitor] Alternative (Singular)
|
||||
|
||||
**Search intent**: User is actively looking to switch from a specific competitor
|
||||
|
||||
**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`
|
||||
|
||||
**Target keywords**: "[Competitor] alternative", "alternative to [Competitor]", "switch from [Competitor]"
|
||||
|
||||
**Page structure**:
|
||||
1. Why people look for alternatives (validate their pain)
|
||||
2. Summary: You as the alternative (quick positioning)
|
||||
3. Detailed comparison (features, service, pricing)
|
||||
4. Who should switch (and who shouldn't)
|
||||
5. Migration path
|
||||
6. Social proof from switchers
|
||||
7. CTA
|
||||
|
||||
---
|
||||
|
||||
### Format 2: [Competitor] Alternatives (Plural)
|
||||
|
||||
**Search intent**: User is researching options, earlier in journey
|
||||
|
||||
**URL pattern**: `/alternatives/[competitor]-alternatives`
|
||||
|
||||
**Target keywords**: "[Competitor] alternatives", "best [Competitor] alternatives", "tools like [Competitor]"
|
||||
|
||||
**Page structure**:
|
||||
1. Why people look for alternatives (common pain points)
|
||||
2. What to look for in an alternative (criteria framework)
|
||||
3. List of alternatives (you first, but include real options)
|
||||
4. Comparison table (summary)
|
||||
5. Detailed breakdown of each alternative
|
||||
6. Recommendation by use case
|
||||
7. CTA
|
||||
|
||||
**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
|
||||
|
||||
---
|
||||
|
||||
### Format 3: You vs [Competitor]
|
||||
|
||||
**Search intent**: User is directly comparing you to a specific competitor
|
||||
|
||||
**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`
|
||||
|
||||
**Target keywords**: "[You] vs [Competitor]", "[Competitor] vs [You]"
|
||||
|
||||
**Page structure**:
|
||||
1. TL;DR summary (key differences in 2-3 sentences)
|
||||
2. At-a-glance comparison table
|
||||
3. Detailed comparison by category (Features, Pricing, Support, Ease of use, Integrations)
|
||||
4. Who [You] is best for
|
||||
5. Who [Competitor] is best for (be honest)
|
||||
6. What customers say (testimonials from switchers)
|
||||
7. Migration support
|
||||
8. CTA
|
||||
|
||||
---
|
||||
|
||||
### Format 4: [Competitor A] vs [Competitor B]
|
||||
|
||||
**Search intent**: User comparing two competitors (not you directly)
|
||||
|
||||
**URL pattern**: `/compare/[competitor-a]-vs-[competitor-b]`
|
||||
|
||||
**Page structure**:
|
||||
1. Overview of both products
|
||||
2. Comparison by category
|
||||
3. Who each is best for
|
||||
4. The third option (introduce yourself)
|
||||
5. Comparison table (all three)
|
||||
6. CTA
|
||||
|
||||
**Why this works**: Captures search traffic for competitor terms, positions you as knowledgeable.
|
||||
|
||||
---
|
||||
|
||||
## Essential Sections
|
||||
|
||||
### TL;DR Summary
|
||||
Start every page with a quick summary for scanners—key differences in 2-3 sentences.
|
||||
|
||||
### Paragraph Comparisons
|
||||
Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.
|
||||
|
||||
### Feature Comparison
|
||||
For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.
|
||||
|
||||
### Pricing Comparison
|
||||
Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.
|
||||
|
||||
### Who It's For
|
||||
Be explicit about ideal customer for each option. Honest recommendations build trust.
|
||||
|
||||
### Migration Section
|
||||
Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.
|
||||
|
||||
**For detailed templates**: See [references/templates.md](references/templates.md)
|
||||
|
||||
---
|
||||
|
||||
## Content Architecture
|
||||
|
||||
### Centralized Competitor Data
|
||||
Create a single source of truth for each competitor with:
|
||||
- Positioning and target audience
|
||||
- Pricing (all tiers)
|
||||
- Feature ratings
|
||||
- Strengths and weaknesses
|
||||
- Best for / not ideal for
|
||||
- Common complaints (from reviews)
|
||||
- Migration notes
|
||||
|
||||
**For data structure and examples**: See [references/content-architecture.md](references/content-architecture.md)
|
||||
|
||||
---
|
||||
|
||||
## Research Process
|
||||
|
||||
### Deep Competitor Research
|
||||
|
||||
For each competitor, gather:
|
||||
|
||||
1. **Product research**: Sign up, use it, document features/UX/limitations
|
||||
2. **Pricing research**: Current pricing, what's included, hidden costs
|
||||
3. **Review mining**: G2, Capterra, TrustRadius for common praise/complaint themes
|
||||
4. **Customer feedback**: Talk to customers who switched (both directions)
|
||||
5. **Content research**: Their positioning, their comparison pages, their changelog
|
||||
|
||||
### Ongoing Updates
|
||||
|
||||
- **Quarterly**: Verify pricing, check for major feature changes
|
||||
- **When notified**: Customer mentions competitor change
|
||||
- **Annually**: Full refresh of all competitor data
|
||||
|
||||
---
|
||||
|
||||
## SEO Considerations
|
||||
|
||||
### Keyword Targeting
|
||||
|
||||
| Format | Primary Keywords |
|
||||
|--------|-----------------|
|
||||
| Alternative (singular) | [Competitor] alternative, alternative to [Competitor] |
|
||||
| Alternatives (plural) | [Competitor] alternatives, best [Competitor] alternatives |
|
||||
| You vs Competitor | [You] vs [Competitor], [Competitor] vs [You] |
|
||||
| Competitor vs Competitor | [A] vs [B], [B] vs [A] |
|
||||
|
||||
### Internal Linking
|
||||
- Link between related competitor pages
|
||||
- Link from feature pages to relevant comparisons
|
||||
- Create hub page linking to all competitor content
|
||||
|
||||
### Schema Markup
|
||||
Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Competitor Data File
|
||||
Complete competitor profile in YAML format for use across all comparison pages.
|
||||
|
||||
### Page Content
|
||||
For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.
|
||||
|
||||
### Page Set Plan
|
||||
Recommended pages to create with priority order based on search volume.
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What are common reasons people switch to you?
|
||||
2. Do you have customer quotes about switching?
|
||||
3. What's your pricing vs. competitors?
|
||||
4. Do you offer migration support?
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Proactively offer competitor page creation when:
|
||||
|
||||
1. **Competitor mentioned in conversation** — Any time a specific competitor is named, ask if comparison or alternative pages exist; if not, offer to create a page set.
|
||||
2. **Sales team friction** — User mentions prospects comparing them to a specific tool; immediately offer a vs-page for sales enablement.
|
||||
3. **SEO gap identified** — Keyword research shows competitor-branded terms with no coverage; propose a full alternative page set with prioritized build order.
|
||||
4. **Switcher testimonial available** — When a customer quote about switching surfaces, offer to build a migration-focused alternative page around it.
|
||||
5. **Pricing page review** — When reviewing pricing, note that pricing comparison tables belong on dedicated competitor pages, not the pricing page itself.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Artifact | Format | Description |
|
||||
|----------|--------|-------------|
|
||||
| Competitor Intelligence File | YAML data file | Centralized competitor profile: pricing, features, weaknesses, review themes |
|
||||
| Page Set Plan | Prioritized list | Ranked list of pages to build with target keywords and search volume estimates |
|
||||
| Alternative Page (Singular) | Full page copy | Complete `/[competitor]-alternative` page with all sections |
|
||||
| Vs Page | Full page copy | Complete `/vs/[competitor]` page with comparison table and CTA |
|
||||
| Migration Guide Section | Markdown block | Reusable migration copy for inclusion across multiple pages |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All competitor page outputs should be factually accurate, legally safe (no false claims), and fair to competitors. Acknowledge genuine competitor strengths — pages that only disparage competitors lose credibility with evaluators. Reference `marketing-context` for ICP and positioning before writing any comparison copy. Quality bar: every claim must be verifiable from public sources or customer quotes.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **seo-audit** — USE to validate that competitor pages meet on-page SEO requirements before publishing; NOT as a replacement for the keyword strategy built here.
|
||||
- **copywriting** — USE for writing the narrative sections and CTAs on comparison pages; NOT when the task is purely competitor research and architecture.
|
||||
- **content-strategy** — USE when planning a full competitive content program across multiple pages; NOT for single-page execution.
|
||||
- **competitive-intel** — USE when C-level strategic competitive analysis is needed beyond page creation; NOT for tactical page writing.
|
||||
- **marketing-context** — USE as foundation before any competitor page work to align positioning; always load first.
|
||||
@@ -0,0 +1,263 @@
|
||||
# Content Architecture for Competitor Pages
|
||||
|
||||
How to structure and maintain competitor data for scalable comparison pages.
|
||||
|
||||
## Centralized Competitor Data
|
||||
|
||||
Create a single source of truth for each competitor:
|
||||
|
||||
```
|
||||
competitor_data/
|
||||
├── notion.md
|
||||
├── airtable.md
|
||||
├── monday.md
|
||||
└── ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Competitor Data Template
|
||||
|
||||
Per competitor, document:
|
||||
|
||||
```yaml
|
||||
name: Notion
|
||||
website: notion.so
|
||||
tagline: "The all-in-one workspace"
|
||||
founded: 2016
|
||||
headquarters: San Francisco
|
||||
|
||||
# Positioning
|
||||
primary_use_case: "docs + light databases"
|
||||
target_audience: "teams wanting flexible workspace"
|
||||
market_position: "premium, feature-rich"
|
||||
|
||||
# Pricing
|
||||
pricing_model: per-seat
|
||||
free_tier: true
|
||||
free_tier_limits: "limited blocks, 1 user"
|
||||
starter_price: $8/user/month
|
||||
business_price: $15/user/month
|
||||
enterprise: custom
|
||||
|
||||
# Features (rate 1-5 or describe)
|
||||
features:
|
||||
documents: 5
|
||||
databases: 4
|
||||
project_management: 3
|
||||
collaboration: 4
|
||||
integrations: 3
|
||||
mobile_app: 3
|
||||
offline_mode: 2
|
||||
api: 4
|
||||
|
||||
# Strengths (be honest)
|
||||
strengths:
|
||||
- Extremely flexible and customizable
|
||||
- Beautiful, modern interface
|
||||
- Strong template ecosystem
|
||||
- Active community
|
||||
|
||||
# Weaknesses (be fair)
|
||||
weaknesses:
|
||||
- Can be slow with large databases
|
||||
- Learning curve for advanced features
|
||||
- Limited automations compared to dedicated tools
|
||||
- Offline mode is limited
|
||||
|
||||
# Best for
|
||||
best_for:
|
||||
- Teams wanting all-in-one workspace
|
||||
- Content-heavy workflows
|
||||
- Documentation-first teams
|
||||
- Startups and small teams
|
||||
|
||||
# Not ideal for
|
||||
not_ideal_for:
|
||||
- Complex project management needs
|
||||
- Large databases (1000s of rows)
|
||||
- Teams needing robust offline
|
||||
- Enterprise with strict compliance
|
||||
|
||||
# Common complaints (from reviews)
|
||||
common_complaints:
|
||||
- "Gets slow with lots of content"
|
||||
- "Hard to find things as workspace grows"
|
||||
- "Mobile app is clunky"
|
||||
|
||||
# Migration notes
|
||||
migration_from:
|
||||
difficulty: medium
|
||||
data_export: "Markdown, CSV, HTML"
|
||||
what_transfers: "Pages, databases"
|
||||
what_doesnt: "Automations, integrations setup"
|
||||
time_estimate: "1-3 days for small team"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Your Product Data
|
||||
|
||||
Same structure for yourself—be honest:
|
||||
|
||||
```yaml
|
||||
name: [Your Product]
|
||||
# ... same fields
|
||||
|
||||
strengths:
|
||||
- [Your real strengths]
|
||||
|
||||
weaknesses:
|
||||
- [Your honest weaknesses]
|
||||
|
||||
best_for:
|
||||
- [Your ideal customers]
|
||||
|
||||
not_ideal_for:
|
||||
- [Who should use something else]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Page Generation
|
||||
|
||||
Each page pulls from centralized data:
|
||||
|
||||
- **[Competitor] Alternative page**: Pulls competitor data + your data
|
||||
- **[Competitor] Alternatives page**: Pulls competitor data + your data + other alternatives
|
||||
- **You vs [Competitor] page**: Pulls your data + competitor data
|
||||
- **[A] vs [B] page**: Pulls both competitor data + your data
|
||||
|
||||
**Benefits**:
|
||||
- Update competitor pricing once, updates everywhere
|
||||
- Add new feature comparison once, appears on all pages
|
||||
- Consistent accuracy across pages
|
||||
- Easier to maintain at scale
|
||||
|
||||
---
|
||||
|
||||
## Index Page Structure
|
||||
|
||||
### Alternatives Index
|
||||
|
||||
**URL**: `/alternatives` or `/alternatives/index`
|
||||
|
||||
**Purpose**: Lists all "[Competitor] Alternative" pages
|
||||
|
||||
**Page structure**:
|
||||
1. Headline: "[Your Product] as an Alternative"
|
||||
2. Brief intro on why people switch to you
|
||||
3. List of all alternative pages with:
|
||||
- Competitor name/logo
|
||||
- One-line summary of key differentiator vs. that competitor
|
||||
- Link to full comparison
|
||||
4. Common reasons people switch (aggregated)
|
||||
5. CTA
|
||||
|
||||
**Example**:
|
||||
```markdown
|
||||
## Explore [Your Product] as an Alternative
|
||||
|
||||
Looking to switch? See how [Your Product] compares to the tools you're evaluating:
|
||||
|
||||
- **[Notion Alternative](/alternatives/notion)** — Better for teams who need [X]
|
||||
- **[Airtable Alternative](/alternatives/airtable)** — Better for teams who need [Y]
|
||||
- **[Monday Alternative](/alternatives/monday)** — Better for teams who need [Z]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Vs Comparisons Index
|
||||
|
||||
**URL**: `/vs` or `/compare`
|
||||
|
||||
**Purpose**: Lists all "You vs [Competitor]" and "[A] vs [B]" pages
|
||||
|
||||
**Page structure**:
|
||||
1. Headline: "Compare [Your Product]"
|
||||
2. Section: "[Your Product] vs Competitors" — list of direct comparisons
|
||||
3. Section: "Head-to-Head Comparisons" — list of [A] vs [B] pages
|
||||
4. Brief methodology note
|
||||
5. CTA
|
||||
|
||||
---
|
||||
|
||||
### Index Page Best Practices
|
||||
|
||||
**Keep them updated**: When you add a new comparison page, add it to the relevant index.
|
||||
|
||||
**Internal linking**:
|
||||
- Link from index → individual pages
|
||||
- Link from individual pages → back to index
|
||||
- Cross-link between related comparisons
|
||||
|
||||
**SEO value**:
|
||||
- Index pages can rank for broad terms like "project management tool comparisons"
|
||||
- Pass link equity to individual comparison pages
|
||||
- Help search engines discover all comparison content
|
||||
|
||||
**Sorting options**:
|
||||
- By popularity (search volume)
|
||||
- Alphabetically
|
||||
- By category/use case
|
||||
- By date added (show freshness)
|
||||
|
||||
**Include on index pages**:
|
||||
- Last updated date for credibility
|
||||
- Number of pages/comparisons available
|
||||
- Quick filters if you have many comparisons
|
||||
|
||||
---
|
||||
|
||||
## Footer Navigation
|
||||
|
||||
The site footer appears on all marketing pages, making it a powerful internal linking opportunity for competitor pages.
|
||||
|
||||
### Option 1: Link to Index Pages (Minimum)
|
||||
|
||||
At minimum, add links to your comparison index pages in the footer:
|
||||
|
||||
```
|
||||
Footer
|
||||
├── Compare
|
||||
│ ├── Alternatives → /alternatives
|
||||
│ └── Comparisons → /vs
|
||||
```
|
||||
|
||||
This ensures every marketing page passes link equity to your comparison content hub.
|
||||
|
||||
### Option 2: Footer Columns by Format (Recommended for SEO)
|
||||
|
||||
For stronger internal linking, create dedicated footer columns for each format you've built, linking directly to your top competitors:
|
||||
|
||||
```
|
||||
Footer
|
||||
├── [Product] vs ├── Alternatives to ├── Compare
|
||||
│ ├── vs Notion │ ├── Notion Alternative │ ├── Notion vs Airtable
|
||||
│ ├── vs Airtable │ ├── Airtable Alternative │ ├── Monday vs Asana
|
||||
│ ├── vs Monday │ ├── Monday Alternative │ ├── Notion vs Monday
|
||||
│ ├── vs Asana │ ├── Asana Alternative │ ├── ...
|
||||
│ ├── vs Clickup │ ├── Clickup Alternative │ └── View all →
|
||||
│ ├── ... │ ├── ... │
|
||||
│ └── View all → │ └── View all → │
|
||||
```
|
||||
|
||||
**Guidelines**:
|
||||
- Include up to 8 links per column (top competitors by search volume)
|
||||
- Add "View all" link to the full index page
|
||||
- Only create columns for formats you've actually built pages for
|
||||
- Prioritize competitors with highest search volume
|
||||
|
||||
### Why Footer Links Matter
|
||||
|
||||
1. **Sitewide distribution**: Footer links appear on every marketing page, passing link equity from your entire site to comparison content
|
||||
2. **Crawl efficiency**: Search engines discover all comparison pages quickly
|
||||
3. **User discovery**: Visitors evaluating your product can easily find comparisons
|
||||
4. **Competitive positioning**: Signals to search engines that you're a key player in the space
|
||||
|
||||
### Implementation Notes
|
||||
|
||||
- Update footer when adding new high-priority comparison pages
|
||||
- Keep footer clean—don't list every comparison, just the top ones
|
||||
- Match column headers to your URL structure (e.g., "vs" column → `/vs/` URLs)
|
||||
- Consider mobile: columns may stack, so order by priority
|
||||
212
marketing-skill/competitor-alternatives/references/templates.md
Normal file
212
marketing-skill/competitor-alternatives/references/templates.md
Normal file
@@ -0,0 +1,212 @@
|
||||
# Section Templates for Competitor Pages
|
||||
|
||||
Ready-to-use templates for each section of competitor comparison pages.
|
||||
|
||||
## TL;DR Summary
|
||||
|
||||
Start every page with a quick summary for scanners:
|
||||
|
||||
```markdown
|
||||
**TL;DR**: [Competitor] excels at [strength] but struggles with [weakness].
|
||||
[Your product] is built for [your focus], offering [key differentiator].
|
||||
Choose [Competitor] if [their ideal use case]. Choose [You] if [your ideal use case].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Paragraph Comparison (Not Just Tables)
|
||||
|
||||
For each major dimension, write a paragraph:
|
||||
|
||||
```markdown
|
||||
## Features
|
||||
|
||||
[Competitor] offers [description of their feature approach].
|
||||
Their strength is [specific strength], which works well for [use case].
|
||||
However, [limitation] can be challenging for [user type].
|
||||
|
||||
[Your product] takes a different approach with [your approach].
|
||||
This means [benefit], though [honest tradeoff].
|
||||
Teams who [specific need] often find this more effective.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Feature Comparison Section
|
||||
|
||||
Go beyond checkmarks:
|
||||
|
||||
```markdown
|
||||
## Feature Comparison
|
||||
|
||||
### [Feature Category]
|
||||
|
||||
**[Competitor]**: [2-3 sentence description of how they handle this]
|
||||
- Strengths: [specific]
|
||||
- Limitations: [specific]
|
||||
|
||||
**[Your product]**: [2-3 sentence description]
|
||||
- Strengths: [specific]
|
||||
- Limitations: [specific]
|
||||
|
||||
**Bottom line**: Choose [Competitor] if [scenario]. Choose [You] if [scenario].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pricing Comparison Section
|
||||
|
||||
```markdown
|
||||
## Pricing
|
||||
|
||||
| | [Competitor] | [Your Product] |
|
||||
|---|---|---|
|
||||
| Free tier | [Details] | [Details] |
|
||||
| Starting price | $X/user/mo | $X/user/mo |
|
||||
| Business tier | $X/user/mo | $X/user/mo |
|
||||
| Enterprise | Custom | Custom |
|
||||
|
||||
**What's included**: [Competitor]'s $X plan includes [features], while
|
||||
[Your product]'s $X plan includes [features].
|
||||
|
||||
**Total cost consideration**: Beyond per-seat pricing, consider [hidden costs,
|
||||
add-ons, implementation]. [Competitor] charges extra for [X], while
|
||||
[Your product] includes [Y] in base pricing.
|
||||
|
||||
**Value comparison**: For a 10-person team, [Competitor] costs approximately
|
||||
$X/year while [Your product] costs $Y/year, with [key differences in what you get].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Service & Support Comparison
|
||||
|
||||
```markdown
|
||||
## Service & Support
|
||||
|
||||
| | [Competitor] | [Your Product] |
|
||||
|---|---|---|
|
||||
| Documentation | [Quality assessment] | [Quality assessment] |
|
||||
| Response time | [SLA if known] | [Your SLA] |
|
||||
| Support channels | [List] | [List] |
|
||||
| Onboarding | [What they offer] | [What you offer] |
|
||||
| CSM included | [At what tier] | [At what tier] |
|
||||
|
||||
**Support quality**: Based on [G2/Capterra reviews, your research],
|
||||
[Competitor] support is described as [assessment]. Common feedback includes
|
||||
[quotes or themes].
|
||||
|
||||
[Your product] offers [your support approach]. [Specific differentiator like
|
||||
response time, dedicated CSM, implementation help].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Who It's For Section
|
||||
|
||||
```markdown
|
||||
## Who Should Choose [Competitor]
|
||||
|
||||
[Competitor] is the right choice if:
|
||||
- [Specific use case or need]
|
||||
- [Team type or size]
|
||||
- [Workflow or requirement]
|
||||
- [Budget or priority]
|
||||
|
||||
**Ideal [Competitor] customer**: [Persona description in 1-2 sentences]
|
||||
|
||||
## Who Should Choose [Your Product]
|
||||
|
||||
[Your product] is built for teams who:
|
||||
- [Specific use case or need]
|
||||
- [Team type or size]
|
||||
- [Workflow or requirement]
|
||||
- [Priority or value]
|
||||
|
||||
**Ideal [Your product] customer**: [Persona description in 1-2 sentences]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Migration Section
|
||||
|
||||
```markdown
|
||||
## Switching from [Competitor]
|
||||
|
||||
### What transfers
|
||||
- [Data type]: [How easily, any caveats]
|
||||
- [Data type]: [How easily, any caveats]
|
||||
|
||||
### What needs reconfiguration
|
||||
- [Thing]: [Why and effort level]
|
||||
- [Thing]: [Why and effort level]
|
||||
|
||||
### Migration support
|
||||
|
||||
We offer [migration support details]:
|
||||
- [Free data import tool / white-glove migration]
|
||||
- [Documentation / migration guide]
|
||||
- [Timeline expectation]
|
||||
- [Support during transition]
|
||||
|
||||
### What customers say about switching
|
||||
|
||||
> "[Quote from customer who switched]"
|
||||
> — [Name], [Role] at [Company]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Social Proof Section
|
||||
|
||||
Focus on switchers:
|
||||
|
||||
```markdown
|
||||
## What Customers Say
|
||||
|
||||
### Switched from [Competitor]
|
||||
|
||||
> "[Specific quote about why they switched and outcome]"
|
||||
> — [Name], [Role] at [Company]
|
||||
|
||||
> "[Another quote]"
|
||||
> — [Name], [Role] at [Company]
|
||||
|
||||
### Results after switching
|
||||
- [Company] saw [specific result]
|
||||
- [Company] reduced [metric] by [amount]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison Table Best Practices
|
||||
|
||||
### Beyond Checkmarks
|
||||
|
||||
Instead of:
|
||||
| Feature | You | Competitor |
|
||||
|---------|-----|-----------|
|
||||
| Feature A | ✓ | ✓ |
|
||||
| Feature B | ✓ | ✗ |
|
||||
|
||||
Do this:
|
||||
| Feature | You | Competitor |
|
||||
|---------|-----|-----------|
|
||||
| Feature A | Full support with [detail] | Basic support, [limitation] |
|
||||
| Feature B | [Specific capability] | Not available |
|
||||
|
||||
### Organize by Category
|
||||
|
||||
Group features into meaningful categories:
|
||||
- Core functionality
|
||||
- Collaboration
|
||||
- Integrations
|
||||
- Security & compliance
|
||||
- Support & service
|
||||
|
||||
### Include Ratings Where Useful
|
||||
|
||||
| Category | You | Competitor | Notes |
|
||||
|----------|-----|-----------|-------|
|
||||
| Ease of use | ⭐⭐⭐⭐⭐ | ⭐⭐⭐⭐ | [Brief note] |
|
||||
| Feature depth | ⭐⭐⭐⭐ | ⭐⭐⭐⭐⭐ | [Brief note] |
|
||||
@@ -0,0 +1,365 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
comparison_matrix_builder.py — Competitive Feature Comparison Matrix Builder
|
||||
100% stdlib, no pip installs required.
|
||||
|
||||
Usage:
|
||||
python3 comparison_matrix_builder.py # demo mode
|
||||
python3 comparison_matrix_builder.py --input matrix.json
|
||||
python3 comparison_matrix_builder.py --input matrix.json --json
|
||||
python3 comparison_matrix_builder.py --input matrix.json --markdown > comparison.md
|
||||
|
||||
matrix.json format:
|
||||
{
|
||||
"your_product": "YourProduct",
|
||||
"features": [
|
||||
{
|
||||
"name": "SSO / SAML",
|
||||
"category": "Security",
|
||||
"your_status": "full", # full | partial | no | planned
|
||||
"competitors": {
|
||||
"CompetitorA": "no",
|
||||
"CompetitorB": "partial",
|
||||
"CompetitorC": "full"
|
||||
},
|
||||
"notes": "Enterprise tier only" # optional
|
||||
}
|
||||
]
|
||||
}
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Status helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
STATUS_SCORE = {
|
||||
"full": 2,
|
||||
"partial": 1,
|
||||
"no": 0,
|
||||
"planned": 0, # planned ≠ shipped; conservative scoring
|
||||
}
|
||||
|
||||
STATUS_LABEL = {
|
||||
"full": "✅",
|
||||
"partial": "🔶",
|
||||
"no": "❌",
|
||||
"planned": "🗓",
|
||||
}
|
||||
|
||||
STATUS_TEXT = {
|
||||
"full": "Full",
|
||||
"partial": "Partial",
|
||||
"no": "No",
|
||||
"planned": "Planned",
|
||||
}
|
||||
|
||||
FEATURE_IMPORTANCE = {
|
||||
# Generic defaults — override per-feature with "weight" in JSON
|
||||
"default": 1,
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Core builder
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def normalise_status(s: str) -> str:
|
||||
s = (s or "no").strip().lower()
|
||||
return s if s in STATUS_SCORE else "no"
|
||||
|
||||
|
||||
def build_matrix(data: dict) -> dict:
|
||||
your_product = data.get("your_product", "Your Product")
|
||||
features = data.get("features", [])
|
||||
|
||||
if not features:
|
||||
raise ValueError("No features provided in input.")
|
||||
|
||||
# Collect competitor names (ordered, deduplicated)
|
||||
competitors = []
|
||||
seen = set()
|
||||
for f in features:
|
||||
for c in f.get("competitors", {}):
|
||||
if c not in seen:
|
||||
competitors.append(c)
|
||||
seen.add(c)
|
||||
|
||||
categories = sorted(set(f.get("category", "General") for f in features))
|
||||
|
||||
# --- per-feature analysis ---
|
||||
feature_rows = []
|
||||
for f in features:
|
||||
fname = f.get("name", "?")
|
||||
category = f.get("category", "General")
|
||||
weight = f.get("weight", 1)
|
||||
your_raw = normalise_status(f.get("your_status", "no"))
|
||||
your_s = STATUS_SCORE[your_raw]
|
||||
comp_raw = {c: normalise_status(f.get("competitors", {}).get(c, "no"))
|
||||
for c in competitors}
|
||||
comp_s = {c: STATUS_SCORE[comp_raw[c]] for c in competitors}
|
||||
|
||||
you_win = all(your_s > comp_s[c] for c in competitors) if competitors else False
|
||||
you_lose = any(your_s < comp_s[c] for c in competitors)
|
||||
your_max = max(comp_s.values()) if comp_s else 0
|
||||
advantage = your_s - your_max # positive = you're better overall
|
||||
|
||||
feature_rows.append({
|
||||
"name": fname,
|
||||
"category": category,
|
||||
"weight": weight,
|
||||
"your_status": your_raw,
|
||||
"your_score": your_s,
|
||||
"competitors": comp_raw,
|
||||
"comp_scores": comp_s,
|
||||
"you_win": you_win,
|
||||
"you_lose": you_lose,
|
||||
"advantage": advantage,
|
||||
"notes": f.get("notes", ""),
|
||||
})
|
||||
|
||||
# --- competitive scores per competitor ---
|
||||
comp_scores = {}
|
||||
for c in competitors:
|
||||
wins = sum(1 for r in feature_rows if r["your_score"] > r["comp_scores"].get(c, 0))
|
||||
ties = sum(1 for r in feature_rows if r["your_score"] == r["comp_scores"].get(c, 0))
|
||||
losses = sum(1 for r in feature_rows if r["your_score"] < r["comp_scores"].get(c, 0))
|
||||
total = len(feature_rows)
|
||||
score = round((wins / total) * 100) if total else 0
|
||||
comp_scores[c] = {
|
||||
"wins": wins, "ties": ties, "losses": losses,
|
||||
"win_pct": score,
|
||||
"verdict": _verdict(score),
|
||||
}
|
||||
|
||||
# Overall competitive score (average win% across all competitors)
|
||||
overall_win_pct = (
|
||||
round(sum(v["win_pct"] for v in comp_scores.values()) / len(comp_scores))
|
||||
if comp_scores else 0
|
||||
)
|
||||
|
||||
# Advantages and gaps
|
||||
advantages = [r["name"] for r in feature_rows if r["advantage"] > 0]
|
||||
gaps = [r["name"] for r in feature_rows if r["advantage"] < 0]
|
||||
parity = [r["name"] for r in feature_rows if r["advantage"] == 0]
|
||||
|
||||
return {
|
||||
"meta": {
|
||||
"your_product": your_product,
|
||||
"competitors": competitors,
|
||||
"categories": categories,
|
||||
"total_features": len(feature_rows),
|
||||
"overall_win_pct": overall_win_pct,
|
||||
"verdict": _verdict(overall_win_pct),
|
||||
},
|
||||
"competitor_scores": comp_scores,
|
||||
"advantages": advantages,
|
||||
"gaps": gaps,
|
||||
"parity": parity,
|
||||
"features": feature_rows,
|
||||
}
|
||||
|
||||
|
||||
def _verdict(win_pct: int) -> str:
|
||||
if win_pct >= 70: return "Strong advantage"
|
||||
if win_pct >= 50: return "Slight advantage"
|
||||
if win_pct >= 35: return "Competitive parity"
|
||||
return "Trailing"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Markdown output
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def build_markdown(result: dict) -> str:
|
||||
m = result["meta"]
|
||||
rows = result["features"]
|
||||
comp = m["competitors"]
|
||||
|
||||
lines = []
|
||||
lines.append(f"# Feature Comparison: {m['your_product']} vs Competitors\n")
|
||||
lines.append(f"_Generated by comparison_matrix_builder.py — {m['total_features']} features, "
|
||||
f"{len(comp)} competitor(s)_\n")
|
||||
|
||||
# Summary table
|
||||
lines.append("## Competitive Score Summary\n")
|
||||
lines.append("| Competitor | You Win | Tie | You Lose | Win % | Verdict |")
|
||||
lines.append("|---|---|---|---|---|---|")
|
||||
for c, s in result["competitor_scores"].items():
|
||||
lines.append(f"| {c} | {s['wins']} | {s['ties']} | {s['losses']} | "
|
||||
f"**{s['win_pct']}%** | {s['verdict']} |")
|
||||
lines.append(f"\n**Overall win rate: {m['overall_win_pct']}% — {m['verdict']}**\n")
|
||||
|
||||
# Feature matrix by category
|
||||
lines.append("## Feature Matrix\n")
|
||||
header = f"| Feature | {m['your_product']} | " + " | ".join(comp) + " | Notes |"
|
||||
sep = "|---|---|" + "|".join(["---"] * len(comp)) + "|---|"
|
||||
lines.append(header)
|
||||
lines.append(sep)
|
||||
|
||||
current_cat = None
|
||||
for r in rows:
|
||||
cat = r["category"]
|
||||
if cat != current_cat:
|
||||
lines.append(f"| **{cat}** | | " + " | ".join([""] * len(comp)) + " | |")
|
||||
current_cat = cat
|
||||
you_icon = STATUS_LABEL[r["your_status"]]
|
||||
comp_icons = " | ".join(STATUS_LABEL[r["competitors"].get(c, "no")] for c in comp)
|
||||
note = r["notes"] or ""
|
||||
# Highlight row if it's a unique advantage
|
||||
fname = f"**{r['name']}**" if r["advantage"] > 0 else r["name"]
|
||||
lines.append(f"| {fname} | {you_icon} | {comp_icons} | {note} |")
|
||||
|
||||
lines.append("")
|
||||
|
||||
# Advantages
|
||||
if result["advantages"]:
|
||||
lines.append("## ✅ Your Advantages\n")
|
||||
for a in result["advantages"]:
|
||||
lines.append(f"- {a}")
|
||||
lines.append("")
|
||||
|
||||
# Gaps
|
||||
if result["gaps"]:
|
||||
lines.append("## ⚠️ Feature Gaps (competitors ahead)\n")
|
||||
for g in result["gaps"]:
|
||||
lines.append(f"- {g}")
|
||||
lines.append("")
|
||||
|
||||
# Legend
|
||||
lines.append("## Legend\n")
|
||||
for k, v in STATUS_LABEL.items():
|
||||
lines.append(f"- {v} {STATUS_TEXT[k]}")
|
||||
lines.append("")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Pretty terminal output
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def pretty_print(result: dict) -> None:
|
||||
m = result["meta"]
|
||||
print("\n" + "=" * 70)
|
||||
print(f" COMPETITIVE MATRIX: {m['your_product'].upper()} vs {', '.join(m['competitors'])}")
|
||||
print("=" * 70)
|
||||
print(f"\n Total features analysed : {m['total_features']}")
|
||||
print(f" Overall win rate : {m['overall_win_pct']}% ({m['verdict']})")
|
||||
|
||||
print(f"\n{'─'*70}")
|
||||
print(f" {'COMPETITOR':<22} {'WIN%':>5} {'WINS':>5} {'TIES':>5} {'LOSSES':>7} VERDICT")
|
||||
print(f"{'─'*70}")
|
||||
for c, s in result["competitor_scores"].items():
|
||||
bar = "█" * (s["win_pct"] // 10) + "░" * (10 - s["win_pct"] // 10)
|
||||
print(f" {c:<22} {s['win_pct']:>4}% {s['wins']:>5} {s['ties']:>5} "
|
||||
f"{s['losses']:>7} {bar} {s['verdict']}")
|
||||
|
||||
print(f"\n{'─'*70}")
|
||||
col_w = 20
|
||||
header = f" {'FEATURE':<28} | {'YOU':^8}"
|
||||
for c in m["competitors"]:
|
||||
header += f" | {c[:8]:^8}"
|
||||
print(header)
|
||||
print("─" * (30 + 11 * (1 + len(m["competitors"]))))
|
||||
|
||||
current_cat = None
|
||||
for r in result["features"]:
|
||||
if r["category"] != current_cat:
|
||||
print(f"\n [{r['category']}]")
|
||||
current_cat = r["category"]
|
||||
you_icon = STATUS_LABEL[r["your_status"]]
|
||||
line = f" {' '+r['name']:<28} | {you_icon:^8}"
|
||||
for c in m["competitors"]:
|
||||
ci = STATUS_LABEL[r["competitors"].get(c, "no")]
|
||||
line += f" | {ci:^8}"
|
||||
if r["advantage"] > 0:
|
||||
line += " ← advantage"
|
||||
elif r["advantage"] < 0:
|
||||
line += " ← gap"
|
||||
print(line)
|
||||
|
||||
print(f"\n ✅ YOUR ADVANTAGES ({len(result['advantages'])} features)")
|
||||
for a in result["advantages"]:
|
||||
print(f" • {a}")
|
||||
|
||||
print(f"\n ⚠️ FEATURE GAPS ({len(result['gaps'])} features)")
|
||||
for g in result["gaps"]:
|
||||
print(f" • {g}")
|
||||
|
||||
print(f"\n Legend: {STATUS_LABEL['full']} Full {STATUS_LABEL['partial']} Partial "
|
||||
f"{STATUS_LABEL['no']} No {STATUS_LABEL['planned']} Planned\n")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Sample data
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
DEMO_DATA = {
|
||||
"your_product": "SwiftBase",
|
||||
"features": [
|
||||
{"name": "SSO / SAML", "category": "Security", "weight": 3, "your_status": "full", "competitors": {"AcmeSaaS": "no", "ProStack": "partial"}, "notes": "All plans"},
|
||||
{"name": "2FA / MFA", "category": "Security", "weight": 3, "your_status": "full", "competitors": {"AcmeSaaS": "full", "ProStack": "full"}, "notes": ""},
|
||||
{"name": "SOC 2 Type II", "category": "Security", "weight": 3, "your_status": "planned", "competitors": {"AcmeSaaS": "full", "ProStack": "no"}, "notes": "Q3 target"},
|
||||
{"name": "Role-based access", "category": "Security", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "partial", "ProStack": "full"}, "notes": ""},
|
||||
{"name": "REST API", "category": "Integrations", "weight": 3, "your_status": "full", "competitors": {"AcmeSaaS": "full", "ProStack": "full"}, "notes": ""},
|
||||
{"name": "GraphQL API", "category": "Integrations", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "no", "ProStack": "partial"}, "notes": ""},
|
||||
{"name": "Zapier Integration", "category": "Integrations", "weight": 2, "your_status": "partial", "competitors": {"AcmeSaaS": "full", "ProStack": "full"}, "notes": "10 zaps only"},
|
||||
{"name": "Webhooks", "category": "Integrations", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "full", "ProStack": "no"}, "notes": ""},
|
||||
{"name": "Custom domain", "category": "Branding", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "partial", "ProStack": "full"}, "notes": ""},
|
||||
{"name": "White-label / rebrand","category": "Branding", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "no", "ProStack": "partial"}, "notes": "Agency plan"},
|
||||
{"name": "Priority support", "category": "Support", "weight": 2, "your_status": "full", "competitors": {"AcmeSaaS": "partial", "ProStack": "full"}, "notes": "24/7"},
|
||||
{"name": "Dedicated CSM", "category": "Support", "weight": 2, "your_status": "no", "competitors": {"AcmeSaaS": "full", "ProStack": "full"}, "notes": "Enterprise only"},
|
||||
{"name": "SLA guarantee", "category": "Support", "weight": 3, "your_status": "no", "competitors": {"AcmeSaaS": "full", "ProStack": "no"}, "notes": "Roadmap"},
|
||||
],
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# CLI
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def parse_args():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Build a competitive feature comparison matrix (stdlib only).",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog=__doc__,
|
||||
)
|
||||
parser.add_argument("--input", type=str, default=None,
|
||||
help="Path to JSON input file")
|
||||
parser.add_argument("--json", action="store_true",
|
||||
help="Output analysis as JSON")
|
||||
parser.add_argument("--markdown", action="store_true",
|
||||
help="Output comparison table as Markdown")
|
||||
return parser.parse_args()
|
||||
|
||||
|
||||
def main():
|
||||
args = parse_args()
|
||||
|
||||
if args.input:
|
||||
with open(args.input) as f:
|
||||
data = json.load(f)
|
||||
else:
|
||||
print("🔬 DEMO MODE — using sample SaaS product matrix\n", file=sys.stderr)
|
||||
data = DEMO_DATA
|
||||
|
||||
result = build_matrix(data)
|
||||
|
||||
if args.json:
|
||||
# Serialise (remove non-JSON-safe keys)
|
||||
print(json.dumps(result, indent=2))
|
||||
elif args.markdown:
|
||||
print(build_markdown(result))
|
||||
else:
|
||||
pretty_print(result)
|
||||
print("\n💡 TIP: Re-run with --markdown to get a copyable Markdown table.\n")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -1,303 +1,55 @@
|
||||
---
|
||||
name: content-creator
|
||||
description: Create SEO-optimized marketing content with consistent brand voice. Includes brand voice analyzer, SEO optimizer, content frameworks, and social media templates. Use when writing blog posts, creating social media content, analyzing brand voice, optimizing SEO, planning content calendars, or when user mentions content creation, brand voice, SEO optimization, social media marketing, or content strategy.
|
||||
description: "DEPRECATED — Use content-production for full content pipeline, or content-strategy for planning. This skill redirects to the appropriate specialist."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
domain: content-marketing
|
||||
updated: 2025-10-20
|
||||
python-tools: brand_voice_analyzer.py, seo_optimizer.py
|
||||
tech-stack: SEO, social-media-platforms
|
||||
updated: 2026-03-06
|
||||
status: deprecated
|
||||
---
|
||||
|
||||
# Content Creator
|
||||
# Content Creator → Redirected
|
||||
|
||||
Professional-grade brand voice analysis, SEO optimization, and platform-specific content frameworks.
|
||||
> **This skill has been split into two specialist skills.** Use the one that matches your intent:
|
||||
|
||||
---
|
||||
| You want to... | Use this instead |
|
||||
|----------------|-----------------|
|
||||
| **Write** a blog post, article, or guide | [content-production](../content-production/) |
|
||||
| **Plan** what content to create, topic clusters, calendar | [content-strategy](../content-strategy/) |
|
||||
| **Analyze brand voice** | [content-production](../content-production/) (includes `brand_voice_analyzer.py`) |
|
||||
| **Optimize SEO** for existing content | [content-production](../content-production/) (includes `seo_optimizer.py`) |
|
||||
| **Create social media content** | [social-content](../social-content/) |
|
||||
|
||||
## Table of Contents
|
||||
## Why the Change
|
||||
|
||||
- [Keywords](#keywords)
|
||||
- [Quick Start](#quick-start)
|
||||
- [Core Workflows](#core-workflows)
|
||||
- [Tools](#tools)
|
||||
- [Reference Guides](#reference-guides)
|
||||
- [Best Practices](#best-practices)
|
||||
- [Integration Points](#integration-points)
|
||||
The original `content-creator` tried to do everything: planning, writing, SEO, social, brand voice. That made it a jack of all trades. The specialist skills do each job better:
|
||||
|
||||
---
|
||||
- **content-production** — Full pipeline: research → brief → draft → optimize → publish. Includes all Python tools from the original content-creator.
|
||||
- **content-strategy** — Strategic planning: topic clusters, keyword research, content calendars, prioritization frameworks.
|
||||
|
||||
## Keywords
|
||||
## Proactive Triggers
|
||||
|
||||
content creation, blog posts, SEO, brand voice, social media, content calendar, marketing content, content strategy, content marketing, brand consistency, content optimization, social media marketing, content planning, blog writing, content frameworks, brand guidelines, social media strategy
|
||||
- **User asks "content creator"** → Route to content-production (most likely intent is writing).
|
||||
- **User asks "content plan" or "what should I write"** → Route to content-strategy.
|
||||
|
||||
---
|
||||
## Output Artifacts
|
||||
|
||||
## Quick Start
|
||||
| When you ask for... | Routed to... |
|
||||
|---------------------|-------------|
|
||||
| "Write a blog post" | content-production |
|
||||
| "Content calendar" | content-strategy |
|
||||
| "Brand voice analysis" | content-production (`brand_voice_analyzer.py`) |
|
||||
| "SEO optimization" | content-production (`seo_optimizer.py`) |
|
||||
|
||||
### Brand Voice Development
|
||||
## Communication
|
||||
|
||||
1. Run `scripts/brand_voice_analyzer.py` on existing content to establish baseline
|
||||
2. Review `references/brand_guidelines.md` to select voice attributes
|
||||
3. Apply chosen voice consistently across all content
|
||||
This is a redirect skill. Route the user to the correct specialist — don't attempt to handle the request here.
|
||||
|
||||
### Blog Content Creation
|
||||
## Related Skills
|
||||
|
||||
1. Choose template from `references/content_frameworks.md`
|
||||
2. Research keywords for topic
|
||||
3. Write content following template structure
|
||||
4. Run `scripts/seo_optimizer.py [file] [primary-keyword]` to optimize
|
||||
5. Apply recommendations before publishing
|
||||
|
||||
### Social Media Content
|
||||
|
||||
1. Review platform best practices in `references/social_media_optimization.md`
|
||||
2. Use appropriate template from `references/content_frameworks.md`
|
||||
3. Optimize based on platform-specific guidelines
|
||||
4. Schedule using `assets/content_calendar_template.md`
|
||||
|
||||
---
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Workflow 1: Establish Brand Voice (First Time Setup)
|
||||
|
||||
For new brands or clients:
|
||||
|
||||
**Step 1: Analyze Existing Content (if available)**
|
||||
|
||||
```bash
|
||||
python scripts/brand_voice_analyzer.py existing_content.txt
|
||||
```
|
||||
|
||||
**Step 2: Define Voice Attributes**
|
||||
|
||||
- Review brand personality archetypes in `references/brand_guidelines.md`
|
||||
- Select primary and secondary archetypes
|
||||
- Choose 3-5 tone attributes
|
||||
- Document in brand guidelines
|
||||
|
||||
**Step 3: Create Voice Sample**
|
||||
|
||||
- Write 3 sample pieces in chosen voice
|
||||
- Test consistency using analyzer
|
||||
- Refine based on results
|
||||
|
||||
### Workflow 2: Create SEO-Optimized Blog Posts
|
||||
|
||||
**Step 1: Keyword Research**
|
||||
|
||||
- Identify primary keyword (search volume 500-5000/month)
|
||||
- Find 3-5 secondary keywords
|
||||
- List 10-15 LSI keywords
|
||||
|
||||
**Step 2: Content Structure**
|
||||
|
||||
- Use blog template from `references/content_frameworks.md`
|
||||
- Include keyword in title, first paragraph, and 2-3 H2s
|
||||
- Aim for 1,500-2,500 words for comprehensive coverage
|
||||
|
||||
**Step 3: Optimization Check**
|
||||
|
||||
```bash
|
||||
python scripts/seo_optimizer.py blog_post.md "primary keyword" "secondary,keywords,list"
|
||||
```
|
||||
|
||||
**Step 4: Apply SEO Recommendations**
|
||||
|
||||
- Adjust keyword density to 1-3%
|
||||
- Ensure proper heading structure
|
||||
- Add internal and external links
|
||||
- Optimize meta description
|
||||
|
||||
### Workflow 3: Create Social Media Content
|
||||
|
||||
**Step 1: Platform Selection**
|
||||
|
||||
- Identify primary platforms based on audience
|
||||
- Review platform-specific guidelines in `references/social_media_optimization.md`
|
||||
|
||||
**Step 2: Content Adaptation**
|
||||
|
||||
- Start with blog post or core message
|
||||
- Use repurposing matrix from `references/content_frameworks.md`
|
||||
- Adapt for each platform following templates
|
||||
|
||||
**Step 3: Optimization Checklist**
|
||||
|
||||
- Platform-appropriate length
|
||||
- Optimal posting time
|
||||
- Correct image dimensions
|
||||
- Platform-specific hashtags
|
||||
- Engagement elements (polls, questions)
|
||||
|
||||
### Workflow 4: Plan Content Calendar
|
||||
|
||||
**Step 1: Monthly Planning**
|
||||
|
||||
- Copy `assets/content_calendar_template.md`
|
||||
- Set monthly goals and KPIs
|
||||
- Identify key campaigns/themes
|
||||
|
||||
**Step 2: Weekly Distribution**
|
||||
|
||||
- Follow 40/25/25/10 content pillar ratio
|
||||
- Balance platforms throughout week
|
||||
- Align with optimal posting times
|
||||
|
||||
**Step 3: Batch Creation**
|
||||
|
||||
- Create all weekly content in one session
|
||||
- Maintain consistent voice across pieces
|
||||
- Prepare all visual assets together
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
### Brand Voice Analyzer
|
||||
|
||||
Analyzes text content for voice characteristics, readability, and consistency.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Human-readable output
|
||||
python scripts/brand_voice_analyzer.py content.txt
|
||||
|
||||
# JSON output for integrations
|
||||
python scripts/brand_voice_analyzer.py content.txt json
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `file` | Yes | Path to content file |
|
||||
| `format` | No | Output format: `text` (default) or `json` |
|
||||
|
||||
**Output:**
|
||||
|
||||
- Voice profile (formality, tone, perspective)
|
||||
- Readability score (Flesch Reading Ease)
|
||||
- Sentence structure analysis
|
||||
- Improvement recommendations
|
||||
|
||||
### SEO Optimizer
|
||||
|
||||
Analyzes content for SEO optimization and provides actionable recommendations.
|
||||
|
||||
**Usage:**
|
||||
|
||||
```bash
|
||||
# Basic analysis
|
||||
python scripts/seo_optimizer.py article.md "main keyword"
|
||||
|
||||
# With secondary keywords
|
||||
python scripts/seo_optimizer.py article.md "main keyword" "secondary,keywords,list"
|
||||
|
||||
# JSON output
|
||||
python scripts/seo_optimizer.py article.md "keyword" --json
|
||||
```
|
||||
|
||||
**Parameters:**
|
||||
|
||||
| Parameter | Required | Description |
|
||||
|-----------|----------|-------------|
|
||||
| `file` | Yes | Path to content file (md or html) |
|
||||
| `primary_keyword` | Yes | Main target keyword |
|
||||
| `secondary_keywords` | No | Comma-separated secondary keywords |
|
||||
| `--json` | No | Output in JSON format |
|
||||
|
||||
**Output:**
|
||||
|
||||
- SEO score (0-100)
|
||||
- Keyword density analysis
|
||||
- Structure assessment
|
||||
- Meta tag suggestions
|
||||
- Specific optimization recommendations
|
||||
|
||||
---
|
||||
|
||||
## Reference Guides
|
||||
|
||||
### When to Use Each Reference
|
||||
|
||||
**references/brand_guidelines.md**
|
||||
|
||||
- Setting up new brand voice
|
||||
- Ensuring consistency across content
|
||||
- Training new team members
|
||||
- Resolving voice/tone questions
|
||||
|
||||
**references/content_frameworks.md**
|
||||
|
||||
- Starting any new content piece
|
||||
- Structuring different content types
|
||||
- Creating content templates
|
||||
- Planning content repurposing
|
||||
|
||||
**references/social_media_optimization.md**
|
||||
|
||||
- Platform-specific optimization
|
||||
- Hashtag strategy development
|
||||
- Understanding algorithm factors
|
||||
- Setting up analytics tracking
|
||||
|
||||
**references/analytics_guide.md**
|
||||
|
||||
- Tracking content performance
|
||||
- Setting up measurement frameworks
|
||||
- Creating performance reports
|
||||
- Attribution modeling
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Content Creation Process
|
||||
|
||||
1. Start with audience need/pain point
|
||||
2. Research before writing
|
||||
3. Create outline using templates
|
||||
4. Write first draft without editing
|
||||
5. Optimize for SEO
|
||||
6. Edit for brand voice
|
||||
7. Proofread and fact-check
|
||||
8. Optimize for platform
|
||||
9. Schedule strategically
|
||||
|
||||
### Quality Indicators
|
||||
|
||||
- SEO score above 75/100
|
||||
- Readability appropriate for audience
|
||||
- Consistent brand voice throughout
|
||||
- Clear value proposition
|
||||
- Actionable takeaways
|
||||
- Proper visual formatting
|
||||
- Platform-optimized
|
||||
|
||||
### Common Pitfalls to Avoid
|
||||
|
||||
- Writing before researching keywords
|
||||
- Ignoring platform-specific requirements
|
||||
- Inconsistent brand voice
|
||||
- Over-optimizing for SEO (keyword stuffing)
|
||||
- Missing clear CTAs
|
||||
- Publishing without proofreading
|
||||
- Ignoring analytics feedback
|
||||
|
||||
---
|
||||
|
||||
## Integration Points
|
||||
|
||||
This skill works best with:
|
||||
|
||||
- **Analytics platforms** - Google Analytics, social media insights for tracking (see `references/analytics_guide.md`)
|
||||
- **SEO tools** - For keyword research and competitive analysis
|
||||
- **Design tools** - Canva, Figma for visual content
|
||||
- **Scheduling platforms** - Buffer, Hootsuite for content distribution
|
||||
- **Email marketing systems** - For newsletter content campaigns
|
||||
- **content-production**: Full content execution pipeline (successor).
|
||||
- **content-strategy**: Content planning and topic selection (successor).
|
||||
- **content-humanizer**: Post-processing AI content to sound authentic.
|
||||
- **marketing-context**: Foundation context that both successors read.
|
||||
|
||||
261
marketing-skill/content-humanizer/SKILL.md
Normal file
261
marketing-skill/content-humanizer/SKILL.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
name: content-humanizer
|
||||
description: "Makes AI-generated content sound genuinely human — not just cleaned up, but alive. Use when content feels robotic, uses too many AI clichés, lacks personality, or reads like it was written by committee. Triggers: 'this sounds like AI', 'make it more human', 'add personality', 'it feels generic', 'sounds robotic', 'fix AI writing', 'inject our voice'. NOT for initial content creation (use content-production). NOT for SEO optimization (use content-production Mode 3)."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Content Humanizer
|
||||
|
||||
You are an expert in authentic writing and brand voice. Your goal is to transform content that reads like it was generated by a machine — even when it technically was — into writing that sounds like a real person with real opinions, real experience, and real stakes in what they're saying.
|
||||
|
||||
This is not a cleaning service. You're not just removing "delve" and calling it a day. You're rebuilding the voice from the ground up.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it. It contains brand voice guidelines, writing examples, and the specific tone this brand uses. That context is your voice blueprint. Use it — don't improvise a voice when the brief already defines one.
|
||||
|
||||
Gather what you need before starting:
|
||||
|
||||
### What you need
|
||||
- **The content** — paste the draft to humanize
|
||||
- **Brand voice notes** — if no `marketing-context.md`, ask: "Is your voice direct/casual/technical/irreverent? Give me one example of writing you love."
|
||||
- **Audience** — who reads this? (This changes what "human" sounds like)
|
||||
- **Goal** — what should this piece do? (Knowing the goal tells you how much personality is appropriate)
|
||||
|
||||
One question if needed: "Before I rewrite this, give me an example of content you've written or read that felt right. Specific is better than descriptive."
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
Three modes. Run them in sequence for a full transformation, or jump to the one you need:
|
||||
|
||||
### Mode 1: Detect — AI Pattern Analysis
|
||||
Audit the content for AI tells. Name what's wrong and why before fixing anything. This is diagnostic — not editorial.
|
||||
|
||||
### Mode 2: Humanize — Pattern Removal and Rhythm Fix
|
||||
Strip the AI patterns. Fix sentence rhythm. Replace generic with specific. The content starts sounding like a person.
|
||||
|
||||
### Mode 3: Voice Injection — Brand Character
|
||||
Now that the generic is gone, inject the brand's specific personality. This is where "human" becomes *your brand's* human.
|
||||
|
||||
Run all three in one pass when you have enough context. Split them when the client needs to see the audit before you edit.
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Detect — AI Pattern Analysis
|
||||
|
||||
Scan the content for these categories. Score severity: 🔴 critical (kills credibility) / 🟡 medium (softens impact) / 🟢 minor (polish only).
|
||||
|
||||
See [references/ai-tells-checklist.md](references/ai-tells-checklist.md) for the comprehensive detection list.
|
||||
|
||||
### The Core AI Tell Categories
|
||||
|
||||
**1. Overused Filler Words** 🔴
|
||||
The model loves certain words because they appear frequently in its training data. Flag these on sight:
|
||||
- "delve," "delve into," "delve deeper"
|
||||
- "landscape" (as in "the current AI landscape")
|
||||
- "crucial," "vital," "pivotal"
|
||||
- "leverage" (when "use" works fine)
|
||||
- "furthermore," "moreover," "in addition"
|
||||
- "navigate" (metaphorical: "navigate this challenge")
|
||||
- "robust," "comprehensive," "holistic"
|
||||
- "foster," "facilitate," "ensure"
|
||||
|
||||
**2. Hedging Chains** 🔴
|
||||
AI hedges constantly. It hedges because it doesn't know if it's right. Humans hedge sometimes — but not in every sentence.
|
||||
- "It's important to note that..."
|
||||
- "It's worth mentioning that..."
|
||||
- "One might argue that..."
|
||||
- "In many cases," "In most scenarios,"
|
||||
- "It goes without saying..."
|
||||
- "Needless to say..."
|
||||
|
||||
**3. Em-Dash Overuse** 🟡
|
||||
One or two em-dashes in a piece: fine. Em-dash in every other paragraph: AI fingerprint. The model uses em-dashes to add clauses the way humans add breath — but it does it compulsively.
|
||||
|
||||
**4. Identical Paragraph Structure** 🔴
|
||||
Every paragraph: topic sentence → explanation → example → bridge to next. AI is remarkably consistent. Remarkably boring. Real writing has short paragraphs. Fragments. Asides. Digressions. Then it snaps back. The structure varies.
|
||||
|
||||
**5. Lack of Specificity** 🔴
|
||||
AI replaces specific claims with vague ones because specific claims can be wrong. Look for:
|
||||
- "Many companies" → which companies?
|
||||
- "Studies show" → which studies?
|
||||
- "Significantly improved" → improved by how much?
|
||||
- "Leading brands" → name one
|
||||
- "A lot of" → how many?
|
||||
|
||||
**6. False Certainty / False Authority** 🟡
|
||||
AI asserts confidently about things no one can be certain about. "Companies that do X are more successful." According to what? This isn't humility — it's laziness dressed as confidence.
|
||||
|
||||
**7. The "In conclusion" Paragraph** 🟡
|
||||
AI conclusions are often carbon copies of the intro. "In this article, we explored X, Y, and Z. By implementing these strategies, you can achieve..." No human concludes like this. Real conclusions either add something new or nail the exit line.
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Humanize — Pattern Removal and Rhythm Fix
|
||||
|
||||
After identifying what's wrong, fix it systematically.
|
||||
|
||||
### Replace Filler Words
|
||||
|
||||
**Rule:** Never just delete — always replace with something better.
|
||||
|
||||
| AI phrase | Human alternative |
|
||||
|---|---|
|
||||
| "delve into" | "look at," "dig into," "break down," or just: "here's what matters" |
|
||||
| "the [X] landscape" | "how [X] works today," "the current state of [X]" |
|
||||
| "leverage" | "use," "apply," "put to work" |
|
||||
| "crucial" / "vital" | "the part that actually matters," "the one thing," or just state the thing — let it be self-evidently important |
|
||||
| "furthermore" | nothing (just start the next sentence), or "and," or "also" |
|
||||
| "robust" | specific: "handles 10,000 requests/sec," "covers 47 edge cases" |
|
||||
| "facilitate" | "help," "make easier," "allow" |
|
||||
| "navigate this challenge" | "handle this," "deal with this," "get through this" |
|
||||
|
||||
### Fix Sentence Rhythm
|
||||
|
||||
**The problem:** AI produces uniform sentence length. Every sentence is 18-22 words. The ear goes numb.
|
||||
|
||||
**The fix:** Deliberate variation. Read aloud. Then:
|
||||
- Break long sentences into two
|
||||
- Add a short sentence after a long one. Like this.
|
||||
- Use fragments where they serve emphasis. Especially for emphasis.
|
||||
- Let some sentences run longer when the thought needs to unwind and the reader has the context to follow it
|
||||
|
||||
**Rhythm patterns that feel human:**
|
||||
- Long. Short. Long, long. Short.
|
||||
- Question? Answer. Proof.
|
||||
- Claim. Specific example. So what?
|
||||
|
||||
### Replace Generic with Specific
|
||||
|
||||
Every vague claim is an invitation to doubt. Replace:
|
||||
|
||||
**Before:** "Many companies have seen significant improvements by implementing this strategy."
|
||||
|
||||
**After:** "HubSpot published their onboarding funnel data in 2023 — companies that hit their first-value moment within 7 days showed 40% higher 90-day retention. That's not a rounding error."
|
||||
|
||||
If you don't have specific data, be honest: "I haven't seen controlled studies on this, but in my experience working with SaaS onboarding flows, the pattern is consistent: earlier activation = higher retention."
|
||||
|
||||
Personal experience beats vague authority. Every time.
|
||||
|
||||
### Vary Paragraph Structure
|
||||
|
||||
Break the uniform SEEB pattern (Statement → Explanation → Example → Bridge):
|
||||
|
||||
- **Single-sentence paragraph:** Use it. Emphasis needs air.
|
||||
- **Question paragraph:** Pose a question. Then answer it.
|
||||
- **List in the middle:** Drop a quick list when there are genuinely 3-5 parallel items. Then return to prose.
|
||||
- **Aside / parenthetical paragraph:** A small digression that reveals personality. (Readers actually like these. It's the equivalent of a raised eyebrow mid-sentence.)
|
||||
- **Confession:** "I got this wrong the first time." Instantly human.
|
||||
|
||||
### Add Friction and Imperfection
|
||||
|
||||
AI writing is too smooth. Too complete. Real people:
|
||||
- Change direction mid-thought and acknowledge it: "Actually, let me back up..."
|
||||
- Qualify things they're uncertain about without hiding the uncertainty
|
||||
- Have opinions that might be wrong: "I might be wrong about this, but..."
|
||||
- Notice things and say so: "What's interesting here is..."
|
||||
- React: "Which, if you've ever tried to debug this, you know is maddening."
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Voice Injection — Brand Character
|
||||
|
||||
Humanizing removes AI. Voice injection makes it *yours*.
|
||||
|
||||
### Read the Voice Blueprint First
|
||||
|
||||
If `marketing-context.md` is available: read the brand voice section and writing examples. If not, ask for one example of content this brand loves. One. Then extract the patterns from it.
|
||||
|
||||
**What to extract from a voice example:**
|
||||
- Sentence length preference (short punchy vs. longer flowing?)
|
||||
- Formality level (contractions? slang? industry jargon?)
|
||||
- Use of humor (dry wit? self-deprecating? none?)
|
||||
- Relationship stance (peer-to-peer? expert-to-student? provocateur?)
|
||||
- Signature phrases or patterns
|
||||
|
||||
See [references/voice-techniques.md](references/voice-techniques.md) for specific techniques for each voice type.
|
||||
|
||||
### Voice Injection Techniques
|
||||
|
||||
**1. Personal Anecdotes**
|
||||
Even branded content gets more credible when grounded in experience. "We saw this firsthand when building X" is worth more than any study citation.
|
||||
|
||||
**2. Direct Address**
|
||||
Talk to the reader as "you." Not "users" or "teams" or "organizations." You.
|
||||
|
||||
**3. Opinions Without Apology**
|
||||
State your position. "We think the industry is wrong about this" is more credible than "there are various perspectives." Take the side.
|
||||
|
||||
**4. The Aside**
|
||||
A brief parenthetical that shows the brand knows more than it's saying. "This also affects API performance, but that's a separate rabbit hole."
|
||||
|
||||
**5. Rhythm Signature**
|
||||
Every brand has a rhythm. Some write in short staccato bursts. Some write long, winding sentences that spiral back on themselves. Find the rhythm from the examples and apply it consistently.
|
||||
|
||||
### Before / After Example
|
||||
|
||||
**Before (AI-generated):**
|
||||
> It is crucial to leverage your existing customer data in order to effectively navigate the competitive landscape. Furthermore, by implementing a robust onboarding strategy, organizations can ensure that users achieve maximum value from the product and reduce churn significantly.
|
||||
|
||||
**After (humanized):**
|
||||
> Here's the thing nobody says out loud: most SaaS companies have the data to fix their churn problem. They just don't look at it until after customers leave.
|
||||
>
|
||||
> Your activation funnel is in there. Your best cohorts, your worst, the moment the drop-off happens. You don't need another tool — you need someone to stop ignoring what the tool is already showing you.
|
||||
>
|
||||
> Nail onboarding first. Everything else is downstream.
|
||||
|
||||
What changed:
|
||||
- Removed: "crucial," "leverage," "navigate," "robust," "ensure," "significantly," "furthermore"
|
||||
- Added: direct address, specific accusation ("what the tool is already showing you"), short-sentence punch at the end
|
||||
- Changed: passive recommendations → active point of view
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Flag these without being asked:
|
||||
|
||||
- **AI fingerprint density too high** — If the piece has 10+ AI tells per 500 words, a patch job won't work. Flag that the piece needs a full rewrite, not an edit. Trying to polish a piece that's 80% AI patterns produces AI patterns with nicer words.
|
||||
- **Voice context missing** — If `marketing-context.md` doesn't exist and the user hasn't given voice guidance, pause before injecting voice. Ask for one example. Guessing the voice and being wrong wastes everyone's time.
|
||||
- **Specificity gap** — If the piece makes 5+ vague claims with zero data or attribution, flag it to the user. You can make the prose flow better, but you can't invent specific proof. They need to provide it.
|
||||
- **Tone mismatch after humanizing** — If the piece is now genuinely human but sounds like a different brand than everything else the client publishes, flag it. Consistency matters as much as quality.
|
||||
- **Over-editing risk** — If the original content has one or two genuinely good paragraphs buried in the AI mush, flag them before rewriting. Don't accidentally destroy the good parts.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---|---|
|
||||
| AI audit | Annotated version of the draft with each AI pattern flagged, severity score, and count by category |
|
||||
| Humanized draft | Full rewrite with AI patterns removed, rhythm varied, specificity improved |
|
||||
| Voice injection | Annotated draft with brand voice applied — specific changes called out so you can learn the pattern |
|
||||
| Before/after comparison | Side-by-side view of key paragraphs showing what changed and why |
|
||||
| Humanity score | Run `scripts/humanizer_scorer.py` — 0-100 score with breakdown by signal type |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding includes all three
|
||||
- **Actions have owners and deadlines** — no "you might want to consider"
|
||||
- **Confidence tagging** — 🟢 verified pattern / 🟡 medium / 🔴 assumed based on limited voice context
|
||||
|
||||
When auditing: name the pattern → explain why it reads as AI → give the specific fix. Not "this sounds robotic." Say: "Paragraph 4 opens with 'It is important to note that' — this is a pure hedge. Cut it. Start with the actual note."
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **content-production**: Use to produce the initial draft. Run content-humanizer after drafting, before the SEO optimization pass.
|
||||
- **copywriting**: Use for conversion copy — landing pages, CTAs, headlines. content-humanizer works on longer-form pieces; copywriting handles short punchy copy with different principles.
|
||||
- **content-strategy**: Use when deciding what content to create. NOT for voice or draft execution.
|
||||
- **ai-seo**: Use after humanizing, to optimize for AI search citation. Human-sounding content gets cited more — but it still needs structure to get extracted.
|
||||
@@ -0,0 +1,157 @@
|
||||
# AI Tells Checklist
|
||||
|
||||
A comprehensive reference for detecting AI-generated or AI-assisted writing patterns. Use this during Mode 1 (Detect) to audit content before editing.
|
||||
|
||||
Rate each finding: 🔴 Critical (rewrites required) / 🟡 Medium (edits needed) / 🟢 Minor (polish)
|
||||
|
||||
---
|
||||
|
||||
## Category 1: Overused Vocabulary
|
||||
|
||||
These words appear in AI output at 5-20x the frequency of human writing. One instance is fine. Multiple instances in a single piece is a tell.
|
||||
|
||||
### Red-flag verbs (overused)
|
||||
| Word | Problem | What humans say instead |
|
||||
|---|---|---|
|
||||
| delve / delve into | Pretentious filler | look at, dig into, explore, examine |
|
||||
| leverage | Jargon for "use" | use, apply, put to work, capitalize on |
|
||||
| foster | Formal filler | build, develop, encourage, create |
|
||||
| facilitate | Bureaucratic filler | help, make easier, allow, support |
|
||||
| navigate | Overused metaphor | handle, manage, work through, deal with |
|
||||
| ensure | Empty guarantee | check that, make sure, verify |
|
||||
| utilize | Formal for "use" | just say "use" |
|
||||
| prioritize | Often redundant | just say what to do first |
|
||||
| streamline | Vague improvement promise | be specific about what gets faster/easier |
|
||||
|
||||
### Red-flag adjectives (overused)
|
||||
| Word | Problem | What humans say instead |
|
||||
|---|---|---|
|
||||
| crucial / vital / pivotal | Overloaded intensifiers | just show why it matters |
|
||||
| robust | Vague positive | specific: "handles X load," "covers Y cases" |
|
||||
| comprehensive | Overpromise | specific: "covers the 5 most common..." |
|
||||
| innovative | Meaningless | say what it actually does differently |
|
||||
| holistic | Buzzword | say what it covers |
|
||||
| seamless | Overused product adjective | describe the actual experience |
|
||||
| cutting-edge | Dated marketing | say what's new or different specifically |
|
||||
| dynamic | Filler adjective | usually just delete it |
|
||||
|
||||
### Red-flag nouns (overused)
|
||||
| Word | Problem | What humans say instead |
|
||||
|---|---|---|
|
||||
| landscape | Overused metaphor | "how X works today," "the state of X" |
|
||||
| ecosystem | Overused for "industry" or "community" | be specific |
|
||||
| framework | Often vague | name the specific framework or approach |
|
||||
| paradigm | Academic filler | usually replaceable with "approach" or "way of thinking" |
|
||||
| synergy | Corporate cliché | delete or replace with what actually happens |
|
||||
|
||||
---
|
||||
|
||||
## Category 2: Hedging and Qualification Patterns
|
||||
|
||||
Humans hedge. AI hedges compulsively. The difference is frequency and context.
|
||||
|
||||
### Opening hedges (usually safe to cut)
|
||||
- "It's important to note that..."
|
||||
- "It's worth mentioning that..."
|
||||
- "It should be noted that..."
|
||||
- "Needless to say..."
|
||||
- "It goes without saying..."
|
||||
- "Of course, ..."
|
||||
- "Naturally, ..."
|
||||
|
||||
### Mid-sentence hedges (examine each)
|
||||
- "In many cases" / "In most instances" / "In certain scenarios"
|
||||
- "Generally speaking," / "For the most part,"
|
||||
- "This may vary depending on..."
|
||||
- "Results may differ based on..."
|
||||
- "While this isn't always the case..."
|
||||
|
||||
**Diagnostic:** If the hedge is protecting a claim that should just be a claim, cut the hedge and state the claim. If the hedge reflects genuine uncertainty, keep it — but make the uncertainty specific: "I don't have data for this, but based on [context]..."
|
||||
|
||||
### Vague authority claims (replace with specifics)
|
||||
- "Studies show..." → "A 2023 McKinsey study of 400 SaaS companies showed..."
|
||||
- "Research suggests..." → same — name the research
|
||||
- "Many companies..." → "HubSpot, Slack, and several bootstrapped SaaS founders we've talked to..."
|
||||
- "Experts agree..." → name one expert
|
||||
- "It has been shown that..." → by whom, when, where
|
||||
|
||||
---
|
||||
|
||||
## Category 3: Structural Patterns
|
||||
|
||||
### The SEEB paragraph (most common)
|
||||
Pattern: Statement → Explanation → Example → Bridge to next topic
|
||||
When every paragraph follows this exact structure, the writing reads like a machine assembled it. Because it was.
|
||||
|
||||
**Fix:** Mix in fragments. Questions. Short paragraphs. Asides. Let sections breathe differently.
|
||||
|
||||
### Parallelism overload
|
||||
AI loves parallel structure. Three-item lists. Four-item lists. Everything in threes. Alliteration sometimes.
|
||||
|
||||
Occasional parallelism is powerful. Three consecutive bulleted lists of three items each is a tell.
|
||||
|
||||
**Fix:** Break the rhythm. Some sections need bullets. Most don't.
|
||||
|
||||
### The summary conclusion
|
||||
AI conclusions restate the introduction. Paragraph by paragraph. "In this guide, we covered X, Y, and Z. By applying these strategies, you can achieve [thing from the intro]."
|
||||
|
||||
Human conclusions either add something (a new angle, an honest admission, a call to action that feels earned) or they nail the exit line and stop.
|
||||
|
||||
### Symmetric section lengths
|
||||
Every H2 section is roughly the same length. ~300 words. Every one. That's a machine maintaining consistency. Humans have opinions — some things deserve more space, some less.
|
||||
|
||||
---
|
||||
|
||||
## Category 4: Punctuation and Formatting Tells
|
||||
|
||||
### Em-dash frequency 🟡
|
||||
One or two em-dashes per piece: fine. Three per page: suspicion. Five+: AI fingerprint.
|
||||
|
||||
The em-dash is AI's favorite way to add subordinate clauses — like this — because it sounds sophisticated — and it learned this from a lot of well-written text — so now it can't stop.
|
||||
|
||||
**Fix:** Replace most with periods. Break into shorter sentences.
|
||||
|
||||
### Colon-then-list patterns 🟢
|
||||
AI frequently: introduces a list: with: colons. Multiple times per section. Lists are useful. But if every section has a colon-introducing list, it's mechanical.
|
||||
|
||||
### Excessive bold 🟢
|
||||
AI sometimes bolds every important-sounding phrase in a paragraph. **This results** in **too many** phrases being **highlighted for emphasis** when the emphasis **dilutes itself**.
|
||||
|
||||
Bold should be used sparingly — for the one thing that matters most in a section, not for three to five things per paragraph.
|
||||
|
||||
---
|
||||
|
||||
## Category 5: Tonal Tells
|
||||
|
||||
### False warmth 🟡
|
||||
"We hope this guide has been helpful in your journey to..."
|
||||
"We trust that you've found valuable insights in..."
|
||||
"It's our sincere hope that these strategies will empower you to..."
|
||||
|
||||
No one talks like this. It's the corporate newsletter voice. Cut it.
|
||||
|
||||
### Emotional escalation without basis 🟡
|
||||
AI sometimes starts clinical and then, near the end, gets unexpectedly warm and inspirational. "Now that you have these tools, you can transform your business and achieve your goals." The warmth wasn't earned by the preceding content.
|
||||
|
||||
### Artificial enthusiasm 🟢
|
||||
"Exciting developments," "fascinating case study," "incredible opportunity" — used to simulate human engagement. Usually reads as hollow because it's disconnected from actual content that earns those descriptors.
|
||||
|
||||
---
|
||||
|
||||
## Quick Audit Scoring
|
||||
|
||||
For a 1,000-word piece, count:
|
||||
|
||||
| Signal | Count | Severity Threshold |
|
||||
|---|---|---|
|
||||
| Red-flag vocabulary words | | >5 = 🔴 |
|
||||
| Opening hedges | | >2 = 🔴 |
|
||||
| Vague authority claims ("studies show") | | >2 = 🔴 |
|
||||
| Em-dashes | | >4 = 🟡 |
|
||||
| SEEB paragraphs (all follow same structure) | | >60% of paragraphs = 🔴 |
|
||||
| Instances of false warmth | | >1 = 🟡 |
|
||||
|
||||
**Scoring:**
|
||||
- 0-5 total flags: Light edit (Mode 2 quick pass)
|
||||
- 6-12 total flags: Full humanize pass (Mode 2 complete)
|
||||
- 12+ total flags: Full rewrite recommended (Mode 1 audit → complete Mode 2 → Mode 3)
|
||||
168
marketing-skill/content-humanizer/references/voice-techniques.md
Normal file
168
marketing-skill/content-humanizer/references/voice-techniques.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# Voice Techniques Reference
|
||||
|
||||
Techniques for injecting authentic brand voice into content. This is the Mode 3 playbook — after you've removed AI patterns (Mode 2), these techniques put the brand's specific personality in.
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Extract the Voice Profile
|
||||
|
||||
Before writing anything, extract the voice from examples. Ask for one piece of content the brand considers representative. Then answer these questions about it:
|
||||
|
||||
| Question | What to look for |
|
||||
|---|---|
|
||||
| Average sentence length? | Count words per sentence across 10 sentences. ≤15 = punchy. ≥25 = flowing. |
|
||||
| Formality level? | Count contractions ("it's" vs "it is"). Count first-person. Count slang. |
|
||||
| Use of humor? | Dry wit (unexpected juxtapositions). Self-deprecating (acknowledges own limitations). Provocateur (picks fights). None. |
|
||||
| Relationship to reader? | Peer (we're both figuring this out). Expert (I know, you're learning). Challenger (you're probably wrong about this). |
|
||||
| Signature phrases? | Phrases or constructions that appear more than once. That's the brand's verbal tic. |
|
||||
| What do they avoid? | Listen for what's conspicuously absent. |
|
||||
|
||||
Document this as a voice profile before editing. Reference it throughout.
|
||||
|
||||
---
|
||||
|
||||
## The Core Voice Types
|
||||
|
||||
### Voice Type 1: The Direct Expert
|
||||
|
||||
**Profile:** Short sentences. Confident claims. No hedging. No qualifications unless the qualification is the point. Reads like advice from the smartest person in the room who also has the least patience.
|
||||
|
||||
**Natural habitat:** Developer tools, technical documentation, no-fluff B2B brands, opinionated founders.
|
||||
|
||||
**Techniques:**
|
||||
- Lead every section with the conclusion, not the setup
|
||||
- Make claims without softening them: "Most onboarding is broken" not "Many onboarding flows may have room for improvement"
|
||||
- Use "you" relentlessly — direct address, always
|
||||
- Short paragraphs. Often 1-2 sentences.
|
||||
- When listing, use the smallest number of words possible
|
||||
- No rhetorical questions unless you're about to immediately answer them
|
||||
- Swear if the brand does (a well-placed "this is genuinely terrible" signals authenticity)
|
||||
|
||||
**Before:** "It's important to consider that implementing an effective onboarding strategy can have significant positive impacts on user retention rates."
|
||||
|
||||
**After:** "Fix your onboarding. It's where you're losing them."
|
||||
|
||||
---
|
||||
|
||||
### Voice Type 2: The Thoughtful Peer
|
||||
|
||||
**Profile:** Longer sentences when the thought requires it. Occasional vulnerability. Shares the thinking, not just the conclusion. Treats the reader as someone at roughly the same level.
|
||||
|
||||
**Natural habitat:** B2B SaaS with community focus, content brands, newsletter-first companies, founder blogs.
|
||||
|
||||
**Techniques:**
|
||||
- Show the reasoning: "Here's how I think about this..." not just the conclusion
|
||||
- Acknowledge what you don't know: "I don't have solid data on this, but my read is..."
|
||||
- Share the mistake before the lesson: "We tried X first and it failed. Here's what we learned."
|
||||
- Longer transitions: connect ideas, don't just jump to the next point
|
||||
- Questions that earn their keep — rhetorical only when you're genuinely pointing at a tension
|
||||
- First person plural ("we") where appropriate — but only if there actually is a "we"
|
||||
|
||||
**Before:** "Companies should invest in customer success to improve retention."
|
||||
|
||||
**After:** "I spent two years thinking retention was a marketing problem. It wasn't. Every company we talked to that had great retention had one thing in common: they treated customer success like a product team, not a support team. The product mindset made all the difference."
|
||||
|
||||
---
|
||||
|
||||
### Voice Type 3: The Provocateur
|
||||
|
||||
**Profile:** Challenges received wisdom. Takes positions most people avoid. Enjoys being right when everyone else was wrong. Not confrontational for its own sake — has actual conviction behind the provocation.
|
||||
|
||||
**Natural habitat:** Opinionated SaaS, contrarian analyst voices, certain agency brands, fast-growing startups trying to differentiate.
|
||||
|
||||
**Techniques:**
|
||||
- Open with the unpopular claim: "Most SEO advice is wrong" not "There are many perspectives on SEO"
|
||||
- Name the thing people don't say: "The reason nobody talks about X is because..."
|
||||
- Acknowledge the argument against your position before making yours stronger
|
||||
- Use "actually" strategically: "What actually happens is..."
|
||||
- When everyone agrees on something, be specific about what they're getting wrong
|
||||
- Let the evidence land without fanfare — state the uncomfortable number, then wait
|
||||
|
||||
**Before:** "There are various approaches to content marketing that teams may find valuable."
|
||||
|
||||
**After:** "Your competitors' content marketing budgets are wasted. The average B2B blog post gets 300 views and zero conversions. The top 10% of pieces generate 90% of the value. Most teams don't know which 10% they have — which means they're spending 90% of their budget on content that will never pay back."
|
||||
|
||||
---
|
||||
|
||||
### Voice Type 4: The Enthusiastic Practitioner
|
||||
|
||||
**Profile:** Genuine excitement about the craft. Energized by the detail. The person who could talk about their domain for hours and you'd actually enjoy it.
|
||||
|
||||
**Natural habitat:** Creative tools, marketing tech, community platforms, brands with a strong practitioner user base.
|
||||
|
||||
**Techniques:**
|
||||
- Allow enthusiasm to come through without forcing it: "This is the part I love about cohort analysis..."
|
||||
- Share the unexpected detail that only a practitioner would notice
|
||||
- Use specific terminology confidently — don't over-explain to practitioners
|
||||
- "The thing is..." as a transition — signals you're about to share the real insight
|
||||
- Parenthetical asides that reveal depth: "(And yes, I know about [edge case] — that's a separate problem)"
|
||||
- Let the complexity show when the complexity is interesting
|
||||
|
||||
**Before:** "Segmenting your audience allows for more targeted communication."
|
||||
|
||||
**After:** "Here's where audience segmentation gets genuinely interesting. Most people segment by company size or industry. That's fine. But the cohort that always outperforms is behavioral — people who hit your activation event within 72 hours. That cohort has 2-3x the LTV of the same-company-size cohort that took two weeks. The behavior tells you more than the firmographic ever will."
|
||||
|
||||
---
|
||||
|
||||
## Specific Techniques Regardless of Voice Type
|
||||
|
||||
### The Personal Anecdote Injection
|
||||
|
||||
Every brand can use a personal anecdote — even B2B technical brands. The format:
|
||||
|
||||
**Setup:** "When we [did X thing in context]..."
|
||||
**What happened:** "[Specific unexpected thing occurred]."
|
||||
**The lesson:** "[The principle that explains it]."
|
||||
|
||||
The anecdote doesn't have to be dramatic. It just has to be real and specific. "When we rebuilt our onboarding flow in 2023, we expected the copy to be the problem. It was the loading time."
|
||||
|
||||
### The Honest Admission
|
||||
|
||||
Instantly humanizing. Rarely done by brands because it feels like weakness. But readers trust brands that admit:
|
||||
- What they got wrong
|
||||
- What they don't know
|
||||
- What they tried that failed
|
||||
- What surprised them
|
||||
|
||||
The format: "We thought X. We were wrong. What actually happened was Y."
|
||||
|
||||
### The Contrarian Setup
|
||||
|
||||
Works for any voice type. Setup: state the conventional wisdom. Then undercut it.
|
||||
|
||||
"Everyone says [thing]. The data shows [opposite thing]."
|
||||
|
||||
Or more subtle: "The conventional wisdom is [X]. That's mostly true. Except when [specific condition] — and that's where it gets interesting."
|
||||
|
||||
### Sentence Rhythm Signature
|
||||
|
||||
After analyzing the brand voice, identify the rhythm pattern and apply it:
|
||||
|
||||
- **Staccato brand:** Short sentence. Shorter. Done.
|
||||
- **Flowing brand:** Content that allows ideas to build on each other, connect, and arrive somewhere richer than where they started.
|
||||
- **Mixed cadence (most natural):** Long sentence establishing context. Short punch. Then another long one that goes somewhere. Then: done.
|
||||
|
||||
Once you know the pattern, apply it consistently throughout the piece.
|
||||
|
||||
### The Earned Ending
|
||||
|
||||
The last sentence of a piece should land. Not summarize. Not encourage. Land.
|
||||
|
||||
Techniques:
|
||||
- **The hard cut:** State the core truth one final time, nakedly. No wrap-up.
|
||||
- **The reversal:** Setup expectation, then subvert it in the last line.
|
||||
- **The action:** Name the single most important thing to do next. One thing.
|
||||
- **The honest admission:** "We're still figuring this out too."
|
||||
|
||||
Avoid: "By following these steps, you'll be well on your way to achieving your goals." Nobody reads that. Nobody trusts it.
|
||||
|
||||
---
|
||||
|
||||
## Voice Injection Quality Check
|
||||
|
||||
After applying voice:
|
||||
- [ ] Read the piece aloud — does it sound like a person you'd actually follow?
|
||||
- [ ] Is every paragraph distinguishable from the others? (Not just same rhythm, same length, same pattern)
|
||||
- [ ] Is there at least one moment where the brand's specific personality is unmistakable?
|
||||
- [ ] Would someone who knows this brand's other content recognize this as theirs?
|
||||
- [ ] Is there at least one place where the brand says something most brands wouldn't?
|
||||
487
marketing-skill/content-humanizer/scripts/humanizer_scorer.py
Normal file
487
marketing-skill/content-humanizer/scripts/humanizer_scorer.py
Normal file
@@ -0,0 +1,487 @@
|
||||
#!/usr/bin/env python3
|
||||
"""humanizer_scorer.py — scores content 0-100 on 'humanity' by detecting AI writing patterns."""
|
||||
|
||||
import sys
|
||||
import re
|
||||
import json
|
||||
import math
|
||||
from collections import Counter
|
||||
|
||||
# ── Sample content for zero-config demo ──────────────────────────────────────
|
||||
SAMPLE_HUMAN = """
|
||||
We tried to fix our churn problem the wrong way for about a year.
|
||||
|
||||
We threw money at marketing, assumed acquisition would outpace loss, and avoided looking at the actual numbers. It didn't work. Churn stayed flat at 8% monthly, which sounds manageable until you realize that's 65% annual churn. We were filling a leaky bucket with a garden hose.
|
||||
|
||||
The breakthrough — if you can call it that — was embarrassingly simple: we actually talked to the customers who left.
|
||||
|
||||
Not the ones who complained. The ones who quietly disappeared. We called 30 churned accounts over two weeks. You know what most of them said? They didn't hate the product. They just... forgot about it. It was solving a problem they cared about once, and then stopped caring about.
|
||||
|
||||
So we rebuilt our onboarding around one question: what would make this impossible to ignore? Not "valuable" — people know it's valuable. Impossible to ignore.
|
||||
|
||||
Three months later, 30-day activation was up 40%. Churn dropped to 4.5%.
|
||||
|
||||
The lesson wasn't about product or pricing. It was about habit formation. And we were terrible at it.
|
||||
"""
|
||||
|
||||
SAMPLE_AI = """
|
||||
It is crucial to leverage data-driven insights in order to effectively navigate the challenges of customer retention in the competitive SaaS landscape. Furthermore, by implementing robust onboarding strategies, organizations can ensure that users achieve maximum value from the product, thereby significantly reducing churn rates.
|
||||
|
||||
To facilitate this process, it's important to note that companies should delve into their customer behavior data to identify patterns and trends. Moreover, by fostering meaningful connections with customers and ensuring comprehensive support throughout their journey, businesses can cultivate lasting relationships that drive long-term success.
|
||||
|
||||
In conclusion, the implementation of these holistic strategies will empower organizations to streamline their customer success operations and achieve sustainable growth in an increasingly competitive marketplace.
|
||||
"""
|
||||
|
||||
|
||||
# ── AI vocabulary signals ─────────────────────────────────────────────────────
|
||||
AI_VOCABULARY = [
|
||||
# The notorious list
|
||||
"delve", "delve into", "delves", "delving",
|
||||
"landscape",
|
||||
"crucial", "vital", "pivotal",
|
||||
"leverage", "leveraging", "leveraged",
|
||||
"robust",
|
||||
"comprehensive",
|
||||
"holistic",
|
||||
"foster", "fosters", "fostering",
|
||||
"facilitate", "facilitates", "facilitating",
|
||||
"navigate", "navigating",
|
||||
"ensure", "ensures", "ensuring",
|
||||
"utilize", "utilizing", "utilizes",
|
||||
"furthermore", "moreover",
|
||||
"innovative", "cutting-edge",
|
||||
"seamless", "seamlessly",
|
||||
"empower", "empowers", "empowering",
|
||||
"streamline", "streamlines", "streamlining",
|
||||
"cultivate", "cultivating",
|
||||
"paradigm",
|
||||
"ecosystem",
|
||||
"synergy",
|
||||
"in conclusion",
|
||||
"in summary",
|
||||
"to summarize",
|
||||
]
|
||||
|
||||
HEDGING_PHRASES = [
|
||||
"it is important to note",
|
||||
"it's important to note",
|
||||
"it should be noted",
|
||||
"it is worth mentioning",
|
||||
"it's worth mentioning",
|
||||
"it goes without saying",
|
||||
"needless to say",
|
||||
"in many cases",
|
||||
"in most cases",
|
||||
"in certain cases",
|
||||
"in most instances",
|
||||
"in many instances",
|
||||
"generally speaking",
|
||||
"for the most part",
|
||||
"this may vary",
|
||||
"results may differ",
|
||||
"one might argue",
|
||||
"it can be argued",
|
||||
"there are various",
|
||||
"there are many",
|
||||
"it is crucial to",
|
||||
"it's crucial to",
|
||||
]
|
||||
|
||||
PASSIVE_PATTERNS = [
|
||||
r'\b(is|are|was|were|be|been|being)\s+(being\s+)?\w+ed\b',
|
||||
r'\b(can|could|should|would|may|might|must)\s+be\s+\w+ed\b',
|
||||
]
|
||||
|
||||
VAGUE_AUTHORITY = [
|
||||
"studies show",
|
||||
"research suggests",
|
||||
"research shows",
|
||||
"experts agree",
|
||||
"experts say",
|
||||
"many companies",
|
||||
"leading brands",
|
||||
"it has been shown",
|
||||
"according to research",
|
||||
"data suggests",
|
||||
"evidence suggests",
|
||||
]
|
||||
|
||||
|
||||
# ── Scoring functions ─────────────────────────────────────────────────────────
|
||||
|
||||
def score_ai_vocabulary(text: str) -> dict:
|
||||
"""Score 0-25: fewer AI words = higher score."""
|
||||
text_lower = text.lower()
|
||||
words_total = max(1, len(re.findall(r'\b\w+\b', text)))
|
||||
|
||||
hits = []
|
||||
for phrase in AI_VOCABULARY:
|
||||
count = text_lower.count(phrase)
|
||||
if count > 0:
|
||||
hits.append((phrase, count))
|
||||
|
||||
total_hits = sum(c for _, c in hits)
|
||||
density = total_hits / (words_total / 100) # per 100 words
|
||||
|
||||
# Score: 0 hits = 25, scales down
|
||||
if total_hits == 0:
|
||||
score = 25
|
||||
elif total_hits <= 2:
|
||||
score = 20
|
||||
elif total_hits <= 5:
|
||||
score = 14
|
||||
elif total_hits <= 10:
|
||||
score = 8
|
||||
elif total_hits <= 15:
|
||||
score = 3
|
||||
else:
|
||||
score = 0
|
||||
|
||||
return {
|
||||
"score": score,
|
||||
"max": 25,
|
||||
"ai_word_hits": total_hits,
|
||||
"density_per_100_words": round(density, 2),
|
||||
"flagged_terms": [f for f, _ in hits[:10]], # top 10 for display
|
||||
}
|
||||
|
||||
|
||||
def score_sentence_variance(text: str) -> dict:
|
||||
"""Score 0-20: high variance = more human (robots use uniform length)."""
|
||||
sentences = re.split(r'[.!?]+', text)
|
||||
sentences = [s.strip() for s in sentences if len(s.split()) >= 3]
|
||||
|
||||
if len(sentences) < 3:
|
||||
return {"score": 10, "max": 20, "std_dev": 0, "avg_length": 0, "note": "too few sentences to score"}
|
||||
|
||||
lengths = [len(s.split()) for s in sentences]
|
||||
avg = sum(lengths) / len(lengths)
|
||||
variance = sum((l - avg) ** 2 for l in lengths) / len(lengths)
|
||||
std_dev = math.sqrt(variance)
|
||||
|
||||
# Good human writing has std_dev of 8-15 for mixed content
|
||||
if std_dev >= 12:
|
||||
score = 20
|
||||
elif std_dev >= 8:
|
||||
score = 16
|
||||
elif std_dev >= 5:
|
||||
score = 10
|
||||
elif std_dev >= 3:
|
||||
score = 5
|
||||
else:
|
||||
score = 0 # very robotic: all sentences same length
|
||||
|
||||
return {
|
||||
"score": score,
|
||||
"max": 20,
|
||||
"std_dev": round(std_dev, 1),
|
||||
"avg_length": round(avg, 1),
|
||||
"min_length": min(lengths),
|
||||
"max_length": max(lengths),
|
||||
}
|
||||
|
||||
|
||||
def score_passive_voice(text: str) -> dict:
|
||||
"""Score 0-20: less passive = more human."""
|
||||
sentences = re.split(r'[.!?]+', text)
|
||||
sentences = [s.strip() for s in sentences if s.strip()]
|
||||
n_sentences = max(1, len(sentences))
|
||||
|
||||
passive_count = 0
|
||||
for pattern in PASSIVE_PATTERNS:
|
||||
passive_count += len(re.findall(pattern, text, re.IGNORECASE))
|
||||
|
||||
passive_ratio = passive_count / n_sentences
|
||||
|
||||
if passive_ratio < 0.1:
|
||||
score = 20
|
||||
elif passive_ratio < 0.2:
|
||||
score = 16
|
||||
elif passive_ratio < 0.3:
|
||||
score = 10
|
||||
elif passive_ratio < 0.4:
|
||||
score = 5
|
||||
else:
|
||||
score = 0
|
||||
|
||||
return {
|
||||
"score": score,
|
||||
"max": 20,
|
||||
"passive_count": passive_count,
|
||||
"passive_ratio": round(passive_ratio, 2),
|
||||
"passive_pct": f"{round(passive_ratio * 100)}%",
|
||||
}
|
||||
|
||||
|
||||
def score_hedging(text: str) -> dict:
|
||||
"""Score 0-15: fewer hedges = more direct = more human."""
|
||||
text_lower = text.lower()
|
||||
hits = []
|
||||
for phrase in HEDGING_PHRASES:
|
||||
count = text_lower.count(phrase)
|
||||
if count > 0:
|
||||
hits.append((phrase, count))
|
||||
|
||||
total_hedges = sum(c for _, c in hits)
|
||||
|
||||
if total_hedges == 0:
|
||||
score = 15
|
||||
elif total_hedges == 1:
|
||||
score = 12
|
||||
elif total_hedges == 2:
|
||||
score = 8
|
||||
elif total_hedges == 3:
|
||||
score = 4
|
||||
else:
|
||||
score = 0
|
||||
|
||||
vague_hits = sum(text_lower.count(p) for p in VAGUE_AUTHORITY)
|
||||
|
||||
return {
|
||||
"score": score,
|
||||
"max": 15,
|
||||
"hedge_count": total_hedges,
|
||||
"vague_authority_count": vague_hits,
|
||||
"flagged_phrases": [f for f, _ in hits],
|
||||
}
|
||||
|
||||
|
||||
def score_em_dashes(text: str) -> dict:
|
||||
"""Score 0-10: moderate em-dash use is fine; overuse is a tell."""
|
||||
# Count em-dashes (—) and double-hyphen (--) used as em-dash
|
||||
em_count = text.count('—') + text.count('--')
|
||||
word_count = max(1, len(re.findall(r'\b\w+\b', text)))
|
||||
per_100 = em_count / (word_count / 100)
|
||||
|
||||
if per_100 < 0.5:
|
||||
score = 10 # none or very rare: fine
|
||||
elif per_100 < 1.5:
|
||||
score = 8 # occasional: good
|
||||
elif per_100 < 3:
|
||||
score = 5 # frequent: suspicious
|
||||
elif per_100 < 5:
|
||||
score = 2 # overuse: likely AI
|
||||
else:
|
||||
score = 0 # compulsive: AI fingerprint
|
||||
|
||||
return {
|
||||
"score": score,
|
||||
"max": 10,
|
||||
"em_dash_count": em_count,
|
||||
"per_100_words": round(per_100, 2),
|
||||
}
|
||||
|
||||
|
||||
def score_paragraph_variety(text: str) -> dict:
|
||||
"""Score 0-10: varied paragraph lengths = more human."""
|
||||
paragraphs = [p.strip() for p in text.split('\n\n') if p.strip() and not p.startswith('#')]
|
||||
if len(paragraphs) < 3:
|
||||
return {"score": 5, "max": 10, "note": "too few paragraphs to score"}
|
||||
|
||||
lengths = [len(p.split()) for p in paragraphs]
|
||||
avg = sum(lengths) / len(lengths)
|
||||
variance = sum((l - avg) ** 2 for l in lengths) / len(lengths)
|
||||
std_dev = math.sqrt(variance)
|
||||
|
||||
# Has any single-sentence paragraphs? (hallmark of human writing)
|
||||
has_short = any(l <= 15 for l in lengths)
|
||||
has_long = any(l >= 80 for l in lengths)
|
||||
|
||||
score = 0
|
||||
if std_dev >= 30:
|
||||
score += 5
|
||||
elif std_dev >= 15:
|
||||
score += 3
|
||||
elif std_dev >= 5:
|
||||
score += 1
|
||||
|
||||
if has_short:
|
||||
score += 3
|
||||
if has_long and std_dev >= 15:
|
||||
score += 2
|
||||
|
||||
score = min(10, score)
|
||||
return {
|
||||
"score": score,
|
||||
"max": 10,
|
||||
"paragraph_count": len(paragraphs),
|
||||
"paragraph_std_dev": round(std_dev, 1),
|
||||
"has_short_paragraphs": has_short,
|
||||
"avg_paragraph_words": round(avg, 1),
|
||||
}
|
||||
|
||||
|
||||
# ── Main scoring ──────────────────────────────────────────────────────────────
|
||||
|
||||
def score_humanity(text: str) -> dict:
|
||||
vocab = score_ai_vocabulary(text)
|
||||
variance = score_sentence_variance(text)
|
||||
passive = score_passive_voice(text)
|
||||
hedging = score_hedging(text)
|
||||
em = score_em_dashes(text)
|
||||
paragraphs = score_paragraph_variety(text)
|
||||
|
||||
total = vocab["score"] + variance["score"] + passive["score"] + hedging["score"] + em["score"] + paragraphs["score"]
|
||||
|
||||
if total >= 85:
|
||||
label = "Sounds human ✅"
|
||||
elif total >= 70:
|
||||
label = "Mostly human — light edits needed"
|
||||
elif total >= 50:
|
||||
label = "Mixed — AI patterns detectable"
|
||||
elif total >= 30:
|
||||
label = "Robotic — significant rewrite needed"
|
||||
else:
|
||||
label = "AI fingerprint — full rewrite required 🔴"
|
||||
|
||||
return {
|
||||
"humanity_score": total,
|
||||
"label": label,
|
||||
"sections": {
|
||||
"ai_vocabulary": vocab,
|
||||
"sentence_variance": variance,
|
||||
"passive_voice": passive,
|
||||
"hedging": hedging,
|
||||
"em_dashes": em,
|
||||
"paragraph_variety": paragraphs,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
def print_report(result: dict, label: str = "") -> None:
|
||||
total = result["humanity_score"]
|
||||
verdict = result["label"]
|
||||
s = result["sections"]
|
||||
|
||||
bar_filled = int(total / 5)
|
||||
bar = "█" * bar_filled + "░" * (20 - bar_filled)
|
||||
|
||||
print()
|
||||
print("╔══════════════════════════════════════════╗")
|
||||
print("║ HUMANIZER SCORER — REPORT ║")
|
||||
print("╚══════════════════════════════════════════╝")
|
||||
if label:
|
||||
print(f" Input: {label}")
|
||||
print()
|
||||
print(f" HUMANITY SCORE: {total}/100")
|
||||
print(f" [{bar}]")
|
||||
print(f" Verdict: {verdict}")
|
||||
print()
|
||||
print(" ── Section Breakdown ──────────────────────")
|
||||
|
||||
sections = [
|
||||
("AI Vocabulary", s["ai_vocabulary"], 25),
|
||||
("Sentence Variance", s["sentence_variance"], 20),
|
||||
("Passive Voice", s["passive_voice"], 20),
|
||||
("Hedging Phrases", s["hedging"], 15),
|
||||
("Em-Dash Use", s["em_dashes"], 10),
|
||||
("Paragraph Variety", s["paragraph_variety"], 10),
|
||||
]
|
||||
for name, sec, mx in sections:
|
||||
sc = sec["score"]
|
||||
bar2 = "█" * int(sc / mx * 10) + "░" * (10 - int(sc / mx * 10))
|
||||
print(f" {name:<20} {sc:>2}/{mx} [{bar2}]")
|
||||
|
||||
print()
|
||||
print(" ── Detected Issues ────────────────────────")
|
||||
|
||||
v = s["ai_vocabulary"]
|
||||
if v["ai_word_hits"] > 0:
|
||||
terms = ", ".join(v["flagged_terms"][:5])
|
||||
print(f" 🔴 AI vocabulary: {v['ai_word_hits']} hits — [{terms}]")
|
||||
else:
|
||||
print(" ✅ No AI vocabulary detected")
|
||||
|
||||
sv = s["sentence_variance"]
|
||||
if sv["std_dev"] < 5:
|
||||
print(f" 🔴 Sentence rhythm robotic — std dev only {sv['std_dev']} (target: 8+)")
|
||||
elif sv["std_dev"] < 8:
|
||||
print(f" 🟡 Sentence variance low — {sv['std_dev']} (target: 8+)")
|
||||
else:
|
||||
print(f" ✅ Sentence variance good — {sv['std_dev']}")
|
||||
|
||||
pv = s["passive_voice"]
|
||||
if pv["passive_ratio"] > 0.3:
|
||||
print(f" 🔴 Passive voice overuse — {pv['passive_pct']} of sentences")
|
||||
elif pv["passive_ratio"] > 0.2:
|
||||
print(f" 🟡 Passive voice elevated — {pv['passive_pct']}")
|
||||
else:
|
||||
print(f" ✅ Passive voice in range — {pv['passive_pct']}")
|
||||
|
||||
hg = s["hedging"]
|
||||
if hg["hedge_count"] > 2:
|
||||
terms = ", ".join(hg["flagged_phrases"][:3])
|
||||
print(f" 🔴 Hedging overload — {hg['hedge_count']} phrases: [{terms}]")
|
||||
elif hg["hedge_count"] > 0:
|
||||
print(f" 🟡 Hedging present — {hg['hedge_count']} phrase(s): {hg['flagged_phrases']}")
|
||||
else:
|
||||
print(" ✅ No hedging detected")
|
||||
|
||||
if hg["vague_authority_count"] > 0:
|
||||
print(f" 🟡 Vague authority claims: {hg['vague_authority_count']} (e.g. 'studies show') — add citations")
|
||||
|
||||
em = s["em_dashes"]
|
||||
if em["per_100_words"] > 3:
|
||||
print(f" 🟡 Em-dash overuse — {em['em_dash_count']} in piece ({em['per_100_words']}/100 words)")
|
||||
|
||||
pg = s["paragraph_variety"]
|
||||
if not pg.get("has_short_paragraphs"):
|
||||
print(" 🟡 No short paragraphs found — add some 1-2 sentence paragraphs for rhythm")
|
||||
|
||||
print()
|
||||
print(" ── Priority Fixes ─────────────────────────")
|
||||
|
||||
if v["ai_word_hits"] > 5:
|
||||
print(" 1. Replace AI vocabulary (biggest impact)")
|
||||
if sv["std_dev"] < 8:
|
||||
print(" 2. Vary sentence length — mix short punchy sentences with longer ones")
|
||||
if pv["passive_ratio"] > 0.25:
|
||||
print(" 3. Flip passive sentences to active voice")
|
||||
if hg["hedge_count"] > 2:
|
||||
print(" 4. Cut hedging phrases — state claims directly")
|
||||
if not pg.get("has_short_paragraphs"):
|
||||
print(" 5. Add short paragraphs — even 1-sentence paragraphs help rhythm")
|
||||
|
||||
if total >= 85:
|
||||
print(" ✅ No priority fixes — content reads as human")
|
||||
print()
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) == 1:
|
||||
# Demo mode: compare human vs AI sample
|
||||
print("[Demo mode — comparing human vs AI sample content]")
|
||||
print()
|
||||
print("═" * 50)
|
||||
print("SAMPLE 1: Human-written content")
|
||||
print("═" * 50)
|
||||
r1 = score_humanity(SAMPLE_HUMAN)
|
||||
print_report(r1, "Human sample")
|
||||
|
||||
print("═" * 50)
|
||||
print("SAMPLE 2: AI-generated content")
|
||||
print("═" * 50)
|
||||
r2 = score_humanity(SAMPLE_AI)
|
||||
print_report(r2, "AI sample")
|
||||
|
||||
print(f" Delta: Human scored {r1['humanity_score']}, AI scored {r2['humanity_score']}")
|
||||
print(f" Difference: {r1['humanity_score'] - r2['humanity_score']} points")
|
||||
print()
|
||||
else:
|
||||
filepath = sys.argv[1]
|
||||
try:
|
||||
with open(filepath, 'r', encoding='utf-8') as f:
|
||||
text = f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"Error: file not found: {filepath}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
result = score_humanity(text)
|
||||
print_report(result, filepath)
|
||||
|
||||
if "--json" in sys.argv:
|
||||
print(json.dumps(result, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
245
marketing-skill/content-production/SKILL.md
Normal file
245
marketing-skill/content-production/SKILL.md
Normal file
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: content-production
|
||||
description: "Full content production pipeline — takes a topic from blank page to published-ready piece. Use when you need to execute content: write a blog post, article, or guide end-to-end. Triggers: 'write a post about', 'draft an article', 'create content for', 'help me write', 'I need a blog post'. NOT for content strategy or calendar planning (use content-strategy). NOT for repurposing existing content (use content-repurposing). NOT for social captions only."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Content Production
|
||||
|
||||
You are an expert content producer with deep experience across B2B SaaS, developer tools, and technical audiences. Your goal is to take a topic from zero to a finished, optimized piece that ranks, converts, and actually gets read.
|
||||
|
||||
This is the execution engine — not the strategy layer. You're here to build, not plan.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for context first:**
|
||||
If `marketing-context.md` exists, read it before asking questions. It contains brand voice, target audience, keyword targets, and writing examples. Use what's there — only ask for what's missing.
|
||||
|
||||
Gather this context (ask in one shot, don't drip):
|
||||
|
||||
### What you need
|
||||
- **Topic / working title** — what are we writing about?
|
||||
- **Target keyword** — primary search term (if SEO matters)
|
||||
- **Audience** — who reads this and what do they already know?
|
||||
- **Goal** — inform, convert, build authority, drive trial?
|
||||
- **Approximate length** — 800 words? 2,000 words? Long-form?
|
||||
- **Existing content** — do we have pieces this should link to?
|
||||
|
||||
If the topic is vague ("write about AI"), push back: "Give me the specific angle — who's the reader, what problem are they solving?"
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
Three modes. Start at whichever fits:
|
||||
|
||||
### Mode 1: Research & Brief
|
||||
You have a topic but no content yet. Do the research, map the competitive landscape, define the angle, and produce a content brief before writing a word.
|
||||
|
||||
### Mode 2: Draft
|
||||
Brief exists (either provided or from Mode 1). Write the full piece — intro, body, conclusion, headers — following the brief's structure and targeting parameters.
|
||||
|
||||
### Mode 3: Optimize & Polish
|
||||
Draft exists. Run the full optimization pass: SEO signals, readability, structure audit, meta tags, internal links, quality gates. Output a publish-ready version.
|
||||
|
||||
You can run all 3 in sequence or jump directly to any mode.
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Research & Brief
|
||||
|
||||
### Step 1 — Competitive Content Analysis
|
||||
|
||||
Before writing, understand what already ranks. For the target keyword:
|
||||
|
||||
1. Identify the top 5-10 ranking pieces
|
||||
2. Map their angles: Are they listicles? How-tos? Opinion pieces? Comparisons?
|
||||
3. Find the gap: What's missing from the existing content? What angle is underserved?
|
||||
4. Check search intent: Is the person trying to learn, compare, buy, or solve a specific problem?
|
||||
|
||||
**Intent signals:**
|
||||
| SERP Pattern | Intent | What to write |
|
||||
|---|---|---|
|
||||
| "What is / How to" dominate | Informational | Comprehensive guide or explainer |
|
||||
| Product pages, reviews | Commercial | Comparison or buyer's guide |
|
||||
| News, updates | Navigational/news | Skip unless you have unique angle |
|
||||
| Forum results (Reddit, Quora) | Discovery | Opinionated piece with real perspective |
|
||||
|
||||
### Step 2 — Source Gathering
|
||||
|
||||
Collect 3-5 credible, citable sources before drafting. Prioritize:
|
||||
- Original research (studies, surveys, reports)
|
||||
- Official documentation
|
||||
- Expert quotes you can attribute
|
||||
- Data with specific numbers (not vague claims)
|
||||
|
||||
**Rule:** If you can't cite a specific number, don't make a vague claim. "Studies show" is a red flag. Find the actual study.
|
||||
|
||||
### Step 3 — Produce the Content Brief
|
||||
|
||||
Fill in the [Content Brief Template](templates/content-brief-template.md). The brief defines:
|
||||
- Target keyword + secondary keywords
|
||||
- Reader profile and their job-to-be-done
|
||||
- Angle and unique point of view
|
||||
- Required sections and H2 structure
|
||||
- Key claims to prove
|
||||
- Internal links to include
|
||||
- Competitive pieces to beat
|
||||
|
||||
See [references/content-brief-guide.md](references/content-brief-guide.md) for how to write a brief that actually produces better drafts.
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Draft
|
||||
|
||||
You have a brief. Now write.
|
||||
|
||||
### Outline First
|
||||
|
||||
Build the header skeleton before filling in prose. A good outline:
|
||||
- Has a hook-worthy H1 (keyword-included, curiosity-driving)
|
||||
- Has 4-7 H2 sections that follow a logical progression
|
||||
- Uses H3s sparingly — only when a section genuinely needs subdivision
|
||||
- Ends with a CTA-adjacent conclusion
|
||||
|
||||
Don't over-engineer the outline. If you're stuck on structure for more than 5 minutes, start writing and restructure later.
|
||||
|
||||
### Intro Principles
|
||||
|
||||
The intro has one job: make the reader believe this piece will answer their question. Get there in 3-4 sentences.
|
||||
|
||||
Formula that works:
|
||||
1. Name the problem or situation the reader is in
|
||||
2. Name what this piece does about it
|
||||
3. Optionally: give them a reason to trust you on this topic
|
||||
|
||||
**What to avoid:**
|
||||
- Starting with "In today's digital landscape..." (everyone does this)
|
||||
- Starting with a question unless it's genuinely sharp
|
||||
- Burying the point under 3 sentences of context-setting
|
||||
|
||||
### Section-by-Section Approach
|
||||
|
||||
For each H2 section:
|
||||
1. State the main point in the first sentence (don't save it for the end)
|
||||
2. Prove it with an example, stat, or comparison
|
||||
3. Add one actionable takeaway before moving on
|
||||
|
||||
Readers skim. Every section should deliver value on its own.
|
||||
|
||||
### Conclusion
|
||||
|
||||
Three elements:
|
||||
1. Summary of the core argument (1-2 sentences)
|
||||
2. The single most important thing to do next
|
||||
3. CTA (if relevant to the goal)
|
||||
|
||||
Don't pad the conclusion. If it's done, it's done.
|
||||
|
||||
---
|
||||
|
||||
## Mode 3: Optimize & Polish
|
||||
|
||||
Draft exists. Run this in order.
|
||||
|
||||
### SEO Pass
|
||||
|
||||
- **Title tag**: Contains primary keyword, under 60 characters, curiosity-driving
|
||||
- **H1**: Different from title tag, keyword-rich, reads naturally
|
||||
- **H2s**: At least 2-3 contain secondary keywords or related phrases
|
||||
- **First paragraph**: Primary keyword appears in first 100 words
|
||||
- **Image alt text**: Descriptive, includes keyword where natural
|
||||
- **URL slug**: Short, keyword-first, no stop words
|
||||
|
||||
### Readability Pass
|
||||
|
||||
Run `scripts/content_scorer.py` on the draft. Target score: 70+.
|
||||
|
||||
Manual checks:
|
||||
- Average sentence length: aim for 15-20 words, mix it up
|
||||
- No paragraph over 4 sentences (web readers need air)
|
||||
- No jargon without explanation (for non-expert audiences)
|
||||
- Active voice: find passive constructions and flip them
|
||||
|
||||
### Structure Audit
|
||||
|
||||
- Does the intro deliver on the headline's promise?
|
||||
- Is every H2 section earning its place? (Cut if not)
|
||||
- Are there at least 2 examples or concrete illustrations?
|
||||
- Does the conclusion feel earned?
|
||||
|
||||
### Internal Links
|
||||
|
||||
Add 2-4 internal links minimum:
|
||||
- Link from high-traffic existing pages to this piece
|
||||
- Link from this piece to related existing content
|
||||
- Anchor text should describe the destination, not be generic ("click here" is useless)
|
||||
|
||||
### Meta Tags
|
||||
|
||||
Write:
|
||||
- **Meta description**: 150-160 characters, includes keyword, ends with action or hook
|
||||
- **OG title / OG description**: Can differ from meta, optimized for social sharing
|
||||
- **Canonical URL**: Set it, even if obvious
|
||||
|
||||
### Quality Gates — Don't Publish Until These Pass
|
||||
|
||||
See [references/optimization-checklist.md](references/optimization-checklist.md) for the full pre-publish checklist.
|
||||
|
||||
Core gates:
|
||||
- [ ] Primary keyword appears naturally 3-5x (not stuffed)
|
||||
- [ ] Every factual claim has a source or is clearly labeled as opinion
|
||||
- [ ] At least one image, table, or visual element breaks up text
|
||||
- [ ] Intro doesn't start with a cliché
|
||||
- [ ] All internal links work
|
||||
- [ ] Readability score ≥ 70
|
||||
- [ ] Word count is within 10% of target
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Flag these without being asked:
|
||||
|
||||
- **Thin content risk** — If the target keyword has high-authority competitors with 2,000+ word pieces, a 600-word post won't rank. Surface this upfront, before drafting starts.
|
||||
- **Keyword cannibalization** — If existing content already targets this keyword, flag it. Publishing a second piece splits authority instead of building it.
|
||||
- **Intent mismatch** — If the requested angle doesn't match search intent (e.g., writing a brand awareness piece for a transactional keyword), call it out. The piece will get traffic that doesn't convert.
|
||||
- **Missing sources** — If the draft contains claims like "many companies" or "studies show" without citation, flag each one before the piece ships.
|
||||
- **CTA/goal disconnect** — If the piece's goal is "drive trial signups" but there's no CTA, or the CTA is buried at paragraph 12, flag it.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---|---|
|
||||
| Research & brief | Completed content brief: keyword targets, audience, angle, H2 structure, sources, competitive gaps |
|
||||
| Full draft | Complete article with H1, H2s, intro, body, conclusion, and inline source markers |
|
||||
| SEO optimization | Annotated draft with title tag, meta description, keyword placement audit, and OG copy |
|
||||
| Readability audit | Scorer output + specific sentence-level edits flagged |
|
||||
| Publish checklist | Completed gate checklist with pass/fail on each item |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured standard:
|
||||
- **Bottom line first** — answer before explanation
|
||||
- **What + Why + How** — every finding includes all three
|
||||
- **Actions have owners and deadlines** — no "we should probably..."
|
||||
- **Confidence tagging** — 🟢 verified / 🟡 medium / 🔴 assumed
|
||||
|
||||
When reviewing drafts: flag issues → explain impact → give specific fix. Don't just say "improve readability." Say: "Paragraph 3 averages 32 words per sentence. Break the second sentence into two."
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **content-strategy**: Use when deciding *what* to write — topics, calendar, pillar structure. NOT for writing the actual piece (that's this skill).
|
||||
- **content-humanizer**: Use after drafting when the piece sounds robotic or AI-generated. Run this before the optimization pass.
|
||||
- **ai-seo**: Use when optimizing specifically for AI search citation (ChatGPT, Perplexity, AI Overviews) in addition to traditional SEO.
|
||||
- **copywriting**: Use for landing pages, CTAs, and conversion copy. NOT for long-form content (that's this skill).
|
||||
- **seo-audit**: Use when auditing an existing content library for SEO gaps. NOT for single-piece production.
|
||||
@@ -0,0 +1,146 @@
|
||||
# Content Brief Guide
|
||||
|
||||
A brief isn't a writing assignment. It's a contract between the strategist and the writer — and when you're both the same person, it's still the contract between your thinking brain and your writing brain. Skip it and you'll rewrite. Do it right and the draft almost writes itself.
|
||||
|
||||
---
|
||||
|
||||
## Why Briefs Fail (and How to Fix Them)
|
||||
|
||||
Most briefs are too vague. They say "write about email marketing" without telling the writer:
|
||||
- What's the specific angle?
|
||||
- Who's the reader?
|
||||
- What keywords matter?
|
||||
- What tone?
|
||||
- What should the reader do after?
|
||||
|
||||
The result: a draft that misses the mark on every axis.
|
||||
|
||||
**The fix:** Every field in the brief should be specific enough that two different writers would produce the same piece.
|
||||
|
||||
---
|
||||
|
||||
## The Most Important Field: Angle
|
||||
|
||||
The angle is the single most critical field in the brief. It's your differentiated take — not just "write about email marketing" but "why most email open rate benchmarks are useless and what to measure instead."
|
||||
|
||||
**A good angle is:**
|
||||
- One sentence
|
||||
- Opinionated (takes a position)
|
||||
- Different from what already ranks
|
||||
- Grounded in something you actually know or have data on
|
||||
|
||||
**A weak angle is:**
|
||||
- "Comprehensive guide to email marketing"
|
||||
- "Everything you need to know about..."
|
||||
- "Best practices for..."
|
||||
|
||||
If your angle sounds like a Wikipedia article, it's not an angle.
|
||||
|
||||
---
|
||||
|
||||
## Keyword Targeting: What Actually Matters
|
||||
|
||||
You don't need to stuff the brief with 20 keywords. You need:
|
||||
|
||||
1. **One primary keyword** — the main search term this piece is targeting. Every SEO decision flows from this.
|
||||
2. **2-4 secondary keywords** — related phrases that appear naturally. These expand coverage without forcing it.
|
||||
|
||||
**How to find secondary keywords:**
|
||||
- Look at "People Also Ask" on the SERP for your primary term
|
||||
- Check what related terms appear in the top-ranking articles
|
||||
- Use autocomplete on the search bar for your primary term
|
||||
|
||||
**Common mistake:** Targeting a keyword that's informational (someone learning) with a piece that's commercial (someone buying). Match intent or waste the effort.
|
||||
|
||||
---
|
||||
|
||||
## The Competitive Gap: Finding the Opening
|
||||
|
||||
Before writing the brief's angle, look at what's ranking. You're not copying them — you're finding what they missed.
|
||||
|
||||
**Gap patterns to look for:**
|
||||
|
||||
| Pattern | What It Means | Opportunity |
|
||||
|---|---|---|
|
||||
| All top pieces are listicles | No deep explanation exists | Write the definitive guide |
|
||||
| Top pieces are outdated (2+ years old) | Information is stale | Write the current-year version with updated data |
|
||||
| Top pieces are generic (no real examples) | Theory without practice | Write a practitioner piece with real cases |
|
||||
| Top pieces are all from the same POV | Perspective monopoly | Write the contrarian or underdog angle |
|
||||
| Top pieces are very long but shallow | Word count without depth | Write shorter but genuinely useful |
|
||||
|
||||
The gap is your angle. Find it before you brief.
|
||||
|
||||
---
|
||||
|
||||
## Structure: H2s Are the Real Deliverable
|
||||
|
||||
Writers often write vague outlines. "Introduction. Section 1. Conclusion." That's not a structure — that's a placeholder.
|
||||
|
||||
Good H2s do three things:
|
||||
1. **Promise value** — the reader knows what they'll learn
|
||||
2. **Follow logic** — each section flows from the previous
|
||||
3. **Hit keywords** — secondary terms appear naturally
|
||||
|
||||
**Building the H2 structure:**
|
||||
- Write the outline as if you're writing the table of contents for a useful reference book
|
||||
- Each H2 should be a complete thought ("How to Write Subject Lines That Get Opened" not "Subject Lines")
|
||||
- Sequence matters: don't put "Advanced Tactics" before "Why This Matters"
|
||||
|
||||
**The rule of 5:** Most blog posts need 4-6 H2s. Fewer and it's shallow. More and it's scattered.
|
||||
|
||||
---
|
||||
|
||||
## Sources: Non-Negotiable Before Drafting
|
||||
|
||||
Writers who draft without sources invent claims. Then those claims go live on your website.
|
||||
|
||||
**Minimum brief requirement:** 3 sources with specific data points or quotes identified.
|
||||
|
||||
**Source quality hierarchy:**
|
||||
1. Original research (surveys, studies, experiments you conducted)
|
||||
2. Credible third-party research (academic papers, industry reports from named organizations)
|
||||
3. Expert quotes (attributed, verifiable)
|
||||
4. Strong case studies with specific metrics
|
||||
5. Official documentation or standards
|
||||
|
||||
**Red flag sources:** Anything that cites "a study" without naming it. Anything more than 5 years old in a fast-moving category. Competitor blog posts (they're also making stuff up).
|
||||
|
||||
---
|
||||
|
||||
## Internal Linking: Plan It Before, Not After
|
||||
|
||||
Most writers add internal links as an afterthought. This produces one problem: they link to whatever they remember, not what's most valuable.
|
||||
|
||||
The brief should specify:
|
||||
- 2-3 existing pieces this article should link to (and what anchor text to use)
|
||||
- 1-2 existing pages that should link back to this article once published
|
||||
|
||||
This prevents both orphaned content and missed link equity.
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria: If You Don't Define It, You Can't Measure It
|
||||
|
||||
Every brief should answer: how will we know this piece worked?
|
||||
|
||||
Not vague ("gets traffic") — specific:
|
||||
- Ranks in top 5 for [keyword] within [timeframe]
|
||||
- Drives X leads per month
|
||||
- Achieves X% conversion rate on the CTA
|
||||
- Gets cited / linked by [type of site]
|
||||
|
||||
Define it now so you don't change the definition later.
|
||||
|
||||
---
|
||||
|
||||
## Brief Anti-Patterns
|
||||
|
||||
| Anti-pattern | Problem | Fix |
|
||||
|---|---|---|
|
||||
| "Write a comprehensive guide" | No angle, no differentiation | Define the specific take |
|
||||
| Missing audience definition | Writer guesses; often wrong | Name the exact reader job title and pain |
|
||||
| No sources listed | Writer invents facts | Find 3 sources before briefing |
|
||||
| Vague keyword ("marketing") | No SEO targeting | Get specific: "email marketing for B2B SaaS" |
|
||||
| H2s that are just topic labels | No promise, no structure | Rewrite as complete-thought headers |
|
||||
| No internal links specified | Orphaned content | List 2-3 links before writing |
|
||||
| No success criteria | Can't evaluate performance | Define at least one measurable outcome |
|
||||
@@ -0,0 +1,139 @@
|
||||
# Pre-Publish Optimization Checklist
|
||||
|
||||
Run this before every piece goes live. Each section is a gate — fail a gate, fix it before moving on.
|
||||
|
||||
---
|
||||
|
||||
## Gate 1: SEO Signals
|
||||
|
||||
### Title & Headers
|
||||
- [ ] H1 contains primary keyword (naturally, not forced)
|
||||
- [ ] H1 is ≤70 characters
|
||||
- [ ] At least 2 H2s contain secondary keywords or related phrases
|
||||
- [ ] No two H2s are duplicates or near-duplicates
|
||||
- [ ] H1 differs from the title tag (they can overlap but shouldn't be identical)
|
||||
|
||||
### Keyword Presence
|
||||
- [ ] Primary keyword appears in the first 100 words
|
||||
- [ ] Primary keyword appears 3-5 times total (not more — stuffing tanks rankings)
|
||||
- [ ] Keyword variations appear naturally throughout
|
||||
- [ ] No keyword stuffing (reading it aloud sounds natural)
|
||||
|
||||
### Meta & Technical
|
||||
- [ ] Title tag: 50-60 characters, keyword-first where possible
|
||||
- [ ] Meta description: 150-160 characters, includes keyword, ends with hook or action
|
||||
- [ ] URL slug: short, keyword-first, lowercase, hyphens not underscores
|
||||
- [ ] Canonical URL is set
|
||||
- [ ] OG title and OG description written for social sharing
|
||||
|
||||
### Images & Media
|
||||
- [ ] At least one image present
|
||||
- [ ] All images have descriptive alt text (keyword included where natural)
|
||||
- [ ] Images are compressed (under 200KB each)
|
||||
- [ ] Image filenames are descriptive (not IMG_4832.jpg)
|
||||
|
||||
---
|
||||
|
||||
## Gate 2: Readability
|
||||
|
||||
### Score
|
||||
- [ ] Flesch Reading Ease score ≥ 60 (aim for 60-70 for professional audience; 70+ for general)
|
||||
- [ ] Run `scripts/content_scorer.py` — overall score ≥ 70
|
||||
|
||||
### Sentence & Paragraph Structure
|
||||
- [ ] Average sentence length ≤ 20 words
|
||||
- [ ] No single paragraph exceeds 4 sentences
|
||||
- [ ] No sentence exceeds 35 words (check and break if found)
|
||||
- [ ] Sentence length varies — not all short, not all long
|
||||
|
||||
### Voice & Clarity
|
||||
- [ ] Active voice dominant (passive voice < 20% of sentences)
|
||||
- [ ] No weasel words ("very," "really," "quite," "somewhat")
|
||||
- [ ] No jargon without explanation (for non-expert audiences)
|
||||
- [ ] All acronyms spelled out on first use
|
||||
- [ ] Contractions used where natural (improves readability)
|
||||
|
||||
---
|
||||
|
||||
## Gate 3: Structure & Content Quality
|
||||
|
||||
### Opening
|
||||
- [ ] Intro is ≤150 words
|
||||
- [ ] Intro does not start with "In today's..." or "Welcome to..."
|
||||
- [ ] Intro names the reader's problem or situation within the first 2 sentences
|
||||
- [ ] Intro clearly signals what the reader will get from this piece
|
||||
- [ ] No false promise in the intro (piece delivers what it hints at)
|
||||
|
||||
### Body
|
||||
- [ ] Every H2 section leads with its main point (buried leads = reader drop-off)
|
||||
- [ ] At least 2 concrete examples, case studies, or data points
|
||||
- [ ] All statistics and specific claims have citations or are labeled as estimates
|
||||
- [ ] No fluff paragraphs (every paragraph earns its place — if removing it changes nothing, cut it)
|
||||
- [ ] Visual break (table, list, callout, image) at least every 400 words
|
||||
|
||||
### Conclusion
|
||||
- [ ] Conclusion ≤150 words
|
||||
- [ ] Summarizes the core argument (not just "in conclusion...")
|
||||
- [ ] Includes one clear next step or CTA
|
||||
- [ ] Doesn't introduce new arguments or ideas
|
||||
|
||||
---
|
||||
|
||||
## Gate 4: Internal Linking
|
||||
|
||||
- [ ] 2-4 internal links to existing content on the site
|
||||
- [ ] Anchor text describes the destination (not "click here" or "this article")
|
||||
- [ ] Links tested and confirmed working (no 404s)
|
||||
- [ ] No excessive linking to the same page multiple times
|
||||
- [ ] At least one high-traffic page links to this piece (plan this before publishing)
|
||||
|
||||
---
|
||||
|
||||
## Gate 5: Factual Accuracy
|
||||
|
||||
- [ ] Every statistic cited with source (year + organization)
|
||||
- [ ] All external links go to credible sources (not competitors, not thin content)
|
||||
- [ ] No claims made without evidence or without "in my experience" qualifier
|
||||
- [ ] All product/feature mentions are accurate (check with product team if needed)
|
||||
- [ ] Quotes are attributed correctly and not paraphrased beyond recognition
|
||||
- [ ] No outdated information — check date-sensitive claims (pricing, regulations, stats)
|
||||
|
||||
---
|
||||
|
||||
## Gate 6: Brand & Voice
|
||||
|
||||
- [ ] Matches brand voice (check `marketing-context.md` if available)
|
||||
- [ ] Consistent POV throughout (first person, second person, or third — pick one)
|
||||
- [ ] Consistent tense (present or past — don't mix)
|
||||
- [ ] No off-brand claims (anything that overpromises, contradicts other content, or sounds unlike us)
|
||||
- [ ] CTA aligns with piece goal (don't pitch demo on an informational piece for beginners)
|
||||
|
||||
---
|
||||
|
||||
## Gate 7: Final Readthrough
|
||||
|
||||
Run a final read-aloud. Catch what scanning misses.
|
||||
|
||||
- [ ] Read the full piece aloud — anything that makes you stumble, fix it
|
||||
- [ ] The piece flows — section to section makes sense without re-reading
|
||||
- [ ] The headline still feels earned after reading the piece
|
||||
- [ ] You'd share this piece yourself (if not, it's not done)
|
||||
- [ ] No placeholder text, formatting artifacts, or draft notes left in
|
||||
|
||||
---
|
||||
|
||||
## Scoring Summary
|
||||
|
||||
| Gate | Status | Notes |
|
||||
|---|---|---|
|
||||
| SEO Signals | ✅ / ❌ | |
|
||||
| Readability | ✅ / ❌ | |
|
||||
| Structure & Quality | ✅ / ❌ | |
|
||||
| Internal Linking | ✅ / ❌ | |
|
||||
| Factual Accuracy | ✅ / ❌ | |
|
||||
| Brand & Voice | ✅ / ❌ | |
|
||||
| Final Readthrough | ✅ / ❌ | |
|
||||
|
||||
**Publish only when all 7 gates are green.**
|
||||
|
||||
If you're skipping a gate, document why. Conscious tradeoffs are fine. Unconscious shortcuts aren't.
|
||||
446
marketing-skill/content-production/scripts/content_scorer.py
Normal file
446
marketing-skill/content-production/scripts/content_scorer.py
Normal file
@@ -0,0 +1,446 @@
|
||||
#!/usr/bin/env python3
|
||||
"""content_scorer.py — scores content 0-100 on readability, SEO, structure, and engagement."""
|
||||
|
||||
import sys
|
||||
import re
|
||||
import json
|
||||
import math
|
||||
from collections import Counter
|
||||
|
||||
# ── Sample content for zero-config demo run ──────────────────────────────────
|
||||
SAMPLE_CONTENT = """
|
||||
Title: How to Reduce Churn in SaaS: 7 Proven Tactics That Actually Work
|
||||
|
||||
Introduction
|
||||
|
||||
Most SaaS companies discover their churn problem too late — after the customer has already left. By then, the damage is done. In this guide, you'll learn seven tactics to reduce churn before it happens, backed by data from 200+ SaaS companies.
|
||||
|
||||
## Why Customers Churn (It's Not What You Think)
|
||||
|
||||
Customers don't churn because your product is bad. They churn because they never saw value. A study by Mixpanel found that 60% of users who churn never completed onboarding. That's a product adoption problem, not a satisfaction problem.
|
||||
|
||||
Fix the adoption gap first. Everything else is downstream.
|
||||
|
||||
## Tactic 1: Instrument Your Activation Funnel
|
||||
|
||||
You can't fix what you can't see. Start by identifying your activation event — the moment users first experience your product's core value. For Slack, it's sending 2,000 messages. For Dropbox, it's saving a first file.
|
||||
|
||||
Map the funnel from signup to activation. Find where users drop off. That's your highest-leverage intervention point.
|
||||
|
||||
## Tactic 2: Segment Your Churn by Cohort
|
||||
|
||||
Not all churn is equal. A user who churns in week one is a different problem than a user who churns in month six. Cohort analysis breaks this apart.
|
||||
|
||||
Compare cohorts by: acquisition channel, onboarding path, company size, and feature usage. You'll find that certain cohorts churn 3-4x more than others. Focus retention efforts on your best cohorts first — don't try to save everyone.
|
||||
|
||||
## Tactic 3: Build a Customer Health Score
|
||||
|
||||
A health score is a composite signal that predicts churn before it happens. Common inputs include: login frequency, feature adoption rate, support ticket volume, and NPS response.
|
||||
|
||||
Weight each signal by its correlation with retention in your historical data. A score below 40 should trigger a customer success outreach. Don't wait for the cancellation request.
|
||||
|
||||
## Conclusion
|
||||
|
||||
Churn is a lagging indicator. By the time you see it, the problem happened weeks ago. Build systems that surface early signals — activation gaps, usage drops, health score declines — and act on them before customers decide to leave.
|
||||
|
||||
Start with one tactic. Instrument your activation funnel this week.
|
||||
"""
|
||||
|
||||
SAMPLE_KEYWORD = "reduce churn"
|
||||
SAMPLE_TITLE = "How to Reduce Churn in SaaS: 7 Proven Tactics That Actually Work"
|
||||
|
||||
|
||||
# ── Scoring functions ─────────────────────────────────────────────────────────
|
||||
|
||||
def count_syllables(word: str) -> int:
|
||||
"""Approximate syllable count using vowel-group heuristic."""
|
||||
word = word.lower().strip(".,!?;:")
|
||||
if not word:
|
||||
return 0
|
||||
vowels = "aeiouy"
|
||||
count = 0
|
||||
prev_vowel = False
|
||||
for ch in word:
|
||||
is_vowel = ch in vowels
|
||||
if is_vowel and not prev_vowel:
|
||||
count += 1
|
||||
prev_vowel = is_vowel
|
||||
# Adjust for silent e
|
||||
if word.endswith("e") and len(word) > 2:
|
||||
count = max(1, count - 1)
|
||||
return max(1, count)
|
||||
|
||||
|
||||
def flesch_reading_ease(text: str) -> float:
|
||||
"""
|
||||
Flesch Reading Ease score.
|
||||
206.835 - 1.015 * (words/sentences) - 84.6 * (syllables/words)
|
||||
Higher = easier. Target: 60-70 for professional content.
|
||||
"""
|
||||
sentences = re.split(r'[.!?]+', text)
|
||||
sentences = [s.strip() for s in sentences if s.strip()]
|
||||
n_sentences = max(1, len(sentences))
|
||||
|
||||
words = re.findall(r'\b[a-zA-Z]+\b', text)
|
||||
n_words = max(1, len(words))
|
||||
|
||||
n_syllables = sum(count_syllables(w) for w in words)
|
||||
|
||||
asl = n_words / n_sentences # avg sentence length
|
||||
asw = n_syllables / n_words # avg syllables per word
|
||||
|
||||
score = 206.835 - (1.015 * asl) - (84.6 * asw)
|
||||
return round(max(0.0, min(100.0, score)), 1)
|
||||
|
||||
|
||||
def score_readability(text: str) -> dict:
|
||||
"""Score readability 0-25 (25% of total)."""
|
||||
fre = flesch_reading_ease(text)
|
||||
|
||||
# FRE → points (target 60-70 for B2B)
|
||||
if fre >= 65:
|
||||
fre_points = 15
|
||||
elif fre >= 55:
|
||||
fre_points = 12
|
||||
elif fre >= 45:
|
||||
fre_points = 8
|
||||
elif fre >= 35:
|
||||
fre_points = 4
|
||||
else:
|
||||
fre_points = 0
|
||||
|
||||
# Sentence length variance
|
||||
sentences = re.split(r'[.!?]+', text)
|
||||
sentences = [s.strip() for s in sentences if len(s.split()) > 2]
|
||||
lengths = [len(s.split()) for s in sentences]
|
||||
if len(lengths) > 1:
|
||||
mean_len = sum(lengths) / len(lengths)
|
||||
variance = sum((l - mean_len) ** 2 for l in lengths) / len(lengths)
|
||||
std_dev = math.sqrt(variance)
|
||||
variance_points = min(10, int(std_dev)) # good variance = high std dev
|
||||
else:
|
||||
variance_points = 0
|
||||
|
||||
total = min(25, fre_points + variance_points)
|
||||
return {
|
||||
"score": total,
|
||||
"max": 25,
|
||||
"flesch_reading_ease": fre,
|
||||
"sentence_length_std_dev": round(math.sqrt(variance) if len(lengths) > 1 else 0, 1)
|
||||
}
|
||||
|
||||
|
||||
def score_seo(text: str, title: str = "", keyword: str = "") -> dict:
|
||||
"""Score SEO signals 0-25 (25% of total)."""
|
||||
text_lower = text.lower()
|
||||
title_lower = title.lower()
|
||||
keyword_lower = keyword.lower()
|
||||
|
||||
points = 0
|
||||
signals = {}
|
||||
|
||||
# Title contains keyword
|
||||
if keyword_lower and keyword_lower in title_lower:
|
||||
points += 7
|
||||
signals["keyword_in_title"] = True
|
||||
else:
|
||||
signals["keyword_in_title"] = False
|
||||
|
||||
# Keyword in first 100 words
|
||||
first_100 = " ".join(re.findall(r'\b\w+\b', text_lower)[:100])
|
||||
if keyword_lower and keyword_lower in first_100:
|
||||
points += 5
|
||||
signals["keyword_in_intro"] = True
|
||||
else:
|
||||
signals["keyword_in_intro"] = False
|
||||
|
||||
# Keyword density (target 0.5-2%)
|
||||
words = re.findall(r'\b\w+\b', text_lower)
|
||||
n_words = max(1, len(words))
|
||||
kw_words = keyword_lower.split()
|
||||
kw_count = 0
|
||||
for i in range(len(words) - len(kw_words) + 1):
|
||||
if words[i:i+len(kw_words)] == kw_words:
|
||||
kw_count += 1
|
||||
density = (kw_count * len(kw_words)) / n_words * 100
|
||||
signals["keyword_density_pct"] = round(density, 2)
|
||||
signals["keyword_occurrences"] = kw_count
|
||||
if 0.5 <= density <= 2.5:
|
||||
points += 5
|
||||
elif kw_count > 0:
|
||||
points += 2
|
||||
|
||||
# H2 headings present
|
||||
h2_count = len(re.findall(r'^## .+', text, re.MULTILINE))
|
||||
signals["h2_count"] = h2_count
|
||||
if h2_count >= 3:
|
||||
points += 5
|
||||
elif h2_count >= 1:
|
||||
points += 2
|
||||
|
||||
# Title length
|
||||
signals["title_length"] = len(title)
|
||||
if 30 <= len(title) <= 65:
|
||||
points += 3
|
||||
|
||||
total = min(25, points)
|
||||
return {"score": total, "max": 25, **signals}
|
||||
|
||||
|
||||
def score_structure(text: str) -> dict:
|
||||
"""Score structure 0-25 (25% of total)."""
|
||||
points = 0
|
||||
signals = {}
|
||||
|
||||
lines = text.strip().split('\n')
|
||||
|
||||
# Intro: first non-empty paragraph
|
||||
paragraphs = [p.strip() for p in text.split('\n\n') if p.strip()]
|
||||
signals["paragraph_count"] = len(paragraphs)
|
||||
|
||||
# Has intro (first paragraph isn't a heading)
|
||||
if paragraphs and not paragraphs[0].startswith('#'):
|
||||
intro_words = len(paragraphs[0].split())
|
||||
signals["intro_word_count"] = intro_words
|
||||
if 30 <= intro_words <= 200:
|
||||
points += 7
|
||||
elif intro_words > 0:
|
||||
points += 3
|
||||
else:
|
||||
signals["intro_word_count"] = 0
|
||||
|
||||
# Has H2 sections
|
||||
h2s = [l for l in lines if l.startswith('## ')]
|
||||
signals["h2_count"] = len(h2s)
|
||||
if len(h2s) >= 4:
|
||||
points += 8
|
||||
elif len(h2s) >= 2:
|
||||
points += 5
|
||||
elif len(h2s) >= 1:
|
||||
points += 2
|
||||
|
||||
# Has conclusion (last substantial paragraph)
|
||||
last_para = paragraphs[-1] if paragraphs else ""
|
||||
conclusion_words = len(last_para.split())
|
||||
signals["conclusion_word_count"] = conclusion_words
|
||||
conclusion_signals = ['conclusion', 'summary', 'final', 'start ', 'next step', 'action']
|
||||
if any(sig in last_para.lower() for sig in conclusion_signals) and conclusion_words >= 20:
|
||||
points += 7
|
||||
elif conclusion_words >= 30:
|
||||
points += 4
|
||||
|
||||
# Average paragraph length (web = shorter is better)
|
||||
para_lengths = [len(p.split()) for p in paragraphs if not p.startswith('#')]
|
||||
if para_lengths:
|
||||
avg_para_len = sum(para_lengths) / len(para_lengths)
|
||||
signals["avg_paragraph_word_count"] = round(avg_para_len, 1)
|
||||
if avg_para_len <= 80:
|
||||
points += 3
|
||||
else:
|
||||
signals["avg_paragraph_word_count"] = 0
|
||||
|
||||
total = min(25, points)
|
||||
return {"score": total, "max": 25, **signals}
|
||||
|
||||
|
||||
def score_engagement(text: str) -> dict:
|
||||
"""Score engagement signals 0-25 (25% of total)."""
|
||||
points = 0
|
||||
signals = {}
|
||||
text_lower = text.lower()
|
||||
|
||||
# Questions (engage readers, prompt thought)
|
||||
question_count = len(re.findall(r'\?', text))
|
||||
signals["question_count"] = question_count
|
||||
if question_count >= 3:
|
||||
points += 6
|
||||
elif question_count >= 1:
|
||||
points += 3
|
||||
|
||||
# Specific numbers / data points
|
||||
number_count = len(re.findall(r'\b\d+(?:\.\d+)?%?\b', text))
|
||||
signals["numbers_and_stats"] = number_count
|
||||
if number_count >= 5:
|
||||
points += 7
|
||||
elif number_count >= 2:
|
||||
points += 4
|
||||
elif number_count >= 1:
|
||||
points += 2
|
||||
|
||||
# Example signals
|
||||
example_phrases = ['for example', 'for instance', 'such as', 'like ', 'e.g.', 'case study',
|
||||
'imagine', 'consider', 'let\'s say', 'here\'s', 'specifically']
|
||||
example_count = sum(text_lower.count(p) for p in example_phrases)
|
||||
signals["example_signals"] = example_count
|
||||
if example_count >= 3:
|
||||
points += 6
|
||||
elif example_count >= 1:
|
||||
points += 3
|
||||
|
||||
# Lists (bulleted or numbered)
|
||||
list_items = len(re.findall(r'^\s*[-*•]\s+.+|^\s*\d+\.\s+.+', text, re.MULTILINE))
|
||||
signals["list_items"] = list_items
|
||||
if list_items >= 5:
|
||||
points += 6
|
||||
elif list_items >= 2:
|
||||
points += 3
|
||||
|
||||
total = min(25, points)
|
||||
return {"score": total, "max": 25, **signals}
|
||||
|
||||
|
||||
# ── Main ──────────────────────────────────────────────────────────────────────
|
||||
|
||||
def score_content(text: str, title: str = "", keyword: str = "") -> dict:
|
||||
readability = score_readability(text)
|
||||
seo = score_seo(text, title, keyword)
|
||||
structure = score_structure(text)
|
||||
engagement = score_engagement(text)
|
||||
|
||||
total = readability["score"] + seo["score"] + structure["score"] + engagement["score"]
|
||||
|
||||
grade = "D"
|
||||
if total >= 90:
|
||||
grade = "A+"
|
||||
elif total >= 80:
|
||||
grade = "A"
|
||||
elif total >= 70:
|
||||
grade = "B"
|
||||
elif total >= 60:
|
||||
grade = "C"
|
||||
|
||||
return {
|
||||
"total_score": total,
|
||||
"grade": grade,
|
||||
"sections": {
|
||||
"readability": readability,
|
||||
"seo": seo,
|
||||
"structure": structure,
|
||||
"engagement": engagement,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
def print_report(result: dict, title: str, keyword: str) -> None:
|
||||
total = result["total_score"]
|
||||
grade = result["grade"]
|
||||
s = result["sections"]
|
||||
|
||||
bar_filled = int(total / 5)
|
||||
bar = "█" * bar_filled + "░" * (20 - bar_filled)
|
||||
|
||||
print()
|
||||
print("╔══════════════════════════════════════════╗")
|
||||
print("║ CONTENT SCORER — REPORT ║")
|
||||
print("╚══════════════════════════════════════════╝")
|
||||
print(f" Title: {title[:55] or '(not provided)'}")
|
||||
print(f" Keyword: {keyword or '(not provided)'}")
|
||||
print()
|
||||
print(f" TOTAL SCORE: {total}/100 [{grade}]")
|
||||
print(f" [{bar}]")
|
||||
print()
|
||||
print(" ── Section Breakdown ──────────────────────")
|
||||
|
||||
sections = [
|
||||
("Readability", s["readability"]),
|
||||
("SEO Signals", s["seo"]),
|
||||
("Structure", s["structure"]),
|
||||
("Engagement", s["engagement"]),
|
||||
]
|
||||
for label, section in sections:
|
||||
sc = section["score"]
|
||||
mx = section["max"]
|
||||
bar2_filled = int(sc / mx * 10)
|
||||
bar2 = "█" * bar2_filled + "░" * (10 - bar2_filled)
|
||||
print(f" {label:<14} {sc:>2}/{mx} [{bar2}]")
|
||||
|
||||
print()
|
||||
print(" ── Key Signals ────────────────────────────")
|
||||
|
||||
r = s["readability"]
|
||||
print(f" Flesch Reading Ease: {r['flesch_reading_ease']} (target: 60-70)")
|
||||
print(f" Sentence length StDev: {r['sentence_length_std_dev']} (higher = more varied)")
|
||||
|
||||
seo_d = s["seo"]
|
||||
print(f" Keyword in title: {'✅' if seo_d.get('keyword_in_title') else '❌'}")
|
||||
print(f" Keyword in intro: {'✅' if seo_d.get('keyword_in_intro') else '❌'}")
|
||||
print(f" Keyword density: {seo_d.get('keyword_density_pct', 0)}% (target: 0.5-2.5%)")
|
||||
print(f" H2 sections: {seo_d.get('h2_count', 0)}")
|
||||
|
||||
st = s["structure"]
|
||||
print(f" Intro word count: {st.get('intro_word_count', 0)} (target: 30-200)")
|
||||
print(f" Avg paragraph length: {st.get('avg_paragraph_word_count', 0)} words (target: ≤80)")
|
||||
|
||||
en = s["engagement"]
|
||||
print(f" Questions: {en.get('question_count', 0)}")
|
||||
print(f" Stats/numbers: {en.get('numbers_and_stats', 0)}")
|
||||
print(f" Examples: {en.get('example_signals', 0)}")
|
||||
|
||||
print()
|
||||
print(" ── Recommendations ────────────────────────")
|
||||
if r["flesch_reading_ease"] < 55:
|
||||
print(" ⚠ Readability is low — shorten sentences and use simpler words")
|
||||
if not seo_d.get("keyword_in_title"):
|
||||
print(" ⚠ Primary keyword missing from title — add it naturally")
|
||||
if not seo_d.get("keyword_in_intro"):
|
||||
print(" ⚠ Primary keyword missing from first 100 words")
|
||||
if seo_d.get("h2_count", 0) < 3:
|
||||
print(" ⚠ Add more H2 sections — aim for at least 4")
|
||||
if st.get("avg_paragraph_word_count", 0) > 100:
|
||||
print(" ⚠ Paragraphs too long for web — break them up")
|
||||
if en.get("question_count", 0) == 0:
|
||||
print(" ⚠ Add at least one question to engage readers")
|
||||
if en.get("numbers_and_stats", 0) < 2:
|
||||
print(" ⚠ Thin on data — add specific numbers or stats")
|
||||
if total >= 70:
|
||||
print(" ✅ Content is publish-ready (score ≥ 70)")
|
||||
else:
|
||||
print(f" ❌ Score below 70 — address recommendations before publishing")
|
||||
|
||||
print()
|
||||
|
||||
|
||||
def main():
|
||||
title = ""
|
||||
keyword = ""
|
||||
text = ""
|
||||
|
||||
if len(sys.argv) == 1:
|
||||
# Demo mode — use embedded sample
|
||||
print("[Demo mode — using embedded sample content]")
|
||||
text = SAMPLE_CONTENT
|
||||
title = SAMPLE_TITLE
|
||||
keyword = SAMPLE_KEYWORD
|
||||
else:
|
||||
# Read from file
|
||||
filepath = sys.argv[1]
|
||||
keyword = sys.argv[2] if len(sys.argv) > 2 else ""
|
||||
try:
|
||||
with open(filepath, 'r', encoding='utf-8') as f:
|
||||
text = f.read()
|
||||
except FileNotFoundError:
|
||||
print(f"Error: file not found: {filepath}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
# Extract title from first H1 or first line
|
||||
for line in text.split('\n'):
|
||||
line = line.strip()
|
||||
if line.startswith('# '):
|
||||
title = line[2:].strip()
|
||||
break
|
||||
elif line.startswith('Title:'):
|
||||
title = line[6:].strip()
|
||||
break
|
||||
if not title and text:
|
||||
title = text.split('\n')[0][:80]
|
||||
|
||||
result = score_content(text, title, keyword)
|
||||
print_report(result, title, keyword)
|
||||
|
||||
# JSON output for programmatic use
|
||||
if "--json" in sys.argv:
|
||||
print(json.dumps(result, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,126 @@
|
||||
# Content Brief Template
|
||||
|
||||
> Fill in every field before writing starts. Blank fields mean assumptions. Assumptions mean rewrites.
|
||||
|
||||
---
|
||||
|
||||
## Basic Info
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Working Title** | |
|
||||
| **Target Publish Date** | |
|
||||
| **Author / Owner** | |
|
||||
| **Content Type** | Blog post / Guide / Case study / Comparison / Listicle |
|
||||
| **Target Length** | ~___ words |
|
||||
| **Goal** | Awareness / Lead gen / SEO / Thought leadership / Product education |
|
||||
|
||||
---
|
||||
|
||||
## SEO Targeting
|
||||
|
||||
| Field | Value |
|
||||
|---|---|
|
||||
| **Primary Keyword** | |
|
||||
| **Monthly Search Volume** | |
|
||||
| **Keyword Difficulty** | |
|
||||
| **Secondary Keywords** (2-4) | |
|
||||
| **Search Intent** | Informational / Commercial / Navigational |
|
||||
| **SERP Features to Target** | Featured snippet / FAQ / People Also Ask |
|
||||
|
||||
---
|
||||
|
||||
## Audience
|
||||
|
||||
**Who is reading this?**
|
||||
(Job title, company stage, pain point they're searching from)
|
||||
|
||||
**What do they already know?**
|
||||
(Level: beginner / intermediate / expert)
|
||||
|
||||
**What do they want to walk away with?**
|
||||
(The specific outcome or answer)
|
||||
|
||||
**What's their biggest objection or doubt?**
|
||||
(What might make them click away?)
|
||||
|
||||
---
|
||||
|
||||
## Angle & POV
|
||||
|
||||
**The core argument / unique angle:**
|
||||
(One sentence — what's our take that's different from the competition?)
|
||||
|
||||
**Why should they trust us on this?**
|
||||
(Our authority, experience, or data that backs the angle)
|
||||
|
||||
**What's the competition missing?**
|
||||
(Specific gap in top-ranking content we're exploiting)
|
||||
|
||||
---
|
||||
|
||||
## Structure
|
||||
|
||||
**H1 (draft):**
|
||||
|
||||
**Intro approach:**
|
||||
(Hook type: stat / story / counterintuitive claim / problem statement)
|
||||
|
||||
**H2 Outline:**
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
4.
|
||||
5.
|
||||
(Add more as needed)
|
||||
|
||||
**Conclusion approach:**
|
||||
(Summary + CTA or next step)
|
||||
|
||||
---
|
||||
|
||||
## Sources & Research
|
||||
|
||||
| Source | Type | Key Claim / Data Point |
|
||||
|---|---|---|
|
||||
| | Study / Report | |
|
||||
| | Expert quote | |
|
||||
| | Official docs | |
|
||||
| | Data / survey | |
|
||||
|
||||
**Minimum 3 sources required before drafting.**
|
||||
|
||||
---
|
||||
|
||||
## Internal Linking
|
||||
|
||||
**Links FROM this piece (to existing content):**
|
||||
- [Anchor text] → [URL / page title]
|
||||
- [Anchor text] → [URL / page title]
|
||||
|
||||
**Links TO this piece (from existing content):**
|
||||
- [Existing page] → link to this once published
|
||||
|
||||
---
|
||||
|
||||
## Competitive Pieces to Beat
|
||||
|
||||
| URL | Word Count | What They Do Well | What They Miss |
|
||||
|---|---|---|---|
|
||||
| | | | |
|
||||
| | | | |
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Ranks on page 1 for primary keyword within 6 months
|
||||
- [ ] Achieves target engagement (avg time on page > ___ min)
|
||||
- [ ] Generates ___ leads / clicks to product within 30 days
|
||||
- [ ] Other: ___
|
||||
|
||||
---
|
||||
|
||||
## Notes / Special Instructions
|
||||
|
||||
(Brand voice requirements, topics to avoid, tone calibration, product mentions)
|
||||
401
marketing-skill/content-strategy/SKILL.md
Normal file
401
marketing-skill/content-strategy/SKILL.md
Normal file
@@ -0,0 +1,401 @@
|
||||
---
|
||||
name: content-strategy
|
||||
description: "When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions \"content strategy,\" \"what should I write about,\" \"content ideas,\" \"blog strategy,\" \"topic clusters,\" or \"content planning.\" For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Content Strategy
|
||||
|
||||
You are a content strategist. Your goal is to help plan content that drives traffic, builds authority, and generates leads by being either searchable, shareable, or both.
|
||||
|
||||
## Before Planning
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, 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. Business Context
|
||||
- What does the company do?
|
||||
- Who is the ideal customer?
|
||||
- What's the primary goal for content? (traffic, leads, brand awareness, thought leadership)
|
||||
- What problems does your product solve?
|
||||
|
||||
### 2. Customer Research
|
||||
- What questions do customers ask before buying?
|
||||
- What objections come up in sales calls?
|
||||
- What topics appear repeatedly in support tickets?
|
||||
- What language do customers use to describe their problems?
|
||||
|
||||
### 3. Current State
|
||||
- Do you have existing content? What's working?
|
||||
- What resources do you have? (writers, budget, time)
|
||||
- What content formats can you produce? (written, video, audio)
|
||||
|
||||
### 4. Competitive Landscape
|
||||
- Who are your main competitors?
|
||||
- What content gaps exist in your market?
|
||||
|
||||
---
|
||||
|
||||
## Searchable vs Shareable
|
||||
|
||||
Every piece of content must be searchable, shareable, or both. Prioritize in that order—search traffic is the foundation.
|
||||
|
||||
**Searchable content** captures existing demand. Optimized for people actively looking for answers.
|
||||
|
||||
**Shareable content** creates demand. Spreads ideas and gets people talking.
|
||||
|
||||
### When Writing Searchable Content
|
||||
|
||||
- Target a specific keyword or question
|
||||
- Match search intent exactly—answer what the searcher wants
|
||||
- Use clear titles that match search queries
|
||||
- Structure with headings that mirror search patterns
|
||||
- Place keywords in title, headings, first paragraph, URL
|
||||
- Provide comprehensive coverage (don't leave questions unanswered)
|
||||
- Include data, examples, and links to authoritative sources
|
||||
- Optimize for AI/LLM discovery: clear positioning, structured content, brand consistency across the web
|
||||
|
||||
### When Writing Shareable Content
|
||||
|
||||
- Lead with a novel insight, original data, or counterintuitive take
|
||||
- Challenge conventional wisdom with well-reasoned arguments
|
||||
- Tell stories that make people feel something
|
||||
- Create content people want to share to look smart or help others
|
||||
- Connect to current trends or emerging problems
|
||||
- Share vulnerable, honest experiences others can learn from
|
||||
|
||||
---
|
||||
|
||||
## Content Types
|
||||
|
||||
### Searchable Content Types
|
||||
|
||||
**Use-Case Content**
|
||||
Formula: [persona] + [use-case]. Targets long-tail keywords.
|
||||
- "Project management for designers"
|
||||
- "Task tracking for developers"
|
||||
- "Client collaboration for freelancers"
|
||||
|
||||
**Hub and Spoke**
|
||||
Hub = comprehensive overview. Spokes = related subtopics.
|
||||
```
|
||||
/topic (hub)
|
||||
├── /topic/subtopic-1 (spoke)
|
||||
├── /topic/subtopic-2 (spoke)
|
||||
└── /topic/subtopic-3 (spoke)
|
||||
```
|
||||
Create hub first, then build spokes. Interlink strategically.
|
||||
|
||||
**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.
|
||||
|
||||
**Template Libraries**
|
||||
High-intent keywords + product adoption.
|
||||
- Target searches like "marketing plan template"
|
||||
- Provide immediate standalone value
|
||||
- Show how product enhances the template
|
||||
|
||||
### Shareable Content Types
|
||||
|
||||
**Thought Leadership**
|
||||
- Articulate concepts everyone feels but hasn't named
|
||||
- Challenge conventional wisdom with evidence
|
||||
- Share vulnerable, honest experiences
|
||||
|
||||
**Data-Driven Content**
|
||||
- Product data analysis (anonymized insights)
|
||||
- Public data analysis (uncover patterns)
|
||||
- Original research (run experiments, share results)
|
||||
|
||||
**Expert Roundups**
|
||||
15-30 experts answering one specific question. Built-in distribution.
|
||||
|
||||
**Case Studies**
|
||||
Structure: Challenge → Solution → Results → Key learnings
|
||||
|
||||
**Meta Content**
|
||||
Behind-the-scenes transparency. "How We Got Our First $5k MRR," "Why We Chose Debt Over VC."
|
||||
|
||||
For programmatic content at scale, see **programmatic-seo** skill.
|
||||
|
||||
---
|
||||
|
||||
## Content Pillars and Topic Clusters
|
||||
|
||||
Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.
|
||||
|
||||
Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth.
|
||||
|
||||
### How to Identify Pillars
|
||||
|
||||
1. **Product-led**: What problems does your product solve?
|
||||
2. **Audience-led**: What does your ICP need to learn?
|
||||
3. **Search-led**: What topics have volume in your space?
|
||||
4. **Competitor-led**: What are competitors ranking for?
|
||||
|
||||
### Pillar Structure
|
||||
|
||||
```
|
||||
Pillar Topic (Hub)
|
||||
├── Subtopic Cluster 1
|
||||
│ ├── Article A
|
||||
│ ├── Article B
|
||||
│ └── Article C
|
||||
├── Subtopic Cluster 2
|
||||
│ ├── Article D
|
||||
│ ├── Article E
|
||||
│ └── Article F
|
||||
└── Subtopic Cluster 3
|
||||
├── Article G
|
||||
├── Article H
|
||||
└── Article I
|
||||
```
|
||||
|
||||
### Pillar Criteria
|
||||
|
||||
Good pillars should:
|
||||
- Align with your product/service
|
||||
- Match what your audience cares about
|
||||
- Have search volume and/or social interest
|
||||
- Be broad enough for many subtopics
|
||||
|
||||
---
|
||||
|
||||
## Keyword Research by Buyer Stage
|
||||
|
||||
Map topics to the buyer's journey using proven keyword modifiers:
|
||||
|
||||
### Awareness Stage
|
||||
Modifiers: "what is," "how to," "guide to," "introduction to"
|
||||
|
||||
Example: If customers ask about project management basics:
|
||||
- "What is Agile Project Management"
|
||||
- "Guide to Sprint Planning"
|
||||
- "How to Run a Standup Meeting"
|
||||
|
||||
### Consideration Stage
|
||||
Modifiers: "best," "top," "vs," "alternatives," "comparison"
|
||||
|
||||
Example: If customers evaluate multiple tools:
|
||||
- "Best Project Management Tools for Remote Teams"
|
||||
- "Asana vs Trello vs Monday"
|
||||
- "Basecamp Alternatives"
|
||||
|
||||
### Decision Stage
|
||||
Modifiers: "pricing," "reviews," "demo," "trial," "buy"
|
||||
|
||||
Example: If pricing comes up in sales calls:
|
||||
- "Project Management Tool Pricing Comparison"
|
||||
- "How to Choose the Right Plan"
|
||||
- "[Product] Reviews"
|
||||
|
||||
### Implementation Stage
|
||||
Modifiers: "templates," "examples," "tutorial," "how to use," "setup"
|
||||
|
||||
Example: If support tickets show implementation struggles:
|
||||
- "Project Template Library"
|
||||
- "Step-by-Step Setup Tutorial"
|
||||
- "How to Use [Feature]"
|
||||
|
||||
---
|
||||
|
||||
## Content Ideation Sources
|
||||
|
||||
### 1. Keyword Data
|
||||
|
||||
If user provides keyword exports (Ahrefs, SEMrush, GSC), analyze for:
|
||||
- Topic clusters (group related keywords)
|
||||
- Buyer stage (awareness/consideration/decision/implementation)
|
||||
- Search intent (informational, commercial, transactional)
|
||||
- Quick wins (low competition + decent volume + high relevance)
|
||||
- Content gaps (keywords competitors rank for that you don't)
|
||||
|
||||
Output as prioritized table:
|
||||
| Keyword | Volume | Difficulty | Buyer Stage | Content Type | Priority |
|
||||
|
||||
### 2. Call Transcripts
|
||||
|
||||
If user provides sales or customer call transcripts, extract:
|
||||
- Questions asked → FAQ content or blog posts
|
||||
- Pain points → problems in their own words
|
||||
- Objections → content to address proactively
|
||||
- Language patterns → exact phrases to use (voice of customer)
|
||||
- Competitor mentions → what they compared you to
|
||||
|
||||
Output content ideas with supporting quotes.
|
||||
|
||||
### 3. Survey Responses
|
||||
|
||||
If user provides survey data, mine for:
|
||||
- Open-ended responses (topics and language)
|
||||
- Common themes (30%+ mention = high priority)
|
||||
- Resource requests (what they wish existed)
|
||||
- Content preferences (formats they want)
|
||||
|
||||
### 4. Forum Research
|
||||
|
||||
Use web search to find content ideas:
|
||||
|
||||
**Reddit:** `site:reddit.com [topic]`
|
||||
- Top posts in relevant subreddits
|
||||
- Questions and frustrations in comments
|
||||
- Upvoted answers (validates what resonates)
|
||||
|
||||
**Quora:** `site:quora.com [topic]`
|
||||
- Most-followed questions
|
||||
- Highly upvoted answers
|
||||
|
||||
**Other:** Indie Hackers, Hacker News, Product Hunt, industry Slack/Discord
|
||||
|
||||
Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
|
||||
|
||||
### 5. Competitor Analysis
|
||||
|
||||
Use web search to analyze competitor content:
|
||||
|
||||
**Find their content:** `site:competitor.com/blog`
|
||||
|
||||
**Analyze:**
|
||||
- Top-performing posts (comments, shares)
|
||||
- Topics covered repeatedly
|
||||
- Gaps they haven't covered
|
||||
- Case studies (customer problems, use cases, results)
|
||||
- Content structure (pillars, categories, formats)
|
||||
|
||||
**Identify opportunities:**
|
||||
- Topics you can cover better
|
||||
- Angles they're missing
|
||||
- Outdated content to improve on
|
||||
|
||||
### 6. Sales and Support Input
|
||||
|
||||
Extract from customer-facing teams:
|
||||
- Common objections
|
||||
- Repeated questions
|
||||
- Support ticket patterns
|
||||
- Success stories
|
||||
- Feature requests and underlying problems
|
||||
|
||||
---
|
||||
|
||||
## Prioritizing Content Ideas
|
||||
|
||||
Score each idea on four factors:
|
||||
|
||||
### 1. Customer Impact (40%)
|
||||
- How frequently did this topic come up in research?
|
||||
- What percentage of customers face this challenge?
|
||||
- How emotionally charged was this pain point?
|
||||
- What's the potential LTV of customers with this need?
|
||||
|
||||
### 2. Content-Market Fit (30%)
|
||||
- Does this align with problems your product solves?
|
||||
- Can you offer unique insights from customer research?
|
||||
- Do you have customer stories to support this?
|
||||
- Will this naturally lead to product interest?
|
||||
|
||||
### 3. Search Potential (20%)
|
||||
- What's the monthly search volume?
|
||||
- How competitive is this topic?
|
||||
- Are there related long-tail opportunities?
|
||||
- Is search interest growing or declining?
|
||||
|
||||
### 4. Resource Requirements (10%)
|
||||
- Do you have expertise to create authoritative content?
|
||||
- What additional research is needed?
|
||||
- What assets (graphics, data, examples) will you need?
|
||||
|
||||
### Scoring Template
|
||||
|
||||
| Idea | Customer Impact (40%) | Content-Market Fit (30%) | Search Potential (20%) | Resources (10%) | Total |
|
||||
|------|----------------------|-------------------------|----------------------|-----------------|-------|
|
||||
| Topic A | 8 | 9 | 7 | 6 | 8.0 |
|
||||
| Topic B | 6 | 7 | 9 | 8 | 7.1 |
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
When creating a content strategy, provide:
|
||||
|
||||
### 1. Content Pillars
|
||||
- 3-5 pillars with rationale
|
||||
- Subtopic clusters for each pillar
|
||||
- How pillars connect to product
|
||||
|
||||
### 2. Priority Topics
|
||||
For each recommended piece:
|
||||
- Topic/title
|
||||
- Searchable, shareable, or both
|
||||
- Content type (use-case, hub/spoke, thought leadership, etc.)
|
||||
- Target keyword and buyer stage
|
||||
- Why this topic (customer research backing)
|
||||
|
||||
### 3. Topic Cluster Map
|
||||
Visual or structured representation of how content interconnects.
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What patterns emerge from your last 10 customer conversations?
|
||||
2. What questions keep coming up in sales calls?
|
||||
3. Where are competitors' content efforts falling short?
|
||||
4. What unique insights from customer research aren't being shared elsewhere?
|
||||
5. Which existing content drives the most conversions, and why?
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these issues WITHOUT being asked when you notice them in context:
|
||||
|
||||
- **No content plan exists** → Immediately propose a 3-pillar starter strategy with 10 seed topics before asking more questions.
|
||||
- **User has content but low traffic** → Flag the searchable vs. shareable imbalance; run a quick audit of existing titles against keyword intent.
|
||||
- **User is writing content without a keyword target** → Warn that effort may be wasted; offer to identify the right keyword before they start writing.
|
||||
- **Content covers too many audiences** → Flag ICP dilution; recommend splitting pillars by persona or use-case.
|
||||
- **Competitor content clearly outranks them on core topics** → Trigger a gap analysis and surface quick-win opportunities where competition is lower.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| A content strategy | 3-5 pillars with rationale, subtopic clusters per pillar, product-content connection map |
|
||||
| Topic ideation | Prioritized topic table (keyword, volume, difficulty, buyer stage, content type, score) |
|
||||
| A content calendar | Weekly/monthly plan with topic, format, target keyword, and distribution channel |
|
||||
| Competitor analysis | Gap table showing competitor coverage vs. your coverage with opportunity ratings |
|
||||
| A content brief | Single-page brief: goal, audience, keyword, outline, CTA, internal links, proof points |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
|
||||
- **Bottom line first** — recommendation before rationale
|
||||
- **What + Why + How** — every strategy has all three
|
||||
- **Actions have owners and deadlines** — no "you might consider"
|
||||
- **Confidence tagging** — 🟢 high confidence / 🟡 medium / 🔴 assumption
|
||||
|
||||
Output format defaults: tables for prioritization, bullet lists for options, prose for rationale. Match depth to request — a quick question gets a quick answer, not a strategy doc.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **marketing-context**: USE as the foundation before any strategy work — reads product, audience, and brand context. NOT a substitute for this skill.
|
||||
- **copywriting**: USE when a topic is approved and it's time to write the actual piece. NOT for deciding what to write about.
|
||||
- **copy-editing**: USE to polish content drafts after writing. NOT for planning or strategy decisions.
|
||||
- **social-content**: USE when distributing approved content to social platforms. NOT for organic search strategy.
|
||||
- **marketing-ideas**: USE when brainstorming growth channels beyond content. NOT for deep keyword or topic planning.
|
||||
- **seo-audit**: USE when auditing existing content for technical and on-page issues. NOT for creating new strategy from scratch.
|
||||
- **content-production**: USE when scaling content volume with a repeatable production workflow. NOT for initial strategy definition.
|
||||
- **content-humanizer**: USE when AI-generated content needs to sound more authentic. NOT for topic selection.
|
||||
243
marketing-skill/content-strategy/scripts/topic_cluster_mapper.py
Executable file
243
marketing-skill/content-strategy/scripts/topic_cluster_mapper.py
Executable file
@@ -0,0 +1,243 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
topic_cluster_mapper.py — Groups keywords/topics into content clusters
|
||||
Usage:
|
||||
python3 topic_cluster_mapper.py --file keywords.txt
|
||||
python3 topic_cluster_mapper.py --json
|
||||
python3 topic_cluster_mapper.py # demo mode (20 marketing topics)
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
from collections import defaultdict
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Simple stemmer (no nltk)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
STOP_WORDS = {
|
||||
"a", "an", "the", "and", "or", "but", "in", "on", "at", "to", "for",
|
||||
"of", "with", "by", "from", "is", "are", "was", "were", "be", "been",
|
||||
"how", "what", "why", "when", "where", "who", "which", "that", "this",
|
||||
"it", "its", "do", "does", "your", "our", "my", "their", "we", "you",
|
||||
"get", "make", "use", "using", "used", "can", "will", "should", "best",
|
||||
}
|
||||
|
||||
|
||||
def simple_stem(word: str) -> str:
|
||||
"""Very simple suffix-stripping stemmer."""
|
||||
w = word.lower()
|
||||
if len(w) <= 3:
|
||||
return w
|
||||
# Order matters — try longer suffixes first
|
||||
suffixes = [
|
||||
"ization", "isation", "ational", "fulness", "ousness", "iveness",
|
||||
"iveness", "ingness", "ations", "nesses", "ators", "ation",
|
||||
"ating", "alism", "ality", "alize", "alise", "ation", "ator",
|
||||
"ness", "ment", "less", "tion", "sion", "tion", "ing", "ers",
|
||||
"ies", "ied", "ily", "ful", "ous", "ive", "ize", "ise", "est",
|
||||
"ed", "er", "ly", "al", "ic", "s",
|
||||
]
|
||||
for sfx in suffixes:
|
||||
if w.endswith(sfx) and len(w) - len(sfx) >= 3:
|
||||
return w[: -len(sfx)]
|
||||
return w
|
||||
|
||||
|
||||
def extract_stems(topic: str) -> set:
|
||||
words = re.findall(r"\b[a-zA-Z]+\b", topic.lower())
|
||||
return {simple_stem(w) for w in words if w not in STOP_WORDS and len(w) > 2}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Clustering
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def compute_similarity(stems_a: set, stems_b: set) -> float:
|
||||
"""Jaccard similarity between two stem sets."""
|
||||
if not stems_a or not stems_b:
|
||||
return 0.0
|
||||
intersection = stems_a & stems_b
|
||||
union = stems_a | stems_b
|
||||
return len(intersection) / len(union)
|
||||
|
||||
|
||||
def build_clusters(topics: list, threshold: float = 0.15) -> list:
|
||||
"""
|
||||
Greedy clustering: assign each topic to the first cluster it's
|
||||
similar-enough to; else start a new cluster.
|
||||
"""
|
||||
# Pre-compute stems
|
||||
topic_stems = {t: extract_stems(t) for t in topics}
|
||||
|
||||
clusters = [] # list of {"pillar": str, "topics": [str], "stems": set}
|
||||
|
||||
for topic in topics:
|
||||
t_stems = topic_stems[topic]
|
||||
best_cluster = None
|
||||
best_score = 0.0
|
||||
|
||||
for cluster in clusters:
|
||||
sim = compute_similarity(t_stems, cluster["stems"])
|
||||
if sim > best_score:
|
||||
best_score = sim
|
||||
best_cluster = cluster
|
||||
|
||||
if best_cluster and best_score >= threshold:
|
||||
best_cluster["topics"].append(topic)
|
||||
best_cluster["stems"] |= t_stems # grow cluster centroid
|
||||
else:
|
||||
clusters.append({
|
||||
"pillar": topic,
|
||||
"topics": [topic],
|
||||
"stems": set(t_stems),
|
||||
})
|
||||
|
||||
# Identify best pillar: topic with most shared stems to others in cluster
|
||||
for cluster in clusters:
|
||||
if len(cluster["topics"]) == 1:
|
||||
continue
|
||||
all_stems = [topic_stems[t] for t in cluster["topics"]]
|
||||
best_topic = cluster["topics"][0]
|
||||
best_conn = 0
|
||||
for i, topic in enumerate(cluster["topics"]):
|
||||
conn = sum(
|
||||
len(topic_stems[topic] & topic_stems[other])
|
||||
for j, other in enumerate(cluster["topics"]) if i != j
|
||||
)
|
||||
if conn > best_conn:
|
||||
best_conn = conn
|
||||
best_topic = topic
|
||||
cluster["pillar"] = best_topic
|
||||
|
||||
return clusters
|
||||
|
||||
|
||||
def build_output(topics: list, clusters: list) -> dict:
|
||||
cluster_output = []
|
||||
for i, c in enumerate(clusters, 1):
|
||||
supporting = [t for t in c["topics"] if t != c["pillar"]]
|
||||
cluster_output.append({
|
||||
"cluster_id": i,
|
||||
"pillar_topic": c["pillar"],
|
||||
"size": len(c["topics"]),
|
||||
"supporting_topics": supporting,
|
||||
"suggested_url_slug": re.sub(r"[^a-z0-9]+", "-", c["pillar"].lower()).strip("-"),
|
||||
})
|
||||
|
||||
# Sort by cluster size desc
|
||||
cluster_output.sort(key=lambda x: -x["size"])
|
||||
|
||||
return {
|
||||
"total_topics": len(topics),
|
||||
"total_clusters": len(clusters),
|
||||
"clusters": cluster_output,
|
||||
"recommendations": _make_recommendations(cluster_output),
|
||||
}
|
||||
|
||||
|
||||
def _make_recommendations(clusters: list) -> list:
|
||||
recs = []
|
||||
large = [c for c in clusters if c["size"] >= 3]
|
||||
singletons = [c for c in clusters if c["size"] == 1]
|
||||
|
||||
if large:
|
||||
recs.append(f"Create {len(large)} pillar page(s) for clusters with 3+ topics")
|
||||
if singletons:
|
||||
recs.append(
|
||||
f"{len(singletons)} singleton topic(s) — consider merging or expanding to form mini-clusters"
|
||||
)
|
||||
if clusters:
|
||||
biggest = clusters[0]
|
||||
recs.append(
|
||||
f"Highest-priority cluster: '{biggest['pillar_topic']}' "
|
||||
f"({biggest['size']} related topics) — start content here"
|
||||
)
|
||||
return recs
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Demo topics
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
DEMO_TOPICS = [
|
||||
"email marketing strategy",
|
||||
"email subject line tips",
|
||||
"email open rate optimization",
|
||||
"email automation workflows",
|
||||
"SEO keyword research",
|
||||
"on-page SEO optimization",
|
||||
"SEO content strategy",
|
||||
"technical SEO audit",
|
||||
"social media marketing",
|
||||
"social media content calendar",
|
||||
"Instagram marketing tips",
|
||||
"LinkedIn marketing for B2B",
|
||||
"content marketing ROI",
|
||||
"content strategy planning",
|
||||
"blog content ideas",
|
||||
"landing page conversion rate",
|
||||
"conversion rate optimization",
|
||||
"A/B testing landing pages",
|
||||
"paid ads budget allocation",
|
||||
"Google Ads campaign setup",
|
||||
]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Main
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Topic cluster mapper — groups keywords into content clusters."
|
||||
)
|
||||
parser.add_argument("--file", help="Text file with one topic/keyword per line")
|
||||
parser.add_argument("--threshold", type=float, default=0.15,
|
||||
help="Similarity threshold for clustering (default: 0.15)")
|
||||
parser.add_argument("--json", action="store_true", help="Output as JSON")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.file:
|
||||
with open(args.file, "r", encoding="utf-8") as f:
|
||||
topics = [line.strip() for line in f if line.strip()]
|
||||
else:
|
||||
topics = DEMO_TOPICS
|
||||
if not args.json:
|
||||
print("No input provided — running in demo mode with 20 marketing topics.\n")
|
||||
|
||||
if not topics:
|
||||
print("No topics found.", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
clusters = build_clusters(topics, threshold=args.threshold)
|
||||
output = build_output(topics, clusters)
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(output, indent=2))
|
||||
return
|
||||
|
||||
print("=" * 62)
|
||||
print(f" TOPIC CLUSTER MAP {output['total_topics']} topics → {output['total_clusters']} clusters")
|
||||
print("=" * 62)
|
||||
|
||||
for cluster in output["clusters"]:
|
||||
print(f"\n Cluster {cluster['cluster_id']} ({cluster['size']} topics)")
|
||||
print(f" ┌─ PILLAR: {cluster['pillar_topic']}")
|
||||
print(f" │ Slug: /{cluster['suggested_url_slug']}")
|
||||
for st in cluster["supporting_topics"]:
|
||||
print(f" └─ Supporting: {st}")
|
||||
|
||||
print("\n" + "=" * 62)
|
||||
print(" RECOMMENDATIONS")
|
||||
print("=" * 62)
|
||||
for rec in output["recommendations"]:
|
||||
print(f" • {rec}")
|
||||
print()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
491
marketing-skill/copy-editing/SKILL.md
Normal file
491
marketing-skill/copy-editing/SKILL.md
Normal file
@@ -0,0 +1,491 @@
|
||||
---
|
||||
name: copy-editing
|
||||
description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Copy Editing
|
||||
|
||||
You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before editing. Use brand voice and customer language from that context to guide your edits.
|
||||
|
||||
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
|
||||
|
||||
**Key principles:**
|
||||
- Don't change the core message; focus on enhancing it
|
||||
- Multiple focused passes beat one unfocused review
|
||||
- Each edit should have a clear reason
|
||||
- Preserve the author's voice while improving clarity
|
||||
|
||||
---
|
||||
|
||||
## The Seven Sweeps Framework
|
||||
|
||||
Edit copy through seven sequential passes, each focusing on one dimension. After each sweep, loop back to check previous sweeps aren't compromised.
|
||||
|
||||
### Sweep 1: Clarity
|
||||
|
||||
**Focus:** Can the reader understand what you're saying?
|
||||
|
||||
**What to check:**
|
||||
- Confusing sentence structures
|
||||
- Unclear pronoun references
|
||||
- Jargon or insider language
|
||||
- Ambiguous statements
|
||||
- Missing context
|
||||
|
||||
**Common clarity killers:**
|
||||
- Sentences trying to say too much
|
||||
- Abstract language instead of concrete
|
||||
- Assuming reader knowledge they don't have
|
||||
- Burying the point in qualifications
|
||||
|
||||
**Process:**
|
||||
1. Read through quickly, highlighting unclear parts
|
||||
2. Don't correct yet—just note problem areas
|
||||
3. After marking issues, recommend specific edits
|
||||
4. Verify edits maintain the original intent
|
||||
|
||||
**After this sweep:** Confirm the "Rule of One" (one main idea per section) and "You Rule" (copy speaks to the reader) are intact.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 2: Voice and Tone
|
||||
|
||||
**Focus:** Is the copy consistent in how it sounds?
|
||||
|
||||
**What to check:**
|
||||
- Shifts between formal and casual
|
||||
- Inconsistent brand personality
|
||||
- Mood changes that feel jarring
|
||||
- Word choices that don't match the brand
|
||||
|
||||
**Common voice issues:**
|
||||
- Starting casual, becoming corporate
|
||||
- Mixing "we" and "the company" references
|
||||
- Humor in some places, serious in others (unintentionally)
|
||||
- Technical language appearing randomly
|
||||
|
||||
**Process:**
|
||||
1. Read aloud to hear inconsistencies
|
||||
2. Mark where tone shifts unexpectedly
|
||||
3. Recommend edits that smooth transitions
|
||||
4. Ensure personality remains throughout
|
||||
|
||||
**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 3: So What
|
||||
|
||||
**Focus:** Does every claim answer "why should I care?"
|
||||
|
||||
**What to check:**
|
||||
- Features without benefits
|
||||
- Claims without consequences
|
||||
- Statements that don't connect to reader's life
|
||||
- Missing "which means..." bridges
|
||||
|
||||
**The So What test:**
|
||||
For every statement, ask "Okay, so what?" If the copy doesn't answer that question with a deeper benefit, it needs work.
|
||||
|
||||
❌ "Our platform uses AI-powered analytics"
|
||||
*So what?*
|
||||
✅ "Our AI-powered analytics surface insights you'd miss manually—so you can make better decisions in half the time"
|
||||
|
||||
**Common So What failures:**
|
||||
- Feature lists without benefit connections
|
||||
- Impressive-sounding claims that don't land
|
||||
- Technical capabilities without outcomes
|
||||
- Company achievements that don't help the reader
|
||||
|
||||
**Process:**
|
||||
1. Read each claim and literally ask "so what?"
|
||||
2. Highlight claims missing the answer
|
||||
3. Add the benefit bridge or deeper meaning
|
||||
4. Ensure benefits connect to real reader desires
|
||||
|
||||
**After this sweep:** Return to Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 4: Prove It
|
||||
|
||||
**Focus:** Is every claim supported with evidence?
|
||||
|
||||
**What to check:**
|
||||
- Unsubstantiated claims
|
||||
- Missing social proof
|
||||
- Assertions without backup
|
||||
- "Best" or "leading" without evidence
|
||||
|
||||
**Types of proof to look for:**
|
||||
- Testimonials with names and specifics
|
||||
- Case study references
|
||||
- Statistics and data
|
||||
- Third-party validation
|
||||
- Guarantees and risk reversals
|
||||
- Customer logos
|
||||
- Review scores
|
||||
|
||||
**Common proof gaps:**
|
||||
- "Trusted by thousands" (which thousands?)
|
||||
- "Industry-leading" (according to whom?)
|
||||
- "Customers love us" (show them saying it)
|
||||
- Results claims without specifics
|
||||
|
||||
**Process:**
|
||||
1. Identify every claim that needs proof
|
||||
2. Check if proof exists nearby
|
||||
3. Flag unsupported assertions
|
||||
4. Recommend adding proof or softening claims
|
||||
|
||||
**After this sweep:** Return to So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 5: Specificity
|
||||
|
||||
**Focus:** Is the copy concrete enough to be compelling?
|
||||
|
||||
**What to check:**
|
||||
- Vague language ("improve," "enhance," "optimize")
|
||||
- Generic statements that could apply to anyone
|
||||
- Round numbers that feel made up
|
||||
- Missing details that would make it real
|
||||
|
||||
**Specificity upgrades:**
|
||||
|
||||
| Vague | Specific |
|
||||
|-------|----------|
|
||||
| Save time | Save 4 hours every week |
|
||||
| Many customers | 2,847 teams |
|
||||
| Fast results | Results in 14 days |
|
||||
| Improve your workflow | Cut your reporting time in half |
|
||||
| Great support | Response within 2 hours |
|
||||
|
||||
**Common specificity issues:**
|
||||
- Adjectives doing the work nouns should do
|
||||
- Benefits without quantification
|
||||
- Outcomes without timeframes
|
||||
- Claims without concrete examples
|
||||
|
||||
**Process:**
|
||||
1. Highlight vague words and phrases
|
||||
2. Ask "Can this be more specific?"
|
||||
3. Add numbers, timeframes, or examples
|
||||
4. Remove content that can't be made specific (it's probably filler)
|
||||
|
||||
**After this sweep:** Return to Prove It, So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 6: Heightened Emotion
|
||||
|
||||
**Focus:** Does the copy make the reader feel something?
|
||||
|
||||
**What to check:**
|
||||
- Flat, informational language
|
||||
- Missing emotional triggers
|
||||
- Pain points mentioned but not felt
|
||||
- Aspirations stated but not evoked
|
||||
|
||||
**Emotional dimensions to consider:**
|
||||
- Pain of the current state
|
||||
- Frustration with alternatives
|
||||
- Fear of missing out
|
||||
- Desire for transformation
|
||||
- Pride in making smart choices
|
||||
- Relief from solving the problem
|
||||
|
||||
**Techniques for heightening emotion:**
|
||||
- Paint the "before" state vividly
|
||||
- Use sensory language
|
||||
- Tell micro-stories
|
||||
- Reference shared experiences
|
||||
- Ask questions that prompt reflection
|
||||
|
||||
**Process:**
|
||||
1. Read for emotional impact—does it move you?
|
||||
2. Identify flat sections that should resonate
|
||||
3. Add emotional texture while staying authentic
|
||||
4. Ensure emotion serves the message (not manipulation)
|
||||
|
||||
**After this sweep:** Return to Specificity, Prove It, So What, Voice and Tone, then Clarity.
|
||||
|
||||
---
|
||||
|
||||
### Sweep 7: Zero Risk
|
||||
|
||||
**Focus:** Have we removed every barrier to action?
|
||||
|
||||
**What to check:**
|
||||
- Friction near CTAs
|
||||
- Unanswered objections
|
||||
- Missing trust signals
|
||||
- Unclear next steps
|
||||
- Hidden costs or surprises
|
||||
|
||||
**Risk reducers to look for:**
|
||||
- Money-back guarantees
|
||||
- Free trials
|
||||
- "No credit card required"
|
||||
- "Cancel anytime"
|
||||
- Social proof near CTA
|
||||
- Clear expectations of what happens next
|
||||
- Privacy assurances
|
||||
|
||||
**Common risk issues:**
|
||||
- CTA asks for commitment without earning trust
|
||||
- Objections raised but not addressed
|
||||
- Fine print that creates doubt
|
||||
- Vague "Contact us" instead of clear next step
|
||||
|
||||
**Process:**
|
||||
1. Focus on sections near CTAs
|
||||
2. List every reason someone might hesitate
|
||||
3. Check if the copy addresses each concern
|
||||
4. Add risk reversals or trust signals as needed
|
||||
|
||||
**After this sweep:** Return through all previous sweeps one final time: Heightened Emotion, Specificity, Prove It, So What, Voice and Tone, Clarity.
|
||||
|
||||
---
|
||||
|
||||
## Quick-Pass Editing Checks
|
||||
|
||||
Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||
|
||||
### Word-Level Checks
|
||||
|
||||
**Cut these words:**
|
||||
- Very, really, extremely, incredibly (weak intensifiers)
|
||||
- Just, actually, basically (filler)
|
||||
- In order to (use "to")
|
||||
- That (often unnecessary)
|
||||
- Things, stuff (vague)
|
||||
|
||||
**Replace these:**
|
||||
|
||||
| Weak | Strong |
|
||||
|------|--------|
|
||||
| Utilize | Use |
|
||||
| Implement | Set up |
|
||||
| Leverage | Use |
|
||||
| Facilitate | Help |
|
||||
| Innovative | New |
|
||||
| Robust | Strong |
|
||||
| Seamless | Smooth |
|
||||
| Cutting-edge | New/Modern |
|
||||
|
||||
**Watch for:**
|
||||
- Adverbs (usually unnecessary)
|
||||
- Passive voice (switch to active)
|
||||
- Nominalizations (verb → noun: "make a decision" → "decide")
|
||||
|
||||
### Sentence-Level Checks
|
||||
|
||||
- One idea per sentence
|
||||
- Vary sentence length (mix short and long)
|
||||
- Front-load important information
|
||||
- Max 3 conjunctions per sentence
|
||||
- No more than 25 words (usually)
|
||||
|
||||
### Paragraph-Level Checks
|
||||
|
||||
- One topic per paragraph
|
||||
- Short paragraphs (2-4 sentences for web)
|
||||
- Strong opening sentences
|
||||
- Logical flow between paragraphs
|
||||
- White space for scannability
|
||||
|
||||
---
|
||||
|
||||
## Copy Editing Checklist
|
||||
|
||||
### Before You Start
|
||||
- [ ] Understand the goal of this copy
|
||||
- [ ] Know the target audience
|
||||
- [ ] Identify the desired action
|
||||
- [ ] Read through once without editing
|
||||
|
||||
### Clarity (Sweep 1)
|
||||
- [ ] Every sentence is immediately understandable
|
||||
- [ ] No jargon without explanation
|
||||
- [ ] Pronouns have clear references
|
||||
- [ ] No sentences trying to do too much
|
||||
|
||||
### Voice & Tone (Sweep 2)
|
||||
- [ ] Consistent formality level throughout
|
||||
- [ ] Brand personality maintained
|
||||
- [ ] No jarring shifts in mood
|
||||
- [ ] Reads well aloud
|
||||
|
||||
### So What (Sweep 3)
|
||||
- [ ] Every feature connects to a benefit
|
||||
- [ ] Claims answer "why should I care?"
|
||||
- [ ] Benefits connect to real desires
|
||||
- [ ] No impressive-but-empty statements
|
||||
|
||||
### Prove It (Sweep 4)
|
||||
- [ ] Claims are substantiated
|
||||
- [ ] Social proof is specific and attributed
|
||||
- [ ] Numbers and stats have sources
|
||||
- [ ] No unearned superlatives
|
||||
|
||||
### Specificity (Sweep 5)
|
||||
- [ ] Vague words replaced with concrete ones
|
||||
- [ ] Numbers and timeframes included
|
||||
- [ ] Generic statements made specific
|
||||
- [ ] Filler content removed
|
||||
|
||||
### Heightened Emotion (Sweep 6)
|
||||
- [ ] Copy evokes feeling, not just information
|
||||
- [ ] Pain points feel real
|
||||
- [ ] Aspirations feel achievable
|
||||
- [ ] Emotion serves the message authentically
|
||||
|
||||
### Zero Risk (Sweep 7)
|
||||
- [ ] Objections addressed near CTA
|
||||
- [ ] Trust signals present
|
||||
- [ ] Next steps are crystal clear
|
||||
- [ ] Risk reversals stated (guarantee, trial, etc.)
|
||||
|
||||
### Final Checks
|
||||
- [ ] No typos or grammatical errors
|
||||
- [ ] Consistent formatting
|
||||
- [ ] Links work (if applicable)
|
||||
- [ ] Core message preserved through all edits
|
||||
|
||||
---
|
||||
|
||||
## Common Copy Problems & Fixes
|
||||
|
||||
### Problem: Wall of Features
|
||||
**Symptom:** List of what the product does without why it matters
|
||||
**Fix:** Add "which means..." after each feature to bridge to benefits
|
||||
|
||||
### Problem: Corporate Speak
|
||||
**Symptom:** "Leverage synergies to optimize outcomes"
|
||||
**Fix:** Ask "How would a human say this?" and use those words
|
||||
|
||||
### Problem: Weak Opening
|
||||
**Symptom:** Starting with company history or vague statements
|
||||
**Fix:** Lead with the reader's problem or desired outcome
|
||||
|
||||
### Problem: Buried CTA
|
||||
**Symptom:** The ask comes after too much buildup, or isn't clear
|
||||
**Fix:** Make the CTA obvious, early, and repeated
|
||||
|
||||
### Problem: No Proof
|
||||
**Symptom:** "Customers love us" with no evidence
|
||||
**Fix:** Add specific testimonials, numbers, or case references
|
||||
|
||||
### Problem: Generic Claims
|
||||
**Symptom:** "We help businesses grow"
|
||||
**Fix:** Specify who, how, and by how much
|
||||
|
||||
### Problem: Mixed Audiences
|
||||
**Symptom:** Copy tries to speak to everyone, resonates with no one
|
||||
**Fix:** Pick one audience and write directly to them
|
||||
|
||||
### Problem: Feature Overload
|
||||
**Symptom:** Listing every capability, overwhelming the reader
|
||||
**Fix:** Focus on 3-5 key benefits that matter most to the audience
|
||||
|
||||
---
|
||||
|
||||
## Working with Copy Sweeps
|
||||
|
||||
When editing collaboratively:
|
||||
|
||||
1. **Run a sweep and present findings** - Show what you found, why it's an issue
|
||||
2. **Recommend specific edits** - Don't just identify problems; propose solutions
|
||||
3. **Request the updated copy** - Let the author make final decisions
|
||||
4. **Verify previous sweeps** - After each round of edits, re-check earlier sweeps
|
||||
5. **Repeat until clean** - Continue until a full sweep finds no new issues
|
||||
|
||||
This iterative process ensures each edit doesn't create new problems while respecting the author's ownership of the copy.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- [Plain English Alternatives](references/plain-english-alternatives.md): Replace complex words with simpler alternatives
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What's the goal of this copy? (Awareness, conversion, retention)
|
||||
2. What action should readers take?
|
||||
3. Are there specific concerns or known issues?
|
||||
4. What proof/evidence do you have available?
|
||||
|
||||
---
|
||||
|
||||
## When to Use Each Skill
|
||||
|
||||
| Task | Skill to Use |
|
||||
|------|--------------|
|
||||
| Writing new page copy from scratch | copywriting |
|
||||
| Reviewing and improving existing copy | copy-editing (this skill) |
|
||||
| Editing copy you just wrote | copy-editing (this skill) |
|
||||
| Structural or strategic page changes | page-cro |
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these issues WITHOUT being asked when you notice them in context:
|
||||
|
||||
- **Copy is submitted for editing without a stated goal** → Ask for the target action and audience before starting any sweeps; editing without this context guarantees misaligned feedback.
|
||||
- **Multiple tone shifts detected** → Flag Sweep 2 failure immediately; note the specific lines where voice breaks and propose fixes before continuing.
|
||||
- **Features outnumber benefits 2:1 or more** → Raise the "So What" alarm early in the review; this is the single most common conversion killer.
|
||||
- **Superlatives without proof** ("best," "leading," "most trusted") → Flag each instance in Sweep 4 and request the evidence or softer language alternatives.
|
||||
- **CTA is vague or buried** → Call this out in Sweep 7 before delivering any other feedback — it's the highest-impact fix.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| A full copy review | Seven-sweep structured report with specific issues, proposed edits, and rationale for each change |
|
||||
| A quick copy pass | Word- and sentence-level edits with tracked-change style annotations |
|
||||
| A copy editing checklist run | Completed checklist with pass/fail per section and priority fixes |
|
||||
| Specific sweep only (e.g., Clarity) | Focused report for that sweep with before/after examples |
|
||||
| Final polish | Clean edited version of the copy with a summary of all changes made |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
|
||||
- **Bottom line first** — state the overall copy health before diving into issues
|
||||
- **What + Why + How** — every flagged issue gets: what's wrong, why it hurts conversion, how to fix it
|
||||
- **Edits have reasons** — never change words without explaining the principle
|
||||
- **Confidence tagging** — 🟢 clear improvement / 🟡 judgment call / 🔴 needs author input
|
||||
|
||||
Deliver findings sweep-by-sweep. Don't dump all issues at once. Prioritize by conversion impact, not writing preference.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **marketing-context**: USE as foundation before editing — provides brand voice, ICP, and tone benchmarks. NOT a substitute for reading the copy itself.
|
||||
- **copywriting**: USE when the copy needs to be rewritten from scratch rather than edited. NOT for polishing existing drafts.
|
||||
- **content-strategy**: USE when the problem is what to say, not how to say it. NOT for line-level improvements.
|
||||
- **social-content**: USE when edited copy needs to be adapted for social platforms. NOT for page-level editing.
|
||||
- **marketing-ideas**: USE when the client needs a new marketing angle entirely. NOT for editorial improvement.
|
||||
- **content-humanizer**: USE when AI-generated copy needs to pass the human test before copy editing begins. NOT for structural review.
|
||||
- **ab-test-setup**: USE when disagreement on copy variants needs data to resolve. NOT for the editing process itself.
|
||||
@@ -0,0 +1,376 @@
|
||||
# Plain English Alternatives
|
||||
|
||||
Replace complex or pompous words with plain English alternatives.
|
||||
|
||||
Source: Plain English Campaign A-Z of Alternative Words (2001), Australian Government Style Manual (2024), plainlanguage.gov
|
||||
|
||||
---
|
||||
|
||||
## A
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| (an) absence of | no, none |
|
||||
| abundance | enough, plenty, many |
|
||||
| accede to | allow, agree to |
|
||||
| accelerate | speed up |
|
||||
| accommodate | meet, hold, house |
|
||||
| accomplish | do, finish, complete |
|
||||
| accordingly | so, therefore |
|
||||
| acknowledge | thank you for, confirm |
|
||||
| acquire | get, buy, obtain |
|
||||
| additional | extra, more |
|
||||
| adjacent | next to |
|
||||
| advantageous | useful, helpful |
|
||||
| advise | tell, say, inform |
|
||||
| aforesaid | this, earlier |
|
||||
| aggregate | total |
|
||||
| alleviate | ease, reduce |
|
||||
| allocate | give, share, assign |
|
||||
| alternative | other, choice |
|
||||
| ameliorate | improve |
|
||||
| anticipate | expect |
|
||||
| apparent | clear, obvious |
|
||||
| appreciable | large, noticeable |
|
||||
| appropriate | proper, right, suitable |
|
||||
| approximately | about, roughly |
|
||||
| ascertain | find out |
|
||||
| assistance | help |
|
||||
| at the present time | now |
|
||||
| attempt | try |
|
||||
| authorise | allow, let |
|
||||
|
||||
---
|
||||
|
||||
## B
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| belated | late |
|
||||
| beneficial | helpful, useful |
|
||||
| bestow | give |
|
||||
| by means of | by |
|
||||
|
||||
---
|
||||
|
||||
## C
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| calculate | work out |
|
||||
| cease | stop, end |
|
||||
| circumvent | avoid, get around |
|
||||
| clarification | explanation |
|
||||
| commence | start, begin |
|
||||
| communicate | tell, talk, write |
|
||||
| competent | able |
|
||||
| compile | collect, make |
|
||||
| complete | fill in, finish |
|
||||
| component | part |
|
||||
| comprise | include, make up |
|
||||
| (it is) compulsory | (you) must |
|
||||
| conceal | hide |
|
||||
| concerning | about |
|
||||
| consequently | so |
|
||||
| considerable | large, great, much |
|
||||
| constitute | make up, form |
|
||||
| consult | ask, talk to |
|
||||
| consumption | use |
|
||||
| currently | now |
|
||||
|
||||
---
|
||||
|
||||
## D
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| deduct | take off |
|
||||
| deem | treat as, consider |
|
||||
| defer | delay, put off |
|
||||
| deficiency | lack |
|
||||
| delete | remove, cross out |
|
||||
| demonstrate | show, prove |
|
||||
| denote | show, mean |
|
||||
| designate | name, appoint |
|
||||
| despatch/dispatch | send |
|
||||
| determine | decide, find out |
|
||||
| detrimental | harmful |
|
||||
| diminish | reduce, lessen |
|
||||
| discontinue | stop |
|
||||
| disseminate | spread, distribute |
|
||||
| documentation | papers, documents |
|
||||
| due to the fact that | because |
|
||||
| duration | time, length |
|
||||
| dwelling | home |
|
||||
|
||||
---
|
||||
|
||||
## E
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| economical | cheap, good value |
|
||||
| eligible | allowed, qualified |
|
||||
| elucidate | explain |
|
||||
| enable | allow |
|
||||
| encounter | meet |
|
||||
| endeavour | try |
|
||||
| enquire | ask |
|
||||
| ensure | make sure |
|
||||
| entitlement | right |
|
||||
| envisage | expect |
|
||||
| equivalent | equal, the same |
|
||||
| erroneous | wrong |
|
||||
| establish | set up, show |
|
||||
| evaluate | assess, test |
|
||||
| excessive | too much |
|
||||
| exclusively | only |
|
||||
| exempt | free from |
|
||||
| expedite | speed up |
|
||||
| expenditure | spending |
|
||||
| expire | run out |
|
||||
|
||||
---
|
||||
|
||||
## F
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| fabricate | make |
|
||||
| facilitate | help, make possible |
|
||||
| finalise | finish, complete |
|
||||
| following | after |
|
||||
| for the purpose of | to, for |
|
||||
| for the reason that | because |
|
||||
| forthwith | now, at once |
|
||||
| forward | send |
|
||||
| frequently | often |
|
||||
| furnish | give, provide |
|
||||
| furthermore | also, and |
|
||||
|
||||
---
|
||||
|
||||
## G-H
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| generate | produce, create |
|
||||
| henceforth | from now on |
|
||||
| hitherto | until now |
|
||||
|
||||
---
|
||||
|
||||
## I
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| if and when | if, when |
|
||||
| illustrate | show |
|
||||
| immediately | at once, now |
|
||||
| implement | carry out, do |
|
||||
| imply | suggest |
|
||||
| in accordance with | under, following |
|
||||
| in addition to | and, also |
|
||||
| in conjunction with | with |
|
||||
| in excess of | more than |
|
||||
| in lieu of | instead of |
|
||||
| in order to | to |
|
||||
| in receipt of | receive |
|
||||
| in relation to | about |
|
||||
| in respect of | about, for |
|
||||
| in the event of | if |
|
||||
| in the majority of instances | most, usually |
|
||||
| in the near future | soon |
|
||||
| in view of the fact that | because |
|
||||
| inception | start |
|
||||
| indicate | show, suggest |
|
||||
| inform | tell |
|
||||
| initiate | start, begin |
|
||||
| insert | put in |
|
||||
| instances | cases |
|
||||
| irrespective of | despite |
|
||||
| issue | give, send |
|
||||
|
||||
---
|
||||
|
||||
## L-M
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| (a) large number of | many |
|
||||
| liaise with | work with, talk to |
|
||||
| locality | place, area |
|
||||
| locate | find |
|
||||
| magnitude | size |
|
||||
| (it is) mandatory | (you) must |
|
||||
| manner | way |
|
||||
| modification | change |
|
||||
| moreover | also, and |
|
||||
|
||||
---
|
||||
|
||||
## N-O
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| negligible | small |
|
||||
| nevertheless | but, however |
|
||||
| notify | tell |
|
||||
| notwithstanding | despite, even if |
|
||||
| numerous | many |
|
||||
| objective | aim, goal |
|
||||
| (it is) obligatory | (you) must |
|
||||
| obtain | get |
|
||||
| occasioned by | caused by |
|
||||
| on behalf of | for |
|
||||
| on numerous occasions | often |
|
||||
| on receipt of | when you get |
|
||||
| on the grounds that | because |
|
||||
| operate | work, run |
|
||||
| optimum | best |
|
||||
| option | choice |
|
||||
| otherwise | or |
|
||||
| outstanding | unpaid |
|
||||
| owing to | because |
|
||||
|
||||
---
|
||||
|
||||
## P
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| partially | partly |
|
||||
| participate | take part |
|
||||
| particulars | details |
|
||||
| per annum | a year |
|
||||
| perform | do |
|
||||
| permit | let, allow |
|
||||
| personnel | staff, people |
|
||||
| peruse | read |
|
||||
| possess | have, own |
|
||||
| practically | almost |
|
||||
| predominant | main |
|
||||
| prescribe | set |
|
||||
| preserve | keep |
|
||||
| previous | earlier, before |
|
||||
| principal | main |
|
||||
| prior to | before |
|
||||
| proceed | go ahead |
|
||||
| procure | get |
|
||||
| prohibit | ban, stop |
|
||||
| promptly | quickly |
|
||||
| provide | give |
|
||||
| provided that | if |
|
||||
| provisions | rules, terms |
|
||||
| proximity | nearness |
|
||||
| purchase | buy |
|
||||
| pursuant to | under |
|
||||
|
||||
---
|
||||
|
||||
## R
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| reconsider | think again |
|
||||
| reduction | cut |
|
||||
| referred to as | called |
|
||||
| regarding | about |
|
||||
| reimburse | repay |
|
||||
| reiterate | repeat |
|
||||
| relating to | about |
|
||||
| remain | stay |
|
||||
| remainder | rest |
|
||||
| remuneration | pay |
|
||||
| render | make, give |
|
||||
| represent | stand for |
|
||||
| request | ask |
|
||||
| require | need |
|
||||
| residence | home |
|
||||
| retain | keep |
|
||||
| revised | changed, new |
|
||||
|
||||
---
|
||||
|
||||
## S
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| scrutinise | examine, check |
|
||||
| select | choose |
|
||||
| solely | only |
|
||||
| specified | given, stated |
|
||||
| state | say |
|
||||
| statutory | legal, by law |
|
||||
| subject to | depending on |
|
||||
| submit | send, give |
|
||||
| subsequent to | after |
|
||||
| subsequently | later |
|
||||
| substantial | large, much |
|
||||
| sufficient | enough |
|
||||
| supplement | add to |
|
||||
| supplementary | extra |
|
||||
|
||||
---
|
||||
|
||||
## T-U
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| terminate | end, stop |
|
||||
| thereafter | then |
|
||||
| thereby | by this |
|
||||
| thus | so |
|
||||
| to date | so far |
|
||||
| transfer | move |
|
||||
| transmit | send |
|
||||
| ultimately | in the end |
|
||||
| undertake | agree, do |
|
||||
| uniform | same |
|
||||
| utilise | use |
|
||||
|
||||
---
|
||||
|
||||
## V-Z
|
||||
|
||||
| Complex | Plain Alternative |
|
||||
|---------|-------------------|
|
||||
| variation | change |
|
||||
| virtually | almost |
|
||||
| visualise | imagine, see |
|
||||
| ways and means | ways |
|
||||
| whatsoever | any |
|
||||
| with a view to | to |
|
||||
| with effect from | from |
|
||||
| with reference to | about |
|
||||
| with regard to | about |
|
||||
| with respect to | about |
|
||||
| zone | area |
|
||||
|
||||
---
|
||||
|
||||
## Phrases to Remove Entirely
|
||||
|
||||
These phrases often add nothing. Delete them:
|
||||
|
||||
- a total of
|
||||
- absolutely
|
||||
- actually
|
||||
- all things being equal
|
||||
- as a matter of fact
|
||||
- at the end of the day
|
||||
- at this moment in time
|
||||
- basically
|
||||
- currently (when "now" or nothing works)
|
||||
- I am of the opinion that (use: I think)
|
||||
- in due course (use: soon, or say when)
|
||||
- in the final analysis
|
||||
- it should be understood
|
||||
- last but not least
|
||||
- obviously
|
||||
- of course
|
||||
- quite
|
||||
- really
|
||||
- the fact of the matter is
|
||||
- to all intents and purposes
|
||||
- very
|
||||
285
marketing-skill/copy-editing/scripts/readability_scorer.py
Executable file
285
marketing-skill/copy-editing/scripts/readability_scorer.py
Executable file
@@ -0,0 +1,285 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
readability_scorer.py — Readability metrics for marketing copy
|
||||
Usage:
|
||||
python3 readability_scorer.py --file copy.txt
|
||||
echo "Your text here" | python3 readability_scorer.py
|
||||
python3 readability_scorer.py # demo mode
|
||||
python3 readability_scorer.py --json
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import math
|
||||
import re
|
||||
import sys
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Word lists
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
FILLER_WORDS = [
|
||||
"very", "really", "just", "actually", "basically", "literally",
|
||||
"honestly", "totally", "absolutely", "definitely", "certainly",
|
||||
"obviously", "clearly", "quite", "rather", "somewhat", "fairly",
|
||||
"pretty", "simply", "truly", "genuinely", "essentially",
|
||||
]
|
||||
|
||||
# Simple passive voice detection: "was/were/is/are/been/being + past participle"
|
||||
PASSIVE_PATTERN = re.compile(
|
||||
r"\b(was|were|is|are|been|being|be|am)\s+(\w+ed|known|written|built|made|done|seen|given|taken|brought|thought|found|put|set|cut|read|let|hit|hurt|cost|led|felt|kept|left|meant|sent|spent|stood|told|wore|won|beat|lost|broke|chose|drove|flew|froze|grew|hid|rang|rode|rose|ran|sank|sang|spoke|swore|swam|threw|woke|wrote)\b",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
|
||||
ADVERB_PATTERN = re.compile(r"\b\w+ly\b", re.IGNORECASE)
|
||||
|
||||
# Syllable estimation: count vowel groups
|
||||
def count_syllables(word: str) -> int:
|
||||
word = word.lower().strip(".,!?;:\"'")
|
||||
if not word:
|
||||
return 0
|
||||
# Silent e
|
||||
if word.endswith("e") and len(word) > 2:
|
||||
word = word[:-1]
|
||||
count = len(re.findall(r"[aeiou]+", word))
|
||||
return max(1, count)
|
||||
|
||||
|
||||
def split_sentences(text: str) -> list:
|
||||
# Split on sentence-ending punctuation
|
||||
parts = re.split(r"(?<=[.!?])\s+", text.strip())
|
||||
return [p.strip() for p in parts if p.strip()]
|
||||
|
||||
|
||||
def split_words(text: str) -> list:
|
||||
return re.findall(r"\b[a-zA-Z]+\b", text)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Metrics
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def flesch_reading_ease(avg_sentence_len: float, avg_syllables: float) -> float:
|
||||
"""Flesch Reading Ease formula."""
|
||||
score = 206.835 - (1.015 * avg_sentence_len) - (84.6 * avg_syllables)
|
||||
return round(max(0.0, min(100.0, score)), 1)
|
||||
|
||||
|
||||
def flesch_kincaid_grade(avg_sentence_len: float, avg_syllables: float) -> float:
|
||||
"""Flesch-Kincaid Grade Level formula."""
|
||||
grade = (0.39 * avg_sentence_len) + (11.8 * avg_syllables) - 15.59
|
||||
return round(max(0.0, grade), 1)
|
||||
|
||||
|
||||
def ease_label(score: float) -> str:
|
||||
if score >= 90: return "Very Easy (5th grade)"
|
||||
if score >= 80: return "Easy (6th grade)"
|
||||
if score >= 70: return "Fairly Easy (7th grade)"
|
||||
if score >= 60: return "Standard (8-9th grade)"
|
||||
if score >= 50: return "Fairly Difficult (10-12th grade)"
|
||||
if score >= 30: return "Difficult (College)"
|
||||
return "Very Confusing (Professional)"
|
||||
|
||||
|
||||
def analyze_text(text: str) -> dict:
|
||||
sentences = split_sentences(text)
|
||||
words = split_words(text)
|
||||
|
||||
if not words:
|
||||
return {"error": "No readable text found."}
|
||||
|
||||
num_sentences = max(1, len(sentences))
|
||||
num_words = len(words)
|
||||
|
||||
# Syllables
|
||||
syllable_counts = [count_syllables(w) for w in words]
|
||||
total_syllables = sum(syllable_counts)
|
||||
|
||||
avg_sentence_len = num_words / num_sentences
|
||||
avg_word_len = sum(len(w) for w in words) / num_words
|
||||
avg_syllables_per_word = total_syllables / num_words
|
||||
|
||||
fre = flesch_reading_ease(avg_sentence_len, avg_syllables_per_word)
|
||||
fk_grade = flesch_kincaid_grade(avg_sentence_len, avg_syllables_per_word)
|
||||
|
||||
# Passive voice
|
||||
passive_matches = PASSIVE_PATTERN.findall(text)
|
||||
passive_count = len(passive_matches)
|
||||
passive_pct = round(passive_count / num_sentences * 100, 1)
|
||||
|
||||
# Adverbs
|
||||
adverb_matches = ADVERB_PATTERN.findall(text)
|
||||
# Filter obvious non-adverbs
|
||||
non_adverb = {"family", "early", "only", "likely", "nearly", "really",
|
||||
"daily", "weekly", "monthly", "yearly", "friendly", "lovely",
|
||||
"lonely", "lively", "elderly", "costly"}
|
||||
adverbs = [a for a in adverb_matches if a.lower() not in non_adverb]
|
||||
adverb_density = round(len(adverbs) / num_words * 100, 1)
|
||||
|
||||
# Filler words
|
||||
text_lower = text.lower()
|
||||
word_tokens_lower = [w.lower() for w in words]
|
||||
filler_found = {fw: word_tokens_lower.count(fw) for fw in FILLER_WORDS if fw in word_tokens_lower}
|
||||
filler_total = sum(filler_found.values())
|
||||
|
||||
# Scoring:
|
||||
# FRE already 0-100 (higher = easier = better for marketing copy)
|
||||
# Target for marketing: 60-80 range
|
||||
fre_score = fre # use as-is
|
||||
|
||||
return {
|
||||
"stats": {
|
||||
"word_count": num_words,
|
||||
"sentence_count": num_sentences,
|
||||
"avg_sentence_length": round(avg_sentence_len, 1),
|
||||
"avg_word_length": round(avg_word_len, 1),
|
||||
"avg_syllables_per_word": round(avg_syllables_per_word, 2),
|
||||
},
|
||||
"flesch_reading_ease": {
|
||||
"score": fre,
|
||||
"label": ease_label(fre),
|
||||
"target": "60-80 for most marketing copy",
|
||||
},
|
||||
"flesch_kincaid_grade": {
|
||||
"grade_level": fk_grade,
|
||||
"note": f"Equivalent to grade {fk_grade} reading level",
|
||||
},
|
||||
"passive_voice": {
|
||||
"count": passive_count,
|
||||
"percentage": passive_pct,
|
||||
"target": "<10%",
|
||||
"pass": passive_pct < 10,
|
||||
},
|
||||
"adverb_density": {
|
||||
"count": len(adverbs),
|
||||
"percentage": adverb_density,
|
||||
"examples": list(set(adverbs))[:8],
|
||||
"target": "<5%",
|
||||
"pass": adverb_density < 5,
|
||||
},
|
||||
"filler_words": {
|
||||
"total_count": filler_total,
|
||||
"breakdown": filler_found,
|
||||
"target": "0-3 per 100 words",
|
||||
"per_100_words": round(filler_total / num_words * 100, 1),
|
||||
},
|
||||
"overall_score": round(fre),
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Demo text
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
DEMO_TEXT = """
|
||||
Marketing copy needs to be clear, direct, and persuasive. When you write for your audience,
|
||||
you should always think about what they actually want to hear. Really good copy is basically
|
||||
about solving problems. It is very important to avoid using overly complicated language that
|
||||
might confuse the reader.
|
||||
|
||||
The best headlines are written by experts who truly understand their customers. A strong
|
||||
call-to-action is absolutely essential for any landing page. You need to make sure that
|
||||
every single word is earning its place on the page.
|
||||
|
||||
Studies show that shorter sentences improve comprehension. The average reader processes
|
||||
information faster when sentences contain fewer than 20 words. This is genuinely proven
|
||||
by research. Passive voice constructions are often used by writers who want to sound
|
||||
authoritative, but they can actually make copy feel distant and unclear.
|
||||
|
||||
Focus on benefits, not features. Tell the reader what they will gain. Use numbers when
|
||||
you can — "save 3 hours per week" beats "save time" every single time. Specificity
|
||||
builds trust. Vague promises are ignored.
|
||||
"""
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Main
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Readability scorer for marketing copy — Flesch, passive voice, filler words."
|
||||
)
|
||||
parser.add_argument("--file", help="Path to text file")
|
||||
parser.add_argument("--json", action="store_true", help="Output as JSON")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.file:
|
||||
with open(args.file, "r", encoding="utf-8", errors="replace") as f:
|
||||
text = f.read()
|
||||
elif not sys.stdin.isatty():
|
||||
text = sys.stdin.read()
|
||||
if not text.strip():
|
||||
text = DEMO_TEXT
|
||||
if not args.json:
|
||||
print("No input provided — running in demo mode.\n")
|
||||
else:
|
||||
text = DEMO_TEXT
|
||||
if not args.json:
|
||||
print("No input provided — running in demo mode.\n")
|
||||
|
||||
result = analyze_text(text)
|
||||
|
||||
if "error" in result:
|
||||
print(f"Error: {result['error']}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(result, indent=2))
|
||||
return
|
||||
|
||||
fre = result["flesch_reading_ease"]
|
||||
fk = result["flesch_kincaid_grade"]
|
||||
stats = result["stats"]
|
||||
passive = result["passive_voice"]
|
||||
adverbs = result["adverb_density"]
|
||||
fillers = result["filler_words"]
|
||||
score = result["overall_score"]
|
||||
|
||||
PASS = "✅"
|
||||
FAIL = "❌"
|
||||
|
||||
print("=" * 62)
|
||||
print(f" READABILITY REPORT Flesch Score: {fre['score']}/100")
|
||||
print("=" * 62)
|
||||
print(f" {fre['label']}")
|
||||
print(f" Target: {fre['target']}")
|
||||
print()
|
||||
print(f" 📊 Stats")
|
||||
print(f" Words: {stats['word_count']}")
|
||||
print(f" Sentences: {stats['sentence_count']}")
|
||||
print(f" Avg sentence length:{stats['avg_sentence_length']} words")
|
||||
print(f" Avg word length: {stats['avg_word_length']} chars")
|
||||
print(f" Syllables/word: {stats['avg_syllables_per_word']}")
|
||||
print()
|
||||
print(f" 📐 Flesch-Kincaid Grade Level: {fk['grade_level']}")
|
||||
print(f" {fk['note']}")
|
||||
print()
|
||||
|
||||
pv_icon = PASS if passive["pass"] else FAIL
|
||||
print(f" {pv_icon} Passive Voice: {passive['count']} instances ({passive['percentage']}%)")
|
||||
print(f" Target: {passive['target']}")
|
||||
|
||||
av_icon = PASS if adverbs["pass"] else FAIL
|
||||
print(f" {av_icon} Adverb Density: {adverbs['count']} adverbs ({adverbs['percentage']}%)")
|
||||
if adverbs["examples"]:
|
||||
print(f" Examples: {', '.join(adverbs['examples'][:5])}")
|
||||
|
||||
filler_ok = fillers["per_100_words"] <= 3
|
||||
fw_icon = PASS if filler_ok else FAIL
|
||||
print(f" {fw_icon} Filler Words: {fillers['total_count']} total ({fillers['per_100_words']} per 100 words)")
|
||||
if fillers["breakdown"]:
|
||||
top = sorted(fillers["breakdown"].items(), key=lambda x: -x[1])[:5]
|
||||
print(f" Top: {', '.join(f'{w}({c})' for w,c in top)}")
|
||||
|
||||
print()
|
||||
print("=" * 62)
|
||||
score_bar_len = round(score / 10)
|
||||
bar = "█" * score_bar_len + "░" * (10 - score_bar_len)
|
||||
print(f" Readability Score: [{bar}] {score}/100")
|
||||
print("=" * 62)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
296
marketing-skill/copywriting/SKILL.md
Normal file
296
marketing-skill/copywriting/SKILL.md
Normal file
@@ -0,0 +1,296 @@
|
||||
---
|
||||
name: copywriting
|
||||
description: "When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says \"write copy for,\" \"improve this copy,\" \"rewrite this page,\" \"marketing copy,\" \"headline help,\" or \"CTA copy.\" For email copy, see email-sequence. For popup copy, see popup-cro."
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Copywriting
|
||||
|
||||
You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.
|
||||
|
||||
## Before Writing
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, 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. Page Purpose
|
||||
- What type of page? (homepage, landing page, pricing, feature, about)
|
||||
- What is the ONE primary action you want visitors to take?
|
||||
|
||||
### 2. Audience
|
||||
- Who is the ideal customer?
|
||||
- What problem are they trying to solve?
|
||||
- What objections or hesitations do they have?
|
||||
- What language do they use to describe their problem?
|
||||
|
||||
### 3. Product/Offer
|
||||
- What are you selling or offering?
|
||||
- What makes it different from alternatives?
|
||||
- What's the key transformation or outcome?
|
||||
- Any proof points (numbers, testimonials, case studies)?
|
||||
|
||||
### 4. Context
|
||||
- Where is traffic coming from? (ads, organic, email)
|
||||
- What do visitors already know before arriving?
|
||||
|
||||
---
|
||||
|
||||
## Copywriting Principles
|
||||
|
||||
### Clarity Over Cleverness
|
||||
If you have to choose between clear and creative, choose clear.
|
||||
|
||||
### Benefits Over Features
|
||||
Features: What it does. Benefits: What that means for the customer.
|
||||
|
||||
### Specificity Over Vagueness
|
||||
- Vague: "Save time on your workflow"
|
||||
- Specific: "Cut your weekly reporting from 4 hours to 15 minutes"
|
||||
|
||||
### Customer Language Over Company Language
|
||||
Use words your customers use. Mirror voice-of-customer from reviews, interviews, support tickets.
|
||||
|
||||
### One Idea Per Section
|
||||
Each section should advance one argument. Build a logical flow down the page.
|
||||
|
||||
---
|
||||
|
||||
## Writing Style Rules
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Simple over complex** — "Use" not "utilize," "help" not "facilitate"
|
||||
2. **Specific over vague** — Avoid "streamline," "optimize," "innovative"
|
||||
3. **Active over passive** — "We generate reports" not "Reports are generated"
|
||||
4. **Confident over qualified** — Remove "almost," "very," "really"
|
||||
5. **Show over tell** — Describe the outcome instead of using adverbs
|
||||
6. **Honest over sensational** — Never fabricate statistics or testimonials
|
||||
|
||||
### Quick Quality Check
|
||||
|
||||
- Jargon that could confuse outsiders?
|
||||
- Sentences trying to do too much?
|
||||
- Passive voice constructions?
|
||||
- Exclamation points? (remove them)
|
||||
- Marketing buzzwords without substance?
|
||||
|
||||
For thorough line-by-line review, use the **copy-editing** skill after your draft.
|
||||
|
||||
---
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Be Direct
|
||||
Get to the point. Don't bury the value in qualifications.
|
||||
|
||||
❌ Slack lets you share files instantly, from documents to images, directly in your conversations
|
||||
|
||||
✅ Need to share a screenshot? Send as many documents, images, and audio files as your heart desires.
|
||||
|
||||
### Use Rhetorical Questions
|
||||
Questions engage readers and make them think about their own situation.
|
||||
- "Hate returning stuff to Amazon?"
|
||||
- "Tired of chasing approvals?"
|
||||
|
||||
### Use Analogies When Helpful
|
||||
Analogies make abstract concepts concrete and memorable.
|
||||
|
||||
### Pepper in Humor (When Appropriate)
|
||||
Puns and wit make copy memorable—but only if it fits the brand and doesn't undermine clarity.
|
||||
|
||||
---
|
||||
|
||||
## Page Structure Framework
|
||||
|
||||
### Above the Fold
|
||||
|
||||
**Headline**
|
||||
- Your single most important message
|
||||
- Communicate core value proposition
|
||||
- Specific > generic
|
||||
|
||||
**Example formulas:**
|
||||
- "{Achieve outcome} without {pain point}"
|
||||
- "The {category} for {audience}"
|
||||
- "Never {unpleasant event} again"
|
||||
- "{Question highlighting main pain point}"
|
||||
|
||||
**For comprehensive headline formulas**: See [references/copy-frameworks.md](references/copy-frameworks.md)
|
||||
|
||||
**For natural transition phrases**: See [references/natural-transitions.md](references/natural-transitions.md)
|
||||
|
||||
**Subheadline**
|
||||
- Expands on headline
|
||||
- Adds specificity
|
||||
- 1-2 sentences max
|
||||
|
||||
**Primary CTA**
|
||||
- Action-oriented button text
|
||||
- Communicate what they get: "Start Free Trial" > "Sign Up"
|
||||
|
||||
### Core Sections
|
||||
|
||||
| Section | Purpose |
|
||||
|---------|---------|
|
||||
| Social Proof | Build credibility (logos, stats, testimonials) |
|
||||
| Problem/Pain | Show you understand their situation |
|
||||
| Solution/Benefits | Connect to outcomes (3-5 key benefits) |
|
||||
| How It Works | Reduce perceived complexity (3-4 steps) |
|
||||
| Objection Handling | FAQ, comparisons, guarantees |
|
||||
| Final CTA | Recap value, repeat CTA, risk reversal |
|
||||
|
||||
**For detailed section types and page templates**: See [references/copy-frameworks.md](references/copy-frameworks.md)
|
||||
|
||||
---
|
||||
|
||||
## CTA Copy Guidelines
|
||||
|
||||
**Weak CTAs (avoid):**
|
||||
- Submit, Sign Up, Learn More, Click Here, Get Started
|
||||
|
||||
**Strong CTAs (use):**
|
||||
- Start Free Trial
|
||||
- Get [Specific Thing]
|
||||
- See [Product] in Action
|
||||
- Create Your First [Thing]
|
||||
- Download the Guide
|
||||
|
||||
**Formula:** [Action Verb] + [What They Get] + [Qualifier if needed]
|
||||
|
||||
Examples:
|
||||
- "Start My Free Trial"
|
||||
- "Get the Complete Checklist"
|
||||
- "See Pricing for My Team"
|
||||
|
||||
---
|
||||
|
||||
## Page-Specific Guidance
|
||||
|
||||
### Homepage
|
||||
- Serve multiple audiences without being generic
|
||||
- Lead with broadest value proposition
|
||||
- Provide clear paths for different visitor intents
|
||||
|
||||
### Landing Page
|
||||
- Single message, single CTA
|
||||
- Match headline to ad/traffic source
|
||||
- Complete argument on one page
|
||||
|
||||
### Pricing Page
|
||||
- Help visitors choose the right plan
|
||||
- Address "which is right for me?" anxiety
|
||||
- Make recommended plan obvious
|
||||
|
||||
### Feature Page
|
||||
- Connect feature → benefit → outcome
|
||||
- Show use cases and examples
|
||||
- Clear path to try or buy
|
||||
|
||||
### About Page
|
||||
- Tell the story of why you exist
|
||||
- Connect mission to customer benefit
|
||||
- Still include a CTA
|
||||
|
||||
---
|
||||
|
||||
## Voice and Tone
|
||||
|
||||
Before writing, establish:
|
||||
|
||||
**Formality level:**
|
||||
- Casual/conversational
|
||||
- Professional but friendly
|
||||
- Formal/enterprise
|
||||
|
||||
**Brand personality:**
|
||||
- Playful or serious?
|
||||
- Bold or understated?
|
||||
- Technical or accessible?
|
||||
|
||||
Maintain consistency, but adjust intensity:
|
||||
- Headlines can be bolder
|
||||
- Body copy should be clearer
|
||||
- CTAs should be action-oriented
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
When writing copy, provide:
|
||||
|
||||
### Page Copy
|
||||
Organized by section:
|
||||
- Headline, Subheadline, CTA
|
||||
- Section headers and body copy
|
||||
- Secondary CTAs
|
||||
|
||||
### Annotations
|
||||
For key elements, explain:
|
||||
- Why you made this choice
|
||||
- What principle it applies
|
||||
|
||||
### Alternatives
|
||||
For headlines and CTAs, provide 2-3 options:
|
||||
- Option A: [copy] — [rationale]
|
||||
- Option B: [copy] — [rationale]
|
||||
|
||||
### Meta Content (if relevant)
|
||||
- Page title (for SEO)
|
||||
- Meta description
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
Surface these issues WITHOUT being asked when you notice them in context:
|
||||
|
||||
- **Copy opens with "We" or the company name** → Flag it immediately; reframe to lead with the customer's outcome or problem.
|
||||
- **Value proposition is vague** (e.g., "the best platform for teams") → Push for specificity: who, what outcome, how long.
|
||||
- **Features are listed without benefits** → Add "which means..." bridges before delivering the draft.
|
||||
- **No social proof is provided** → Flag this as a conversion risk and ask for testimonials, numbers, or case study references.
|
||||
- **CTA uses weak verbs** (Submit, Learn More, Sign Up) → Propose action-outcome alternatives before finalising.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| When you ask for... | You get... |
|
||||
|---------------------|------------|
|
||||
| Homepage copy | Full page copy organized by section: headline, subheadline, CTA, social proof, benefits, how it works, objection handling, final CTA |
|
||||
| Landing page | Single-focus copy with headline, body, and one CTA — annotated with conversion rationale |
|
||||
| Headline options | 5 headline variants using different formulas (outcome, pain, question, bold claim, category) |
|
||||
| CTA copy | 3-5 CTA options with formula and rationale for each |
|
||||
| Page copy review | Section-by-section feedback on clarity, benefit framing, and CTA strength |
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
All output follows the structured communication standard:
|
||||
|
||||
- **Bottom line first** — deliver the copy, then explain the choices
|
||||
- **What + Why + How** — every copy decision has a principle behind it
|
||||
- **Annotations are mandatory** — never ship copy without explaining the key choices
|
||||
- **Confidence tagging** — 🟢 strong recommendation / 🟡 test this / 🔴 needs proof to land
|
||||
|
||||
Always provide alternatives for high-stakes elements (headline, CTA). Never deliver one option and call it done.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **marketing-context**: USE as the foundation before writing — loads brand voice, ICP, and positioning context. NOT a substitute for this skill.
|
||||
- **copy-editing**: USE after your first draft is complete to systematically polish and improve. NOT for writing new copy from scratch.
|
||||
- **content-strategy**: USE when deciding what topics or pages to create before writing. NOT for the writing itself.
|
||||
- **social-content**: USE when adapting finished copy for social platforms. NOT for long-form page copy.
|
||||
- **marketing-ideas**: USE when brainstorming which marketing assets to build. NOT for writing the copy for those assets.
|
||||
- **content-humanizer**: USE when AI-drafted copy sounds robotic or templated. NOT for strategic decisions.
|
||||
- **ab-test-setup**: USE to design experiments testing copy variants. NOT for writing the copy itself.
|
||||
- **email-sequence**: USE for email copywriting specifically. NOT for page or landing page copy.
|
||||
338
marketing-skill/copywriting/references/copy-frameworks.md
Normal file
338
marketing-skill/copywriting/references/copy-frameworks.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Copy Frameworks Reference
|
||||
|
||||
Headline formulas, page section types, and structural templates.
|
||||
|
||||
## Headline Formulas
|
||||
|
||||
### Outcome-Focused
|
||||
|
||||
**{Achieve desirable outcome} without {pain point}**
|
||||
> Understand how users are really experiencing your site without drowning in numbers
|
||||
|
||||
**{Achieve desirable outcome} by {how product makes it possible}**
|
||||
> Generate more leads by seeing which companies visit your site
|
||||
|
||||
**Turn {input} into {outcome}**
|
||||
> Turn your hard-earned sales into repeat customers
|
||||
|
||||
**[Achieve outcome] in [timeframe]**
|
||||
> Get your tax refund in 10 days
|
||||
|
||||
---
|
||||
|
||||
### Problem-Focused
|
||||
|
||||
**Never {unpleasant event} again**
|
||||
> Never miss a sales opportunity again
|
||||
|
||||
**{Question highlighting the main pain point}**
|
||||
> Hate returning stuff to Amazon?
|
||||
|
||||
**Stop [pain]. Start [pleasure].**
|
||||
> Stop chasing invoices. Start getting paid on time.
|
||||
|
||||
---
|
||||
|
||||
### Audience-Focused
|
||||
|
||||
**{Key feature/product type} for {target audience}**
|
||||
> Advanced analytics for Shopify e-commerce
|
||||
|
||||
**{Key feature/product type} for {target audience} to {what it's used for}**
|
||||
> An online whiteboard for teams to ideate and brainstorm together
|
||||
|
||||
**You don't have to {skills or resources} to {achieve desirable outcome}**
|
||||
> With Ahrefs, you don't have to be an SEO pro to rank higher and get more traffic
|
||||
|
||||
---
|
||||
|
||||
### Differentiation-Focused
|
||||
|
||||
**The {opposite of usual process} way to {achieve desirable outcome}**
|
||||
> The easiest way to turn your passion into income
|
||||
|
||||
**The [category] that [key differentiator]**
|
||||
> The CRM that updates itself
|
||||
|
||||
---
|
||||
|
||||
### Proof-Focused
|
||||
|
||||
**[Number] [people] use [product] to [outcome]**
|
||||
> 50,000 marketers use Drip to send better emails
|
||||
|
||||
**{Key benefit of your product}**
|
||||
> Sound clear in online meetings
|
||||
|
||||
---
|
||||
|
||||
### Additional Formulas
|
||||
|
||||
**The simple way to {outcome}**
|
||||
> The simple way to track your time
|
||||
|
||||
**Finally, {category} that {benefit}**
|
||||
> Finally, accounting software that doesn't suck
|
||||
|
||||
**{Outcome} without {common pain}**
|
||||
> Build your website without writing code
|
||||
|
||||
**Get {benefit} from your {thing}**
|
||||
> Get more revenue from your existing traffic
|
||||
|
||||
**{Action verb} your {thing} like {admirable example}**
|
||||
> Market your SaaS like a Fortune 500
|
||||
|
||||
**What if you could {desirable outcome}?**
|
||||
> What if you could close deals 30% faster?
|
||||
|
||||
**Everything you need to {outcome}**
|
||||
> Everything you need to launch your course
|
||||
|
||||
**The {adjective} {category} built for {audience}**
|
||||
> The lightweight CRM built for startups
|
||||
|
||||
---
|
||||
|
||||
## Landing Page Section Types
|
||||
|
||||
### Core Sections
|
||||
|
||||
**Hero (Above the Fold)**
|
||||
- Headline + subheadline
|
||||
- Primary CTA
|
||||
- Supporting visual (product screenshot, hero image)
|
||||
- Optional: Social proof bar
|
||||
|
||||
**Social Proof Bar**
|
||||
- Customer logos (recognizable > many)
|
||||
- Key metric ("10,000+ teams")
|
||||
- Star rating with review count
|
||||
- Short testimonial snippet
|
||||
|
||||
**Problem/Pain Section**
|
||||
- Articulate their problem better than they can
|
||||
- Create recognition ("that's exactly my situation")
|
||||
- Hint at cost of not solving it
|
||||
|
||||
**Solution/Benefits Section**
|
||||
- Bridge from problem to your solution
|
||||
- 3-5 key benefits (not 10)
|
||||
- Each: headline + explanation + proof if available
|
||||
|
||||
**How It Works**
|
||||
- 3-4 numbered steps
|
||||
- Reduces perceived complexity
|
||||
- Each step: action + outcome
|
||||
|
||||
**Final CTA Section**
|
||||
- Recap value proposition
|
||||
- Repeat primary CTA
|
||||
- Risk reversal (guarantee, free trial)
|
||||
|
||||
---
|
||||
|
||||
### Supporting Sections
|
||||
|
||||
**Testimonials**
|
||||
- Full quotes with names, roles, companies
|
||||
- Photos when possible
|
||||
- Specific results over vague praise
|
||||
- Formats: quote cards, video, tweet embeds
|
||||
|
||||
**Case Studies**
|
||||
- Problem → Solution → Results
|
||||
- Specific metrics and outcomes
|
||||
- Customer name and context
|
||||
- Can be snippets with "Read more" links
|
||||
|
||||
**Use Cases**
|
||||
- Different ways product is used
|
||||
- Helps visitors self-identify
|
||||
- "For marketers who need X" format
|
||||
|
||||
**Personas / "Built For" Sections**
|
||||
- Explicitly call out target audience
|
||||
- "Perfect for [role]" blocks
|
||||
- Addresses "Is this for me?" question
|
||||
|
||||
**FAQ Section**
|
||||
- Address common objections
|
||||
- Good for SEO
|
||||
- Reduces support burden
|
||||
- 5-10 most common questions
|
||||
|
||||
**Comparison Section**
|
||||
- vs. competitors (name them or don't)
|
||||
- vs. status quo (spreadsheets, manual processes)
|
||||
- Tables or side-by-side format
|
||||
|
||||
**Integrations / Partners**
|
||||
- Logos of tools you connect with
|
||||
- "Works with your stack" messaging
|
||||
- Builds credibility
|
||||
|
||||
**Founder Story / Manifesto**
|
||||
- Why you built this
|
||||
- What you believe
|
||||
- Emotional connection
|
||||
- Differentiates from faceless competitors
|
||||
|
||||
**Demo / Product Tour**
|
||||
- Interactive demos
|
||||
- Video walkthroughs
|
||||
- GIF previews
|
||||
- Shows product in action
|
||||
|
||||
**Pricing Preview**
|
||||
- Teaser even on non-pricing pages
|
||||
- Starting price or "from $X/mo"
|
||||
- Moves decision-makers forward
|
||||
|
||||
**Guarantee / Risk Reversal**
|
||||
- Money-back guarantee
|
||||
- Free trial terms
|
||||
- "Cancel anytime"
|
||||
- Reduces friction
|
||||
|
||||
**Stats Section**
|
||||
- Key metrics that build credibility
|
||||
- "10,000+ customers"
|
||||
- "4.9/5 rating"
|
||||
- "$2M saved for customers"
|
||||
|
||||
---
|
||||
|
||||
## Page Structure Templates
|
||||
|
||||
### Feature-Heavy Page (Weak)
|
||||
|
||||
```
|
||||
1. Hero
|
||||
2. Feature 1
|
||||
3. Feature 2
|
||||
4. Feature 3
|
||||
5. Feature 4
|
||||
6. CTA
|
||||
```
|
||||
|
||||
This is a list, not a persuasive narrative.
|
||||
|
||||
---
|
||||
|
||||
### Varied, Engaging Page (Strong)
|
||||
|
||||
```
|
||||
1. Hero with clear value prop
|
||||
2. Social proof bar (logos or stats)
|
||||
3. Problem/pain section
|
||||
4. How it works (3 steps)
|
||||
5. Key benefits (2-3, not 10)
|
||||
6. Testimonial
|
||||
7. Use cases or personas
|
||||
8. Comparison to alternatives
|
||||
9. Case study snippet
|
||||
10. FAQ
|
||||
11. Final CTA with guarantee
|
||||
```
|
||||
|
||||
This tells a story and addresses objections.
|
||||
|
||||
---
|
||||
|
||||
### Compact Landing Page
|
||||
|
||||
```
|
||||
1. Hero (headline, subhead, CTA, image)
|
||||
2. Social proof bar
|
||||
3. 3 key benefits with icons
|
||||
4. Testimonial
|
||||
5. How it works (3 steps)
|
||||
6. Final CTA with guarantee
|
||||
```
|
||||
|
||||
Good for ad landing pages where brevity matters.
|
||||
|
||||
---
|
||||
|
||||
### Enterprise/B2B Landing Page
|
||||
|
||||
```
|
||||
1. Hero (outcome-focused headline)
|
||||
2. Logo bar (recognizable companies)
|
||||
3. Problem section (business pain)
|
||||
4. Solution overview
|
||||
5. Use cases by role/department
|
||||
6. Security/compliance section
|
||||
7. Integration logos
|
||||
8. Case study with metrics
|
||||
9. ROI/value section
|
||||
10. Contact/demo CTA
|
||||
```
|
||||
|
||||
Addresses enterprise buyer concerns.
|
||||
|
||||
---
|
||||
|
||||
### Product Launch Page
|
||||
|
||||
```
|
||||
1. Hero with launch announcement
|
||||
2. Video demo or walkthrough
|
||||
3. Feature highlights (3-5)
|
||||
4. Before/after comparison
|
||||
5. Early testimonials
|
||||
6. Launch pricing or early access offer
|
||||
7. CTA with urgency
|
||||
```
|
||||
|
||||
Good for ProductHunt, launches, or announcements.
|
||||
|
||||
---
|
||||
|
||||
## Section Writing Tips
|
||||
|
||||
### Problem Section
|
||||
|
||||
Start with phrases like:
|
||||
- "You know the feeling..."
|
||||
- "If you're like most [role]..."
|
||||
- "Every day, [audience] struggles with..."
|
||||
- "We've all been there..."
|
||||
|
||||
Then describe:
|
||||
- The specific frustration
|
||||
- The time/money wasted
|
||||
- The impact on their work/life
|
||||
|
||||
### Benefits Section
|
||||
|
||||
For each benefit, include:
|
||||
- **Headline**: The outcome they get
|
||||
- **Body**: How it works (1-2 sentences)
|
||||
- **Proof**: Number, testimonial, or example (optional)
|
||||
|
||||
### How It Works Section
|
||||
|
||||
Each step should be:
|
||||
- **Numbered**: Creates sense of progress
|
||||
- **Simple verb**: "Connect," "Set up," "Get"
|
||||
- **Outcome-oriented**: What they get from this step
|
||||
|
||||
Example:
|
||||
1. Connect your tools (takes 2 minutes)
|
||||
2. Set your preferences
|
||||
3. Get automated reports every Monday
|
||||
|
||||
### Testimonial Selection
|
||||
|
||||
Best testimonials include:
|
||||
- Specific results ("increased conversions by 32%")
|
||||
- Before/after context ("We used to spend hours...")
|
||||
- Role + company for credibility
|
||||
- Something quotable and specific
|
||||
|
||||
Avoid testimonials that just say:
|
||||
- "Great product!"
|
||||
- "Love it!"
|
||||
- "Easy to use!"
|
||||
252
marketing-skill/copywriting/references/natural-transitions.md
Normal file
252
marketing-skill/copywriting/references/natural-transitions.md
Normal file
@@ -0,0 +1,252 @@
|
||||
# Natural Transitions
|
||||
|
||||
Transitional phrases to guide readers through your content. Good signposting improves readability, user engagement, and helps search engines understand content structure.
|
||||
|
||||
Adapted from: University of Manchester Academic Phrasebank (2023), Plain English Campaign, web content best practices
|
||||
|
||||
---
|
||||
|
||||
## Previewing Content Structure
|
||||
|
||||
Use to orient readers and set expectations:
|
||||
|
||||
- Here's what we'll cover...
|
||||
- This guide walks you through...
|
||||
- Below, you'll find...
|
||||
- We'll start with X, then move to Y...
|
||||
- First, let's look at...
|
||||
- Let's break this down step by step.
|
||||
- The sections below explain...
|
||||
|
||||
---
|
||||
|
||||
## Introducing a New Topic
|
||||
|
||||
- When it comes to X,...
|
||||
- Regarding X,...
|
||||
- Speaking of X,...
|
||||
- Now let's talk about X.
|
||||
- Another key factor is...
|
||||
- X is worth exploring because...
|
||||
|
||||
---
|
||||
|
||||
## Referring Back
|
||||
|
||||
Use to connect ideas and reinforce key points:
|
||||
|
||||
- As mentioned earlier,...
|
||||
- As we covered above,...
|
||||
- Remember when we discussed X?
|
||||
- Building on that point,...
|
||||
- Going back to X,...
|
||||
- Earlier, we explained that...
|
||||
|
||||
---
|
||||
|
||||
## Moving Between Sections
|
||||
|
||||
- Now let's look at...
|
||||
- Next up:...
|
||||
- Moving on to...
|
||||
- With that covered, let's turn to...
|
||||
- Now that you understand X, here's Y.
|
||||
- That brings us to...
|
||||
|
||||
---
|
||||
|
||||
## Indicating Addition
|
||||
|
||||
- Also,...
|
||||
- Plus,...
|
||||
- On top of that,...
|
||||
- What's more,...
|
||||
- Another benefit is...
|
||||
- Beyond that,...
|
||||
- In addition,...
|
||||
- There's also...
|
||||
|
||||
**Note:** Use "moreover" and "furthermore" sparingly. They can sound AI-generated when overused.
|
||||
|
||||
---
|
||||
|
||||
## Indicating Contrast
|
||||
|
||||
- However,...
|
||||
- But,...
|
||||
- That said,...
|
||||
- On the flip side,...
|
||||
- In contrast,...
|
||||
- Unlike X, Y...
|
||||
- While X is true, Y...
|
||||
- Despite this,...
|
||||
|
||||
---
|
||||
|
||||
## Indicating Similarity
|
||||
|
||||
- Similarly,...
|
||||
- Likewise,...
|
||||
- In the same way,...
|
||||
- Just like X, Y also...
|
||||
- This mirrors...
|
||||
- The same applies to...
|
||||
|
||||
---
|
||||
|
||||
## Indicating Cause and Effect
|
||||
|
||||
- So,...
|
||||
- This means...
|
||||
- As a result,...
|
||||
- That's why...
|
||||
- Because of this,...
|
||||
- This leads to...
|
||||
- The outcome?...
|
||||
- Here's what happens:...
|
||||
|
||||
---
|
||||
|
||||
## Giving Examples
|
||||
|
||||
- For example,...
|
||||
- For instance,...
|
||||
- Here's an example:...
|
||||
- Take X, for instance.
|
||||
- Consider this:...
|
||||
- A good example is...
|
||||
- To illustrate,...
|
||||
- Like when...
|
||||
- Say you want to...
|
||||
|
||||
---
|
||||
|
||||
## Emphasising Key Points
|
||||
|
||||
- Here's the key takeaway:...
|
||||
- The important thing is...
|
||||
- What matters most is...
|
||||
- Don't miss this:...
|
||||
- Pay attention to...
|
||||
- This is critical:...
|
||||
- The bottom line?...
|
||||
|
||||
---
|
||||
|
||||
## Providing Evidence
|
||||
|
||||
Use when citing sources, data, or expert opinions:
|
||||
|
||||
### Neutral attribution
|
||||
- According to [Source],...
|
||||
- [Source] reports that...
|
||||
- Research shows that...
|
||||
- Data from [Source] indicates...
|
||||
- A study by [Source] found...
|
||||
|
||||
### Expert quotes
|
||||
- As [Expert] puts it,...
|
||||
- [Expert] explains,...
|
||||
- In the words of [Expert],...
|
||||
- [Expert] notes that...
|
||||
|
||||
### Supporting claims
|
||||
- This is backed by...
|
||||
- Evidence suggests...
|
||||
- The numbers confirm...
|
||||
- This aligns with findings from...
|
||||
|
||||
---
|
||||
|
||||
## Summarising Sections
|
||||
|
||||
- To recap,...
|
||||
- Here's the short version:...
|
||||
- In short,...
|
||||
- The takeaway?...
|
||||
- So what does this mean?...
|
||||
- Let's pull this together:...
|
||||
- Quick summary:...
|
||||
|
||||
---
|
||||
|
||||
## Concluding Content
|
||||
|
||||
- Wrapping up,...
|
||||
- The bottom line is...
|
||||
- Here's what to do next:...
|
||||
- To sum up,...
|
||||
- Final thoughts:...
|
||||
- Ready to get started?...
|
||||
- Now it's your turn.
|
||||
|
||||
**Note:** Avoid "In conclusion" at the start of a paragraph. It's overused and signals AI writing.
|
||||
|
||||
---
|
||||
|
||||
## Question-Based Transitions
|
||||
|
||||
Useful for conversational tone and featured snippet optimization:
|
||||
|
||||
- So what does this mean for you?
|
||||
- But why does this matter?
|
||||
- How do you actually do this?
|
||||
- What's the catch?
|
||||
- Sound complicated? It's not.
|
||||
- Wondering where to start?
|
||||
- Still not sure? Here's the breakdown.
|
||||
|
||||
---
|
||||
|
||||
## List Introductions
|
||||
|
||||
For numbered lists and step-by-step content:
|
||||
|
||||
- Here's how to do it:
|
||||
- Follow these steps:
|
||||
- The process is straightforward:
|
||||
- Here's what you need to know:
|
||||
- Key things to consider:
|
||||
- The main factors are:
|
||||
|
||||
---
|
||||
|
||||
## Hedging Language
|
||||
|
||||
For claims that need qualification or aren't absolute:
|
||||
|
||||
- may, might, could
|
||||
- tends to, generally
|
||||
- often, usually, typically
|
||||
- in most cases
|
||||
- it appears that
|
||||
- evidence suggests
|
||||
- this can help
|
||||
- many experts believe
|
||||
|
||||
---
|
||||
|
||||
## Best Practice Guidelines
|
||||
|
||||
1. **Match tone to audience**: B2B content can be slightly more formal; B2C often benefits from conversational transitions
|
||||
2. **Vary your transitions**: Repeating the same phrase gets noticed (and not in a good way)
|
||||
3. **Don't over-signpost**: Trust your reader; every sentence doesn't need a transition
|
||||
4. **Use for scannability**: Transitions at paragraph starts help skimmers navigate
|
||||
5. **Keep it natural**: Read aloud; if it sounds forced, simplify
|
||||
6. **Front-load key info**: Put the important word or phrase early in the transition
|
||||
|
||||
---
|
||||
|
||||
## Transitions to Avoid (AI Tells)
|
||||
|
||||
These phrases are overused in AI-generated content:
|
||||
|
||||
- "That being said,..."
|
||||
- "It's worth noting that..."
|
||||
- "At its core,..."
|
||||
- "In today's digital landscape,..."
|
||||
- "When it comes to the realm of..."
|
||||
- "This begs the question..."
|
||||
- "Let's delve into..."
|
||||
|
||||
See the seo-audit skill's `references/ai-writing-detection.md` for a complete list of AI writing tells.
|
||||
256
marketing-skill/copywriting/scripts/headline_scorer.py
Executable file
256
marketing-skill/copywriting/scripts/headline_scorer.py
Executable file
@@ -0,0 +1,256 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
headline_scorer.py — Scores headlines 0-100
|
||||
Usage:
|
||||
python3 headline_scorer.py "Your headline here"
|
||||
python3 headline_scorer.py --file headlines.txt
|
||||
python3 headline_scorer.py --json
|
||||
python3 headline_scorer.py # demo mode
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import re
|
||||
import sys
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Word lists
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
POWER_WORDS = {
|
||||
# urgency / scarcity
|
||||
"now", "today", "instantly", "immediately", "urgent", "limited",
|
||||
"exclusive", "last", "hurry", "deadline", "expires", "fast",
|
||||
# value / benefit
|
||||
"free", "save", "proven", "guaranteed", "results", "boost",
|
||||
"increase", "grow", "maximize", "unlock", "secret", "revealed",
|
||||
"transform", "master", "ultimate", "best", "top", "powerful",
|
||||
# curiosity / intrigue
|
||||
"discover", "uncover", "surprising", "shocking", "hidden",
|
||||
"unknown", "insider", "hack", "trick", "truth",
|
||||
# social proof / authority
|
||||
"experts", "researchers", "scientists", "officially", "certified",
|
||||
"award-winning", "world-class",
|
||||
# ease / simplicity
|
||||
"easy", "simple", "effortless", "quick", "step-by-step",
|
||||
"foolproof", "beginner", "without",
|
||||
# negative triggers (fear/loss)
|
||||
"avoid", "stop", "never", "mistake", "fail", "warning", "danger",
|
||||
"worst", "deadly", "risky",
|
||||
}
|
||||
|
||||
EMOTIONAL_TRIGGERS = {
|
||||
"love", "hate", "fear", "hope", "joy", "pain", "anger", "envy",
|
||||
"trust", "doubt", "regret", "pride", "shame", "relief", "success",
|
||||
"failure", "happiness", "frustration", "excitement", "anxiety",
|
||||
"lonely", "powerful", "confident", "inspired",
|
||||
}
|
||||
|
||||
JARGON_WORDS = {
|
||||
"synergy", "leverage", "disruptive", "paradigm", "scalable",
|
||||
"bandwidth", "circle back", "ping", "holistic", "ecosystem",
|
||||
"utilize", "facilitate", "ideate", "incentivize", "stakeholders",
|
||||
"deliverables", "actionable", "bespoke", "granular", "boil the ocean",
|
||||
"low-hanging fruit", "move the needle", "thought leader", "deep dive",
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Scoring functions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def tokenize(headline: str) -> list:
|
||||
return re.findall(r"\b\w+(?:[-']\w+)*\b", headline.lower())
|
||||
|
||||
|
||||
def score_power_words(tokens: list) -> tuple:
|
||||
found = [t for t in tokens if t in POWER_WORDS]
|
||||
# 1 power word = 60pts, 2 = 85, 3+ = 100
|
||||
score = min(100, len(found) * 35 + (10 if found else 0))
|
||||
return score, found
|
||||
|
||||
|
||||
def score_emotional_triggers(tokens: list) -> tuple:
|
||||
found = [t for t in tokens if t in EMOTIONAL_TRIGGERS]
|
||||
score = min(100, len(found) * 50)
|
||||
return score, found
|
||||
|
||||
|
||||
def score_numbers(headline: str) -> tuple:
|
||||
numbers = re.findall(r"\b\d+(?:[,\.]\d+)?%?\b", headline)
|
||||
score = 100 if numbers else 0
|
||||
return score, numbers
|
||||
|
||||
|
||||
def score_length(tokens: list) -> tuple:
|
||||
n = len(tokens)
|
||||
if 6 <= n <= 12:
|
||||
score = 100
|
||||
note = f"{n} words — optimal (6-12)"
|
||||
elif n < 6:
|
||||
score = max(0, 40 + (n - 1) * 12)
|
||||
note = f"{n} words — too short (6-12 optimal)"
|
||||
else:
|
||||
score = max(0, 100 - (n - 12) * 10)
|
||||
note = f"{n} words — too long (6-12 optimal)"
|
||||
return score, note
|
||||
|
||||
|
||||
def score_specificity(headline: str, tokens: list) -> tuple:
|
||||
signals = []
|
||||
if re.search(r"\b\d+\b", headline):
|
||||
signals.append("contains number")
|
||||
if re.search(r"\b(in \d+|within \d+|\d+ days?|\d+ weeks?|\d+ months?|\d+ hours?|\d+ minutes?)\b", headline, re.I):
|
||||
signals.append("timeframe")
|
||||
if re.search(r"\b(how to|step|guide|checklist|strategy|system|framework|formula)\b", headline, re.I):
|
||||
signals.append("concrete format")
|
||||
if re.search(r"\b\d+%\b", headline):
|
||||
signals.append("percentage")
|
||||
score = min(100, len(signals) * 34)
|
||||
return score, signals
|
||||
|
||||
|
||||
def score_clarity(tokens: list) -> tuple:
|
||||
found_jargon = [t for t in tokens if t in JARGON_WORDS]
|
||||
score = max(0, 100 - len(found_jargon) * 30)
|
||||
note = "No jargon detected" if not found_jargon else f"Jargon: {', '.join(found_jargon)}"
|
||||
return score, note
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Aggregate
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
WEIGHTS = {
|
||||
"power_words": 0.25,
|
||||
"emotional_triggers": 0.15,
|
||||
"numbers": 0.15,
|
||||
"length": 0.20,
|
||||
"specificity": 0.15,
|
||||
"clarity": 0.10,
|
||||
}
|
||||
|
||||
|
||||
def score_headline(headline: str) -> dict:
|
||||
tokens = tokenize(headline)
|
||||
|
||||
pw_score, pw_found = score_power_words(tokens)
|
||||
et_score, et_found = score_emotional_triggers(tokens)
|
||||
num_score, nums = score_numbers(headline)
|
||||
len_score, len_note = score_length(tokens)
|
||||
spec_score, spec_signals = score_specificity(headline, tokens)
|
||||
clar_score, clar_note = score_clarity(tokens)
|
||||
|
||||
breakdown = {
|
||||
"power_words": {"score": pw_score, "found": pw_found, "weight": "25%"},
|
||||
"emotional_triggers": {"score": et_score, "found": et_found, "weight": "15%"},
|
||||
"numbers": {"score": num_score, "found": nums, "weight": "15%"},
|
||||
"length": {"score": len_score, "note": len_note, "weight": "20%"},
|
||||
"specificity": {"score": spec_score, "signals": spec_signals, "weight": "15%"},
|
||||
"clarity": {"score": clar_score, "note": clar_note, "weight": "10%"},
|
||||
}
|
||||
|
||||
overall = round(sum(
|
||||
breakdown[k]["score"] * WEIGHTS[k]
|
||||
for k in WEIGHTS
|
||||
))
|
||||
|
||||
grade = "A" if overall >= 85 else "B" if overall >= 70 else "C" if overall >= 55 else "D" if overall >= 40 else "F"
|
||||
|
||||
return {
|
||||
"headline": headline,
|
||||
"overall_score": overall,
|
||||
"grade": grade,
|
||||
"breakdown": breakdown,
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Demo headlines
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
DEMO_HEADLINES = [
|
||||
"10 Proven Ways to Double Your Email Open Rates in 30 Days",
|
||||
"Marketing Tips for Better Results",
|
||||
"Unlock the Secret Formula That Top Experts Use to Grow Revenue Fast",
|
||||
"How to Leverage Synergistic Paradigms for Scalable Growth",
|
||||
"Our New Product Is Now Available",
|
||||
]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Output helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def print_result(result: dict):
|
||||
h = result["headline"]
|
||||
score = result["overall_score"]
|
||||
grade = result["grade"]
|
||||
print(f"\n{'─' * 60}")
|
||||
print(f" Headline: {h}")
|
||||
print(f" Score: {score}/100 Grade: {grade}")
|
||||
print(f"{'─' * 60}")
|
||||
bd = result["breakdown"]
|
||||
rows = [
|
||||
("Power Words", "power_words", lambda r: f"found: {r['found'] or 'none'}"),
|
||||
("Emotional Trigger", "emotional_triggers", lambda r: f"found: {r['found'] or 'none'}"),
|
||||
("Numbers/Stats", "numbers", lambda r: f"found: {r['found'] or 'none'}"),
|
||||
("Length", "length", lambda r: r["note"]),
|
||||
("Specificity", "specificity", lambda r: f"signals: {r['signals'] or 'none'}"),
|
||||
("Clarity", "clarity", lambda r: r["note"]),
|
||||
]
|
||||
for label, key, detail_fn in rows:
|
||||
r = bd[key]
|
||||
bar_len = round(r["score"] / 10)
|
||||
bar = "█" * bar_len + "░" * (10 - bar_len)
|
||||
detail = detail_fn(r)
|
||||
print(f" {label:<20} [{bar}] {r['score']:>3}/100 {detail}")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Main
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Headline scorer — rates headlines 0-100 across 6 dimensions."
|
||||
)
|
||||
parser.add_argument("headline", nargs="?", help="Single headline to score")
|
||||
parser.add_argument("--file", help="Text file with one headline per line")
|
||||
parser.add_argument("--json", action="store_true", help="Output as JSON")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.headline:
|
||||
headlines = [args.headline]
|
||||
elif args.file:
|
||||
with open(args.file, "r", encoding="utf-8") as f:
|
||||
headlines = [line.strip() for line in f if line.strip()]
|
||||
else:
|
||||
headlines = DEMO_HEADLINES
|
||||
if not args.json:
|
||||
print("No input provided — running in demo mode.\n")
|
||||
print("Demo headlines:")
|
||||
for h in headlines:
|
||||
print(f" • {h}")
|
||||
|
||||
results = [score_headline(h) for h in headlines]
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(results, indent=2))
|
||||
return
|
||||
|
||||
for result in results:
|
||||
print_result(result)
|
||||
|
||||
if len(results) > 1:
|
||||
avg = round(sum(r["overall_score"] for r in results) / len(results))
|
||||
best = max(results, key=lambda r: r["overall_score"])
|
||||
print(f"\n{'=' * 60}")
|
||||
print(f" {len(results)} headlines analyzed | Avg score: {avg}/100")
|
||||
print(f" Best: \"{best['headline'][:50]}\" ({best['overall_score']}/100)")
|
||||
print("=" * 60)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
340
marketing-skill/email-sequence/SKILL.md
Normal file
340
marketing-skill/email-sequence/SKILL.md
Normal file
@@ -0,0 +1,340 @@
|
||||
---
|
||||
name: email-sequence
|
||||
description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
|
||||
license: MIT
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
author: Alireza Rezvani
|
||||
category: marketing
|
||||
updated: 2026-03-06
|
||||
---
|
||||
|
||||
# Email Sequence Design
|
||||
|
||||
You are an expert in email marketing and automation. Your goal is to create email sequences that nurture relationships, drive action, and move people toward conversion.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before creating a sequence, understand:
|
||||
|
||||
1. **Sequence Type**
|
||||
- Welcome/onboarding sequence
|
||||
- Lead nurture sequence
|
||||
- Re-engagement sequence
|
||||
- Post-purchase sequence
|
||||
- Event-based sequence
|
||||
- Educational sequence
|
||||
- Sales sequence
|
||||
|
||||
2. **Audience Context**
|
||||
- Who are they?
|
||||
- What triggered them into this sequence?
|
||||
- What do they already know/believe?
|
||||
- What's their current relationship with you?
|
||||
|
||||
3. **Goals**
|
||||
- Primary conversion goal
|
||||
- Relationship-building goals
|
||||
- Segmentation goals
|
||||
- What defines success?
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. One Email, One Job
|
||||
- Each email has one primary purpose
|
||||
- One main CTA per email
|
||||
- Don't try to do everything
|
||||
|
||||
### 2. Value Before Ask
|
||||
- Lead with usefulness
|
||||
- Build trust through content
|
||||
- Earn the right to sell
|
||||
|
||||
### 3. Relevance Over Volume
|
||||
- Fewer, better emails win
|
||||
- Segment for relevance
|
||||
- Quality > frequency
|
||||
|
||||
### 4. Clear Path Forward
|
||||
- Every email moves them somewhere
|
||||
- Links should do something useful
|
||||
- Make next steps obvious
|
||||
|
||||
---
|
||||
|
||||
## Email Sequence Strategy
|
||||
|
||||
### Sequence Length
|
||||
- Welcome: 3-7 emails
|
||||
- Lead nurture: 5-10 emails
|
||||
- Onboarding: 5-10 emails
|
||||
- Re-engagement: 3-5 emails
|
||||
|
||||
Depends on:
|
||||
- Sales cycle length
|
||||
- Product complexity
|
||||
- Relationship stage
|
||||
|
||||
### Timing/Delays
|
||||
- Welcome email: Immediately
|
||||
- Early sequence: 1-2 days apart
|
||||
- Nurture: 2-4 days apart
|
||||
- Long-term: Weekly or bi-weekly
|
||||
|
||||
Consider:
|
||||
- B2B: Avoid weekends
|
||||
- B2C: Test weekends
|
||||
- Time zones: Send at local time
|
||||
|
||||
### Subject Line Strategy
|
||||
- Clear > Clever
|
||||
- Specific > Vague
|
||||
- Benefit or curiosity-driven
|
||||
- 40-60 characters ideal
|
||||
- Test emoji (they're polarizing)
|
||||
|
||||
**Patterns that work:**
|
||||
- Question: "Still struggling with X?"
|
||||
- How-to: "How to [achieve outcome] in [timeframe]"
|
||||
- Number: "3 ways to [benefit]"
|
||||
- Direct: "[First name], your [thing] is ready"
|
||||
- Story tease: "The mistake I made with [topic]"
|
||||
|
||||
### Preview Text
|
||||
- Extends the subject line
|
||||
- ~90-140 characters
|
||||
- Don't repeat subject line
|
||||
- Complete the thought or add intrigue
|
||||
|
||||
---
|
||||
|
||||
## Sequence Types Overview
|
||||
|
||||
### Welcome Sequence (Post-Signup)
|
||||
**Length**: 5-7 emails over 12-14 days
|
||||
**Goal**: Activate, build trust, convert
|
||||
|
||||
Key emails:
|
||||
1. Welcome + deliver promised value (immediate)
|
||||
2. Quick win (day 1-2)
|
||||
3. Story/Why (day 3-4)
|
||||
4. Social proof (day 5-6)
|
||||
5. Overcome objection (day 7-8)
|
||||
6. Core feature highlight (day 9-11)
|
||||
7. Conversion (day 12-14)
|
||||
|
||||
### Lead Nurture Sequence (Pre-Sale)
|
||||
**Length**: 6-8 emails over 2-3 weeks
|
||||
**Goal**: Build trust, demonstrate expertise, convert
|
||||
|
||||
Key emails:
|
||||
1. Deliver lead magnet + intro (immediate)
|
||||
2. Expand on topic (day 2-3)
|
||||
3. Problem deep-dive (day 4-5)
|
||||
4. Solution framework (day 6-8)
|
||||
5. Case study (day 9-11)
|
||||
6. Differentiation (day 12-14)
|
||||
7. Objection handler (day 15-18)
|
||||
8. Direct offer (day 19-21)
|
||||
|
||||
### Re-Engagement Sequence
|
||||
**Length**: 3-4 emails over 2 weeks
|
||||
**Trigger**: 30-60 days of inactivity
|
||||
**Goal**: Win back or clean list
|
||||
|
||||
Key emails:
|
||||
1. Check-in (genuine concern)
|
||||
2. Value reminder (what's new)
|
||||
3. Incentive (special offer)
|
||||
4. Last chance (stay or unsubscribe)
|
||||
|
||||
### Onboarding Sequence (Product Users)
|
||||
**Length**: 5-7 emails over 14 days
|
||||
**Goal**: Activate, drive to aha moment, upgrade
|
||||
**Note**: Coordinate with in-app onboarding—email supports, doesn't duplicate
|
||||
|
||||
Key emails:
|
||||
1. Welcome + first step (immediate)
|
||||
2. Getting started help (day 1)
|
||||
3. Feature highlight (day 2-3)
|
||||
4. Success story (day 4-5)
|
||||
5. Check-in (day 7)
|
||||
6. Advanced tip (day 10-12)
|
||||
7. Upgrade/expand (day 14+)
|
||||
|
||||
**For detailed templates**: See [references/sequence-templates.md](references/sequence-templates.md)
|
||||
|
||||
---
|
||||
|
||||
## Email Types by Category
|
||||
|
||||
### Onboarding Emails
|
||||
- New users series
|
||||
- New customers series
|
||||
- Key onboarding step reminders
|
||||
- New user invites
|
||||
|
||||
### Retention Emails
|
||||
- Upgrade to paid
|
||||
- Upgrade to higher plan
|
||||
- Ask for review
|
||||
- Proactive support offers
|
||||
- Product usage reports
|
||||
- NPS survey
|
||||
- Referral program
|
||||
|
||||
### Billing Emails
|
||||
- Switch to annual
|
||||
- Failed payment recovery
|
||||
- Cancellation survey
|
||||
- Upcoming renewal reminders
|
||||
|
||||
### Usage Emails
|
||||
- Daily/weekly/monthly summaries
|
||||
- Key event notifications
|
||||
- Milestone celebrations
|
||||
|
||||
### Win-Back Emails
|
||||
- Expired trials
|
||||
- Cancelled customers
|
||||
|
||||
### Campaign Emails
|
||||
- Monthly roundup / newsletter
|
||||
- Seasonal promotions
|
||||
- Product updates
|
||||
- Industry news roundup
|
||||
- Pricing updates
|
||||
|
||||
**For detailed email type reference**: See [references/email-types.md](references/email-types.md)
|
||||
|
||||
---
|
||||
|
||||
## Email Copy Guidelines
|
||||
|
||||
### Structure
|
||||
1. **Hook**: First line grabs attention
|
||||
2. **Context**: Why this matters to them
|
||||
3. **Value**: The useful content
|
||||
4. **CTA**: What to do next
|
||||
5. **Sign-off**: Human, warm close
|
||||
|
||||
### Formatting
|
||||
- Short paragraphs (1-3 sentences)
|
||||
- White space between sections
|
||||
- Bullet points for scanability
|
||||
- Bold for emphasis (sparingly)
|
||||
- Mobile-first (most read on phone)
|
||||
|
||||
### Tone
|
||||
- Conversational, not formal
|
||||
- First-person (I/we) and second-person (you)
|
||||
- Active voice
|
||||
- Read it out loud—does it sound human?
|
||||
|
||||
### Length
|
||||
- 50-125 words for transactional
|
||||
- 150-300 words for educational
|
||||
- 300-500 words for story-driven
|
||||
|
||||
### CTA Guidelines
|
||||
- Buttons for primary actions
|
||||
- Links for secondary actions
|
||||
- One clear primary CTA per email
|
||||
- Button text: Action + outcome
|
||||
|
||||
**For detailed copy, personalization, and testing guidelines**: See [references/copy-guidelines.md](references/copy-guidelines.md)
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Sequence Overview
|
||||
```
|
||||
Sequence Name: [Name]
|
||||
Trigger: [What starts the sequence]
|
||||
Goal: [Primary conversion goal]
|
||||
Length: [Number of emails]
|
||||
Timing: [Delay between emails]
|
||||
Exit Conditions: [When they leave the sequence]
|
||||
```
|
||||
|
||||
### For Each Email
|
||||
```
|
||||
Email [#]: [Name/Purpose]
|
||||
Send: [Timing]
|
||||
Subject: [Subject line]
|
||||
Preview: [Preview text]
|
||||
Body: [Full copy]
|
||||
CTA: [Button text] → [Link destination]
|
||||
Segment/Conditions: [If applicable]
|
||||
```
|
||||
|
||||
### Metrics Plan
|
||||
What to measure and benchmarks
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What triggers entry to this sequence?
|
||||
2. What's the primary goal/conversion action?
|
||||
3. What do they already know about you?
|
||||
4. What other emails are they receiving?
|
||||
5. What's your current email performance?
|
||||
|
||||
---
|
||||
|
||||
## Tool Integrations
|
||||
|
||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools:
|
||||
|
||||
| Tool | Best For | MCP | Guide |
|
||||
|------|----------|:---:|-------|
|
||||
| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) |
|
||||
| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) |
|
||||
| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) |
|
||||
| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) |
|
||||
| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) |
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **cold-email** — WHEN the sequence targets people who have NOT opted in (outbound prospecting). NOT for warm leads or subscribers who have expressed interest.
|
||||
- **copywriting** — WHEN landing pages linked from emails need copy optimization that matches the email's message and audience. NOT for the email copy itself.
|
||||
- **launch-strategy** — WHEN coordinating email sequences around a specific product launch, announcement, or release window. NOT for evergreen nurture or onboarding sequences.
|
||||
- **analytics-tracking** — WHEN setting up email click tracking, UTM parameters, and attribution to connect email engagement to downstream conversions. NOT for writing or designing the sequence.
|
||||
- **onboarding-cro** — WHEN email sequences are supporting a parallel in-app onboarding flow and need to be coordinated to avoid duplication. NOT as a replacement for in-app onboarding experience.
|
||||
|
||||
---
|
||||
|
||||
## Communication
|
||||
|
||||
Deliver email sequences as complete, ready-to-send drafts — include subject line, preview text, full body, and CTA for every email in the sequence. Always specify the trigger condition and send timing. When the sequence is long (5+ emails), lead with a sequence overview table before individual emails. Flag if any email could conflict with other sequences the audience receives. Load `marketing-context` for brand voice, ICP, and product context before writing.
|
||||
|
||||
---
|
||||
|
||||
## Proactive Triggers
|
||||
|
||||
- User mentions low trial-to-paid conversion → ask if there's a trial expiration email sequence before recommending in-app or pricing changes.
|
||||
- User reports high open rates but low clicks → diagnose email body copy and CTA specificity before blaming subject lines.
|
||||
- User wants to "do email marketing" → clarify sequence type (welcome, nurture, re-engagement, etc.) before writing anything.
|
||||
- User has a product launch coming → recommend coordinating launch email sequence with in-app messaging and landing page copy for consistent messaging.
|
||||
- User mentions list is going cold → suggest re-engagement sequence with progressive offers before recommending acquisition spend.
|
||||
|
||||
---
|
||||
|
||||
## Output Artifacts
|
||||
|
||||
| Artifact | Description |
|
||||
|----------|-------------|
|
||||
| Sequence Architecture Doc | Trigger, goal, length, timing, exit conditions, and branching logic for the full sequence |
|
||||
| Complete Email Drafts | Subject line, preview text, full body, and CTA for every email in the sequence |
|
||||
| Metrics Benchmarks | Open rate, click rate, and conversion rate targets per email type and sequence goal |
|
||||
| Segmentation Rules | Audience entry/exit conditions, behavioral branching, and suppression lists |
|
||||
| Subject Line Variations | 3 subject line alternatives per email for A/B testing |
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user