feat(marketing): add weighted scoring systems to seo-audit + paid-ads

Phase 1 of the marketing skills improvement plan. Inspired by patterns
from claude-seo (4.7k stars) and claude-ads (2.4k stars) — the highest-
traction Claude Code plugins in the SEO/ads space. Adopts their best
patterns without replacing our existing skills.

seo-audit additions:
- scripts/seo_health_scorer.py — weighted 0-100 health score across 7
  categories (Technical 22%, Content 23%, On-Page 20%, Schema 10%,
  Performance 10%, AI Readiness 10%, Images 5%). Industry profiles
  (SaaS/ecommerce/local/publisher) adjust weights. Severity-weighted
  scoring with Critical/High/Medium/Low priority levels and Quick Wins
  extraction. Demo mode included.
- references/cwv-thresholds.md — Core Web Vitals 2026 thresholds (LCP,
  CLS, INP) with good/needs-improvement/poor ranges and common fixes
- references/eeat-framework.md — E-E-A-T audit checklist per Google's
  Sept 2025 Quality Rater Guidelines, YMYL topic handling
- references/schema-types.md — active/deprecated JSON-LD types with
  validation checklist and common mistakes

paid-ads additions:
- scripts/ad_health_scorer.py — multi-platform ad account scoring with
  severity multipliers (Critical=5x, High=3x, Medium=1.5x, Low=0.5x).
  Platform-specific category weights for Google (6 categories, 74 checks),
  Meta (4 categories), LinkedIn (4), TikTok (4). Cross-platform aggregation
  weighted by budget share. Quick Wins prioritization. Demo mode with
  Google + Meta sample data.
- references/scoring-system.md — full scoring algorithm, severity
  multipliers, platform weights, grade bands, quality gates (hard rules
  like "never Broad Match + Manual CPC")
- references/copy-frameworks.md — 6 ad copy frameworks (PAS, BAB, AIDA,
  FAB, 4P, Star-Story-Solution) with selection matrix by product type,
  platform-specific character limits, and brand DNA extraction (7 voice
  axes as JSON schema)

Key patterns adopted from claude-seo/ads:
- Weighted numeric scores replace binary pass/fail
- Severity multipliers make critical issues dominate the score
- Industry/platform auto-detection adjusts weights
- Quick Wins = high severity + partially working (warn not fail)
- Reference files are lazy-loaded, not inline
- Demo mode with realistic sample data

All scripts stdlib-only, --json + --help verified.

Also saved: documentation/implementation/marketing-skills-improvement-plan.md
covering all 3 phases (Phase 2: content scoring, Phase 3: AI detection).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: alirezarezvani

documentation/implementation/marketing-skills-improvement-plan.md

