@jairodri/huckleberry-cli 1.0.2 → 1.1.0

package/skills/form-cro/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "form-cro",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Audit our demo request form. It currently has these fields: First Name, Last Name, Work Email, Phone Number, Company Name, Company Size, Job Title, Industry, Current Solution, Budget Range, and a 'Tell us about your needs' textarea. Our conversion rate is 3.1% and we want to improve it.",
+      "expected_output": "Should check for product-marketing-context.md first. Should apply the 'every field has a cost' principle — 11 fields is excessive for a demo form. Should reference the field cost data (3 fields baseline, 7+ fields = 25-50% conversion reduction). Should evaluate each field: which are essential for demo prep, which can be collected later or inferred. Should recommend cutting to essential fields (likely Work Email, Company Name, and maybe one qualifier). Should provide audit findings in the structured format (Issue, Impact, Fix, Priority). Should recommend Quick Wins, High-Impact Changes, and Test Ideas.",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Applies 'every field has a cost' principle",
+        "References field count impact data",
+        "Evaluates each field for necessity",
+        "Recommends cutting to essential fields",
+        "Provides findings in structured format (Issue, Impact, Fix, Priority)",
+        "Includes Quick Wins, High-Impact Changes, Test Ideas"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "Our contact form just has Name, Email, and Message fields but we're getting a lot of spam submissions and low-quality leads. How do we fix this without adding too much friction?",
+      "expected_output": "Should apply the contact form type guidance. Should address spam with non-friction solutions first: honeypot fields, reCAPTCHA, server-side validation. Should then address lead quality: suggest adding one qualifying field (company name or budget range) to filter without excessive friction. Should apply the error handling guidance for validation. Should recommend form layout and submit button optimization. Should balance quality vs quantity in recommendations.",
+      "assertions": [
+        "Applies contact form type guidance",
+        "Recommends anti-spam solutions (honeypot, reCAPTCHA)",
+        "Suggests minimal qualifying fields for lead quality",
+        "Balances quality vs quantity",
+        "Addresses error handling and validation",
+        "Recommends non-friction solutions first"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "should we use a single-step or multi-step form for our quote request? we need company info, project details, timeline, and budget.",
+      "expected_output": "Should trigger on casual phrasing. Should apply the multi-step form guidance — with this many required data types, multi-step is likely better. Should reference the threshold: multi-step recommended when more than 5-6 fields. Should recommend grouping by type (contact info → project details → budget/timeline). Should include progress indicator recommendation. Should apply best practices: easy questions first, save progress, allow back navigation. Should note that multi-step often increases completion for longer forms.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Recommends multi-step based on field count",
+        "References the 5-6 field threshold for multi-step",
+        "Suggests logical field grouping",
+        "Recommends progress indicator",
+        "Applies multi-step best practices",
+        "Notes multi-step increases completion for longer forms"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "How should we handle form errors? Users keep getting frustrated and abandoning our lead capture form when they hit validation errors.",
+      "expected_output": "Should apply the error handling guidance. Should recommend inline validation (not just on submit). Should provide specific error message examples (helpful, not generic). Should recommend: don't clear the form on error, focus on the problem field, show requirements upfront not after failure. Should address common validation UX issues: email format, phone format, required field indicators. Should provide examples of good vs bad error messages.",
+      "assertions": [
+        "Applies error handling guidance",
+        "Recommends inline validation",
+        "Provides specific error message examples",
+        "Recommends not clearing form on error",
+        "Recommends showing requirements upfront",
+        "Provides good vs bad error message examples",
+        "Addresses common validation UX issues"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "We need to optimize our form for mobile. Over 60% of our traffic is mobile but our form conversion rate on mobile is half of desktop.",
+      "expected_output": "Should apply the mobile optimization guidance. Should recommend: larger touch targets (44px+ height), appropriate keyboard types (email, tel), autofill support, single column layout, sticky CTA button, reduce typing (use dropdowns, toggles). Should address mobile-specific form issues: viewport, font size, button placement, scroll behavior. Should recommend testing with actual devices.",
+      "assertions": [
+        "Applies mobile optimization guidance",
+        "Recommends larger touch targets (44px+)",
+        "Recommends appropriate keyboard types",
+        "Recommends autofill support",
+        "Recommends single column layout",
+        "Addresses mobile-specific issues",
+        "Recommends testing with actual devices"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Our signup form has too many fields and people keep abandoning it halfway through. Can you help optimize it?",
+      "expected_output": "Should recognize this is about signup/registration form optimization, not general form CRO. Should defer to or cross-reference the signup-flow-cro skill, which specifically handles signup, registration, and account creation flows. May provide general form friction advice but should make clear that signup-flow-cro is the right skill for signup forms.",
+      "assertions": [
+        "Recognizes this as signup flow optimization",
+        "References or defers to signup-flow-cro skill",
+        "Does not attempt full signup form optimization using general form CRO patterns"
+      ],
+      "files": []
+    }
+  ]
+}

