@jairodri/huckleberry-cli 1.0.1 → 1.1.0

package/skills/sales-enablement/references/one-pager-templates.md

@@ -0,0 +1,208 @@
+# One-Pager Templates
+
+Templates for different one-pager use cases, with layout guidance and copy prompts.
+
+## Product Overview One-Pager
+
+The default one-pager. Introduces your product to someone who knows nothing about you.
+
+### Structure
+
+```
+[Logo]                                              [Tagline]
+
+HEADLINE: One sentence describing what you do and who it's for.
+
+THE PROBLEM
+2-3 sentences describing the pain your buyer faces.
+
+THE SOLUTION
+2-3 sentences describing how your product solves it.
+
+WHY [YOUR PRODUCT]
+• Differentiator 1 — One sentence explaining the benefit
+• Differentiator 2 — One sentence explaining the benefit
+• Differentiator 3 — One sentence explaining the benefit
+
+PROOF
+"Customer quote with specific result." — Name, Title, Company
+[Optional: 2-3 metric callouts: "X% improvement", "Y hours saved"]
+
+[CTA Button/Link]                    [Contact: name@company.com]
+```
+
+### Copy Prompts
+
+- Headline: "What do you do, in one sentence, that makes someone say 'tell me more'?"
+- Problem: "What is your buyer struggling with before they find you?"
+- Differentiators: "If you could only tell them 3 things, what would make them choose you?"
+
+---
+
+## Use-Case Specific One-Pager
+
+Tailored to a specific workflow, vertical, or problem. More targeted than the product overview.
+
+### Structure
+
+```
+[Logo]                                    [Use Case: e.g., "For Sales Teams"]
+
+HEADLINE: How [your product] helps [persona] [achieve outcome].
+
+THE CHALLENGE
+When [persona] needs to [task], they face [specific pain].
+This leads to [consequence]: [time wasted / money lost / risk].
+
+HOW IT WORKS
+1. [Step 1] — What happens and why it matters
+2. [Step 2] — What happens and why it matters
+3. [Step 3] — What happens and why it matters
+
+RESULTS
+• [Metric 1]: Before → After
+• [Metric 2]: Before → After
+• [Metric 3]: Before → After
+
+CUSTOMER SPOTLIGHT
+"Quote about this specific use case." — Name, Title, Company
+
+[CTA: "See it in action" or "Start a pilot"]       [Contact info]
+```
+
+### When to Use
+
+- Different buyer personas need different one-pagers
+- Industry-specific versions (healthcare, fintech, e-commerce)
+- Use-case versions (reporting, onboarding, security)
+
+---
+
+## Post-Meeting Leave-Behind
+
+Designed to reinforce a conversation that already happened. Summarizes what you discussed and proposes next steps.
+
+### Structure
+
+```
+[Logo]                                            [Date of Meeting]
+
+MEETING RECAP: [Company Name]
+
+WHAT WE DISCUSSED
+• [Pain point 1 they mentioned]
+• [Pain point 2 they mentioned]
+• [Goal they're trying to achieve]
+
+HOW [YOUR PRODUCT] HELPS
+• [Solution to pain 1] — [Specific capability or workflow]
+• [Solution to pain 2] — [Specific capability or workflow]
+• [How you help them reach their goal]
+
+RELEVANT PROOF
+"Quote from a similar customer." — Name, Title, Company
+[1-2 metrics from a similar customer]
+
+PROPOSED NEXT STEPS
+1. [Next step with date]
+2. [Follow-up action]
+3. [Decision timeline]
+
+[Your name]  |  [Your title]  |  [Email]  |  [Phone]
+```
+
+### Tips
+
+- Send within 24 hours of the meeting
+- Reference specific things they said (shows you listened)
+- Keep proposed next steps concrete and time-bound
+- This is the asset your champion forwards to their boss
+
+---
+
+## Champion Enablement One-Pager
+
+Designed specifically for your internal champion to share with their team and leadership. Written to make them look smart.
+
+### Structure
+
+```
+[Logo]
+
+WHY WE'RE EVALUATING [YOUR PRODUCT]
+
+THE SITUATION
+[2-3 sentences about the internal challenge, written as if the champion
+is explaining it to their team. Use "we" and "our" language.]
+
+WHAT [YOUR PRODUCT] DOES
+[1-2 sentences. Plain language, no jargon.]
+
+WHY THIS SOLUTION
+• [Reason 1] — How it solves our specific problem
+• [Reason 2] — How it compares to what we do today
+• [Reason 3] — How it compares to alternatives we evaluated
+
+EXPECTED IMPACT
+• [Metric]: Current state → Expected state
+• [Metric]: Current state → Expected state
+• [Time to value]: Live within [X weeks]
+
+WHO ELSE USES IT
+[2-3 recognizable company names in their industry]
+"Relevant customer quote." — Name, Title, Company
+
+NEXT STEPS
+• [What we're doing next]
+• [What we need from the team]
+• [Decision timeline]
+
+Questions? Talk to [Champion name] or [Your name at email].
+```
+
+### Why This Works
+
+- Written in the champion's voice, not yours
+- Answers the questions their boss will ask
+- Includes peer proof from companies they respect
+- Clear ask and timeline to drive internal momentum
+
+---
+
+## Layout Guidance
+
+### Visual Hierarchy
+
+1. **Headline** — Largest text, top of page, immediately communicates value
+2. **Section headers** — Bold, clear, act as scannable anchors
+3. **Body text** — Short sentences, bullet points preferred over paragraphs
+4. **Proof elements** — Metrics and quotes should visually stand out (larger font, color, or callout box)
+5. **CTA** — Prominent placement, bottom of page or bottom-right
+
+### Whitespace
+
+- Margins: at least 0.75" on all sides
+- Space between sections: enough to visually separate (don't cram)
+- If it feels crowded, cut content. Never shrink font below 9pt.
+
+### Font Sizing
+
+| Element | Suggested Size |
+|---------|---------------|
+| Headline | 18-24pt |
+| Section headers | 12-14pt bold |
+| Body text | 10-11pt |
+| Fine print / footer | 8-9pt |
+
+### Color
+
+- Use brand colors for headers and accents
+- Keep body text dark (black or near-black) on white
+- Limit accent colors to 1-2 for visual consistency
+- Use color to draw attention to metrics and CTAs
+
+### File Format
+
+- **PDF** for email attachments and leave-behinds
+- **Google Slides / PowerPoint** for editable versions reps can customize
+- Always include both — reps will customize, prospects want clean PDFs

package/skills/schema-markup/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: schema-markup
+description: Add and optimize schema markup and structured data for rich results.
+metadata:
+  version: 1.1.0
+---
+
+# Schema Markup
+
+You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.
+
+## Initial Assessment
+
+**Check for brand-specific assets in businesses/{business}/brand/ first:**
+If `businesses/{business}/brand/` exists (or `businesses/{business}/brand/` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
+
+Before implementing schema, understand:
+
+1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?
+
+2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?
+
+3. **Goals** - Which rich results are you targeting? What's the business value?
+
+---
+
+## Core Principles
+
+### 1. Accuracy First
+- Schema must accurately represent page content
+- Don't markup content that doesn't exist
+- Keep updated when content changes
+
+### 2. Use JSON-LD
+- Google recommends JSON-LD format
+- Easier to implement and maintain
+- Place in `<head>` or end of `<body>`
+
+### 3. Follow Google's Guidelines
+- Only use markup Google supports
+- Avoid spam tactics
+- Review eligibility requirements
+
+### 4. Validate Everything
+- Test before deploying
+- Monitor Search Console
+- Fix errors promptly
+
+---
+
+## Common Schema Types
+
+| Type | Use For | Required Properties |
+|------|---------|-------------------|
+| Organization | Company homepage/about | name, url |
+| WebSite | Homepage (search box) | name, url |
+| Article | Blog posts, news | headline, image, datePublished, author |
+| Product | Product pages | name, image, offers |
+| SoftwareApplication | SaaS/app pages | name, offers |
+| FAQPage | FAQ content | mainEntity (Q&A array) |
+| HowTo | Tutorials | name, step |
+| BreadcrumbList | Any page with breadcrumbs | itemListElement |
+| LocalBusiness | Local business pages | name, address |
+| Event | Events, webinars | name, startDate, location |
+
+**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)
+
+---
+
+## Quick Reference
+
+### Organization (Company Page)
+Required: name, url
+Recommended: logo, sameAs (social profiles), contactPoint
+
+### Article/BlogPosting
+Required: headline, image, datePublished, author
+Recommended: dateModified, publisher, description
+
+### Product
+Required: name, image, offers (price + availability)
+Recommended: sku, brand, aggregateRating, review
+
+### FAQPage
+Required: mainEntity (array of Question/Answer pairs)
+
+### BreadcrumbList
+Required: itemListElement (array with position, name, item)
+
+---
+
+## Multiple Schema Types
+
+You can combine multiple schema types on one page using `@graph`:
+
+```json
+{
+  "@context": "https://schema.org",
+  "@graph": [
+    { "@type": "Organization", ... },
+    { "@type": "WebSite", ... },
+    { "@type": "BreadcrumbList", ... }
+  ]
+}
+```
+
+---
+
+## Validation and Testing
+
+### Tools
+- **Google Rich Results Test**: https://search.google.com/test/rich-results
+- **Schema.org Validator**: https://validator.schema.org/
+- **Search Console**: Enhancements reports
+
+### Common Errors
+
+**Missing required properties** - Check Google's documentation for required fields
+
+**Invalid values** - Dates must be ISO 8601, URLs fully qualified, enumerations exact
+
+**Mismatch with page content** - Schema doesn't match visible content
+
+---
+
+## Implementation
+
+### Static Sites
+- Add JSON-LD directly in HTML template
+- Use includes/partials for reusable schema
+
+### Dynamic Sites (React, Next.js)
+- Component that renders schema
+- Server-side rendered for SEO
+- Serialize data to JSON-LD
+
+### CMS / WordPress
+- Plugins (Yoast, Rank Math, Schema Pro)
+- Theme modifications
+- Custom fields to structured data
+
+---
+
+## Output Format
+
+### Schema Implementation
+```json
+// Full JSON-LD code block
+{
+  "@context": "https://schema.org",
+  "@type": "...",
+  // Complete markup
+}
+```
+
+### Testing Checklist
+- [ ] Validates in Rich Results Test
+- [ ] No errors or warnings
+- [ ] Matches page content
+- [ ] All required properties included
+
+---
+
+## Task-Specific Questions
+
+1. What type of page is this?
+2. What rich results are you hoping to achieve?
+3. What data is available to populate the schema?
+4. Is there existing schema on the page?
+5. What's your tech stack?
+
+---
+
+## Related Skills
+
+- **seo-audit**: For overall SEO including schema review
+- **ai-seo**: For AI search optimization (schema helps AI understand content)
+- **programmatic-seo**: For templated schema at scale
+- **site-architecture**: For breadcrumb structure and navigation schema planning

package/skills/schema-markup/evals/evals.json

@@ -0,0 +1,87 @@
+{
+  "skill_name": "schema-markup",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Add schema markup to our SaaS product's homepage. We're a project management tool called TaskFlow. We need Organization schema and any other relevant types.",
+      "expected_output": "Should check for product-marketing-context.md first. Should implement Organization schema in JSON-LD format with all required and recommended properties (name, url, logo, description, sameAs for social profiles). Should recommend additional schema types for a SaaS homepage: WebSite (with SearchAction if applicable), SoftwareApplication or Product. Should use @graph for multiple schema types on one page. Should provide the complete JSON-LD code ready to implement. Should recommend validation with Google's Rich Results Test and Schema.org validator.",
+      "assertions": [
+        "Checks for product-marketing-context.md",
+        "Implements Organization schema in JSON-LD",
+        "Includes required and recommended properties",
+        "Recommends additional relevant schema types",
+        "Uses @graph for multiple types",
+        "Provides complete JSON-LD code",
+        "Recommends validation tools"
+      ],
+      "files": []
+    },
+    {
+      "id": 2,
+      "prompt": "We have a FAQ page with 20 questions about our product. How do I add FAQ schema to get the rich results in Google?",
+      "expected_output": "Should implement FAQPage schema in JSON-LD format. Should show the correct structure: FAQPage as mainEntity containing Question items, each with acceptedAnswer. Should provide a complete code example with 2-3 sample questions. Should explain that FAQ schema can enable rich results showing questions/answers directly in search. Should note Google's guidelines for FAQ schema (factual answers, not promotional). Should recommend validation approach.",
+      "assertions": [
+        "Implements FAQPage schema in JSON-LD",
+        "Shows correct nested structure (FAQPage > Question > Answer)",
+        "Provides complete code example",
+        "Explains rich result benefits",
+        "Notes Google's FAQ schema guidelines",
+        "Recommends validation"
+      ],
+      "files": []
+    },
+    {
+      "id": 3,
+      "prompt": "add schema to our blog posts. we publish articles about marketing tips.",
+      "expected_output": "Should trigger on casual phrasing. Should implement Article (or BlogPosting) schema in JSON-LD. Should include required properties: headline, author (as Person with name and url), datePublished, dateModified, image, publisher (as Organization). Should recommend BreadcrumbList schema alongside the article schema. Should provide template code that can be reused across blog posts. Should address how to populate dynamic fields (date, author, headline) from the CMS.",
+      "assertions": [
+        "Triggers on casual phrasing",
+        "Implements Article or BlogPosting schema",
+        "Includes author, datePublished, image, publisher",
+        "Recommends BreadcrumbList alongside",
+        "Provides reusable template code",
+        "Addresses CMS integration for dynamic fields"
+      ],
+      "files": []
+    },
+    {
+      "id": 4,
+      "prompt": "We're an e-commerce site selling physical products. What schema markup do we need for our product pages?",
+      "expected_output": "Should implement Product schema with full properties: name, description, image, brand, sku, offers (with price, priceCurrency, availability, url). Should recommend AggregateRating if they have reviews, and Review schema for individual reviews. Should include BreadcrumbList for navigation. Should address common e-commerce schema types: Product, Offer, AggregateRating, Review. Should provide complete JSON-LD code. Should note that Product schema can enable rich results (price, availability, ratings in search).",
+      "assertions": [
+        "Implements Product schema with full properties",
+        "Includes Offer with price, availability",
+        "Recommends AggregateRating and Review schema",
+        "Includes BreadcrumbList",
+        "Provides complete JSON-LD code",
+        "Notes rich result benefits for products"
+      ],
+      "files": []
+    },
+    {
+      "id": 5,
+      "prompt": "We added schema markup to our site but it's not showing rich results in Google. Can you help debug?",
+      "expected_output": "Should provide a systematic debugging approach: first validate with Google Rich Results Test and Schema.org validator (syntax errors), then check for common issues (incorrect nesting, missing required properties, JSON-LD placement errors). Should explain that valid schema doesn't guarantee rich results — Google chooses when to show them. Should recommend checking Search Console for structured data reports and errors. Should address common debugging scenarios: schema not detected, warnings vs errors, eligible vs displayed.",
+      "assertions": [
+        "Recommends validation tools for debugging",
+        "Checks for common schema errors",
+        "Explains valid schema doesn't guarantee rich results",
+        "Recommends Search Console structured data reports",
+        "Addresses warnings vs errors distinction",
+        "Provides systematic debugging approach"
+      ],
+      "files": []
+    },
+    {
+      "id": 6,
+      "prompt": "Our organic search traffic dropped after a site redesign. Can you do a technical SEO audit?",
+      "expected_output": "Should recognize this is a technical SEO audit request, not a schema markup task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive technical SEO audits. Schema markup is one component of SEO but doesn't address the broader technical issues (redirects, crawlability, indexation) that likely caused the traffic drop.",
+      "assertions": [
+        "Recognizes this as a technical SEO audit request",
+        "References or defers to seo-audit skill",
+        "Does not attempt full SEO audit using schema markup patterns"
+      ],
+      "files": []
+    }
+  ]
+}