@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/free-tool-strategy/references/tool-types.md

@@ -0,0 +1,253 @@
+# Free Tool Types Reference
+
+Detailed guide to each type of marketing tool you can build.
+
+## Contents
+- Calculators
+- Generators
+- Analyzers/Auditors
+- Testers/Validators
+- Libraries/Resources
+- Interactive Educational
+- Tool Concept Examples by Industry (SaaS product, agency/services, e-commerce, developer tools, finance)
+
+## Calculators
+
+**Best for**: Decisions involving numbers, comparisons, estimates
+
+**Examples**:
+- ROI calculator
+- Savings calculator
+- Cost comparison tool
+- Salary calculator
+- Tax estimator
+- Pricing estimator
+- Compound interest calculator
+- Break-even calculator
+
+**Why they work**:
+- Personalized output
+- High perceived value
+- Share-worthy results
+- Clear problem → solution
+
+**Implementation tips**:
+- Keep inputs simple
+- Show calculations transparently
+- Make results shareable
+- Add "powered by" branding
+
+---
+
+## Generators
+
+**Best for**: Creating something useful quickly
+
+**Examples**:
+- Policy generator (privacy, terms)
+- Template generator
+- Name/tagline generator
+- Email subject line generator
+- Resume builder
+- Color palette generator
+- Logo maker
+- Contract generator
+
+**Why they work**:
+- Tangible output
+- Saves time
+- Easily shared
+- Repeat usage
+
+**Implementation tips**:
+- Output should be immediately usable
+- Allow customization
+- Offer download/export options
+- Include email gating for premium outputs
+
+---
+
+## Analyzers/Auditors
+
+**Best for**: Evaluating existing work or assets
+
+**Examples**:
+- Website grader
+- SEO analyzer
+- Email subject tester
+- Headline analyzer
+- Security checker
+- Performance auditor
+- Accessibility checker
+- Code quality analyzer
+
+**Why they work**:
+- Curiosity-driven
+- Personalized insights
+- Creates awareness of problems
+- Natural lead to solution
+
+**Implementation tips**:
+- Score or grade for gamification
+- Benchmark against averages
+- Provide actionable recommendations
+- Follow up with improvement offers
+
+---
+
+## Testers/Validators
+
+**Best for**: Checking if something works
+
+**Examples**:
+- Meta tag preview
+- Email rendering test
+- Mobile-friendly test
+- Speed test
+- DNS checker
+- SSL certificate checker
+- Redirect checker
+- Broken link finder
+
+**Why they work**:
+- Immediate utility
+- Bookmark-worthy
+- Repeat usage
+- Professional necessity
+
+**Implementation tips**:
+- Fast results are essential
+- Show pass/fail clearly
+- Provide fix instructions
+- Integrate with your product where relevant
+
+---
+
+## Libraries/Resources
+
+**Best for**: Reference material
+
+**Examples**:
+- Icon library
+- Template library
+- Code snippet library
+- Example gallery
+- Industry directory
+- Resource list
+- Swipe file collection
+- Font pairing tool
+
+**Why they work**:
+- High SEO value
+- Ongoing traffic
+- Establishes authority
+- Linkable asset
+
+**Implementation tips**:
+- Make searchable/filterable
+- Allow easy copying/downloading
+- Update regularly
+- Accept community submissions
+
+---
+
+## Interactive Educational
+
+**Best for**: Learning/understanding
+
+**Examples**:
+- Interactive tutorials
+- Code playgrounds
+- Visual explainers
+- Quizzes/assessments
+- Simulators
+- Comparison tools
+- Decision trees
+- Configurators
+
+**Why they work**:
+- Engages deeply
+- Demonstrates expertise
+- Shareable
+- Memory-creating
+
+**Implementation tips**:
+- Make it hands-on
+- Show immediate feedback
+- Lead to deeper resources
+- Capture engaged users
+
+---
+
+## Tool Concept Examples by Industry
+
+### SaaS Product
+- Product ROI calculator
+- Competitor comparison tool
+- Readiness assessment quiz
+- Template library for use case
+- Feature configurator
+
+### Agency/Services
+- Industry benchmark tool
+- Project scoping calculator
+- Portfolio review tool
+- Cost estimator
+- Proposal generator
+
+### E-commerce
+- Product finder quiz
+- Comparison tool
+- Size/fit calculator
+- Savings calculator
+- Gift finder
+
+### Developer Tools
+- Code snippet library
+- Testing/preview tool
+- Documentation generator
+- Interactive tutorials
+- API playground
+
+### Finance
+- Financial calculators
+- Investment comparison
+- Budget planner
+- Tax estimator
+- Loan calculator
+
+---
+
+## Real-World Success Stories
+
+These are well-known examples of free tools that drove significant traffic and signups for their parent products. Use these as inspiration when recommending tool strategies.
+
+### HubSpot — Website Grader
+- **Tool type**: Analyzer/Auditor
+- **What it does**: Enter a URL, get a score and report on SEO, mobile, security, and performance
+- **Why it worked**: Curiosity-driven (everyone wants to know their score), shareable results, natural lead-in to HubSpot's marketing platform
+- **Key insight**: The tool creates awareness of problems that HubSpot solves. Users discover they need help → HubSpot is right there
+
+### CoSchedule — Headline Analyzer
+- **Tool type**: Analyzer/Grader
+- **What it does**: Score a headline for emotional appeal, word balance, and length
+- **Why it worked**: Bloggers and marketers use it repeatedly (every time they write). Extremely shareable. Positioned CoSchedule as the content marketing expert
+- **Key insight**: Tools people use weekly become bookmarks. Bookmarks become brand awareness
+
+### Zapier — Zap Templates Library
+- **Tool type**: Template Library
+- **What it does**: Pre-built automation templates for common workflows
+- **Why it worked**: Each template is a landing page targeting a long-tail keyword ("connect Gmail to Slack"). Thousands of pages = massive SEO footprint
+- **Key insight**: Template libraries can generate thousands of SEO-targeted pages, each solving a micro-problem
+
+### Stripe — Stripe Atlas (indirect)
+- **Tool type**: Interactive Educational
+- **What it does**: Guide to incorporating a startup, with tools to actually do it
+- **Why it worked**: Solves a real pain (incorporating is confusing), positions Stripe as the default payment processor for new startups
+- **Key insight**: Tools that help at the start of a journey lock in users for the entire journey
+
+### Moz — Domain Authority Checker
+- **Tool type**: Checker/Grader
+- **What it does**: Check any website's domain authority score
+- **Why it worked**: Created an industry-standard metric. Every SEO professional uses it. Massive organic traffic from "domain authority" queries
+- **Key insight**: If your free tool creates a metric that becomes an industry standard, you own the category