package/skills/free-tool-strategy/SKILL.md

@@ -0,0 +1,325 @@
+---
+name: free-tool-strategy
+description: "Plans free tools, calculators, generators, and interactive widgets that attract target audience through search and social sharing."
+allowed-tools: []
+---
+
+# Free Tool Strategy (Engineering as Marketing)
+
+## Purpose
+
+Free tools are permanent acquisition assets. Build a calculator, checker, generator, or grader that your target audience actively searches for. It ranks in Google, gets shared, and funnels users to your paid product. One tool can drive more signups than months of content.
+
+## Reads
+
+- `brand/audience.md` — Personas, daily workflow, pain points
+- `brand/keyword-plan.md` — Search volume data for tool-related queries
+- `brand/positioning.md` — Positioning angles to connect tool → product
+- `brand/creative-kit.md` — Brand colors, fonts for tool landing page
+
+## On Activation
+
+1. Read `brand/audience.md`, `brand/keyword-plan.md`, `brand/positioning.md`, `brand/creative-kit.md`.
+2. If any file is missing, note what's unavailable. The skill works at zero context — ask the user directly for missing info in Step 1.
+3. Pre-fill persona details, keyword data, and positioning angles from whatever brand/ files exist. Only ask for what's genuinely unknown.
+
+Why these files matter: audience.md tells you whose pain to solve (without this, tools target the wrong users). keyword-plan.md gives search volume data so you don't build tools nobody searches for. positioning.md connects the free tool to the paid product (without this connection, traffic doesn't convert). creative-kit.md ensures the tool landing page matches the brand.
+
+## Workflow
+
+### Step 1: Identify Audience Workflow Pain Points
+
+If `brand/audience.md` exists, extract the primary persona and their pain points — skip the interview below and go straight to Step 2 with that data. If not, map the target audience's daily workflow and find friction:
+
+```
+Persona: [Role/Title]
+Daily workflow:
+1. [Task] -> Pain: [what's annoying about this]
+2. [Task] -> Pain: [what's tedious/manual]
+3. [Task] -> Pain: [what requires expensive tools]
+4. [Task] -> Pain: [what they currently use spreadsheets for]
+5. [Task] -> Pain: [what they google repeatedly]
+```
+
+Best free tool candidates solve pains that are:
+- Recurring (done weekly or more)
+- Currently solved with manual effort or spreadsheets
+- Searchable ("X calculator", "X generator", "X checker")
+- Completable in one session (not ongoing SaaS)
+- Adjacent to your paid product's value prop
+
+### Step 2: Match to Buildable Tools
+
+#### Tool Type Matrix
+
+| Tool Type | Best For | Search Pattern | Build Effort |
+|-----------|----------|---------------|-------------|
+| Calculator | Quantifiable decisions | "[X] calculator" | Low |
+| Generator | Content/creative tasks | "[X] generator" | Low-Medium |
+| Checker/Auditor | Quality assessment | "[X] checker", "[X] audit" | Medium |
+| Grader/Scorer | Benchmarking | "[X] grader", "[X] score" | Medium |
+| Converter | Format transformations | "[X] to [Y] converter" | Low |
+| Template library | Workflow shortcuts | "[X] templates" | Low |
+| Comparison tool | Purchase decisions | "compare [X]" | Medium |
+| Playground/Sandbox | Try-before-buy | "try [X] online" | High |
+
+#### Idea Generation Framework
+
+For each persona pain point, ask:
+1. Can we calculate something for them? -> Calculator
+2. Can we create something for them? -> Generator
+3. Can we evaluate something for them? -> Checker/Grader
+4. Can we simplify a conversion? -> Converter
+5. Can we give them a head start? -> Template
+6. Can we let them try before buying? -> Playground
+
+Score each idea:
+
+| Criteria | Weight | Score 1-5 |
+|----------|--------|-----------|
+| Search volume for "[tool] [type]" | 30% | |
+| Relevance to paid product | 25% | |
+| Build effort (inverse) | 20% | |
+| Shareability | 15% | |
+| Data capture opportunity | 10% | |
+
+### Step 3: Validate Search Volume
+
+For each tool candidate, check:
+
+```
+Primary keyword: "[tool name]" — Volume: [X], Difficulty: [Y]
+Variations:
+- "free [tool name]" — Volume: [X]
+- "[tool name] online" — Volume: [X]
+- "best [tool name]" — Volume: [X]
+- "[specific use case] [tool type]" — Volume: [X]
+
+Total addressable search volume: [sum]
+Current top results: [list competitors and their quality]
+Opportunity: [Can we build something meaningfully better?]
+```
+
+Kill the idea if:
+- Total search volume < 1,000/month
+- Top 3 results are high-authority sites with excellent tools
+- Tool requires ongoing data maintenance you can't sustain
+
+### If Web Search Is Unavailable
+
+Assess tool viability based on: (1) audience pain intensity from brand/audience.md, (2) user's direct knowledge of search intent, (3) competitive landscape from brand/competitors.md. Skip search volume validation but note: 'Tool concept is validated on strategic merit, not search data. Run keyword validation before investing in development.'
+
+### Step 4: Design Tool UX Flow
+
+```
+Page 1: Landing + Input
+|- Headline: "[Verb] your [thing] in [time]"
+|- Subheadline: "Free [tool type] — no signup required"
+|- Input area: [minimal fields/inputs needed]
+|- CTA: "[Action verb] — it's free"
+|- Social proof: "[X] people used this tool this month"
+
+Page 2: Results
+|- Results display: [clear, visual, actionable output]
+|- Shareable result: [unique URL or image for sharing]
+|- Email gate (optional): "Get detailed results + recommendations"
+|- Product tie-in: "Want to [do this automatically]? Try [Product]"
+|- CTA: "[Start free trial]" (secondary, not aggressive)
+
+Optional: Comparison/benchmark
+|- "Your score: [X]. Average in your industry: [Y]"
+|- "Top performers score [Z]. Here's how to get there."
+|- Link to relevant content/product features
+```
+
+#### UX Principles for Free Tools
+
+- **No signup wall before results.** Let them use the tool first. Gate the detailed report or saved results, not the core function.
+- **Instant results.** No "we'll email you." Show results immediately.
+- **One input screen.** If you need 10 fields, progressive disclosure or smart defaults.
+- **Shareable output.** Unique URL, downloadable image, or embeddable widget.
+- **Mobile-first.** Most discovery happens on phones.
+
+### Step 5: Plan SEO Strategy
+
+On-page optimization for the tool landing page:
+
+```
+Title tag: "Free [Tool Name] — [Benefit] | [Brand]"
+Meta description: "[Verb] your [thing] with our free [tool type]. No signup required. Used by [X]+ [personas]."
+H1: "[Verb] Your [Thing] in [Time]"
+URL: /tools/[tool-name]
+
+Content sections (below the tool):
+1. "How to use this [tool type]" — captures "how to" queries
+2. "What is [concept]?" — captures informational queries
+3. "Why [concept] matters" — builds authority
+4. "[Tool type] methodology" — transparency + E-E-A-T
+5. FAQ — captures long-tail questions
+
+Internal links:
+- From tool -> relevant blog posts
+- From tool -> product features that automate this
+- From blog posts -> tool (embed or link)
+```
+
+Link building angles:
+- Pitch to roundup posts: "best [X] tools" articles
+- Resource pages in your niche
+- Social sharing of interesting results/benchmarks
+
+### Step 6: Define Conversion Hooks
+
+The tool-to-product bridge. Never bait-and-switch — the connection must be genuine:
+
+| Hook Type | When to Use | Example |
+|-----------|-------------|---------|
+| Automation hook | Tool does manually what product automates | "Tired of running this manually? [Product] does it continuously." |
+| Depth hook | Tool gives surface results, product goes deeper | "Want the full analysis? [Product] checks [X] more factors." |
+| Save/history hook | Tool has no memory, product persists | "Save your results and track changes over time with [Product]." |
+| Team hook | Tool is single-player, product is multiplayer | "Share results with your team. [Start free trial]" |
+| Integration hook | Tool is standalone, product connects | "[Product] connects this to your [workflow/tools]." |
+
+### Step 7: Write Tool Landing Page Copy
+
+```markdown
+# [Verb] Your [Thing] in [Time]
+
+Free [tool type] for [audience]. No signup required.
+
+[Tool input area]
+
+[Primary CTA: "Analyze" / "Generate" / "Calculate"]
+
+---
+
+## How It Works
+1. [Input step — what user provides]
+2. [Process step — what the tool does]
+3. [Output step — what user gets]
+
+## Why [X,000]+ [Personas] Use This Tool
+
+[2-3 specific testimonials or usage stats]
+
+## [Concept] Explained
+[Educational content that captures informational search traffic
+and establishes authority. 300-500 words.]
+
+## FAQ
+**Is this really free?**
+Yes. No credit card, no signup, no catch.
+
+**How accurate is this?**
+[Methodology explanation. Transparency builds trust.]
+
+**Can I save my results?**
+[If gated: "Create a free account to save and share results."]
+[If not: "Download your results as [format]."]
+
+**Who built this?**
+[Product] is [brief description]. This tool is part of how we help
+[audience] [achieve outcome].
+
+---
+
+## Want to [automate/go deeper]?
+
+[Product] does everything this tool does — automatically,
+continuously, and with [additional benefits].
+
+[Start Free Trial] — No credit card required.
+```
+
+## Anti-Patterns
+
+| Mistake | Why It Fails |
+|---------|-------------|
+| Building a tool that requires ongoing data maintenance | You'll abandon it in 3 months. Tools should be stateless or use user-provided input. |
+| Tool has no connection to paid product | Drives traffic that never converts. The tool must demonstrate a pain your product solves. |
+| Too complex for a side project | If it takes more than 2-3 weeks to build, it's not a free tool — it's a product. Scope aggressively. |
+| Gating core results behind signup | Users bounce. Show results first, gate the detailed report or saved history. |
+| Copying an existing tool without differentiation | "Another X calculator" won't rank or get shared. Find the angle — faster, more specific, better UX. |
+| Building for vanity search volume | High-volume generic tools (e.g., "word counter") attract the wrong audience. Target tool queries adjacent to your product. |
+
+## Tech Stack Recommendations
+
+Pick the simplest stack that works:
+
+| Complexity | Stack | When to Use |
+|-----------|-------|-------------|
+| Low | Single HTML + vanilla JS | Calculators, converters, simple generators |
+| Medium | Next.js / Astro | Multi-page tools, tools needing API calls |
+| High | Next.js + database | Tools requiring saved results, user accounts |
+
+Default recommendation: **single-page HTML/JS** unless the tool genuinely requires server-side processing. Simpler = ships faster = starts ranking sooner.
+
+## Tool Category Examples
+
+**For Marketers:**
+- Headline analyzer, email subject line grader, readability checker
+- Ad copy generator, CTA optimizer, meta description writer
+- SEO audit tool, keyword density checker, backlink checker
+
+**For Developers:**
+- JSON formatter, regex tester, cron expression builder
+- API response validator, color palette generator, favicon generator
+- Performance budget calculator, bundle size analyzer
+
+**For Business:**
+- ROI calculator, pricing calculator, break-even analyzer
+- Invoice generator, proposal template builder
+- Competitor comparison matrix generator
+
+**For Designers:**
+- Color contrast checker, font pairing tool, spacing calculator
+- Responsive breakpoint visualizer, icon search
+
+## Metrics to Track
+
+| Metric | What It Tells You |
+|--------|------------------|
+| Tool pageviews | SEO and sharing effectiveness |
+| Tool completions | UX quality (started vs finished) |
+| Result shares | Viral potential |
+| Email captures | Lead gen effectiveness |
+| Tool -> Signup rate | Conversion hook quality |
+| Tool -> Paid rate | Product-tool alignment |
+| Organic ranking | SEO investment payoff |
+
+## Output
+
+Write all deliverables to `marketing/free-tool-strategy/`. Each strategy produces:
+
+```markdown
+# Free Tool Strategy: [Product Name]
+
+## Recommended Tool: [Tool Name]
+- Type: [Calculator/Generator/Checker/etc.]
+- Primary keyword: "[keyword]" — [X] monthly searches
+- Build effort: [Low/Medium/High] — estimated [X] days
+- Tech stack: [recommendation]
+
+## Tool Ideas (Ranked)
+
+| Rank | Tool | Type | Search Vol | Product Relevance | Score |
+|------|------|------|-----------|-------------------|-------|
+| 1 | [name] | [type] | [vol] | [relevance] | [X/5] |
+| 2 | ... | ... | ... | ... | ... |
+| 3 | ... | ... | ... | ... | ... |
+
+## Search Volume Validation (Top 3)
+[Validation data per Step 3]
+
+## UX Flow
+[Per Step 4 template]
+
+## SEO Strategy
+[Per Step 5]
+
+## Conversion Hook
+[Per Step 6]
+
+## Landing Page Copy
+[Per Step 7 template]
+```

