@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/page-cro/SKILL.md

@@ -0,0 +1,269 @@
+---
+name: page-cro
+description: "Audits existing landing pages for conversion rate optimization. Scores hero section, CTA placement, social proof, objection handling, and form..."
+allowed-tools: []
+---
+
+# Page CRO (Conversion Rate Optimization)
+
+## Purpose
+
+Take any landing page and audit it for conversion leaks. Score each element, prioritize fixes by impact, and provide ready-to-implement copy and layout changes. No vague advice — specific rewrites and structural fixes.
+
+## Reads
+
+- `brand/audience.md` — Target personas, pain points, buying triggers
+- `brand/positioning.md` — Value props, differentiators, proof points
+- `brand/voice-profile.md` — Brand voice for copy rewrites
+
+## Brand Integration
+
+- **audience.md** — Scoring thresholds shift by persona. A developer audience tolerates minimal social proof; a non-technical buyer needs more hand-holding. Pain points from audience.md inform which objections the page should address — unaddressed objections are the most common conversion killer.
+- **positioning.md** — Every copy rewrite must reinforce the positioning angle. If the brand differentiates on speed, the hero rewrite should lead with speed. Proof points from positioning.md become the social proof recommendations.
+- **voice-profile.md** — All before/after copy rewrites match the brand voice. A playful brand gets different CTA copy than a professional brand.
+
+## Workflow
+
+### Step 0: Awareness Gate (MANDATORY)
+
+Before auditing, determine the target audience's awareness level:
+
+1. **Can you determine awareness level from the prompt/context?**
+   - For SEO: keyword intent maps to awareness level
+     - Informational ("how to fix X") → Problem-aware
+     - Comparative ("X vs Y") → Solution-aware
+     - Branded ("your product") → Product-aware
+     - Transactional ("buy X") → Most-aware
+   - For social: content topic + audience → awareness level
+   - For email: subscriber stage → awareness level
+
+2. **If YES** → Proceed with awareness-matched audit
+   - Load `references/awareness-level-guide.md`
+   - Check if page architecture matches awareness level
+   - Score: -20 points for mismatched architecture
+
+3. **If NO** → ASK THE USER before proceeding:
+   "What awareness level is your target audience at?"
+   - Unaware — doesn't know they have a problem
+   - Problem-aware — knows the problem, doesn't know solutions exist
+   - Solution-aware — knows solutions exist, doesn't know your product
+   - Product-aware — knows your product, not convinced it's right
+   - Most-aware — ready to buy, just needs the offer
+
+### Step 1: Capture the Page
+
+Get the page content. Try these in order:
+1. **User provides URL** — Use WebFetch or browser tool to get the rendered page
+2. **User provides HTML/markdown** — Work with what's given
+3. **User describes the page** — Ask for the actual page content before auditing; descriptions alone produce weak audits
+
+If the page is behind authentication, ask the user to paste the HTML or provide screenshots.
+
+Extract and map:
+- Hero section (headline, subheadline, CTA)
+- Navigation and header
+- Each content section in scroll order
+- All CTAs (primary, secondary, inline)
+- Social proof elements (testimonials, logos, stats)
+- Forms and their fields
+- Footer and secondary navigation
+- Page load performance indicators
+
+### Step 2: Run the Audit
+
+Score each element 1-10 with specific reasoning.
+
+#### Hero Section Audit
+
+| Check | What to look for |
+|-------|-----------------|
+| Headline clarity | Does it pass the 5-second test? Can a stranger understand what you do? |
+| Specificity | Numbers, outcomes, timeframes > vague claims |
+| Subheadline | Expands on HOW, not just restates the headline |
+| Hero CTA | Single, clear, action-oriented. Not "Submit" or "Learn More" |
+| Visual | Supports the message, not decorative stock photos |
+| Above-fold completeness | Headline + value prop + CTA + credibility signal all visible without scrolling |
+
+**5-Second Test:** If someone sees only the above-fold content for 5 seconds, can they answer:
+1. What does this product do?
+2. Who is it for?
+3. Why should I care?
+4. What do I do next?
+
+#### CTA Audit
+
+| Check | What to look for |
+|-------|-----------------|
+| Primary CTA count | One primary action per page. Multiple = decision paralysis |
+| CTA copy | Action verb + outcome. "Start free trial" > "Sign up" > "Submit" |
+| CTA contrast | Visually dominant, not competing with other elements |
+| CTA frequency | Appears after every major content section |
+| CTA anxiety reducers | "No credit card required", "Cancel anytime", "2-minute setup" |
+| Secondary CTA | Lower-commitment alternative for not-ready visitors |
+
+#### Social Proof Audit
+
+| Check | What to look for |
+|-------|-----------------|
+| Testimonial specificity | Named person + role + company + specific result > anonymous quote |
+| Logo bar | Recognizable brands, 5-8 logos, "Trusted by" framing |
+| Stats | Specific numbers ("12,847 teams" not "thousands of teams") |
+| Case studies | At least one detailed success story linked |
+| Review scores | G2, Capterra, Product Hunt badges if applicable |
+| Placement | Social proof appears before the main CTA, not buried at bottom |
+
+#### Objection Handling Audit
+
+| Check | What to look for |
+|-------|-----------------|
+| Price objection | ROI framing, comparison anchoring, money-back guarantee |
+| Trust objection | Security badges, compliance logos, data handling statement |
+| Effort objection | "Setup in 5 minutes", migration assistance, onboarding help |
+| Switching objection | Import tools, comparison with current solution |
+| FAQ section | Addresses top 5-7 real objections, not softballs |
+
+#### Form Friction Audit
+
+| Check | What to look for |
+|-------|-----------------|
+| Field count | Every field above 3 reduces conversion. Justify each field |
+| Required vs optional | Mark optional fields or remove them |
+| Field labels | Above the field, not placeholder text that disappears |
+| Error handling | Inline validation, specific error messages |
+| Multi-step | If >4 fields, break into steps with progress indicator |
+| Social login | Google/GitHub/SSO options reduce friction |
+
+### Step 3: Score and Prioritize
+
+Generate a priority matrix. Score each of the 5 audit areas 1-10 (hero, CTA, social proof, objection handling, form friction). Sum them, multiply by 2 to get a /100 score. Then assign priority based on impact and effort:
+
+```
+## CRO Audit Score: [X]/100
+
+| Element | Score | Impact | Effort | Priority |
+|---------|-------|--------|--------|----------|
+| Hero headline | 4/10 | High | Low | P0 |
+| CTA copy | 3/10 | High | Low | P0 |
+| Social proof | 5/10 | High | Medium | P1 |
+| Form friction | 6/10 | Medium | Medium | P2 |
+| Objection handling | 2/10 | High | Medium | P1 |
+
+Priority ranking: High impact + Low effort = P0, High impact + Medium effort = P1, everything else = P2
+```
+
+### Step 4: Generate Recommendations
+
+For each P0 and P1 issue, provide:
+
+```markdown
+### Issue: [Element] — Score [X/10]
+
+**Problem:** [Specific description of what's wrong]
+
+**Before:**
+> [Exact current copy/structure]
+
+**After:**
+> [Rewritten copy/structure]
+
+**Why this works:** [Psychology principle or data point backing the change]
+
+**Expected impact:** [Estimated conversion lift range]
+```
+
+### Step 5: Provide Implementation Checklist
+
+```markdown
+## Implementation Priority
+
+### This Week (P0 — High Impact, Low Effort)
+- [ ] Rewrite hero headline to [specific suggestion]
+- [ ] Change CTA from "[current]" to "[suggested]"
+- [ ] Add anxiety reducer below primary CTA
+
+### Next Sprint (P1 — High Impact, Medium Effort)
+- [ ] Add 3 specific testimonials with results
+- [ ] Create FAQ section addressing [top objections]
+- [ ] Add logo bar above the fold
+
+### Backlog (P2 — Medium Impact)
+- [ ] Reduce form fields from [X] to [Y]
+- [ ] Add secondary CTA for lower-commitment action
+- [ ] Implement exit-intent offer
+```
+
+## Key Frameworks
+
+### AIDA (Attention-Interest-Desire-Action)
+- **Attention:** Headline that stops the scroll
+- **Interest:** Subheadline that creates curiosity
+- **Desire:** Benefits, social proof, and outcomes that build want
+- **Action:** Clear, low-friction CTA
+
+### PAS (Problem-Agitate-Solve)
+- **Problem:** Name the specific pain point
+- **Agitate:** Amplify the consequences of not solving it
+- **Solve:** Present your product as the resolution
+
+### Above-the-Fold Checklist
+Everything visible without scrolling must include:
+1. Clear headline (what you do)
+2. Subheadline (how/why it matters)
+3. Primary CTA (what to do next)
+4. One credibility signal (logo bar, stat, or testimonial)
+5. Relevant visual (product screenshot > stock photo)
+
+## CTA Copy Formulas
+
+| Pattern | Example |
+|---------|---------|
+| Action + Outcome | "Start saving 10 hours/week" |
+| Action + Timeframe | "Get started in 2 minutes" |
+| Action + Risk Reversal | "Try free for 14 days" |
+| Action + Specificity | "Build your first workflow" |
+
+## Worked Example
+
+- **Hero: 7/10** — Headline is benefit-focused but subhead is too long. Recommend: cut to 8 words.
+- **CTA: 5/10** — Generic 'Sign Up' button. Recommend: 'Start your free trial' with benefit reinforcement.
+- **Social Proof: 3/10** — No testimonials above fold. Recommend: add 1-2 customer quotes near CTA.
+
+## Anti-Patterns
+
+- Don't suggest a complete page redesign — focus on conversion fixes within the existing structure
+- Don't critique branding, aesthetics, or color choices unless they directly impact conversion (e.g., CTA blends into background)
+- Don't provide vague advice ("improve the headline") — every recommendation must include specific rewrite copy
+- Don't audit content/blog pages as if they were landing pages — different goals, different criteria
+- Don't recommend tools or integrations the agent can't implement — stay within copy and structural changes
+- Don't ignore mobile — flag any element that would break on small screens
+
+## Edge Cases
+
+- **Page behind auth:** Ask user to paste HTML or provide screenshots. Don't attempt to bypass login.
+- **Blog/content page:** Shift criteria — evaluate for CTA to next step (newsletter, lead magnet), not for direct conversion. Skip form friction audit.
+- **No clear CTA:** Flag as P0. The page needs a CTA before anything else matters.
+- **Mobile-only page:** Prioritize tap target sizes, scroll depth, and thumb-zone placement in recommendations.
+
+See `references/cro-benchmarks.md` for industry conversion rates, element-specific impact data, and A/B test planning benchmarks. Use these to ground scores and expected impact estimates in real numbers.
+
+## Recommendation Psychology
+
+Ground every recommendation in conversion psychology: social proof leverages conformity bias, anxiety reducers counter loss aversion, benefit-focused CTAs activate approach motivation. The 5-second test works because users form lasting first impressions in 50ms — if the value prop isn't instant, bounce rates spike.
+
+## Output
+
+The audit produces:
+- Scored element breakdown with specific reasoning
+- Prioritized recommendation list (P0/P1/P2)
+- Before/after copy rewrites for every P0 and P1 item
+- Implementation checklist ordered by impact/effort
+- Framework references for each recommendation
+
+## Quality Checks
+
+- [ ] Every P0/P1 issue has a specific before/after rewrite, not vague advice
+- [ ] Copy rewrites match brand voice (if voice-profile.md exists)
+- [ ] Recommendations are achievable without a full redesign
+- [ ] Mobile experience considered for all recommendations
+- [ ] Prioritization reflects actual impact/effort, not just opinion
+- [ ] Social proof recommendations reference specific proof types available to the brand