@@ -0,0 +1,82 @@
+# Marketing Skills Improvement Plan — Inspired by claude-seo/ads/blog
+
+**Status:** Active (created 2026-04-13)
+**Inspired by:** claude-seo (4.7k stars), claude-ads (2.4k stars), claude-blog (466 stars)
+**Scope:** Improve 5 existing marketing skills with 8 cross-cutting patterns. No replacements — purely additive.
+
+---
+
+## The 8 patterns to adopt
+
+1. **Weighted 0-100 scoring** — replace binary pass/fail with numeric health scores
+2. **Priority levels with SLAs** — Critical/High/Medium/Low + time-to-fix
+3. **Industry auto-detection** — route to different check weights by business type
+4. **On-demand reference loading** — modular .md files instead of inline knowledge
+5. **Quality gates (hard stops)** — non-negotiable rules that block action
+6. **Multi-tier API fallback** — free tier always works, premium tier enhances
+7. **Quick Wins prioritization** — severity × impact / time-to-fix
+8. **AI citation readiness** — dual-optimize for Google + AI platforms
+
+---
+
+## Phase 1 — Scoring systems + references (seo-audit, paid-ads)
+
+### seo-audit improvements
+- Weighted 0-100 health score: Technical 22%, Content 23%, On-Page 20%, Schema 10%, Performance 10%, AI Readiness 10%, Images 5%
+- Priority levels (Critical/High/Medium/Low) with SLAs on every finding
+- Industry auto-detection (SaaS/local/ecommerce/publisher) → different weight profiles
+- New references: cwv-thresholds.md, schema-types.md, eeat-framework.md
+- New script: seo_health_scorer.py (compute weighted score from check results)
+
+### paid-ads improvements
+- Platform-specific checks with weighted scoring (Google 74, Meta 46, LinkedIn 25, TikTok 25)
+- Severity multiplier matrix (Critical=5x, High=3x, Medium=1.5x, Low=0.5x) × category weights
+- Budget-weighted cross-platform aggregation: Score = Σ(Platform_Score × Budget_Share)
+- Brand DNA extraction (7 voice axes) as reusable JSON
+- Copy framework selection logic: AIDA vs PAS vs BAB by product type
+- Quick Wins: severity × estimated_impact / time_to_fix
+- New references: google-audit.md, meta-audit.md, scoring-system.md, copy-frameworks.md
+- New script: ad_health_scorer.py
+
+## Phase 2 — Content scoring + quality gates (content-creator, content-production)
+
+### content-creator improvements
+- Dual-optimization: Google rankings + AI citation platforms (Perplexity, ChatGPT, AI Overviews)
+- 12 content templates with auto-selection logic
+- Answer-first formatting (40-60 word paragraphs at H2) for AI extractability
+- Passage-level citability checks (120-180 word chunks, Q&A formatting)
+- New references: content-templates.md, ai-citation-readiness.md
+
+### content-production improvements
+- 100-point scoring: Content Quality 30, SEO 25, E-E-A-T 15, Technical 15, AI Citation 15
+- Score bands → action: <60 rewrite, 60-69 rework, 70-79 target, 80-89 publish, 90+ flagship
+- Quality gates: zero fabricated stats, heading hierarchy, image alt text, source tier
+- Freshness signals: dateModified tracking, decay detection
+- New script: content_scorer.py
+
+## Phase 3 — AI detection + readability (copy-editing)
+
+### copy-editing improvements
+- AI content detection: burstiness (sentence length variance), vocabulary diversity (TTR), 17 AI phrases
+- Readability bands: Consumer (Flesch 60-80), Professional (50-60), Technical (30-50)
+- Anti-pattern enforcement: passive voice ≤10%, AI words ≤5/1K, transition words 20-30%
+- Paragraph micro-scoring: 40-80 word ideal, >150 blocking
+- New scripts: ai_content_detector.py, readability_scorer.py
+
+---
+
+## What we DON'T adopt (anti-patterns to avoid)
+
+- No timeout fallbacks on parallel agents (claude-ads blocks if one agent fails — we should fail gracefully)
+- No paid API requirements (claude-seo needs DataForSEO for full coverage — we keep stdlib-only)
+- No external ML model dependencies (claude-blog uses Google NLP — we use deterministic analysis)
+- No WeasyPrint/matplotlib for reporting (heavy deps — we use markdown/JSON output)
+
+---
+
+## Execution
+
+- Each phase: feature branch → PR to dev → /plugin-audit → merge
+- Each skill keeps its existing SKILL.md structure; new files are additive
+- Scripts are Python stdlib-only, CLI-first, --json output
+- References are lazy-loaded .md files, not inline in SKILL.md

marketing-skill/paid-ads/references/copy-frameworks.md