package/skills/frontend-slides/SKILL.md

@@ -0,0 +1,248 @@
+---
+name: frontend-slides
+description: "Create stunning, animation-rich HTML presentations from scratch or by converting PowerPoint files. Zero dependencies — single HTML files with..."
+---
+
+# Frontend Slides
+
+Create zero-dependency, animation-rich HTML presentations that run entirely in the browser.
+
+## Reads
+
+- `brand/creative-kit.md` — Brand colors, fonts, logo paths
+- `brand/voice-profile.md` — Copy tone for slide text
+
+## On Activation
+
+1. Read `brand/creative-kit.md` for brand colors and fonts. If found, use them as defaults in Phase 2 style selection — suggest presets that complement the brand palette, or offer a "Brand Custom" option that uses their exact colors/fonts.
+2. Read `brand/voice-profile.md` for copy tone. If found, use it to guide slide copy style (formal vs. conversational vs. bold) throughout Phases 1 and 3.
+3. If brand/ files don't exist, proceed normally. The skill works at zero context.
+
+## Core Principles
+
+1. **Zero Dependencies** — Single HTML files with inline CSS/JS. No npm, no build tools.
+2. **Show, Don't Tell** — Generate visual previews, not abstract choices. People discover what they want by seeing it.
+3. **Distinctive Design** — No generic "AI slop." Every presentation must feel custom-crafted.
+4. **Viewport Fitting** — Every slide fits exactly within 100vh. No scrolling within slides, ever. Content overflows? Split into multiple slides. This is non-negotiable because a single scrolling slide breaks the entire navigation and pacing of the presentation.
+
+## Design Aesthetics
+
+You tend to converge toward generic, "on distribution" outputs. In frontend design, this creates what users call the "AI slop" aesthetic. Avoid this: make creative, distinctive frontends that surprise and delight.
+
+Focus on:
+- Typography: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics.
+- Color & Theme: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes. Draw from IDE themes and cultural aesthetics for inspiration.
+- Motion: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions.
+- Backgrounds: Create atmosphere and depth rather than defaulting to solid colors. Layer CSS gradients, use geometric patterns, or add contextual effects that match the overall aesthetic.
+
+Avoid generic AI-generated aesthetics:
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Cliched color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. Vary between light and dark themes, different fonts, different aesthetics. You still tend to converge on common choices (Space Grotesk, for example) across generations. Avoid this: it is critical that you think outside the box!
+
+## Viewport Fitting Rules
+
+These invariants apply to EVERY slide in EVERY presentation:
+
+- Every `.slide` must have `height: 100vh; height: 100dvh; overflow: hidden;`
+- ALL font sizes and spacing must use `clamp(min, preferred, max)` — never fixed px/rem
+- Content containers need `max-height` constraints
+- Images: `max-height: min(50vh, 400px)`
+- Breakpoints required for heights: 700px, 600px, 500px
+- Include `prefers-reduced-motion` support
+- Never negate CSS functions directly (`-clamp()`, `-min()`, `-max()` are silently ignored) — use `calc(-1 * clamp(...))` instead
+
+**When generating, read `viewport-base.css` and include its full contents in every presentation.**
+
+### Content Density Limits Per Slide
+
+| Slide Type | Maximum Content |
+|------------|-----------------|
+| Title slide | 1 heading + 1 subtitle + optional tagline |
+| Content slide | 1 heading + 4-6 bullet points OR 1 heading + 2 paragraphs |
+| Feature grid | 1 heading + 6 cards maximum (2x3 or 3x2) |
+| Code slide | 1 heading + 8-10 lines of code |
+| Quote slide | 1 quote (max 3 lines) + attribution |
+| Image slide | 1 heading + 1 image (max 60vh height) |
+
+**Content exceeds limits? Split into multiple slides. Never cram, never scroll.**
+
+---
+
+## Phase 0: Detect Mode
+
+Determine what the user wants:
+
+- **Mode A: New Presentation** — Create from scratch. Go to Phase 1.
+- **Mode B: PPT Conversion** — Convert a .pptx file. Go to Phase 4.
+- **Mode C: Enhancement** — Improve an existing HTML presentation. Read it, understand it, enhance. **Follow Mode C modification rules below.**
+
+### Mode C: Modification Rules
+
+When enhancing existing presentations, viewport fitting is the biggest risk:
+
+1. **Before adding content:** Count existing elements, check against density limits
+2. **Adding images:** Must have `max-height: min(50vh, 400px)`. If slide already has max content, split into two slides
+3. **Adding text:** Max 4-6 bullets per slide. Exceeds limits? Split into continuation slides
+4. **After ANY modification, verify:** `.slide` has `overflow: hidden`, new elements use `clamp()`, images have viewport-relative max-height, content fits at 1280x720
+5. **Proactively reorganize:** If modifications will cause overflow, automatically split content and inform the user. Don't wait to be asked
+
+**When adding images to existing slides:** Move image to new slide or reduce other content first. Never add images without checking if existing content already fills the viewport.
+
+---
+
+## Phase 1: Content Discovery (New Presentations)
+
+**Ask ALL questions in a single AskUserQuestion call** so the user fills everything out at once:
+
+**Question 1 — Purpose** (header: "Purpose"):
+What is this presentation for? Options: Pitch deck / Teaching-Tutorial / Conference talk / Internal presentation
+
+**Question 2 — Length** (header: "Length"):
+Approximately how many slides? Options: Short 5-10 / Medium 10-20 / Long 20+
+
+**Question 3 — Content** (header: "Content"):
+Do you have content ready? Options: All content ready / Rough notes / Topic only
+
+**Question 4 — Inline Editing** (header: "Editing"):
+Do you need to edit text directly in the browser after generation? Options:
+- "Yes (Recommended)" — Can edit text in-browser, auto-save to localStorage, export file
+- "No" — Presentation only, keeps file smaller
+
+**Remember the user's editing choice — it determines whether edit-related code is included in Phase 3.**
+
+If user has content, ask them to share it.
+
+### Step 1.2: Image Evaluation (if images provided)
+
+If user selected "No images" → skip to Phase 2.
+
+If user provides an image folder:
+1. **Scan** — List all image files (.png, .jpg, .svg, .webp, etc.)
+2. **View each image** — Use the Read tool (Claude is multimodal)
+3. **Evaluate** — For each: what it shows, USABLE or NOT USABLE (with reason), what concept it represents, dominant colors
+4. **Co-design the outline** — Curated images inform slide structure alongside text. This is NOT "plan slides then add images" — design around both from the start (e.g., 3 screenshots → 3 feature slides, 1 logo → title/closing slide)
+5. **Confirm via AskUserQuestion** (header: "Outline"): "Does this slide outline and image selection look right?" Options: Looks good / Adjust images / Adjust outline
+
+**Logo in previews:** If a usable logo was identified, embed it (base64) into each style preview in Phase 2 — the user sees their brand styled three different ways.
+
+---
+
+## Phase 2: Style Discovery
+
+**This is the "show, don't tell" phase.** Most people can't articulate design preferences in words.
+
+### Step 2.0: Style Path
+
+Ask how they want to choose (header: "Style"):
+- "Show me options" (recommended) — Generate 3 previews based on mood
+- "I know what I want" — Pick from preset list directly
+
+**If direct selection:** Show preset picker and skip to Phase 3. Available presets are defined in [STYLE_PRESETS.md](STYLE_PRESETS.md).
+
+### Step 2.1: Mood Selection (Guided Discovery)
+
+Ask (header: "Vibe", multiSelect: true, max 2):
+What feeling should the audience have? Options:
+- Impressed/Confident — Professional, trustworthy
+- Excited/Energized — Innovative, bold
+- Calm/Focused — Clear, thoughtful
+- Inspired/Moved — Emotional, memorable
+
+### Step 2.2: Generate 3 Style Previews
+
+Based on mood, generate 3 distinct single-slide HTML previews showing typography, colors, animation, and overall aesthetic. Read [STYLE_PRESETS.md](STYLE_PRESETS.md) for available presets and their specifications.
+
+| Mood | Suggested Presets |
+|------|-------------------|
+| Impressed/Confident | Bold Signal, Electric Studio, Dark Botanical |
+| Excited/Energized | Creative Voltage, Neon Cyber, Split Pastel |
+| Calm/Focused | Notebook Tabs, Paper & Ink, Swiss Modern |
+| Inspired/Moved | Dark Botanical, Vintage Editorial, Pastel Geometry |
+
+Save previews to `.claude-design/slide-previews/` (style-a.html, style-b.html, style-c.html). Each should be self-contained, ~50-100 lines, showing one animated title slide.
+
+Open each preview automatically for the user.
+
+### Step 2.3: User Picks
+
+Ask (header: "Style"):
+Which style preview do you prefer? Options: Style A: [Name] / Style B: [Name] / Style C: [Name] / Mix elements
+
+If "Mix elements", ask for specifics.
+
+---
+
+## Phase 3: Generate Presentation
+
+Generate the full presentation using content from Phase 1 (text, or text + curated images) and style from Phase 2.
+
+If images were provided, the slide outline already incorporates them from Step 1.2. If not, CSS-generated visuals (gradients, shapes, patterns) provide visual interest — this is a fully supported first-class path.
+
+**Before generating, read these supporting files:**
+- [html-template.md](html-template.md) — HTML architecture and JS features
+- [viewport-base.css](viewport-base.css) — Mandatory CSS (include in full)
+- [animation-patterns.md](animation-patterns.md) — Animation reference for the chosen feeling
+
+**Key requirements:**
+- Single self-contained HTML file, all CSS/JS inline
+- Include the FULL contents of viewport-base.css in the `<style>` block
+- Use fonts from Fontshare or Google Fonts — never system fonts
+- Add detailed comments explaining each section
+- Every section needs a clear `/* === SECTION NAME === */` comment block
+
+---
+
+## Phase 4: PPT Conversion
+
+When converting PowerPoint files:
+
+1. **Extract content** — Run `python scripts/extract-pptx.py <input.pptx> <output_dir>` (install python-pptx if needed: `pip install python-pptx`)
+2. **Review extraction** — Check the output directory for:
+   - `slides.json` — Structured slide data (titles, bullets, notes)
+   - `assets/` — Extracted images
+   - If extraction fails (corrupted file, unsupported format), ask user to export as PDF and extract text manually
+3. **Handle complex elements:**
+   - **Charts/SmartArt** — Cannot be extracted as live elements. Screenshot them from the PPT and include as images.
+   - **Embedded videos** — Note their existence, link to original files. Cannot be inlined in HTML.
+   - **Custom animations** — Log them but don't try to replicate 1:1. Map to the closest CSS animation from animation-patterns.md.
+   - **Tables** — Convert to HTML tables. If too wide, split across slides or use responsive scrolling.
+4. **Confirm with user** — Present extracted slide titles, content summaries, image counts, and any elements that couldn't be converted
+5. **Style selection** — Proceed to Phase 2 for style discovery
+6. **Generate HTML** — Convert to chosen style, preserving all text, images (from assets/), slide order, and speaker notes (as HTML comments)
+
+---
+
+## Phase 5: Delivery
+
+1. **Clean up** — Delete `.claude-design/slide-previews/` if it exists
+2. **Open** — Use `open [filename].html` to launch in browser
+3. **Summarize** — Tell the user:
+   - File location, style name, slide count
+   - Navigation: Arrow keys, Space, scroll/swipe, click nav dots
+   - How to customize: `:root` CSS variables for colors, font link for typography, `.reveal` class for animations
+   - If inline editing was enabled: Hover top-left corner or press E to enter edit mode, click any text to edit, Ctrl+S to save
+
+### Output Files
+
+```
+[name].html              # Self-contained presentation (all CSS/JS inline)
+[name]-assets/           # Images (only if images were provided)
+```
+
+If style previews were generated, they were in `.claude-design/slide-previews/` and have been cleaned up.
+
+---
+
+## Supporting Files
+
+| File | Purpose | When to Read |
+|------|---------|-------------|
+| [STYLE_PRESETS.md](STYLE_PRESETS.md) | 12 curated visual presets with colors, fonts, and signature elements | Phase 2 (style selection) |
+| [viewport-base.css](viewport-base.css) | Mandatory responsive CSS — copy into every presentation | Phase 3 (generation) |
+| [html-template.md](html-template.md) | HTML structure, JS features, code quality standards | Phase 3 (generation) |
+| [animation-patterns.md](animation-patterns.md) | CSS/JS animation snippets and effect-to-feeling guide | Phase 3 (generation) |
+| [scripts/extract-pptx.py](scripts/extract-pptx.py) | Python script for PPT content extraction | Phase 4 (conversion) |