package/skills/page-cro/references/cro-benchmarks.md

@@ -0,0 +1,140 @@
+# CRO Benchmarks & Industry Data
+
+Conversion rate benchmarks and element-specific data to ground audit recommendations in real numbers.
+
+---
+
+## Landing Page Conversion Rates by Industry
+
+| Industry | Median CR | Top 25% CR | Top 10% CR |
+|----------|-----------|------------|------------|
+| SaaS / Software | 3.0% | 6.5% | 11.7% |
+| E-commerce | 2.6% | 5.2% | 9.8% |
+| Finance / Insurance | 4.3% | 8.1% | 14.2% |
+| Education | 3.4% | 7.0% | 13.0% |
+| Healthcare | 3.6% | 6.9% | 12.5% |
+| Agency / Consulting | 2.5% | 5.0% | 10.0% |
+| Real Estate | 2.8% | 5.5% | 10.5% |
+| Travel | 3.1% | 5.7% | 11.0% |
+
+**Source context:** These ranges reflect typical landing page CRs across multiple studies (Unbounce, WordStream, HubSpot). Use as directional benchmarks, not absolute targets — CR depends heavily on traffic quality, offer strength, and page intent.
+
+---
+
+## Element-Specific Impact Data
+
+### Headlines
+
+- Pages with specific, benefit-driven headlines convert 2-3x higher than vague ones
+- Including a number in the headline increases engagement by ~36%
+- Question-format headlines can increase CR by 10-25% (context-dependent)
+- Optimal headline length: 6-12 words for landing pages
+
+### CTAs
+
+| CTA Pattern | Typical Lift vs. Generic |
+|-------------|------------------------|
+| Action + outcome ("Start saving time") | +30-40% vs. "Submit" |
+| First-person ("Start my free trial") | +25-90% vs. third-person |
+| Urgency + reason ("Get instant access") | +10-20% |
+| Risk reversal ("Try free — no card needed") | +15-30% |
+
+**Button color:** No single "best" color — contrast with the page matters more than the specific hue. The CTA should be the most visually dominant element above the fold.
+
+**CTA count:** Pages with a single primary CTA convert higher than pages with multiple competing CTAs. Decision paralysis is real — Hick's Law shows that more choices increase decision time and reduce action.
+
+### Social Proof
+
+| Proof Type | Typical Impact |
+|------------|---------------|
+| Customer testimonials (with photo + name) | +20-35% CR lift |
+| Logo bar (5-8 recognizable brands) | +10-20% trust signal |
+| Specific user count ("12,847 teams") | +15-25% vs. vague claims |
+| Star ratings / review badges | +10-15% |
+| Case study link | +5-10% (indirect, builds confidence) |
+
+**Placement matters:** Social proof placed before or alongside the primary CTA outperforms proof buried at the bottom of the page. The proof should be visible at the decision point, not after the user has already decided.
+
+### Form Friction
+
+| Fields | Typical Completion Rate |
+|--------|----------------------|
+| 1 field (email only) | 25-40% |
+| 2-3 fields | 20-30% |
+| 4-5 fields | 15-20% |
+| 6+ fields | <10% |
+
+**Rule of thumb:** Each additional form field above 3 reduces conversion by ~5-10%. Every field must justify its existence by either being legally required or providing enough value to outweigh the friction.
+
+**Multi-step forms:** Breaking a long form into 2-3 steps with a progress bar can recover 20-40% of the drop-off from a single long form — the commitment bias from completing step 1 drives completion of steps 2+.
+
+---
+
+## Above-the-Fold Benchmarks
+
+- Users spend 57% of their viewing time above the fold (Nielsen Norman Group)
+- First impression forms in ~50ms — the above-fold content IS the first impression
+- Pages with a clear headline + CTA + credibility signal above the fold convert 2-3x vs. those requiring a scroll to understand the offer
+- Optimal hero section height: 600-800px (ensures CTA visibility on most screens without scrolling)
+
+---
+
+## Page Speed & Conversion
+
+| Load Time | Impact |
+|-----------|--------|
+| 1s → 3s | Bounce probability increases 32% |
+| 1s → 5s | Bounce probability increases 90% |
+| 1s → 6s | Bounce probability increases 106% |
+| 1s → 10s | Bounce probability increases 123% |
+
+**Source:** Google/SOASTA research. Page speed is a conversion factor but typically a P2 recommendation since it requires engineering effort. Flag it in the audit but focus copy/structural fixes first.
+
+---
+
+## Mobile vs. Desktop
+
+| Metric | Desktop | Mobile |
+|--------|---------|--------|
+| Avg. session duration | 4-6 min | 2-3 min |
+| Avg. conversion rate | 3-5% | 1.5-3% |
+| Form completion rate | Higher | 30-50% lower |
+| Scroll depth | 60-70% | 50-60% |
+
+**Implication:** Mobile users are more impatient, scroll less, and abandon forms faster. Mobile CRO means: shorter copy above fold, larger tap targets (min 44x44px), fewer form fields, and sticky CTAs that stay visible during scroll.
+
+---
+
+## A/B Test Planning
+
+### Sample Size Estimation
+
+To detect a 10% relative improvement (e.g., 3% → 3.3% CR):
+- At 95% confidence, 80% power: ~30,000 visitors per variant
+- At 90% confidence, 80% power: ~22,000 visitors per variant
+
+To detect a 25% relative improvement (e.g., 3% → 3.75% CR):
+- At 95% confidence: ~5,000 visitors per variant
+- At 90% confidence: ~3,800 visitors per variant
+
+**Rule of thumb:** Run tests for minimum 2 weeks regardless of traffic (to capture day-of-week effects). Stop tests only after reaching statistical significance AND minimum duration.
+
+### What to Test First
+
+Priority order by typical impact:
+1. Headline copy (highest impact, lowest effort)
+2. CTA copy and placement
+3. Social proof presence and positioning
+4. Form field count
+5. Page layout / section ordering
+6. Visual elements (images, video)
+
+---
+
+## Using These Benchmarks
+
+These numbers provide context for audit scores and expected impact estimates. When recommending changes:
+- Reference the benchmark to justify priority ("Your CR of 1.2% is below the 3.0% industry median")
+- Use impact ranges from this file for "Expected impact" in recommendations
+- Cite the reasoning behind the data, not just the number — this helps the user understand why the change matters
+- Acknowledge that benchmarks are directional — specific results depend on traffic source, offer, and audience