@@ -0,0 +1,101 @@
+# Ad Copy Frameworks
+
+Reference for selecting the right copy framework based on product type and campaign goal. Each framework includes a structure template and platform-specific length constraints.
+
+## Framework selection matrix
+
+| Product type | Pain-point heavy? | Transformation story? | Feature-led? | Recommended framework |
+|---|---|---|---|---|
+| SaaS / B2B | ✅ | | | PAS (Problem-Agitate-Solve) |
+| Coaching / courses | | ✅ | | BAB (Before-After-Bridge) |
+| Ecommerce / physical | | | ✅ | FAB (Features-Advantages-Benefits) |
+| Content / info product | ✅ | ✅ | | AIDA (Attention-Interest-Desire-Action) |
+| App / tool launch | | | ✅ | 4P (Promise-Picture-Proof-Push) |
+| Services / consulting | ✅ | ✅ | | Star-Story-Solution |
+
+## The 6 frameworks
+
+### PAS — Problem → Agitate → Solve
+**Best for:** Pain-point products, SaaS solving specific frustrations
+
+```
+Problem:  Name the exact pain (1 sentence)
+Agitate:  Twist the knife — what happens if they don't fix it (1-2 sentences)
+Solve:    Your product is the answer (1 sentence + CTA)
+```
+
+### BAB — Before → After → Bridge
+**Best for:** Transformation products, coaching, courses
+
+```
+Before:   Current painful state (1 sentence)
+After:    Desired state they'll achieve (1 sentence)
+Bridge:   Your product connects the two (1 sentence + CTA)
+```
+
+### AIDA — Attention → Interest → Desire → Action
+**Best for:** Content marketing, info products, broad audiences
+
+```
+Attention: Hook with a surprising stat or question
+Interest:  Explain why this matters to them
+Desire:    Show social proof or specific outcomes
+Action:    Clear CTA with urgency
+```
+
+### FAB — Features → Advantages → Benefits
+**Best for:** Product-led, ecommerce, feature-rich offerings
+
+```
+Feature:    What it has (spec/capability)
+Advantage:  Why that matters vs alternatives
+Benefit:    What the user gains (outcome)
+```
+
+### 4P — Promise → Picture → Proof → Push
+**Best for:** App launches, tools, direct response
+
+```
+Promise:  Bold claim (1 headline)
+Picture:  Vivid scenario of life with the product
+Proof:    Social proof, stats, testimonial
+Push:     Strong CTA with urgency/scarcity
+```
+
+### Star-Story-Solution
+**Best for:** Personal brands, services, consulting
+
+```
+Star:      Introduce the hero (the customer, not you)
+Story:     Their struggle (relatable narrative)
+Solution:  How your service transforms their situation
+```
+
+## Platform-specific constraints
+
+| Platform | Headline | Body | CTA |
+|---|---|---|---|
+| Google RSA | 30 chars × 15 headlines | 90 chars × 4 descriptions | Auto from list |
+| Meta Feed | 40 chars (before truncation) | 125 chars primary text (before "See more") | Button from list |
+| Meta Stories | 40 chars overlay | Minimal — visual-first | Swipe up / button |
+| LinkedIn Sponsored | 70 chars intro text visible | 150 chars before truncation | Button from list |
+| TikTok | Overlay text in video | Caption 100 chars | Button from list |
+| Microsoft | 30 chars × 15 headlines | 90 chars × 4 descriptions | Auto from list |
+
+## Brand DNA extraction (7 voice axes)
+
+Before writing ad copy, extract the brand's voice profile on these 7 axes:
+
+```json
+{
+  "formal_casual": 0.7,       // 0 = corporate formal, 1 = casual/friendly
+  "bold_subtle": 0.6,         // 0 = understated, 1 = bold/provocative
+  "technical_human": 0.4,     // 0 = jargon-heavy, 1 = plain language
+  "serious_playful": 0.5,     // 0 = gravitas, 1 = humor/wit
+  "traditional_innovative": 0.8, // 0 = established, 1 = cutting-edge
+  "exclusive_inclusive": 0.6,  // 0 = luxury/elite, 1 = accessible/everyone
+  "data_emotional": 0.5       // 0 = stats-driven, 1 = story-driven
+}
+```
+
+Save as `brand-profile.json` for reuse across campaigns. Each axis is 0.0-1.0.

marketing-skill/paid-ads/references/scoring-system.md