package/skills/free-tool-strategy/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "free-tool-strategy",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "We want to build a free tool to drive leads for our SEO software. We're thinking about an SEO audit tool or a keyword research tool. Which would be better and how should we approach it?",
+      "expected_output": "Should check for product-marketing-context.md first. Should apply the evaluation scorecard to compare both tool ideas across dimensions (audience alignment, lead quality, build effort, SEO value, maintenance burden, competitive differentiation). Should reference the tool types from the skill (analyzers, testers). Should recommend the stronger option with rationale. Should discuss lead capture gating strategy (what's free vs what requires email). Should address MVP scope — what's the minimum valuable version. Should provide implementation recommendations.",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Applies evaluation scorecard to compare options",
+        "References tool types from the skill",
+        "Recommends one option with clear rationale",
+        "Discusses lead capture gating strategy",
+        "Addresses MVP scope",
+        "Provides implementation recommendations"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "I want to build a free ROI calculator for our HR software. Users input their company size and current processes, and it shows how much time and money they'd save.",
+      "expected_output": "Should identify this as a calculator tool type. Should apply the ideation framework to validate the concept. Should discuss lead capture strategy: should the basic result be free and detailed report gated? Should address the build vs buy decision. Should recommend MVP scope (what inputs, what outputs, what formula). Should discuss SEO considerations for the tool page. Should reference the evaluation scorecard to score the idea.",
+      "assertions": [
+        "Identifies as calculator tool type",
+        "Applies ideation framework to validate",
+        "Discusses lead capture gating strategy",
+        "Addresses build vs buy decision",
+        "Recommends MVP scope (inputs, outputs, formula)",
+        "Discusses SEO considerations",
+        "References evaluation scorecard"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "give me some ideas for free tools we could build. we sell email marketing software for e-commerce brands.",
+      "expected_output": "Should trigger on casual phrasing. Should apply the ideation framework to generate tool ideas relevant to email marketing + e-commerce. Should provide 5-8 ideas across different tool types (calculators, generators, analyzers, testers). Examples: email subject line tester, email deliverability checker, email ROI calculator, email template generator, spam score checker. Should briefly score each against the evaluation dimensions. Should recommend top 2-3 to pursue.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Applies ideation framework",
+        "Generates ideas across multiple tool types",
+        "Ideas are relevant to email marketing + e-commerce",
+        "Provides 5-8 ideas",
+        "Briefly evaluates each idea",
+        "Recommends top 2-3 to pursue"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "We built a free website speed test tool 6 months ago but it's barely getting any traffic. What went wrong and how do we fix it?",
+      "expected_output": "Should diagnose why the tool isn't getting traffic. Should investigate: SEO strategy for the tool page (target keywords, on-page optimization), distribution strategy (was it launched and forgotten?), competitive landscape (are there dominant free tools already?), tool quality and UX (does it provide unique value?). Should apply the engineering as marketing principles. Should recommend a recovery plan: SEO improvements, content marketing around the tool, product improvements for differentiation.",
+      "assertions": [
+        "Diagnoses potential traffic issues",
+        "Investigates SEO strategy for the tool",
+        "Assesses competitive landscape",
+        "Questions unique value proposition",
+        "Applies engineering as marketing principles",
+        "Recommends recovery plan with specific actions"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "Should we gate our free tool behind an email capture or make it completely free? We want leads but don't want to kill usage.",
+      "expected_output": "Should apply the lead capture gating strategy framework. Should present the spectrum: fully ungated → partial gating (basic results free, detailed report gated) → fully gated. Should recommend partial gating as the typical best approach — give enough value to demonstrate the tool's worth, gate the detailed/actionable output. Should discuss tradeoffs: ungated = more SEO value and usage, gated = more leads but fewer users. Should provide specific gating recommendations based on tool type.",
+      "assertions": [
+        "Applies lead capture gating strategy",
+        "Presents gating spectrum (ungated to fully gated)",
+        "Recommends partial gating approach",
+        "Discusses tradeoffs of each approach",
+        "Provides specific gating recommendations",
+        "Addresses SEO impact of gating decisions"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "How do I optimize the landing page for our free tool to get more signups? The tool itself is great but nobody finds it.",
+      "expected_output": "Should recognize this is a landing page conversion optimization task, not a free tool strategy task. Should defer to or cross-reference the page-cro skill for optimizing the tool's landing page conversion rate. May provide free-tool-specific context (gating strategy, value demonstration) but should make clear that page-cro is the right skill for page conversion optimization.",
+      "assertions": [
+        "Recognizes this as page CRO, not free tool strategy",
+        "References or defers to page-cro skill",
+        "May provide free-tool-specific context",
+        "Does not attempt full page CRO using free tool strategy patterns"
+      ],
+      "files": []
+    }
+  ]
+}