@@ -0,0 +1,87 @@
+# Ad Account Scoring System
+
+Reference for `ad_health_scorer.py`. Defines the weighted scoring algorithm, severity multipliers, and platform-specific category weights.
+
+## Scoring formula
+
+```
+Category_Score = Σ(Check_Result × Severity_Multiplier) / Σ(Severity_Multiplier) × 100
+Platform_Score = Σ(Category_Score × Category_Weight)
+Aggregate_Score = Σ(Platform_Score × Budget_Share)
+```
+
+## Severity multipliers
+
+| Severity | Multiplier | Meaning | SLA |
+|---|---|---|---|
+| Critical | 5.0x | Blocks revenue or burns budget | Fix immediately |
+| High | 3.0x | Significant performance impact | Fix within 1 week |
+| Medium | 1.5x | Optimization opportunity | Fix within 1 month |
+| Low | 0.5x | Polish / best practice | Backlog |
+
+Critical issues dominate the score. A single critical failure drops the category score significantly, which is the correct behavior — a missing conversion tag invalidates everything downstream.
+
+## Platform category weights
+
+### Google Ads
+| Category | Weight | Key checks |
+|---|---|---|
+| Conversion Tracking | 25% | Tag installed, Enhanced Conversions, attribution model, conversion window |
+| Wasted Spend | 20% | Negative keywords, search terms review, broad match rules, 3× CPA kill rule |
+| Account Structure | 15% | Naming conventions, ad group size, campaign types |
+| Keywords | 15% | Quality Score, duplicates, match types, search intent alignment |
+| Ads | 15% | RSA headlines count, extensions, A/B testing |
+| Settings | 10% | Location targeting, schedules, networks, bidding strategy |
+
+### Meta (Facebook/Instagram)
+| Category | Weight | Key checks |
+|---|---|---|
+| Pixel & CAPI | 30% | Pixel installed, CAPI active, event deduplication, domain verification |
+| Creative | 30% | Format diversity, fatigue detection, safe zones, copy length |
+| Structure | 20% | CBO, campaign naming, advantage+ settings |
+| Audience | 20% | Lookalike seed size, exclusions, overlap, custom audiences |
+
+### LinkedIn
+| Category | Weight | Key checks |
+|---|---|---|
+| Technical | 25% | Insight tag, conversion events, matched audiences |
+| Targeting | 25% | Audience size, job function vs title, company lists |
+| Creative | 25% | Format mix, single-image vs carousel vs video, CTA alignment |
+| Budget | 25% | Daily budget sufficiency, bid strategy, pacing |
+
+### TikTok
+| Category | Weight | Key checks |
+|---|---|---|
+| Pixel | 25% | Pixel installed, events configured, match quality |
+| Creative | 30% | Native-feel content, format mix, hook rate (3s), UGC ratio |
+| Targeting | 25% | Interest vs behavior, custom audiences, lookalikes |
+| Budget | 20% | Learning phase budget (50× target CPA), pacing |
+
+## Grade bands
+
+| Grade | Score | Meaning |
+|---|---|---|
+| A | 90-100 | Excellent — maintain and scale |
+| B | 75-89 | Good — address high-priority items |
+| C | 60-74 | Needs work — systematic improvements needed |
+| D | 40-59 | Poor — significant issues blocking performance |
+| F | <40 | Critical — account needs fundamental restructuring |
+
+Bands are calibrated wider than SEO scoring because ad accounts typically have more actionable but non-critical issues (e.g., missing extensions, suboptimal ad copy).
+
+## Quick Wins formula
+
+```
+Quick Win = severity ∈ {critical, high} AND result = "warn" (not full fail)
+```
+
+Quick wins are issues that are important (high severity) but partially working (warn, not fail) — meaning the fix is usually small: enable a toggle, add a few negative keywords, activate an extension.
+
+## Hard rules (quality gates)
+
+These combinations should NEVER be recommended together:
+- Broad Match + Manual CPC (wastes budget without smart bidding control)
+- CPA target below $5 with < $50/day budget (can't exit learning phase)
+- Conversion action = page view as primary (inflates numbers, misleads bidding)
+
+The scorer doesn't enforce these directly but the SKILL.md workflow should flag them as critical failures.