feat: fork marketingskills → HVAC Marketing Skills for Compendium
- Forked from coreyhaines31/marketingskills v1.1.0 (MIT license) - Removed 4 SaaS-only skills (churn-prevention, paywall-upgrade-cro, onboarding-cro, signup-flow-cro) - Reworked 2 skills (popup-cro → hvac-estimate-popups, revops → hvac-lead-ops) - Adapted all 28 retained skills with HVAC industry context and Compendium integration - Created 10 new HVAC-specific skills: - hvac-content-from-data (flagship DB integration) - hvac-seasonal-campaign (demand cycle marketing) - hvac-review-management (GBP review strategy) - hvac-video-repurpose (long-form → social) - hvac-technical-content (audience-calibrated writing) - hvac-brand-voice (trade authenticity guide) - hvac-contractor-website-audit (discovery & analysis) - hvac-contractor-website-package (marketing package assembly) - hvac-compliance-claims (EPA/rebate/safety claim checking) - hvac-content-qc (fact-check & citation gate) - Renamed product-marketing-context → hvac-marketing-context (global) - Created COMPENDIUM_INTEGRATION.md (shared integration contract) - Added Compendium wrapper tools (search, scrape, classify) - Added compendium capability tags to YAML frontmatter - Updated README, AGENTS.md, CLAUDE.md, VERSIONS.md, marketplace.json - All 38 skills pass validate-skills.sh - Zero dangling references to removed/renamed skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
bengizmo
parent
2f5db8d95c
commit
1e70d8387b
106 changed files with 9166 additions and 7127 deletions
|
|
@ -1,18 +1,19 @@
|
||||||
{
|
{
|
||||||
"name": "marketingskills",
|
"name": "hvac-marketing-skills",
|
||||||
"owner": {
|
"owner": {
|
||||||
"name": "Corey Haines",
|
"name": "Ben (Compendium)",
|
||||||
"url": "https://corey.co"
|
"url": "https://git.tealmaker.com/ben/hvac-marketing-skills"
|
||||||
},
|
},
|
||||||
"metadata": {
|
"metadata": {
|
||||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
|
"description": "38 HVAC marketing skills for AI agents — adapted from coreyhaines31/marketingskills with Compendium platform integration",
|
||||||
"version": "1.0.0",
|
"version": "1.0.0-hvac",
|
||||||
"repository": "https://github.com/coreyhaines31/marketingskills"
|
"repository": "https://git.tealmaker.com/ben/hvac-marketing-skills",
|
||||||
|
"upstream": "https://github.com/coreyhaines31/marketingskills"
|
||||||
},
|
},
|
||||||
"plugins": [
|
"plugins": [
|
||||||
{
|
{
|
||||||
"name": "marketing-skills",
|
"name": "hvac-marketing-skills",
|
||||||
"description": "32 marketing skills for technical marketers and founders: CRO, copywriting, cold email, SEO, AI SEO, paid ads, ad creative, churn prevention, pricing strategy, referral programs, revenue operations, sales enablement, site architecture, and more",
|
"description": "38 HVAC marketing skills: content strategy, local SEO, contractor marketing, seasonal campaigns, brand voice, CRO, copywriting, paid ads, review management, compliance claims, and more — with Compendium database integration",
|
||||||
"source": "./",
|
"source": "./",
|
||||||
"strict": false,
|
"strict": false,
|
||||||
"skills": [
|
"skills": [
|
||||||
|
|
@ -20,7 +21,6 @@
|
||||||
"./skills/ad-creative",
|
"./skills/ad-creative",
|
||||||
"./skills/ai-seo",
|
"./skills/ai-seo",
|
||||||
"./skills/analytics-tracking",
|
"./skills/analytics-tracking",
|
||||||
"./skills/churn-prevention",
|
|
||||||
"./skills/cold-email",
|
"./skills/cold-email",
|
||||||
"./skills/competitor-alternatives",
|
"./skills/competitor-alternatives",
|
||||||
"./skills/content-strategy",
|
"./skills/content-strategy",
|
||||||
|
|
@ -29,23 +29,30 @@
|
||||||
"./skills/email-sequence",
|
"./skills/email-sequence",
|
||||||
"./skills/form-cro",
|
"./skills/form-cro",
|
||||||
"./skills/free-tool-strategy",
|
"./skills/free-tool-strategy",
|
||||||
|
"./skills/hvac-brand-voice",
|
||||||
|
"./skills/hvac-compliance-claims",
|
||||||
|
"./skills/hvac-content-from-data",
|
||||||
|
"./skills/hvac-content-qc",
|
||||||
|
"./skills/hvac-contractor-website-audit",
|
||||||
|
"./skills/hvac-contractor-website-package",
|
||||||
|
"./skills/hvac-estimate-popups",
|
||||||
|
"./skills/hvac-lead-ops",
|
||||||
|
"./skills/hvac-marketing-context",
|
||||||
|
"./skills/hvac-review-management",
|
||||||
|
"./skills/hvac-seasonal-campaign",
|
||||||
|
"./skills/hvac-technical-content",
|
||||||
|
"./skills/hvac-video-repurpose",
|
||||||
"./skills/launch-strategy",
|
"./skills/launch-strategy",
|
||||||
"./skills/marketing-ideas",
|
"./skills/marketing-ideas",
|
||||||
"./skills/marketing-psychology",
|
"./skills/marketing-psychology",
|
||||||
"./skills/onboarding-cro",
|
|
||||||
"./skills/page-cro",
|
"./skills/page-cro",
|
||||||
"./skills/paid-ads",
|
"./skills/paid-ads",
|
||||||
"./skills/paywall-upgrade-cro",
|
|
||||||
"./skills/popup-cro",
|
|
||||||
"./skills/pricing-strategy",
|
"./skills/pricing-strategy",
|
||||||
"./skills/product-marketing-context",
|
|
||||||
"./skills/programmatic-seo",
|
"./skills/programmatic-seo",
|
||||||
"./skills/referral-program",
|
"./skills/referral-program",
|
||||||
"./skills/revops",
|
|
||||||
"./skills/sales-enablement",
|
"./skills/sales-enablement",
|
||||||
"./skills/schema-markup",
|
"./skills/schema-markup",
|
||||||
"./skills/seo-audit",
|
"./skills/seo-audit",
|
||||||
"./skills/signup-flow-cro",
|
|
||||||
"./skills/site-architecture",
|
"./skills/site-architecture",
|
||||||
"./skills/social-content"
|
"./skills/social-content"
|
||||||
]
|
]
|
||||||
|
|
|
||||||
224
AGENTS.md
224
AGENTS.md
|
|
@ -1,217 +1,31 @@
|
||||||
# AGENTS.md
|
# HVAC Marketing Skills — Claude Code Instructions
|
||||||
|
|
||||||
Guidelines for AI agents working in this repository.
|
## What This Repo Is
|
||||||
|
|
||||||
## Repository Overview
|
38 HVAC marketing skills for AI agents, forked from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills). Each skill is a SKILL.md file in `skills/{name}/`.
|
||||||
|
|
||||||
This repository contains **Agent Skills** for AI agents following the [Agent Skills specification](https://agentskills.io/specification.md). Skills install to `.agents/skills/` (the cross-agent standard). This repo also serves as a **Claude Code plugin marketplace** via `.claude-plugin/marketplace.json`.
|
## Key Files
|
||||||
|
|
||||||
- **Name**: Marketing Skills
|
- `COMPENDIUM_INTEGRATION.md` — Database queries, API endpoints, fallback behavior
|
||||||
- **GitHub**: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
|
- `AGENTS.md` — Skill format spec and contribution guidelines
|
||||||
- **Creator**: Corey Haines
|
- `VERSIONS.md` — Skill version tracking
|
||||||
- **License**: MIT
|
- `.claude-plugin/marketplace.json` — Plugin manifest
|
||||||
|
|
||||||
## Repository Structure
|
## Working With Skills
|
||||||
|
|
||||||
```
|
- Foundation skill is `hvac-marketing-context` — all others reference it
|
||||||
marketingskills/
|
- Skills declare `compendium.mode` in frontmatter: `standalone`, `enhanced`, or `required`
|
||||||
├── .claude-plugin/
|
- When Compendium services are unavailable, fall back to `WebSearch`/`WebFetch`
|
||||||
│ └── marketplace.json # Claude Code plugin marketplace manifest
|
- SKILL.md files must stay under 500 lines
|
||||||
├── skills/ # Agent Skills
|
|
||||||
│ └── skill-name/
|
|
||||||
│ └── SKILL.md # Required skill file
|
|
||||||
├── tools/
|
|
||||||
│ ├── clis/ # Zero-dependency Node.js CLI tools (51 tools)
|
|
||||||
│ ├── integrations/ # API integration guides per tool
|
|
||||||
│ └── REGISTRY.md # Tool index with capabilities
|
|
||||||
├── CONTRIBUTING.md
|
|
||||||
├── LICENSE
|
|
||||||
└── README.md
|
|
||||||
```
|
|
||||||
|
|
||||||
## Build / Lint / Test Commands
|
## Validation
|
||||||
|
|
||||||
**Skills** are content-only (no build step). Verify manually:
|
|
||||||
- YAML frontmatter is valid
|
|
||||||
- `name` field matches directory name exactly
|
|
||||||
- `name` is 1-64 chars, lowercase alphanumeric and hyphens only
|
|
||||||
- `description` is 1-1024 characters
|
|
||||||
|
|
||||||
**CLI tools** (`tools/clis/*.js`) are zero-dependency Node.js scripts (Node 18+). Verify with:
|
|
||||||
```bash
|
|
||||||
node --check tools/clis/<name>.js # Syntax check
|
|
||||||
node tools/clis/<name>.js # Show usage (no args = help)
|
|
||||||
node tools/clis/<name>.js <cmd> --dry-run # Preview request without sending
|
|
||||||
```
|
|
||||||
|
|
||||||
## Agent Skills Specification
|
|
||||||
|
|
||||||
Skills follow the [Agent Skills spec](https://agentskills.io/specification.md).
|
|
||||||
|
|
||||||
### Required Frontmatter
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
---
|
|
||||||
name: skill-name
|
|
||||||
description: What this skill does and when to use it. Include trigger phrases.
|
|
||||||
---
|
|
||||||
```
|
|
||||||
|
|
||||||
### Frontmatter Field Constraints
|
|
||||||
|
|
||||||
| Field | Required | Constraints |
|
|
||||||
|---------------|----------|------------------------------------------------------------------|
|
|
||||||
| `name` | Yes | 1-64 chars, lowercase `a-z`, numbers, hyphens. Must match dir. |
|
|
||||||
| `description` | Yes | 1-1024 chars. Describe what it does and when to use it. |
|
|
||||||
| `license` | No | License name (default: MIT) |
|
|
||||||
| `metadata` | No | Key-value pairs (author, version, etc.) |
|
|
||||||
|
|
||||||
### Name Field Rules
|
|
||||||
|
|
||||||
- Lowercase letters, numbers, and hyphens only
|
|
||||||
- Cannot start or end with hyphen
|
|
||||||
- No consecutive hyphens (`--`)
|
|
||||||
- Must match parent directory name exactly
|
|
||||||
|
|
||||||
**Valid**: `page-cro`, `email-sequence`, `ab-test-setup`
|
|
||||||
**Invalid**: `Page-CRO`, `-page`, `page--cro`
|
|
||||||
|
|
||||||
### Optional Skill Directories
|
|
||||||
|
|
||||||
```
|
|
||||||
skills/skill-name/
|
|
||||||
├── SKILL.md # Required - main instructions (<500 lines)
|
|
||||||
├── references/ # Optional - detailed docs loaded on demand
|
|
||||||
├── scripts/ # Optional - executable code
|
|
||||||
└── assets/ # Optional - templates, data files
|
|
||||||
```
|
|
||||||
|
|
||||||
## Writing Style Guidelines
|
|
||||||
|
|
||||||
### Structure
|
|
||||||
|
|
||||||
- Keep `SKILL.md` under 500 lines (move details to `references/`)
|
|
||||||
- Use H2 (`##`) for main sections, H3 (`###`) for subsections
|
|
||||||
- Use bullet points and numbered lists liberally
|
|
||||||
- Short paragraphs (2-4 sentences max)
|
|
||||||
|
|
||||||
### Tone
|
|
||||||
|
|
||||||
- Direct and instructional
|
|
||||||
- Second person ("You are a conversion rate optimization expert")
|
|
||||||
- Professional but approachable
|
|
||||||
|
|
||||||
### Formatting
|
|
||||||
|
|
||||||
- Bold (`**text**`) for key terms
|
|
||||||
- Code blocks for examples and templates
|
|
||||||
- Tables for reference data
|
|
||||||
- No excessive emojis
|
|
||||||
|
|
||||||
### Clarity Principles
|
|
||||||
|
|
||||||
- Clarity over cleverness
|
|
||||||
- Specific over vague
|
|
||||||
- Active voice over passive
|
|
||||||
- One idea per section
|
|
||||||
|
|
||||||
### Description Field Best Practices
|
|
||||||
|
|
||||||
The `description` is critical for skill discovery. Include:
|
|
||||||
1. What the skill does
|
|
||||||
2. When to use it (trigger phrases)
|
|
||||||
3. Related skills for scope boundaries
|
|
||||||
|
|
||||||
```yaml
|
|
||||||
description: When the user wants to optimize conversions on any marketing page. Use when the user says "CRO," "conversion rate optimization," "this page isn't converting." For signup flows, see signup-flow-cro.
|
|
||||||
```
|
|
||||||
|
|
||||||
## Claude Code Plugin
|
|
||||||
|
|
||||||
This repo also serves as a plugin marketplace. The manifest at `.claude-plugin/marketplace.json` lists all skills for installation via:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
/plugin marketplace add coreyhaines31/marketingskills
|
./validate-skills.sh # All 38 skills must pass
|
||||||
/plugin install marketing-skills
|
|
||||||
```
|
```
|
||||||
|
|
||||||
See [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins.md) for details.
|
## Git
|
||||||
|
|
||||||
## Git Workflow
|
- `upstream` remote = GitHub (read-only)
|
||||||
|
- `local` remote = Gitea (`http://192.168.10.31:3005/ben/hvac-marketing-skills.git`)
|
||||||
### Branch Naming
|
- Push only to `local`
|
||||||
|
|
||||||
- New skills: `feature/skill-name`
|
|
||||||
- Improvements: `fix/skill-name-description`
|
|
||||||
- Documentation: `docs/description`
|
|
||||||
|
|
||||||
### Commit Messages
|
|
||||||
|
|
||||||
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
|
||||||
|
|
||||||
- `feat: add skill-name skill`
|
|
||||||
- `fix: improve clarity in page-cro`
|
|
||||||
- `docs: update README`
|
|
||||||
|
|
||||||
### Pull Request Checklist
|
|
||||||
|
|
||||||
- [ ] `name` matches directory name exactly
|
|
||||||
- [ ] `name` follows naming rules (lowercase, hyphens, no `--`)
|
|
||||||
- [ ] `description` is 1-1024 chars with trigger phrases
|
|
||||||
- [ ] `SKILL.md` is under 500 lines
|
|
||||||
- [ ] No sensitive data or credentials
|
|
||||||
|
|
||||||
## Tool Integrations
|
|
||||||
|
|
||||||
This repository includes a tools registry for agent-compatible marketing tools.
|
|
||||||
|
|
||||||
- **Tool discovery**: Read `tools/REGISTRY.md` to see available tools and their capabilities
|
|
||||||
- **Integration details**: See `tools/integrations/{tool}.md` for API endpoints, auth, and common operations
|
|
||||||
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam
|
|
||||||
|
|
||||||
### Registry Structure
|
|
||||||
|
|
||||||
```
|
|
||||||
tools/
|
|
||||||
├── REGISTRY.md # Index of all tools with capabilities
|
|
||||||
└── integrations/ # Detailed integration guides
|
|
||||||
├── ga4.md
|
|
||||||
├── stripe.md
|
|
||||||
├── rewardful.md
|
|
||||||
└── ...
|
|
||||||
```
|
|
||||||
|
|
||||||
### When to Use Tools
|
|
||||||
|
|
||||||
Skills reference relevant tools for implementation. For example:
|
|
||||||
- `referral-program` skill → rewardful, tolt, dub-co, mention-me guides
|
|
||||||
- `analytics-tracking` skill → ga4, mixpanel, segment guides
|
|
||||||
- `email-sequence` skill → customer-io, mailchimp, resend guides
|
|
||||||
- `paid-ads` skill → google-ads, meta-ads, linkedin-ads guides
|
|
||||||
|
|
||||||
## Checking for Updates
|
|
||||||
|
|
||||||
When using any skill from this repository:
|
|
||||||
|
|
||||||
1. **Once per session**, on first skill use, check for updates:
|
|
||||||
- Fetch `VERSIONS.md` from GitHub: https://raw.githubusercontent.com/coreyhaines31/marketingskills/main/VERSIONS.md
|
|
||||||
- Compare versions against local skill files
|
|
||||||
|
|
||||||
2. **Only prompt if meaningful**:
|
|
||||||
- 2 or more skills have updates, OR
|
|
||||||
- Any skill has a major version bump (e.g., 1.x to 2.x)
|
|
||||||
|
|
||||||
3. **Non-blocking notification** at end of response:
|
|
||||||
```
|
|
||||||
---
|
|
||||||
Skills update available: X marketing skills have updates.
|
|
||||||
Say "update skills" to update automatically, or run `git pull` in your marketingskills folder.
|
|
||||||
```
|
|
||||||
|
|
||||||
4. **If user says "update skills"**:
|
|
||||||
- Run `git pull` in the marketingskills directory
|
|
||||||
- Confirm what was updated
|
|
||||||
|
|
||||||
## Skill Categories
|
|
||||||
|
|
||||||
See `README.md` for the current list of skills organized by category. When adding new skills, follow the naming patterns of existing skills in that category.
|
|
||||||
|
|
|
||||||
282
COMPENDIUM_INTEGRATION.md
Normal file
282
COMPENDIUM_INTEGRATION.md
Normal file
|
|
@ -0,0 +1,282 @@
|
||||||
|
# Compendium Integration Contract
|
||||||
|
|
||||||
|
> Single source of truth for all Compendium platform access from HVAC marketing skills.
|
||||||
|
> Skills reference this file instead of embedding raw SQL/API snippets.
|
||||||
|
|
||||||
|
## Quick Reference
|
||||||
|
|
||||||
|
| Service | Endpoint | Auth | Rate Limit |
|
||||||
|
|---------|----------|------|------------|
|
||||||
|
| PostgreSQL (via MCP) | `mcp__postgres__execute_sql` | MCP connection | No hard limit |
|
||||||
|
| Search Router | `http://192.168.10.249:30099` | None (internal) | No hard limit |
|
||||||
|
| Scrape Router | `http://192.168.10.249:30098` | None (internal) | ~10K pages/day |
|
||||||
|
| Classification API | `http://192.168.10.249:30080/api/v2/content-classification/` | None (internal) | 100 req/hr |
|
||||||
|
| Live Browse | `mcp__playwright__browser_*` | MCP connection | Session-based |
|
||||||
|
| Zen Analysis | `mcp__zen__analyze` / `mcp__zen__thinkdeep` | MCP connection | No hard limit |
|
||||||
|
|
||||||
|
## Health Checks
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# PostgreSQL
|
||||||
|
mcp__postgres__execute_sql: "SELECT 1"
|
||||||
|
|
||||||
|
# Search Router
|
||||||
|
curl -s http://192.168.10.249:30099/health
|
||||||
|
|
||||||
|
# Scrape Router
|
||||||
|
curl -s http://192.168.10.249:30098/health
|
||||||
|
|
||||||
|
# Classification API
|
||||||
|
curl -s http://192.168.10.249:30080/api/v2/content-classification/health/
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool Tiers
|
||||||
|
|
||||||
|
Skills declare which tiers they use via `compendium.tools` in YAML frontmatter.
|
||||||
|
|
||||||
|
### Tier: DB Query (`db`)
|
||||||
|
**Tool**: `mcp__postgres__execute_sql`
|
||||||
|
|
||||||
|
Direct SQL access to the Compendium database. Use parameterized queries.
|
||||||
|
|
||||||
|
### Tier: Live Browse (`browse`)
|
||||||
|
**Tool**: `mcp__playwright__browser_*`
|
||||||
|
|
||||||
|
View live social profiles, competitor websites, current SERP results. Use for visual audits and real-time data.
|
||||||
|
|
||||||
|
### Tier: Search (`search`)
|
||||||
|
**Tools**: Claude Code `WebSearch` + Search Router API
|
||||||
|
|
||||||
|
For competitive research, content discovery, trend validation. Prefer `WebSearch` for general queries; use Search Router for HVAC-specific indexed content.
|
||||||
|
|
||||||
|
### Tier: Scrape (`scrape`)
|
||||||
|
**Tool**: Scrape Router API (`http://192.168.10.249:30098`)
|
||||||
|
|
||||||
|
Full page content extraction and competitor copy harvesting.
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic scrape
|
||||||
|
curl -X POST http://192.168.10.249:30098/scrape \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"url": "https://example-hvac.com", "extract_text": true}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tier: Classify (`classify`)
|
||||||
|
**Tool**: Classification API
|
||||||
|
|
||||||
|
Classify content against HVAC taxonomy (8 dimensions).
|
||||||
|
|
||||||
|
```bash
|
||||||
|
curl -X POST http://192.168.10.249:30080/api/v2/content-classification/classify/ \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"text": "content to classify", "content_type": "article"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tier: Analyze (`analyze`)
|
||||||
|
**Tools**: `mcp__zen__analyze` / `mcp__zen__thinkdeep`
|
||||||
|
|
||||||
|
Deep analysis of content strategy, competitive positioning, and complex marketing decisions.
|
||||||
|
|
||||||
|
### Tier: Web Fetch (`fetch`)
|
||||||
|
**Tool**: Claude Code `WebFetch`
|
||||||
|
|
||||||
|
Quick page reads, API documentation lookup, lightweight scraping.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reusable Query Templates
|
||||||
|
|
||||||
|
### Content Discovery
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- trending-topics: What topics are gaining traction this week
|
||||||
|
SELECT topic, article_count, avg_engagement, trend_direction
|
||||||
|
FROM mv_topic_trends_weekly
|
||||||
|
WHERE trend_direction = 'rising'
|
||||||
|
ORDER BY article_count DESC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- topic-saturation: Find underserved content opportunities
|
||||||
|
SELECT topic, total_articles, avg_quality_score, saturation_level
|
||||||
|
FROM mv_topic_saturation
|
||||||
|
WHERE saturation_level IN ('low', 'medium')
|
||||||
|
ORDER BY total_articles ASC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- content-freshness: Find content that needs updating or repurposing
|
||||||
|
SELECT title, source_type, published_date, freshness_status
|
||||||
|
FROM mv_content_freshness
|
||||||
|
WHERE type != 'email'
|
||||||
|
AND freshness_status IN ('stale', 'aging')
|
||||||
|
ORDER BY published_date ASC
|
||||||
|
LIMIT 20;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Quotes & Statistics
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- notable-quotes: Source real quotes for content
|
||||||
|
SELECT speaker_name, quote_text, source_title, source_type, published_date
|
||||||
|
FROM mv_notable_quotes
|
||||||
|
WHERE speaker_name IS NOT NULL
|
||||||
|
ORDER BY published_date DESC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- industry-statistics: Data points for authority content
|
||||||
|
SELECT stat_text, stat_value, source_name, source_url, source_verified, collected_date
|
||||||
|
FROM intelligence.statistics
|
||||||
|
WHERE source_verified = true
|
||||||
|
ORDER BY collected_date DESC
|
||||||
|
LIMIT 30;
|
||||||
|
|
||||||
|
-- unverified-statistics: Use with "industry estimate" label
|
||||||
|
SELECT stat_text, stat_value, source_name, collected_date
|
||||||
|
FROM intelligence.statistics
|
||||||
|
WHERE source_verified = false OR source_verified IS NULL
|
||||||
|
ORDER BY collected_date DESC
|
||||||
|
LIMIT 20;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Influencer & Brand Tracking
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- influencer-activity: Track HVAC industry voices
|
||||||
|
SELECT influencer_name, platform, follower_count, post_count, avg_engagement
|
||||||
|
FROM mv_influencer_activity
|
||||||
|
ORDER BY avg_engagement DESC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- brand-content: Track brand mentions and content
|
||||||
|
SELECT brand_name, content_count, avg_sentiment, last_mentioned
|
||||||
|
FROM mv_brand_content_tracker
|
||||||
|
ORDER BY content_count DESC
|
||||||
|
LIMIT 20;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Social Media Insights
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- instagram-posts: Enriched Instagram content data
|
||||||
|
SELECT username, caption, like_count, comment_count, posted_at, content_type
|
||||||
|
FROM v_instagram_posts_enriched
|
||||||
|
ORDER BY like_count DESC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- optimal-posting: Best times to post by platform
|
||||||
|
SELECT platform, day_of_week, hour_of_day, avg_engagement
|
||||||
|
FROM mv_optimal_posting_times
|
||||||
|
ORDER BY avg_engagement DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Content Classification
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- classified-content: Browse classified content by type and quality
|
||||||
|
SELECT title, source_type, technical_level, audience_segment,
|
||||||
|
quality_score, confidence_score, classification_date
|
||||||
|
FROM v_content_classified
|
||||||
|
WHERE confidence_score >= 0.6
|
||||||
|
ORDER BY classification_date DESC
|
||||||
|
LIMIT 30;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Contractor Discovery
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- contractors: HVAC contractor data for local marketing
|
||||||
|
SELECT company_name, city, state, phone, website, rating, review_count
|
||||||
|
FROM hvac.contractors
|
||||||
|
WHERE website IS NOT NULL
|
||||||
|
ORDER BY review_count DESC
|
||||||
|
LIMIT 20;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Quality Rules
|
||||||
|
|
||||||
|
1. **Always filter `mv_content_freshness`** with `type != 'email'` — email content is internal
|
||||||
|
2. **Treat `intelligence.statistics` as unverified** unless `source_verified = true`
|
||||||
|
3. **Require `confidence_score >= 0.6`** for classification outputs from `v_content_classified`
|
||||||
|
4. **Quote attribution**: Always include `speaker_name`, `source_title`, and `published_date` from `mv_notable_quotes`
|
||||||
|
5. **Freshness**: Check `published_date` or `collected_date` — data older than 12 months should be flagged
|
||||||
|
|
||||||
|
### Confidence Labels
|
||||||
|
|
||||||
|
Use these labels when citing Compendium data in generated content:
|
||||||
|
|
||||||
|
| Label | When to use |
|
||||||
|
|-------|-------------|
|
||||||
|
| **Verified** | `source_verified = true` in `intelligence.statistics` |
|
||||||
|
| **Industry estimate** | Statistics without verification, from reputable sources |
|
||||||
|
| **Unverified — needs review** | `source_verified = false` or unknown provenance |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Fallback Behavior
|
||||||
|
|
||||||
|
When a Compendium service is unavailable, skills fall back gracefully:
|
||||||
|
|
||||||
|
| Service Down | Fallback Strategy |
|
||||||
|
|-------------|-------------------|
|
||||||
|
| PostgreSQL | Use Claude Code `WebSearch` for data; note "live data unavailable" |
|
||||||
|
| Search Router | Use Claude Code `WebSearch` directly |
|
||||||
|
| Scrape Router | Use Claude Code `WebFetch` for page content |
|
||||||
|
| Classification API | Skip classification; use manual assessment |
|
||||||
|
| Playwright MCP | Describe what would be checked; ask user to verify manually |
|
||||||
|
| Zen MCP | Use Claude's built-in analysis capabilities |
|
||||||
|
|
||||||
|
**Every skill must work standalone.** Compendium integration enhances output quality but is never a hard blocker (except skills marked `mode: required`).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Search Router API
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Search with default backends
|
||||||
|
curl "http://192.168.10.249:30099/search?q=hvac+efficiency+tips&format=json"
|
||||||
|
|
||||||
|
# Search with specific backend
|
||||||
|
curl "http://192.168.10.249:30099/search?q=hvac+contractor+reviews&backend=jina&format=json"
|
||||||
|
|
||||||
|
# Available backends: searxng-direct, searxng-proxied, jina, exa
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Scrape Router API
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Basic text extraction
|
||||||
|
curl -X POST http://192.168.10.249:30098/scrape \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"url": "https://example.com/page", "extract_text": true}'
|
||||||
|
|
||||||
|
# With metadata extraction
|
||||||
|
curl -X POST http://192.168.10.249:30098/scrape \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{"url": "https://example.com", "extract_text": true, "extract_metadata": true}'
|
||||||
|
|
||||||
|
# Chain: crawlee → camoufox → crawl4ai (automatic fallback)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Classification API
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Classify content
|
||||||
|
curl -X POST http://192.168.10.249:30080/api/v2/content-classification/classify/ \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d '{
|
||||||
|
"text": "How to diagnose a failed compressor...",
|
||||||
|
"content_type": "article",
|
||||||
|
"return_dimensions": true
|
||||||
|
}'
|
||||||
|
|
||||||
|
# 8 classification dimensions:
|
||||||
|
# - topic_category, technical_level, audience_segment, content_format
|
||||||
|
# - quality_score, engagement_potential, commercial_intent, sentiment
|
||||||
|
```
|
||||||
356
README.md
356
README.md
|
|
@ -1,257 +1,183 @@
|
||||||
# Marketing Skills for AI Agents
|
# HVAC Marketing Skills for AI Agents
|
||||||
|
|
||||||
A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want AI coding agents to help with conversion optimization, copywriting, SEO, analytics, and growth engineering. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the [Agent Skills spec](https://agentskills.io).
|
HVAC-adapted marketing skills for AI coding agents, forked from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) (MIT license). Every skill has been adapted for the HVAC industry with deep integration into the [Compendium](https://git.tealmaker.com/ben/compendium) content intelligence platform.
|
||||||
|
|
||||||
Built by [Corey Haines](https://corey.co?ref=marketingskills). Need hands-on help? Check out [Conversion Factory](https://conversionfactory.co?ref=marketingskills) — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to [Swipe Files](https://swipefiles.com?ref=marketingskills). Want an autonomous AI agent that uses these skills to be your CMO? Try [Magister](https://magistermarketing.com?ref=marketingskills).
|
**38 skills** covering HVAC content creation, local SEO, contractor marketing, seasonal campaigns, and trade-specific content strategy. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the [Agent Skills spec](https://agentskills.io).
|
||||||
|
|
||||||
New to the terminal and coding agents? Check out the companion guide [Coding for Marketers](https://codingformarketers.com?ref=marketingskills).
|
## Upstream Credit
|
||||||
|
|
||||||
**Contributions welcome!** Found a way to improve a skill or have a new one to add? [Open a PR](#contributing).
|
Original marketing skills by [Corey Haines](https://corey.co) — MIT licensed. This derivative adds HVAC industry context, Compendium database integration, and 10 new HVAC-specific skills.
|
||||||
|
|
||||||
Run into a problem or have a question? [Open an issue](https://github.com/coreyhaines31/marketingskills/issues) — we're happy to help.
|
## What's Different from Upstream
|
||||||
|
|
||||||
## What are Skills?
|
- **HVAC industry focus**: All SaaS examples replaced with HVAC equivalents (contractors, equipment, seasonal campaigns)
|
||||||
|
- **Compendium integration**: Skills can query 43K videos, 272K web articles, 15K podcasts, 6.5K social posts, and 1,400 industry statistics
|
||||||
Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, your agent can recognize when you're working on a marketing task and apply the right frameworks and best practices.
|
- **10 new HVAC skills**: Content from data, seasonal campaigns, review management, video repurposing, technical content, brand voice, contractor website audit/package, compliance claims, content QC
|
||||||
|
- **4 SaaS-only skills removed**: churn-prevention, paywall-upgrade-cro, onboarding-cro, signup-flow-cro
|
||||||
|
- **2 skills reworked**: popup-cro → hvac-estimate-popups, revops → hvac-lead-ops
|
||||||
|
- **Shared integration contract**: `COMPENDIUM_INTEGRATION.md` — single source of truth for all platform access
|
||||||
|
|
||||||
## How Skills Work Together
|
## How Skills Work Together
|
||||||
|
|
||||||
Skills reference each other and build on shared context. The `product-marketing-context` skill is the foundation — every other skill checks it first to understand your product, audience, and positioning before doing anything.
|
The `hvac-marketing-context` skill is the foundation — every other skill checks it first to understand your brands, audience, and HVAC positioning.
|
||||||
|
|
||||||
```
|
```
|
||||||
┌──────────────────────────────────────┐
|
┌──────────────────────────────────┐
|
||||||
│ product-marketing-context │
|
│ hvac-marketing-context │
|
||||||
│ (read by all other skills first) │
|
│ (read by all other skills first) │
|
||||||
└──────────────────┬───────────────────┘
|
└───────────────┬──────────────────┘
|
||||||
│
|
│
|
||||||
┌──────────────┬─────────────┬─────────────┼─────────────┬──────────────┬──────────────┐
|
┌──────────┬──────────┬──────────────┼──────────┬──────────┬──────────┐
|
||||||
▼ ▼ ▼ ▼ ▼ ▼ ▼
|
▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────┐
|
SEO & CRO Content & Paid & HVAC Sales & Strategy
|
||||||
│ SEO & │ │ CRO │ │Content & │ │ Paid & │ │ Growth & │ │ Sales & │ │ Strategy │
|
Local Copy Measure Specific GTM
|
||||||
│ Content │ │ │ │ Copy │ │Measurement │ │Retention │ │ GTM │ │ │
|
|
||||||
├──────────┤ ├──────────┤ ├──────────┤ ├────────────┤ ├──────────┤ ├─────────────┤ ├───────────┤
|
|
||||||
│seo-audit │ │page-cro │ │copywritng│ │paid-ads │ │referral │ │revops │ │mktg-ideas │
|
|
||||||
│ai-seo │ │signup-cro│ │copy-edit │ │ad-creative │ │free-tool │ │sales-enable │ │mktg-psych │
|
|
||||||
│site-arch │ │onboard │ │cold-email│ │ab-test │ │churn- │ │launch │ │ │
|
|
||||||
│programm │ │form-cro │ │email-seq │ │analytics │ │ prevent │ │pricing │ │ │
|
|
||||||
│schema │ │popup-cro │ │social │ │ │ │ │ │competitor │ │ │
|
|
||||||
│content │ │paywall │ │ │ │ │ │ │ │ │ │ │
|
|
||||||
└────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └──────┬──────┘ └─────┬─────┘
|
|
||||||
│ │ │ │ │ │ │
|
|
||||||
└────────────┴─────┬──────┴──────────────┴─────────────┴──────────────┴──────────────┘
|
|
||||||
│
|
|
||||||
Skills cross-reference each other:
|
|
||||||
copywriting ↔ page-cro ↔ ab-test-setup
|
|
||||||
revops ↔ sales-enablement ↔ cold-email
|
|
||||||
seo-audit ↔ schema-markup ↔ ai-seo
|
|
||||||
```
|
```
|
||||||
|
|
||||||
See each skill's **Related Skills** section for the full dependency map.
|
See each skill's **Related Skills** section for the full dependency map.
|
||||||
|
|
||||||
## Available Skills
|
## Compendium Integration
|
||||||
|
|
||||||
<!-- SKILLS:START -->
|
Skills operate in three modes (declared in YAML frontmatter):
|
||||||
|
|
||||||
|
| Mode | Meaning |
|
||||||
|
|------|---------|
|
||||||
|
| `standalone` | Works without any Compendium access |
|
||||||
|
| `enhanced` | Better with Compendium but fully functional without |
|
||||||
|
| `required` | Needs Compendium (only 2 skills) |
|
||||||
|
|
||||||
|
See [COMPENDIUM_INTEGRATION.md](COMPENDIUM_INTEGRATION.md) for full details on database queries, API endpoints, fallback behavior, and data quality rules.
|
||||||
|
|
||||||
|
### Primary Brands
|
||||||
|
|
||||||
|
- **HVAC Know It All** (Gary McCreadie) — YouTube, Instagram, Facebook
|
||||||
|
- **measureQuick** (Jim Bergmann) — App, YouTube, LinkedIn
|
||||||
|
|
||||||
|
## Available Skills (38)
|
||||||
|
|
||||||
|
### HVAC-Specific (New)
|
||||||
| Skill | Description |
|
| Skill | Description |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| [ab-test-setup](skills/ab-test-setup/) | When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B... |
|
| [hvac-content-from-data](skills/hvac-content-from-data/) | Create content directly from Compendium database intelligence |
|
||||||
| [ad-creative](skills/ad-creative/) | When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad... |
|
| [hvac-seasonal-campaign](skills/hvac-seasonal-campaign/) | Seasonal marketing tied to HVAC demand cycles |
|
||||||
| [ai-seo](skills/ai-seo/) | When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers.... |
|
| [hvac-review-management](skills/hvac-review-management/) | Google Business Profile review strategy |
|
||||||
| [analytics-tracking](skills/analytics-tracking/) | When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions... |
|
| [hvac-video-repurpose](skills/hvac-video-repurpose/) | Repurpose long-form video/podcast content for social |
|
||||||
| [churn-prevention](skills/churn-prevention/) | When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or... |
|
| [hvac-technical-content](skills/hvac-technical-content/) | Write technical HVAC content at the right level |
|
||||||
| [cold-email](skills/cold-email/) | Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails,... |
|
| [hvac-brand-voice](skills/hvac-brand-voice/) | Brand voice and personality guide for HVAC brands |
|
||||||
| [competitor-alternatives](skills/competitor-alternatives/) | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when... |
|
| [hvac-contractor-website-audit](skills/hvac-contractor-website-audit/) | Contractor website discovery and analysis |
|
||||||
| [content-strategy](skills/content-strategy/) | When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also... |
|
| [hvac-contractor-website-package](skills/hvac-contractor-website-package/) | Marketing package assembly from audit data |
|
||||||
| [copy-editing](skills/copy-editing/) | When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this... |
|
| [hvac-compliance-claims](skills/hvac-compliance-claims/) | EPA/rebate/safety claim checking |
|
||||||
| [copywriting](skills/copywriting/) | When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages,... |
|
| [hvac-content-qc](skills/hvac-content-qc/) | Content quality control and citation verification |
|
||||||
| [email-sequence](skills/email-sequence/) | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email... |
|
|
||||||
| [form-cro](skills/form-cro/) | When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms,... |
|
### Foundation
|
||||||
| [free-tool-strategy](skills/free-tool-strategy/) | When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or... |
|
| Skill | Description |
|
||||||
| [launch-strategy](skills/launch-strategy/) | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user... |
|
|-------|-------------|
|
||||||
| [marketing-ideas](skills/marketing-ideas/) | When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the... |
|
| [hvac-marketing-context](skills/hvac-marketing-context/) | Foundation doc — brand profiles, audience segments, HVAC calendar |
|
||||||
| [marketing-psychology](skills/marketing-psychology/) | When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when... |
|
|
||||||
| [onboarding-cro](skills/onboarding-cro/) | When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also... |
|
### SEO & Local
|
||||||
| [page-cro](skills/page-cro/) | When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing... |
|
| Skill | Description |
|
||||||
| [paid-ads](skills/paid-ads/) | When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X,... |
|
|-------|-------------|
|
||||||
| [paywall-upgrade-cro](skills/paywall-upgrade-cro/) | When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use... |
|
| [seo-audit](skills/seo-audit/) | Technical, on-page, and local SEO audit |
|
||||||
| [popup-cro](skills/popup-cro/) | When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also... |
|
| [ai-seo](skills/ai-seo/) | AI search optimization for HVAC queries |
|
||||||
| [pricing-strategy](skills/pricing-strategy/) | When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions... |
|
| [schema-markup](skills/schema-markup/) | LocalBusiness, HVACBusiness, Service structured data |
|
||||||
| [product-marketing-context](skills/product-marketing-context/) | When the user wants to create or update their product marketing context document. Also use when the user mentions... |
|
| [site-architecture](skills/site-architecture/) | HVAC contractor/brand site structure |
|
||||||
| [programmatic-seo](skills/programmatic-seo/) | When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions... |
|
| [programmatic-seo](skills/programmatic-seo/) | Location x service matrix page generation |
|
||||||
| [referral-program](skills/referral-program/) | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy.... |
|
| [competitor-alternatives](skills/competitor-alternatives/) | HVAC brand and tool comparisons |
|
||||||
| [revops](skills/revops/) | When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes.... |
|
|
||||||
| [sales-enablement](skills/sales-enablement/) | When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also... |
|
### Content & Copy
|
||||||
| [schema-markup](skills/schema-markup/) | When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user... |
|
| Skill | Description |
|
||||||
| [seo-audit](skills/seo-audit/) | When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO... |
|
|-------|-------------|
|
||||||
| [signup-flow-cro](skills/signup-flow-cro/) | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the... |
|
| [content-strategy](skills/content-strategy/) | HVAC content pillars and gap analysis |
|
||||||
| [site-architecture](skills/site-architecture/) | When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal... |
|
| [copywriting](skills/copywriting/) | HVAC voice guide with real quote sourcing |
|
||||||
| [social-content](skills/social-content/) | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram,... |
|
| [copy-editing](skills/copy-editing/) | Edit and polish existing copy |
|
||||||
<!-- SKILLS:END -->
|
| [social-content](skills/social-content/) | Platform-specific HVAC social content |
|
||||||
|
| [email-sequence](skills/email-sequence/) | HVAC newsletter and maintenance sequences |
|
||||||
|
| [cold-email](skills/cold-email/) | B2B outreach for distributors and manufacturers |
|
||||||
|
|
||||||
|
### CRO & Conversion
|
||||||
|
| Skill | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| [page-cro](skills/page-cro/) | HVAC service page optimization |
|
||||||
|
| [form-cro](skills/form-cro/) | Quote request and scheduling forms |
|
||||||
|
| [hvac-estimate-popups](skills/hvac-estimate-popups/) | Estimate request popups and seasonal CTAs |
|
||||||
|
|
||||||
|
### Paid & Measurement
|
||||||
|
| Skill | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| [paid-ads](skills/paid-ads/) | Local Service Ads and seasonal campaigns |
|
||||||
|
| [ad-creative](skills/ad-creative/) | HVAC ad creative with seasonal messaging |
|
||||||
|
| [analytics-tracking](skills/analytics-tracking/) | HVAC conversion tracking |
|
||||||
|
| [ab-test-setup](skills/ab-test-setup/) | A/B testing for HVAC pages |
|
||||||
|
|
||||||
|
### Strategy & Growth
|
||||||
|
| Skill | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| [marketing-ideas](skills/marketing-ideas/) | HVAC marketing tactics and campaigns |
|
||||||
|
| [marketing-psychology](skills/marketing-psychology/) | Psychology applied to HVAC marketing |
|
||||||
|
| [pricing-strategy](skills/pricing-strategy/) | HVAC service pricing strategy |
|
||||||
|
| [referral-program](skills/referral-program/) | Contractor referral programs |
|
||||||
|
| [free-tool-strategy](skills/free-tool-strategy/) | HVAC calculators and estimators |
|
||||||
|
| [launch-strategy](skills/launch-strategy/) | HVAC service and product launches |
|
||||||
|
|
||||||
|
### Sales & Operations
|
||||||
|
| Skill | Description |
|
||||||
|
|-------|-------------|
|
||||||
|
| [hvac-lead-ops](skills/hvac-lead-ops/) | Intake-to-booked-job funnel management |
|
||||||
|
| [sales-enablement](skills/sales-enablement/) | Equipment proposals and maintenance pitches |
|
||||||
|
|
||||||
## Installation
|
## Installation
|
||||||
|
|
||||||
### Option 1: CLI Install (Recommended)
|
### Clone and Copy (Recommended)
|
||||||
|
|
||||||
Use [npx skills](https://github.com/vercel-labs/skills) to install skills directly:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Install all skills
|
git clone http://192.168.10.31:3005/ben/hvac-marketing-skills.git
|
||||||
npx skills add coreyhaines31/marketingskills
|
cp -r hvac-marketing-skills/skills/* .agents/skills/
|
||||||
|
|
||||||
# Install specific skills
|
|
||||||
npx skills add coreyhaines31/marketingskills --skill page-cro copywriting
|
|
||||||
|
|
||||||
# List available skills
|
|
||||||
npx skills add coreyhaines31/marketingskills --list
|
|
||||||
```
|
```
|
||||||
|
|
||||||
This automatically installs to your `.agents/skills/` directory (and symlinks into `.claude/skills/` for Claude Code compatibility).
|
### Git Submodule
|
||||||
|
|
||||||
### Option 2: Claude Code Plugin
|
|
||||||
|
|
||||||
Install via Claude Code's built-in plugin system:
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Add the marketplace
|
git submodule add http://192.168.10.31:3005/ben/hvac-marketing-skills.git .agents/hvac-marketing-skills
|
||||||
/plugin marketplace add coreyhaines31/marketingskills
|
|
||||||
|
|
||||||
# Install all marketing skills
|
|
||||||
/plugin install marketing-skills
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Option 3: Clone and Copy
|
|
||||||
|
|
||||||
Clone the entire repo and copy the skills folder:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git clone https://github.com/coreyhaines31/marketingskills.git
|
|
||||||
cp -r marketingskills/skills/* .agents/skills/
|
|
||||||
```
|
|
||||||
|
|
||||||
### Option 4: Git Submodule
|
|
||||||
|
|
||||||
Add as a submodule for easy updates:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
git submodule add https://github.com/coreyhaines31/marketingskills.git .agents/marketingskills
|
|
||||||
```
|
|
||||||
|
|
||||||
Then reference skills from `.agents/marketingskills/skills/`.
|
|
||||||
|
|
||||||
### Option 5: Fork and Customize
|
|
||||||
|
|
||||||
1. Fork this repository
|
|
||||||
2. Customize skills for your specific needs
|
|
||||||
3. Clone your fork into your projects
|
|
||||||
|
|
||||||
### Option 6: SkillKit (Multi-Agent)
|
|
||||||
|
|
||||||
Use [SkillKit](https://github.com/rohitg00/skillkit) to install skills across multiple AI agents (Claude Code, Cursor, Copilot, etc.):
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# Install all skills
|
|
||||||
npx skillkit install coreyhaines31/marketingskills
|
|
||||||
|
|
||||||
# Install specific skills
|
|
||||||
npx skillkit install coreyhaines31/marketingskills --skill page-cro copywriting
|
|
||||||
|
|
||||||
# List available skills
|
|
||||||
npx skillkit install coreyhaines31/marketingskills --list
|
|
||||||
```
|
|
||||||
|
|
||||||
## Upgrading from v1.0
|
|
||||||
|
|
||||||
Skills now use `.agents/` instead of `.claude/` for the product marketing context file. Move your existing context file:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
mkdir -p .agents
|
|
||||||
mv .claude/product-marketing-context.md .agents/product-marketing-context.md
|
|
||||||
```
|
|
||||||
|
|
||||||
Skills will still check `.claude/` as a fallback, so nothing breaks if you don't.
|
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
Once installed, just ask your agent to help with marketing tasks:
|
|
||||||
|
|
||||||
```
|
```
|
||||||
"Help me optimize this landing page for conversions"
|
"Create a blog post about trending HVAC topics"
|
||||||
→ Uses page-cro skill
|
→ Uses hvac-content-from-data skill + Compendium DB
|
||||||
|
|
||||||
"Write homepage copy for my SaaS"
|
"Write an Instagram post about a field diagnostic story"
|
||||||
→ Uses copywriting skill
|
→ Uses social-content skill + hvac-brand-voice
|
||||||
|
|
||||||
"Set up GA4 tracking for signups"
|
"Audit this contractor's website: example-hvac.com"
|
||||||
→ Uses analytics-tracking skill
|
→ Uses hvac-contractor-website-audit skill
|
||||||
|
|
||||||
"Create a 5-email welcome sequence"
|
"Check this article for compliance issues"
|
||||||
→ Uses email-sequence skill
|
→ Uses hvac-compliance-claims + hvac-content-qc skills
|
||||||
```
|
```
|
||||||
|
|
||||||
You can also invoke skills directly:
|
## Tools
|
||||||
|
|
||||||
|
### Compendium Integration Tools
|
||||||
|
- `tools/compendium/compendium-search.sh` — Search Router queries
|
||||||
|
- `tools/compendium/compendium-scrape.sh` — Scrape Router requests
|
||||||
|
- `tools/compendium/compendium-classify.sh` — Classification API calls
|
||||||
|
|
||||||
|
### Kept from Upstream
|
||||||
|
- Google Ads / LSA management
|
||||||
|
- Meta Ads (Facebook/Instagram)
|
||||||
|
- Google Search Console
|
||||||
|
- Buffer (social scheduling)
|
||||||
|
- Hotjar (CRO heatmaps)
|
||||||
|
- Newsletter tools (Mailchimp/Kit)
|
||||||
|
|
||||||
|
See [tools/REGISTRY.md](tools/REGISTRY.md) for full tool index.
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./validate-skills.sh # All 38 skills must pass
|
||||||
```
|
```
|
||||||
/page-cro
|
|
||||||
/email-sequence
|
|
||||||
/seo-audit
|
|
||||||
```
|
|
||||||
|
|
||||||
## Skill Categories
|
|
||||||
|
|
||||||
### Conversion Optimization
|
|
||||||
- `page-cro` - Any marketing page
|
|
||||||
- `signup-flow-cro` - Registration flows
|
|
||||||
- `onboarding-cro` - Post-signup activation
|
|
||||||
- `form-cro` - Lead capture forms
|
|
||||||
- `popup-cro` - Modals and overlays
|
|
||||||
- `paywall-upgrade-cro` - In-app upgrade moments
|
|
||||||
|
|
||||||
### Content & Copy
|
|
||||||
- `copywriting` - Marketing page copy
|
|
||||||
- `copy-editing` - Edit and polish existing copy
|
|
||||||
- `cold-email` - B2B cold outreach emails and sequences
|
|
||||||
- `email-sequence` - Automated email flows
|
|
||||||
- `social-content` - Social media content
|
|
||||||
|
|
||||||
### SEO & Discovery
|
|
||||||
- `seo-audit` - Technical and on-page SEO
|
|
||||||
- `ai-seo` - AI search optimization (AEO, GEO, LLMO)
|
|
||||||
- `programmatic-seo` - Scaled page generation
|
|
||||||
- `site-architecture` - Page hierarchy, navigation, URL structure
|
|
||||||
- `competitor-alternatives` - Comparison and alternative pages
|
|
||||||
- `schema-markup` - Structured data
|
|
||||||
|
|
||||||
### Paid & Distribution
|
|
||||||
- `paid-ads` - Google, Meta, LinkedIn ad campaigns
|
|
||||||
- `ad-creative` - Bulk ad creative generation and iteration
|
|
||||||
- `social-content` - Social media scheduling and strategy
|
|
||||||
|
|
||||||
### Measurement & Testing
|
|
||||||
- `analytics-tracking` - Event tracking setup
|
|
||||||
- `ab-test-setup` - Experiment design
|
|
||||||
|
|
||||||
### Retention
|
|
||||||
- `churn-prevention` - Cancel flows, save offers, dunning, payment recovery
|
|
||||||
|
|
||||||
### Growth Engineering
|
|
||||||
- `free-tool-strategy` - Marketing tools and calculators
|
|
||||||
- `referral-program` - Referral and affiliate programs
|
|
||||||
|
|
||||||
### Strategy & Monetization
|
|
||||||
- `marketing-ideas` - 140 SaaS marketing ideas
|
|
||||||
- `marketing-psychology` - Mental models and psychology
|
|
||||||
- `launch-strategy` - Product launches and announcements
|
|
||||||
- `pricing-strategy` - Pricing, packaging, and monetization
|
|
||||||
|
|
||||||
### Sales & RevOps
|
|
||||||
- `revops` - Lead lifecycle, scoring, routing, pipeline management
|
|
||||||
- `sales-enablement` - Sales decks, one-pagers, objection docs, demo scripts
|
|
||||||
|
|
||||||
## Contributing
|
|
||||||
|
|
||||||
Found a way to improve a skill? Have a new skill to suggest? PRs and issues welcome!
|
|
||||||
|
|
||||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding or improving skills.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
[MIT](LICENSE) - Use these however you want.
|
[MIT](LICENSE) — forked from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills).
|
||||||
|
|
|
||||||
127
VERSIONS.md
127
VERSIONS.md
|
|
@ -1,70 +1,75 @@
|
||||||
# Marketing Skills Versions
|
# HVAC Marketing Skills Versions
|
||||||
|
|
||||||
Current versions of all skills. Agents can compare against local versions to check for updates.
|
Current versions of all skills. Forked from [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) v1.1.0.
|
||||||
|
|
||||||
| Skill | Version | Last Updated |
|
| Skill | Version | Last Updated | Status |
|
||||||
|-------|---------|--------------|
|
|-------|---------|--------------|--------|
|
||||||
| ab-test-setup | 1.1.0 | 2026-02-27 |
|
| ab-test-setup | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| ad-creative | 1.1.0 | 2026-02-27 |
|
| ad-creative | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| ai-seo | 1.1.0 | 2026-02-27 |
|
| ai-seo | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| analytics-tracking | 1.1.0 | 2026-02-27 |
|
| analytics-tracking | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| churn-prevention | 1.1.0 | 2026-02-27 |
|
| cold-email | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| cold-email | 1.1.0 | 2026-02-27 |
|
| competitor-alternatives | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| competitor-alternatives | 1.1.0 | 2026-02-27 |
|
| content-strategy | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| content-strategy | 1.1.0 | 2026-02-27 |
|
| copy-editing | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| copy-editing | 1.1.0 | 2026-02-27 |
|
| copywriting | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| copywriting | 1.1.0 | 2026-02-27 |
|
| email-sequence | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| email-sequence | 1.1.0 | 2026-02-27 |
|
| form-cro | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| form-cro | 1.1.0 | 2026-02-27 |
|
| free-tool-strategy | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| free-tool-strategy | 1.1.0 | 2026-02-27 |
|
| hvac-brand-voice | 2.0.0 | 2026-03-10 | New |
|
||||||
| launch-strategy | 1.1.0 | 2026-02-27 |
|
| hvac-compliance-claims | 2.0.0 | 2026-03-10 | New |
|
||||||
| marketing-ideas | 1.1.0 | 2026-02-27 |
|
| hvac-content-from-data | 2.0.0 | 2026-03-10 | New |
|
||||||
| marketing-psychology | 1.1.0 | 2026-02-27 |
|
| hvac-content-qc | 2.0.0 | 2026-03-10 | New |
|
||||||
| onboarding-cro | 1.1.0 | 2026-02-27 |
|
| hvac-contractor-website-audit | 2.0.0 | 2026-03-10 | New |
|
||||||
| page-cro | 1.1.0 | 2026-02-27 |
|
| hvac-contractor-website-package | 2.0.0 | 2026-03-10 | New |
|
||||||
| paid-ads | 1.1.0 | 2026-02-27 |
|
| hvac-estimate-popups | 2.0.0 | 2026-03-10 | Reworked |
|
||||||
| paywall-upgrade-cro | 1.1.0 | 2026-02-27 |
|
| hvac-lead-ops | 2.0.0 | 2026-03-10 | Reworked |
|
||||||
| popup-cro | 1.1.0 | 2026-02-27 |
|
| hvac-marketing-context | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| pricing-strategy | 1.1.0 | 2026-02-27 |
|
| hvac-review-management | 2.0.0 | 2026-03-10 | New |
|
||||||
| product-marketing-context | 1.1.0 | 2026-02-27 |
|
| hvac-seasonal-campaign | 2.0.0 | 2026-03-10 | New |
|
||||||
| programmatic-seo | 1.1.0 | 2026-02-27 |
|
| hvac-technical-content | 2.0.0 | 2026-03-10 | New |
|
||||||
| referral-program | 1.1.0 | 2026-02-27 |
|
| hvac-video-repurpose | 2.0.0 | 2026-03-10 | New |
|
||||||
| revops | 1.1.0 | 2026-02-27 |
|
| launch-strategy | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| sales-enablement | 1.1.0 | 2026-02-27 |
|
| marketing-ideas | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| schema-markup | 1.1.0 | 2026-02-27 |
|
| marketing-psychology | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| seo-audit | 1.1.0 | 2026-02-27 |
|
| page-cro | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| signup-flow-cro | 1.1.0 | 2026-02-27 |
|
| paid-ads | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| site-architecture | 1.1.0 | 2026-02-27 |
|
| pricing-strategy | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
| social-content | 1.1.0 | 2026-02-27 |
|
| programmatic-seo | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| referral-program | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| sales-enablement | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| schema-markup | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| seo-audit | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| site-architecture | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
| social-content | 2.0.0 | 2026-03-10 | Adapted |
|
||||||
|
|
||||||
## Recent Changes
|
## Changes
|
||||||
|
|
||||||
### 2026-02-27
|
### 2026-03-10 — v1.0.0-hvac (HVAC Fork)
|
||||||
- Migrated context path from `.claude/` to `.agents/` for agent-agnostic compatibility
|
- Forked from coreyhaines31/marketingskills v1.1.0
|
||||||
- All skills now check `.agents/product-marketing-context.md` first, with `.claude/` fallback for older setups
|
- All 28 retained skills adapted for HVAC industry with Compendium integration
|
||||||
- Updated install paths in README to reference `.agents/skills/`
|
- 10 new HVAC-specific skills added
|
||||||
- Bumped all 32 skills from 1.0.0 → 1.1.0
|
- 4 SaaS-only skills removed (churn-prevention, paywall-upgrade-cro, onboarding-cro, signup-flow-cro)
|
||||||
|
- 2 skills reworked (popup-cro → hvac-estimate-popups, revops → hvac-lead-ops)
|
||||||
|
- Added COMPENDIUM_INTEGRATION.md shared integration contract
|
||||||
|
- Added Compendium wrapper tools (search, scrape, classify)
|
||||||
|
- Added `compendium` capability tags to YAML frontmatter
|
||||||
|
- All skills bumped to 2.0.0
|
||||||
|
|
||||||
### 2026-02-22
|
### Upstream History (pre-fork)
|
||||||
- Added `revops` skill for revenue operations, lead lifecycle, scoring, routing, pipeline management, and CRM automation
|
|
||||||
- Added `sales-enablement` skill for sales decks, one-pagers, objection handling, demo scripts, and sales playbooks
|
|
||||||
|
|
||||||
### 2026-02-21
|
#### 2026-02-27 (upstream v1.1.0)
|
||||||
- Added `site-architecture` skill for website structure planning, page hierarchy, navigation design, URL structure, and internal linking strategy
|
- Migrated context path from `.claude/` to `.agents/`
|
||||||
|
- All skills bumped from 1.0.0 → 1.1.0
|
||||||
|
|
||||||
### 2026-02-18
|
#### 2026-02-22
|
||||||
- Added `ai-seo` skill for AI search optimization (AEO, GEO, LLMO, AI Overviews)
|
- Added `revops` and `sales-enablement` skills
|
||||||
- Moved AEO/GEO content patterns from `seo-audit` references to `ai-seo` skill
|
|
||||||
- Added `churn-prevention` skill for cancel flows, save offers, dunning, and payment recovery
|
|
||||||
|
|
||||||
### 2026-02-17
|
#### 2026-02-21
|
||||||
- Added `ad-creative` skill for bulk ad creative generation and performance-based iteration
|
- Added `site-architecture` skill
|
||||||
- Added 51 zero-dependency CLI tools for marketing platforms (`tools/clis/`)
|
|
||||||
- Added 31 new integration guides (`tools/integrations/`)
|
|
||||||
- Added 4 email outreach CLIs: hunter, snov, lemlist, instantly
|
|
||||||
- Security hardening: header auth for meta-ads, URL encoding, input validation
|
|
||||||
- All CLIs reviewed via independent codex audit (auth, security, error handling, consistency)
|
|
||||||
|
|
||||||
### 2026-01-27
|
#### 2026-02-18
|
||||||
- Initial version tracking added
|
- Added `ai-seo` and `churn-prevention` skills
|
||||||
- Added tools registry with 29 integration guides
|
|
||||||
|
#### 2026-02-17
|
||||||
|
- Added `ad-creative` skill and 51 CLI tools
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,10 @@
|
||||||
name: ab-test-setup
|
name: ab-test-setup
|
||||||
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," or "how long should I run this test." Use this whenever someone is comparing two approaches and wants to measure which performs better. For tracking implementation, see analytics-tracking. For page-level conversion optimization, see page-cro.
|
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," or "how long should I run this test." Use this whenever someone is comparing two approaches and wants to measure which performs better. For tracking implementation, see analytics-tracking. For page-level conversion optimization, see page-cro.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: standalone
|
||||||
|
tools: []
|
||||||
---
|
---
|
||||||
|
|
||||||
# A/B Test Setup
|
# A/B Test Setup
|
||||||
|
|
@ -12,7 +15,7 @@ You are an expert in experimentation and A/B testing. Your goal is to help desig
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 designing a test, understand:
|
Before designing a test, understand:
|
||||||
|
|
||||||
|
|
@ -61,7 +64,7 @@ We'll know this is true when [metrics].
|
||||||
|
|
||||||
**Weak**: "Changing the button color might increase clicks."
|
**Weak**: "Changing the button color might increase clicks."
|
||||||
|
|
||||||
**Strong**: "Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and using contrasting color will increase CTA clicks by 15%+ for new visitors. We'll measure click-through rate from page view to signup start."
|
**Strong**: "Because users report difficulty finding the CTA (per heatmaps and feedback), we believe making the button larger and more visible will increase quote request submissions by 15%+ for new visitors. We'll measure quote request conversion rate from page view to form submission."
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -91,7 +94,7 @@ We'll know this is true when [metrics].
|
||||||
- [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html)
|
- [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html)
|
||||||
- [Optimizely's](https://www.optimizely.com/sample-size-calculator/)
|
- [Optimizely's](https://www.optimizely.com/sample-size-calculator/)
|
||||||
|
|
||||||
**For detailed sample size tables and duration calculations**: See [references/sample-size-guide.md](references/sample-size-guide.md)
|
**For HVAC example:** If your current quote request rate is 3% and you want to detect a 20% lift, you need 12,000 visitors per variant, or 24,000 total.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -110,10 +113,10 @@ We'll know this is true when [metrics].
|
||||||
- Things that shouldn't get worse
|
- Things that shouldn't get worse
|
||||||
- Stop test if significantly negative
|
- Stop test if significantly negative
|
||||||
|
|
||||||
### Example: Pricing Page Test
|
### Example: Quote Request CTA Test
|
||||||
- **Primary**: Plan selection rate
|
- **Primary**: Quote request submission rate
|
||||||
- **Secondary**: Time on page, plan distribution
|
- **Secondary**: Click-through rate on CTA, form abandonment rate
|
||||||
- **Guardrail**: Support tickets, refund rate
|
- **Guardrail**: Page bounce rate (shouldn't go up), phone calls (shouldn't decrease)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -123,16 +126,34 @@ We'll know this is true when [metrics].
|
||||||
|
|
||||||
| Category | Examples |
|
| Category | Examples |
|
||||||
|----------|----------|
|
|----------|----------|
|
||||||
| Headlines/Copy | Message angle, value prop, specificity, tone |
|
| Headlines/Copy | Message angle, value prop, urgency, tone |
|
||||||
| Visual Design | Layout, color, images, hierarchy |
|
| CTA | Button copy, size, placement, color |
|
||||||
| CTA | Button copy, size, placement, number |
|
| Visual Design | Layout, hierarchy, images |
|
||||||
| Content | Information included, order, amount, social proof |
|
| Form | Fields required, button placement, form length |
|
||||||
|
| Timing | When CTA appears (immediately vs. after scroll) |
|
||||||
|
|
||||||
### Best Practices
|
### Best Practices
|
||||||
- Single, meaningful change
|
- Single, meaningful change
|
||||||
- Bold enough to make a difference
|
- Bold enough to make a difference
|
||||||
- True to the hypothesis
|
- True to the hypothesis
|
||||||
|
|
||||||
|
### HVAC-Specific Test Ideas
|
||||||
|
|
||||||
|
**Example 1: CTA Copy Test**
|
||||||
|
- **Control**: "Get Free Quote"
|
||||||
|
- **Variant**: "Schedule Service Today"
|
||||||
|
- **Hypothesis**: Specific action language increases urgency and form completion
|
||||||
|
|
||||||
|
**Example 2: Urgency Test**
|
||||||
|
- **Control**: Standard headline
|
||||||
|
- **Variant**: "Emergency AC Service Available Now"
|
||||||
|
- **Hypothesis**: Urgency language increases quote requests for emergency services
|
||||||
|
|
||||||
|
**Example 3: Form Length Test**
|
||||||
|
- **Control**: 5-field quote form (Name, Phone, Service type, Issue, Address)
|
||||||
|
- **Variant**: 3-field form (Name, Phone, Service type)
|
||||||
|
- **Hypothesis**: Fewer required fields increase form completion rate
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Traffic Allocation
|
## Traffic Allocation
|
||||||
|
|
@ -222,10 +243,30 @@ Looking at results before reaching sample size and stopping early leads to false
|
||||||
Document every test with:
|
Document every test with:
|
||||||
- Hypothesis
|
- Hypothesis
|
||||||
- Variants (with screenshots)
|
- Variants (with screenshots)
|
||||||
- Results (sample, metrics, significance)
|
- Results (sample, metrics, significance, confidence intervals)
|
||||||
- Decision and learnings
|
- Decision and learnings
|
||||||
|
- Next steps
|
||||||
|
|
||||||
**For templates**: See [references/test-templates.md](references/test-templates.md)
|
**Example:**
|
||||||
|
```markdown
|
||||||
|
## Test: CTA Copy for Quote Requests
|
||||||
|
|
||||||
|
**Hypothesis:** "Schedule Service Today" (action-specific) will increase quote form
|
||||||
|
submissions more than "Get Free Quote" (generic).
|
||||||
|
|
||||||
|
**Duration:** Jan 15-29, 2024
|
||||||
|
**Sample Size:** 15,000 per variant
|
||||||
|
|
||||||
|
**Results:**
|
||||||
|
- Control: 3.2% conversion rate (485/15,000)
|
||||||
|
- Variant: 3.8% conversion rate (570/15,000)
|
||||||
|
- Lift: +18.8%
|
||||||
|
- Confidence: 97.3% (p=0.004)
|
||||||
|
|
||||||
|
**Decision:** Implement variant. Action-specific CTA performed significantly better.
|
||||||
|
|
||||||
|
**Learning:** Specificity drives urgency. Test "Call Now" vs "Schedule Today" next.
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -263,4 +304,4 @@ Document every test with:
|
||||||
|
|
||||||
- **page-cro**: For generating test ideas based on CRO principles
|
- **page-cro**: For generating test ideas based on CRO principles
|
||||||
- **analytics-tracking**: For setting up test measurement
|
- **analytics-tracking**: For setting up test measurement
|
||||||
- **copywriting**: For creating variant copy
|
- **hvac-copywriting**: For creating variant copy
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "I want to A/B test our homepage headline. We currently say 'The All-in-One Project Management Tool' and want to test something benefit-focused. We get about 15,000 visitors/month and our current signup rate is 3.2%.",
|
"prompt": "I want to A/B test our homepage headline. We currently say 'The All-in-One Project Management Tool' and want to test something benefit-focused. We get about 15,000 visitors/month and our current signup rate is 3.2%.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should build a proper hypothesis using the framework: 'Because [observation], we believe [change] will cause [outcome], which we'll measure by [metric].' Should identify this as an A/B test (two variants). Should calculate or reference sample size needs based on 15,000 monthly visitors and 3.2% baseline. Should define primary metric (signup rate), secondary metrics, and guardrail metrics. Should warn about the peeking problem and recommend a fixed test duration. Should provide the test plan in the structured output format.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should build a proper hypothesis using the framework: 'Because [observation], we believe [change] will cause [outcome], which we'll measure by [metric].' Should identify this as an A/B test (two variants). Should calculate or reference sample size needs based on 15,000 monthly visitors and 3.2% baseline. Should define primary metric (signup rate), secondary metrics, and guardrail metrics. Should warn about the peeking problem and recommend a fixed test duration. Should provide the test plan in the structured output format.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Uses the hypothesis framework with observation, belief, outcome, and metric",
|
"Uses the hypothesis framework with observation, belief, outcome, and metric",
|
||||||
"Identifies as A/B test type",
|
"Identifies as A/B test type",
|
||||||
"Addresses sample size calculation based on traffic and baseline rate",
|
"Addresses sample size calculation based on traffic and baseline rate",
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: ad-creative
|
name: ad-creative
|
||||||
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see paid-ads. For landing page copy, see copywriting."
|
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LSA ad copy,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see paid-ads. For landing page copy, see hvac-copywriting."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Ad Creative
|
# Ad Creative
|
||||||
|
|
@ -12,35 +15,35 @@ You are an expert performance creative strategist. Your goal is to generate high
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Platform & Format
|
### 1. Platform & Format
|
||||||
- What platform? (Google Ads, Meta, LinkedIn, TikTok, Twitter/X)
|
- What platform? (Google Ads, Meta, LSA, Local Search)
|
||||||
- What ad format? (Search RSAs, display, social feed, stories, video)
|
- What ad format? (Search RSAs, display, social feed, stories)
|
||||||
- Are there existing ads to iterate on, or starting from scratch?
|
- Are there existing ads to iterate on, or starting from scratch?
|
||||||
|
|
||||||
### 2. Product & Offer
|
### 2. Service & Offer
|
||||||
- What are you promoting? (Product, feature, free trial, demo, lead magnet)
|
- What service(s)? (AC repair, furnace repair, maintenance, installation, emergency)
|
||||||
- What's the core value proposition?
|
- What's the core offer? (Same-day service, free quote, seasonal special, guarantee)
|
||||||
- What makes this different from competitors?
|
- What makes this different from competitors?
|
||||||
|
|
||||||
### 3. Audience & Intent
|
### 3. Audience & Intent
|
||||||
- Who is the target audience?
|
- Who is the target audience? (Homeowners in specific area, age range)
|
||||||
- What stage of awareness? (Problem-aware, solution-aware, product-aware)
|
- What stage of awareness? (Problem-aware: "AC broken", solution-aware: "looking for repair")
|
||||||
- What pain points or desires drive them?
|
- What pain points or desires drive them? (Comfort, safety, cost savings, speed)
|
||||||
|
|
||||||
### 4. Performance Data (if iterating)
|
### 4. Performance Data (if iterating)
|
||||||
- What creative is currently running?
|
- What creative is currently running?
|
||||||
- Which headlines/descriptions are performing best? (CTR, conversion rate, ROAS)
|
- Which headlines/descriptions are performing best? (CTR, conversion rate, CPA)
|
||||||
- Which are underperforming?
|
- Which are underperforming?
|
||||||
- What angles or themes have been tested?
|
- What angles or themes have been tested?
|
||||||
|
|
||||||
### 5. Constraints
|
### 5. Constraints
|
||||||
- Brand voice guidelines or words to avoid?
|
- Brand voice guidelines or words to avoid?
|
||||||
- Compliance requirements? (Industry regulations, platform policies)
|
- Compliance requirements? (Local licensing, guarantees)
|
||||||
- Any mandatory elements? (Brand name, trademark symbols, disclaimers)
|
- Any mandatory elements? (License number, "licensed and insured")
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -49,7 +52,7 @@ Gather this context (ask if not provided):
|
||||||
This skill supports two modes:
|
This skill supports two modes:
|
||||||
|
|
||||||
### Mode 1: Generate from Scratch
|
### Mode 1: Generate from Scratch
|
||||||
When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
|
When starting fresh, you generate a full set of ad creative based on service context, audience insights, and platform best practices.
|
||||||
|
|
||||||
### Mode 2: Iterate from Performance Data
|
### Mode 2: Iterate from Performance Data
|
||||||
When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
|
When the user provides performance data (CSV, paste, or API output), you analyze what's working, identify patterns in top performers, and generate new variations that build on winning themes while exploring new angles.
|
||||||
|
|
@ -77,9 +80,22 @@ Platforms reject or truncate creative that exceeds these limits, so verify every
|
||||||
**RSA rules:**
|
**RSA rules:**
|
||||||
- Headlines must make sense independently and in any combination
|
- Headlines must make sense independently and in any combination
|
||||||
- Pin headlines to positions only when necessary (reduces optimization)
|
- Pin headlines to positions only when necessary (reduces optimization)
|
||||||
- Include at least one keyword-focused headline
|
- Include at least one keyword-focused headline (e.g., "AC Repair")
|
||||||
- Include at least one benefit-focused headline
|
- Include at least one benefit-focused headline (e.g., "2-Hour Response")
|
||||||
- Include at least one CTA headline
|
- Include at least one CTA headline (e.g., "Call Now")
|
||||||
|
|
||||||
|
### Local Service Ads (LSA)
|
||||||
|
|
||||||
|
| Element | Limit | Notes |
|
||||||
|
|---------|-------|-------|
|
||||||
|
| Business name | 80 characters | Auto-filled from GMB |
|
||||||
|
| Service | 80 characters | "AC Repair in [City]" |
|
||||||
|
| Description | 140 characters | Service benefits |
|
||||||
|
|
||||||
|
**LSA tips:**
|
||||||
|
- Lead with urgency if emergency service
|
||||||
|
- Include guarantee or promise ("Same-day available")
|
||||||
|
- Service area automatically added by Google
|
||||||
|
|
||||||
### Meta Ads (Facebook/Instagram)
|
### Meta Ads (Facebook/Instagram)
|
||||||
|
|
||||||
|
|
@ -88,78 +104,33 @@ Platforms reject or truncate creative that exceeds these limits, so verify every
|
||||||
| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
|
| Primary text | 125 chars visible (up to 2,200) | Front-load the hook |
|
||||||
| Headline | 40 characters recommended | Below the image |
|
| Headline | 40 characters recommended | Below the image |
|
||||||
| Description | 30 characters recommended | Below headline |
|
| Description | 30 characters recommended | Below headline |
|
||||||
| URL display link | 40 characters | Optional |
|
|
||||||
|
|
||||||
### LinkedIn Ads
|
|
||||||
|
|
||||||
| Element | Limit | Notes |
|
|
||||||
|---------|-------|-------|
|
|
||||||
| Intro text | 150 chars recommended (600 max) | Above the image |
|
|
||||||
| Headline | 70 chars recommended (200 max) | Below the image |
|
|
||||||
| Description | 100 chars recommended (300 max) | Appears in some placements |
|
|
||||||
|
|
||||||
### TikTok Ads
|
|
||||||
|
|
||||||
| Element | Limit | Notes |
|
|
||||||
|---------|-------|-------|
|
|
||||||
| Ad text | 80 chars recommended (100 max) | Above the video |
|
|
||||||
| Display name | 40 characters | Brand name |
|
|
||||||
|
|
||||||
### Twitter/X Ads
|
|
||||||
|
|
||||||
| Element | Limit | Notes |
|
|
||||||
|---------|-------|-------|
|
|
||||||
| Tweet text | 280 characters | The ad copy |
|
|
||||||
| Headline | 70 characters | Card headline |
|
|
||||||
| Description | 200 characters | Card description |
|
|
||||||
|
|
||||||
For detailed specs and format variations, see [references/platform-specs.md](references/platform-specs.md).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Generating Ad Visuals
|
## Generating Ad Copy for HVAC
|
||||||
|
|
||||||
For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
|
|
||||||
|
|
||||||
- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images
|
|
||||||
- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads
|
|
||||||
- **Voice & audio** — ElevenLabs, OpenAI TTS, Cartesia for voiceovers, cloning, multilingual
|
|
||||||
- **Code-based video** — Remotion for templated, data-driven video at scale
|
|
||||||
- **Platform image specs** — Correct dimensions for every ad placement
|
|
||||||
- **Cost comparison** — Pricing for 100+ ad variations across tools
|
|
||||||
|
|
||||||
**Recommended workflow for scaled production:**
|
|
||||||
1. Generate hero creative with AI tools (exploratory, high-quality)
|
|
||||||
2. Build Remotion templates based on winning patterns
|
|
||||||
3. Batch produce variations with Remotion using data feeds
|
|
||||||
4. Iterate — AI for new angles, Remotion for scale
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Generating Ad Copy
|
|
||||||
|
|
||||||
### Step 1: Define Your Angles
|
### Step 1: Define Your Angles
|
||||||
|
|
||||||
Before writing individual headlines, establish 3-5 distinct **angles** — different reasons someone would click. Each angle should tap into a different motivation.
|
Before writing individual headlines, establish 3-5 distinct **angles** — different reasons a homeowner would click.
|
||||||
|
|
||||||
**Common angle categories:**
|
**Common angle categories for HVAC:**
|
||||||
|
|
||||||
| Category | Example Angle |
|
| Category | Example Angle |
|
||||||
|----------|---------------|
|
|----------|---------------|
|
||||||
| Pain point | "Stop wasting time on X" |
|
| Urgency/Emergency | "AC Down? We're There in 2 Hours" |
|
||||||
| Outcome | "Achieve Y in Z days" |
|
| Comfort/Safety | "Breathe Easy — Professional HVAC" |
|
||||||
| Social proof | "Join 10,000+ teams who..." |
|
| Speed | "Same-Day Service Available" |
|
||||||
| Curiosity | "The X secret top companies use" |
|
| Guarantee | "Satisfaction Guaranteed or Your Money Back" |
|
||||||
| Comparison | "Unlike X, we do Y" |
|
| Local Trust | "Serving [City] Families for 25 Years" |
|
||||||
| Urgency | "Limited time: get X free" |
|
| Cost Savings | "Free Quote — No Obligation" |
|
||||||
| Identity | "Built for [specific role/type]" |
|
| Social Proof | "4.9 Stars from 2,000+ Happy Customers" |
|
||||||
| Contrarian | "Why [common practice] doesn't work" |
|
| Prevention | "Prevent Breakdowns — Spring Maintenance" |
|
||||||
|
|
||||||
### Step 2: Generate Variations per Angle
|
### Step 2: Generate Variations per Angle
|
||||||
|
|
||||||
For each angle, generate multiple variations. Vary:
|
For each angle, generate multiple variations. Vary:
|
||||||
- **Word choice** — synonyms, active vs. passive
|
- **Word choice** — synonyms, active vs. passive
|
||||||
- **Specificity** — numbers vs. general claims
|
- **Specificity** — "2 hours" vs. "fast," "$0 service call" vs. "free"
|
||||||
- **Tone** — direct vs. question vs. command
|
- **Tone** — direct vs. question vs. command
|
||||||
- **Structure** — short punch vs. full benefit statement
|
- **Structure** — short punch vs. full benefit statement
|
||||||
|
|
||||||
|
|
@ -179,10 +150,10 @@ When the user provides performance data, follow this process:
|
||||||
|
|
||||||
### Step 1: Analyze Winners
|
### Step 1: Analyze Winners
|
||||||
|
|
||||||
Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask which metric matters most) and identify:
|
Look at the top-performing creative (by CTR, conversion rate, or CPA) and identify:
|
||||||
|
|
||||||
- **Winning themes** — What topics or pain points appear in top performers?
|
- **Winning themes** — What angles appear in top performers?
|
||||||
- **Winning structures** — Questions? Statements? Commands? Numbers?
|
- **Winning structures** — Questions? Statements? Numbers? Commands?
|
||||||
- **Winning word patterns** — Specific words or phrases that recur?
|
- **Winning word patterns** — Specific words or phrases that recur?
|
||||||
- **Character utilization** — Are top performers shorter or longer?
|
- **Character utilization** — Are top performers shorter or longer?
|
||||||
|
|
||||||
|
|
@ -191,7 +162,7 @@ Look at the top-performing creative (by CTR, conversion rate, or ROAS — ask wh
|
||||||
Look at the worst performers and identify:
|
Look at the worst performers and identify:
|
||||||
|
|
||||||
- **Themes that fall flat** — What angles aren't resonating?
|
- **Themes that fall flat** — What angles aren't resonating?
|
||||||
- **Common patterns in low performers** — Too generic? Too long? Wrong tone?
|
- **Common patterns in low performers** — Too generic? Too long?
|
||||||
|
|
||||||
### Step 3: Generate New Variations
|
### Step 3: Generate New Variations
|
||||||
|
|
||||||
|
|
@ -207,40 +178,64 @@ Track what was learned and what's being tested:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Iteration Log
|
## Iteration Log
|
||||||
- Round: [number]
|
- Round: 3
|
||||||
- Date: [date]
|
- Date: 2024-03-15
|
||||||
- Top performers: [list with metrics]
|
- Top performers: "2-Hour Emergency Response" (5.2% CTR), "Avoid AC Repair Horror" (4.8% CTR)
|
||||||
- Winning patterns: [summary]
|
- Winning patterns: Urgency, number specificity, benefits over features
|
||||||
- New variations: [count] headlines, [count] descriptions
|
- New variations: 5 new emergency angles, 3 prevention angles
|
||||||
- New angles being tested: [list]
|
- New angles being tested: Weekend availability, warranty claims
|
||||||
- Angles retired: [list]
|
- Angles retired: Generic "affordable" messaging
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Writing Quality Standards
|
## Writing Quality Standards for HVAC
|
||||||
|
|
||||||
### Headlines That Click
|
### Headlines That Click
|
||||||
|
|
||||||
**Strong headlines:**
|
**Strong headlines:**
|
||||||
- Specific ("Cut reporting time 75%") over vague ("Save time")
|
- Specific ("2-Hour Emergency AC Repair") over vague ("Fast HVAC Service")
|
||||||
- Benefits ("Ship code faster") over features ("CI/CD pipeline")
|
- Benefits ("Stay Cool All Summer") over features ("15-Year Warranty")
|
||||||
- Active voice ("Automate your reports") over passive ("Reports are automated")
|
- Active voice ("Get Your AC Fixed Today") over passive ("Your AC Can Be Repaired")
|
||||||
- Include numbers when possible ("3x faster," "in 5 minutes," "10,000+ teams")
|
- Include numbers when possible ("25 years," "2-hour response," "4.9 stars")
|
||||||
|
- Urgency for emergency services ("Now," "Today," "Emergency")
|
||||||
|
|
||||||
**Avoid:**
|
**Avoid:**
|
||||||
- Jargon the audience won't recognize
|
- Jargon homeowners won't recognize ("compressor," "refrigerant charge")
|
||||||
- Claims without specificity ("Best," "Leading," "Top")
|
- Claims without specificity ("Best," "Trusted," "Professional")
|
||||||
- All caps or excessive punctuation
|
- All caps or excessive punctuation
|
||||||
- Clickbait that the landing page can't deliver on
|
- Clickbait the landing page can't deliver on
|
||||||
|
|
||||||
### Descriptions That Convert
|
### Descriptions That Convert
|
||||||
|
|
||||||
Descriptions should complement headlines, not repeat them. Use descriptions to:
|
Descriptions should complement headlines, not repeat them. Use descriptions to:
|
||||||
- Add proof points (numbers, testimonials, awards)
|
- Add proof points ("25,000+ happy customers," "Licensed & insured")
|
||||||
- Handle objections ("No credit card required," "Free forever for small teams")
|
- Handle objections ("Free estimates," "No call-out fee")
|
||||||
- Reinforce CTAs ("Start your free trial today")
|
- Reinforce CTAs ("Call now," "Schedule your service")
|
||||||
- Add urgency when genuine ("Limited to first 500 signups")
|
- Add trust signals ("Family-owned," "Same-day available")
|
||||||
|
|
||||||
|
**Good:** "Emergency AC repair with 2-hour response. Free quote. Licensed & insured. Available 24/7."
|
||||||
|
|
||||||
|
**Bad:** "We provide air conditioning repair services for homeowners."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seasonal Creative Cycles
|
||||||
|
|
||||||
|
### Summer (May-August)
|
||||||
|
- **Themes**: Emergency, heat relief, comfort, speed
|
||||||
|
- **Keywords**: Emergency AC, AC repair, heat wave
|
||||||
|
- **Example headlines**: "AC Down in Heat Wave?" "Stay Cool All Summer"
|
||||||
|
|
||||||
|
### Winter (November-February)
|
||||||
|
- **Themes**: Warmth, safety, reliability, prevention
|
||||||
|
- **Keywords**: Emergency furnace, furnace repair, cold weather
|
||||||
|
- **Example headlines**: "Furnace Out? We'll Warm You Up" "Don't Freeze This Winter"
|
||||||
|
|
||||||
|
### Shoulder Seasons (Spring/Fall)
|
||||||
|
- **Themes**: Maintenance, prevention, checkups, preparing for season
|
||||||
|
- **Keywords**: HVAC maintenance, AC tune-up, furnace inspection
|
||||||
|
- **Example headlines**: "Spring AC Tune-Up" "Prepare for Winter Now"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -251,26 +246,25 @@ Descriptions should complement headlines, not repeat them. Use descriptions to:
|
||||||
Organize by angle, with character counts:
|
Organize by angle, with character counts:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Angle: [Pain Point — Manual Reporting]
|
## Angle: Emergency AC Repair
|
||||||
|
|
||||||
### Headlines (30 char max)
|
### Headlines (30 char max)
|
||||||
1. "Stop Building Reports by Hand" (29)
|
1. "AC Emergency? 2-Hour Response" (28)
|
||||||
2. "Automate Your Weekly Reports" (28)
|
2. "Beat the Heat — Emergency AC" (28)
|
||||||
3. "Reports Done in 5 Min, Not 5 Hr" (31) <- OVER LIMIT, trimmed below
|
3. "AC Broken? We're There Fast" (27)
|
||||||
-> "Reports in 5 Min, Not 5 Hrs" (27)
|
|
||||||
|
|
||||||
### Descriptions (90 char max)
|
### Descriptions (90 char max)
|
||||||
1. "Marketing teams save 10+ hours/week with automated reporting. Start free." (73)
|
1. "Licensed, insured, available 24/7. Free estimate. Call now!" (58)
|
||||||
2. "Connect your data sources once. Get automated reports forever. No code required." (80)
|
2. "Same-day service in your area. No obligation quote. Schedule today." (66)
|
||||||
```
|
```
|
||||||
|
|
||||||
### Bulk CSV Output
|
### Bulk CSV Output
|
||||||
|
|
||||||
When generating at scale (10+ variations), offer CSV format for direct upload:
|
When generating at scale, offer CSV format for direct upload:
|
||||||
|
|
||||||
```csv
|
```csv
|
||||||
headline_1,headline_2,headline_3,description_1,description_2,platform
|
headline_1,headline_2,headline_3,description_1,description_2,service
|
||||||
"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads"
|
"Emergency AC Repair","2-Hour Response","Call Now","Same-day service available. Licensed & insured.","Free quote, no obligation. Schedule today.","ac_repair"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Iteration Report
|
### Iteration Report
|
||||||
|
|
@ -279,52 +273,33 @@ When iterating, include a summary:
|
||||||
|
|
||||||
```
|
```
|
||||||
## Performance Summary
|
## Performance Summary
|
||||||
- Analyzed: [X] headlines, [Y] descriptions
|
- Analyzed: 18 headlines, 8 descriptions
|
||||||
- Top performer: "[headline]" — [metric]: [value]
|
- Top performer: "2-Hour Emergency AC Response" — 5.8% CTR
|
||||||
- Worst performer: "[headline]" — [metric]: [value]
|
- Worst performer: "Professional AC Service" — 1.2% CTR
|
||||||
- Pattern: [observation]
|
- Pattern: Urgency + specificity outperforms generic messaging
|
||||||
|
|
||||||
## New Creative
|
## New Creative
|
||||||
[organized variations]
|
[organized variations by angle]
|
||||||
|
|
||||||
## Recommendations
|
## Recommendations
|
||||||
- [What to pause, what to scale, what to test next]
|
- Scale "2-hour response" angle (proven winner)
|
||||||
|
- Test "avoid breakdowns" prevention angle (unexplored)
|
||||||
|
- Retire generic "professional" messaging
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Batch Generation Workflow
|
|
||||||
|
|
||||||
For large-scale creative production (Anthropic's growth team generates 100+ variations per cycle):
|
|
||||||
|
|
||||||
### 1. Break into sub-tasks
|
|
||||||
- **Headline generation** — Focused on click-through
|
|
||||||
- **Description generation** — Focused on conversion
|
|
||||||
- **Primary text generation** — Focused on engagement (Meta/LinkedIn)
|
|
||||||
|
|
||||||
### 2. Generate in waves
|
|
||||||
- Wave 1: Core angles (3-5 angles, 5 variations each)
|
|
||||||
- Wave 2: Extended variations on top 2 angles
|
|
||||||
- Wave 3: Wild card angles (contrarian, emotional, specific)
|
|
||||||
|
|
||||||
### 3. Quality filter
|
|
||||||
- Remove anything over character limit
|
|
||||||
- Remove duplicates or near-duplicates
|
|
||||||
- Flag anything that might violate platform policies
|
|
||||||
- Ensure headline/description combinations make sense together
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Common Mistakes
|
## Common Mistakes
|
||||||
|
|
||||||
- **Writing headlines that only work together** — RSA headlines get combined randomly
|
- **Writing headlines that only work together** — RSA headlines get combined randomly, must work independently
|
||||||
- **Ignoring character limits** — Platforms truncate without warning
|
- **Ignoring character limits** — Platforms truncate without warning
|
||||||
- **All variations sound the same** — Vary angles, not just word choice
|
- **All variations sound the same** — Vary angles, not just word choice
|
||||||
- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3
|
- **No urgency/CTA headlines** — For HVAC, include "Call Now," "Schedule Today"
|
||||||
- **Generic descriptions** — "Learn more about our solution" wastes the slot
|
- **Too generic** — "HVAC Service" loses to "2-Hour Emergency AC Repair"
|
||||||
- **Iterating without data** — Gut feelings are less reliable than metrics
|
- **Iterating without data** — Gut feelings are less reliable than metrics
|
||||||
- **Testing too many things at once** — Change one variable per test cycle
|
- **Testing too many things at once** — Change one variable per test cycle
|
||||||
- **Retiring creative too early** — Allow 1,000+ impressions before judging
|
- **Retiring creative too early** — Allow 1,000+ impressions before judging
|
||||||
|
- **Mismatch between urgency in ad and offer** — Don't promise "2-hour emergency" then offer scheduled appointments
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -334,29 +309,31 @@ For pulling performance data and managing campaigns, see the [tools registry](..
|
||||||
|
|
||||||
| Platform | Pull Performance Data | Manage Campaigns | Guide |
|
| Platform | Pull Performance Data | Manage Campaigns | Guide |
|
||||||
|----------|:---------------------:|:----------------:|-------|
|
|----------|:---------------------:|:----------------:|-------|
|
||||||
| **Google Ads** | `google-ads campaigns list`, `google-ads reports get` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) |
|
| **Google Ads** | `google-ads campaigns list` | `google-ads campaigns create` | [google-ads.md](../../tools/integrations/google-ads.md) |
|
||||||
| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) |
|
| **Meta Ads** | `meta-ads insights get` | `meta-ads campaigns list` | [meta-ads.md](../../tools/integrations/meta-ads.md) |
|
||||||
| **LinkedIn Ads** | `linkedin-ads analytics get` | `linkedin-ads campaigns list` | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
|
|
||||||
| **TikTok Ads** | `tiktok-ads reports get` | `tiktok-ads campaigns list` | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
|
|
||||||
|
|
||||||
### Workflow: Pull Data, Analyze, Generate
|
---
|
||||||
|
|
||||||
```bash
|
## Compendium Integration
|
||||||
# 1. Pull recent ad performance
|
|
||||||
node tools/clis/google-ads.js reports get --type ad_performance --date-range last_30_days
|
|
||||||
|
|
||||||
# 2. Analyze output (identify top/bottom performers)
|
This skill can be enhanced using **Compendium** market intelligence and competitor analysis.
|
||||||
# 3. Feed winning patterns into this skill
|
|
||||||
# 4. Generate new variations
|
**Relevant Compendium capabilities:**
|
||||||
# 5. Upload to platform
|
- **Database**: Access HVAC competitor ad creative and messaging patterns
|
||||||
```
|
- **Search**: Identify trending HVAC keywords and emerging customer pain points
|
||||||
|
|
||||||
|
**When to use Compendium:**
|
||||||
|
- Analyzing competitor ad copy to identify messaging gaps
|
||||||
|
- Finding seasonal trending keywords for creative angles
|
||||||
|
- Benchmarking your creative themes against industry standards
|
||||||
|
|
||||||
|
See [COMPENDIUM_INTEGRATION.md](../COMPENDIUM_INTEGRATION.md) for detailed workflows.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **paid-ads**: For campaign strategy, targeting, budgets, and optimization
|
- **paid-ads**: For campaign strategy, targeting, budgets, and optimization
|
||||||
- **copywriting**: For landing page copy (where ad traffic lands)
|
- **hvac-copywriting**: For landing page copy (where ad traffic lands)
|
||||||
- **ab-test-setup**: For structuring creative tests with statistical rigor
|
- **ab-test-setup**: For structuring creative tests with statistical rigor
|
||||||
- **marketing-psychology**: For psychological principles behind high-performing creative
|
- **page-cro**: For optimizing post-click conversion rates
|
||||||
- **copy-editing**: For polishing ad copy before launch
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",
|
"prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Uses angle-based generation approach",
|
"Uses angle-based generation approach",
|
||||||
"Identifies multiple angles (3-5)",
|
"Identifies multiple angles (3-5)",
|
||||||
"Respects Meta character limits (125/40/30)",
|
"Respects Meta character limits (125/40/30)",
|
||||||
|
|
|
||||||
|
|
@ -1,39 +1,42 @@
|
||||||
---
|
---
|
||||||
name: ai-seo
|
name: ai-seo
|
||||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup."
|
description: "When the user wants to optimize HVAC content for AI search engines and LLM visibility. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'get cited by AI,' 'how do I show up in AI answers,' 'LLM mentions,' 'HVAC AI search,' or 'optimize for Claude/Gemini.' Use this whenever someone wants their HVAC content cited or surfaced by AI assistants and search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [search, fetch, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# AI SEO
|
# AI SEO
|
||||||
|
|
||||||
You are an expert in AI search optimization — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help users get their content cited as a source in AI-generated answers.
|
You are an expert in AI search optimization for HVAC contractors and brands — the practice of making content discoverable, extractable, and citable by AI systems including Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, and Copilot. Your goal is to help HVAC businesses get their content cited as authoritative sources in AI-generated answers.
|
||||||
|
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Current AI Visibility
|
### 1. Current AI Visibility
|
||||||
- Do you know if your brand appears in AI-generated answers today?
|
- Do you know if your brand appears in AI-generated answers today?
|
||||||
- Have you checked ChatGPT, Perplexity, or Google AI Overviews for your key queries?
|
- Have you checked ChatGPT, Perplexity, or Google AI Overviews for HVAC queries?
|
||||||
- What queries matter most to your business?
|
- What queries matter most to your business? (e.g., "Best HVAC company near me", "When should I replace my furnace?")
|
||||||
|
|
||||||
### 2. Content & Domain
|
### 2. Content & Domain
|
||||||
- What type of content do you produce? (Blog, docs, comparisons, product pages)
|
- What type of HVAC content do you produce? (Blog, guides, equipment reviews, local service pages)
|
||||||
- What's your domain authority / traditional SEO strength?
|
- What's your domain authority / traditional SEO strength?
|
||||||
- Do you have existing structured data (schema markup)?
|
- Do you have existing structured data (schema markup)?
|
||||||
|
|
||||||
### 3. Goals
|
### 3. Goals
|
||||||
- Get cited as a source in AI answers?
|
- Get cited as an HVAC authority in AI answers?
|
||||||
- Appear in Google AI Overviews for specific queries?
|
- Appear in Google AI Overviews for specific HVAC queries?
|
||||||
- Compete with specific brands already getting cited?
|
- Compete with specific HVAC brands/competitors already getting cited?
|
||||||
- Optimize existing content or create new AI-optimized content?
|
- Optimize existing content or create new AI-optimized content?
|
||||||
|
|
||||||
### 4. Competitive Landscape
|
### 4. Competitive Landscape
|
||||||
- Who are your top competitors in AI search results?
|
- Who are your top HVAC competitors in AI search results?
|
||||||
- Are they being cited where you're not?
|
- Are they being cited where you're not?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -42,14 +45,14 @@ Gather this context (ask if not provided):
|
||||||
|
|
||||||
### The AI Search Landscape
|
### The AI Search Landscape
|
||||||
|
|
||||||
| Platform | How It Works | Source Selection |
|
| Platform | How It Works | Source Selection | HVAC Relevance |
|
||||||
|----------|-------------|----------------|
|
|----------|-------------|----------------|---|
|
||||||
| **Google AI Overviews** | Summarizes top-ranking pages | Strong correlation with traditional rankings |
|
| **Google AI Overviews** | Summarizes top-ranking pages | Strong correlation with traditional rankings | High — HVAC searches common |
|
||||||
| **ChatGPT (with search)** | Searches web, cites sources | Draws from wider range, not just top-ranked |
|
| **ChatGPT (with search)** | Searches web, cites sources | Draws from wider range, not just top-ranked | Medium — requires search mode |
|
||||||
| **Perplexity** | Always cites sources with links | Favors authoritative, recent, well-structured content |
|
| **Perplexity** | Always cites sources with links | Favors authoritative, recent, well-structured | High — citations include HVAC pros |
|
||||||
| **Gemini** | Google's AI assistant | Pulls from Google index + Knowledge Graph |
|
| **Gemini** | Google's AI assistant | Pulls from Google index + Knowledge Graph | High — same as Google index |
|
||||||
| **Copilot** | Bing-powered AI search | Bing index + authoritative sources |
|
| **Copilot** | Bing-powered AI search | Bing index + authoritative sources | Medium — Bing index coverage |
|
||||||
| **Claude** | Brave Search (when enabled) | Training data + Brave search results |
|
| **Claude** | Brave Search (when enabled) | Training data + Brave search results | Medium — less HVAC-focused |
|
||||||
|
|
||||||
For a deep dive on how each platform selects sources and what to optimize per platform, see [references/platform-ranking-factors.md](references/platform-ranking-factors.md).
|
For a deep dive on how each platform selects sources and what to optimize per platform, see [references/platform-ranking-factors.md](references/platform-ranking-factors.md).
|
||||||
|
|
||||||
|
|
@ -59,7 +62,7 @@ Traditional SEO gets you ranked. AI SEO gets you **cited**.
|
||||||
|
|
||||||
In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position.
|
In traditional search, you need to rank on page 1. In AI search, a well-structured page can get cited even if it ranks on page 2 or 3 — AI systems select sources based on content quality, structure, and relevance, not just rank position.
|
||||||
|
|
||||||
**Critical stats:**
|
**Critical stats for AI search:**
|
||||||
- AI Overviews appear in ~45% of Google searches
|
- AI Overviews appear in ~45% of Google searches
|
||||||
- AI Overviews reduce clicks to websites by up to 58%
|
- AI Overviews reduce clicks to websites by up to 58%
|
||||||
- Brands are 6.5x more likely to be cited via third-party sources than their own domains
|
- Brands are 6.5x more likely to be cited via third-party sources than their own domains
|
||||||
|
|
@ -68,34 +71,37 @@ In traditional search, you need to rank on page 1. In AI search, a well-structur
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## AI Visibility Audit
|
## AI Visibility Audit for HVAC
|
||||||
|
|
||||||
Before optimizing, assess your current AI search presence.
|
Before optimizing, assess your current AI search presence.
|
||||||
|
|
||||||
### Step 1: Check AI Answers for Your Key Queries
|
### Step 1: Check AI Answers for Your Key HVAC Queries
|
||||||
|
|
||||||
Test 10-20 of your most important queries across platforms:
|
Test 10-20 of your most important HVAC queries across platforms:
|
||||||
|
|
||||||
| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? |
|
| Query | Google AI Overview | ChatGPT | Perplexity | You Cited? | Competitors Cited? |
|
||||||
|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:|
|
|-------|:-----------------:|:-------:|:----------:|:----------:|:-----------------:|
|
||||||
| [query 1] | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
|
| "Best HVAC contractor near me" | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
|
||||||
| [query 2] | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
|
| "How to know when AC needs repair" | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
|
||||||
|
| "Furnace replacement cost" | Yes/No | Yes/No | Yes/No | Yes/No | [who] |
|
||||||
|
|
||||||
**Query types to test:**
|
**HVAC query types to test:**
|
||||||
- "What is [your product category]?"
|
- "What is [HVAC component]?" (SEER rating, AFUE, etc.)
|
||||||
- "Best [product category] for [use case]"
|
- "Best [HVAC service] for [use case]" (best AC for allergy relief, etc.)
|
||||||
- "[Your brand] vs [competitor]"
|
- "[Your brand] vs [Competitor]"
|
||||||
- "How to [problem your product solves]"
|
- "How to [HVAC maintenance task]"
|
||||||
- "[Your product category] pricing"
|
- "[HVAC component] pricing"
|
||||||
|
- "When should I [HVAC service]?"
|
||||||
|
- "Best HVAC contractor near me"
|
||||||
|
|
||||||
### Step 2: Analyze Citation Patterns
|
### Step 2: Analyze Citation Patterns
|
||||||
|
|
||||||
When your competitors get cited and you don't, examine:
|
When competitors get cited and you don't, examine:
|
||||||
- **Content structure** — Is their content more extractable?
|
- **Content structure** — Is their content more extractable?
|
||||||
- **Authority signals** — Do they have more citations, stats, expert quotes?
|
- **Authority signals** — Do they have more citations, stats, expert quotes?
|
||||||
- **Freshness** — Is their content more recently updated?
|
- **Freshness** — Is their content more recently updated?
|
||||||
- **Schema markup** — Do they have structured data you're missing?
|
- **Schema markup** — Do they have structured data you're missing?
|
||||||
- **Third-party presence** — Are they cited via Wikipedia, Reddit, review sites?
|
- **Third-party presence** — Are they cited via HVAC industry forums, Wikipedia, review sites?
|
||||||
|
|
||||||
### Step 3: Content Extractability Check
|
### Step 3: Content Extractability Check
|
||||||
|
|
||||||
|
|
@ -103,14 +109,14 @@ For each priority page, verify:
|
||||||
|
|
||||||
| Check | Pass/Fail |
|
| Check | Pass/Fail |
|
||||||
|-------|-----------|
|
|-------|-----------|
|
||||||
| Clear definition in first paragraph? | |
|
| Clear definition/answer in first paragraph? | |
|
||||||
| Self-contained answer blocks (work without surrounding context)? | |
|
| Self-contained answer blocks (work without surrounding context)? | |
|
||||||
| Statistics with sources cited? | |
|
| Statistics with sources cited? | |
|
||||||
| Comparison tables for "[X] vs [Y]" queries? | |
|
| Comparison tables for HVAC choices? | |
|
||||||
| FAQ section with natural-language questions? | |
|
| FAQ section with natural-language questions? | |
|
||||||
| Schema markup (FAQ, HowTo, Article, Product)? | |
|
| Schema markup (FAQ, HowTo, Article, LocalBusiness)? | |
|
||||||
| Expert attribution (author name, credentials)? | |
|
| Expert attribution (author name, HVAC credentials)? | |
|
||||||
| Recently updated (within 6 months)? | |
|
| Recently updated (within 3 months for HVAC info)? | |
|
||||||
| Heading structure matches query patterns? | |
|
| Heading structure matches query patterns? | |
|
||||||
| AI bots allowed in robots.txt? | |
|
| AI bots allowed in robots.txt? | |
|
||||||
|
|
||||||
|
|
@ -124,7 +130,7 @@ Verify your robots.txt allows AI crawlers. Each AI platform has its own bot, and
|
||||||
- **Google-Extended** — Google Gemini and AI Overviews
|
- **Google-Extended** — Google Gemini and AI Overviews
|
||||||
- **Bingbot** — Microsoft Copilot (via Bing)
|
- **Bingbot** — Microsoft Copilot (via Bing)
|
||||||
|
|
||||||
Check your robots.txt for `Disallow` rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers (like **CCBot** from Common Crawl) while allowing the search bots listed above.
|
Check your robots.txt for `Disallow` rules targeting any of these. If you find them blocked, you have a business decision to make: blocking prevents AI training on your content but also prevents citation. One middle ground is blocking training-only crawlers while allowing the search bots listed above.
|
||||||
|
|
||||||
See [references/platform-ranking-factors.md](references/platform-ranking-factors.md) for the full robots.txt configuration.
|
See [references/platform-ranking-factors.md](references/platform-ranking-factors.md) for the full robots.txt configuration.
|
||||||
|
|
||||||
|
|
@ -144,65 +150,66 @@ See [references/platform-ranking-factors.md](references/platform-ranking-factors
|
||||||
|
|
||||||
AI systems extract passages, not pages. Every key claim should work as a standalone statement.
|
AI systems extract passages, not pages. Every key claim should work as a standalone statement.
|
||||||
|
|
||||||
**Content block patterns:**
|
**HVAC content block patterns:**
|
||||||
- **Definition blocks** for "What is X?" queries
|
- **Definition blocks** for "What is [HVAC term]?" queries (SEER, AFUE, etc.)
|
||||||
- **Step-by-step blocks** for "How to X" queries
|
- **Step-by-step blocks** for "How to [maintenance task]" queries
|
||||||
- **Comparison tables** for "X vs Y" queries
|
- **Cost/pricing blocks** for "How much does [service] cost?"
|
||||||
- **Pros/cons blocks** for evaluation queries
|
- **Comparison tables** for "AC brand comparison" or "HVAC repair vs. replacement"
|
||||||
- **FAQ blocks** for common questions
|
- **Pros/cons blocks** for decision-making queries
|
||||||
- **Statistic blocks** with cited sources
|
- **FAQ blocks** for common HVAC questions
|
||||||
|
- **Statistic blocks** with cited sources (industry research, manufacturer specs)
|
||||||
|
|
||||||
For detailed templates for each block type, see [references/content-patterns.md](references/content-patterns.md).
|
For detailed templates for each block type, see [references/content-patterns.md](references/content-patterns.md).
|
||||||
|
|
||||||
**Structural rules:**
|
**Structural rules:**
|
||||||
- Lead every section with a direct answer (don't bury it)
|
- Lead every section with a direct answer (don't bury it)
|
||||||
- Keep key answer passages to 40-60 words (optimal for snippet extraction)
|
- Keep key answer passages to 40-60 words (optimal for snippet extraction)
|
||||||
- Use H2/H3 headings that match how people phrase queries
|
- Use H2/H3 headings that match how people phrase HVAC queries
|
||||||
- Tables beat prose for comparison content
|
- Tables beat prose for comparison/pricing content
|
||||||
- Numbered lists beat paragraphs for process content
|
- Numbered lists beat paragraphs for process content (e.g., "5 signs you need AC repair")
|
||||||
- Each paragraph should convey one clear idea
|
- Each paragraph should convey one clear idea
|
||||||
|
|
||||||
### Pillar 2: Authority — Make Content Citable
|
### Pillar 2: Authority — Make Content Citable
|
||||||
|
|
||||||
AI systems prefer sources they can trust. Build citation-worthiness.
|
AI systems prefer sources they can trust. Build citation-worthiness for HVAC content.
|
||||||
|
|
||||||
**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods:
|
**The Princeton GEO research** (KDD 2024, studied across Perplexity.ai) ranked 9 optimization methods:
|
||||||
|
|
||||||
| Method | Visibility Boost | How to Apply |
|
| Method | Visibility Boost | How to Apply (HVAC) |
|
||||||
|--------|:---------------:|--------------|
|
|--------|:---------------:|--------------|
|
||||||
| **Cite sources** | +40% | Add authoritative references with links |
|
| **Cite sources** | +40% | Link to EPA SEER standards, manufacturer specs, HVAC industry research |
|
||||||
| **Add statistics** | +37% | Include specific numbers with sources |
|
| **Add statistics** | +37% | Include specific data (avg AC lifespan, energy savings %, installed costs) |
|
||||||
| **Add quotations** | +30% | Expert quotes with name and title |
|
| **Add quotations** | +30% | Expert quotes from HVAC technicians with names/credentials |
|
||||||
| **Authoritative tone** | +25% | Write with demonstrated expertise |
|
| **Authoritative tone** | +25% | Write with demonstrated HVAC expertise |
|
||||||
| **Improve clarity** | +20% | Simplify complex concepts |
|
| **Improve clarity** | +20% | Simplify technical HVAC concepts for homeowners |
|
||||||
| **Technical terms** | +18% | Use domain-specific terminology |
|
| **Technical terms** | +18% | Use HVAC-specific terminology (SEER, AFUE, BTU, etc.) |
|
||||||
| **Unique vocabulary** | +15% | Increase word diversity |
|
| **Unique vocabulary** | +15% | Increase word diversity |
|
||||||
| **Fluency optimization** | +15-30% | Improve readability and flow |
|
| **Fluency optimization** | +15-30% | Improve readability and flow |
|
||||||
| ~~Keyword stuffing~~ | **-10%** | **Actively hurts AI visibility** |
|
| ~~Keyword stuffing~~ | **-10%** | **Actively hurts AI visibility** |
|
||||||
|
|
||||||
**Best combination:** Fluency + Statistics = maximum boost. Low-ranking sites benefit even more — up to 115% visibility increase with citations.
|
**Best combination:** Fluency + Statistics = maximum boost.
|
||||||
|
|
||||||
**Statistics and data** (+37-40% citation boost)
|
**Statistics and data** (+37-40% citation boost)
|
||||||
- Include specific numbers with sources
|
- Include specific HVAC numbers (costs, efficiency ratings, timelines)
|
||||||
- Cite original research, not summaries of research
|
- Cite original HVAC research, not summaries
|
||||||
- Add dates to all statistics
|
- Add dates to all statistics ("As of 2024...")
|
||||||
- Original data beats aggregated data
|
- Original data (from your installation projects) beats aggregated
|
||||||
|
|
||||||
**Expert attribution** (+25-30% citation boost)
|
**Expert attribution** (+25-30% citation boost)
|
||||||
- Named authors with credentials
|
- Named HVAC technicians with credentials (EPA cert, licenses)
|
||||||
- Expert quotes with titles and organizations
|
- Expert quotes with titles ("Sarah Chen, EPA-certified HVAC technician...")
|
||||||
- "According to [Source]" framing for claims
|
- "According to [source]" framing for claims
|
||||||
- Author bios with relevant expertise
|
- Author bios with relevant HVAC expertise
|
||||||
|
|
||||||
**Freshness signals**
|
**Freshness signals**
|
||||||
- "Last updated: [date]" prominently displayed
|
- "Last updated: [date]" prominently displayed
|
||||||
- Regular content refreshes (quarterly minimum for competitive topics)
|
- Regular content refreshes (quarterly minimum for HVAC how-to content)
|
||||||
- Current year references and recent statistics
|
- Current year references and recent statistics
|
||||||
- Remove or update outdated information
|
- Remove or update outdated equipment/pricing info
|
||||||
|
|
||||||
**E-E-A-T alignment**
|
**E-E-A-T alignment**
|
||||||
- First-hand experience demonstrated
|
- First-hand HVAC experience demonstrated (customer stories, project photos)
|
||||||
- Specific, detailed information (not generic)
|
- Specific, detailed information (not generic "HVAC is important")
|
||||||
- Transparent sourcing and methodology
|
- Transparent sourcing and methodology
|
||||||
- Clear author expertise for the topic
|
- Clear author expertise for the topic
|
||||||
|
|
||||||
|
|
@ -211,56 +218,59 @@ AI systems prefer sources they can trust. Build citation-worthiness.
|
||||||
AI systems don't just cite your website — they cite where you appear.
|
AI systems don't just cite your website — they cite where you appear.
|
||||||
|
|
||||||
**Third-party sources matter more than your own site:**
|
**Third-party sources matter more than your own site:**
|
||||||
- Wikipedia mentions (7.8% of all ChatGPT citations)
|
- Industry association mentions (ASHRAE, ACCA mentions)
|
||||||
- Reddit discussions (1.8% of ChatGPT citations)
|
- HVAC review sites (Google Reviews, Yelp, Angi, HomeAdvisor)
|
||||||
- Industry publications and guest posts
|
- Industry publications and guest posts
|
||||||
- Review sites (G2, Capterra, TrustRadius for B2B SaaS)
|
- HVAC forums and communities
|
||||||
- YouTube (frequently cited by Google AI Overviews)
|
- YouTube content (frequently cited by Google AI Overviews)
|
||||||
- Quora answers
|
- Quora answers about HVAC
|
||||||
|
|
||||||
**Actions:**
|
**Actions:**
|
||||||
- Ensure your Wikipedia page is accurate and current
|
- Ensure your Google Business Profile is current and cited
|
||||||
- Participate authentically in Reddit communities
|
- Maintain active presence on HVAC review platforms
|
||||||
- Get featured in industry roundups and comparison articles
|
- Get featured in industry publications
|
||||||
- Maintain updated profiles on relevant review platforms
|
- Create YouTube content for key HVAC how-to queries
|
||||||
- Create YouTube content for key how-to queries
|
- Answer relevant HVAC questions on Quora
|
||||||
- Answer relevant Quora questions with depth
|
- Sponsor or participate in HVAC industry events
|
||||||
|
- Build backlinks from HVAC industry sites
|
||||||
|
|
||||||
### Schema Markup for AI
|
### Schema Markup for AI
|
||||||
|
|
||||||
Structured data helps AI systems understand your content. Key schemas:
|
Structured data helps AI systems understand your HVAC content. Key schemas:
|
||||||
|
|
||||||
| Content Type | Schema | Why It Helps |
|
| Content Type | Schema | Why It Helps (HVAC) |
|
||||||
|-------------|--------|-------------|
|
|-------------|--------|-------------|
|
||||||
| Articles/Blog posts | `Article`, `BlogPosting` | Author, date, topic identification |
|
| Service pages | `Service`, `LocalBusiness` | Service area, provider, availability |
|
||||||
| How-to content | `HowTo` | Step extraction for process queries |
|
| How-to guides | `HowTo` | Step extraction for HVAC tasks |
|
||||||
| FAQs | `FAQPage` | Direct Q&A extraction |
|
| FAQs | `FAQPage` | Direct Q&A extraction for HVAC questions |
|
||||||
| Products | `Product` | Pricing, features, reviews |
|
| Location pages | `LocalBusiness` | Address, service areas, reviews |
|
||||||
| Comparisons | `ItemList` | Structured comparison data |
|
| Reviews | `Review`, `AggregateRating` | Trust signals for HVAC contractor |
|
||||||
| Reviews | `Review`, `AggregateRating` | Trust signals |
|
| Equipment/products | `Product` | Specs, pricing, reviews |
|
||||||
| Organization | `Organization` | Entity recognition |
|
| Articles/Blog | `Article`, `BlogPosting` | Author, date, topic identification |
|
||||||
|
| Organization | `Organization` | Entity recognition for HVAC company |
|
||||||
|
|
||||||
Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill.
|
Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Content Types That Get Cited Most
|
## HVAC Content Types That Get Cited Most
|
||||||
|
|
||||||
Not all content is equally citable. Prioritize these formats:
|
Not all content is equally citable. Prioritize these formats:
|
||||||
|
|
||||||
| Content Type | Citation Share | Why AI Cites It |
|
| Content Type | Citation Share | Why AI Cites It (HVAC) |
|
||||||
|-------------|:------------:|----------------|
|
|-------------|:------------:|----------------|
|
||||||
| **Comparison articles** | ~33% | Structured, balanced, high-intent |
|
| **Comparison articles** | ~33% | "Furnace brands compared", "AC repair vs. replacement" |
|
||||||
| **Definitive guides** | ~15% | Comprehensive, authoritative |
|
| **Definitive guides** | ~15% | "Complete HVAC maintenance guide" |
|
||||||
| **Original research/data** | ~12% | Unique, citable statistics |
|
| **Original research/data** | ~12% | HVAC contractor cost surveys, efficiency studies |
|
||||||
| **Best-of/listicles** | ~10% | Clear structure, entity-rich |
|
| **Best-of/listicles** | ~10% | "Best HVAC contractors in Denver" |
|
||||||
| **Product pages** | ~10% | Specific details AI can extract |
|
| **How-to guides** | ~8% | "How to change HVAC filter", "AC troubleshooting" |
|
||||||
| **How-to guides** | ~8% | Step-by-step structure |
|
| **FAQ pages** | ~7% | Common HVAC questions answered |
|
||||||
| **Opinion/analysis** | ~10% | Expert perspective, quotable |
|
| **Cost/pricing pages** | ~8% | HVAC service pricing, equipment costs |
|
||||||
|
| **Product pages** | ~10% | HVAC equipment specs and features |
|
||||||
|
|
||||||
**Underperformers for AI citation:**
|
**Underperformers for AI citation:**
|
||||||
- Generic blog posts without structure
|
- Generic service pages without details
|
||||||
- Thin product pages with marketing fluff
|
- Thin "learn more" pages (no substance)
|
||||||
- Gated content (AI can't access it)
|
- Gated content (AI can't access it)
|
||||||
- Content without dates or author attribution
|
- Content without dates or author attribution
|
||||||
- PDF-only content (harder for AI to parse)
|
- PDF-only content (harder for AI to parse)
|
||||||
|
|
@ -276,7 +286,7 @@ Not all content is equally citable. Prioritize these formats:
|
||||||
| AI Overview presence | Do AI Overviews appear for your queries? | Manual check or Semrush/Ahrefs |
|
| AI Overview presence | Do AI Overviews appear for your queries? | Manual check or Semrush/Ahrefs |
|
||||||
| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) |
|
| Brand citation rate | How often you're cited in AI answers | AI visibility tools (see below) |
|
||||||
| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie |
|
| Share of AI voice | Your citations vs. competitors | Peec AI, Otterly, ZipTie |
|
||||||
| Citation sentiment | How AI describes your brand | Manual review + monitoring tools |
|
| Citation sentiment | How AI describes your HVAC brand | Manual review + monitoring tools |
|
||||||
| Source attribution | Which of your pages get cited | Track referral traffic from AI sources |
|
| Source attribution | Which of your pages get cited | Track referral traffic from AI sources |
|
||||||
|
|
||||||
### AI Visibility Monitoring Tools
|
### AI Visibility Monitoring Tools
|
||||||
|
|
@ -291,60 +301,66 @@ Not all content is equally citable. Prioritize these formats:
|
||||||
### DIY Monitoring (No Tools)
|
### DIY Monitoring (No Tools)
|
||||||
|
|
||||||
Monthly manual check:
|
Monthly manual check:
|
||||||
1. Pick your top 20 queries
|
1. Pick your top 20 HVAC queries
|
||||||
2. Run each through ChatGPT, Perplexity, and Google
|
2. Run each through ChatGPT, Perplexity, and Google
|
||||||
3. Record: Are you cited? Who is? What page?
|
3. Record: Are you cited? Who is? What page?
|
||||||
4. Log in a spreadsheet, track month-over-month
|
4. Log in a spreadsheet, track month-over-month
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## AI SEO for Different Content Types
|
## HVAC-Specific Content Optimization Examples
|
||||||
|
|
||||||
### SaaS Product Pages
|
### Service Pages (AC Repair, Furnace Installation, etc.)
|
||||||
|
|
||||||
**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.
|
**Goal:** Get cited in "What is [service]?" and "Best [service] in [location]" queries.
|
||||||
|
|
||||||
**Optimize:**
|
**Optimize:**
|
||||||
- Clear product description in first paragraph (what it does, who it's for)
|
- Clear service description in first paragraph
|
||||||
- Feature comparison tables (you vs. category, not just competitors)
|
- Timeline and cost range (what to expect)
|
||||||
- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast")
|
- Signs you need this service (troubleshooting)
|
||||||
- Customer count or social proof with numbers
|
- Local availability and service areas
|
||||||
- Pricing transparency (AI cites pages with visible pricing)
|
- Technician credentials (EPA, licenses)
|
||||||
- FAQ section addressing common buyer questions
|
- FAQ addressing common service questions
|
||||||
|
- Customer testimonials with names and locations
|
||||||
|
|
||||||
### Blog Content
|
### HVAC Equipment Pages
|
||||||
|
|
||||||
**Goal:** Get cited as an authoritative source on topics in your space.
|
**Goal:** Get cited in "Carrier [model] reviews", "Best furnaces 2024" queries.
|
||||||
|
|
||||||
**Optimize:**
|
**Optimize:**
|
||||||
- One clear target query per post (match heading to query)
|
- SEER/AFUE rating prominently displayed
|
||||||
- Definition in first paragraph for "What is" queries
|
- Price range or typical installed cost
|
||||||
- Original data, research, or expert quotes
|
- Energy savings estimate based on specs
|
||||||
|
- Comparison table vs. competing models
|
||||||
|
- Warranty information
|
||||||
|
- Where to buy/install (contractor directory)
|
||||||
|
- User reviews and ratings
|
||||||
|
|
||||||
|
### HVAC Blog Content & Guides
|
||||||
|
|
||||||
|
**Goal:** Get cited as authoritative source on HVAC topics.
|
||||||
|
|
||||||
|
**Optimize:**
|
||||||
|
- One clear target query per post
|
||||||
|
- Definition in first paragraph
|
||||||
|
- Step-by-step format for how-to content
|
||||||
|
- Original data or expert quotes (from HVAC professionals)
|
||||||
- "Last updated" date visible
|
- "Last updated" date visible
|
||||||
- Author bio with relevant credentials
|
- Author bio with HVAC credentials
|
||||||
- Internal links to related product/feature pages
|
- Links to related service/product pages
|
||||||
|
- FAQ section
|
||||||
|
|
||||||
### Comparison/Alternative Pages
|
### Cost & Pricing Pages
|
||||||
|
|
||||||
**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries.
|
**Goal:** Get cited in "How much does HVAC repair cost?" queries.
|
||||||
|
|
||||||
**Optimize:**
|
**Optimize:**
|
||||||
- Structured comparison tables (not just prose)
|
- Specific price ranges by service/location
|
||||||
- Fair and balanced (AI penalizes obviously biased comparisons)
|
- Cost factors explained (equipment, labor, complexity)
|
||||||
- Specific criteria with ratings or scores
|
- Comparison of price vs. quality/longevity
|
||||||
- Updated pricing and feature data
|
- Financing/payment options
|
||||||
- Cite the competitor-alternatives skill for building these pages
|
- Estimate example walkthrough
|
||||||
|
- Local cost data (costs vary by region)
|
||||||
### Documentation / Help Content
|
|
||||||
|
|
||||||
**Goal:** Get cited in "How to [X] with [your product]" queries.
|
|
||||||
|
|
||||||
**Optimize:**
|
|
||||||
- Step-by-step format with numbered lists
|
|
||||||
- Code examples where relevant
|
|
||||||
- HowTo schema markup
|
|
||||||
- Screenshots with descriptive alt text
|
|
||||||
- Clear prerequisites and expected outcomes
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -353,13 +369,13 @@ Monthly manual check:
|
||||||
- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast
|
- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast
|
||||||
- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top
|
- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top
|
||||||
- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert
|
- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert
|
||||||
- **No freshness signals** — Undated content loses to dated content because AI systems weight recency heavily. Show when content was last updated
|
- **No freshness signals** — Undated or outdated HVAC information loses to current content because AI systems weight recency heavily
|
||||||
- **Gating all content** — AI can't access gated content. Keep your most authoritative content open
|
- **Gating all content** — AI can't access gated content. Keep your most authoritative HVAC content open
|
||||||
- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog
|
- **Ignoring third-party presence** — You may get more AI citations from an Angi or HomeAdvisor listing than from your own blog
|
||||||
- **No structured data** — Schema markup gives AI systems structured context about your content
|
- **No structured data** — Schema markup gives AI systems structured context about your HVAC services and locations
|
||||||
- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study)
|
- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10%
|
||||||
- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you
|
- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you
|
||||||
- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will
|
- **Generic content without data** — "We're the best HVAC contractor" won't get cited. "Our customers save $300/year with our maintenance plans" will
|
||||||
- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum
|
- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -370,29 +386,37 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md).
|
||||||
|
|
||||||
| Tool | Use For |
|
| Tool | Use For |
|
||||||
|------|---------|
|
|------|---------|
|
||||||
| `semrush` | AI Overview tracking, keyword research, content gap analysis |
|
| `semrush` | AI Overview tracking, HVAC keyword research, content gap analysis |
|
||||||
| `ahrefs` | Backlink analysis, content explorer, AI Overview data |
|
| `ahrefs` | Backlink analysis, content explorer, AI Overview data |
|
||||||
| `gsc` | Search Console performance data, query tracking |
|
| `gsc` | Search Console performance data, query tracking |
|
||||||
| `ga4` | Referral traffic from AI sources |
|
| `ga4` | Referral traffic from AI sources |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill integrates with Compendium content intelligence platform for HVAC market analysis:
|
||||||
|
- **Tool tier**: `search` (identify AI-optimized HVAC competitors), `fetch` (validate content structure), `analyze` (AI interpretation of HVAC content)
|
||||||
|
- **Reference**: See `COMPENDIUM_INTEGRATION.md` for HVAC data pipelines (competitor analysis, HVAC content benchmarking)
|
||||||
|
- **Use case**: Identify AI citation opportunities in HVAC market, benchmark AI visibility vs. competitors, discover content gaps
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What are your top 10-20 most important queries?
|
1. What are your top 20 most important HVAC queries?
|
||||||
2. Have you checked if AI answers exist for those queries today?
|
2. Have you checked if AI answers exist for those queries today?
|
||||||
3. Do you have structured data (schema markup) on your site?
|
3. Do you have structured data (schema markup) on your HVAC site?
|
||||||
4. What content types do you publish? (Blog, docs, comparisons, etc.)
|
4. What HVAC content types do you publish? (Blog, guides, equipment reviews, local pages)
|
||||||
5. Are competitors being cited by AI where you're not?
|
5. Are HVAC competitors being cited by AI where you're not?
|
||||||
6. Do you have a Wikipedia page or presence on review sites?
|
6. Do you have a Google Business Profile and HVAC review site presence?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **seo-audit**: For traditional technical and on-page SEO audits
|
- **seo-audit**: For traditional technical and on-page SEO audits
|
||||||
- **schema-markup**: For implementing structured data that helps AI understand your content
|
- **schema-markup**: For implementing structured data (LocalBusiness, Service, HowTo)
|
||||||
- **content-strategy**: For planning what content to create
|
- **content-strategy**: For planning what HVAC content to create
|
||||||
- **competitor-alternatives**: For building comparison pages that get cited
|
- **programmatic-seo**: For building location + service pages at scale
|
||||||
- **programmatic-seo**: For building SEO pages at scale
|
- **competitor-alternatives**: For building HVAC comparison pages
|
||||||
- **copywriting**: For writing content that's both human-readable and AI-extractable
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.",
|
"prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies three pillars framework (Structure, Authority, Presence)",
|
"Applies three pillars framework (Structure, Authority, Presence)",
|
||||||
"Runs AI Visibility Audit across platforms",
|
"Runs AI Visibility Audit across platforms",
|
||||||
"Checks content extractability",
|
"Checks content extractability",
|
||||||
|
|
|
||||||
|
|
@ -1,24 +1,27 @@
|
||||||
---
|
---
|
||||||
name: analytics-tracking
|
name: analytics-tracking
|
||||||
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-test-setup.
|
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "phone call tracking," "quote request tracking," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-test-setup.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [fetch, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Analytics Tracking
|
# Analytics Tracking
|
||||||
|
|
||||||
You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions.
|
You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and business decisions.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 tracking, understand:
|
Before implementing tracking, understand:
|
||||||
|
|
||||||
1. **Business Context** - What decisions will this data inform? What are key conversions?
|
1. **Business Context** - What decisions will this data inform? (Budget allocation, service focus, expansion)
|
||||||
2. **Current State** - What tracking exists? What tools are in use?
|
2. **Current State** - What tracking exists? What tools are in use?
|
||||||
3. **Technical Context** - What's the tech stack? Any privacy/compliance requirements?
|
3. **Technical Context** - What's the tech stack? Any privacy requirements?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -26,7 +29,7 @@ Before implementing tracking, understand:
|
||||||
|
|
||||||
### 1. Track for Decisions, Not Data
|
### 1. Track for Decisions, Not Data
|
||||||
- Every event should inform a decision
|
- Every event should inform a decision
|
||||||
- Avoid vanity metrics
|
- Avoid vanity metrics (form views matter less than quote requests)
|
||||||
- Quality > quantity of events
|
- Quality > quantity of events
|
||||||
|
|
||||||
### 2. Start with the Questions
|
### 2. Start with the Questions
|
||||||
|
|
@ -46,25 +49,26 @@ Before implementing tracking, understand:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tracking Plan Framework
|
## Essential Events for HVAC
|
||||||
|
|
||||||
### Structure
|
### Marketing Site
|
||||||
|
|
||||||
```
|
| Event | Properties | Why It Matters |
|
||||||
Event Name | Category | Properties | Trigger | Notes
|
|-------|------------|----------------|
|
||||||
---------- | -------- | ---------- | ------- | -----
|
| quote_request_submitted | service_type, page | Lead generation |
|
||||||
```
|
| phone_call_initiated | service_type, source | Direct conversion |
|
||||||
|
| service_area_check | zip_code, result | Audience quality |
|
||||||
|
| testimonial_viewed | service_type | Social proof engagement |
|
||||||
|
| pricing_page_viewed | - | Consideration signal |
|
||||||
|
|
||||||
### Event Types
|
### Lead Qualification
|
||||||
|
|
||||||
| Type | Examples |
|
| Event | Properties | Why It Matters |
|
||||||
|------|----------|
|
|-------|------------|----------------|
|
||||||
| Pageviews | Automatic, enhanced with metadata |
|
| quote_call_received | service_type, customer_new_or_existing | Call tracking integration |
|
||||||
| User Actions | Button clicks, form submissions, feature usage |
|
| quote_converted_to_booking | service_type, service_value | Pipeline conversion |
|
||||||
| System Events | Signup completed, purchase, subscription changed |
|
| service_completed | service_type, customer_review_left | Outcome measurement |
|
||||||
| Custom Conversions | Goal completions, funnel stages |
|
| maintenance_agreement_enrolled | plan_type, duration | Recurring revenue |
|
||||||
|
|
||||||
**For comprehensive event lists**: See [references/event-library.md](references/event-library.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -73,62 +77,39 @@ Event Name | Category | Properties | Trigger | Notes
|
||||||
### Recommended Format: Object-Action
|
### Recommended Format: Object-Action
|
||||||
|
|
||||||
```
|
```
|
||||||
signup_completed
|
quote_request_submitted
|
||||||
button_clicked
|
phone_call_initiated
|
||||||
form_submitted
|
service_booked_confirmed
|
||||||
article_read
|
maintenance_agreement_enrolled
|
||||||
checkout_payment_completed
|
review_submitted
|
||||||
```
|
```
|
||||||
|
|
||||||
### Best Practices
|
### Best Practices
|
||||||
- Lowercase with underscores
|
- Lowercase with underscores
|
||||||
- Be specific: `cta_hero_clicked` vs. `button_clicked`
|
- Be specific: `ac_repair_quote_requested` vs. `quote_requested`
|
||||||
- Include context in properties, not event name
|
- Include context in properties, not event name
|
||||||
- Avoid spaces and special characters
|
- Avoid spaces and special characters
|
||||||
- Document decisions
|
- Document decisions
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Essential Events
|
|
||||||
|
|
||||||
### Marketing Site
|
|
||||||
|
|
||||||
| Event | Properties |
|
|
||||||
|-------|------------|
|
|
||||||
| cta_clicked | button_text, location |
|
|
||||||
| form_submitted | form_type |
|
|
||||||
| signup_completed | method, source |
|
|
||||||
| demo_requested | - |
|
|
||||||
|
|
||||||
### Product/App
|
|
||||||
|
|
||||||
| Event | Properties |
|
|
||||||
|-------|------------|
|
|
||||||
| onboarding_step_completed | step_number, step_name |
|
|
||||||
| feature_used | feature_name |
|
|
||||||
| purchase_completed | plan, value |
|
|
||||||
| subscription_cancelled | reason |
|
|
||||||
|
|
||||||
**For full event library by business type**: See [references/event-library.md](references/event-library.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Event Properties
|
## Event Properties
|
||||||
|
|
||||||
### Standard Properties
|
### Standard Properties for HVAC
|
||||||
|
|
||||||
| Category | Properties |
|
| Category | Properties |
|
||||||
|----------|------------|
|
|----------|------------|
|
||||||
| Page | page_title, page_location, page_referrer |
|
| Page | page_title, page_location, page_referrer |
|
||||||
| User | user_id, user_type, account_id, plan_type |
|
| User | user_id, customer_id, is_new_customer |
|
||||||
| Campaign | source, medium, campaign, content, term |
|
| Campaign | utm_source, utm_medium, utm_campaign |
|
||||||
| Product | product_id, product_name, category, price |
|
| Service | service_type (ac_repair, furnace_repair, maintenance, installation), urgency (emergency, scheduled) |
|
||||||
|
| Business | service_area, estimated_value, conversion_time |
|
||||||
|
|
||||||
### Best Practices
|
### Best Practices
|
||||||
- Use consistent property names
|
- Use consistent property names
|
||||||
- Include relevant context
|
- Include relevant context
|
||||||
- Don't duplicate automatic properties
|
- Don't duplicate automatic properties
|
||||||
- Avoid PII in properties
|
- Avoid PII in properties (no names, addresses, phone numbers)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -139,64 +120,119 @@ checkout_payment_completed
|
||||||
1. Create GA4 property and data stream
|
1. Create GA4 property and data stream
|
||||||
2. Install gtag.js or GTM
|
2. Install gtag.js or GTM
|
||||||
3. Enable enhanced measurement
|
3. Enable enhanced measurement
|
||||||
4. Configure custom events
|
4. Configure custom events for HVAC conversions
|
||||||
5. Mark conversions in Admin
|
5. Mark conversions in Admin
|
||||||
|
|
||||||
### Custom Event Example
|
### Custom Event Example
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
gtag('event', 'signup_completed', {
|
gtag('event', 'quote_request_submitted', {
|
||||||
'method': 'email',
|
'service_type': 'ac_repair',
|
||||||
'plan': 'free'
|
'page_location': 'service-page',
|
||||||
|
'urgency': 'emergency'
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
**For detailed GA4 implementation**: See [references/ga4-implementation.md](references/ga4-implementation.md)
|
### Phone Call Tracking
|
||||||
|
|
||||||
|
GA4 doesn't automatically track phone calls. Options:
|
||||||
|
|
||||||
|
**Option 1: Tracking number (recommended for HVAC)**
|
||||||
|
- Use CallRail, Call Tracking Metrics, or similar
|
||||||
|
- Track phone numbers as conversion events
|
||||||
|
- Connect to CRM for full attribution
|
||||||
|
|
||||||
|
**Option 2: Click-to-call tracking**
|
||||||
|
```javascript
|
||||||
|
document.getElementById('call-button').addEventListener('click', function() {
|
||||||
|
gtag('event', 'phone_call_initiated', {
|
||||||
|
'service_type': 'emergency_ac'
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Google Tag Manager
|
## Google Tag Manager Setup
|
||||||
|
|
||||||
### Container Structure
|
### Container Structure
|
||||||
|
|
||||||
| Component | Purpose |
|
| Component | Purpose | HVAC Example |
|
||||||
|-----------|---------|
|
|-----------|---------|--------------|
|
||||||
| Tags | Code that executes (GA4, pixels) |
|
| Tags | Code that executes (GA4, pixels) | GA4 event tag for quote_request |
|
||||||
| Triggers | When tags fire (page view, click) |
|
| Triggers | When tags fire | Form submission, button click |
|
||||||
| Variables | Dynamic values (click text, data layer) |
|
| Variables | Dynamic values (click text, data layer) | service_type from form |
|
||||||
|
|
||||||
### Data Layer Pattern
|
### Data Layer Pattern
|
||||||
|
|
||||||
```javascript
|
```javascript
|
||||||
dataLayer.push({
|
dataLayer.push({
|
||||||
'event': 'form_submitted',
|
'event': 'quote_request_submitted',
|
||||||
'form_name': 'contact',
|
'service_type': 'ac_repair',
|
||||||
'form_location': 'footer'
|
'page_location': 'service-ac-repair'
|
||||||
});
|
});
|
||||||
```
|
```
|
||||||
|
|
||||||
**For detailed GTM implementation**: See [references/gtm-implementation.md](references/gtm-implementation.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## UTM Parameter Strategy
|
## UTM Parameter Strategy
|
||||||
|
|
||||||
### Standard Parameters
|
### Standard Parameters for HVAC
|
||||||
|
|
||||||
| Parameter | Purpose | Example |
|
| Parameter | Purpose | Example |
|
||||||
|-----------|---------|---------|
|
|-----------|---------|---------|
|
||||||
| utm_source | Traffic source | google, newsletter |
|
| utm_source | Traffic source | google_lsa, facebook, email |
|
||||||
| utm_medium | Marketing medium | cpc, email, social |
|
| utm_medium | Marketing medium | cpc, social, email |
|
||||||
| utm_campaign | Campaign name | spring_sale |
|
| utm_campaign | Campaign name | summer_ac_campaign |
|
||||||
| utm_content | Differentiate versions | hero_cta |
|
| utm_content | Differentiate versions | emergency_ad_1, maintenance_ad_2 |
|
||||||
| utm_term | Paid search keywords | running+shoes |
|
|
||||||
|
|
||||||
### Naming Conventions
|
### Naming Conventions
|
||||||
- Lowercase everything
|
- Lowercase everything
|
||||||
- Use underscores or hyphens consistently
|
- Use underscores consistently
|
||||||
- Be specific but concise: `blog_footer_cta`, not `cta1`
|
- Be specific: `google_lsa_ac_emergency`, not `google1`
|
||||||
- Document all UTMs in a spreadsheet
|
- Document all UTMs in a spreadsheet
|
||||||
|
|
||||||
|
### Example URLs
|
||||||
|
|
||||||
|
```
|
||||||
|
Home page from Google LSA:
|
||||||
|
https://example.com/?utm_source=google_lsa&utm_medium=cpc&utm_campaign=ac_repair_emergency
|
||||||
|
|
||||||
|
Facebook retargeting:
|
||||||
|
https://example.com/?utm_source=facebook&utm_medium=social&utm_campaign=summer_ac&utm_content=lookalike_warm
|
||||||
|
|
||||||
|
Email campaign:
|
||||||
|
https://example.com/?utm_source=email&utm_medium=email&utm_campaign=spring_maintenance
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phone Call Tracking Integration
|
||||||
|
|
||||||
|
For HVAC, phone calls are often the primary conversion. Options:
|
||||||
|
|
||||||
|
### Call Tracking Software
|
||||||
|
- **CallRail** — Track calls, record, integrate with CRM
|
||||||
|
- **Call Tracking Metrics** — Similar to CallRail
|
||||||
|
- **Google Call Extensions** — Built into Google Ads, tracks calls
|
||||||
|
|
||||||
|
### Implementation
|
||||||
|
1. Get unique tracking number(s) per campaign
|
||||||
|
2. Display on website (dynamic number insertion)
|
||||||
|
3. Log calls in GA4 as conversion events
|
||||||
|
4. Integrate with CRM to track lead quality
|
||||||
|
5. Report on cost per call and call quality
|
||||||
|
|
||||||
|
### GA4 Phone Call Event
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
gtag('event', 'phone_call_initiated', {
|
||||||
|
'phone_number': '[tracking_number]',
|
||||||
|
'service_type': 'emergency_ac',
|
||||||
|
'utm_source': 'google_lsa'
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Debugging and Validation
|
## Debugging and Validation
|
||||||
|
|
@ -216,6 +252,7 @@ dataLayer.push({
|
||||||
- [ ] No duplicate events
|
- [ ] No duplicate events
|
||||||
- [ ] Works across browsers and mobile
|
- [ ] Works across browsers and mobile
|
||||||
- [ ] Conversions recorded correctly
|
- [ ] Conversions recorded correctly
|
||||||
|
- [ ] Phone calls tracked (if using call tracking)
|
||||||
- [ ] No PII leaking
|
- [ ] No PII leaking
|
||||||
|
|
||||||
### Common Issues
|
### Common Issues
|
||||||
|
|
@ -225,6 +262,7 @@ dataLayer.push({
|
||||||
| Events not firing | Trigger config, GTM loaded |
|
| Events not firing | Trigger config, GTM loaded |
|
||||||
| Wrong values | Variable path, data layer structure |
|
| Wrong values | Variable path, data layer structure |
|
||||||
| Duplicate events | Multiple containers, trigger firing twice |
|
| Duplicate events | Multiple containers, trigger firing twice |
|
||||||
|
| Phone calls not tracked | Tracking number integration, GA4 event setup |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -237,7 +275,7 @@ dataLayer.push({
|
||||||
- User deletion capabilities
|
- User deletion capabilities
|
||||||
|
|
||||||
### Implementation
|
### Implementation
|
||||||
- Use consent mode (wait for consent)
|
- Use consent mode (wait for consent before firing)
|
||||||
- IP anonymization
|
- IP anonymization
|
||||||
- Only collect what you need
|
- Only collect what you need
|
||||||
- Integrate with consent management platform
|
- Integrate with consent management platform
|
||||||
|
|
@ -249,61 +287,61 @@ dataLayer.push({
|
||||||
### Tracking Plan Document
|
### Tracking Plan Document
|
||||||
|
|
||||||
```markdown
|
```markdown
|
||||||
# [Site/Product] Tracking Plan
|
# HVAC Website Tracking Plan
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
- Tools: GA4, GTM
|
- Tools: GA4, GTM, CallRail
|
||||||
- Last updated: [Date]
|
- Last updated: 2024-03-15
|
||||||
|
|
||||||
## Events
|
## Conversion Events
|
||||||
|
|
||||||
| Event Name | Description | Properties | Trigger |
|
| Event Name | Description | Properties | Trigger |
|
||||||
|------------|-------------|------------|---------|
|
|------------|-------------|------------|---------|
|
||||||
| signup_completed | User completes signup | method, plan | Success page |
|
| quote_request_submitted | User completes quote form | service_type, page | Form success |
|
||||||
|
| phone_call_initiated | User clicks call button | service_type, source | Call button click |
|
||||||
|
| service_booked | Quote converts to service | service_type, value | CRM integration |
|
||||||
|
|
||||||
## Custom Dimensions
|
## UTM Strategy
|
||||||
|
|
||||||
| Name | Scope | Parameter |
|
| Campaign | Source | Medium | Campaign Name |
|
||||||
|------|-------|-----------|
|
|----------|--------|--------|---------------|
|
||||||
| user_type | User | user_type |
|
| Google LSA | google_lsa | cpc | ac_repair_emergency |
|
||||||
|
| Facebook | facebook | social | summer_ac_campaign |
|
||||||
## Conversions
|
|
||||||
|
|
||||||
| Conversion | Event | Counting |
|
|
||||||
|------------|-------|----------|
|
|
||||||
| Signup | signup_completed | Once per session |
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What tools are you using (GA4, Mixpanel, etc.)?
|
1. What are your top 3-5 conversion goals? (Quote requests, phone calls, bookings)
|
||||||
2. What key actions do you want to track?
|
2. Do you currently track phone calls? How?
|
||||||
3. What decisions will this data inform?
|
3. What tools are you using? (GA4, GTM, CRM, call tracking)
|
||||||
4. Who implements - dev team or marketing?
|
4. Who implements — dev team or marketing?
|
||||||
5. Are there privacy/consent requirements?
|
5. Are there privacy/consent requirements?
|
||||||
6. What's already tracked?
|
6. What decisions will this data inform?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tool Integrations
|
## Compendium Integration
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analytics tools:
|
This skill can be enhanced using **Compendium** industry benchmarking and competitor analysis.
|
||||||
|
|
||||||
| Tool | Best For | MCP | Guide |
|
**Relevant Compendium capabilities:**
|
||||||
|------|----------|:---:|-------|
|
- **Fetch**: Pull industry conversion rate benchmarks for HVAC companies
|
||||||
| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) |
|
- **Analyze**: Compare your tracking metrics against industry standards
|
||||||
| **Mixpanel** | Product analytics, event tracking | - | [mixpanel.md](../../tools/integrations/mixpanel.md) |
|
|
||||||
| **Amplitude** | Product analytics, cohort analysis | - | [amplitude.md](../../tools/integrations/amplitude.md) |
|
**When to use Compendium:**
|
||||||
| **PostHog** | Open-source analytics, session replay | - | [posthog.md](../../tools/integrations/posthog.md) |
|
- Benchmarking your quote request rate against competitors
|
||||||
| **Segment** | Customer data platform, routing | - | [segment.md](../../tools/integrations/segment.md) |
|
- Understanding typical HVAC call-to-booking conversion rates
|
||||||
|
- Identifying industry benchmarks for customer acquisition cost
|
||||||
|
|
||||||
|
See [COMPENDIUM_INTEGRATION.md](../COMPENDIUM_INTEGRATION.md) for detailed workflows.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **ab-test-setup**: For experiment tracking
|
- **ab-test-setup**: For experiment tracking
|
||||||
- **seo-audit**: For organic traffic analysis
|
|
||||||
- **page-cro**: For conversion optimization (uses this data)
|
- **page-cro**: For conversion optimization (uses this data)
|
||||||
- **revops**: For pipeline metrics, CRM tracking, and revenue attribution
|
- **paid-ads**: For campaign attribution
|
||||||
|
- **hvac-lead-ops**: For pipeline metrics, CRM tracking, and revenue attribution
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me set up analytics tracking for our B2B SaaS product. We use GA4 and GTM. We need to track signups, feature usage, and upgrade events.",
|
"prompt": "Help me set up analytics tracking for our B2B SaaS product. We use GA4 and GTM. We need to track signups, feature usage, and upgrade events.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the 'track for decisions' principle — ask what decisions the tracking will inform. Should use the event naming convention (object_action, lowercase with underscores). Should define essential events for SaaS: signup_completed, trial_started, feature_used, plan_upgraded, etc. Should provide GA4 implementation details with proper event parameters. Should include GTM data layer push examples. Should organize output as a tracking plan with event name, trigger, parameters, and purpose for each event.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the 'track for decisions' principle — ask what decisions the tracking will inform. Should use the event naming convention (object_action, lowercase with underscores). Should define essential events for SaaS: signup_completed, trial_started, feature_used, plan_upgraded, etc. Should provide GA4 implementation details with proper event parameters. Should include GTM data layer push examples. Should organize output as a tracking plan with event name, trigger, parameters, and purpose for each event.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies 'track for decisions' principle",
|
"Applies 'track for decisions' principle",
|
||||||
"Uses object_action naming convention",
|
"Uses object_action naming convention",
|
||||||
"Defines essential SaaS events (signup, feature usage, upgrade)",
|
"Defines essential SaaS events (signup, feature usage, upgrade)",
|
||||||
|
|
|
||||||
|
|
@ -1,424 +0,0 @@
|
||||||
---
|
|
||||||
name: churn-prevention
|
|
||||||
description: "When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or implement retention strategies. Also use when the user mentions 'churn,' 'cancel flow,' 'offboarding,' 'save offer,' 'dunning,' 'failed payment recovery,' 'win-back,' 'retention,' 'exit survey,' 'pause subscription,' 'involuntary churn,' 'people keep canceling,' 'churn rate is too high,' 'how do I keep users,' or 'customers are leaving.' Use this whenever someone is losing subscribers or wants to build systems to prevent it. For post-cancel win-back email sequences, see email-sequence. For in-app upgrade paywalls, see paywall-upgrade-cro."
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Churn Prevention
|
|
||||||
|
|
||||||
You are an expert in SaaS retention and churn prevention. Your goal is to help reduce both voluntary churn (customers choosing to cancel) and involuntary churn (failed payments) through well-designed cancel flows, dynamic save offers, proactive retention, and dunning strategies.
|
|
||||||
|
|
||||||
## Before Starting
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
|
||||||
|
|
||||||
### 1. Current Churn Situation
|
|
||||||
- What's your monthly churn rate? (Voluntary vs. involuntary if known)
|
|
||||||
- How many active subscribers?
|
|
||||||
- What's the average MRR per customer?
|
|
||||||
- Do you have a cancel flow today, or does cancel happen instantly?
|
|
||||||
|
|
||||||
### 2. Billing & Platform
|
|
||||||
- What billing provider? (Stripe, Chargebee, Paddle, Recurly, Braintree)
|
|
||||||
- Monthly, annual, or both billing intervals?
|
|
||||||
- Do you support plan pausing or downgrades?
|
|
||||||
- Any existing retention tooling? (Churnkey, ProsperStack, Raaft)
|
|
||||||
|
|
||||||
### 3. Product & Usage Data
|
|
||||||
- Do you track feature usage per user?
|
|
||||||
- Can you identify engagement drop-offs?
|
|
||||||
- Do you have cancellation reason data from past churns?
|
|
||||||
- What's your activation metric? (What do retained users do that churned users don't?)
|
|
||||||
|
|
||||||
### 4. Constraints
|
|
||||||
- B2B or B2C? (Affects flow design)
|
|
||||||
- Self-serve cancellation required? (Some regulations mandate easy cancel)
|
|
||||||
- Brand tone for offboarding? (Empathetic, direct, playful)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## How This Skill Works
|
|
||||||
|
|
||||||
Churn has two types requiring different strategies:
|
|
||||||
|
|
||||||
| Type | Cause | Solution |
|
|
||||||
|------|-------|----------|
|
|
||||||
| **Voluntary** | Customer chooses to cancel | Cancel flows, save offers, exit surveys |
|
|
||||||
| **Involuntary** | Payment fails | Dunning emails, smart retries, card updaters |
|
|
||||||
|
|
||||||
Voluntary churn is typically 50-70% of total churn. Involuntary churn is 30-50% but is often easier to fix.
|
|
||||||
|
|
||||||
This skill supports three modes:
|
|
||||||
|
|
||||||
1. **Build a cancel flow** — Design from scratch with survey, save offers, and confirmation
|
|
||||||
2. **Optimize an existing flow** — Analyze cancel data and improve save rates
|
|
||||||
3. **Set up dunning** — Failed payment recovery with retries and email sequences
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cancel Flow Design
|
|
||||||
|
|
||||||
### The Cancel Flow Structure
|
|
||||||
|
|
||||||
Every cancel flow follows this sequence:
|
|
||||||
|
|
||||||
```
|
|
||||||
Trigger → Survey → Dynamic Offer → Confirmation → Post-Cancel
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 1: Trigger**
|
|
||||||
Customer clicks "Cancel subscription" in account settings.
|
|
||||||
|
|
||||||
**Step 2: Exit Survey**
|
|
||||||
Ask why they're cancelling. This determines which save offer to show.
|
|
||||||
|
|
||||||
**Step 3: Dynamic Save Offer**
|
|
||||||
Present a targeted offer based on their reason (discount, pause, downgrade, etc.)
|
|
||||||
|
|
||||||
**Step 4: Confirmation**
|
|
||||||
If they still want to cancel, confirm clearly with end-of-billing-period messaging.
|
|
||||||
|
|
||||||
**Step 5: Post-Cancel**
|
|
||||||
Set expectations, offer easy reactivation path, trigger win-back sequence.
|
|
||||||
|
|
||||||
### Exit Survey Design
|
|
||||||
|
|
||||||
The exit survey is the foundation. Good reason categories:
|
|
||||||
|
|
||||||
| Reason | What It Tells You |
|
|
||||||
|--------|-------------------|
|
|
||||||
| Too expensive | Price sensitivity, may respond to discount or downgrade |
|
|
||||||
| Not using it enough | Low engagement, may respond to pause or onboarding help |
|
|
||||||
| Missing a feature | Product gap, show roadmap or workaround |
|
|
||||||
| Switching to competitor | Competitive pressure, understand what they offer |
|
|
||||||
| Technical issues / bugs | Product quality, escalate to support |
|
|
||||||
| Temporary / seasonal need | Usage pattern, offer pause |
|
|
||||||
| Business closed / changed | Unavoidable, learn and let go gracefully |
|
|
||||||
| Other | Catch-all, include free text field |
|
|
||||||
|
|
||||||
**Survey best practices:**
|
|
||||||
- 1 question, single-select with optional free text
|
|
||||||
- 5-8 reason options max (avoid decision fatigue)
|
|
||||||
- Put most common reasons first (review data quarterly)
|
|
||||||
- Don't make it feel like a guilt trip
|
|
||||||
- "Help us improve" framing works better than "Why are you leaving?"
|
|
||||||
|
|
||||||
### Dynamic Save Offers
|
|
||||||
|
|
||||||
The key insight: **match the offer to the reason.** A discount won't save someone who isn't using the product. A feature roadmap won't save someone who can't afford it.
|
|
||||||
|
|
||||||
**Offer-to-reason mapping:**
|
|
||||||
|
|
||||||
| Cancel Reason | Primary Offer | Fallback Offer |
|
|
||||||
|---------------|---------------|----------------|
|
|
||||||
| Too expensive | Discount (20-30% for 2-3 months) | Downgrade to lower plan |
|
|
||||||
| Not using it enough | Pause (1-3 months) | Free onboarding session |
|
|
||||||
| Missing feature | Roadmap preview + timeline | Workaround guide |
|
|
||||||
| Switching to competitor | Competitive comparison + discount | Feedback session |
|
|
||||||
| Technical issues | Escalate to support immediately | Credit + priority fix |
|
|
||||||
| Temporary / seasonal | Pause subscription | Downgrade temporarily |
|
|
||||||
| Business closed | Skip offer (respect the situation) | — |
|
|
||||||
|
|
||||||
### Save Offer Types
|
|
||||||
|
|
||||||
**Discount**
|
|
||||||
- 20-30% off for 2-3 months is the sweet spot
|
|
||||||
- Avoid 50%+ discounts (trains customers to cancel for deals)
|
|
||||||
- Time-limit the offer ("This offer expires when you leave this page")
|
|
||||||
- Show the dollar amount saved, not just the percentage
|
|
||||||
|
|
||||||
**Pause subscription**
|
|
||||||
- 1-3 month pause maximum (longer pauses rarely reactivate)
|
|
||||||
- 60-80% of pausers eventually return to active
|
|
||||||
- Auto-reactivation with advance notice email
|
|
||||||
- Keep their data and settings intact
|
|
||||||
|
|
||||||
**Plan downgrade**
|
|
||||||
- Offer a lower tier instead of full cancellation
|
|
||||||
- Show what they keep vs. what they lose
|
|
||||||
- Position as "right-size your plan" not "downgrade"
|
|
||||||
- Easy path back up when ready
|
|
||||||
|
|
||||||
**Feature unlock / extension**
|
|
||||||
- Unlock a premium feature they haven't tried
|
|
||||||
- Extend trial of a higher tier
|
|
||||||
- Works best for "not getting enough value" reasons
|
|
||||||
|
|
||||||
**Personal outreach**
|
|
||||||
- For high-value accounts (top 10-20% by MRR)
|
|
||||||
- Route to customer success for a call
|
|
||||||
- Personal email from founder for smaller companies
|
|
||||||
|
|
||||||
### Cancel Flow UI Patterns
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────┐
|
|
||||||
│ We're sorry to see you go │
|
|
||||||
│ │
|
|
||||||
│ What's the main reason you're │
|
|
||||||
│ cancelling? │
|
|
||||||
│ │
|
|
||||||
│ ○ Too expensive │
|
|
||||||
│ ○ Not using it enough │
|
|
||||||
│ ○ Missing a feature I need │
|
|
||||||
│ ○ Switching to another tool │
|
|
||||||
│ ○ Technical issues │
|
|
||||||
│ ○ Temporary / don't need right now │
|
|
||||||
│ ○ Other: [____________] │
|
|
||||||
│ │
|
|
||||||
│ [Continue] │
|
|
||||||
│ [Never mind, keep my subscription] │
|
|
||||||
└─────────────────────────────────────┘
|
|
||||||
↓ (selects "Too expensive")
|
|
||||||
┌─────────────────────────────────────┐
|
|
||||||
│ What if we could help? │
|
|
||||||
│ │
|
|
||||||
│ We'd love to keep you. Here's a │
|
|
||||||
│ special offer: │
|
|
||||||
│ │
|
|
||||||
│ ┌───────────────────────────────┐ │
|
|
||||||
│ │ 25% off for the next 3 months│ │
|
|
||||||
│ │ Save $XX/month │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ [Accept Offer] │ │
|
|
||||||
│ └───────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ Or switch to [Basic Plan] at │
|
|
||||||
│ $X/month → │
|
|
||||||
│ │
|
|
||||||
│ [No thanks, continue cancelling] │
|
|
||||||
└─────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**UI principles:**
|
|
||||||
- Keep the "continue cancelling" option visible (no dark patterns)
|
|
||||||
- One primary offer + one fallback, not a wall of options
|
|
||||||
- Show specific dollar savings, not abstract percentages
|
|
||||||
- Use the customer's name and account data when possible
|
|
||||||
- Mobile-friendly (many cancellations happen on mobile)
|
|
||||||
|
|
||||||
For detailed cancel flow patterns by industry and billing provider, see [references/cancel-flow-patterns.md](references/cancel-flow-patterns.md).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Churn Prediction & Proactive Retention
|
|
||||||
|
|
||||||
The best save happens before the customer ever clicks "Cancel."
|
|
||||||
|
|
||||||
### Risk Signals
|
|
||||||
|
|
||||||
Track these leading indicators of churn:
|
|
||||||
|
|
||||||
| Signal | Risk Level | Timeframe |
|
|
||||||
|--------|-----------|-----------|
|
|
||||||
| Login frequency drops 50%+ | High | 2-4 weeks before cancel |
|
|
||||||
| Key feature usage stops | High | 1-3 weeks before cancel |
|
|
||||||
| Support tickets spike then stop | High | 1-2 weeks before cancel |
|
|
||||||
| Email open rates decline | Medium | 2-6 weeks before cancel |
|
|
||||||
| Billing page visits increase | High | Days before cancel |
|
|
||||||
| Team seats removed | High | 1-2 weeks before cancel |
|
|
||||||
| Data export initiated | Critical | Days before cancel |
|
|
||||||
| NPS score drops below 6 | Medium | 1-3 months before cancel |
|
|
||||||
|
|
||||||
### Health Score Model
|
|
||||||
|
|
||||||
Build a simple health score (0-100) from weighted signals:
|
|
||||||
|
|
||||||
```
|
|
||||||
Health Score = (
|
|
||||||
Login frequency score × 0.30 +
|
|
||||||
Feature usage score × 0.25 +
|
|
||||||
Support sentiment × 0.15 +
|
|
||||||
Billing health × 0.15 +
|
|
||||||
Engagement score × 0.15
|
|
||||||
)
|
|
||||||
```
|
|
||||||
|
|
||||||
| Score | Status | Action |
|
|
||||||
|-------|--------|--------|
|
|
||||||
| 80-100 | Healthy | Upsell opportunities |
|
|
||||||
| 60-79 | Needs attention | Proactive check-in |
|
|
||||||
| 40-59 | At risk | Intervention campaign |
|
|
||||||
| 0-39 | Critical | Personal outreach |
|
|
||||||
|
|
||||||
### Proactive Interventions
|
|
||||||
|
|
||||||
**Before they think about cancelling:**
|
|
||||||
|
|
||||||
| Trigger | Intervention |
|
|
||||||
|---------|-------------|
|
|
||||||
| Usage drop >50% for 2 weeks | "We noticed you haven't used [feature]. Need help?" email |
|
|
||||||
| Approaching plan limit | Upgrade nudge (not a wall — paywall-upgrade-cro handles this) |
|
|
||||||
| No login for 14 days | Re-engagement email with recent product updates |
|
|
||||||
| NPS detractor (0-6) | Personal follow-up within 24 hours |
|
|
||||||
| Support ticket unresolved >48h | Escalation + proactive status update |
|
|
||||||
| Annual renewal in 30 days | Value recap email + renewal confirmation |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Involuntary Churn: Payment Recovery
|
|
||||||
|
|
||||||
Failed payments cause 30-50% of all churn but are the most recoverable.
|
|
||||||
|
|
||||||
### The Dunning Stack
|
|
||||||
|
|
||||||
```
|
|
||||||
Pre-dunning → Smart retry → Dunning emails → Grace period → Hard cancel
|
|
||||||
```
|
|
||||||
|
|
||||||
### Pre-Dunning (Prevent Failures)
|
|
||||||
|
|
||||||
- **Card expiry alerts**: Email 30, 15, and 7 days before card expires
|
|
||||||
- **Backup payment method**: Prompt for a second payment method at signup
|
|
||||||
- **Card updater services**: Visa/Mastercard auto-update programs (reduces hard declines 30-50%)
|
|
||||||
- **Pre-billing notification**: Email 3-5 days before charge for annual plans
|
|
||||||
|
|
||||||
### Smart Retry Logic
|
|
||||||
|
|
||||||
Not all failures are the same. Retry strategy by decline type:
|
|
||||||
|
|
||||||
| Decline Type | Examples | Retry Strategy |
|
|
||||||
|-------------|----------|----------------|
|
|
||||||
| Soft decline (temporary) | Insufficient funds, processor timeout | Retry 3-5 times over 7-10 days |
|
|
||||||
| Hard decline (permanent) | Card stolen, account closed | Don't retry — ask for new card |
|
|
||||||
| Authentication required | 3D Secure, SCA | Send customer to update payment |
|
|
||||||
|
|
||||||
**Retry timing best practices:**
|
|
||||||
- Retry 1: 24 hours after failure
|
|
||||||
- Retry 2: 3 days after failure
|
|
||||||
- Retry 3: 5 days after failure
|
|
||||||
- Retry 4: 7 days after failure (with dunning email escalation)
|
|
||||||
- After 4 retries: Hard cancel with reactivation path
|
|
||||||
|
|
||||||
**Smart retry tip:** Retry on the day of the month the payment originally succeeded (if Day 1 worked before, retry on Day 1). Stripe Smart Retries handles this automatically.
|
|
||||||
|
|
||||||
### Dunning Email Sequence
|
|
||||||
|
|
||||||
| Email | Timing | Tone | Content |
|
|
||||||
|-------|--------|------|---------|
|
|
||||||
| 1 | Day 0 (failure) | Friendly alert | "Your payment didn't go through. Update your card." |
|
|
||||||
| 2 | Day 3 | Helpful reminder | "Quick reminder — update your payment to keep access." |
|
|
||||||
| 3 | Day 7 | Urgency | "Your account will be paused in 3 days. Update now." |
|
|
||||||
| 4 | Day 10 | Final warning | "Last chance to keep your account active." |
|
|
||||||
|
|
||||||
**Dunning email best practices:**
|
|
||||||
- Direct link to payment update page (no login required if possible)
|
|
||||||
- Show what they'll lose (their data, their team's access)
|
|
||||||
- Don't blame ("your payment failed" not "you failed to pay")
|
|
||||||
- Include support contact for help
|
|
||||||
- Plain text performs better than designed emails for dunning
|
|
||||||
|
|
||||||
### Recovery Benchmarks
|
|
||||||
|
|
||||||
| Metric | Poor | Average | Good |
|
|
||||||
|--------|------|---------|------|
|
|
||||||
| Soft decline recovery | <40% | 50-60% | 70%+ |
|
|
||||||
| Hard decline recovery | <10% | 20-30% | 40%+ |
|
|
||||||
| Overall payment recovery | <30% | 40-50% | 60%+ |
|
|
||||||
| Pre-dunning prevention | None | 10-15% | 20-30% |
|
|
||||||
|
|
||||||
For the complete dunning playbook with provider-specific setup, see [references/dunning-playbook.md](references/dunning-playbook.md).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Metrics & Measurement
|
|
||||||
|
|
||||||
### Key Churn Metrics
|
|
||||||
|
|
||||||
| Metric | Formula | Target |
|
|
||||||
|--------|---------|--------|
|
|
||||||
| Monthly churn rate | Churned customers / Start-of-month customers | <5% B2C, <2% B2B |
|
|
||||||
| Revenue churn (net) | (Lost MRR - Expansion MRR) / Start MRR | Negative (net expansion) |
|
|
||||||
| Cancel flow save rate | Saved / Total cancel sessions | 25-35% |
|
|
||||||
| Offer acceptance rate | Accepted offers / Shown offers | 15-25% |
|
|
||||||
| Pause reactivation rate | Reactivated / Total paused | 60-80% |
|
|
||||||
| Dunning recovery rate | Recovered / Total failed payments | 50-60% |
|
|
||||||
| Time to cancel | Days from first churn signal to cancel | Track trend |
|
|
||||||
|
|
||||||
### Cohort Analysis
|
|
||||||
|
|
||||||
Segment churn by:
|
|
||||||
- **Acquisition channel** — Which channels bring stickier customers?
|
|
||||||
- **Plan type** — Which plans churn most?
|
|
||||||
- **Tenure** — When do most cancellations happen? (30, 60, 90 days?)
|
|
||||||
- **Cancel reason** — Which reasons are growing?
|
|
||||||
- **Save offer type** — Which offers work best for which segments?
|
|
||||||
|
|
||||||
### Cancel Flow A/B Tests
|
|
||||||
|
|
||||||
Test one variable at a time:
|
|
||||||
|
|
||||||
| Test | Hypothesis | Metric |
|
|
||||||
|------|-----------|--------|
|
|
||||||
| Discount % (20% vs 30%) | Higher discount saves more | Save rate, LTV impact |
|
|
||||||
| Pause duration (1 vs 3 months) | Longer pause increases return rate | Reactivation rate |
|
|
||||||
| Survey placement (before vs after offer) | Survey-first personalizes offers | Save rate |
|
|
||||||
| Offer presentation (modal vs full page) | Full page gets more attention | Save rate |
|
|
||||||
| Copy tone (empathetic vs direct) | Empathetic reduces friction | Save rate |
|
|
||||||
|
|
||||||
**How to run cancel flow experiments:** Use the **ab-test-setup** skill to design statistically rigorous tests. PostHog is a good fit for cancel flow experiments — its feature flags can split users into different flows server-side, and its funnel analytics track each step of the cancel flow (survey → offer → accept/decline → confirm). See the [PostHog integration guide](../../tools/integrations/posthog.md) for setup.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Common Mistakes
|
|
||||||
|
|
||||||
- **No cancel flow at all** — Instant cancel leaves money on the table. Even a simple survey + one offer saves 10-15%
|
|
||||||
- **Making cancellation hard to find** — Hidden cancel buttons breed resentment and bad reviews. Many jurisdictions require easy cancellation (FTC Click-to-Cancel rule)
|
|
||||||
- **Same offer for every reason** — A blanket discount doesn't address "missing feature" or "not using it"
|
|
||||||
- **Discounts too deep** — 50%+ discounts train customers to cancel-and-return for deals
|
|
||||||
- **Ignoring involuntary churn** — Often 30-50% of total churn and the easiest to fix
|
|
||||||
- **No dunning emails** — Letting payment failures silently cancel accounts
|
|
||||||
- **Guilt-trip copy** — "Are you sure you want to abandon us?" damages brand trust
|
|
||||||
- **Not tracking save offer LTV** — A "saved" customer who churns 30 days later wasn't really saved
|
|
||||||
- **Pausing too long** — Pauses beyond 3 months rarely reactivate. Set limits.
|
|
||||||
- **No post-cancel path** — Make reactivation easy and trigger win-back emails, because some churned users will want to come back
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tool Integrations
|
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md).
|
|
||||||
|
|
||||||
### Retention Platforms
|
|
||||||
|
|
||||||
| Tool | Best For | Key Feature |
|
|
||||||
|------|----------|-------------|
|
|
||||||
| **Churnkey** | Full cancel flow + dunning | AI-powered adaptive offers, 34% avg save rate |
|
|
||||||
| **ProsperStack** | Cancel flows with analytics | Advanced rules engine, Stripe/Chargebee integration |
|
|
||||||
| **Raaft** | Simple cancel flow builder | Easy setup, good for early-stage |
|
|
||||||
| **Chargebee Retention** | Chargebee customers | Native integration, was Brightback |
|
|
||||||
|
|
||||||
### Billing Providers (Dunning)
|
|
||||||
|
|
||||||
| Provider | Smart Retries | Dunning Emails | Card Updater |
|
|
||||||
|----------|:------------:|:--------------:|:------------:|
|
|
||||||
| **Stripe** | Built-in (Smart Retries) | Built-in | Automatic |
|
|
||||||
| **Chargebee** | Built-in | Built-in | Via gateway |
|
|
||||||
| **Paddle** | Built-in | Built-in | Managed |
|
|
||||||
| **Recurly** | Built-in | Built-in | Built-in |
|
|
||||||
| **Braintree** | Manual config | Manual | Via gateway |
|
|
||||||
|
|
||||||
### Related CLI Tools
|
|
||||||
|
|
||||||
| Tool | Use For |
|
|
||||||
|------|---------|
|
|
||||||
| `stripe` | Subscription management, dunning config, payment retries |
|
|
||||||
| `customer-io` | Dunning email sequences, retention campaigns |
|
|
||||||
| `posthog` | Cancel flow A/B tests via feature flags, funnel analytics |
|
|
||||||
| `mixpanel` / `ga4` | Usage tracking, churn signal analysis |
|
|
||||||
| `segment` | Event routing for health scoring |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **email-sequence**: For win-back email sequences after cancellation
|
|
||||||
- **paywall-upgrade-cro**: For in-app upgrade moments and trial expiration
|
|
||||||
- **pricing-strategy**: For plan structure and annual discount strategy
|
|
||||||
- **onboarding-cro**: For activation to prevent early churn
|
|
||||||
- **analytics-tracking**: For setting up churn signal events
|
|
||||||
- **ab-test-setup**: For testing cancel flow variations with statistical rigor
|
|
||||||
|
|
@ -1,93 +0,0 @@
|
||||||
{
|
|
||||||
"skill_name": "churn-prevention",
|
|
||||||
"evals": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"prompt": "Our SaaS product has a 7% monthly churn rate and we need to bring it down. We're a $49/month project management tool with about 2,000 paying customers. Can you help us design a churn prevention strategy?",
|
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should address both voluntary and involuntary churn. Should design a cancel flow following the framework: trigger → exit survey → dynamic save offer → confirmation → post-cancel nurture. Should include the 7 exit survey categories and recommend dynamic save offers mapped to each cancellation reason. Should address dunning for involuntary churn (pre-dunning, smart retry, email sequence, grace period). Should recommend a health score model. Should provide prioritized implementation plan.",
|
|
||||||
"assertions": [
|
|
||||||
"Checks for product-marketing-context.md",
|
|
||||||
"Addresses both voluntary and involuntary churn",
|
|
||||||
"Designs cancel flow with proper stages",
|
|
||||||
"Includes exit survey with multiple categories",
|
|
||||||
"Maps save offers to cancellation reasons",
|
|
||||||
"Addresses dunning stack for payment recovery",
|
|
||||||
"Recommends health score model",
|
|
||||||
"Provides prioritized implementation plan"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"prompt": "We keep losing customers because their credit cards expire. About 15% of our churn is from failed payments. How do we fix this?",
|
|
||||||
"expected_output": "Should identify this as involuntary churn / payment recovery. Should apply the dunning stack framework: pre-dunning (card expiration reminders before failure), smart retry (retry logic based on failure reason), dunning email sequence (escalating urgency), grace period, and eventual cancellation. Should provide specific timing for each stage. Should recommend payment recovery tools and strategies (card updater services, backup payment methods). Should include recovery rate benchmarks.",
|
|
||||||
"assertions": [
|
|
||||||
"Identifies as involuntary churn / payment recovery",
|
|
||||||
"Applies dunning stack framework",
|
|
||||||
"Includes pre-dunning card expiration reminders",
|
|
||||||
"Includes smart retry logic",
|
|
||||||
"Provides dunning email sequence with escalating urgency",
|
|
||||||
"Recommends grace period before cancellation",
|
|
||||||
"Mentions card updater services or backup payment methods",
|
|
||||||
"Includes recovery benchmarks"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 3,
|
|
||||||
"prompt": "what should we show users when they click the cancel button? right now they just go straight to cancellation with no attempt to save them",
|
|
||||||
"expected_output": "Should trigger on casual phrasing. Should design the cancel flow: cancel button → exit survey → dynamic save offer → confirmation → post-cancel. Should detail the exit survey categories (too expensive, missing feature, switched to competitor, not using enough, technical issues, bad support, other). Should provide dynamic save offers matched to each reason (e.g., too expensive → discount offer, missing feature → roadmap update, not using enough → onboarding help). Should include copy recommendations for each screen. Should warn against dark patterns (making it impossible to cancel).",
|
|
||||||
"assertions": [
|
|
||||||
"Triggers on casual phrasing",
|
|
||||||
"Designs multi-step cancel flow",
|
|
||||||
"Includes exit survey with 7 categories",
|
|
||||||
"Provides dynamic save offers mapped to reasons",
|
|
||||||
"Includes copy recommendations",
|
|
||||||
"Warns against dark patterns",
|
|
||||||
"Includes confirmation and post-cancel steps"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 4,
|
|
||||||
"prompt": "How do we identify which customers are at risk of churning before they actually cancel? We want to be proactive.",
|
|
||||||
"expected_output": "Should apply the health score model framework. Should define health score components: product usage signals (login frequency, feature adoption, key action completion), engagement signals (support tickets, NPS responses, email engagement), and account signals (contract type, company growth, stakeholder changes). Should recommend scoring methodology (0-100 scale). Should define risk tiers and recommended interventions for each tier. Should suggest data sources and implementation approach.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies health score model framework",
|
|
||||||
"Defines usage-based health signals",
|
|
||||||
"Defines engagement-based health signals",
|
|
||||||
"Defines account-based health signals",
|
|
||||||
"Recommends scoring methodology",
|
|
||||||
"Defines risk tiers with interventions",
|
|
||||||
"Suggests data sources and implementation"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 5,
|
|
||||||
"prompt": "Our exit survey shows that 40% of cancellations say 'too expensive' as the reason. What save offers should we try?",
|
|
||||||
"expected_output": "Should reference the dynamic save offers mapped to the 'too expensive' reason. Should suggest multiple offer types: temporary discount, downgrade to cheaper plan, annual billing discount, pause instead of cancel, extended trial of current plan. Should recommend testing different offers to find what works best. Should also dig deeper — 'too expensive' often masks other issues (not seeing value, not using enough features). Should suggest follow-up questions in the exit survey to get more specific.",
|
|
||||||
"assertions": [
|
|
||||||
"References save offers for 'too expensive' reason",
|
|
||||||
"Suggests multiple offer types (discount, downgrade, pause)",
|
|
||||||
"Recommends testing different offers",
|
|
||||||
"Notes that 'too expensive' often masks other issues",
|
|
||||||
"Suggests deeper follow-up questions",
|
|
||||||
"Provides specific save offer copy or structure"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 6,
|
|
||||||
"prompt": "We want to set up a win-back email sequence for customers who already cancelled. Can you help write those emails?",
|
|
||||||
"expected_output": "Should recognize this overlaps with email sequence work. Should defer to or cross-reference the email-sequence skill for writing the actual email sequence. May provide churn-specific context (timing post-cancel, re-engagement hooks, win-back offer strategy) but should make clear that email-sequence is the right skill for designing and writing the full email sequence.",
|
|
||||||
"assertions": [
|
|
||||||
"Recognizes overlap with email sequence work",
|
|
||||||
"References or defers to email-sequence skill",
|
|
||||||
"May provide churn-specific context for the sequence",
|
|
||||||
"Does not attempt to write a full email sequence"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
@ -1,316 +0,0 @@
|
||||||
# Cancel Flow Patterns
|
|
||||||
|
|
||||||
Detailed cancel flow patterns by business type, billing provider, and industry.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cancel Flow by Business Type
|
|
||||||
|
|
||||||
### B2C / Self-Serve SaaS
|
|
||||||
|
|
||||||
High volume, low touch. The flow must work without human intervention.
|
|
||||||
|
|
||||||
**Flow structure:**
|
|
||||||
```
|
|
||||||
Cancel button → Exit survey (1 question) → Dynamic offer → Confirm → Post-cancel
|
|
||||||
```
|
|
||||||
|
|
||||||
**Characteristics:**
|
|
||||||
- Fully automated, no human in the loop
|
|
||||||
- Quick — 2-3 screens maximum
|
|
||||||
- One offer + one fallback, not a menu of options
|
|
||||||
- Mobile-optimized (significant cancellations on mobile)
|
|
||||||
- Clear "continue cancelling" at every step
|
|
||||||
|
|
||||||
**Typical save rate:** 20-30%
|
|
||||||
|
|
||||||
**Example flow for a $29/mo productivity app:**
|
|
||||||
1. "What's the main reason?" → 6 options
|
|
||||||
2. Selected "Too expensive" → "Get 25% off for 3 months (save $21.75)"
|
|
||||||
3. Declined → "Or switch to our Starter plan at $12/mo"
|
|
||||||
4. Declined → "We're sorry to see you go. Your access continues until [date]."
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### B2B / Team Plans
|
|
||||||
|
|
||||||
Lower volume, higher stakes. Personal outreach is worth the cost.
|
|
||||||
|
|
||||||
**Flow structure:**
|
|
||||||
```
|
|
||||||
Cancel button → Exit survey → Offer (or route to CS) → Confirm → Post-cancel
|
|
||||||
```
|
|
||||||
|
|
||||||
**Characteristics:**
|
|
||||||
- Route accounts above MRR threshold to customer success
|
|
||||||
- Show team impact ("Your 8 team members will lose access")
|
|
||||||
- Offer admin-to-admin call for enterprise accounts
|
|
||||||
- Longer consideration — allow "schedule a call" as a save option
|
|
||||||
- Require admin/owner role to cancel (not any team member)
|
|
||||||
|
|
||||||
**Typical save rate:** 30-45% (higher because of personal touch)
|
|
||||||
|
|
||||||
**MRR-based routing:**
|
|
||||||
|
|
||||||
| Account MRR | Cancel Flow |
|
|
||||||
|-------------|-------------|
|
|
||||||
| <$100/mo | Automated flow with offers |
|
|
||||||
| $100-$500/mo | Automated + flag for CS follow-up |
|
|
||||||
| $500-$2,000/mo | Route to CS before cancel completes |
|
|
||||||
| $2,000+/mo | Block self-serve cancel, require CS call |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Freemium / Free-to-Paid
|
|
||||||
|
|
||||||
Users cancelling paid to return to free tier. Different psychology — they're not leaving, they're downgrading.
|
|
||||||
|
|
||||||
**Flow structure:**
|
|
||||||
```
|
|
||||||
Cancel button → "Switch to Free?" prompt → Exit survey (if still cancelling) → Offer → Confirm
|
|
||||||
```
|
|
||||||
|
|
||||||
**Characteristics:**
|
|
||||||
- Lead with the free tier as the first option (not a save offer)
|
|
||||||
- Show what they keep on free vs. what they lose
|
|
||||||
- The "save" is keeping them on free, not losing them entirely
|
|
||||||
- Track free-tier users for future re-upgrade campaigns
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Cancel Flow by Billing Interval
|
|
||||||
|
|
||||||
### Monthly Subscribers
|
|
||||||
|
|
||||||
- More price-sensitive, shorter commitment
|
|
||||||
- Discount offers work well (20-30% for 2-3 months)
|
|
||||||
- Pause is effective (1-2 months)
|
|
||||||
- Suggest annual plan at a discount as an alternative
|
|
||||||
|
|
||||||
**Offer priority:**
|
|
||||||
1. Discount (if reason = price)
|
|
||||||
2. Pause (if reason = not using / temporary)
|
|
||||||
3. Annual plan switch (if engaged but price-sensitive)
|
|
||||||
|
|
||||||
### Annual Subscribers
|
|
||||||
|
|
||||||
- Higher commitment, often cancelling for stronger reasons
|
|
||||||
- Prorate refund expectations matter
|
|
||||||
- Longer save window (they've already paid)
|
|
||||||
- Personal outreach more justified (higher LTV at stake)
|
|
||||||
|
|
||||||
**Offer priority:**
|
|
||||||
1. Pause remainder of term (if temporary)
|
|
||||||
2. Plan adjustment + credit for next renewal
|
|
||||||
3. Personal outreach from CS
|
|
||||||
4. Partial refund + downgrade (better than full refund + cancel)
|
|
||||||
|
|
||||||
**Refund handling:**
|
|
||||||
- Offer prorated refund if significant time remaining
|
|
||||||
- "Pause until renewal" if less than 3 months left
|
|
||||||
- Be generous — bad refund experiences create vocal detractors
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Save Offer Patterns
|
|
||||||
|
|
||||||
### The Discount Ladder
|
|
||||||
|
|
||||||
Don't lead with your biggest discount. Escalate:
|
|
||||||
|
|
||||||
```
|
|
||||||
Cancel click → 15% off → Still cancelling → 25% off → Still cancelling → Let them go
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rules:**
|
|
||||||
- Maximum 2 discount offers per cancel session
|
|
||||||
- Never exceed 30% (higher trains cancel-for-discount behavior)
|
|
||||||
- Time-limit discounts (2-3 months, then full price resumes)
|
|
||||||
- Track discount accepters — if they cancel again at full price, don't re-offer
|
|
||||||
|
|
||||||
### The Pause Playbook
|
|
||||||
|
|
||||||
Pause is often better than a discount because it doesn't devalue your product.
|
|
||||||
|
|
||||||
**Implementation:**
|
|
||||||
|
|
||||||
| Setting | Recommendation |
|
|
||||||
|---------|---------------|
|
|
||||||
| Pause duration options | 1 month, 2 months, 3 months |
|
|
||||||
| Default selection | 1 month (shortest) |
|
|
||||||
| Maximum pause | 3 months (longer pauses rarely return) |
|
|
||||||
| During pause | Keep data, remove access |
|
|
||||||
| Reactivation | Auto-reactivate with 7-day advance email |
|
|
||||||
| Repeat pauses | Allow 1 pause per 12-month period |
|
|
||||||
|
|
||||||
**Pause reactivation sequence:**
|
|
||||||
- Day -7: "Your pause ends in 7 days. We've been busy — here's what's new."
|
|
||||||
- Day -1: "Welcome back tomorrow! Here's what's waiting for you."
|
|
||||||
- Day 0: "You're back! Here's a quick tour of what's new."
|
|
||||||
|
|
||||||
### The Downgrade Path
|
|
||||||
|
|
||||||
For multi-plan products, downgrade is the strongest save:
|
|
||||||
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────────┐
|
|
||||||
│ Before you go, what about right-sizing │
|
|
||||||
│ your plan? │
|
|
||||||
│ │
|
|
||||||
│ Current: Pro ($49/mo) │
|
|
||||||
│ │
|
|
||||||
│ ┌─────────────────────────────────┐ │
|
|
||||||
│ │ Switch to Starter ($19/mo) │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ ✓ Keep: Projects, integrations │ │
|
|
||||||
│ │ ✗ Lose: Advanced analytics, │ │
|
|
||||||
│ │ team features │ │
|
|
||||||
│ │ │ │
|
|
||||||
│ │ [Switch to Starter] │ │
|
|
||||||
│ └─────────────────────────────────┘ │
|
|
||||||
│ │
|
|
||||||
│ [No thanks, continue cancelling] │
|
|
||||||
└─────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**Downgrade best practices:**
|
|
||||||
- Show exactly what they keep and what they lose
|
|
||||||
- Use checkmarks and X marks for scanability
|
|
||||||
- Preserve their data even on the lower plan
|
|
||||||
- If they downgrade, don't show upgrade prompts for at least 30 days
|
|
||||||
|
|
||||||
### The Competitor Switch Handler
|
|
||||||
|
|
||||||
When the cancel reason is "switching to competitor":
|
|
||||||
|
|
||||||
1. **Ask which competitor** (optional, don't force it)
|
|
||||||
2. **Show a comparison** if you have one (see competitor-alternatives skill)
|
|
||||||
3. **Offer a migration credit** ("We'll match their price for 3 months")
|
|
||||||
4. **Request a feedback call** ("15 minutes to understand what we're missing")
|
|
||||||
|
|
||||||
This data is gold for product and marketing teams.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Post-Cancel Experience
|
|
||||||
|
|
||||||
What happens after cancel matters for:
|
|
||||||
- Win-back potential
|
|
||||||
- Word of mouth
|
|
||||||
- Review sentiment
|
|
||||||
|
|
||||||
### Confirmation Page
|
|
||||||
|
|
||||||
```
|
|
||||||
Your subscription has been cancelled.
|
|
||||||
|
|
||||||
What happens next:
|
|
||||||
• Your access continues until [billing period end date]
|
|
||||||
• Your data will be preserved for 90 days
|
|
||||||
• You can reactivate anytime from your account settings
|
|
||||||
|
|
||||||
[Reactivate My Account]
|
|
||||||
|
|
||||||
We'd love to have you back. We'll keep improving based on feedback
|
|
||||||
from customers like you.
|
|
||||||
```
|
|
||||||
|
|
||||||
### Post-Cancel Sequence
|
|
||||||
|
|
||||||
| Timing | Action |
|
|
||||||
|--------|--------|
|
|
||||||
| Immediately | Confirmation email with access end date |
|
|
||||||
| Day 1 | (Nothing — don't be desperate) |
|
|
||||||
| Day 7 | NPS/satisfaction survey about overall experience |
|
|
||||||
| Day 30 | "What's new" email with recent improvements |
|
|
||||||
| Day 60 | Address their specific cancel reason if resolved |
|
|
||||||
| Day 90 | Final win-back with special offer |
|
|
||||||
|
|
||||||
**For detailed win-back email sequences**: See the email-sequence skill.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Segmentation Rules
|
|
||||||
|
|
||||||
The most effective cancel flows use segmentation to show different offers to different customers.
|
|
||||||
|
|
||||||
### Segmentation Dimensions
|
|
||||||
|
|
||||||
| Dimension | Why It Matters |
|
|
||||||
|-----------|---------------|
|
|
||||||
| Plan / MRR | Higher-value customers get personal outreach |
|
|
||||||
| Tenure | Long-term customers get more generous offers |
|
|
||||||
| Usage level | High-usage customers get different messaging than dormant ones |
|
|
||||||
| Billing interval | Monthly vs. annual need different approaches |
|
|
||||||
| Previous saves | Don't re-offer the same discount to a repeat canceller |
|
|
||||||
| Cancel reason | Drives which offer to show (core mapping) |
|
|
||||||
|
|
||||||
### Segment-Specific Flows
|
|
||||||
|
|
||||||
**New customer (< 30 days):**
|
|
||||||
- They haven't activated. The save is onboarding, not discounts.
|
|
||||||
- Offer: Free onboarding call, setup help, extended trial
|
|
||||||
- Ask: "What were you hoping to accomplish?" (learn what's missing)
|
|
||||||
|
|
||||||
**Engaged customer cancelling on price:**
|
|
||||||
- They love the product but can't justify the cost.
|
|
||||||
- Offer: Discount, annual plan switch, downgrade
|
|
||||||
- High save potential
|
|
||||||
|
|
||||||
**Dormant customer (no login 30+ days):**
|
|
||||||
- They forgot about you. A discount won't bring them back.
|
|
||||||
- Offer: Pause subscription, "what changed?" conversation
|
|
||||||
- Low save potential — focus on learning why
|
|
||||||
|
|
||||||
**Power user switching to competitor:**
|
|
||||||
- They're actively choosing something else.
|
|
||||||
- Offer: Competitive match, feedback call, roadmap preview
|
|
||||||
- Medium save potential — depends on reason
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Implementation Checklist
|
|
||||||
|
|
||||||
### Phase 1: Foundation (Week 1)
|
|
||||||
- [ ] Add cancel flow (survey + 1 offer + confirmation)
|
|
||||||
- [ ] Set up exit survey with 5-7 reason categories
|
|
||||||
- [ ] Map one offer per reason (simple 1:1 mapping)
|
|
||||||
- [ ] Track cancel reasons and save rate in analytics
|
|
||||||
- [ ] Enable pre-dunning card expiry emails
|
|
||||||
|
|
||||||
### Phase 2: Optimization (Weeks 2-4)
|
|
||||||
- [ ] Add fallback offers (primary + secondary per reason)
|
|
||||||
- [ ] Implement pause subscription option
|
|
||||||
- [ ] Set up dunning email sequence (4 emails over 10 days)
|
|
||||||
- [ ] Enable smart retries (Stripe Smart Retries or equivalent)
|
|
||||||
- [ ] Add MRR-based routing for high-value accounts
|
|
||||||
|
|
||||||
### Phase 3: Advanced (Month 2+)
|
|
||||||
- [ ] Build health score from usage signals
|
|
||||||
- [ ] Set up proactive intervention triggers
|
|
||||||
- [ ] A/B test discount amounts and offer types
|
|
||||||
- [ ] Segment flows by plan, tenure, and usage
|
|
||||||
- [ ] Post-cancel win-back sequence (coordinate with email-sequence skill)
|
|
||||||
- [ ] Cohort analysis: churn by channel, plan, tenure
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Compliance Notes
|
|
||||||
|
|
||||||
### FTC Click-to-Cancel Rule (US)
|
|
||||||
- Cancellation must be as easy as signup
|
|
||||||
- Cannot require a phone call to cancel if signup was online
|
|
||||||
- Cannot add excessive steps to discourage cancellation
|
|
||||||
- Save offers are allowed but "continue cancelling" must be clear
|
|
||||||
|
|
||||||
### GDPR / Data Retention (EU)
|
|
||||||
- Inform users about data retention period post-cancel
|
|
||||||
- Offer data export before account deletion
|
|
||||||
- Honor deletion requests within 30 days
|
|
||||||
- Don't use post-cancel data for marketing without consent
|
|
||||||
|
|
||||||
### General Best Practices
|
|
||||||
- Always show a clear path to complete cancellation
|
|
||||||
- Never hide the cancel button (dark pattern)
|
|
||||||
- Process cancellation even if save flow has errors
|
|
||||||
- Confirm cancellation with email receipt
|
|
||||||
|
|
@ -1,408 +0,0 @@
|
||||||
# Dunning Playbook
|
|
||||||
|
|
||||||
Complete guide to recovering failed payments and reducing involuntary churn.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Why Dunning Matters
|
|
||||||
|
|
||||||
- Failed payments cause 30-50% of all subscription churn
|
|
||||||
- Most failed payments are recoverable with the right strategy
|
|
||||||
- Subscription businesses lose an estimated $129 billion annually to involuntary churn
|
|
||||||
- Effective dunning recovers 50-60% of failed payments
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## The Dunning Timeline
|
|
||||||
|
|
||||||
```
|
|
||||||
Day -30 to -7: Pre-dunning (prevent failures)
|
|
||||||
Day 0: Payment fails → Smart retry #1 + Email #1
|
|
||||||
Day 1-3: Smart retry #2 + Email #2
|
|
||||||
Day 3-5: Smart retry #3
|
|
||||||
Day 5-7: Smart retry #4 + Email #3
|
|
||||||
Day 7-10: Final retry + Email #4 (final warning)
|
|
||||||
Day 10-14: Grace period ends → Account paused/cancelled
|
|
||||||
Day 14+: Win-back sequence begins
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pre-Dunning: Prevent Failures Before They Happen
|
|
||||||
|
|
||||||
### Card Expiry Management
|
|
||||||
|
|
||||||
| Timing | Action |
|
|
||||||
|--------|--------|
|
|
||||||
| 30 days before expiry | Email: "Your card ending in 4242 expires next month" |
|
|
||||||
| 15 days before expiry | Email: "Update your payment method to avoid interruption" |
|
|
||||||
| 7 days before expiry | Email: "Your card expires in 7 days — update now" |
|
|
||||||
| 3 days before expiry | In-app banner: "Payment method expiring soon" |
|
|
||||||
|
|
||||||
**Email template — Card expiring:**
|
|
||||||
```
|
|
||||||
Subject: Your card ending in 4242 expires soon
|
|
||||||
|
|
||||||
Hi [Name],
|
|
||||||
|
|
||||||
The card on file for your [Product] subscription expires on [date].
|
|
||||||
|
|
||||||
Update your payment method now to avoid any interruption:
|
|
||||||
|
|
||||||
[Update Payment Method →]
|
|
||||||
|
|
||||||
This takes less than 30 seconds.
|
|
||||||
|
|
||||||
— [Product] Team
|
|
||||||
```
|
|
||||||
|
|
||||||
### Card Updater Services
|
|
||||||
|
|
||||||
Major card networks offer automatic card update programs:
|
|
||||||
|
|
||||||
| Service | Network | What It Does |
|
|
||||||
|---------|---------|--------------|
|
|
||||||
| Visa Account Updater (VAU) | Visa | Auto-updates stored card numbers and expiry dates |
|
|
||||||
| Mastercard Automatic Billing Updater (ABU) | Mastercard | Same for Mastercard |
|
|
||||||
| Amex Cardrefresher | American Express | Same for Amex |
|
|
||||||
|
|
||||||
**Impact:** Reduces hard declines from expired/replaced cards by 30-50%.
|
|
||||||
|
|
||||||
**How to enable:**
|
|
||||||
- **Stripe**: Automatic — enabled by default
|
|
||||||
- **Chargebee**: Enabled through gateway settings
|
|
||||||
- **Recurly**: Built-in, enabled by default
|
|
||||||
- **Braintree**: Contact processor to enable
|
|
||||||
|
|
||||||
### Backup Payment Methods
|
|
||||||
|
|
||||||
Prompt for a second payment method:
|
|
||||||
- During signup: "Add a backup payment method" (low conversion)
|
|
||||||
- After first successful payment: "Protect your account with a backup card" (better timing)
|
|
||||||
- After a failed payment is recovered: "Add a backup to prevent future interruptions" (best timing — they felt the pain)
|
|
||||||
|
|
||||||
### Pre-Billing Notifications
|
|
||||||
|
|
||||||
For annual plans or high-value subscriptions:
|
|
||||||
- Email 7 days before renewal with amount and date
|
|
||||||
- Include link to update payment method
|
|
||||||
- Show what's included in the renewal
|
|
||||||
- Required by some regulations for auto-renewals
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Smart Retry Strategy
|
|
||||||
|
|
||||||
### Decline Type Classification
|
|
||||||
|
|
||||||
| Code | Type | Meaning | Retry? |
|
|
||||||
|------|------|---------|--------|
|
|
||||||
| `insufficient_funds` | Soft | Temporarily low balance | Yes — retry in 2-3 days |
|
|
||||||
| `card_declined` (generic) | Soft | Various temporary reasons | Yes — retry 3-4 times |
|
|
||||||
| `processing_error` | Soft | Gateway/network issue | Yes — retry within 24h |
|
|
||||||
| `expired_card` | Hard | Card is expired | No — request new card |
|
|
||||||
| `stolen_card` | Hard | Card reported stolen | No — request new card |
|
|
||||||
| `do_not_honor` | Soft/Hard | Bank refused (ambiguous) | Try once more, then ask for new card |
|
|
||||||
| `authentication_required` | Auth | SCA/3DS needed | Send customer to authenticate |
|
|
||||||
|
|
||||||
### Retry Schedule by Provider
|
|
||||||
|
|
||||||
**Stripe (Smart Retries — recommended):**
|
|
||||||
- Enable "Smart Retries" in Stripe Dashboard → Billing → Settings
|
|
||||||
- Stripe's ML model picks optimal retry timing based on billions of transactions
|
|
||||||
- Typically 4-8 retry attempts over 3-4 weeks
|
|
||||||
- Recovers ~15% more than fixed-schedule retries
|
|
||||||
|
|
||||||
**Manual retry schedule (if no smart retries):**
|
|
||||||
|
|
||||||
| Retry | Timing | Best Day/Time |
|
|
||||||
|-------|--------|--------------|
|
|
||||||
| 1 | Day 1 (24h after failure) | Morning, same day of week as original |
|
|
||||||
| 2 | Day 3 | Try a different time of day |
|
|
||||||
| 3 | Day 5 | After typical payday (1st, 15th) |
|
|
||||||
| 4 | Day 7 | Morning of the next business day |
|
|
||||||
| 5 (final) | Day 10 | Last attempt before grace period ends |
|
|
||||||
|
|
||||||
**Retry timing insights:**
|
|
||||||
- Retry on the same day of month the original payment succeeded
|
|
||||||
- Retry after common paydays (1st and 15th of the month)
|
|
||||||
- Avoid retrying on weekends (lower approval rates)
|
|
||||||
- Morning retries (8-10am local time) perform slightly better
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Dunning Email Sequence
|
|
||||||
|
|
||||||
### Email 1: Payment Failed (Day 0)
|
|
||||||
|
|
||||||
**Tone:** Friendly, matter-of-fact. No alarm.
|
|
||||||
|
|
||||||
```
|
|
||||||
Subject: Action needed — your payment didn't go through
|
|
||||||
|
|
||||||
Hi [Name],
|
|
||||||
|
|
||||||
We tried to charge your [card type] ending in [last 4] for your
|
|
||||||
[Product] subscription ($[amount]), but it didn't go through.
|
|
||||||
|
|
||||||
This happens sometimes — usually a quick card update fixes it.
|
|
||||||
|
|
||||||
[Update Payment Method →]
|
|
||||||
|
|
||||||
Your access isn't affected yet. We'll retry automatically, but
|
|
||||||
updating your card is the fastest fix.
|
|
||||||
|
|
||||||
Need help? Just reply to this email.
|
|
||||||
|
|
||||||
— [Product] Team
|
|
||||||
```
|
|
||||||
|
|
||||||
### Email 2: Reminder (Day 3)
|
|
||||||
|
|
||||||
**Tone:** Helpful, slightly more urgent.
|
|
||||||
|
|
||||||
```
|
|
||||||
Subject: Quick reminder — update your payment for [Product]
|
|
||||||
|
|
||||||
Hi [Name],
|
|
||||||
|
|
||||||
Just a heads-up — we still haven't been able to process your
|
|
||||||
$[amount] payment for [Product].
|
|
||||||
|
|
||||||
[Update Payment Method →]
|
|
||||||
|
|
||||||
Takes less than 30 seconds. Your [data/projects/team access]
|
|
||||||
is safe, but we'll need a valid payment method to keep your
|
|
||||||
account active.
|
|
||||||
|
|
||||||
Questions? Reply here and we'll help.
|
|
||||||
|
|
||||||
— [Product] Team
|
|
||||||
```
|
|
||||||
|
|
||||||
### Email 3: Urgency (Day 7)
|
|
||||||
|
|
||||||
**Tone:** Direct, clear consequences.
|
|
||||||
|
|
||||||
```
|
|
||||||
Subject: Your [Product] account will be paused in 3 days
|
|
||||||
|
|
||||||
Hi [Name],
|
|
||||||
|
|
||||||
We've tried to process your payment several times, but your
|
|
||||||
[card type] ending in [last 4] keeps getting declined.
|
|
||||||
|
|
||||||
If we don't receive payment by [date], your account will be
|
|
||||||
paused and you'll lose access to:
|
|
||||||
|
|
||||||
• [Key feature/data they use]
|
|
||||||
• [Their projects/workspace]
|
|
||||||
• [Team access for X members]
|
|
||||||
|
|
||||||
[Update Payment Method Now →]
|
|
||||||
|
|
||||||
Your data won't be deleted — you can reactivate anytime by
|
|
||||||
updating your payment method.
|
|
||||||
|
|
||||||
— [Product] Team
|
|
||||||
```
|
|
||||||
|
|
||||||
### Email 4: Final Warning (Day 10)
|
|
||||||
|
|
||||||
**Tone:** Final, clear, no guilt.
|
|
||||||
|
|
||||||
```
|
|
||||||
Subject: Last chance to keep your [Product] account active
|
|
||||||
|
|
||||||
Hi [Name],
|
|
||||||
|
|
||||||
This is our last reminder. Your payment of $[amount] is past
|
|
||||||
due, and your account will be paused tomorrow ([date]).
|
|
||||||
|
|
||||||
[Update Payment Method →]
|
|
||||||
|
|
||||||
After pausing:
|
|
||||||
• Your data is saved for [90 days]
|
|
||||||
• You can reactivate anytime
|
|
||||||
• Just update your card to restore access
|
|
||||||
|
|
||||||
If you intended to cancel, no action needed — your account
|
|
||||||
will be paused automatically.
|
|
||||||
|
|
||||||
— [Product] Team
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Grace Period Management
|
|
||||||
|
|
||||||
### What Happens During Grace Period
|
|
||||||
|
|
||||||
| Setting | Recommendation |
|
|
||||||
|---------|---------------|
|
|
||||||
| Duration | 7-14 days after final retry |
|
|
||||||
| Access | Degraded (read-only) or full access |
|
|
||||||
| Visibility | In-app banner: "Payment past due — update to continue" |
|
|
||||||
| Retry | Continue background retries during grace |
|
|
||||||
| Communication | Dunning emails continue |
|
|
||||||
|
|
||||||
### Access Degradation Options
|
|
||||||
|
|
||||||
**Option A: Full access during grace (recommended for B2B)**
|
|
||||||
- Lower friction, customer feels respected
|
|
||||||
- Higher recovery rate (they still see value)
|
|
||||||
- Risk: some customers exploit the grace period
|
|
||||||
|
|
||||||
**Option B: Read-only access (recommended for B2C)**
|
|
||||||
- Can view but not create/edit
|
|
||||||
- Creates urgency without data loss fear
|
|
||||||
- Clear message: "Update payment to resume full access"
|
|
||||||
|
|
||||||
**Option C: Immediate lockout (not recommended)**
|
|
||||||
- Aggressive, damages relationship
|
|
||||||
- Lower recovery rate
|
|
||||||
- Only appropriate for very low-cost plans
|
|
||||||
|
|
||||||
### Post-Grace Period
|
|
||||||
|
|
||||||
| Timing | Action |
|
|
||||||
|--------|--------|
|
|
||||||
| Grace period ends | Pause account (not delete) |
|
|
||||||
| Day 1 post-pause | "Your account has been paused" email |
|
|
||||||
| Day 7 post-pause | "Your data is still here" reminder |
|
|
||||||
| Day 30 post-pause | Win-back attempt with new offer |
|
|
||||||
| Day 60 post-pause | Final win-back |
|
|
||||||
| Day 90 post-pause | Data deletion warning (if applicable) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Provider-Specific Setup
|
|
||||||
|
|
||||||
### Stripe
|
|
||||||
|
|
||||||
**Enable Smart Retries:**
|
|
||||||
1. Dashboard → Settings → Billing → Subscriptions and emails
|
|
||||||
2. Enable "Smart Retries" under retry rules
|
|
||||||
3. Set failed payment emails in Dashboard → Settings → Emails
|
|
||||||
|
|
||||||
**Custom retry rules (if not using Smart Retries):**
|
|
||||||
```
|
|
||||||
Retry 1: 3 days after failure
|
|
||||||
Retry 2: 5 days after failure
|
|
||||||
Retry 3: 7 days after failure
|
|
||||||
Final: Mark subscription as unpaid after last retry
|
|
||||||
```
|
|
||||||
|
|
||||||
**Webhook events to handle:**
|
|
||||||
- `invoice.payment_failed` — trigger dunning
|
|
||||||
- `invoice.paid` — cancel dunning, restore access
|
|
||||||
- `customer.subscription.updated` — status changes
|
|
||||||
- `customer.subscription.deleted` — final cancellation
|
|
||||||
|
|
||||||
### Chargebee
|
|
||||||
|
|
||||||
**Built-in dunning:**
|
|
||||||
1. Settings → Configure Chargebee → Retry Settings
|
|
||||||
2. Configure retry attempts and intervals
|
|
||||||
3. Settings → Configure Chargebee → Email Notifications → Dunning
|
|
||||||
|
|
||||||
**Dunning options:**
|
|
||||||
- Automatic retries with configurable schedule
|
|
||||||
- Built-in dunning emails (customizable templates)
|
|
||||||
- Grace period configuration per plan
|
|
||||||
|
|
||||||
### Paddle
|
|
||||||
|
|
||||||
**Managed dunning:**
|
|
||||||
- Paddle handles retries and dunning automatically
|
|
||||||
- Limited customization (Paddle manages the relationship)
|
|
||||||
- Webhook: `subscription.payment_failed`, `subscription.cancelled`
|
|
||||||
- Best for hands-off approach
|
|
||||||
|
|
||||||
### Recurly
|
|
||||||
|
|
||||||
**Revenue Recovery:**
|
|
||||||
1. Configuration → Dunning Management
|
|
||||||
2. Set retry schedule per plan
|
|
||||||
3. Configure grace period and final action (pause vs cancel)
|
|
||||||
|
|
||||||
**Advanced features:**
|
|
||||||
- Machine-learning retry optimization
|
|
||||||
- Per-plan dunning schedules
|
|
||||||
- Built-in Account Updater
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## In-App Dunning
|
|
||||||
|
|
||||||
Don't rely on email alone. Show payment failures in the app:
|
|
||||||
|
|
||||||
### Banner Pattern
|
|
||||||
```
|
|
||||||
┌──────────────────────────────────────────────────────┐
|
|
||||||
│ ⚠ Your payment of $29 failed. Update your card to │
|
|
||||||
│ avoid losing access. [Update Payment →] [Dismiss] │
|
|
||||||
└──────────────────────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
**Rules:**
|
|
||||||
- Show on every page load during dunning period
|
|
||||||
- Allow dismiss (but show again next session)
|
|
||||||
- Direct link to payment update (fewest clicks possible)
|
|
||||||
- Don't block the product — let them continue using it
|
|
||||||
|
|
||||||
### Modal Pattern (for final warning)
|
|
||||||
```
|
|
||||||
┌─────────────────────────────────────┐
|
|
||||||
│ │
|
|
||||||
│ Your account will be paused │
|
|
||||||
│ on [date] │
|
|
||||||
│ │
|
|
||||||
│ Update your payment method to │
|
|
||||||
│ keep access to your [X] projects │
|
|
||||||
│ and [Y] team members. │
|
|
||||||
│ │
|
|
||||||
│ [Update Payment Method] │
|
|
||||||
│ [Remind Me Later] │
|
|
||||||
│ │
|
|
||||||
└─────────────────────────────────────┘
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Measuring Dunning Performance
|
|
||||||
|
|
||||||
### Key Metrics
|
|
||||||
|
|
||||||
| Metric | How to Calculate | Target |
|
|
||||||
|--------|-----------------|--------|
|
|
||||||
| Recovery rate | Recovered payments / Total failed | 50-60% |
|
|
||||||
| Recovery rate by decline type | Recovered / Failed per type | Soft: 70%+, Hard: 40%+ |
|
|
||||||
| Time to recovery | Days from failure to successful payment | <5 days |
|
|
||||||
| Pre-dunning prevention rate | Prevented failures / Expected failures | 20-30% |
|
|
||||||
| Dunning email open rate | Opens / Sent per email | 60%+ |
|
|
||||||
| Dunning email click rate | Clicks / Opens per email | 30%+ |
|
|
||||||
| Revenue recovered (monthly) | Sum of recovered payment amounts | Track trend |
|
|
||||||
| Revenue lost to involuntary churn | Sum of failed + unrecovered amounts | Track trend |
|
|
||||||
|
|
||||||
### Benchmarking
|
|
||||||
|
|
||||||
**By company stage:**
|
|
||||||
|
|
||||||
| Stage | Typical Involuntary Churn | Target After Optimization |
|
|
||||||
|-------|--------------------------|--------------------------|
|
|
||||||
| Early (< $1M ARR) | 3-5% of MRR/month | 1-2% |
|
|
||||||
| Growth ($1-10M ARR) | 2-4% of MRR/month | 0.5-1.5% |
|
|
||||||
| Scale ($10M+ ARR) | 1-3% of MRR/month | 0.3-0.8% |
|
|
||||||
|
|
||||||
### ROI Calculation
|
|
||||||
|
|
||||||
```
|
|
||||||
Monthly failed payment MRR: $10,000
|
|
||||||
Current recovery rate: 30% ($3,000 recovered)
|
|
||||||
Target recovery rate: 60% ($6,000 recovered)
|
|
||||||
Monthly improvement: $3,000/month
|
|
||||||
Annual improvement: $36,000/year
|
|
||||||
Cost of dunning optimization: ~$200-500/month (tooling)
|
|
||||||
ROI: 6-15x
|
|
||||||
```
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: cold-email
|
name: cold-email
|
||||||
description: Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, sales development emails, or SDR emails. Also use when the user mentions "cold outreach," "prospecting email," "outbound email," "email to leads," "reach out to prospects," "sales email," "follow-up email sequence," "nobody's replying to my emails," or "how do I write a cold email." Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences. For warm/lifecycle email sequences, see email-sequence. For sales collateral beyond emails, see sales-enablement.
|
description: Write B2B cold emails and follow-up sequences for HVAC B2B outreach (distributor partnerships, contractor recruitment, manufacturer reps). Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, or partner development emails. Also use when the user mentions "cold outreach," "prospecting email," "partner email," "contractor recruitment," "reach out to distributors," "manufacturer email," "follow-up sequence," or "how do I recruit contractors." Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences. For warm/lifecycle email sequences, see email-sequence. Narrow focus to compliant B2B partner outreach.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, browse]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Cold Email Writing
|
# Cold Email Writing
|
||||||
|
|
@ -12,15 +15,17 @@ You are an expert cold email writer. Your goal is to write emails that sound lik
|
||||||
## Before Writing
|
## Before Writing
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Understand the situation (ask if not provided):
|
Understand the situation (ask if not provided):
|
||||||
|
|
||||||
1. **Who are you writing to?** — Role, company, why them specifically
|
1. **Who are you writing to?** — Role (distributor, contractor, training org, service partner), company, why them specifically
|
||||||
2. **What do you want?** — The outcome (meeting, reply, intro, demo)
|
2. **What do you want?** — The outcome (partnership meeting, contractor enrollment, distributor rep signup, co-marketing deal)
|
||||||
3. **What's the value?** — The specific problem you solve for people like them
|
3. **What's the value?** — The specific problem you solve (margin improvement, lead generation, training access, brand support)
|
||||||
4. **What's your proof?** — A result, case study, or credibility signal
|
4. **What's your proof?** — Results (contractor volume metrics, distributor territory growth, training completion rates), case studies, partner testimonials
|
||||||
5. **Any research signals?** — Funding, hiring, LinkedIn posts, company news, tech stack changes
|
5. **Any research signals?** — Company expansion, new truck fleet, service territory growth, recent hiring, licensing updates
|
||||||
|
|
||||||
|
For HVAC B2B outreach, focus on compliant channels: distributor networks, contractor licensing databases, industry partner directories. Avoid consumer-facing spam tactics.
|
||||||
|
|
||||||
Work with whatever the user gives you. If they have a strong signal and a clear value prop, that's enough to write. Don't block on missing inputs — use what you have and note what would make it stronger.
|
Work with whatever the user gives you. If they have a strong signal and a clear value prop, that's enough to write. Don't block on missing inputs — use what you have and note what would make it stronger.
|
||||||
|
|
||||||
|
|
@ -52,47 +57,74 @@ Interest-based CTAs ("Worth exploring?" / "Would this be useful?") beat meeting
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Voice & Tone
|
## HVAC B2B Voice & Tone
|
||||||
|
|
||||||
**The target voice:** A smart colleague who noticed something relevant and is sharing it. Conversational but not sloppy. Confident but not pushy.
|
HVAC cold outreach is peer-to-peer. You're approaching professionals who value efficiency and specificity.
|
||||||
|
|
||||||
|
**The target voice:** A colleague who understands their business and has something genuinely useful to offer. Not a sales rep, but a partner exploring a mutual opportunity.
|
||||||
|
|
||||||
**Calibrate to the audience:**
|
**Calibrate to the audience:**
|
||||||
|
|
||||||
- C-suite: ultra-brief, peer-level, understated
|
- **Distributor/Owner**: Business-focused, specifics on margin/volume, peer-level, understated
|
||||||
- Mid-level: more specific value, slightly more detail
|
- **Contractor/Service Manager**: Technical credibility, lead generation or efficiency angle, respect their trade expertise
|
||||||
- Technical: precise, no fluff, respect their intelligence
|
- **Training Organization**: Data on learner outcomes, certification value, partnership benefits
|
||||||
|
- **OEM/Rep**: Market analysis, territory opportunities, mutual growth angle
|
||||||
|
|
||||||
|
**HVAC-Specific Credibility Signals:**
|
||||||
|
- Reference their service territory or expansion
|
||||||
|
- Mention equipment lines they carry or install
|
||||||
|
- Call out seasonal demand patterns you're seeing
|
||||||
|
- Reference their contractor testimonials or case studies
|
||||||
|
|
||||||
**What it should NOT sound like:**
|
**What it should NOT sound like:**
|
||||||
|
|
||||||
- A template with fields swapped in
|
- A template with fields swapped in
|
||||||
- A pitch deck compressed into paragraph form
|
- Overly salesy HVAC jargon ("cutting-edge," "leading provider," "synergies")
|
||||||
- A LinkedIn DM from someone you've never met
|
- A LinkedIn DM tone in an email
|
||||||
- An AI-generated email (avoid the telltale patterns: "I hope this email finds you well," "I came across your profile," "leverage," "synergy," "best-in-class")
|
- Generic ("I came across your company...")
|
||||||
|
- Pushy timeline pressure (they're busy in the field)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Structure
|
## HVAC B2B Cold Email Structure
|
||||||
|
|
||||||
There's no single right structure. Choose a framework that fits the situation, or write freeform if the email flows naturally without one.
|
No single right structure. Choose what fits the situation or write naturally. These are proven shapes in HVAC.
|
||||||
|
|
||||||
**Common shapes that work:**
|
**For Distributor/Partner Outreach:**
|
||||||
|
- **Market opportunity → Specific value → Proof → Low-friction ask**
|
||||||
|
"We're seeing demand shift to inverter equipment in [region]. Customers asking for [benefit]. XYZ distributor in [nearby territory] increased orders [X]% when they focused here. Worth exploring for your territory?"
|
||||||
|
|
||||||
- **Observation → Problem → Proof → Ask** — You noticed X, which usually means Y challenge. We helped Z with that. Interested?
|
**For Contractor Recruitment/Partnership:**
|
||||||
- **Question → Value → Ask** — Struggling with X? We do Y. Company Z saw [result]. Worth a look?
|
- **Observation → Lead generation or efficiency angle → Proof → Next step**
|
||||||
- **Trigger → Insight → Ask** — Congrats on X. That usually creates Y challenge. We've helped similar companies with that. Curious?
|
"Noticed your company expanded to [area]. Contractors adding heat pumps are seeing [$ result]. We've helped [similar contractor] book [# appointments/leads]. Quick call to explore?"
|
||||||
- **Story → Bridge → Ask** — [Similar company] had [problem]. They [solved it this way]. Relevant to you?
|
|
||||||
|
**For Training or Certification Partnerships:**
|
||||||
|
- **Trend → Contractor pain point → Proof → Collaboration ask**
|
||||||
|
"SEER2 deadline caught contractors off guard. We built certification that [covers key gaps]. Training org [X] saw [% of students] pass certification. Interested in co-marketing?"
|
||||||
|
|
||||||
|
**For Equipment/Rep Opportunities:**
|
||||||
|
- **Market condition → Territory gap → Mutual benefit → Ask**
|
||||||
|
"Heat pump adoption in [region] is accelerating but contractors are underserving [specific segment]. We can support your reps with [resources/leads]. Brief call to map opportunity?"
|
||||||
|
|
||||||
For the full catalog of frameworks with examples, see [frameworks.md](references/frameworks.md).
|
For the full catalog of frameworks with examples, see [frameworks.md](references/frameworks.md).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Subject Lines
|
## HVAC Cold Email Subject Lines
|
||||||
|
|
||||||
Short, boring, internal-looking. The subject line's only job is to get the email opened — not to sell.
|
Short, boring, internal-looking. Get it opened.
|
||||||
|
|
||||||
- 2-4 words, lowercase, no punctuation tricks
|
- 2-4 words, lowercase, no punctuation tricks
|
||||||
- Should look like it came from a colleague ("reply rates," "hiring ops," "Q2 forecast")
|
- Should look like it came from a colleague or peer: "heat pump demand shift," "SEER2 training," "contractor lead program," "territory expansion"
|
||||||
- No product pitches, no urgency, no emojis, no prospect's first name
|
- No product pitches, no urgency, no emojis, no prospect's first name
|
||||||
|
- For partner outreach: reference their market, a mutual opportunity, or a relevant trend
|
||||||
|
|
||||||
|
Examples that work:
|
||||||
|
- "heat pump opportunity in [region]"
|
||||||
|
- "contractor partnership question"
|
||||||
|
- "SEER2 certification interest"
|
||||||
|
- "distributor territory expansion"
|
||||||
|
- "training partnership idea"
|
||||||
|
|
||||||
See [subject-lines.md](references/subject-lines.md) for the full data.
|
See [subject-lines.md](references/subject-lines.md) for the full data.
|
||||||
|
|
||||||
|
|
@ -122,16 +154,19 @@ Before presenting, gut-check:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## What to Avoid
|
## What to Avoid in HVAC B2B Cold Email
|
||||||
|
|
||||||
- Opening with "I hope this email finds you well" or "My name is X and I work at Y"
|
- Opening with "I hope this email finds you well" or "I came across your profile"
|
||||||
- Jargon: "synergy," "leverage," "circle back," "best-in-class," "leading provider"
|
- HVAC jargon without context: "cutting-edge inverter technology," "best-in-class efficiency"
|
||||||
- Feature dumps — one proof point beats ten features
|
- Generic value props: "We help contractors succeed"
|
||||||
|
- Feature dumps of equipment specs
|
||||||
- HTML, images, or multiple links
|
- HTML, images, or multiple links
|
||||||
- Fake "Re:" or "Fwd:" subject lines
|
- Fake "Re:" or "Fwd:" subject lines
|
||||||
- Identical templates with only {{FirstName}} swapped
|
- Identical templates with only company names swapped
|
||||||
- Asking for 30-minute calls in first touch
|
- Asking for 30-minute calls in first touch
|
||||||
- "Just checking in" follow-ups
|
- "Just checking in" follow-ups without new info
|
||||||
|
- Pressure tactics or "urgency" language for B2B partner outreach
|
||||||
|
- Cold calls followed by email without context
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -149,10 +184,23 @@ Use this data to inform your writing — not as a checklist to satisfy.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
HVAC cold email outreach can leverage Compendium's content and contractor data:
|
||||||
|
|
||||||
|
- **Search Tools**: Research prospect companies, their service areas, recent growth signals, or equipment focus
|
||||||
|
- **Database Tools**: Identify contractor licensing, distributor partnerships, training needs in your target market
|
||||||
|
- **Browse Tools**: Monitor LinkedIn/social presence of target accounts, understand their content strategy and focus areas
|
||||||
|
|
||||||
|
**Tool Tiers**: Enhanced mode — requires search, database, and browse capabilities
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **copywriting**: For landing pages and web copy
|
- **copywriting**: For landing page and email body copy
|
||||||
- **email-sequence**: For lifecycle/nurture email sequences (not cold outreach)
|
- **email-sequence**: For lifecycle/nurture sequences (post-initial outreach)
|
||||||
- **social-content**: For LinkedIn and social posts
|
- **social-content**: For LinkedIn outreach and profile strategy
|
||||||
- **product-marketing-context**: For establishing foundational positioning
|
- **content-strategy**: For positioning and competitive research
|
||||||
- **revops**: For lead scoring, routing, and pipeline management
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Write a cold email to VP of Marketing at mid-size B2B SaaS companies. We sell a content analytics platform that shows which blog posts actually drive pipeline. Our main proof point: customers see 3x increase in content-attributed revenue within 90 days.",
|
"prompt": "Write a cold email to VP of Marketing at mid-size B2B SaaS companies. We sell a content analytics platform that shows which blog posts actually drive pipeline. Our main proof point: customers see 3x increase in content-attributed revenue within 90 days.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should write like a peer, not a vendor. Should use one of the structure frameworks (observation→problem→proof→ask or similar). Subject line should be 2-4 words, lowercase, internal-looking. Every sentence should earn its place. Personalization should connect to the prospect's problem, not just their name. Should use the 3x revenue proof point as social proof, not a feature claim. CTA should be low-friction (not 'book a demo'). Should provide 2-3 variations. Should include a quality check against the guidelines.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should write like a peer, not a vendor. Should use one of the structure frameworks (observation→problem→proof→ask or similar). Subject line should be 2-4 words, lowercase, internal-looking. Every sentence should earn its place. Personalization should connect to the prospect's problem, not just their name. Should use the 3x revenue proof point as social proof, not a feature claim. CTA should be low-friction (not 'book a demo'). Should provide 2-3 variations. Should include a quality check against the guidelines.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Writes like a peer, not a vendor",
|
"Writes like a peer, not a vendor",
|
||||||
"Uses a structure framework from the skill",
|
"Uses a structure framework from the skill",
|
||||||
"Subject line is short, lowercase, internal-looking",
|
"Subject line is short, lowercase, internal-looking",
|
||||||
|
|
|
||||||
|
|
@ -1,39 +1,45 @@
|
||||||
---
|
---
|
||||||
name: competitor-alternatives
|
name: competitor-alternatives
|
||||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'battle card,' or 'competitor teardown.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For sales-specific competitor docs, see sales-enablement."
|
description: "When the user wants to create HVAC brand comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'HVAC brand comparison,' '[Brand] vs [Brand],' '[Brand] alternative,' 'Carrier vs Trane,' '[Equipment] comparison,' 'competitor teardown,' 'how do we compare,' 'battle card,' 'HVAC contractor comparison,' or '[Service] vs [Service] (repair vs replacement).' Use this for any content that positions an HVAC product/service/brand against competitors. For sales-specific competitor docs, see sales-enablement."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, scrape, browse]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Competitor & Alternative Pages
|
# HVAC Competitor & Alternative Pages
|
||||||
|
|
||||||
You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.
|
You are an expert in creating HVAC brand comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to HVAC buyers/specifiers, and position your product effectively.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 creating competitor pages, understand:
|
Before creating competitor pages, understand:
|
||||||
|
|
||||||
1. **Your Product**
|
1. **Your Product/Service**
|
||||||
|
- HVAC equipment brand/model or service offering?
|
||||||
- Core value proposition
|
- Core value proposition
|
||||||
- Key differentiators
|
- Key differentiators
|
||||||
- Ideal customer profile
|
- Ideal customer profile (residential/commercial/contractors)
|
||||||
- Pricing model
|
- Pricing model
|
||||||
- Strengths and honest weaknesses
|
- Strengths and honest weaknesses
|
||||||
|
|
||||||
2. **Competitive Landscape**
|
2. **Competitive Landscape**
|
||||||
- Direct competitors
|
- Direct HVAC competitors (Carrier vs Trane, brands at same price point)
|
||||||
- Indirect/adjacent competitors
|
- Indirect competitors (DIY vs professional repair)
|
||||||
|
- Equipment comparisons (AC vs heat pump for your climate)
|
||||||
|
- Service comparisons (repair vs replacement decisions)
|
||||||
- Market positioning of each
|
- Market positioning of each
|
||||||
- Search volume for competitor terms
|
- Search volume for competitor terms
|
||||||
|
|
||||||
3. **Goals**
|
3. **Goals**
|
||||||
- SEO traffic capture
|
- SEO traffic capture from comparison searches
|
||||||
- Sales enablement
|
- Sales enablement for contractors/homeowners
|
||||||
- Conversion from competitor users
|
- Conversion from competitor customers
|
||||||
- Brand positioning
|
- Brand positioning in HVAC market
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -43,19 +49,19 @@ Before creating competitor pages, understand:
|
||||||
- Acknowledge competitor strengths
|
- Acknowledge competitor strengths
|
||||||
- Be accurate about your limitations
|
- Be accurate about your limitations
|
||||||
- Don't misrepresent competitor features
|
- Don't misrepresent competitor features
|
||||||
- Readers are comparing—they'll verify claims
|
- Readers are HVAC professionals or informed buyers—they'll verify claims
|
||||||
|
|
||||||
### 2. Depth Over Surface
|
### 2. Depth Over Surface
|
||||||
- Go beyond feature checklists
|
- Go beyond feature checklists
|
||||||
- Explain *why* differences matter
|
- Explain *why* differences matter for HVAC performance
|
||||||
- Include use cases and scenarios
|
- Include use cases (residential vs commercial, climate factors)
|
||||||
- Show, don't just tell
|
- Show real specs and performance data
|
||||||
|
|
||||||
### 3. Help Them Decide
|
### 3. Help Them Decide
|
||||||
- Different tools fit different needs
|
- Different HVAC systems fit different needs and budgets
|
||||||
- Be clear about who you're best for
|
- Be clear about who you're best for
|
||||||
- Be clear about who competitor is best for
|
- Be clear about who competitor is best for
|
||||||
- Reduce evaluation friction
|
- Reduce evaluation friction for contractors and homeowners
|
||||||
|
|
||||||
### 4. Modular Content Architecture
|
### 4. Modular Content Architecture
|
||||||
- Competitor data should be centralized
|
- Competitor data should be centralized
|
||||||
|
|
@ -68,39 +74,39 @@ Before creating competitor pages, understand:
|
||||||
|
|
||||||
### Format 1: [Competitor] Alternative (Singular)
|
### Format 1: [Competitor] Alternative (Singular)
|
||||||
|
|
||||||
**Search intent**: User is actively looking to switch from a specific competitor
|
**Search intent**: HVAC buyer actively looking to switch from a specific brand/equipment
|
||||||
|
|
||||||
**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`
|
**URL pattern**: `/alternatives/[competitor]` or `/[competitor]-alternative`
|
||||||
|
|
||||||
**Target keywords**: "[Competitor] alternative", "alternative to [Competitor]", "switch from [Competitor]"
|
**Target keywords**: "[Competitor] alternative", "alternative to [Competitor]", "instead of [Competitor]"
|
||||||
|
|
||||||
**Page structure**:
|
**Page structure**:
|
||||||
1. Why people look for alternatives (validate their pain)
|
1. Why people look for HVAC alternatives (pain points with competitor)
|
||||||
2. Summary: You as the alternative (quick positioning)
|
2. Summary: You as the HVAC alternative (quick positioning)
|
||||||
3. Detailed comparison (features, service, pricing)
|
3. Detailed comparison (equipment specs, service, pricing, efficiency)
|
||||||
4. Who should switch (and who shouldn't)
|
4. Who should switch (and who shouldn't — honesty)
|
||||||
5. Migration path
|
5. Migration/upgrade path
|
||||||
6. Social proof from switchers
|
6. Social proof from HVAC contractors/customers who switched
|
||||||
7. CTA
|
7. CTA (Request quote, speak to expert)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Format 2: [Competitor] Alternatives (Plural)
|
### Format 2: [Competitor] Alternatives (Plural)
|
||||||
|
|
||||||
**Search intent**: User is researching options, earlier in journey
|
**Search intent**: HVAC buyer researching options, earlier in journey
|
||||||
|
|
||||||
**URL pattern**: `/alternatives/[competitor]-alternatives`
|
**URL pattern**: `/alternatives/[competitor]-alternatives`
|
||||||
|
|
||||||
**Target keywords**: "[Competitor] alternatives", "best [Competitor] alternatives", "tools like [Competitor]"
|
**Target keywords**: "[Competitor] alternatives", "best [Competitor] alternatives", "brands like [Competitor]"
|
||||||
|
|
||||||
**Page structure**:
|
**Page structure**:
|
||||||
1. Why people look for alternatives (common pain points)
|
1. Why people look for HVAC alternatives (common pain points)
|
||||||
2. What to look for in an alternative (criteria framework)
|
2. What to look for in an HVAC alternative (criteria framework: SEER rating, price, warranty, etc.)
|
||||||
3. List of alternatives (you first, but include real options)
|
3. List of alternatives (you first, but include real options)
|
||||||
4. Comparison table (summary)
|
4. Comparison table (summary)
|
||||||
5. Detailed breakdown of each alternative
|
5. Detailed breakdown of each alternative
|
||||||
6. Recommendation by use case
|
6. Recommendation by use case (residential, commercial, different climates)
|
||||||
7. CTA
|
7. CTA (Get quote, consult contractor)
|
||||||
|
|
||||||
**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
|
**Important**: Include 4-7 real alternatives. Being genuinely helpful builds trust and ranks better.
|
||||||
|
|
||||||
|
|
@ -108,61 +114,90 @@ Before creating competitor pages, understand:
|
||||||
|
|
||||||
### Format 3: You vs [Competitor]
|
### Format 3: You vs [Competitor]
|
||||||
|
|
||||||
**Search intent**: User is directly comparing you to a specific competitor
|
**Search intent**: Buyer directly comparing you to a specific HVAC competitor
|
||||||
|
|
||||||
**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`
|
**URL pattern**: `/vs/[competitor]` or `/compare/[you]-vs-[competitor]`
|
||||||
|
|
||||||
**Target keywords**: "[You] vs [Competitor]", "[Competitor] vs [You]"
|
**Target keywords**: "[You] vs [Competitor]", "[Competitor] vs [You]"
|
||||||
|
|
||||||
**Page structure**:
|
**Page structure**:
|
||||||
1. TL;DR summary (key differences in 2-3 sentences)
|
1. TL;DR summary (key HVAC performance differences in 2-3 sentences)
|
||||||
2. At-a-glance comparison table
|
2. At-a-glance comparison table (SEER, AFUE, price, warranty, service)
|
||||||
3. Detailed comparison by category (Features, Pricing, Support, Ease of use, Integrations)
|
3. Detailed comparison by category:
|
||||||
4. Who [You] is best for
|
- Efficiency ratings (SEER, AFUE, HSPF)
|
||||||
|
- Pricing (equipment + installation)
|
||||||
|
- Warranty coverage
|
||||||
|
- Noise levels
|
||||||
|
- Smart home compatibility
|
||||||
|
- Availability in your region
|
||||||
|
- Service/support
|
||||||
|
4. Who [You] is best for (use case, climate, budget)
|
||||||
5. Who [Competitor] is best for (be honest)
|
5. Who [Competitor] is best for (be honest)
|
||||||
6. What customers say (testimonials from switchers)
|
6. What customers/contractors say (testimonials from switchers)
|
||||||
7. Migration support
|
7. Installation/upgrade process
|
||||||
8. CTA
|
8. CTA (Get quote, speak with HVAC pro)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Format 4: [Competitor A] vs [Competitor B]
|
### Format 4: [Brand A] vs [Brand B]
|
||||||
|
|
||||||
**Search intent**: User comparing two competitors (not you directly)
|
**Search intent**: HVAC buyer comparing two competitors (not you directly, but positioning yourself as third option)
|
||||||
|
|
||||||
**URL pattern**: `/compare/[competitor-a]-vs-[competitor-b]`
|
**URL pattern**: `/compare/[brand-a]-vs-[brand-b]`
|
||||||
|
|
||||||
**Page structure**:
|
**Page structure**:
|
||||||
1. Overview of both products
|
1. Overview of both HVAC brands/equipment
|
||||||
2. Comparison by category
|
2. Comparison by category (efficiency, price, warranty, etc.)
|
||||||
3. Who each is best for
|
3. Who each brand is best for
|
||||||
4. The third option (introduce yourself)
|
4. The third option (introduce yourself)
|
||||||
5. Comparison table (all three)
|
5. Comparison table (all three)
|
||||||
6. CTA
|
6. Recommendation by use case
|
||||||
|
7. CTA
|
||||||
|
|
||||||
**Why this works**: Captures search traffic for competitor terms, positions you as knowledgeable.
|
**Why this works**: Captures search traffic for competitor-focused HVAC terms, positions you as knowledgeable third option.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Essential Sections
|
## Essential Sections
|
||||||
|
|
||||||
### TL;DR Summary
|
### TL;DR Summary
|
||||||
Start every page with a quick summary for scanners—key differences in 2-3 sentences.
|
Start every page with a quick summary for scanners—key HVAC differences in 2-3 sentences.
|
||||||
|
|
||||||
### Paragraph Comparisons
|
### Technical Comparisons
|
||||||
Go beyond tables. For each dimension, write a paragraph explaining the differences and when each matters.
|
HVAC-specific dimensions:
|
||||||
|
- **Efficiency**: SEER (cooling), AFUE (heating), HSPF (heat pumps)
|
||||||
|
- **Price**: Equipment cost, typical installation cost, total cost of ownership
|
||||||
|
- **Warranty**: Equipment warranty, labor warranty, duration
|
||||||
|
- **Noise**: Decibel levels at typical operating conditions
|
||||||
|
- **Smart home**: Thermostat compatibility, smart controls
|
||||||
|
- **Size/footprint**: Physical dimensions, compatibility with existing systems
|
||||||
|
- **Refrigerant**: Environmental impact, regional restrictions
|
||||||
|
- **Maintenance**: Filter costs, service intervals, availability
|
||||||
|
|
||||||
### Feature Comparison
|
### Feature Comparison by Category
|
||||||
For each category: describe how each handles it, list strengths and limitations, give bottom line recommendation.
|
For each dimension: describe how each handles it, list strengths and limitations, give bottom line recommendation.
|
||||||
|
|
||||||
### Pricing Comparison
|
### Efficiency & Savings
|
||||||
Include tier-by-tier comparison, what's included, hidden costs, and total cost calculation for sample team size.
|
Concrete energy savings estimates (if possible).
|
||||||
|
|
||||||
|
### Warranty & Support
|
||||||
|
Comprehensive coverage details, service availability, contractor network.
|
||||||
|
|
||||||
### Who It's For
|
### Who It's For
|
||||||
Be explicit about ideal customer for each option. Honest recommendations build trust.
|
Be explicit about ideal customer for each HVAC option:
|
||||||
|
- Homeowner in cold climate (furnace)
|
||||||
|
- Homeowner in warm climate (AC)
|
||||||
|
- Contractor specifying for new construction
|
||||||
|
- Budget-conscious replacement
|
||||||
|
- High-efficiency premium buyer
|
||||||
|
|
||||||
### Migration Section
|
### Migration Section
|
||||||
Cover what transfers, what needs reconfiguration, support offered, and quotes from customers who switched.
|
For equipment replacement pages:
|
||||||
|
- What transfers (ductwork, electrical)
|
||||||
|
- What needs replacement/reconfiguration
|
||||||
|
- Removal/disposal of old equipment
|
||||||
|
- Installation timeline
|
||||||
|
- Support offered
|
||||||
|
|
||||||
**For detailed templates**: See [references/templates.md](references/templates.md)
|
**For detailed templates**: See [references/templates.md](references/templates.md)
|
||||||
|
|
||||||
|
|
@ -171,14 +206,17 @@ Cover what transfers, what needs reconfiguration, support offered, and quotes fr
|
||||||
## Content Architecture
|
## Content Architecture
|
||||||
|
|
||||||
### Centralized Competitor Data
|
### Centralized Competitor Data
|
||||||
Create a single source of truth for each competitor with:
|
|
||||||
|
Create a single source of truth for each HVAC competitor with:
|
||||||
- Positioning and target audience
|
- Positioning and target audience
|
||||||
- Pricing (all tiers)
|
- Equipment models and specs (SEER, AFUE, HSPF)
|
||||||
- Feature ratings
|
- Pricing (all tiers, regional variation)
|
||||||
|
- Warranty coverage
|
||||||
- Strengths and weaknesses
|
- Strengths and weaknesses
|
||||||
- Best for / not ideal for
|
- Best for / not ideal for
|
||||||
- Common complaints (from reviews)
|
- Common complaints (from review sites, contractor forums)
|
||||||
- Migration notes
|
- Upgrade/installation notes
|
||||||
|
- Contractor availability
|
||||||
|
|
||||||
**For data structure and examples**: See [references/content-architecture.md](references/content-architecture.md)
|
**For data structure and examples**: See [references/content-architecture.md](references/content-architecture.md)
|
||||||
|
|
||||||
|
|
@ -186,21 +224,22 @@ Create a single source of truth for each competitor with:
|
||||||
|
|
||||||
## Research Process
|
## Research Process
|
||||||
|
|
||||||
### Deep Competitor Research
|
### Deep HVAC Competitor Research
|
||||||
|
|
||||||
For each competitor, gather:
|
For each competitor, gather:
|
||||||
|
|
||||||
1. **Product research**: Sign up, use it, document features/UX/limitations
|
1. **Product research**: Specifications (SEER, AFUE, noise level, size), available models, features
|
||||||
2. **Pricing research**: Current pricing, what's included, hidden costs
|
2. **Pricing research**: Current equipment pricing, typical installation costs by region, financing options
|
||||||
3. **Review mining**: G2, Capterra, TrustRadius for common praise/complaint themes
|
3. **Review mining**: HVAC.com, Yelp, G2, specialized HVAC forums for common praise/complaint themes
|
||||||
4. **Customer feedback**: Talk to customers who switched (both directions)
|
4. **Contractor feedback**: Talk to HVAC contractors who install/service both brands
|
||||||
5. **Content research**: Their positioning, their comparison pages, their changelog
|
5. **Customer feedback**: End-user testimonials and case studies
|
||||||
|
6. **Content research**: Competitor positioning, their comparison pages, product documentation
|
||||||
|
|
||||||
### Ongoing Updates
|
### Ongoing Updates
|
||||||
|
|
||||||
- **Quarterly**: Verify pricing, check for major feature changes
|
- **Quarterly**: Verify specs, check for new model releases, update pricing
|
||||||
- **When notified**: Customer mentions competitor change
|
- **When notified**: New products launched, major spec changes
|
||||||
- **Annually**: Full refresh of all competitor data
|
- **Annually**: Full refresh of all competitor positioning and data
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -208,49 +247,99 @@ For each competitor, gather:
|
||||||
|
|
||||||
### Keyword Targeting
|
### Keyword Targeting
|
||||||
|
|
||||||
| Format | Primary Keywords |
|
| Format | Primary HVAC Keywords |
|
||||||
|--------|-----------------|
|
|--------|-----------------|
|
||||||
| Alternative (singular) | [Competitor] alternative, alternative to [Competitor] |
|
| Alternative (singular) | [Brand] alternative, alternative to [Brand], [Brand] vs [Your Brand] |
|
||||||
| Alternatives (plural) | [Competitor] alternatives, best [Competitor] alternatives |
|
| Alternatives (plural) | [Brand] alternatives, best [Brand] alternatives, brands like [Brand] |
|
||||||
| You vs Competitor | [You] vs [Competitor], [Competitor] vs [You] |
|
| You vs Competitor | [Your Brand] vs [Brand], [Brand] vs [Your Brand] |
|
||||||
| Competitor vs Competitor | [A] vs [B], [B] vs [A] |
|
| Brand vs Brand | [Brand A] vs [Brand B], [Brand B] vs [Brand A] |
|
||||||
|
| Service comparison | AC repair vs AC replacement, furnace repair vs replacement |
|
||||||
|
|
||||||
### Internal Linking
|
### Internal Linking
|
||||||
- Link between related competitor pages
|
|
||||||
- Link from feature pages to relevant comparisons
|
- Link between related HVAC competitor pages
|
||||||
|
- Link from product/service pages to relevant comparisons
|
||||||
- Create hub page linking to all competitor content
|
- Create hub page linking to all competitor content
|
||||||
|
- Link from main service pages to comparison pages
|
||||||
|
|
||||||
### Schema Markup
|
### Schema Markup
|
||||||
Consider FAQ schema for common questions like "What is the best alternative to [Competitor]?"
|
|
||||||
|
Consider FAQ schema for questions like:
|
||||||
|
- "What is the best alternative to [Brand]?"
|
||||||
|
- "Is [Brand A] better than [Brand B]?"
|
||||||
|
- Use ComparisonPage or ItemList schema for structured comparisons
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HVAC-Specific Comparison Dimensions
|
||||||
|
|
||||||
|
### Equipment Brands (Carrier vs Trane)
|
||||||
|
|
||||||
|
Key differentiators:
|
||||||
|
- Efficiency ratings (SEER, AFUE)
|
||||||
|
- Price positioning (budget, mid-range, premium)
|
||||||
|
- Warranty length and coverage
|
||||||
|
- Noise levels
|
||||||
|
- Smart home integration
|
||||||
|
- R&D/innovation
|
||||||
|
- Contractor loyalty/rebates
|
||||||
|
- Regional availability
|
||||||
|
- Service network strength
|
||||||
|
|
||||||
|
### Service Decisions (Repair vs Replace)
|
||||||
|
|
||||||
|
Key differentiators:
|
||||||
|
- Age of equipment (typical lifespan: 10-15 years)
|
||||||
|
- Repair costs vs replacement costs
|
||||||
|
- Efficiency gains from new equipment
|
||||||
|
- Environmental factors (newer refrigerants)
|
||||||
|
- Long-term cost of ownership
|
||||||
|
- Contractor recommendation
|
||||||
|
|
||||||
|
### Equipment Types (AC vs Heat Pump)
|
||||||
|
|
||||||
|
Key differentiators:
|
||||||
|
- Climate appropriateness
|
||||||
|
- Total cost of ownership (fuel/electricity)
|
||||||
|
- Comfort (heating capability)
|
||||||
|
- Noise levels
|
||||||
|
- Space requirements
|
||||||
|
- Efficiency ratings (SEER vs HSPF)
|
||||||
|
- Maintenance needs
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
### Competitor Data File
|
### Competitor Data File
|
||||||
Complete competitor profile in YAML format for use across all comparison pages.
|
Complete competitor HVAC profile in YAML format for use across all comparison pages.
|
||||||
|
|
||||||
### Page Content
|
### Page Content
|
||||||
For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.
|
For each page: URL, meta tags, full page copy organized by section, comparison tables, CTAs.
|
||||||
|
|
||||||
### Page Set Plan
|
### Page Set Plan
|
||||||
Recommended pages to create with priority order based on search volume.
|
Recommended HVAC comparison pages to create with priority order based on search volume.
|
||||||
|
|
||||||
|
### Comparison Table Templates
|
||||||
|
Ready-to-use tables for common HVAC comparisons (brand comparison, service decision, equipment type).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What are common reasons people switch to you?
|
1. What HVAC products/services are you comparing? (Equipment brands, service types, etc.)
|
||||||
2. Do you have customer quotes about switching?
|
2. What are common reasons HVAC contractors/customers switch to you?
|
||||||
3. What's your pricing vs. competitors?
|
3. Do you have contractor testimonials or case studies about competitive advantages?
|
||||||
4. Do you offer migration support?
|
4. What's your pricing vs. HVAC competitors?
|
||||||
|
5. Do you offer migration/upgrade support?
|
||||||
|
6. What are the 5 most common HVAC buyer questions about your competitors?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **programmatic-seo**: For building competitor pages at scale
|
- **programmatic-seo**: For building HVAC competitor pages at scale (equipment variants, locations)
|
||||||
- **copywriting**: For writing compelling comparison copy
|
- **copywriting**: For writing compelling HVAC comparison copy
|
||||||
- **seo-audit**: For optimizing competitor pages
|
- **seo-audit**: For optimizing HVAC competitor pages after launch
|
||||||
- **schema-markup**: For FAQ and comparison schema
|
- **schema-markup**: For FAQ and comparison schema on HVAC pages
|
||||||
- **sales-enablement**: For internal sales collateral, decks, and objection docs
|
- **sales-enablement**: For internal sales collateral, contractor enablement, and objection docs
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Create a 'Best Asana Alternatives' page for our project management tool. We compete mainly on price (we're $8/user vs their $24/user) and simplicity (they've become bloated). Target audience is small teams (5-20 people).",
|
"prompt": "Create a 'Best Asana Alternatives' page for our project management tool. We compete mainly on price (we're $8/user vs their $24/user) and simplicity (they've become bloated). Target audience is small teams (5-20 people).",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify this as the plural alternatives format ([Competitor] Alternatives). Should include the essential sections: TL;DR comparison, brief paragraphs on each alternative (including the user's product positioned first or prominently), feature comparison table, pricing comparison, who each alternative is best for. Should use the modular content architecture approach. Should address SEO considerations for the target keyword 'Asana alternatives.' Should position the user's product with the stated differentiators (price, simplicity).",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should identify this as the plural alternatives format ([Competitor] Alternatives). Should include the essential sections: TL;DR comparison, brief paragraphs on each alternative (including the user's product positioned first or prominently), feature comparison table, pricing comparison, who each alternative is best for. Should use the modular content architecture approach. Should address SEO considerations for the target keyword 'Asana alternatives.' Should position the user's product with the stated differentiators (price, simplicity).",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Identifies as plural alternatives format",
|
"Identifies as plural alternatives format",
|
||||||
"Includes TL;DR comparison section",
|
"Includes TL;DR comparison section",
|
||||||
"Includes feature comparison table",
|
"Includes feature comparison table",
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,10 @@
|
||||||
name: content-strategy
|
name: content-strategy
|
||||||
description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," "content planning," "editorial calendar," "content marketing," "content roadmap," "what content should I create," "blog topics," "content pillars," or "I don't know what to write." Use this whenever someone needs help deciding what content to produce, not just writing it. For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit. For social media content specifically, see social-content.
|
description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," "content planning," "editorial calendar," "content marketing," "content roadmap," "what content should I create," "blog topics," "content pillars," or "I don't know what to write." Use this whenever someone needs help deciding what content to produce, not just writing it. For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit. For social media content specifically, see social-content.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Content Strategy
|
# Content Strategy
|
||||||
|
|
@ -12,7 +15,7 @@ You are a content strategist. Your goal is to help plan content that drives traf
|
||||||
## Before Planning
|
## Before Planning
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
|
|
@ -23,10 +26,10 @@ Gather this context (ask if not provided):
|
||||||
- What problems does your product solve?
|
- What problems does your product solve?
|
||||||
|
|
||||||
### 2. Customer Research
|
### 2. Customer Research
|
||||||
- What questions do customers ask before buying?
|
- What questions do contractors/distributors/homeowners ask before purchasing?
|
||||||
- What objections come up in sales calls?
|
- What objections come up in sales calls? (price, equipment reliability, efficiency claims)
|
||||||
- What topics appear repeatedly in support tickets?
|
- What topics appear repeatedly in support tickets? (warranty, installation, commissioning, performance)
|
||||||
- What language do customers use to describe their problems?
|
- What language do customers use to describe their problems? (high humidity, short cycling, comfort issues)
|
||||||
|
|
||||||
### 3. Current State
|
### 3. Current State
|
||||||
- Do you have existing content? What's working?
|
- Do you have existing content? What's working?
|
||||||
|
|
@ -75,9 +78,9 @@ Every piece of content must be searchable, shareable, or both. Prioritize in tha
|
||||||
|
|
||||||
**Use-Case Content**
|
**Use-Case Content**
|
||||||
Formula: [persona] + [use-case]. Targets long-tail keywords.
|
Formula: [persona] + [use-case]. Targets long-tail keywords.
|
||||||
- "Project management for designers"
|
- "HVAC system selection for apartment buildings"
|
||||||
- "Task tracking for developers"
|
- "Preventive maintenance for commercial contractors"
|
||||||
- "Client collaboration for freelancers"
|
- "Outdoor unit installation for harsh climates"
|
||||||
|
|
||||||
**Hub and Spoke**
|
**Hub and Spoke**
|
||||||
Hub = comprehensive overview. Spokes = related subtopics.
|
Hub = comprehensive overview. Spokes = related subtopics.
|
||||||
|
|
@ -91,11 +94,11 @@ Create hub first, then build spokes. Interlink strategically.
|
||||||
|
|
||||||
**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.
|
**Note:** Most content works fine under `/blog`. Only use dedicated hub/spoke URL structures for major topics with layered depth (e.g., Atlassian's `/agile` guide). For typical blog posts, `/blog/post-title` is sufficient.
|
||||||
|
|
||||||
**Template Libraries**
|
**Checklists & Tools**
|
||||||
High-intent keywords + product adoption.
|
High-intent keywords + system selection.
|
||||||
- Target searches like "marketing plan template"
|
- Target searches like "HVAC maintenance checklist," "equipment sizing calculator"
|
||||||
- Provide immediate standalone value
|
- Provide immediate standalone value
|
||||||
- Show how product enhances the template
|
- Show how equipment/service fits the checklist
|
||||||
|
|
||||||
### Shareable Content Types
|
### Shareable Content Types
|
||||||
|
|
||||||
|
|
@ -122,18 +125,16 @@ For programmatic content at scale, see **programmatic-seo** skill.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Content Pillars and Topic Clusters
|
## HVAC Content Pillars and Topic Clusters
|
||||||
|
|
||||||
Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content.
|
Content pillars are the 3-5 core topics your brand will own. Each pillar spawns a cluster of related content. HVAC brands typically own pillars around efficiency, regulations, seasonality, troubleshooting, and equipment selection.
|
||||||
|
|
||||||
Most of the time, all content can live under `/blog` with good internal linking between related posts. Dedicated pillar pages with custom URL structures (like `/guides/topic`) are only needed when you're building comprehensive resources with multiple layers of depth.
|
### How to Identify HVAC Pillars
|
||||||
|
|
||||||
### How to Identify Pillars
|
1. **Product-led**: What equipment/systems do you sell? (heat pumps, variable-speed, mini-split, commercial)
|
||||||
|
2. **Audience-led**: What does your ICP need to learn? (contractors need efficiency specs; homeowners need comfort/savings)
|
||||||
1. **Product-led**: What problems does your product solve?
|
3. **Search-led**: What topics have volume? (Use Compendium `mv_topic_trends_weekly` for seasonal demand patterns)
|
||||||
2. **Audience-led**: What does your ICP need to learn?
|
4. **Regulatory-led**: What compliance changes are coming? (SEER2 transition, state mandates, refrigerant phase-outs)
|
||||||
3. **Search-led**: What topics have volume in your space?
|
|
||||||
4. **Competitor-led**: What are competitors ranking for?
|
|
||||||
|
|
||||||
### Pillar Structure
|
### Pillar Structure
|
||||||
|
|
||||||
|
|
@ -153,13 +154,21 @@ Pillar Topic (Hub)
|
||||||
└── Article I
|
└── Article I
|
||||||
```
|
```
|
||||||
|
|
||||||
### Pillar Criteria
|
### HVAC Pillar Examples
|
||||||
|
|
||||||
Good pillars should:
|
**Example Pillars for Equipment Manufacturer:**
|
||||||
- Align with your product/service
|
1. **Efficiency & Compliance** (SEER2, regulations, energy savings) — Awareness + Decision
|
||||||
- Match what your audience cares about
|
2. **Installation & Commissioning** (contractor-focused, regional differences) — Implementation
|
||||||
- Have search volume and/or social interest
|
3. **Troubleshooting & Support** (common issues, diagnostics, performance) — Support/Retention
|
||||||
- Be broad enough for many subtopics
|
4. **Product Technology** (inverter, variable-speed, smart controls) — Awareness + Consideration
|
||||||
|
5. **Seasonal Maintenance** (seasonal demand patterns, IAQ) — Retention
|
||||||
|
|
||||||
|
**Example Pillars for HVAC Service Company:**
|
||||||
|
1. **Residential HVAC Services** (maintenance, repair, replacement)
|
||||||
|
2. **Indoor Air Quality & Health**
|
||||||
|
3. **Energy Efficiency Tips** (homeowner-facing)
|
||||||
|
4. **Emergency & Seasonal Services**
|
||||||
|
5. **Equipment Selection Guide** (HVAC buying decision)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -170,34 +179,34 @@ Map topics to the buyer's journey using proven keyword modifiers:
|
||||||
### Awareness Stage
|
### Awareness Stage
|
||||||
Modifiers: "what is," "how to," "guide to," "introduction to"
|
Modifiers: "what is," "how to," "guide to," "introduction to"
|
||||||
|
|
||||||
Example: If customers ask about project management basics:
|
Example: If customers ask about HVAC basics:
|
||||||
- "What is Agile Project Management"
|
- "What is a Heat Pump and How Does It Work"
|
||||||
- "Guide to Sprint Planning"
|
- "Guide to Indoor Air Quality"
|
||||||
- "How to Run a Standup Meeting"
|
- "How to Commission an HVAC System"
|
||||||
|
|
||||||
### Consideration Stage
|
### Consideration Stage
|
||||||
Modifiers: "best," "top," "vs," "alternatives," "comparison"
|
Modifiers: "best," "top," "vs," "comparison," "efficiency ratings"
|
||||||
|
|
||||||
Example: If customers evaluate multiple tools:
|
Example: If customers evaluate equipment options:
|
||||||
- "Best Project Management Tools for Remote Teams"
|
- "Best HVAC Systems for High Humidity Climates"
|
||||||
- "Asana vs Trello vs Monday"
|
- "Inverter vs Fixed-Speed Compressors"
|
||||||
- "Basecamp Alternatives"
|
- "Variable Refrigerant Flow Alternatives"
|
||||||
|
|
||||||
### Decision Stage
|
### Decision Stage
|
||||||
Modifiers: "pricing," "reviews," "demo," "trial," "buy"
|
Modifiers: "pricing," "reviews," "specifications," "performance data"
|
||||||
|
|
||||||
Example: If pricing comes up in sales calls:
|
Example: If specifications and performance come up:
|
||||||
- "Project Management Tool Pricing Comparison"
|
- "HVAC Equipment SEER2 Ratings Explained"
|
||||||
- "How to Choose the Right Plan"
|
- "[Equipment Brand] Performance Reviews"
|
||||||
- "[Product] Reviews"
|
- "Equipment Selection Guide"
|
||||||
|
|
||||||
### Implementation Stage
|
### Implementation Stage
|
||||||
Modifiers: "templates," "examples," "tutorial," "how to use," "setup"
|
Modifiers: "commissioning," "startup," "tuning," "maintenance," "troubleshooting"
|
||||||
|
|
||||||
Example: If support tickets show implementation struggles:
|
Example: If support tickets show field issues:
|
||||||
- "Project Template Library"
|
- "HVAC System Commissioning Checklist"
|
||||||
- "Step-by-Step Setup Tutorial"
|
- "Seasonal Maintenance Guide"
|
||||||
- "How to Use [Feature]"
|
- "How to Diagnose Short Cycling"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -251,23 +260,24 @@ Use web search to find content ideas:
|
||||||
|
|
||||||
Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
|
Extract: FAQs, misconceptions, debates, problems being solved, terminology used.
|
||||||
|
|
||||||
### 5. Competitor Analysis
|
### 5. Competitor & Industry Analysis
|
||||||
|
|
||||||
Use web search to analyze competitor content:
|
Use web search and Compendium database to analyze content:
|
||||||
|
|
||||||
**Find their content:** `site:competitor.com/blog`
|
**Find content:** Use `site:` search + check YouTube/podcast content in Compendium (`mv_topic_trends_weekly`, `mv_topic_saturation`)
|
||||||
|
|
||||||
**Analyze:**
|
**Analyze:**
|
||||||
- Top-performing posts (comments, shares)
|
- What topics are saturated in your space?
|
||||||
- Topics covered repeatedly
|
- Where are HVAC contractors/manufacturers creating content?
|
||||||
- Gaps they haven't covered
|
- Equipment reviews and performance discussions
|
||||||
- Case studies (customer problems, use cases, results)
|
- Regional/seasonal content patterns
|
||||||
- Content structure (pillars, categories, formats)
|
- Installation and troubleshooting focus areas
|
||||||
|
|
||||||
**Identify opportunities:**
|
**Identify opportunities:**
|
||||||
- Topics you can cover better
|
- Equipment categories underserved in your region
|
||||||
- Angles they're missing
|
- Emerging efficiency standards (SEER2, EER)
|
||||||
- Outdated content to improve on
|
- Seasonal pain points (cooling/heating demand peaks)
|
||||||
|
- Compliance and regulatory changes
|
||||||
|
|
||||||
### 6. Sales and Support Input
|
### 6. Sales and Support Input
|
||||||
|
|
||||||
|
|
@ -348,12 +358,22 @@ Visual or structured representation of how content interconnects.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Content strategy for HVAC brands can leverage Compendium's content intelligence database:
|
||||||
|
|
||||||
|
- **Database Tools**: Query `mv_topic_saturation` to see if topics are oversaturated in your category; use `mv_topic_trends_weekly` for seasonal demand patterns and emerging topics
|
||||||
|
- **Search Integration**: Identify gaps between what's being discussed and what contractors/homeowners are searching for
|
||||||
|
- **Analysis**: Use Compendium's content classification to understand competitor angles, equipment mentions, and pain point language
|
||||||
|
|
||||||
|
**Tool Tiers**: Enhanced mode — requires database access and search/analyze capabilities
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **copywriting**: For writing individual content pieces
|
- **copywriting**: For writing individual content pieces
|
||||||
- **seo-audit**: For technical SEO and on-page optimization
|
- **seo-audit**: For technical SEO and on-page optimization
|
||||||
- **ai-seo**: For optimizing content for AI search engines and getting cited by LLMs
|
|
||||||
- **programmatic-seo**: For scaled content generation
|
|
||||||
- **site-architecture**: For page hierarchy, navigation design, and URL structure
|
|
||||||
- **email-sequence**: For email-based content
|
|
||||||
- **social-content**: For social media content
|
- **social-content**: For social media content
|
||||||
|
- **email-sequence**: For email-based content nurturing
|
||||||
|
- **cold-email**: For B2B manufacturer and distributor outreach
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me build a content strategy for our B2B SaaS product. We sell expense management software to finance teams at companies with 50-500 employees. We currently have no blog and want to start from scratch.",
|
"prompt": "Help me build a content strategy for our B2B SaaS product. We sell expense management software to finance teams at companies with 50-500 employees. We currently have no blog and want to start from scratch.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should establish content pillars (3-5 core topic areas). Should map content types by buyer stage (awareness → consideration → decision → implementation). Should identify keyword research opportunities by buyer stage. Should recommend a mix of searchable (SEO-driven) and shareable (thought leadership, data) content. Should use the prioritization scoring framework (customer impact 40%, content-market fit 30%, search potential 20%, resources 10%). Should provide an initial content calendar or publishing cadence. Should recommend content types appropriate for starting from scratch.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should establish content pillars (3-5 core topic areas). Should map content types by buyer stage (awareness → consideration → decision → implementation). Should identify keyword research opportunities by buyer stage. Should recommend a mix of searchable (SEO-driven) and shareable (thought leadership, data) content. Should use the prioritization scoring framework (customer impact 40%, content-market fit 30%, search potential 20%, resources 10%). Should provide an initial content calendar or publishing cadence. Should recommend content types appropriate for starting from scratch.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Establishes 3-5 content pillars",
|
"Establishes 3-5 content pillars",
|
||||||
"Maps content by buyer stage (awareness through implementation)",
|
"Maps content by buyer stage (awareness through implementation)",
|
||||||
"Includes keyword research by buyer stage",
|
"Includes keyword research by buyer stage",
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,10 @@
|
||||||
name: copy-editing
|
name: copy-editing
|
||||||
description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' or 'sharpen the messaging.' Use this when the user already has copy and wants it improved rather than rewritten from scratch. For writing new copy, see copywriting."
|
description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' or 'sharpen the messaging.' Use this when the user already has copy and wants it improved rather than rewritten from scratch. For writing new copy, see copywriting."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: standalone
|
||||||
|
tools: []
|
||||||
---
|
---
|
||||||
|
|
||||||
# Copy Editing
|
# Copy Editing
|
||||||
|
|
@ -12,7 +15,7 @@ You are an expert copy editor specializing in marketing and conversion copy. You
|
||||||
## Core Philosophy
|
## Core Philosophy
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before editing. Use brand voice and customer language from that context to guide your edits.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before editing. Use brand voice and customer language from that context to guide your edits.
|
||||||
|
|
||||||
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
|
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
|
||||||
|
|
||||||
|
|
@ -64,18 +67,21 @@ Edit copy through seven sequential passes, each focusing on one dimension. After
|
||||||
- Inconsistent brand personality
|
- Inconsistent brand personality
|
||||||
- Mood changes that feel jarring
|
- Mood changes that feel jarring
|
||||||
- Word choices that don't match the brand
|
- Word choices that don't match the brand
|
||||||
|
- HVAC tone markers: technical vs. accessible language; contractor vs. homeowner voice
|
||||||
|
|
||||||
**Common voice issues:**
|
**Common voice issues in HVAC copy:**
|
||||||
- Starting casual, becoming corporate
|
- Mixing technical jargon with oversimplified explanations
|
||||||
- Mixing "we" and "the company" references
|
- Switching between "contractor-speak" and "homeowner-friendly"
|
||||||
- Humor in some places, serious in others (unintentionally)
|
- Formal in headlines, casual in body (or vice versa)
|
||||||
- Technical language appearing randomly
|
- Inconsistent use of specifications language (SEER2, tonnage, etc.)
|
||||||
|
- Shifting between "we install" and "you can install"
|
||||||
|
|
||||||
**Process:**
|
**Process:**
|
||||||
1. Read aloud to hear inconsistencies
|
1. Read aloud to hear inconsistencies
|
||||||
2. Mark where tone shifts unexpectedly
|
2. Mark where tone shifts unexpectedly
|
||||||
3. Recommend edits that smooth transitions
|
3. Check: Is this for contractors, homeowners, or both? Consistency within audience context matters.
|
||||||
4. Ensure personality remains throughout
|
4. Recommend edits that smooth transitions
|
||||||
|
5. Ensure personality remains throughout
|
||||||
|
|
||||||
**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
|
**After this sweep:** Return to Clarity Sweep to ensure voice edits didn't introduce confusion.
|
||||||
|
|
||||||
|
|
@ -283,9 +289,10 @@ Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||||
| Cutting-edge | New/Modern |
|
| Cutting-edge | New/Modern |
|
||||||
|
|
||||||
**Watch for:**
|
**Watch for:**
|
||||||
- Adverbs (usually unnecessary)
|
- Adverbs (usually unnecessary) — especially "very," "efficiently," "optimally"
|
||||||
- Passive voice (switch to active)
|
- Passive voice (switch to active) — "is maintained" → "we maintain" or "you maintain"
|
||||||
- Nominalizations (verb → noun: "make a decision" → "decide")
|
- Nominalizations (verb → noun): "make a decision" → "decide," "achieve efficiency" → "maximize efficiency"
|
||||||
|
- HVAC buzzwords without substance: "innovative," "cutting-edge," "advanced," "smart" (without proof)
|
||||||
|
|
||||||
### Sentence-Level Checks
|
### Sentence-Level Checks
|
||||||
|
|
||||||
|
|
@ -324,6 +331,8 @@ Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||||
- [ ] Brand personality maintained
|
- [ ] Brand personality maintained
|
||||||
- [ ] No jarring shifts in mood
|
- [ ] No jarring shifts in mood
|
||||||
- [ ] Reads well aloud
|
- [ ] Reads well aloud
|
||||||
|
- [ ] HVAC tone consistent (contractor-focused vs. homeowner-friendly, or clearly segmented)
|
||||||
|
- [ ] Technical language appropriate for audience
|
||||||
|
|
||||||
### So What (Sweep 3)
|
### So What (Sweep 3)
|
||||||
- [ ] Every feature connects to a benefit
|
- [ ] Every feature connects to a benefit
|
||||||
|
|
@ -386,16 +395,20 @@ Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||||
**Fix:** Add specific testimonials, numbers, or case references
|
**Fix:** Add specific testimonials, numbers, or case references
|
||||||
|
|
||||||
### Problem: Generic Claims
|
### Problem: Generic Claims
|
||||||
**Symptom:** "We help businesses grow"
|
**Symptom:** "We help contractors succeed" or "Industry-leading efficiency"
|
||||||
**Fix:** Specify who, how, and by how much
|
**Fix:** Specify who, how, and by how much. "Our inverter-driven heat pumps achieve up to 20 SEER2, reducing annual energy costs 30% for contractors in humid climates."
|
||||||
|
|
||||||
### Problem: Mixed Audiences
|
### Problem: Mixed Audiences
|
||||||
**Symptom:** Copy tries to speak to everyone, resonates with no one
|
**Symptom:** Copy tries to speak to contractors AND homeowners without segmenting
|
||||||
**Fix:** Pick one audience and write directly to them
|
**Fix:** Either pick one audience and write directly to them, OR clearly segment ("For Contractors" / "For Homeowners") with distinct messaging
|
||||||
|
|
||||||
### Problem: Feature Overload
|
### Problem: Feature Overload
|
||||||
**Symptom:** Listing every capability, overwhelming the reader
|
**Symptom:** Listing every equipment spec (SEER2, EER, sound rating, tonnage range, refrigerant type, all at once)
|
||||||
**Fix:** Focus on 3-5 key benefits that matter most to the audience
|
**Fix:** Lead with the main benefit, then ladder benefits. Feature specs come after proving value.
|
||||||
|
|
||||||
|
### Problem: Jargon Without Translation
|
||||||
|
**Symptom:** "Our variable-speed compressor and inverter technology optimize subcooling for enhanced capacity modulation"
|
||||||
|
**Fix:** Translate for your audience. For homeowners: "Our system automatically adjusts to your comfort needs, saving energy." For contractors: "Variable-speed with inverter provides consistent capacity across ambient conditions."
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -431,9 +444,9 @@ This iterative process ensures each edit doesn't create new problems while respe
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete)
|
- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete)
|
||||||
- **page-cro**: For broader page optimization beyond copy
|
- **content-strategy**: For broader messaging and positioning decisions
|
||||||
- **marketing-psychology**: For understanding why certain edits improve conversion
|
- **social-content**: For social copy review and optimization
|
||||||
- **ab-test-setup**: For testing copy variations
|
- **email-sequence**: For email body copy editing
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -444,4 +457,6 @@ This iterative process ensures each edit doesn't create new problems while respe
|
||||||
| Writing new page copy from scratch | copywriting |
|
| Writing new page copy from scratch | copywriting |
|
||||||
| Reviewing and improving existing copy | copy-editing (this skill) |
|
| Reviewing and improving existing copy | copy-editing (this skill) |
|
||||||
| Editing copy you just wrote | copy-editing (this skill) |
|
| Editing copy you just wrote | copy-editing (this skill) |
|
||||||
| Structural or strategic page changes | page-cro |
|
| Planning content topics and pillars | content-strategy |
|
||||||
|
| Writing social media content | social-content |
|
||||||
|
| Creating email sequences | email-sequence |
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Edit this homepage copy for us: 'Welcome to CloudSync! We are very excited to offer you an innovative, cutting-edge platform that seamlessly integrates with your existing tools. Our powerful solution helps businesses of all sizes optimize their workflows and drive meaningful results. Get started today and experience the difference!'",
|
"prompt": "Edit this homepage copy for us: 'Welcome to CloudSync! We are very excited to offer you an innovative, cutting-edge platform that seamlessly integrates with your existing tools. Our powerful solution helps businesses of all sizes optimize their workflows and drive meaningful results. Get started today and experience the difference!'",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the Seven Sweeps Framework systematically. Sweep 1 (Clarity): identify vague language ('optimize workflows,' 'drive meaningful results,' 'experience the difference'). Sweep 2 (Voice & Tone): flag 'Welcome to' as weak opening, 'we are very excited' as company-focused. Sweep 3 (So What): question what specific value is being offered. Sweep 4 (Prove It): note no proof points, stats, or evidence. Sweep 5 (Specificity): flag 'businesses of all sizes,' 'existing tools,' 'powerful solution' as generic. Sweep 6 (Heightened Emotion): assess emotional impact. Sweep 7 (Zero Risk): check for trust signals. Should provide a rewritten version addressing all issues.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the Seven Sweeps Framework systematically. Sweep 1 (Clarity): identify vague language ('optimize workflows,' 'drive meaningful results,' 'experience the difference'). Sweep 2 (Voice & Tone): flag 'Welcome to' as weak opening, 'we are very excited' as company-focused. Sweep 3 (So What): question what specific value is being offered. Sweep 4 (Prove It): note no proof points, stats, or evidence. Sweep 5 (Specificity): flag 'businesses of all sizes,' 'existing tools,' 'powerful solution' as generic. Sweep 6 (Heightened Emotion): assess emotional impact. Sweep 7 (Zero Risk): check for trust signals. Should provide a rewritten version addressing all issues.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies Seven Sweeps Framework",
|
"Applies Seven Sweeps Framework",
|
||||||
"Identifies vague language (Clarity sweep)",
|
"Identifies vague language (Clarity sweep)",
|
||||||
"Flags weak opening and company-focused language (Voice & Tone sweep)",
|
"Flags weak opening and company-focused language (Voice & Tone sweep)",
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: copywriting
|
name: copywriting
|
||||||
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," "CTA copy," "value proposition," "tagline," "subheadline," "hero section copy," "above the fold," "this copy is weak," "make this more compelling," or "help me describe my product." Use this whenever someone is working on website text that needs to persuade or convert. For email copy, see email-sequence. For popup copy, see popup-cro. For editing existing copy, see copy-editing.
|
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, equipment pages, about pages, or service pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," "CTA copy," "value proposition," "tagline," "subheadline," "hero section copy," "equipment description," or "service page copy." Use this whenever someone is working on website text that needs to persuade or convert. For email copy, see email-sequence. For editing existing copy, see copy-editing.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Copywriting
|
# Copywriting
|
||||||
|
|
@ -12,7 +15,7 @@ You are an expert conversion copywriter. Your goal is to write marketing copy th
|
||||||
## Before Writing
|
## Before Writing
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
|
|
@ -21,16 +24,16 @@ Gather this context (ask if not provided):
|
||||||
- What is the ONE primary action you want visitors to take?
|
- What is the ONE primary action you want visitors to take?
|
||||||
|
|
||||||
### 2. Audience
|
### 2. Audience
|
||||||
- Who is the ideal customer?
|
- Who is the ideal customer? (homeowner, building owner, contractor, facility manager, distributor)
|
||||||
- What problem are they trying to solve?
|
- What problem are they trying to solve? (comfort, efficiency, noise, humidity, system reliability)
|
||||||
- What objections or hesitations do they have?
|
- What objections or hesitations do they have? (upfront cost, learning curve, compatibility with existing system)
|
||||||
- What language do they use to describe their problem?
|
- What language do they use? (SEER2, ton, inverter, variable-speed, comfort zones, humidity control)
|
||||||
|
|
||||||
### 3. Product/Offer
|
### 3. Product/Offer
|
||||||
- What are you selling or offering?
|
- What are you selling? (equipment, service, installation, maintenance plan, training)
|
||||||
- What makes it different from alternatives?
|
- What makes it different? (efficiency rating, warranty, durability, local support, installation quality)
|
||||||
- What's the key transformation or outcome?
|
- What's the outcome? (lower energy bills, better comfort, fewer breakdowns, faster response times)
|
||||||
- Any proof points (numbers, testimonials, case studies)?
|
- Any proof points? (AHRI ratings, customer testimonials, energy savings data, performance specs, contractor reviews)
|
||||||
|
|
||||||
### 4. Context
|
### 4. Context
|
||||||
- Where is traffic coming from? (ads, organic, email)
|
- Where is traffic coming from? (ads, organic, email)
|
||||||
|
|
@ -167,53 +170,73 @@ Examples:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Page-Specific Guidance
|
## HVAC Page-Specific Guidance
|
||||||
|
|
||||||
### Homepage
|
### Homepage (Equipment Manufacturer)
|
||||||
- Serve multiple audiences without being generic
|
- Lead with signature product benefit (efficiency rating, durability, warranty)
|
||||||
- Lead with broadest value proposition
|
- Serve multiple audiences: contractors, homeowners, distributors
|
||||||
- Provide clear paths for different visitor intents
|
- Show key differentiators (inverter technology, noise level, regional support)
|
||||||
|
- Clear CTAs: "Find a Distributor," "Download Specs," "View Product Lineup"
|
||||||
|
|
||||||
### Landing Page
|
### Equipment Product Page
|
||||||
- Single message, single CTA
|
- Headline: Lead with main benefit (efficiency, comfort, reliability)
|
||||||
- Match headline to ad/traffic source
|
- Specs section: AHRI ratings, SEER2, EER, sound rating, refrigerant type
|
||||||
- Complete argument on one page
|
- Applications: Climate zones, residential vs. commercial, capacity range
|
||||||
|
- Installation video or diagram
|
||||||
|
- Compatibility info: Existing system requirements, installation complexity
|
||||||
|
- CTA: "Request Quote," "Find Installation Contractor," "Download Product Sheet"
|
||||||
|
|
||||||
### Pricing Page
|
### Service Company Landing Page
|
||||||
- Help visitors choose the right plan
|
- Single message: Your main service (maintenance, emergency repair, replacement)
|
||||||
- Address "which is right for me?" anxiety
|
- Match headline to traffic source (seasonal: "Summer AC Maintenance," "Winter HVAC Prep")
|
||||||
- Make recommended plan obvious
|
- Proof: Response time guarantee, customer reviews, technician certifications
|
||||||
|
- CTA: "Schedule Service," "Request Emergency Service," "Get Free Estimate"
|
||||||
|
|
||||||
### Feature Page
|
### Maintenance/Seasonal Service Page
|
||||||
- Connect feature → benefit → outcome
|
- Problem-solution format (high utility bills → maintenance plan)
|
||||||
- Show use cases and examples
|
- Seasonal guidance: What to check before summer/winter
|
||||||
- Clear path to try or buy
|
- Cost comparison: Preventive maintenance vs. emergency repairs
|
||||||
|
- CTA: "Schedule Maintenance," "Download Maintenance Checklist"
|
||||||
|
|
||||||
### About Page
|
### About Page (Service Company)
|
||||||
- Tell the story of why you exist
|
- Story: How you got into HVAC, why you care about service quality
|
||||||
- Connect mission to customer benefit
|
- Team credibility: Certifications, years of experience, local community involvement
|
||||||
- Still include a CTA
|
- Why choose us: Emergency availability, warranty promise, customer relationships
|
||||||
|
- CTA: "Request Service" or "Meet the Team"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Voice and Tone
|
## HVAC Voice and Tone Guide
|
||||||
|
|
||||||
Before writing, establish:
|
HVAC copy typically balances technical credibility with accessibility. Your voice depends on your audience.
|
||||||
|
|
||||||
**Formality level:**
|
**For Contractors & Distributors:**
|
||||||
- Casual/conversational
|
- Authoritative technician tone (you know HVAC)
|
||||||
- Professional but friendly
|
- Precise terminology (SEER2, staging, subcooling)
|
||||||
- Formal/enterprise
|
- Respect their expertise and time
|
||||||
|
- Formal/professional; not sales-y
|
||||||
|
|
||||||
**Brand personality:**
|
**For Homeowners:**
|
||||||
- Playful or serious?
|
- Helpful advisor tone (demystify HVAC)
|
||||||
- Bold or understated?
|
- Translate jargon into benefits (comfort, savings, reliability)
|
||||||
- Technical or accessible?
|
- Acknowledge pain points (high bills, comfort issues, complexity)
|
||||||
|
- Professional but friendly; conversational
|
||||||
|
|
||||||
Maintain consistency, but adjust intensity:
|
**For Facility Managers:**
|
||||||
- Headlines can be bolder
|
- Business-focused (uptime, efficiency, compliance)
|
||||||
- Body copy should be clearer
|
- Data-driven (performance specs, cost of ownership)
|
||||||
- CTAs should be action-oriented
|
- Minimize downtime language
|
||||||
|
- Professional/formal
|
||||||
|
|
||||||
|
**Brand Personality Consistency:**
|
||||||
|
If you're a manufacturer: Trustworthy, technical, innovation-forward
|
||||||
|
If you're a service company: Reliable, local, problem-solvers
|
||||||
|
If you're a distributor: Partner, accessible, builder-focused
|
||||||
|
|
||||||
|
Adjust intensity but keep consistency:
|
||||||
|
- Headlines can be direct/bold
|
||||||
|
- Body copy should be clear and specific
|
||||||
|
- CTAs should be action-oriented and low-friction
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -243,10 +266,22 @@ For headlines and CTAs, provide 2-3 options:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Copywriting for HVAC can leverage Compendium's quote and topic databases:
|
||||||
|
|
||||||
|
- **Search Tools**: Find real customer quotes from `mv_notable_quotes` to use in testimonials and social proof
|
||||||
|
- **Database**: Reference actual HVAC topics, pain points, and language from Compendium's classified content
|
||||||
|
- **Analysis**: Understand how competitors describe features and benefits; identify gaps in messaging
|
||||||
|
|
||||||
|
**Tool Tiers**: Enhanced mode — requires search and database access
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **copy-editing**: For polishing existing copy (use after your draft)
|
- **copy-editing**: For polishing existing copy (use after your draft)
|
||||||
- **page-cro**: If page structure/strategy needs work, not just copy
|
- **content-strategy**: For broader messaging and positioning
|
||||||
- **email-sequence**: For email copywriting
|
- **email-sequence**: For email copywriting
|
||||||
- **popup-cro**: For popup and modal copy
|
- **social-content**: For social media copy
|
||||||
- **ab-test-setup**: To test copy variations
|
- **cold-email**: For B2B outreach copy
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Write homepage copy for a SaaS tool that automates employee onboarding. Target audience is HR directors at mid-size companies (200-2000 employees). Main differentiator is that it integrates with all major HRIS systems and cuts onboarding time from 2 weeks to 2 days.",
|
"prompt": "Write homepage copy for a SaaS tool that automates employee onboarding. Target audience is HR directors at mid-size companies (200-2000 employees). Main differentiator is that it integrates with all major HRIS systems and cuts onboarding time from 2 weeks to 2 days.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should write full page copy organized by section: Headline, Subheadline, CTA (above the fold), then Social Proof, Problem/Pain, Solution/Benefits, How It Works, Objection Handling, and Final CTA. Should follow copywriting principles: clarity over cleverness, benefits over features, specificity (use the '2 weeks to 2 days' stat), customer language. Headline should communicate core value proposition. CTAs should be action-oriented ('Start Free Trial' not 'Submit'). Should provide 2-3 headline alternatives with rationale. Should include annotations explaining key copy choices. Should include meta content (SEO page title and meta description).",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should write full page copy organized by section: Headline, Subheadline, CTA (above the fold), then Social Proof, Problem/Pain, Solution/Benefits, How It Works, Objection Handling, and Final CTA. Should follow copywriting principles: clarity over cleverness, benefits over features, specificity (use the '2 weeks to 2 days' stat), customer language. Headline should communicate core value proposition. CTAs should be action-oriented ('Start Free Trial' not 'Submit'). Should provide 2-3 headline alternatives with rationale. Should include annotations explaining key copy choices. Should include meta content (SEO page title and meta description).",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Writes full page copy organized by section",
|
"Writes full page copy organized by section",
|
||||||
"Includes Headline, Subheadline, and CTA above the fold",
|
"Includes Headline, Subheadline, and CTA above the fold",
|
||||||
"Includes Social Proof, Problem/Pain, Solution/Benefits, How It Works sections",
|
"Includes Social Proof, Problem/Pain, Solution/Benefits, How It Works sections",
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: email-sequence
|
name: email-sequence
|
||||||
description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," "lifecycle emails," "trigger-based emails," "email funnel," "email workflow," "what emails should I send," "welcome series," or "email cadence." Use this for any multi-email automated flow. For cold outreach emails, see cold-email. For in-app onboarding, see onboarding-cro.
|
description: "When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions 'welcome sequence,' 'seasonal emails,' 'maintenance reminders,' 'drip campaign,' 'email automation,' 'follow-up emails,' 'email flow,' 'newsletter strategy,' or 'email cadence.' For cold outreach emails, see cold-email. For email content and copy, see copywriting."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, fetch]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Email Sequence Design
|
# Email Sequence Design
|
||||||
|
|
@ -12,24 +15,25 @@ You are an expert in email marketing and automation. Your goal is to create emai
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 creating a sequence, understand:
|
Before creating a sequence, understand:
|
||||||
|
|
||||||
1. **Sequence Type**
|
1. **Sequence Type**
|
||||||
- Welcome/onboarding sequence
|
- Welcome/onboarding sequence (new contractor partner, new customer)
|
||||||
- Lead nurture sequence
|
- Seasonal reminder sequence (pre-summer AC check, winter heating prep)
|
||||||
- Re-engagement sequence
|
- Maintenance alert sequence (time-based: annual or 6-month)
|
||||||
- Post-purchase sequence
|
- Equipment launch sequence (new product announcement)
|
||||||
- Event-based sequence
|
- Training/educational sequence (certifications, new standards like SEER2)
|
||||||
- Educational sequence
|
- Lead nurture sequence (distributor to HVAC contractor)
|
||||||
- Sales sequence
|
- Post-service sequence (follow-up after installation or repair)
|
||||||
|
- Newsletter sequence (monthly industry updates, tips)
|
||||||
|
|
||||||
2. **Audience Context**
|
2. **Audience Context**
|
||||||
- Who are they?
|
- Who are they? (homeowner, contractor, facility manager, distributor, training prospect)
|
||||||
- What triggered them into this sequence?
|
- What triggered entry? (sign-up, season change, purchase, certification enrollment)
|
||||||
- What do they already know/believe?
|
- What do they know? (equipment basics, your brand, their pain points)
|
||||||
- What's their current relationship with you?
|
- Relationship stage? (new lead, existing customer, seasonal re-engage)
|
||||||
|
|
||||||
3. **Goals**
|
3. **Goals**
|
||||||
- Primary conversion goal
|
- Primary conversion goal
|
||||||
|
|
@ -111,100 +115,105 @@ Consider:
|
||||||
|
|
||||||
## Sequence Types Overview
|
## Sequence Types Overview
|
||||||
|
|
||||||
### Welcome Sequence (Post-Signup)
|
### Seasonal Maintenance Sequence (Homeowner)
|
||||||
**Length**: 5-7 emails over 12-14 days
|
**Length**: 3-4 emails, quarterly (Jan, Apr, Jul, Oct)
|
||||||
**Goal**: Activate, build trust, convert
|
**Goal**: Remind, drive service bookings, build loyalty
|
||||||
|
|
||||||
Key emails:
|
Key emails:
|
||||||
1. Welcome + deliver promised value (immediate)
|
1. Seasonal prep tip + checklist (email 1)
|
||||||
2. Quick win (day 1-2)
|
2. "Have you scheduled?" reminder (email 2, day 3)
|
||||||
3. Story/Why (day 3-4)
|
3. Special offer or urgency angle (email 3, day 7)
|
||||||
4. Social proof (day 5-6)
|
4. Last chance / alternative CTA (email 4, day 14)
|
||||||
5. Overcome objection (day 7-8)
|
|
||||||
6. Core feature highlight (day 9-11)
|
|
||||||
7. Conversion (day 12-14)
|
|
||||||
|
|
||||||
### Lead Nurture Sequence (Pre-Sale)
|
### Equipment Launch Sequence (Distributor/Contractor)
|
||||||
**Length**: 6-8 emails over 2-3 weeks
|
**Length**: 5 emails over 3 weeks
|
||||||
**Goal**: Build trust, demonstrate expertise, convert
|
**Goal**: Drive awareness, spec familiarity, early adoption
|
||||||
|
|
||||||
Key emails:
|
Key emails:
|
||||||
1. Deliver lead magnet + intro (immediate)
|
1. Product announcement + key specs (immediate)
|
||||||
2. Expand on topic (day 2-3)
|
2. Technical deep-dive or performance data (day 2-3)
|
||||||
3. Problem deep-dive (day 4-5)
|
3. Competitive comparison (day 5-7)
|
||||||
4. Solution framework (day 6-8)
|
4. Contractor case study or win story (day 10-12)
|
||||||
5. Case study (day 9-11)
|
5. Launch incentive or early availability (day 14-18)
|
||||||
6. Differentiation (day 12-14)
|
|
||||||
7. Objection handler (day 15-18)
|
|
||||||
8. Direct offer (day 19-21)
|
|
||||||
|
|
||||||
### Re-Engagement Sequence
|
### Post-Installation Follow-Up (Service Company)
|
||||||
**Length**: 3-4 emails over 2 weeks
|
**Length**: 3 emails over 30 days
|
||||||
**Trigger**: 30-60 days of inactivity
|
**Goal**: Ensure satisfaction, prevent callbacks, upsell maintenance plans
|
||||||
**Goal**: Win back or clean list
|
|
||||||
|
|
||||||
Key emails:
|
Key emails:
|
||||||
1. Check-in (genuine concern)
|
1. "Thanks for choosing us" + maintenance tips (immediate)
|
||||||
2. Value reminder (what's new)
|
2. System optimization advice (day 7)
|
||||||
3. Incentive (special offer)
|
3. Maintenance plan offer (day 21-30)
|
||||||
4. Last chance (stay or unsubscribe)
|
|
||||||
|
|
||||||
### Onboarding Sequence (Product Users)
|
### Training/Certification Sequence
|
||||||
**Length**: 5-7 emails over 14 days
|
**Length**: 6-8 emails over program duration
|
||||||
**Goal**: Activate, drive to aha moment, upgrade
|
**Goal**: Enroll, engage, complete course, support adoption
|
||||||
**Note**: Coordinate with in-app onboarding—email supports, doesn't duplicate
|
|
||||||
|
|
||||||
Key emails:
|
Key emails:
|
||||||
1. Welcome + first step (immediate)
|
1. Course welcome + getting started (immediate)
|
||||||
2. Getting started help (day 1)
|
2. Week 1 module + encouragement (day 2-3)
|
||||||
3. Feature highlight (day 2-3)
|
3. Success story from past students (day 7)
|
||||||
4. Success story (day 4-5)
|
4. Mid-course check-in (day 14)
|
||||||
5. Check-in (day 7)
|
5. Advanced topics unlock (day 21)
|
||||||
6. Advanced tip (day 10-12)
|
6. Final module + exam prep (day 28)
|
||||||
7. Upgrade/expand (day 14+)
|
7. Certification celebration + next steps (day 35+)
|
||||||
|
|
||||||
|
### Newsletter Sequence (Industry Updates)
|
||||||
|
**Length**: Monthly (1 email) + seasonal deep-dives
|
||||||
|
**Goal**: Build authority, keep subscribers engaged, drive referrals
|
||||||
|
|
||||||
|
Key emails:
|
||||||
|
1. Monthly update (industry news, HVAC tips, standards changes)
|
||||||
|
2. Quarterly deep-dive (longer form, technical focus)
|
||||||
|
3. Seasonal special (winter/summer focus on common issues)
|
||||||
|
|
||||||
**For detailed templates**: See [references/sequence-templates.md](references/sequence-templates.md)
|
**For detailed templates**: See [references/sequence-templates.md](references/sequence-templates.md)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Email Types by Category
|
## HVAC Email Types by Category
|
||||||
|
|
||||||
### Onboarding Emails
|
### Maintenance & Seasonal Emails
|
||||||
- New users series
|
- Pre-season system checks (summer cooling, winter heating)
|
||||||
- New customers series
|
- Annual maintenance reminders
|
||||||
- Key onboarding step reminders
|
- Seasonal tip series (humidity control, energy savings)
|
||||||
- New user invites
|
- Filter replacement reminders
|
||||||
|
- System optimization tips
|
||||||
|
|
||||||
### Retention Emails
|
### Equipment & Sales Emails
|
||||||
- Upgrade to paid
|
- New equipment announcements
|
||||||
- Upgrade to higher plan
|
- Performance comparison guides
|
||||||
- Ask for review
|
- Equipment compatibility checks
|
||||||
- Proactive support offers
|
- Spec sheets and tech data downloads
|
||||||
- Product usage reports
|
- Upgrade/expansion offers
|
||||||
- NPS survey
|
|
||||||
- Referral program
|
|
||||||
|
|
||||||
### Billing Emails
|
### Service Company Emails
|
||||||
- Switch to annual
|
- Post-installation follow-up
|
||||||
- Failed payment recovery
|
- Service completion confirmation
|
||||||
- Cancellation survey
|
- Upsell maintenance plans
|
||||||
- Upcoming renewal reminders
|
- Emergency service notifications
|
||||||
|
- Customer testimonial requests
|
||||||
|
|
||||||
### Usage Emails
|
### Training & Education Emails
|
||||||
- Daily/weekly/monthly summaries
|
- Certification enrollment confirmations
|
||||||
- Key event notifications
|
- Course module releases
|
||||||
- Milestone celebrations
|
- Webinar announcements
|
||||||
|
- Technical training updates
|
||||||
|
- Standards compliance education (SEER2, regional codes)
|
||||||
|
|
||||||
### Win-Back Emails
|
### Contractor Partnership Emails
|
||||||
- Expired trials
|
- New distributor partner onboarding
|
||||||
- Cancelled customers
|
- Contractor incentive programs
|
||||||
|
- Lead generation program updates
|
||||||
|
- Co-marketing opportunity invitations
|
||||||
|
- Volume incentive promotions
|
||||||
|
|
||||||
### Campaign Emails
|
### Newsletter & Content Emails
|
||||||
- Monthly roundup / newsletter
|
- Monthly HVAC industry updates
|
||||||
- Seasonal promotions
|
- Regulatory/standard change notifications
|
||||||
- Product updates
|
- Success story highlights
|
||||||
- Industry news roundup
|
- Referral program updates
|
||||||
- Pricing updates
|
- Event/webinar announcements
|
||||||
|
|
||||||
**For detailed email type reference**: See [references/email-types.md](references/email-types.md)
|
**For detailed email type reference**: See [references/email-types.md](references/email-types.md)
|
||||||
|
|
||||||
|
|
@ -285,25 +294,23 @@ What to measure and benchmarks
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tool Integrations
|
---
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email tools:
|
## Compendium Integration
|
||||||
|
|
||||||
| Tool | Best For | MCP | Guide |
|
Email sequences for HVAC can leverage Compendium's content and timing data:
|
||||||
|------|----------|:---:|-------|
|
|
||||||
| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) |
|
- **Database Tools**: Use seasonal trend data (`mv_topic_trends_weekly`) to time maintenance reminders and equipment launches
|
||||||
| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) |
|
- **Fetch Tools**: Pull recent industry news, standards updates, and contractor/homeowner content for newsletter ideas
|
||||||
| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) |
|
- **Analytics**: Track what topics generate engagement to inform sequence content
|
||||||
| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) |
|
|
||||||
| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) |
|
**Tool Tiers**: Enhanced mode — requires database and fetch capabilities
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **churn-prevention**: For cancel flows, save offers, and dunning strategy (email supports this)
|
- **copywriting**: For email copy and body content
|
||||||
- **onboarding-cro**: For in-app onboarding (email supports this)
|
- **content-strategy**: For broader content and lifecycle planning
|
||||||
- **copywriting**: For landing pages emails link to
|
- **social-content**: For repurposing email content to social media
|
||||||
- **ab-test-setup**: For testing email elements
|
- **cold-email**: For B2B contractor and distributor outreach
|
||||||
- **popup-cro**: For email capture popups
|
|
||||||
- **revops**: For lifecycle stages that trigger email sequences
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Create a welcome email sequence for new users who sign up for our project management tool's free trial. The trial is 14 days. We want to get them to their aha moment (creating their first project and inviting a team member).",
|
"prompt": "Create a welcome email sequence for new users who sign up for our project management tool's free trial. The trial is 14 days. We want to get them to their aha moment (creating their first project and inviting a team member).",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should create a welcome sequence (5-7 emails) following the core principles: one email one job, value before ask. Should map each email to a specific goal in the 14-day trial journey. Should include timing/delays between emails. Each email should follow the email copy structure: hook → context → value → CTA → sign-off. Should include subject lines following the subject line strategy. Should align sequence with the aha moment (first project + team invite). Output should follow the structured format with sequence overview and per-email specs.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should create a welcome sequence (5-7 emails) following the core principles: one email one job, value before ask. Should map each email to a specific goal in the 14-day trial journey. Should include timing/delays between emails. Each email should follow the email copy structure: hook → context → value → CTA → sign-off. Should include subject lines following the subject line strategy. Should align sequence with the aha moment (first project + team invite). Output should follow the structured format with sequence overview and per-email specs.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Creates 5-7 email welcome sequence",
|
"Creates 5-7 email welcome sequence",
|
||||||
"Follows one email one job principle",
|
"Follows one email one job principle",
|
||||||
"Maps emails to trial timeline (14 days)",
|
"Maps emails to trial timeline (14 days)",
|
||||||
|
|
@ -80,10 +80,8 @@
|
||||||
{
|
{
|
||||||
"id": 6,
|
"id": 6,
|
||||||
"prompt": "Help me optimize our post-signup onboarding experience. Users sign up but 60% never complete setup.",
|
"prompt": "Help me optimize our post-signup onboarding experience. Users sign up but 60% never complete setup.",
|
||||||
"expected_output": "Should recognize this is an in-app onboarding optimization task, not an email sequence task. Should defer to or cross-reference the onboarding-cro skill, which handles in-app onboarding flows, checklists, and activation optimization. May offer to help with the email component of onboarding but should make clear that onboarding-cro is the primary skill for this task.",
|
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Recognizes this as in-app onboarding optimization",
|
"Recognizes this as in-app onboarding optimization",
|
||||||
"References or defers to onboarding-cro skill",
|
|
||||||
"Does not attempt full onboarding redesign using email patterns",
|
"Does not attempt full onboarding redesign using email patterns",
|
||||||
"May offer email component support"
|
"May offer email component support"
|
||||||
],
|
],
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: form-cro
|
name: form-cro
|
||||||
description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," "contact form," "nobody fills out our form," "form abandonment," "too many fields," "demo request form," or "lead form isn't converting." Use this for any non-signup form that captures information. For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro.
|
description: "When the user wants to optimize any form — including quote request forms, service scheduling forms, maintenance agreement signups, or multi-step forms. Also use when the user mentions 'form optimization,' 'form conversions,' 'form abandonment,' 'form friction,' 'too many fields,' 'nobody fills out my form,' 'form completion rate,' or 'form UX.' For general page conversion optimization, see page-cro. For popups/modals, see hvac-estimate-popups."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [browse, scrape]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Form CRO
|
# Form CRO
|
||||||
|
|
@ -12,18 +15,17 @@ You are an expert in form optimization. Your goal is to maximize form completion
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 providing recommendations, identify:
|
Before providing recommendations, identify:
|
||||||
|
|
||||||
1. **Form Type**
|
1. **Form Type**
|
||||||
- Lead capture (gated content, newsletter)
|
- Quote request (with service type)
|
||||||
- Contact form
|
- Service scheduling
|
||||||
- Demo/sales request
|
- Maintenance agreement signup
|
||||||
- Application form
|
- Customer survey (post-service)
|
||||||
- Survey/feedback
|
- Newsletter signup
|
||||||
- Checkout form
|
- Multi-step estimate form
|
||||||
- Quote request
|
|
||||||
|
|
||||||
2. **Current State**
|
2. **Current State**
|
||||||
- How many fields?
|
- How many fields?
|
||||||
|
|
@ -33,7 +35,7 @@ Before providing recommendations, identify:
|
||||||
|
|
||||||
3. **Business Context**
|
3. **Business Context**
|
||||||
- What happens with form submissions?
|
- What happens with form submissions?
|
||||||
- Which fields are actually used in follow-up?
|
- Which fields are actually used for follow-up?
|
||||||
- Are there compliance/legal requirements?
|
- Are there compliance/legal requirements?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -49,12 +51,12 @@ Each field reduces completion rate. Rule of thumb:
|
||||||
For each field, ask:
|
For each field, ask:
|
||||||
- Is this absolutely necessary before we can help them?
|
- Is this absolutely necessary before we can help them?
|
||||||
- Can we get this information another way?
|
- Can we get this information another way?
|
||||||
- Can we ask this later?
|
- Can we ask this later (during phone call)?
|
||||||
|
|
||||||
### 2. Value Must Exceed Effort
|
### 2. Value Must Exceed Effort
|
||||||
- Clear value proposition above form
|
- Clear value proposition above form ("Free, no-obligation quote")
|
||||||
- Make what they get obvious
|
- Make what they get obvious
|
||||||
- Reduce perceived effort (field count, labels)
|
- Reduce perceived effort (minimize fields)
|
||||||
|
|
||||||
### 3. Reduce Cognitive Load
|
### 3. Reduce Cognitive Load
|
||||||
- One question per field
|
- One question per field
|
||||||
|
|
@ -72,62 +74,58 @@ For each field, ask:
|
||||||
- Typo detection (did you mean gmail.com?)
|
- Typo detection (did you mean gmail.com?)
|
||||||
- Proper mobile keyboard
|
- Proper mobile keyboard
|
||||||
|
|
||||||
### Name Fields
|
### Name Field
|
||||||
- Single "Name" vs. First/Last — test this
|
- Single "Name" vs. First/Last — test this
|
||||||
- Single field reduces friction
|
- Single field reduces friction
|
||||||
- Split needed only if personalization requires it
|
- Split needed only if personalization requires it
|
||||||
|
|
||||||
### Phone Number
|
### Phone Number
|
||||||
- Make optional if possible
|
- Make optional if email is required, OR primary CTA should be "Call Now" not "Get Quote"
|
||||||
- If required, explain why
|
- If required, explain why upfront
|
||||||
- Auto-format as they type
|
- Auto-format as they type
|
||||||
- Country code handling
|
- Click-to-call on mobile (tel: link)
|
||||||
|
|
||||||
### Company/Organization
|
### Service Type
|
||||||
- Auto-suggest for faster entry
|
- Essential for routing quotes
|
||||||
- Enrichment after submission (Clearbit, etc.)
|
- Dropdown or buttons (don't make it hard)
|
||||||
- Consider inferring from email domain
|
|
||||||
|
|
||||||
### Job Title/Role
|
|
||||||
- Dropdown if categories matter
|
|
||||||
- Free text if wide variation
|
|
||||||
- Consider making optional
|
|
||||||
|
|
||||||
### Message/Comments (Free Text)
|
|
||||||
- Make optional
|
|
||||||
- Reasonable character guidance
|
|
||||||
- Expand on focus
|
|
||||||
|
|
||||||
### Dropdown Selects
|
|
||||||
- "Select one..." placeholder
|
|
||||||
- Searchable if many options
|
|
||||||
- Consider radio buttons if < 5 options
|
|
||||||
- "Other" option with text field
|
- "Other" option with text field
|
||||||
|
|
||||||
### Checkboxes (Multi-select)
|
### Property Type
|
||||||
- Clear, parallel labels
|
- House, multi-family, commercial — affects quote complexity
|
||||||
- Reasonable number of options
|
- Dropdown or buttons
|
||||||
- Consider "Select all that apply" instruction
|
|
||||||
|
### Issue Description
|
||||||
|
- Optional text field ("What's wrong with your AC?")
|
||||||
|
- Make optional; clarify during call
|
||||||
|
- Reasonable character guidance
|
||||||
|
|
||||||
|
### Urgency/Timeline
|
||||||
|
- "Needs repair today" vs. "routine maintenance" → affects routing
|
||||||
|
- Dropdown or buttons
|
||||||
|
- Can help with emergency service upsells
|
||||||
|
|
||||||
|
### Best Practices for All Fields**
|
||||||
|
- Labels: Keep visible (not just placeholder)
|
||||||
|
- Placeholders: Examples, not labels
|
||||||
|
- Help text: Only when genuinely helpful
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Form Layout Optimization
|
## Form Layout Optimization
|
||||||
|
|
||||||
### Field Order
|
### Field Order
|
||||||
1. Start with easiest fields (name, email)
|
1. Start with easiest fields (name, phone)
|
||||||
2. Build commitment before asking more
|
2. Build commitment before asking more
|
||||||
3. Sensitive fields last (phone, company size)
|
3. Service type and issue earlier (helps routing)
|
||||||
4. Logical grouping if many fields
|
4. Sensitive fields last if any
|
||||||
|
5. Logical grouping if many fields
|
||||||
|
|
||||||
### Labels and Placeholders
|
### Labels and Placeholders
|
||||||
- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in
|
|
||||||
- Placeholders: Examples, not labels
|
|
||||||
- Help text: Only when genuinely helpful
|
|
||||||
|
|
||||||
**Good:**
|
**Good:**
|
||||||
```
|
```
|
||||||
Email
|
Email
|
||||||
[name@company.com]
|
[name@example.com]
|
||||||
```
|
```
|
||||||
|
|
||||||
**Bad:**
|
**Bad:**
|
||||||
|
|
@ -138,12 +136,12 @@ Email
|
||||||
### Visual Design
|
### Visual Design
|
||||||
- Sufficient spacing between fields
|
- Sufficient spacing between fields
|
||||||
- Clear visual hierarchy
|
- Clear visual hierarchy
|
||||||
- CTA button stands out
|
- CTA button stands out (green, contrasting color)
|
||||||
- Mobile-friendly tap targets (44px+)
|
- Mobile-friendly tap targets (44px+)
|
||||||
|
|
||||||
### Single Column vs. Multi-Column
|
### Single Column vs. Multi-Column
|
||||||
- Single column: Higher completion, mobile-friendly
|
- Single column: Higher completion, mobile-friendly
|
||||||
- Multi-column: Only for short related fields (First/Last name)
|
- Multi-column: Only for short related fields (Name + Phone)
|
||||||
- When in doubt, single column
|
- When in doubt, single column
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -152,23 +150,23 @@ Email
|
||||||
|
|
||||||
### When to Use Multi-Step
|
### When to Use Multi-Step
|
||||||
- More than 5-6 fields
|
- More than 5-6 fields
|
||||||
- Logically distinct sections
|
- Logically distinct sections (Contact info → Service selection → Details)
|
||||||
- Conditional paths based on answers
|
- Conditional paths based on answers
|
||||||
- Complex forms (applications, quotes)
|
- Complex estimates
|
||||||
|
|
||||||
### Multi-Step Best Practices
|
### Multi-Step Best Practices
|
||||||
- Progress indicator (step X of Y)
|
- Progress indicator (step X of Y)
|
||||||
- Start with easy, end with sensitive
|
- Start with easy, end with technical details
|
||||||
- One topic per step
|
- One topic per step
|
||||||
- Allow back navigation
|
- Allow back navigation
|
||||||
- Save progress (don't lose data on refresh)
|
- Save progress (don't lose data on refresh)
|
||||||
- Clear indication of required vs. optional
|
- Clear indication of required vs. optional
|
||||||
|
|
||||||
### Progressive Commitment Pattern
|
### Progressive Commitment Pattern
|
||||||
1. Low-friction start (just email)
|
1. Easy start (name, phone, email)
|
||||||
2. More detail (name, company)
|
2. Service selection (what needs fixing?)
|
||||||
3. Qualifying questions
|
3. Issue details (describe the problem)
|
||||||
4. Contact preferences
|
4. Preferences (best time to call, urgency)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -185,7 +183,7 @@ Email
|
||||||
- Positioned near the field
|
- Positioned near the field
|
||||||
- Don't clear their input
|
- Don't clear their input
|
||||||
|
|
||||||
**Good:** "Please enter a valid email address (e.g., name@company.com)"
|
**Good:** "Please enter a valid phone number (e.g., 555-123-4567)"
|
||||||
**Bad:** "Invalid input"
|
**Bad:** "Invalid input"
|
||||||
|
|
||||||
### On Submit
|
### On Submit
|
||||||
|
|
@ -204,20 +202,20 @@ Strong: "[Action] + [What they get]"
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
- "Get My Free Quote"
|
- "Get My Free Quote"
|
||||||
- "Download the Guide"
|
- "Schedule Service Today"
|
||||||
- "Request Demo"
|
- "Claim Maintenance Special"
|
||||||
- "Send Message"
|
- "Send My Request"
|
||||||
- "Start Free Trial"
|
|
||||||
|
|
||||||
### Button Placement
|
### Button Placement
|
||||||
- Immediately after last field
|
- Immediately after last field
|
||||||
- Left-aligned with fields
|
- Left-aligned with fields
|
||||||
- Sufficient size and contrast
|
- Sufficient size and contrast
|
||||||
- Mobile: Sticky or clearly visible
|
- Mobile: Sticky or clearly visible
|
||||||
|
- On mobile, consider "Call Now" button instead
|
||||||
|
|
||||||
### Post-Submit States
|
### Post-Submit States
|
||||||
- Loading state (disable button, show spinner)
|
- Loading state (disable button, show spinner)
|
||||||
- Success confirmation (clear next steps)
|
- Success confirmation (clear next steps: "We'll call you within 2 hours")
|
||||||
- Error handling (clear message, focus on issue)
|
- Error handling (clear message, focus on issue)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -225,55 +223,51 @@ Examples:
|
||||||
## Trust and Friction Reduction
|
## Trust and Friction Reduction
|
||||||
|
|
||||||
### Near the Form
|
### Near the Form
|
||||||
- Privacy statement: "We'll never share your info"
|
- Privacy statement: "We'll never spam your number"
|
||||||
- Security badges if collecting sensitive data
|
- Phone required? Explain why upfront: "So we can call within 2 hours"
|
||||||
|
- Trust badges (BBB, certified, licensed)
|
||||||
- Testimonial or social proof
|
- Testimonial or social proof
|
||||||
- Expected response time
|
- Expected response time: "We'll call you within 2 hours"
|
||||||
|
|
||||||
### Reducing Perceived Effort
|
### Reducing Perceived Effort
|
||||||
- "Takes 30 seconds"
|
- "Takes 60 seconds"
|
||||||
- Field count indicator
|
- Field count indicator: "Just 4 quick questions"
|
||||||
- Remove visual clutter
|
- Remove visual clutter
|
||||||
- Generous white space
|
- Generous white space
|
||||||
|
|
||||||
### Addressing Objections
|
### Addressing Objections
|
||||||
- "No spam, unsubscribe anytime"
|
- "Free, no-obligation quote"
|
||||||
- "We won't share your number"
|
- "We won't spam your number"
|
||||||
- "No credit card required"
|
- "Licensed and insured"
|
||||||
|
- "Serving [City] for [X] years"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Form Types: Specific Guidance
|
## Form Types: Specific Guidance
|
||||||
|
|
||||||
### Lead Capture (Gated Content)
|
### Quote Request Form
|
||||||
- Minimum viable fields (often just email)
|
- Essential: Name, Phone, Service type (or property type if multi-service)
|
||||||
- Clear value proposition for what they get
|
- Optional: Email, Issue description, Urgency
|
||||||
- Consider asking enrichment questions post-download
|
- Consider asking enrichment after submission
|
||||||
- Test email-only vs. email + name
|
- Test phone-only vs. phone + email
|
||||||
|
|
||||||
### Contact Form
|
### Service Scheduling Form
|
||||||
- Essential: Email/Name + Message
|
- Name, Phone, Preferred date/time required
|
||||||
- Phone optional
|
- Address/property type essential
|
||||||
- Set response time expectations
|
- Issue type dropdown
|
||||||
- Offer alternatives (chat, phone)
|
- Set clear expectations: "We'll confirm within 1 hour"
|
||||||
|
|
||||||
### Demo Request
|
### Maintenance Agreement Signup
|
||||||
- Name, Email, Company required
|
- Name, Address, Phone required
|
||||||
- Phone: Optional with "preferred contact" choice
|
- Property type, age of HVAC system
|
||||||
- Use case/goal question helps personalize
|
- Budget/preferences for pricing
|
||||||
- Calendar embed can increase show rate
|
- Contact frequency preferences
|
||||||
|
|
||||||
### Quote/Estimate Request
|
### Post-Service Survey (optional)
|
||||||
- Multi-step often works well
|
- 1-5 stars on technician
|
||||||
- Start with easy questions
|
- 1-5 stars on overall service
|
||||||
- Technical details later
|
- Brief text feedback
|
||||||
- Save progress for complex forms
|
- Willingness to refer
|
||||||
|
|
||||||
### Survey Forms
|
|
||||||
- Progress bar essential
|
|
||||||
- One question per screen for engagement
|
|
||||||
- Skip logic for relevance
|
|
||||||
- Consider incentive for completion
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -338,75 +332,35 @@ Ideas to A/B test with expected outcomes
|
||||||
- Single-step form vs. multi-step with progress bar
|
- Single-step form vs. multi-step with progress bar
|
||||||
- 1-column vs. 2-column field layout
|
- 1-column vs. 2-column field layout
|
||||||
- Form embedded on page vs. separate page
|
- Form embedded on page vs. separate page
|
||||||
- Vertical vs. horizontal field alignment
|
- Phone-first CTA vs. quote form first
|
||||||
- Form above fold vs. after content
|
|
||||||
|
|
||||||
**Field Optimization**
|
**Field Optimization**
|
||||||
- Reduce to minimum viable fields
|
- Reduce to minimum viable fields
|
||||||
- Add or remove phone number field
|
- Add or remove phone number field
|
||||||
- Add or remove company/organization field
|
- Add or remove email field
|
||||||
- Test required vs. optional field balance
|
- Make phone required vs. optional
|
||||||
- Use field enrichment to auto-fill known data
|
- Change field order (urgency first vs. last)
|
||||||
- Hide fields for returning/known visitors
|
|
||||||
|
|
||||||
**Smart Forms**
|
**Mobile Variations**
|
||||||
- Add real-time validation for emails and phone numbers
|
- Click-to-call button vs. form
|
||||||
- Progressive profiling (ask more over time)
|
- Sticky submit vs. scrolling
|
||||||
- Conditional fields based on earlier answers
|
- Single vs. multi-column on mobile
|
||||||
- Auto-suggest for company names
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Copy & Design Experiments
|
## Compendium Integration
|
||||||
|
|
||||||
**Labels & Microcopy**
|
This skill can be enhanced using **Compendium** competitor analysis and HVAC industry data.
|
||||||
- Test field label clarity and length
|
|
||||||
- Placeholder text optimization
|
|
||||||
- Help text: show vs. hide vs. on-hover
|
|
||||||
- Error message tone (friendly vs. direct)
|
|
||||||
|
|
||||||
**CTAs & Buttons**
|
**Relevant Compendium capabilities:**
|
||||||
- Button text variations ("Submit" vs. "Get My Quote" vs. specific action)
|
- **Browse & Scrape**: Analyze competitor quote forms to benchmark fields, layout, and conversion optimization
|
||||||
- Button color and size testing
|
- **Search**: Identify industry best practices for HVAC form design
|
||||||
- Button placement relative to fields
|
|
||||||
|
|
||||||
**Trust Elements**
|
**When to use Compendium:**
|
||||||
- Add privacy assurance near form
|
- Benchmarking your form against competitor forms
|
||||||
- Show trust badges next to submit
|
- Finding emerging best practices for service booking forms
|
||||||
- Add testimonial near form
|
|
||||||
- Display expected response time
|
|
||||||
|
|
||||||
---
|
See [COMPENDIUM_INTEGRATION.md](../COMPENDIUM_INTEGRATION.md) for detailed workflows.
|
||||||
|
|
||||||
### Form Type-Specific Experiments
|
|
||||||
|
|
||||||
**Demo Request Forms**
|
|
||||||
- Test with/without phone number requirement
|
|
||||||
- Add "preferred contact method" choice
|
|
||||||
- Include "What's your biggest challenge?" question
|
|
||||||
- Test calendar embed vs. form submission
|
|
||||||
|
|
||||||
**Lead Capture Forms**
|
|
||||||
- Email-only vs. email + name
|
|
||||||
- Test value proposition messaging above form
|
|
||||||
- Gated vs. ungated content strategies
|
|
||||||
- Post-submission enrichment questions
|
|
||||||
|
|
||||||
**Contact Forms**
|
|
||||||
- Add department/topic routing dropdown
|
|
||||||
- Test with/without message field requirement
|
|
||||||
- Show alternative contact methods (chat, phone)
|
|
||||||
- Expected response time messaging
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Mobile & UX Experiments
|
|
||||||
|
|
||||||
- Larger touch targets for mobile
|
|
||||||
- Test appropriate keyboard types by field
|
|
||||||
- Sticky submit button on mobile
|
|
||||||
- Auto-focus first field on page load
|
|
||||||
- Test form container styling (card vs. minimal)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -423,7 +377,6 @@ Ideas to A/B test with expected outcomes
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **signup-flow-cro**: For account creation forms
|
- **hvac-estimate-popups**: For forms inside popups/modals
|
||||||
- **popup-cro**: For forms inside popups/modals
|
|
||||||
- **page-cro**: For the page containing the form
|
- **page-cro**: For the page containing the form
|
||||||
- **ab-test-setup**: For testing form changes
|
- **ab-test-setup**: For testing form changes
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"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.",
|
"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.",
|
"expected_output": "Should check for hvac-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": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies 'every field has a cost' principle",
|
"Applies 'every field has a cost' principle",
|
||||||
"References field count impact data",
|
"References field count impact data",
|
||||||
"Evaluates each field for necessity",
|
"Evaluates each field for necessity",
|
||||||
|
|
@ -78,10 +78,8 @@
|
||||||
{
|
{
|
||||||
"id": 6,
|
"id": 6,
|
||||||
"prompt": "Our signup form has too many fields and people keep abandoning it halfway through. Can you help optimize it?",
|
"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": [
|
"assertions": [
|
||||||
"Recognizes this as signup flow optimization",
|
"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"
|
"Does not attempt full signup form optimization using general form CRO patterns"
|
||||||
],
|
],
|
||||||
"files": []
|
"files": []
|
||||||
|
|
|
||||||
|
|
@ -1,40 +1,43 @@
|
||||||
---
|
---
|
||||||
name: free-tool-strategy
|
name: free-tool-strategy
|
||||||
description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," "free resource," "ROI calculator," "grader tool," "audit tool," "should I build a free tool," or "tools for lead gen." Use this whenever someone wants to build something useful and give it away to attract leads or earn links. For content-based lead generation, see content-strategy.
|
description: "When the user wants to plan, evaluate, or build a free HVAC tool for marketing purposes — lead generation, SEO value, or customer education. Also use when the user mentions 'free tool,' 'calculator,' 'ROI calculator,' 'load calculator,' 'energy savings estimator,' 'refrigerant calculator,' 'sizing tool,' 'maintenance tracker,' 'should I build a tool,' 'marketing tool,' or 'lead gen tool.' Use whenever someone wants to build something useful and give it away to attract leads or provide customer value."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Free Tool Strategy (Engineering as Marketing)
|
# HVAC Free Tool Strategy (Engineering as Marketing)
|
||||||
|
|
||||||
You are an expert in engineering-as-marketing strategy. Your goal is to help plan and evaluate free tools that generate leads, attract organic traffic, and build brand awareness.
|
You are an expert in free tool strategy for HVAC. Your goal is to help plan and evaluate free tools that generate leads, attract organic traffic, educate customers, and build brand authority.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 designing a tool strategy, understand:
|
Before designing a tool strategy, understand:
|
||||||
|
|
||||||
1. **Business Context** - What's the core product? Who is the target audience? What problems do they have?
|
1. **Business Context** - Contractor, distributor, or equipment manufacturer? What problems do you solve?
|
||||||
|
|
||||||
2. **Goals** - Lead generation? SEO/traffic? Brand awareness? Product education?
|
2. **Goals** - Lead generation? Customer education? Organic traffic? Brand authority?
|
||||||
|
|
||||||
3. **Resources** - Technical capacity to build? Ongoing maintenance bandwidth? Budget for promotion?
|
3. **Resources** - Technical capacity to build? Ongoing maintenance? Budget?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Core Principles
|
## Core Principles
|
||||||
|
|
||||||
### 1. Solve a Real Problem
|
### 1. Solve a Real Problem
|
||||||
- Tool must provide genuine value
|
- Homeowners and contractors actually use the tool
|
||||||
- Solves a problem your audience actually has
|
- Saves them time or money
|
||||||
- Useful even without your main product
|
- Useful even without your main product
|
||||||
|
|
||||||
### 2. Adjacent to Core Product
|
### 2. Adjacent to Core Business
|
||||||
- Related to what you sell
|
- Related to what you sell
|
||||||
- Natural path from tool to product
|
- Natural path from tool to service
|
||||||
- Educates on problem you solve
|
- Positions you as expert
|
||||||
|
|
||||||
### 3. Simple and Focused
|
### 3. Simple and Focused
|
||||||
- Does one thing well
|
- Does one thing well
|
||||||
|
|
@ -46,39 +49,105 @@ Before designing a tool strategy, understand:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tool Types Overview
|
## HVAC Tool Types
|
||||||
|
|
||||||
| Type | Examples | Best For |
|
| Type | Examples | Best For | Lead Value |
|
||||||
|------|----------|----------|
|
|------|----------|----------|---|
|
||||||
| Calculators | ROI, savings, pricing estimators | Decisions involving numbers |
|
| **Calculators** | Load calculator, energy savings, ROI estimator | Decisions involving numbers | High (intent-driven) |
|
||||||
| Generators | Templates, policies, names | Creating something quickly |
|
| **Estimators** | Equipment size estimator, cost range | Customer planning | High |
|
||||||
| Analyzers | Website graders, SEO auditors | Evaluating existing work |
|
| **Assessors** | Home energy audit, maintenance checklist | Identifying problems | Medium-High |
|
||||||
| Testers | Meta tag preview, speed tests | Checking if something works |
|
| **Trackers** | Maintenance schedule, filter change tracker | Retention and upsell | Medium |
|
||||||
| Libraries | Icon sets, templates, snippets | Reference material |
|
| **Comparators** | Equipment comparison, heat pump vs. furnace | Educational, decision support | Medium |
|
||||||
| Interactive | Tutorials, playgrounds, quizzes | Learning/understanding |
|
| **Tools** | Refrigerant charge calculator, ductwork designer | Technical/contractor | Medium |
|
||||||
|
|
||||||
**For detailed tool types and examples**: See [references/tool-types.md](references/tool-types.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Ideation Framework
|
## HVAC Calculator Ideas
|
||||||
|
|
||||||
### Start with Pain Points
|
### 1. Heating/Cooling Load Calculator
|
||||||
|
|
||||||
1. **What problems does your audience Google?** - Search query research, common questions
|
**What it does**: Customer inputs home size, insulation, climate, and tool calculates required BTU capacity
|
||||||
|
|
||||||
2. **What manual processes are tedious?** - Spreadsheet tasks, repetitive calculations
|
**Why valuable**:
|
||||||
|
- Many homeowners oversize AC (wastes money)
|
||||||
|
- Undersized systems can't keep up
|
||||||
|
- Creates sense of need for professional assessment
|
||||||
|
- Natural path: "Get professional load calculation"
|
||||||
|
|
||||||
3. **What do they need before buying your product?** - Assessments, planning, comparisons
|
**Lead quality**: High (owner of home, considering replacement)
|
||||||
|
|
||||||
4. **What information do they wish they had?** - Data they can't easily access, benchmarks
|
**Build effort**: Medium (requires HVAC calculation formula)
|
||||||
|
|
||||||
### Validate the Idea
|
**Data source**: Compendium `intelligence.statistics` for climate zones and efficiency data
|
||||||
|
|
||||||
- **Search demand**: Is there search volume? How competitive?
|
### 2. Energy Savings Estimator
|
||||||
- **Uniqueness**: What exists? How can you be 10x better?
|
|
||||||
- **Lead quality**: Does this audience match buyers?
|
**What it does**: Customer inputs current system efficiency, local energy rates, and tool calculates annual savings from upgrade
|
||||||
- **Build feasibility**: How complex? Can you scope an MVP?
|
|
||||||
|
**Example**:
|
||||||
|
- Current: 13 SEER AC (old system)
|
||||||
|
- New: 20 SEER AC (high-efficiency)
|
||||||
|
- Difference: ~$300/year savings
|
||||||
|
- 10-year savings: $3,000
|
||||||
|
- Less cost of new system = ROI
|
||||||
|
|
||||||
|
**Why valuable**:
|
||||||
|
- Justifies equipment investment
|
||||||
|
- Makes efficiency investment tangible
|
||||||
|
- Addresses price objection with ROI
|
||||||
|
|
||||||
|
**Lead quality**: High (comparing costs, considering upgrade)
|
||||||
|
|
||||||
|
**Build effort**: Low (simple calculation)
|
||||||
|
|
||||||
|
### 3. Equipment Cost Range Estimator
|
||||||
|
|
||||||
|
**What it does**: Customer inputs system type and size, tool shows typical cost range for budget/mid/premium options
|
||||||
|
|
||||||
|
**Why valuable**:
|
||||||
|
- Homeowners have no idea what things cost
|
||||||
|
- Sets expectations before quote
|
||||||
|
- Reduces sticker shock
|
||||||
|
- Positions you as transparent
|
||||||
|
|
||||||
|
**Example**:
|
||||||
|
- Furnace Replacement (80K BTU): $2,500 - $4,500
|
||||||
|
- AC Replacement (3 ton): $3,000 - $5,000
|
||||||
|
- Heat Pump System: $5,000 - $8,000
|
||||||
|
|
||||||
|
**Lead quality**: Medium (awareness stage, not yet ready to buy)
|
||||||
|
|
||||||
|
**Build effort**: Low (lookup table)
|
||||||
|
|
||||||
|
### 4. Maintenance Schedule Tracker
|
||||||
|
|
||||||
|
**What it does**: Homeowner enters system model, tool sends email reminders for seasonal tune-ups and filter changes
|
||||||
|
|
||||||
|
**Why valuable**:
|
||||||
|
- Drives service call volume
|
||||||
|
- Positions you as helpful (not just selling)
|
||||||
|
- Email captures contact for future marketing
|
||||||
|
- Reduces customer churn (they call you for regular maintenance)
|
||||||
|
|
||||||
|
**Lead quality**: Medium (existing customer retention, not new leads)
|
||||||
|
|
||||||
|
**Build effort**: Medium (email automation needed)
|
||||||
|
|
||||||
|
### 5. Home Energy Audit Checklist
|
||||||
|
|
||||||
|
**What it does**: Interactive checklist of home energy efficiency issues (insulation, sealing, equipment age, thermostat, etc.)
|
||||||
|
|
||||||
|
**Output**: Printable report showing potential savings
|
||||||
|
|
||||||
|
**Why valuable**:
|
||||||
|
- Identifies problems homeowners didn't know about
|
||||||
|
- Creates sense of urgency (problem awareness)
|
||||||
|
- Natural path to professional audit
|
||||||
|
- Differentiates you as expert
|
||||||
|
|
||||||
|
**Lead quality**: High (problem-aware)
|
||||||
|
|
||||||
|
**Build effort**: Low (interactive form + scoring)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -88,57 +157,107 @@ Before designing a tool strategy, understand:
|
||||||
|
|
||||||
| Approach | Pros | Cons |
|
| Approach | Pros | Cons |
|
||||||
|----------|------|------|
|
|----------|------|------|
|
||||||
| Fully gated | Maximum capture | Lower usage |
|
| Fully gated (email required upfront) | Maximum capture | Lower usage |
|
||||||
| Partially gated | Balance of both | Common pattern |
|
| Results gated (free to calculate, email for detailed results) | Balance of both | Common pattern |
|
||||||
| Ungated + optional | Maximum reach | Lower capture |
|
| Ungated + optional | Maximum reach | Lower capture |
|
||||||
| Ungated entirely | Pure SEO/brand | No direct leads |
|
| Ungated entirely | Pure SEO/brand | No direct leads |
|
||||||
|
|
||||||
|
### Recommended: Results Gating
|
||||||
|
|
||||||
|
1. Tool is free to use (no email required)
|
||||||
|
2. Basic result is shown ("Your home needs ~3 tons AC")
|
||||||
|
3. "Get detailed savings estimate" requires email
|
||||||
|
4. Detailed PDF sent via email with offer
|
||||||
|
|
||||||
|
**Example**:
|
||||||
|
- Load calculator: Shows BTU requirement for free
|
||||||
|
- "Email me my savings estimate": Captures email, sends PDF with energy savings, financing options, call-to-action
|
||||||
|
|
||||||
### Lead Capture Best Practices
|
### Lead Capture Best Practices
|
||||||
- Value exchange clear: "Get your full report"
|
- Clear value exchange: "Get your savings estimate in 30 seconds"
|
||||||
- Minimal friction: Email only
|
- Minimal friction: Email only (don't ask for phone, address, etc. upfront)
|
||||||
- Show preview of what they'll get
|
- Show preview: "You'll see annual savings estimate + equipment cost range"
|
||||||
- Optional: Segment by asking one qualifying question
|
- Optional qualification: "What's your main concern?" (HVAC replacement, energy costs, comfort)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## SEO Considerations
|
## SEO Considerations
|
||||||
|
|
||||||
### Keyword Strategy
|
### Keyword Strategy
|
||||||
**Tool landing page**: "[thing] calculator", "[thing] generator", "free [tool type]"
|
|
||||||
|
|
||||||
**Supporting content**: "How to [use case]", "What is [concept]"
|
**Tool landing page targets**:
|
||||||
|
- "[Thing] calculator" ("HVAC calculator," "load calculator," "energy savings calculator")
|
||||||
|
- "Free [tool]" ("Free HVAC cost estimator," "Free maintenance tracker")
|
||||||
|
- "How much does [thing] cost" ("How much does AC replacement cost," "Furnace cost")
|
||||||
|
|
||||||
|
**Supporting content**:
|
||||||
|
- "How to use the [tool]"
|
||||||
|
- "What's a good [metric]" ("What's a good SEER rating," "What BTU do I need")
|
||||||
|
- Glossary articles linked from tool
|
||||||
|
|
||||||
### Link Building
|
### Link Building
|
||||||
|
|
||||||
Free tools attract links because:
|
Free tools attract links because:
|
||||||
- Genuinely useful (people reference them)
|
- Genuinely useful (people reference them)
|
||||||
- Unique (can't link to just any page)
|
- Unique (can't link to just any page)
|
||||||
- Shareable (social amplification)
|
- Shareable (embedded in blogs, articles)
|
||||||
|
|
||||||
|
**Outreach**:
|
||||||
|
- Blog posts mentioning HVAC costs → link to your calculator
|
||||||
|
- HVAC forums and Reddit discussions → mention tool
|
||||||
|
- Contractor associations → link from resources page
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Build vs. Buy
|
## Build vs. Buy vs. Embed
|
||||||
|
|
||||||
### Build Custom
|
### Build Custom
|
||||||
When: Unique concept, core to brand, high strategic value, have dev capacity
|
|
||||||
|
**When**: Unique concept, core to brand, high strategic value
|
||||||
|
|
||||||
|
**Effort**: 2-6 months + ongoing maintenance
|
||||||
|
|
||||||
|
**Cost**: $5,000 - $25,000+ development
|
||||||
|
|
||||||
|
**Best for**: Contractors building competitive moat
|
||||||
|
|
||||||
### Use No-Code Tools
|
### Use No-Code Tools
|
||||||
Options: Outgrow, Involve.me, Typeform, Tally, Bubble, Webflow
|
|
||||||
When: Speed to market, limited dev resources, testing concept
|
**Options**: Outgrow, Involve.me, Typeform, Bubble, Webflow
|
||||||
|
|
||||||
|
**Effort**: 2-4 weeks + minimal maintenance
|
||||||
|
|
||||||
|
**Cost**: $50 - $500/month SaaS fee
|
||||||
|
|
||||||
|
**Best for**: Quick MVP, limited dev resources, testing concept
|
||||||
|
|
||||||
### Embed Existing
|
### Embed Existing
|
||||||
When: Something good exists, white-label available, not core differentiator
|
|
||||||
|
**Options**: White-labeled solutions, calculator APIs, third-party tools
|
||||||
|
|
||||||
|
**Effort**: 1-2 weeks integration
|
||||||
|
|
||||||
|
**Cost**: $0 - $100/month (if white-label)
|
||||||
|
|
||||||
|
**Best for**: Quick launch, not core differentiator
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## MVP Scope
|
## MVP Scope
|
||||||
|
|
||||||
### Minimum Viable Tool
|
### Minimum Viable Tool
|
||||||
1. Core functionality only—does the one thing, works reliably
|
|
||||||
2. Essential UX—clear input, obvious output, mobile works
|
1. **Core functionality only** — Solves the problem, works reliably
|
||||||
3. Basic lead capture—email collection, leads go somewhere useful
|
2. **Essential UX** — Clear inputs, obvious output, mobile works
|
||||||
|
3. **Basic lead capture** — Email only, goes somewhere useful
|
||||||
|
|
||||||
### What to Skip Initially
|
### What to Skip Initially
|
||||||
Account creation, saving results, advanced features, perfect design, every edge case
|
|
||||||
|
- User accounts and login
|
||||||
|
- Saving results
|
||||||
|
- Advanced features
|
||||||
|
- Perfect design
|
||||||
|
- Every edge case
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -146,33 +265,81 @@ Account creation, saving results, advanced features, perfect design, every edge
|
||||||
|
|
||||||
Rate each factor 1-5:
|
Rate each factor 1-5:
|
||||||
|
|
||||||
| Factor | Score |
|
| Factor | Why It Matters | Score |
|
||||||
|--------|-------|
|
|--------|---|---|
|
||||||
| Search demand exists | ___ |
|
| **Search demand exists** | Will people find it? | ___ |
|
||||||
| Audience match to buyers | ___ |
|
| **Audience match to buyers** | Do searchers become customers? | ___ |
|
||||||
| Uniqueness vs. existing | ___ |
|
| **Uniqueness vs. existing** | What makes yours better? | ___ |
|
||||||
| Natural path to product | ___ |
|
| **Natural path to service** | Does it lead to your business? | ___ |
|
||||||
| Build feasibility | ___ |
|
| **Build feasibility** | Can you realistically build/maintain it? | ___ |
|
||||||
| Maintenance burden (inverse) | ___ |
|
| **Maintenance burden (inverse)** | How much upkeep does it need? | ___ |
|
||||||
| Link-building potential | ___ |
|
| **Link-building potential** | Will people link to it? | ___ |
|
||||||
| Share-worthiness | ___ |
|
| **Share-worthiness** | Will customers share/embed it? | ___ |
|
||||||
|
|
||||||
**25+**: Strong candidate | **15-24**: Promising | **<15**: Reconsider
|
**Scoring**:
|
||||||
|
- **25+**: Strong candidate, build it
|
||||||
|
- **15-24**: Promising, test with MVP first
|
||||||
|
- **<15**: Reconsider, focus on something else
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium intelligence to support tool strategy:
|
||||||
|
|
||||||
|
- **Market data**: 1,400+ HVAC statistics available via `intelligence.statistics`
|
||||||
|
- Regional climate zones and seasonal demand
|
||||||
|
- Energy efficiency benchmarks and savings data
|
||||||
|
- Equipment cost ranges and market averages
|
||||||
|
- Industry standard BTU calculations
|
||||||
|
|
||||||
|
- **Search research**: Identify calculator keywords and search volume
|
||||||
|
- **Competitor analysis**: See what free tools competitors offer
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Example: Energy Savings Calculator Build
|
||||||
|
|
||||||
|
**Timeline**: 2-3 weeks with no-code tool
|
||||||
|
|
||||||
|
**Inputs**:
|
||||||
|
- Current system efficiency (SEER)
|
||||||
|
- Monthly electricity cost
|
||||||
|
- New system efficiency (customer selects)
|
||||||
|
|
||||||
|
**Formula**:
|
||||||
|
```
|
||||||
|
Annual kWh savings = (Current SEER - New SEER) × Home cooling load × Hours per season
|
||||||
|
Annual $ savings = Annual kWh × Local electricity rate
|
||||||
|
10-year savings = Annual $ × 10 - Cost of new system
|
||||||
|
```
|
||||||
|
|
||||||
|
**Output**:
|
||||||
|
- Monthly savings: $X
|
||||||
|
- Annual savings: $X
|
||||||
|
- 10-year savings vs. cost: $X (ROI)
|
||||||
|
- [Email for detailed cost estimate]
|
||||||
|
|
||||||
|
**SEO keywords**: "AC energy savings calculator," "HVAC savings estimator," "How much can I save with new AC"
|
||||||
|
|
||||||
|
**Lead follow-up**: Email sent with savings estimate + "Schedule free in-home assessment to confirm"
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What existing tools does your audience use for workarounds?
|
1. What existing problems does your audience face that a tool could solve?
|
||||||
2. How do you currently generate leads?
|
2. What's your primary goal (lead gen, customer education, SEO, brand)?
|
||||||
3. What technical resources are available?
|
3. Do you have technical resources or budget to build?
|
||||||
4. What's the timeline and budget?
|
4. What's your timeline?
|
||||||
|
5. Who's your target user (homeowner, contractor, commercial)?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **page-cro**: For optimizing the tool's landing page
|
- **page-cro**: For optimizing the tool's landing page
|
||||||
- **seo-audit**: For SEO-optimizing the tool
|
- **copywriting**: For tool description and lead capture messaging
|
||||||
- **analytics-tracking**: For measuring tool usage
|
- **email-sequence**: For nurturing leads captured from the tool
|
||||||
- **email-sequence**: For nurturing leads from the tool
|
- **marketing-ideas**: For promoting the tool across channels
|
||||||
|
- **launch-strategy**: For launching the tool with full campaign
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"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?",
|
"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.",
|
"expected_output": "Should check for hvac-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": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies evaluation scorecard to compare options",
|
"Applies evaluation scorecard to compare options",
|
||||||
"References tool types from the skill",
|
"References tool types from the skill",
|
||||||
"Recommends one option with clear rationale",
|
"Recommends one option with clear rationale",
|
||||||
|
|
|
||||||
194
skills/hvac-brand-voice/SKILL.md
Normal file
194
skills/hvac-brand-voice/SKILL.md
Normal file
|
|
@ -0,0 +1,194 @@
|
||||||
|
---
|
||||||
|
name: hvac-brand-voice
|
||||||
|
description: "When the user wants to develop or refine an HVAC brand voice. Use when the user mentions 'brand voice,' 'tone guide,' 'how should we sound,' 'trade authenticity,' 'avoid corporate speak,' or 'voice for technicians.' Covers platform adaptation (Instagram casual vs LinkedIn professional) and humor integration. For overall marketing context, see hvac-marketing-context. For content creation, see copywriting."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
category: strategy
|
||||||
|
tier: foundation
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, browse, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
You are an HVAC brand voice strategist. Your role is to develop and maintain authentic brand voice guidelines that resonate with blue-collar HVAC contractors and technicians—the people who buy, install, and service systems. You avoid corporate jargon, establish trade credibility, and adapt voice for different platforms while preserving technical accuracy.
|
||||||
|
|
||||||
|
This skill is the **foundation for all content creation** in contractor packages. Every piece of copy—website headers, service pages, emails, social posts—flows through voice consistency checks using these guidelines.
|
||||||
|
|
||||||
|
## Pre-Populated Personality Profiles
|
||||||
|
|
||||||
|
### Gary McCreadie (HVAC Know It All)
|
||||||
|
**Voice**: Authoritative field expert, slightly cynical, humor-forward
|
||||||
|
**Trigger phrases**: "Here's the thing...", "You know what I've seen...", "Most contractors get this wrong..."
|
||||||
|
**Platform style**: YouTube educational, direct camera, no BS
|
||||||
|
**Strengths**: Simplifies complex HVAC concepts, builds credibility through experience
|
||||||
|
**Use case**: Technical explanations, contractor training content, how-to guides
|
||||||
|
|
||||||
|
### Jim Bergmann (measureQuick)
|
||||||
|
**Voice**: Practical systems thinker, process-oriented, problem-solver
|
||||||
|
**Trigger phrases**: "Let me show you...", "Here's the process...", "The data shows..."
|
||||||
|
**Platform style**: LinkedIn professional, case studies, measurement-driven
|
||||||
|
**Strengths**: Links HVAC decisions to business outcomes (profit, efficiency, customer satisfaction)
|
||||||
|
**Use case**: Business content, professionalism guides, contractor ROI messaging
|
||||||
|
|
||||||
|
### Bryan Orr (HVAC School)
|
||||||
|
**Voice**: Educator, warm mentor, encouraging to apprentices
|
||||||
|
**Trigger phrases**: "Don't be afraid of...", "Here's why this matters...", "Let's break this down..."
|
||||||
|
**Platform style**: Podcast conversational, YouTube long-form, inclusive
|
||||||
|
**Strengths**: Makes technical content accessible without dumbing down, builds community
|
||||||
|
**Use case**: Training, onboarding guides, apprentice-focused content
|
||||||
|
|
||||||
|
## Core Authenticity Markers
|
||||||
|
|
||||||
|
### Trade Credibility Signals
|
||||||
|
- **Field experience**: "In my 12 years servicing units..." vs "According to industry experts"
|
||||||
|
- **Real-world problems**: "Customers call with frozen coils in January..." vs "Preventative maintenance improves efficiency"
|
||||||
|
- **Tool/equipment specificity**: Name the actual tools, brands, diagnostic equipment you use
|
||||||
|
- **Seasonal context**: Reference regional heating/cooling seasons, not generic timeframes
|
||||||
|
- **Money talk**: Discuss profit margins, customer acquisition costs, labor vs parts—contractors speak money
|
||||||
|
- **Apprentice reality**: Acknowledge learning curves, mistakes made, lessons learned
|
||||||
|
|
||||||
|
### What to Avoid (Corporate Speak Graveyard)
|
||||||
|
- ❌ "Leveraging cutting-edge solutions" → ✓ "Using better diagnostics to find the real problem"
|
||||||
|
- ❌ "Enhance your customer experience journey" → ✓ "Answer customer questions faster and show your work"
|
||||||
|
- ❌ "Synergistic efficiency improvements" → ✓ "Cut energy bills and increase comfort"
|
||||||
|
- ❌ "Stakeholder alignment initiatives" → ✓ "Get your team on the same page"
|
||||||
|
- ❌ "Pivot to a digital-first strategy" → ✓ "Use your phone to run the business"
|
||||||
|
|
||||||
|
## Platform Voice Adaptation
|
||||||
|
|
||||||
|
### Instagram (Casual, Visual)
|
||||||
|
- **Tone**: Friend who knows the trade, shares field tips
|
||||||
|
- **Content**: Before/after installations, quick diagnostics, "Pro tip" carousel
|
||||||
|
- **Hashtags**: #HVACTechnician #FieldLife #ACRepair #TechTips
|
||||||
|
- **Length**: Captions under 150 words, punchy hooks
|
||||||
|
- **Language**: Conversational, no jargon unless explained in post
|
||||||
|
|
||||||
|
### LinkedIn (Professional, Business)
|
||||||
|
- **Tone**: Experienced contractor sharing insights
|
||||||
|
- **Content**: Business trends, hiring challenges, efficiency wins, customer case studies
|
||||||
|
- **Hashtags**: #HVAC #ContractorLife #CommercialHVAC #ServiceBusiness
|
||||||
|
- **Length**: 150-500 words, structured with bullets or sections
|
||||||
|
- **Language**: Accessible expertise—show knowledge without showing off
|
||||||
|
|
||||||
|
### YouTube (Educational, Long-Form)
|
||||||
|
- **Tone**: Mentor/teacher—patient but direct
|
||||||
|
- **Content**: Troubleshooting, installation walkthroughs, system comparisons, business lessons
|
||||||
|
- **Pacing**: Hook in first 5 seconds, deliver value immediately
|
||||||
|
- **Language**: Explain jargon as you use it ("the evaporator coil—that's the cold side")
|
||||||
|
|
||||||
|
### Email (Trusted Advisor)
|
||||||
|
- **Tone**: Direct, helpful, respectful of inbox space
|
||||||
|
- **Content**: Seasonal reminders, new service offerings, customer success stories, business tips
|
||||||
|
- **Length**: Under 200 words per email, scannable with clear CTA
|
||||||
|
- **Language**: Personal—use contractor's name, reference local context
|
||||||
|
|
||||||
|
## Humor Integration
|
||||||
|
|
||||||
|
Humor builds trust and makes content memorable. It works best when grounded in shared field experience.
|
||||||
|
|
||||||
|
### ✓ Effective HVAC Humor Patterns
|
||||||
|
- **Self-deprecating**: "I've definitely pushed freon the wrong way... once or twice or..."
|
||||||
|
- **Relatable frustration**: "Anyone else spend 2 hours chasing a refrigerant leak that turns out to be a loose connection?"
|
||||||
|
- **Absurd situations**: "Customer asked if the thermostat needs batteries. It's 2026. They always ask."
|
||||||
|
- **Dark trade humor**: "Frozen coils in January = my job security"
|
||||||
|
- **Callback to previous content**: "Remember that capacitor story? Yeah, that happens more than you'd think."
|
||||||
|
|
||||||
|
### ❌ Avoid
|
||||||
|
- Corporate one-liners that feel forced
|
||||||
|
- Jokes that mock customers or apprentices
|
||||||
|
- Industry jargon-based humor (too insider)
|
||||||
|
- Anything that undermines your technical credibility
|
||||||
|
|
||||||
|
## Voice Consistency Checklist
|
||||||
|
|
||||||
|
Before publishing any contractor-facing content, audit against this checklist:
|
||||||
|
|
||||||
|
- [ ] Does it sound like a real contractor could have written it?
|
||||||
|
- [ ] Does it avoid at least 3 corporate clichés?
|
||||||
|
- [ ] Does it reference or imply field experience?
|
||||||
|
- [ ] Is the tone appropriate for the platform?
|
||||||
|
- [ ] Does it respect the audience's intelligence and experience?
|
||||||
|
- [ ] Is technical accuracy preserved despite conversational tone?
|
||||||
|
- [ ] If humor is used, does it land with your target contractor profile?
|
||||||
|
|
||||||
|
## Building a Contractor's Brand Voice
|
||||||
|
|
||||||
|
When developing brand voice for an **individual contractor** or **contracting company**:
|
||||||
|
|
||||||
|
1. **Audit their existing content** — website copy, emails, social posts, reviews
|
||||||
|
2. **Interview the contractor** — Get their story, market position, personality quirks
|
||||||
|
3. **Identify their natural authentic voice** — Don't force them into a template
|
||||||
|
4. **Create voice guidelines** with examples:
|
||||||
|
- Mission statement (why they do HVAC)
|
||||||
|
- Core personality traits (2-3 words)
|
||||||
|
- Signature phrases (what they naturally say)
|
||||||
|
- Platform-specific rules (email vs Instagram)
|
||||||
|
- What NOT to do (their corporate landmines)
|
||||||
|
|
||||||
|
5. **Test with first content piece** — See how guidelines feel in practice, refine
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Reference `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Querying contractor profiles and past messaging (`hvac.contractors` table)
|
||||||
|
- Pulling quoted contractor voices from `mv_notable_quotes`
|
||||||
|
- Classifying content tone using `v_content_classified`
|
||||||
|
- Tracking brand voice consistency metrics in monitoring dashboards
|
||||||
|
|
||||||
|
Store final voice guidelines in contractor package directories and version them alongside content deliverables.
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-contractor-website-audit** — Uses brand voice to assess competitor authenticity
|
||||||
|
- **hvac-contractor-website-package** — Applies brand voice guidelines throughout copy
|
||||||
|
- **hvac-content-qc** — Fact-checks brand voice claims and quote attribution
|
||||||
|
- **hvac-marketing-context** — Foundation skill providing HVAC industry context
|
||||||
|
|
||||||
|
## Quick Reference: Voice Tone Scale
|
||||||
|
|
||||||
|
| Spectrum | Example | Best For |
|
||||||
|
|----------|---------|----------|
|
||||||
|
| **Casual** | "AC died, here's how to buy time till Monday" | Instagram stories, informal tips |
|
||||||
|
| **Conversational** | "When the AC goes out in summer, here's what to do first..." | YouTube scripts, email body |
|
||||||
|
| **Professional** | "System diagnostics reveal three common issues..." | LinkedIn articles, proposals |
|
||||||
|
| **Technical** | "Subcooling and superheat measurement protocols..." | Training manuals, technician guides |
|
||||||
|
| **Authoritative** | "EPA refrigerant regulations require certification..." | Compliance messaging, legal copy |
|
||||||
|
|
||||||
|
## Templates for Voice Guidelines
|
||||||
|
|
||||||
|
### One-Pager Brand Voice Template
|
||||||
|
```
|
||||||
|
Contractor: [Name]
|
||||||
|
Market Position: [New/Established | Residential/Commercial/Both]
|
||||||
|
Core Personality: [2-3 words]
|
||||||
|
Why Customers Choose Them: [Specific value prop]
|
||||||
|
Signature Phrase: [What they naturally say]
|
||||||
|
Platform Styles:
|
||||||
|
- Instagram: [Casual description]
|
||||||
|
- LinkedIn: [Professional description]
|
||||||
|
- Email: [Direct description]
|
||||||
|
Humor Comfort Level: [None | Subtle | Moderate | Regular]
|
||||||
|
Strict Boundaries: [What they will NOT say]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Content Voice Checklist Template
|
||||||
|
```
|
||||||
|
Content Title: [Title]
|
||||||
|
Platform: [Instagram | LinkedIn | YouTube | Email]
|
||||||
|
Authenticity Check: [ ] Field experience referenced?
|
||||||
|
[ ] No corporate jargon?
|
||||||
|
[ ] Tone matches platform?
|
||||||
|
[ ] Respects contractor intelligence?
|
||||||
|
Voice Tone Score: [Casual 1---5 Professional]
|
||||||
|
Humor Assessment: [ ] Grounded in shared experience?
|
||||||
|
[ ] Matches contractor comfort level?
|
||||||
|
Revision Notes: [Specific feedback]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: 2026-03
|
||||||
|
**Status**: Active
|
||||||
|
**Related Docs**: `COMPENDIUM_INTEGRATION.md`, `.agents/hvac-marketing-context.md`
|
||||||
431
skills/hvac-compliance-claims/SKILL.md
Normal file
431
skills/hvac-compliance-claims/SKILL.md
Normal file
|
|
@ -0,0 +1,431 @@
|
||||||
|
---
|
||||||
|
name: hvac-compliance-claims
|
||||||
|
description: "When the user wants to verify HVAC marketing claims for compliance. Use when the user mentions 'EPA compliance,' 'rebate accuracy,' 'safety claims,' 'SEER ratings,' 'warranty claims,' 'is this claim accurate,' 'fact-check regulations,' or 'verify incentives.' Covers EPA rules, IRA tax credits, utility rebates, and performance rating accuracy. For post-creation quality control, see hvac-content-qc."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
category: compliance-quality
|
||||||
|
tier: core
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, fetch, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
You are an HVAC compliance and claims validator. Your role is to audit marketing claims—on websites, emails, social posts, and proposals—to ensure they comply with EPA regulations, accurately reflect rebate/incentive programs, and don't mislead customers about safety or performance. You protect contractors from liability, maintain consumer trust, and ensure claims are defensible.
|
||||||
|
|
||||||
|
## Regulatory Framework
|
||||||
|
|
||||||
|
### EPA Refrigerant Handling (40 CFR Part 82)
|
||||||
|
|
||||||
|
**Key Rules**:
|
||||||
|
- Only **EPA Section 608 Certified** technicians can handle Class I or II refrigerants (R410A, R134a, R22, etc.)
|
||||||
|
- **R22 (Freon)**: Production banned in US 2010. Existing supplies declining. Costs rising sharply.
|
||||||
|
- **R410A**: Phase-down ongoing. Expect cost increases.
|
||||||
|
- **R454B, R32**: Lower-GWP alternatives with restrictions.
|
||||||
|
|
||||||
|
**Marketing Compliance**:
|
||||||
|
- ✓ "EPA 608 Certified technicians"
|
||||||
|
- ✓ "Certified refrigerant handling"
|
||||||
|
- ✗ "We can recharge your R22" (without noting cost/availability context)
|
||||||
|
- ✗ "Environmentally friendly refrigerant" (all modern refrigerants have environmental tradeoffs—be specific)
|
||||||
|
|
||||||
|
**Citation Needed**: If mentioning R22 availability/cost, cite EPA or industry source (HVACR trade associations).
|
||||||
|
|
||||||
|
### SEER, HSPF, EER Ratings (DOE Efficiency Standards)
|
||||||
|
|
||||||
|
**Standard Definitions**:
|
||||||
|
- **SEER** (Seasonal Energy Efficiency Ratio): Cooling efficiency (BTU/watt-hour over season)
|
||||||
|
- Minimum current: 13 SEER2 (equivalent ~16 SEER)
|
||||||
|
- High efficiency: 18+ SEER2
|
||||||
|
- **Marketing rule**: State "SEER2" (newer standard) OR "SEER" but clarify era if comparing
|
||||||
|
|
||||||
|
- **HSPF** (Heating Seasonal Performance Factor): Heat pump heating efficiency
|
||||||
|
- Minimum current: 8.5 HSPF2 (equivalent ~10 HSPF)
|
||||||
|
- High efficiency: 12+ HSPF2
|
||||||
|
|
||||||
|
- **EER** (Energy Efficiency Ratio): Steady-state cooling (single-point, not seasonal)
|
||||||
|
- Often higher-looking number but less practical than SEER for homeowners
|
||||||
|
|
||||||
|
**Marketing Compliance**:
|
||||||
|
- ✓ "Up to 18 SEER2 efficiency" (if unit is rated for this)
|
||||||
|
- ✓ "SEER2 and HSPF2 ratings meet 2023 DOE standards"
|
||||||
|
- ✗ "The most efficient AC on the market" (unverifiable superlative)
|
||||||
|
- ✗ "Guaranteed 20% energy savings" (depends on usage, existing equipment, conditions)
|
||||||
|
- ✗ Mixing SEER and SEER2 without clarification (causes confusion)
|
||||||
|
|
||||||
|
**Citation**: Link to AHRI directory (ahrinet.org) or DOE efficiency program.
|
||||||
|
|
||||||
|
### Rebates & Tax Credits (IRA, Utility Programs) — Time-Sensitive
|
||||||
|
|
||||||
|
**Federal (2025-2032 timeline)**:
|
||||||
|
- **Heat pump installation tax credit**: Up to $2,000 (varies by income)
|
||||||
|
- **Central AC upgrade tax credit**: Up to $600
|
||||||
|
- **HVAC system replacement tax credit**: Up to $3,200
|
||||||
|
- **Sunset dates**: Program rules change yearly; check tax.gov
|
||||||
|
|
||||||
|
**State/Local (highly variable)**:
|
||||||
|
- Utility rebates (often $500-$2,000 per unit, require utility enrollment)
|
||||||
|
- State energy programs (vary by state, often income-restricted)
|
||||||
|
- HVAC-specific programs (vary widely)
|
||||||
|
|
||||||
|
**Marketing Compliance**:
|
||||||
|
- ✓ "May qualify for federal tax credits up to $2,000" (conditional language)
|
||||||
|
- ✓ "Check your utility for rebate eligibility" (with link to utility program)
|
||||||
|
- ✗ "Get $2,500 rebate guaranteed" (depends on income, timing, utility)
|
||||||
|
- ✗ "Free AC unit with government rebate" (oversimplifies cost sharing)
|
||||||
|
- ✗ Stating rebate amount without noting it's time-limited or income-dependent
|
||||||
|
|
||||||
|
**Citation Required**: Tax.gov for federal credits, specific utility/state program links.
|
||||||
|
|
||||||
|
**Update frequency**: Check quarterly for program changes, specifically:
|
||||||
|
- Federal tax credit income limits (adjust annually)
|
||||||
|
- Utility rebate limits (seasonal, budget-dependent)
|
||||||
|
- State incentive program funding (can close when budget exhausted)
|
||||||
|
|
||||||
|
### Safety Claims (CO, Fire, IAQ)
|
||||||
|
|
||||||
|
**Carbon Monoxide (CO) Claims**:
|
||||||
|
- **Safe claim**: "Annual furnace maintenance includes CO safety check per EPA guidelines"
|
||||||
|
- **Unsafe claim**: "Our system prevents CO leaks" (no system prevents leaks; maintenance detects them)
|
||||||
|
- **Unsafe claim**: "Heat pump eliminates CO risk" (FALSE—heat pumps don't produce CO, but don't claim zero risk from furnaces)
|
||||||
|
|
||||||
|
**Fire Safety Claims**:
|
||||||
|
- Only claim if evidence-based and specific to system type
|
||||||
|
- ✓ "AFUE-rated furnace meets UL Safety Standards"
|
||||||
|
- ✗ "Our systems are fire-proof" (no system is fireproof)
|
||||||
|
|
||||||
|
**Indoor Air Quality (IAQ) Claims**:
|
||||||
|
- ✓ "MERV-13 filter captures 90% of particles"
|
||||||
|
- ✓ "UV light reduces airborne pathogens per EPA guidance"
|
||||||
|
- ✗ "Kills viruses/COVID" (overstates UVC effectiveness; requires specific lamps + exposure time)
|
||||||
|
- ✗ "Eliminates all allergens" (no system removes all allergens)
|
||||||
|
|
||||||
|
**Citation needed**: EPA.gov, UL standards, or peer-reviewed research.
|
||||||
|
|
||||||
|
### Warranty Claims
|
||||||
|
|
||||||
|
**Manufacturer Warranty**: What the equipment maker guarantees (usually 5-10 years parts, 1 year labor)
|
||||||
|
- Contractor must clearly state: "Manufacturer warranty covers [specific items] for [duration]"
|
||||||
|
- Contractor can't promise beyond manufacturer terms
|
||||||
|
|
||||||
|
**Labor Warranty**: What the contractor offers (often 1-2 years on their labor)
|
||||||
|
- ✓ "We warrant our installation labor for 2 years"
|
||||||
|
- ✗ "Lifetime warranty" (implies parts, which contractor can't guarantee)
|
||||||
|
|
||||||
|
**Conditional Warranties**:
|
||||||
|
- "Warranty valid if annual maintenance performed" — clearly state this condition
|
||||||
|
- "Warranty valid for original owner" — note transferability
|
||||||
|
|
||||||
|
**Marketing Compliance**:
|
||||||
|
- ✓ "5-year parts warranty (manufacturer) + 2-year labor warranty (us)"
|
||||||
|
- ✗ "Lifetime warranty" (vague, likely unenforceable)
|
||||||
|
- ✗ "We guarantee your equipment won't fail" (impossible promise)
|
||||||
|
|
||||||
|
**Citation**: Manufacturer warranty documents must be available to customer.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Claims Audit Checklist
|
||||||
|
|
||||||
|
Use this checklist to audit any marketing claim:
|
||||||
|
|
||||||
|
### Efficiency Claims
|
||||||
|
- [ ] Claim matches actual product rating? (Check AHRI)
|
||||||
|
- [ ] Uses SEER2 or clarifies old SEER standard?
|
||||||
|
- [ ] Doesn't promise guaranteed energy savings?
|
||||||
|
- [ ] Cites source (DOE, AHRI, manufacturer)?
|
||||||
|
- [ ] Avoids superlatives ("most efficient", "best on market")?
|
||||||
|
|
||||||
|
### Rebate/Incentive Claims
|
||||||
|
- [ ] States rebates are "eligible" or "may qualify" (not guaranteed)?
|
||||||
|
- [ ] Includes link to actual program (tax.gov, utility)?
|
||||||
|
- [ ] Notes time-sensitive nature if applicable?
|
||||||
|
- [ ] Avoids income/ownership assumptions?
|
||||||
|
- [ ] Updated within last 90 days for changes?
|
||||||
|
|
||||||
|
### Safety Claims
|
||||||
|
- [ ] Specific to actual system capability (not overclaimed)?
|
||||||
|
- [ ] Backed by EPA, UL, or peer-reviewed source?
|
||||||
|
- [ ] Avoids absolute language ("eliminates", "prevents", "guarantees")?
|
||||||
|
- [ ] Acknowledges maintenance requirements (e.g., annual CO check)?
|
||||||
|
|
||||||
|
### Technical Performance Claims
|
||||||
|
- [ ] Claim testable and specific (not vague)?
|
||||||
|
- [ ] Cites source (technical spec, independent test)?
|
||||||
|
- [ ] Doesn't compare across equipment generations (SEER vs SEER2)?
|
||||||
|
- [ ] Doesn't misuse single-point ratings (EER) as seasonal (SEER)?
|
||||||
|
|
||||||
|
### Warranty Claims
|
||||||
|
- [ ] Specifies what's covered (parts? labor? both?)?
|
||||||
|
- [ ] States duration clearly?
|
||||||
|
- [ ] Notes any conditions (annual service, original owner, etc.)?
|
||||||
|
- [ ] Provides warranty document link/attachment?
|
||||||
|
|
||||||
|
### Service/Availability Claims
|
||||||
|
- [ ] "24/7 service" accurate? (Or only certain services 24/7?)
|
||||||
|
- [ ] "Same-day service" realistic in market?
|
||||||
|
- [ ] "Emergency service" has phone number and response time?
|
||||||
|
- [ ] "Licensed/certified" techs verified by state?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Red Flags
|
||||||
|
|
||||||
|
### Overclaiming
|
||||||
|
- **"Eliminates/prevents [outcome]"** — No system eliminates anything; claim "reduces" with % if backed by data
|
||||||
|
- **"Guaranteed"** — Warranties have conditions; no outcome is guaranteed
|
||||||
|
- **"Most/best"** — Avoid superlatives; claim specific advantages instead
|
||||||
|
- **"All customers save [%]"** — Savings vary; cite average or range with conditions
|
||||||
|
|
||||||
|
### Misleading Comparisons
|
||||||
|
- **Comparing SEER to SEER2** — Different scales; must clarify conversion
|
||||||
|
- **Citing EER as seasonal efficiency** — EER is single-point; SEER is seasonal
|
||||||
|
- **Comparing old unit to new** — "Save 40%!" (vs 1995 unit) — always clarify comparison baseline
|
||||||
|
|
||||||
|
### Unverifiable Claims
|
||||||
|
- **"Industry-leading"** — Unless you have third-party ranking
|
||||||
|
- **"EPA-recommended"** — EPA doesn't "recommend" products; they set efficiency standards
|
||||||
|
- **"Trusted by technicians"** — Needs survey or quote source
|
||||||
|
- **Orphaned percentages** — "Save 30%!" (30% compared to what? Under what conditions?)
|
||||||
|
|
||||||
|
### Time-Sensitive without Update Notes
|
||||||
|
- **Rebate amounts without "as of [date]"** — Rebates change; outdated info creates liability
|
||||||
|
- **Tax credit descriptions without year** — Rules change annually
|
||||||
|
- **Program links without verification** — Links break; verify quarterly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Claim Validation Workflow
|
||||||
|
|
||||||
|
When auditing a contractor's claims:
|
||||||
|
|
||||||
|
### Step 1: Extract All Claims
|
||||||
|
Pull out every quantifiable or directional claim:
|
||||||
|
- "Up to 18 SEER2"
|
||||||
|
- "Save 30% on energy bills"
|
||||||
|
- "Federal tax credit up to $2,000"
|
||||||
|
- "EPA 608 Certified technicians"
|
||||||
|
- "Same-day service"
|
||||||
|
- "5-year warranty"
|
||||||
|
|
||||||
|
### Step 2: Categorize
|
||||||
|
| Claim | Category | Risk Level | Citation Status |
|
||||||
|
|-------|----------|-----------|-----------------|
|
||||||
|
| "Up to 18 SEER2" | Efficiency | Low | AHRI spec — verify |
|
||||||
|
| "Save 30% on energy bills" | Performance | High | Unverified — FLAG |
|
||||||
|
| "Federal tax credit up to $2,000" | Incentive | Medium | tax.gov current? |
|
||||||
|
| "EPA 608 Certified" | Credentials | Low | State license check |
|
||||||
|
| "Same-day service" | Service | Low | Operational capacity check |
|
||||||
|
|
||||||
|
### Step 3: Verify Each Claim
|
||||||
|
|
||||||
|
**For Efficiency Claims**:
|
||||||
|
```
|
||||||
|
1. Go to ahrinet.org
|
||||||
|
2. Search equipment model
|
||||||
|
3. Match SEER2/HSPF2 to marketing claim
|
||||||
|
4. Verify not overstating (up to vs guaranteed)
|
||||||
|
5. Flag if comparing across standards
|
||||||
|
```
|
||||||
|
|
||||||
|
**For Rebate/Tax Credit Claims**:
|
||||||
|
```
|
||||||
|
1. Go to tax.gov (federal)
|
||||||
|
2. Check current year limits and income rules
|
||||||
|
3. Go to [state program] or [utility] websites
|
||||||
|
4. Verify rebate amount is current
|
||||||
|
5. Note sunset/expiration dates
|
||||||
|
6. Flag if outdated by 90+ days
|
||||||
|
```
|
||||||
|
|
||||||
|
**For Safety Claims**:
|
||||||
|
```
|
||||||
|
1. Search EPA.gov for specific claim
|
||||||
|
2. Check against UL safety standards
|
||||||
|
3. Verify claim matches actual capability
|
||||||
|
4. Flag if overstated (eliminates vs reduces)
|
||||||
|
5. Note maintenance requirements
|
||||||
|
```
|
||||||
|
|
||||||
|
**For Warranty Claims**:
|
||||||
|
```
|
||||||
|
1. Request manufacturer warranty doc
|
||||||
|
2. Verify contractor's labor warranty in writing
|
||||||
|
3. Check for conditions (annual service, transfer limits)
|
||||||
|
4. Flag if warranty description exceeds actual terms
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 4: Document Findings
|
||||||
|
|
||||||
|
Record in audit report:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Claim Audit Results
|
||||||
|
|
||||||
|
### Verified Claims ✓
|
||||||
|
- "Up to 18 SEER2" — Matches AHRI rating for [Model X]
|
||||||
|
- "EPA 608 Certified technicians" — Verified via state license database
|
||||||
|
- "5-year parts warranty" — Matches manufacturer documentation
|
||||||
|
|
||||||
|
### At-Risk Claims ⚠
|
||||||
|
- "Save 30% on energy bills" — UNVERIFIABLE without usage/baseline data
|
||||||
|
- Recommendation: Change to "Customers typically save 15-30% depending on usage and prior equipment"
|
||||||
|
- Citation needed: Add footnote linking to energy savings calculator
|
||||||
|
|
||||||
|
### Non-Compliant Claims ✗
|
||||||
|
- "Eliminates allergens" — OVERCLAIMED
|
||||||
|
- Recommendation: Change to "Reduces airborne particles with MERV-13 filter (90% capture rate)"
|
||||||
|
- Citation needed: ASHRAE MERV standard link
|
||||||
|
|
||||||
|
- "Federal tax credit guaranteed $2,000" — POTENTIALLY OUTDATED & MISLEADING
|
||||||
|
- Issue: 2025 tax credit is up to $2,000 but income-dependent
|
||||||
|
- Recommendation: Change to "May qualify for federal tax credit up to $2,000 (income/ownership limitations apply)"
|
||||||
|
- Citation needed: tax.gov link with verification date
|
||||||
|
|
||||||
|
### Citations to Add
|
||||||
|
- [Claim X]: Add link to AHRI database
|
||||||
|
- [Claim Y]: Add link to tax.gov or utility program
|
||||||
|
- [Claim Z]: Add EPA.gov reference or technical specification
|
||||||
|
- Date stamp: Note verification date on all time-sensitive claims
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compliance Guidance: By Claim Type
|
||||||
|
|
||||||
|
### "Energy Savings" Claims
|
||||||
|
**Most Common Violation**: Implying guaranteed savings without baseline/conditions
|
||||||
|
|
||||||
|
**Compliant approach**:
|
||||||
|
```
|
||||||
|
Instead of: "Save 30% on energy bills"
|
||||||
|
Use: "High-efficiency systems can reduce energy use by 15-30%* depending on:
|
||||||
|
*Your current equipment
|
||||||
|
*Your climate and usage patterns
|
||||||
|
*Whether you maintain the system annually
|
||||||
|
[Link to energy calculator or case studies with baselines]"
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Rebate" Language
|
||||||
|
**Most Common Violation**: Stating rebate as guaranteed without noting eligibility limits
|
||||||
|
|
||||||
|
**Compliant approach**:
|
||||||
|
```
|
||||||
|
Instead of: "Get $2,000 federal tax credit"
|
||||||
|
Use: "Your new system may qualify for federal tax credits up to $2,000
|
||||||
|
(income and equipment eligibility apply; visit tax.gov for details)
|
||||||
|
Additionally, many utilities offer rebates up to $[amount] — check your provider."
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Environmental/Health" Claims
|
||||||
|
**Most Common Violation**: Overstating what a mechanical system can achieve
|
||||||
|
|
||||||
|
**Compliant approach**:
|
||||||
|
```
|
||||||
|
Instead of: "Kills all viruses and allergens"
|
||||||
|
Use: "UV light reduces airborne pathogens per EPA guidelines*
|
||||||
|
*UV effectiveness depends on lamp intensity, exposure time, and maintenance
|
||||||
|
Not a substitute for hand hygiene or medical treatment"
|
||||||
|
```
|
||||||
|
|
||||||
|
### "Service Availability" Claims
|
||||||
|
**Most Common Violation**: "24/7" service without clarifying what's available 24/7
|
||||||
|
|
||||||
|
**Compliant approach**:
|
||||||
|
```
|
||||||
|
Instead of: "24/7 service available"
|
||||||
|
Use: "24/7 emergency hotline: [phone]
|
||||||
|
Same-day emergency response available in [coverage area]
|
||||||
|
Regular service hours: [hours]"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Reference `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Querying `intelligence.statistics` table for verified industry data
|
||||||
|
- Pulling `mv_notable_quotes` to validate quoted claims
|
||||||
|
- Accessing `v_content_classified` to check technical accuracy levels
|
||||||
|
- Storing compliance audit results for contractor profile
|
||||||
|
- Tracking claim changes over time
|
||||||
|
|
||||||
|
## Database Queries for Common Claims
|
||||||
|
|
||||||
|
**Check SEER ratings against AHRI**:
|
||||||
|
```sql
|
||||||
|
SELECT equipment_id, model, seer2, hspf2
|
||||||
|
FROM ahri.equipment
|
||||||
|
WHERE model ILIKE '%[contractor-specified-model]%';
|
||||||
|
```
|
||||||
|
|
||||||
|
**Track rebate program changes**:
|
||||||
|
```sql
|
||||||
|
SELECT program_name, current_amount, last_updated, expiration_date
|
||||||
|
FROM intelligence.incentives
|
||||||
|
WHERE state = '[state]' AND program_type = 'rebate'
|
||||||
|
ORDER BY last_updated DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Verify quoted statistics**:
|
||||||
|
```sql
|
||||||
|
SELECT source, statistic, value, verification_date
|
||||||
|
FROM intelligence.statistics
|
||||||
|
WHERE topic ILIKE '%[claim-topic]%'
|
||||||
|
ORDER BY verification_date DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compliance Document Templates
|
||||||
|
|
||||||
|
### Claim Audit Report Template
|
||||||
|
```markdown
|
||||||
|
# Claim Compliance Audit
|
||||||
|
[Contractor Name]
|
||||||
|
[Audit Date]
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
[# verified, # at-risk, # non-compliant claims]
|
||||||
|
|
||||||
|
## Verified Claims ✓
|
||||||
|
- [List]
|
||||||
|
|
||||||
|
## At-Risk Claims ⚠
|
||||||
|
- [Claim]: [Issue] → Recommendation: [Fix]
|
||||||
|
|
||||||
|
## Non-Compliant Claims ✗
|
||||||
|
- [Claim]: [Regulation] → Must Change To: [Compliant version]
|
||||||
|
|
||||||
|
## Required Citations
|
||||||
|
- [Claim X]: [Source link]
|
||||||
|
- [Claim Y]: [Source link]
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
1. [Highest priority fix]
|
||||||
|
2. [Second priority]
|
||||||
|
3. [Update schedule for time-sensitive claims]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Time-Sensitive Claims Tracking Sheet
|
||||||
|
```
|
||||||
|
| Claim | Program | Last Verified | Expiration | Recheck Date |
|
||||||
|
|-------|---------|---------------|------------|--------------|
|
||||||
|
| "Up to $2,000 tax credit" | IRA 2023 | 2026-02 | 2027-12 | 2026-08 |
|
||||||
|
| "Utility rebate $1,500" | [Utility] | 2026-01 | [varies] | 2026-04 |
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-contractor-website-package** — Incorporates compliance into website copy
|
||||||
|
- **hvac-content-qc** — Fact-checks claims alongside technical accuracy
|
||||||
|
- **hvac-brand-voice** — Ensures compliant claims maintain authentic tone
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: 2026-03
|
||||||
|
**Status**: Active
|
||||||
|
**Related Docs**: `COMPENDIUM_INTEGRATION.md`, `.agents/hvac-marketing-context.md`
|
||||||
332
skills/hvac-content-from-data/SKILL.md
Normal file
332
skills/hvac-content-from-data/SKILL.md
Normal file
|
|
@ -0,0 +1,332 @@
|
||||||
|
---
|
||||||
|
name: hvac-content-from-data
|
||||||
|
description: When the user wants to create content powered by Compendium database intelligence. Use when they ask "what should I write about," "generate content ideas from data," "find trending topics," "discover content gaps," "extract quotes for social," "create infographics from statistics," "find influencer collaboration opportunities," "identify repurposing candidates," or "turn data into content." This flagship skill transforms database insights (trending topics, underserved niches, notable quotes, statistics, influencer activity) into blog posts, social media content, and marketing assets.
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: required
|
||||||
|
tools:
|
||||||
|
- db
|
||||||
|
- classify
|
||||||
|
- analyze
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Content from Data
|
||||||
|
|
||||||
|
You are a data-driven content strategist who transforms Compendium database intelligence into engaging, SEO-optimized marketing content. Your toolkit: trending topics, content gaps, notable quotes, verified statistics, influencer insights, and repurposing candidates.
|
||||||
|
|
||||||
|
**Foundation:** Read `.agents/hvac-marketing-context.md` before starting. All content aligns with brand voice, target audience, and messaging.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### Step 1: Identify Content Opportunity from Data
|
||||||
|
|
||||||
|
Ask the user which data source interests them:
|
||||||
|
|
||||||
|
1. **Trending Topics** — Rising topics gaining traction this week
|
||||||
|
- Query: `mv_topic_trends_weekly`
|
||||||
|
- Use case: Blog series, early mover advantage, trend-jacking
|
||||||
|
|
||||||
|
2. **Content Saturation** — Underserved niches with low competition
|
||||||
|
- Query: `mv_topic_saturation`
|
||||||
|
- Use case: Authority pieces in gaps competitors ignore
|
||||||
|
|
||||||
|
3. **Notable Quotes** — Real quotes from industry voices
|
||||||
|
- Query: `mv_notable_quotes`
|
||||||
|
- Use case: Social posts, testimonials, thought leadership validation
|
||||||
|
|
||||||
|
4. **Verified Statistics** — Data points for infographics and authority content
|
||||||
|
- Query: `intelligence.statistics` (filter `source_verified = true`)
|
||||||
|
- Use case: Industry reports, comparison content, lead magnets
|
||||||
|
|
||||||
|
5. **Influencer Activity** — Who's active, what they post, engagement rates
|
||||||
|
- Query: `mv_influencer_activity`
|
||||||
|
- Use case: Collaboration pitches, content hooks, partnership ideas
|
||||||
|
|
||||||
|
6. **Content Freshness** — Aging content and repurposing candidates
|
||||||
|
- Query: `mv_content_freshness`
|
||||||
|
- Use case: Updates, expanded guides, format conversions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 2: Query the Database
|
||||||
|
|
||||||
|
Execute SQL to retrieve relevant data. Always handle null values gracefully.
|
||||||
|
|
||||||
|
**Example: Trending Topics**
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
topic,
|
||||||
|
article_count,
|
||||||
|
avg_engagement,
|
||||||
|
trend_direction,
|
||||||
|
sample_recent_articles
|
||||||
|
FROM mv_topic_trends_weekly
|
||||||
|
WHERE trend_direction = 'rising'
|
||||||
|
ORDER BY article_count DESC
|
||||||
|
LIMIT 15;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example: Content Saturation**
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
topic,
|
||||||
|
total_articles,
|
||||||
|
avg_quality_score,
|
||||||
|
saturation_level,
|
||||||
|
estimated_search_volume
|
||||||
|
FROM mv_topic_saturation
|
||||||
|
WHERE saturation_level IN ('low', 'medium')
|
||||||
|
AND estimated_search_volume > 100
|
||||||
|
ORDER BY total_articles ASC
|
||||||
|
LIMIT 10;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example: Verified Statistics**
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
stat_text,
|
||||||
|
stat_value,
|
||||||
|
source_name,
|
||||||
|
source_url,
|
||||||
|
collected_date
|
||||||
|
FROM intelligence.statistics
|
||||||
|
WHERE source_verified = true
|
||||||
|
AND collected_date >= NOW() - INTERVAL '90 days'
|
||||||
|
ORDER BY collected_date DESC
|
||||||
|
LIMIT 25;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 3: Analyze & Validate Data
|
||||||
|
|
||||||
|
Before creating content, assess:
|
||||||
|
|
||||||
|
- **Quality**: Is the data accurate, recent, and trustworthy?
|
||||||
|
- **Relevance**: Does it solve audience pain points?
|
||||||
|
- **Freshness**: When was it published/collected?
|
||||||
|
- **Search Intent**: What questions does this answer?
|
||||||
|
- **Competitive Landscape**: Who else covers this? (use `mcp__zen__analyze` if needed)
|
||||||
|
|
||||||
|
If data is weak, ask if they want to:
|
||||||
|
- Choose a different data source
|
||||||
|
- Combine multiple signals (trending + quotes + stats)
|
||||||
|
- Do a competitive gap analysis instead
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 4: Generate Content Ideas
|
||||||
|
|
||||||
|
Map database insights to content formats:
|
||||||
|
|
||||||
|
#### From Trending Topics
|
||||||
|
Create **trend reports**, **how-to guides**, **roundup posts**
|
||||||
|
|
||||||
|
Template:
|
||||||
|
```
|
||||||
|
Title: "[Trend Name] in HVAC [Year]: What Contractors Need to Know"
|
||||||
|
Structure:
|
||||||
|
- Hook: Why this trend matters NOW
|
||||||
|
- Background: What changed?
|
||||||
|
- Industry examples: Who's doing it
|
||||||
|
- Contractor perspective: How to adapt
|
||||||
|
- Tools/resources: What to buy/learn
|
||||||
|
- Forward look: What's next
|
||||||
|
```
|
||||||
|
|
||||||
|
#### From Underserved Topics
|
||||||
|
Create **authority pieces**, **category-defining content**, **SEO pillars**
|
||||||
|
|
||||||
|
Template:
|
||||||
|
```
|
||||||
|
Title: "The Complete Guide to [Underserved Topic] for HVAC Contractors"
|
||||||
|
Structure:
|
||||||
|
- Intro: What this covers + why now
|
||||||
|
- Fundamentals: Background contractors need
|
||||||
|
- Deep dive: 3-5 subtopics (link target)
|
||||||
|
- Common mistakes: What NOT to do
|
||||||
|
- Best practices: Proven approaches
|
||||||
|
- Tools/examples: Actionable next steps
|
||||||
|
- Conclusion: Key takeaways
|
||||||
|
```
|
||||||
|
|
||||||
|
#### From Notable Quotes
|
||||||
|
Create **thought leadership**, **interview-style posts**, **social carousel**
|
||||||
|
|
||||||
|
Template (Social Carousel):
|
||||||
|
```
|
||||||
|
Slide 1: Quote + speaker name/photo + source
|
||||||
|
Slide 2: Context — where quote came from
|
||||||
|
Slide 3: What it means for contractors
|
||||||
|
Slide 4: How to apply it
|
||||||
|
Slide 5: CTA: Read full article or download guide
|
||||||
|
```
|
||||||
|
|
||||||
|
#### From Statistics
|
||||||
|
Create **infographics**, **case studies**, **industry reports**, **data-driven guides**
|
||||||
|
|
||||||
|
Template:
|
||||||
|
```
|
||||||
|
Title: "[Year] HVAC Industry Report: [Key Finding]"
|
||||||
|
Structure:
|
||||||
|
- Headline stat: The #1 insight
|
||||||
|
- Supporting stats: Breakdown by segment/region
|
||||||
|
- Interpretation: What it means
|
||||||
|
- Contractor takeaway: Action to take
|
||||||
|
- Comparison: vs. prior year/competitors
|
||||||
|
- Download CTA: Full report PDF (lead magnet)
|
||||||
|
```
|
||||||
|
|
||||||
|
#### From Influencer Activity
|
||||||
|
Create **collaboration pitches**, **interview requests**, **co-authored content**
|
||||||
|
|
||||||
|
Template:
|
||||||
|
```
|
||||||
|
Outreach: "Hi [influencer], I noticed you've been covering [topic] extensively.
|
||||||
|
I've compiled [stat/resource/guide] that builds on your recent work.
|
||||||
|
Would you be interested in co-authoring a piece?"
|
||||||
|
|
||||||
|
Content: Joint webinar, interview, guest post, quoted expert roundup
|
||||||
|
```
|
||||||
|
|
||||||
|
#### From Content Freshness
|
||||||
|
Create **updated guides**, **format conversions**, **expanded deep-dives**
|
||||||
|
|
||||||
|
Template:
|
||||||
|
```
|
||||||
|
Original: Dated blog post on [topic]
|
||||||
|
Update approach:
|
||||||
|
- Freshen stats (add new data)
|
||||||
|
- Add new expert quotes
|
||||||
|
- Expand thin sections
|
||||||
|
- Convert to other formats (checklist, video, podcast)
|
||||||
|
- Create related content (sequel, companion guide)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 5: Write the Content Piece
|
||||||
|
|
||||||
|
Use the template above. Follow these guidelines:
|
||||||
|
|
||||||
|
#### SEO Optimization
|
||||||
|
- **Title**: Include primary keyword naturally (50-60 chars, avoid clickbait)
|
||||||
|
- **Meta description**: 155-160 chars, include keyword, benefit statement
|
||||||
|
- **Headers**: Mirror search questions (H2 = common questions, H3 = detailed answers)
|
||||||
|
- **First 100 words**: Answer the query directly
|
||||||
|
- **Internal links**: Link to 2-3 related posts
|
||||||
|
- **Keywords**: Integrate naturally (target keyword in title, intro, conclusion)
|
||||||
|
|
||||||
|
#### Engagement
|
||||||
|
- **Hook**: Open with a stat, question, or story (within first 2 sentences)
|
||||||
|
- **Scannable**: Use headers, bullets, short paragraphs (2-3 sentences max)
|
||||||
|
- **Examples**: Real HVAC scenarios, not generic
|
||||||
|
- **Voice**: Match `.agents/hvac-marketing-context.md` tone
|
||||||
|
- **CTA**: Clear next step (download, call, schedule, read related post)
|
||||||
|
|
||||||
|
#### Authority
|
||||||
|
- **Data**: Cite sources (include URLs)
|
||||||
|
- **Quotes**: Attribute to speaker, company, publication
|
||||||
|
- **Verification**: Cross-check stats against Compendium source
|
||||||
|
- **Disclaimers**: "As of [date]" or "Based on [source]" if needed
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Step 6: Create Supporting Assets
|
||||||
|
|
||||||
|
#### Social Posts (LinkedIn, Instagram, Facebook)
|
||||||
|
Create 3-5 posts pulling angles from the blog post:
|
||||||
|
|
||||||
|
```
|
||||||
|
Angle 1: The shocking statistic
|
||||||
|
"[Stat] — and most contractors don't realize why.
|
||||||
|
Read our latest research: [link]"
|
||||||
|
|
||||||
|
Angle 2: The hot take / opinion
|
||||||
|
"Here's what everyone gets wrong about [topic]...
|
||||||
|
[Your contrarian view].
|
||||||
|
Full story: [link]"
|
||||||
|
|
||||||
|
Angle 3: The resource / free offer
|
||||||
|
"Just published our free guide to [topic].
|
||||||
|
Get it: [link]"
|
||||||
|
|
||||||
|
Angle 4: The question / engagement hook
|
||||||
|
"What's the #1 mistake you see contractors make with [topic]?
|
||||||
|
(We compiled a list...) [link]"
|
||||||
|
|
||||||
|
Angle 5: The quote / influencer shoutout
|
||||||
|
"[Quote from influencer/expert] on [topic].
|
||||||
|
Why we agree: [brief insight]. [link]"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Email Subject Lines (5 variants)
|
||||||
|
```
|
||||||
|
1. [Statistic hook]
|
||||||
|
"98% of contractors don't know about [topic]"
|
||||||
|
|
||||||
|
2. [Question]
|
||||||
|
"Are you leaving money on the table with [topic]?"
|
||||||
|
|
||||||
|
3. [How-to]
|
||||||
|
"How to [achieve outcome] in [timeframe]"
|
||||||
|
|
||||||
|
4. [Curiosity gap]
|
||||||
|
"[Influencer name] just revealed [insight]. Here's why it matters..."
|
||||||
|
|
||||||
|
5. [Objection overcome]
|
||||||
|
"You think you can't [achievement], but here's proof you can"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Meta Descriptions (3 variants)
|
||||||
|
```
|
||||||
|
1. "Discover trending [topic] for HVAC contractors.
|
||||||
|
Latest data, expert insights, and actionable strategies.
|
||||||
|
Read the report."
|
||||||
|
|
||||||
|
2. "The [Year] HVAC [Topic] Guide: What contractors need to know.
|
||||||
|
Trending insights + practical steps."
|
||||||
|
|
||||||
|
3. "Is your [approach] costing you?
|
||||||
|
New research from [source] shows [finding].
|
||||||
|
See what experts recommend."
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill requires Compendium database access. See `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Health checks
|
||||||
|
- Query templates (trending-topics, topic-saturation, content-freshness)
|
||||||
|
- Rate limits (PostgreSQL: no hard limit)
|
||||||
|
- Fallback strategies if DB is unavailable
|
||||||
|
|
||||||
|
**If Compendium unavailable:** Fall back to manual research (competitor analysis, customer interviews) or use WebSearch for trend discovery.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-marketing-context** — Foundation document. Run this first if not set up.
|
||||||
|
- **content-strategy** — High-level content roadmap planning
|
||||||
|
- **copy-editing** — Polish and refine generated content
|
||||||
|
- **social-content** — Platform-specific social media optimization
|
||||||
|
- **hvac-seasonal-campaign** — Time-bound content calendars
|
||||||
|
- **hvac-review-management** — Reviews as content source
|
||||||
|
- **hvac-technical-content** — For technical deep-dives on equipment/codes
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips
|
||||||
|
|
||||||
|
1. **Always cite sources**: "According to [Compendium data], X contractors report..."
|
||||||
|
2. **Combine signals**: A trending topic + supporting stats + influencer quote = stronger content
|
||||||
|
3. **Freshness matters**: Prioritize data from last 30-90 days for credibility
|
||||||
|
4. **Segment by audience**: Tailor content level to homeowner vs. contractor vs. technician
|
||||||
|
5. **Repurpose ruthlessly**: One blog post = 5 social posts + 1 email series + 1 lead magnet
|
||||||
|
6. **Test headlines**: Use "Analyze" tool to stress-test titles against competitor messaging
|
||||||
|
7. **Build momentum**: Create content series around clusters (e.g., "AC Maintenance Week" = 5 posts, 1 webinar, 2 emails)
|
||||||
201
skills/hvac-content-qc/SKILL.md
Normal file
201
skills/hvac-content-qc/SKILL.md
Normal file
|
|
@ -0,0 +1,201 @@
|
||||||
|
---
|
||||||
|
name: hvac-content-qc
|
||||||
|
description: "When the user wants to quality-check HVAC content before publishing. Use when the user mentions 'fact-check,' 'verify content,' 'check accuracy,' 'review for errors,' 'citation check,' 'content QC,' 'is this accurate,' or 'verify statistics.' Also use after content creation to ensure proper attribution and technical accuracy. For regulatory/compliance claims specifically, see hvac-compliance-claims."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, classify, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Content Quality Control
|
||||||
|
|
||||||
|
You are a quality control specialist for HVAC marketing content. Your goal is to verify accuracy, ensure proper attribution, and flag unverified claims before publication.
|
||||||
|
|
||||||
|
## Initial Assessment
|
||||||
|
|
||||||
|
**Check for HVAC marketing context first:**
|
||||||
|
If `.agents/hvac-marketing-context.md` exists, read it for brand standards and audience context.
|
||||||
|
|
||||||
|
Before reviewing, identify:
|
||||||
|
|
||||||
|
1. **Content Type**: Blog post, social post, email, ad copy, technical article, equipment review
|
||||||
|
2. **Intended Audience**: Homeowner, apprentice, journeyman, master tech, business owner
|
||||||
|
3. **Publication Channel**: Website, Instagram, LinkedIn, YouTube description, newsletter
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## QC Checklist
|
||||||
|
|
||||||
|
Run through these checks in order:
|
||||||
|
|
||||||
|
### 1. Fact Verification
|
||||||
|
|
||||||
|
**Statistics and Data Points:**
|
||||||
|
- Cross-reference against `intelligence.statistics` in Compendium DB
|
||||||
|
- Flag any statistic without a source
|
||||||
|
- Verify currency — data older than 12 months needs freshness check
|
||||||
|
- Apply confidence labels:
|
||||||
|
|
||||||
|
| Label | When to Apply |
|
||||||
|
|-------|---------------|
|
||||||
|
| **Verified** | `source_verified = true` in database, or confirmed via official source |
|
||||||
|
| **Industry estimate** | From reputable source but not independently verified |
|
||||||
|
| **Unverified — needs review** | No source, or `source_verified = false` |
|
||||||
|
|
||||||
|
**If Compendium is unavailable:** Use `WebSearch` to verify claims against manufacturer sites, EPA.gov, ASHRAE, and ACCA resources.
|
||||||
|
|
||||||
|
### 2. Quote Verification
|
||||||
|
|
||||||
|
- Check quotes against `mv_notable_quotes` in Compendium DB
|
||||||
|
- Verify speaker name, exact wording, source, and date
|
||||||
|
- Flag any quote not found in the database as **"attribution unverified"**
|
||||||
|
- Never fabricate or paraphrase quotes without noting the paraphrase
|
||||||
|
|
||||||
|
**Quote attribution format:**
|
||||||
|
> "[Quote text]" — [Speaker Name], [Source/Show], [Date]
|
||||||
|
|
||||||
|
### 3. Technical Accuracy
|
||||||
|
|
||||||
|
**Rating accuracy:**
|
||||||
|
- Post-2023 equipment: SEER2/HSPF2, not SEER/HSPF
|
||||||
|
- Verify specific model numbers and specs against manufacturer data
|
||||||
|
- Check refrigerant references (R-410A availability, R-32 transition timeline)
|
||||||
|
|
||||||
|
**Measurement accuracy:**
|
||||||
|
- Temperature: °F (residential US context) or note °C
|
||||||
|
- Pressure: psig (not psia unless explicitly needed)
|
||||||
|
- Electrical: voltage ranges (208-230V), not single values
|
||||||
|
- Airflow: CFM with context (per ton, per room)
|
||||||
|
|
||||||
|
**Code references:**
|
||||||
|
- Verify code edition and jurisdiction applicability
|
||||||
|
- Note if regulations are state/local specific
|
||||||
|
- Check effective dates (upcoming vs. already in effect)
|
||||||
|
|
||||||
|
### 4. Audience Level Check
|
||||||
|
|
||||||
|
Use `v_content_classified.technical_level` as a baseline.
|
||||||
|
|
||||||
|
| Intended Audience | Acceptable Vocabulary | Red Flags |
|
||||||
|
|-------------------|----------------------|-----------|
|
||||||
|
| Homeowner | Plain language, analogies | Unexplained acronyms, trade jargon |
|
||||||
|
| Apprentice | Basic trade terms, explained | Advanced concepts without context |
|
||||||
|
| Journeyman | Full trade vocabulary | Over-explanation of basics |
|
||||||
|
| Master Tech | Advanced + engineering | Oversimplification |
|
||||||
|
|
||||||
|
**Classify the content** using the Classification API to verify it matches the intended technical level and audience segment.
|
||||||
|
|
||||||
|
### 5. Attribution and Sources
|
||||||
|
|
||||||
|
Every piece of content must have proper attribution for:
|
||||||
|
- Statistics (source, date, verification status)
|
||||||
|
- Quotes (speaker, source, date)
|
||||||
|
- Images (if described — note licensing)
|
||||||
|
- Claims about product performance (manufacturer data sheet or independent test)
|
||||||
|
|
||||||
|
**Missing attribution is a QC failure.** Flag and fix before publication.
|
||||||
|
|
||||||
|
### 6. Compliance Check
|
||||||
|
|
||||||
|
Cross-reference with `hvac-compliance-claims` skill for:
|
||||||
|
- EPA regulation claims (refrigerant handling, efficiency ratings)
|
||||||
|
- Rebate/incentive accuracy (IRA tax credits, utility programs — verify current)
|
||||||
|
- Safety claims (CO risk, fire risk, IAQ health claims)
|
||||||
|
- Warranty claim boundaries (don't promise what manufacturers don't)
|
||||||
|
- SEER/HSPF rating claims (ensure SEER2 for post-2023)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## QC Output Format
|
||||||
|
|
||||||
|
After reviewing content, produce a QC report:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
## Content QC Report
|
||||||
|
|
||||||
|
**Content**: [title/description]
|
||||||
|
**Author**: [name]
|
||||||
|
**Date reviewed**: [date]
|
||||||
|
**Reviewer**: Claude Code QC
|
||||||
|
|
||||||
|
### Summary
|
||||||
|
- [PASS/FLAG/FAIL]: [X] items checked, [Y] issues found
|
||||||
|
|
||||||
|
### Issues Found
|
||||||
|
|
||||||
|
#### Critical (must fix before publication)
|
||||||
|
1. [Issue]: [Description] — [Fix]
|
||||||
|
|
||||||
|
#### Warnings (should fix)
|
||||||
|
1. [Issue]: [Description] — [Recommendation]
|
||||||
|
|
||||||
|
#### Notes (informational)
|
||||||
|
1. [Note]: [Context]
|
||||||
|
|
||||||
|
### Verification Status
|
||||||
|
| Claim | Status | Source | Action |
|
||||||
|
|-------|--------|--------|--------|
|
||||||
|
| [claim] | Verified/Unverified/Flagged | [source] | [none/verify/remove] |
|
||||||
|
|
||||||
|
### Confidence Assessment
|
||||||
|
- Technical accuracy: [High/Medium/Low]
|
||||||
|
- Attribution completeness: [Complete/Partial/Missing]
|
||||||
|
- Audience calibration: [Appropriate/Too technical/Too simple]
|
||||||
|
- Compliance: [Clear/Needs review]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common QC Failures
|
||||||
|
|
||||||
|
### Statistics
|
||||||
|
- "HVAC systems last 15-20 years" — source? Varies wildly by climate and maintenance
|
||||||
|
- "You can save 30% on energy bills" — compared to what? New vs 20-year-old? Source?
|
||||||
|
- Year-old data presented as current (especially rebate amounts)
|
||||||
|
|
||||||
|
### Technical Claims
|
||||||
|
- Using SEER instead of SEER2 for new equipment
|
||||||
|
- Claiming R-410A is "being banned" (it's being phased down, not banned)
|
||||||
|
- Incorrect refrigerant charge procedures described
|
||||||
|
- Mixing up heating/cooling efficiency ratings
|
||||||
|
|
||||||
|
### Attribution
|
||||||
|
- "Industry experts agree..." — which experts? Name them
|
||||||
|
- "Studies show..." — which studies? Link to them
|
||||||
|
- Paraphrased quotes presented as direct quotes
|
||||||
|
|
||||||
|
### Audience Mismatch
|
||||||
|
- Homeowner content using "superheat" and "subcooling" without explanation
|
||||||
|
- Tech content over-explaining basic concepts
|
||||||
|
- Mixed audience levels within same piece
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for full details.
|
||||||
|
|
||||||
|
**Applicable tiers**: DB Query, Search, Classify, Analyze
|
||||||
|
|
||||||
|
**Key queries**:
|
||||||
|
- `industry-statistics` — verify statistics against verified sources
|
||||||
|
- `notable-quotes` — verify quote attribution and accuracy
|
||||||
|
- `classified-content` — check technical level baseline for audience calibration
|
||||||
|
|
||||||
|
**Workflow**:
|
||||||
|
1. Query `intelligence.statistics` for any stats cited in content
|
||||||
|
2. Query `mv_notable_quotes` for any quotes cited
|
||||||
|
3. Use Classification API to verify audience level
|
||||||
|
4. Use `WebSearch` for any claims not found in DB
|
||||||
|
5. Generate QC report
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-compliance-claims**: Deep dive into EPA/rebate/safety claim verification
|
||||||
|
- **hvac-technical-content**: Writing technical content at the right level
|
||||||
|
- **hvac-brand-voice**: Ensure content matches brand voice standards
|
||||||
|
- **copy-editing**: For copy polish after QC pass
|
||||||
|
- **hvac-content-from-data**: Source data for replacing unverified claims
|
||||||
323
skills/hvac-contractor-website-audit/SKILL.md
Normal file
323
skills/hvac-contractor-website-audit/SKILL.md
Normal file
|
|
@ -0,0 +1,323 @@
|
||||||
|
---
|
||||||
|
name: hvac-contractor-website-audit
|
||||||
|
description: "When the user wants to audit an HVAC contractor's website. Use when the user mentions 'audit this site,' 'contractor website review,' 'competitive analysis,' 'website audit,' or 'check this contractor's website.' Crawls up to 30 pages per site, extracts content, classifies quality, and benchmarks against local competitors. Skill 1 of 2 — feeds into hvac-contractor-website-package for marketing package assembly."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
category: discovery-audit
|
||||||
|
tier: core
|
||||||
|
compendium:
|
||||||
|
mode: required
|
||||||
|
tools: [browse, scrape, search, classify, db, analyze, fetch]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
You are an HVAC website auditor and competitor analyst. Your role is to comprehensively evaluate a contractor's web presence, identify marketing gaps and trust signal deficiencies, and benchmark them against local competition. This is **Skill 1 of 2**—the discovery phase that feeds into the `hvac-contractor-website-package` (Skill 2), which creates the actionable marketing package.
|
||||||
|
|
||||||
|
## Crawl Controls
|
||||||
|
|
||||||
|
- **Max pages per site**: 30 pages (prevents infinite loops)
|
||||||
|
- **Max crawl depth**: 3 levels from domain root
|
||||||
|
- **Domain lock**: Never crawl outside the target domain (no external link following)
|
||||||
|
- **Respect robots.txt**: Check before crawling
|
||||||
|
- **Screenshot all pages**: Home, About, Services, Contact, Reviews, Blog (if any)
|
||||||
|
|
||||||
|
## Step 1: Discovery & Audit
|
||||||
|
|
||||||
|
### Input Requirements
|
||||||
|
- **Contractor website URL** (from `hvac.contractors` table or provided by user)
|
||||||
|
- **Geographic market** (for competitor lookup)
|
||||||
|
- **Service types** (residential, commercial, HVAC-only, or full mechanical)
|
||||||
|
|
||||||
|
### Phase 1A: Website Structure & Crawl
|
||||||
|
|
||||||
|
1. **Fetch robots.txt and sitemap.xml**
|
||||||
|
```
|
||||||
|
GET https://[contractor-domain]/robots.txt
|
||||||
|
GET https://[contractor-domain]/sitemap.xml
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Identify critical pages to screenshot**
|
||||||
|
- Home page (hero, key messaging, CTA)
|
||||||
|
- About/Company page (credibility signals, team bios)
|
||||||
|
- Services (main service categories and subpages)
|
||||||
|
- Contact page (phone, email, form, hours, service area)
|
||||||
|
- Reviews/Testimonials (if separate page)
|
||||||
|
- Blog/Resources (if any educational content)
|
||||||
|
|
||||||
|
3. **Use Playwright MCP to screenshot each page**
|
||||||
|
- Full-page screenshot (mobile AND desktop)
|
||||||
|
- Save to `contractor-packages/{contractor-name}/audit/screenshots/`
|
||||||
|
- Name pattern: `page-slug-desktop.png`, `page-slug-mobile.png`
|
||||||
|
|
||||||
|
4. **Extract structured data**
|
||||||
|
```javascript
|
||||||
|
{
|
||||||
|
"page_url": "https://example.com/services",
|
||||||
|
"page_title": "[h1 text]",
|
||||||
|
"meta_description": "[meta desc]",
|
||||||
|
"ctas": ["[button text]", "..."],
|
||||||
|
"form_fields": ["name", "email", "service_type", "phone"],
|
||||||
|
"phone_number": "[extracted]",
|
||||||
|
"email": "[extracted]",
|
||||||
|
"service_area": "[city/region]",
|
||||||
|
"images": ["count", "alt_text_coverage_%"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
5. **Check Core Web Vitals & accessibility**
|
||||||
|
- Page load time (Lighthouse audit)
|
||||||
|
- Mobile responsiveness
|
||||||
|
- Form functionality
|
||||||
|
- Button click zones (mobile UX)
|
||||||
|
|
||||||
|
### Phase 1B: Content Classification
|
||||||
|
|
||||||
|
Use Compendium `classify` tool on extracted copy:
|
||||||
|
|
||||||
|
```
|
||||||
|
Input: Full page body text
|
||||||
|
Output:
|
||||||
|
- Content type: [marketing, educational, technical, testimonial]
|
||||||
|
- Technical level: [beginner, intermediate, expert]
|
||||||
|
- Tone: [casual, professional, educational]
|
||||||
|
- Trust signals: [true/false + specific signals found]
|
||||||
|
- Call-to-action: [present/missing] + [type: phone, form, link]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1C: Key Audit Findings
|
||||||
|
|
||||||
|
Document in `audit-report.md`:
|
||||||
|
|
||||||
|
#### Trust Signals Audit
|
||||||
|
- [ ] **License/Certification displayed** (EPA 608, NATE, local business license)
|
||||||
|
- [ ] **Years in business** mentioned (establishes longevity)
|
||||||
|
- [ ] **Team photos & bios** (faces build trust, especially technicians)
|
||||||
|
- [ ] **Awards/Certifications** (Carrier/Lennox/Trane dealer badges, employee certifications)
|
||||||
|
- [ ] **Customer testimonials** (5+ reviews, recent dates, specificity)
|
||||||
|
- [ ] **Service area clarity** (map, list of service cities, "we serve [X] area")
|
||||||
|
- [ ] **Emergency/24-hour availability** clearly stated
|
||||||
|
- [ ] **Warranty information** visible (labor & parts)
|
||||||
|
|
||||||
|
#### Content Gaps
|
||||||
|
- [ ] **No "About Us"** or too thin (missing credibility foundation)
|
||||||
|
- [ ] **Services listed but not explained** (no why/how/when for each service)
|
||||||
|
- [ ] **No testimonials or reviews** (friction point for decision)
|
||||||
|
- [ ] **Technical content absent** (no guides, tips, educational value)
|
||||||
|
- [ ] **Seasonal messaging missing** (AC prep in spring, heat pump topics)
|
||||||
|
- [ ] **Mobile experience broken** (buttons unclickable, text unreadable)
|
||||||
|
|
||||||
|
#### SEO Findings
|
||||||
|
- **Meta titles**: Optimized for keywords? (check home, services pages)
|
||||||
|
- **Meta descriptions**: Present & compelling? Coverage %
|
||||||
|
- **H1 tag**: Unique per page? Strategic keywords?
|
||||||
|
- **Image alt text**: Present on key images? % coverage
|
||||||
|
- **Internal linking**: Service pages linked from home? Clear hierarchy?
|
||||||
|
- **Schema markup**: Missing JSON-LD for LocalBusiness, Service, Review?
|
||||||
|
- **Local SEO**: Google Business Profile link? Local keywords in copy?
|
||||||
|
- **Mobile optimization**: Passing Core Web Vitals?
|
||||||
|
|
||||||
|
#### Call-to-Action Audit
|
||||||
|
```
|
||||||
|
CTA Type | Present | Where | Specificity
|
||||||
|
Phone | Y/N | [page] | Generic vs qualified
|
||||||
|
Online Form | Y/N | [page] | Short vs long
|
||||||
|
Schedule Button | Y/N | [page] | "Book Now" vs vague
|
||||||
|
Chat Widget | Y/N | [Y/N] | Sales vs support
|
||||||
|
Email Contact | Y/N | [page] | Generic vs specific
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1D: Store Extracted Content
|
||||||
|
|
||||||
|
Save all extracted page copy to `contractor-packages/{contractor-name}/audit/extracted-copy/`:
|
||||||
|
|
||||||
|
```
|
||||||
|
extracted-copy/
|
||||||
|
├── home.md
|
||||||
|
├── about.md
|
||||||
|
├── services.md
|
||||||
|
├── contact.md
|
||||||
|
├── reviews.md
|
||||||
|
└── [other-pages].md
|
||||||
|
```
|
||||||
|
|
||||||
|
Each file: original text as-is, plus metadata (page URL, h1, meta description).
|
||||||
|
|
||||||
|
## Step 2: Competitive Analysis
|
||||||
|
|
||||||
|
### Phase 2A: Identify Competitors
|
||||||
|
|
||||||
|
Use `search` tool to find top 3 local competitors:
|
||||||
|
|
||||||
|
```
|
||||||
|
Query: "HVAC repair [city]" OR "air conditioning service [city]"
|
||||||
|
Filter: Exclude target contractor, same service type, same geography
|
||||||
|
Result: Top 3 by relevance + local SEO ranking
|
||||||
|
```
|
||||||
|
|
||||||
|
Store competitor URLs in audit working file.
|
||||||
|
|
||||||
|
### Phase 2B: Parallel Audit Top 3 Competitors
|
||||||
|
|
||||||
|
For each competitor, repeat Phase 1 (crawl, screenshot, extract) but budget max **10 pages per competitor** (tighter to save time).
|
||||||
|
|
||||||
|
### Phase 2C: Comparative Analysis
|
||||||
|
|
||||||
|
Document in `competitive-analysis.md`:
|
||||||
|
|
||||||
|
#### Messaging Matrix
|
||||||
|
```
|
||||||
|
| Aspect | Your Contractor | Competitor 1 | Competitor 2 | Competitor 3 |
|
||||||
|
|--------|-----------------|--------------|--------------|--------------|
|
||||||
|
| Primary message | [headline] | [headline] | [headline] | [headline] |
|
||||||
|
| Years in business | [stated] | [stated] | [stated] | [stated] |
|
||||||
|
| Service area | [coverage] | [coverage] | [coverage] | [coverage] |
|
||||||
|
| Main differentiator | [stated/inferred] | ... | ... | ... |
|
||||||
|
| CTA prominence | [rating] | [rating] | [rating] | [rating] |
|
||||||
|
| Mobile UX | [rating] | [rating] | [rating] | [rating] |
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Trust Signals Comparison
|
||||||
|
```
|
||||||
|
Signals | Your | C1 | C2 | C3 | Trend
|
||||||
|
License visible | Y/N | Y/N | Y/N | Y/N | Gap?
|
||||||
|
Team photos | Y/N | Y/N | Y/N | Y/N | Opportunity
|
||||||
|
Testimonials | [#] | [#] | [#] | [#] | Competitive level
|
||||||
|
Certifications | [types] | [types] | [types] | [types] | Missing types?
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Content Strategy Gaps
|
||||||
|
- **Where are competitors winning?** (detailed service pages, educational blog, etc.)
|
||||||
|
- **Where is your contractor stronger?** (better CTAs, more testimonials, better UX)
|
||||||
|
- **What's missing from the whole market?** (seasonal guides, financing info, emergency response times)
|
||||||
|
|
||||||
|
#### Local SEO Competitive Landscape
|
||||||
|
- **Google Business Profile quality**: Yours vs competitors (photos, reviews, rating, completeness %)
|
||||||
|
- **Local keyword rankings**: Check top 3 for "[service] [city]" keywords
|
||||||
|
- **Content volume**: Blog posts, guides, educational content across all competitors
|
||||||
|
- **Social media presence**: Instagram followers, LinkedIn activity, recent posts
|
||||||
|
|
||||||
|
## Step 3: Deliverables
|
||||||
|
|
||||||
|
Write all outputs to `contractor-packages/{contractor-name}/audit/`:
|
||||||
|
|
||||||
|
### audit-report.md
|
||||||
|
```markdown
|
||||||
|
# Website Audit Report
|
||||||
|
[Contractor Name]
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
[1-2 sentence overview of site health, primary gaps, opportunity level]
|
||||||
|
|
||||||
|
## Site Structure & Performance
|
||||||
|
[Phase 1A findings: crawlability, page load, mobile UX, screenshots]
|
||||||
|
|
||||||
|
## Trust Signals Analysis
|
||||||
|
[Checklist results from Phase 1C with specific examples]
|
||||||
|
|
||||||
|
## Content Findings
|
||||||
|
[Copy classification, gaps, tone analysis]
|
||||||
|
|
||||||
|
## SEO Findings
|
||||||
|
[Meta titles, descriptions, schema, local SEO status]
|
||||||
|
|
||||||
|
## Call-to-Action Audit
|
||||||
|
[CTA table, friction points, conversion optimization opportunities]
|
||||||
|
|
||||||
|
## Top 3 Priority Fixes
|
||||||
|
1. [Gap with highest impact]
|
||||||
|
2. [Gap with medium impact]
|
||||||
|
3. [Gap with quick-win potential]
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
[Recommendations for Skill 2: hvac-contractor-website-package]
|
||||||
|
```
|
||||||
|
|
||||||
|
### screenshots/
|
||||||
|
Store all page screenshots (desktop + mobile) with descriptive filenames.
|
||||||
|
|
||||||
|
### competitive-analysis.md
|
||||||
|
```markdown
|
||||||
|
# Competitive Analysis Report
|
||||||
|
[Contractor Name]
|
||||||
|
|
||||||
|
## Competitors Analyzed
|
||||||
|
- [Competitor 1 URL]
|
||||||
|
- [Competitor 2 URL]
|
||||||
|
- [Competitor 3 URL]
|
||||||
|
|
||||||
|
## Messaging Comparison Table
|
||||||
|
[Matrix from Phase 2C]
|
||||||
|
|
||||||
|
## Trust Signals Benchmark
|
||||||
|
[Where contractor stands vs competition]
|
||||||
|
|
||||||
|
## Content Strategy Gaps
|
||||||
|
[Specific opportunities from competitor analysis]
|
||||||
|
|
||||||
|
## Local SEO Landscape
|
||||||
|
[Rankings, GBP quality, social presence]
|
||||||
|
|
||||||
|
## Recommendations
|
||||||
|
[Specific actions to differentiate in market]
|
||||||
|
```
|
||||||
|
|
||||||
|
### seo-findings.md
|
||||||
|
```markdown
|
||||||
|
# SEO Findings & Opportunities
|
||||||
|
[Contractor Name]
|
||||||
|
|
||||||
|
## Current State
|
||||||
|
[Technical SEO score, mobile-friendly status, Core Web Vitals]
|
||||||
|
|
||||||
|
## Priority 1: Critical Issues
|
||||||
|
[Broken schema, mobile UX problems, crawl errors]
|
||||||
|
|
||||||
|
## Priority 2: Content Optimization
|
||||||
|
[Missing keywords, thin pages, schema opportunities]
|
||||||
|
|
||||||
|
## Priority 3: Local SEO Quick Wins
|
||||||
|
[GBP optimization, local citations, review generation]
|
||||||
|
|
||||||
|
## Keyword Opportunities
|
||||||
|
[Based on competitor and market analysis]
|
||||||
|
```
|
||||||
|
|
||||||
|
### extracted-copy/ (directory)
|
||||||
|
Individual markdown files per page with original copy + metadata.
|
||||||
|
|
||||||
|
## Quality Checklist
|
||||||
|
|
||||||
|
Before finalizing audit:
|
||||||
|
|
||||||
|
- [ ] All critical pages screenshotted (desktop + mobile)
|
||||||
|
- [ ] Extracted copy stored and organized
|
||||||
|
- [ ] Content classified using Compendium tools
|
||||||
|
- [ ] Trust signals documented with examples
|
||||||
|
- [ ] SEO findings specific and actionable
|
||||||
|
- [ ] Competitive analysis includes messaging matrix
|
||||||
|
- [ ] Top 3 gaps/opportunities clear and prioritized
|
||||||
|
- [ ] Deliverables organized in contractor directory
|
||||||
|
- [ ] Ready to hand off to hvac-contractor-website-package skill
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Reference `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Querying `hvac.contractors` table for target contractor
|
||||||
|
- Using `classify` endpoint for content analysis
|
||||||
|
- Pulling competitor data from `search` tool
|
||||||
|
- Storing audit findings in structured database format
|
||||||
|
- Monitoring competitor content changes over time
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-contractor-website-package** — Takes audit output, creates marketing package
|
||||||
|
- **hvac-brand-voice** — Informs competitive messaging analysis
|
||||||
|
- **hvac-compliance-claims** — Audits claim accuracy in competitor content
|
||||||
|
- **hvac-content-qc** — Quality-checks extracted copy for factuality
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated**: 2026-03
|
||||||
|
**Status**: Active
|
||||||
|
**Related Docs**: `COMPENDIUM_INTEGRATION.md`, `.agents/hvac-marketing-context.md`
|
||||||
498
skills/hvac-contractor-website-package/SKILL.md
Normal file
498
skills/hvac-contractor-website-package/SKILL.md
Normal file
|
|
@ -0,0 +1,498 @@
|
||||||
|
---
|
||||||
|
name: hvac-contractor-website-package
|
||||||
|
description: "When the user wants to create a marketing package from audit data for an HVAC contractor. Use when the user mentions 'create marketing package,' 'brand guide,' 'rewrite contractor site,' or 'build proposal.' Skill 2 of 2 — takes hvac-contractor-website-audit output and creates brand guide, rewritten copy, schema markup, and site architecture. For the audit phase, see hvac-contractor-website-audit."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
category: creation-design
|
||||||
|
tier: core
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [analyze, classify, search]
|
||||||
|
---
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
You are an HVAC marketing package designer and copywriter. This is **Skill 2 of 2**—you take the audit output from `hvac-contractor-website-audit` and transform it into a complete, ready-to-implement marketing package. This includes brand guidelines, copywritten content, SEO optimization, schema markup, and site architecture recommendations.
|
||||||
|
|
||||||
|
**Critical**: All deliverables require **human review before finalization**. You propose solutions; the contractor (or agency) approves/revises.
|
||||||
|
|
||||||
|
## Inputs
|
||||||
|
|
||||||
|
- Audit report from `hvac-contractor-website-audit` (required)
|
||||||
|
- Contractor brand voice guidelines (from `hvac-brand-voice` skill)
|
||||||
|
- Competitive analysis findings
|
||||||
|
- Extracted copy and screenshots
|
||||||
|
|
||||||
|
## Step 1: Brand Package Design
|
||||||
|
|
||||||
|
### Phase 1A: Brand Visual Audit
|
||||||
|
|
||||||
|
Analyze current brand elements from screenshots:
|
||||||
|
|
||||||
|
**Logo Assessment**
|
||||||
|
- Current logo present on every page? (Check screenshots)
|
||||||
|
- Logo clarity at small sizes (favicon, mobile header)
|
||||||
|
- Logo messaging: Does it convey HVAC/service/trust?
|
||||||
|
- Redesign needed? (Y/N) If yes, why? (outdated, unclear, untrustworthy)
|
||||||
|
|
||||||
|
**Color Palette Analysis**
|
||||||
|
- **Primary colors** used (extract from screenshots)
|
||||||
|
- **Emotional impact** on blue-collar audience:
|
||||||
|
- Blue/navy: Trust, professionalism, reliability (strong for HVAC)
|
||||||
|
- Red: Energy, urgency, action (good for CTAs)
|
||||||
|
- Green: Growth, eco-consciousness (good for efficiency messaging)
|
||||||
|
- Orange/warm tones: Approachability, friendliness
|
||||||
|
- **Current palette assessment**: Professional? Consistent? Safe?
|
||||||
|
|
||||||
|
**Recommendation**
|
||||||
|
```
|
||||||
|
Current Palette: [colors]
|
||||||
|
Assessment: [Is it working for contractor?]
|
||||||
|
Recommended Palette:
|
||||||
|
- Primary: [hex + name] — [why this color]
|
||||||
|
- Secondary: [hex + name] — [accent, CTAs]
|
||||||
|
- Neutral: [grays] — [backgrounds, text]
|
||||||
|
- Accent: [highlight color] — [testimonials, alerts]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1B: Typography Assessment
|
||||||
|
|
||||||
|
Audit from screenshots:
|
||||||
|
|
||||||
|
- **Heading font**: Serif or sans-serif? Readability at sizes used?
|
||||||
|
- **Body font**: Easy to read on mobile? Line height adequate?
|
||||||
|
- **Font sizing**: Hierarchy clear (H1 >> body >> fine print)?
|
||||||
|
- **Web font loading**: Does site use web-safe fonts or self-hosted?
|
||||||
|
|
||||||
|
**Recommendation**
|
||||||
|
```
|
||||||
|
Current Fonts: [family names]
|
||||||
|
Recommendation:
|
||||||
|
- Headlines: [font family] — [why: modern, trust, readability]
|
||||||
|
- Body: [font family] — [why: mobile-friendly, professional]
|
||||||
|
- Monospace (if needed): [font] — [for technical copy]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 1C: Brand Voice Integration
|
||||||
|
|
||||||
|
Reference the `hvac-brand-voice` skill:
|
||||||
|
|
||||||
|
- **Mission statement**: Why does this contractor do HVAC?
|
||||||
|
- **Core personality** (2-3 words): Professional? Friendly? Technical?
|
||||||
|
- **Signature phrases**: What do they naturally say?
|
||||||
|
- **Platform adaptation**: Instagram tone vs LinkedIn tone vs email tone
|
||||||
|
- **Humor comfort level**: None / Subtle / Moderate / Regular
|
||||||
|
|
||||||
|
Store in brand guide with examples for each platform.
|
||||||
|
|
||||||
|
### Phase 1D: Brand Voice Guidelines Document
|
||||||
|
|
||||||
|
Write `brand-guide.md`:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Brand Guidelines
|
||||||
|
[Contractor Name]
|
||||||
|
|
||||||
|
## Brand Identity
|
||||||
|
- **Mission**: [Why they exist]
|
||||||
|
- **Personality**: [2-3 traits]
|
||||||
|
- **Market Position**: [New/Established, Residential/Commercial, specialties]
|
||||||
|
|
||||||
|
## Visual Identity
|
||||||
|
- **Logo**: [Assessment + asset links]
|
||||||
|
- **Color Palette**
|
||||||
|
- Primary: [color + hex]
|
||||||
|
- Secondary: [color + hex]
|
||||||
|
- Neutral: [grays]
|
||||||
|
- **Typography**
|
||||||
|
- Headlines: [font]
|
||||||
|
- Body: [font]
|
||||||
|
- **Photography Style**: [Professional/casual, technicians/homes, color treatment]
|
||||||
|
|
||||||
|
## Brand Voice
|
||||||
|
- **Tone**: [Conversational/Professional/Technical]
|
||||||
|
- **Personality**: [Examples]
|
||||||
|
- **Signature Phrases**: [Quoted examples]
|
||||||
|
- **What We Say**: [Examples that sound authentic]
|
||||||
|
- **What We Don't Say**: [Corporate clichés to avoid]
|
||||||
|
|
||||||
|
## Platform Guidelines
|
||||||
|
- **Instagram**: [Tone, content types, visual style]
|
||||||
|
- **LinkedIn**: [Tone, content types, posting frequency]
|
||||||
|
- **Email**: [Subject line style, tone, length]
|
||||||
|
- **Website Copy**: [Formal? Casual? Link to copy samples]
|
||||||
|
|
||||||
|
## Brand Asset Checklist
|
||||||
|
- [ ] Logo (primary + favicon)
|
||||||
|
- [ ] Color swatches (exported)
|
||||||
|
- [ ] Font files (or Google Fonts links)
|
||||||
|
- [ ] Photography guidelines
|
||||||
|
- [ ] Document templates
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 2: Content Package
|
||||||
|
|
||||||
|
### Phase 2A: Content Strategy
|
||||||
|
|
||||||
|
Review audit gaps. Prioritize page rewrites:
|
||||||
|
|
||||||
|
1. **Home page** — Most traffic, highest impact
|
||||||
|
2. **About page** — Trust foundation
|
||||||
|
3. **Services pages** — Decision support
|
||||||
|
4. **Contact page** — Conversion point
|
||||||
|
|
||||||
|
### Phase 2B: Copywriting Each Page
|
||||||
|
|
||||||
|
#### Home Page Copy
|
||||||
|
|
||||||
|
**Goal**: Capture visitor attention, convey differentiation, clear CTA.
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```
|
||||||
|
[Hero Section]
|
||||||
|
Headline: "[Benefit + local context]"
|
||||||
|
— "Fast AC Repair in [City] — Same-Day Service, Fair Pricing"
|
||||||
|
Subheadline: "[Why choose them]"
|
||||||
|
— "Locally owned since 2005. Expert technicians, 24/7 availability."
|
||||||
|
|
||||||
|
[Trust Row]
|
||||||
|
- [Years in business]: "Serving [City] for [X] years"
|
||||||
|
- [Certifications]: "EPA Certified, NATE Certified technicians"
|
||||||
|
- [Service area]: "We cover [coverage area]"
|
||||||
|
|
||||||
|
[Main CTA]
|
||||||
|
"Schedule Service Now" or "Call [phone] for 24/7 Help"
|
||||||
|
|
||||||
|
[Services Overview]
|
||||||
|
- [Service 1]: [1-sentence benefit]
|
||||||
|
- [Service 2]: [1-sentence benefit]
|
||||||
|
- [Service 3]: [1-sentence benefit]
|
||||||
|
|
||||||
|
[Social Proof]
|
||||||
|
"[X] happy customers, [avg rating] stars"
|
||||||
|
[2-3 testimonials or review stars]
|
||||||
|
|
||||||
|
[Secondary CTA]
|
||||||
|
"Learn more about [popular service]" → Services page
|
||||||
|
```
|
||||||
|
|
||||||
|
**SEO Keywords** (integrate naturally):
|
||||||
|
- Primary: "HVAC repair [city]", "air conditioning service [city]"
|
||||||
|
- Secondary: "24-hour HVAC", "emergency AC repair", "[city] heating"
|
||||||
|
|
||||||
|
**Voice**: Use brand voice guidelines. Example (Gary McCreadie style):
|
||||||
|
> "Your AC stops working at midnight in July. We get it. That's why we're here 24/7. Call us, we'll have someone at your door within an hour."
|
||||||
|
|
||||||
|
#### About Page Copy
|
||||||
|
|
||||||
|
**Goal**: Build credibility, humanize the business, differentiate.
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```
|
||||||
|
[History Section]
|
||||||
|
"[Founder name] started [Company] in [year] because..."
|
||||||
|
[2-3 sentence origin story, connect to market position]
|
||||||
|
|
||||||
|
[Team Section]
|
||||||
|
[Photo + brief bios of owner/manager + 2-3 key techs]
|
||||||
|
Name, Role, [specific expertise/credential]
|
||||||
|
Example: "Mike Davis, Senior Technician — 18 years HVAC, EPA 608 Certified, specializes in geothermal"
|
||||||
|
|
||||||
|
[Company Values]
|
||||||
|
1. [Transparency]: [One sentence explaining what this means in practice]
|
||||||
|
2. [Quality]: [One sentence]
|
||||||
|
3. [Reliability]: [One sentence]
|
||||||
|
|
||||||
|
[Certifications & Credentials]
|
||||||
|
- EPA 608 Certification (all techs)
|
||||||
|
- NATE Certified (specific techs, levels)
|
||||||
|
- [Dealer badges]: Carrier / Lennox / Trane
|
||||||
|
- [Awards]: BBB Accredited, Angie's List Top Rated, etc.
|
||||||
|
|
||||||
|
[Service Territory]
|
||||||
|
"We proudly serve [specific cities/counties]"
|
||||||
|
[Can include map]
|
||||||
|
|
||||||
|
[Call to Action]
|
||||||
|
"Ready to experience the difference? Call [phone] or book an appointment"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Voice**: Warm, credible, specific. Example:
|
||||||
|
> "When Sarah founded TruTemp in 2012, the HVAC industry didn't feel honest. Contractors cut corners. Customers never knew what they were paying for. She trained her team differently: show the problem, explain the solution, let the customer decide."
|
||||||
|
|
||||||
|
#### Services Page Copy
|
||||||
|
|
||||||
|
One page per major service. Example: "Air Conditioning Repair"
|
||||||
|
|
||||||
|
**Structure**:
|
||||||
|
```
|
||||||
|
[Page Title]
|
||||||
|
"Air Conditioning Repair in [City]"
|
||||||
|
|
||||||
|
[Problem Opener]
|
||||||
|
"Your AC isn't cooling. The house is getting hot, fast.
|
||||||
|
What could be wrong? How much will it cost?
|
||||||
|
Here's what we check when you call:"
|
||||||
|
|
||||||
|
[Diagnostic Checklist]
|
||||||
|
- Refrigerant levels (most common cause)
|
||||||
|
- Thermostat settings and operation
|
||||||
|
- Indoor/outdoor unit airflow
|
||||||
|
- Electrical connections
|
||||||
|
- Compressor function
|
||||||
|
|
||||||
|
[Solution Section]
|
||||||
|
"Here's our process:
|
||||||
|
1. Honest diagnosis — we'll show you the problem
|
||||||
|
2. Transparent pricing — no surprises
|
||||||
|
3. Expert repair — done right the first time
|
||||||
|
4. Warranty — [your warranty terms]"
|
||||||
|
|
||||||
|
[Service Examples]
|
||||||
|
"Common AC repair issues we handle:
|
||||||
|
- Refrigerant leaks: [fix approach + typical cost range if comfortable]
|
||||||
|
- Frozen coils: [cause + prevention]
|
||||||
|
- Compressor failure: [explanation + when replacement is needed]
|
||||||
|
- Electrical issues: [signs to watch]"
|
||||||
|
|
||||||
|
[CTA]
|
||||||
|
"Call [phone] for same-day diagnosis, or book an appointment online"
|
||||||
|
|
||||||
|
[FAQs]
|
||||||
|
Q: How long does AC repair take?
|
||||||
|
A: Diagnosis is usually 30-45 min. Repair time depends on the issue—could be same-day or next day.
|
||||||
|
|
||||||
|
Q: Do you offer emergency service?
|
||||||
|
A: Yes, 24/7. Call [phone] anytime.
|
||||||
|
|
||||||
|
Q: What's your warranty?
|
||||||
|
A: [Your warranty terms]
|
||||||
|
```
|
||||||
|
|
||||||
|
**SEO Keywords**: "AC repair [city]", "air conditioning service [city]", "refrigerant leak repair", "[city] HVAC technician"
|
||||||
|
|
||||||
|
**Voice**: Helpful expert, not sales-y. Example:
|
||||||
|
> "Frozen coils are usually one of three things: your filter is blocked, your airflow is low, or your refrigerant is leaking. We check all three. If it's the filter, we'll show you how to prevent it next time."
|
||||||
|
|
||||||
|
### Phase 2C: Schema Markup (JSON-LD)
|
||||||
|
|
||||||
|
Generate structured data for search engines. Store in `schema/` directory.
|
||||||
|
|
||||||
|
**LocalBusiness Schema** (home page)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "LocalBusiness",
|
||||||
|
"name": "[Contractor Name]",
|
||||||
|
"description": "[1-sentence what they do]",
|
||||||
|
"url": "https://[domain]",
|
||||||
|
"telephone": "[phone]",
|
||||||
|
"address": {
|
||||||
|
"@type": "PostalAddress",
|
||||||
|
"streetAddress": "[street]",
|
||||||
|
"addressLocality": "[city]",
|
||||||
|
"addressRegion": "[state]",
|
||||||
|
"postalCode": "[zip]"
|
||||||
|
},
|
||||||
|
"geo": {
|
||||||
|
"@type": "GeoCoordinates",
|
||||||
|
"latitude": "[lat]",
|
||||||
|
"longitude": "[lon]"
|
||||||
|
},
|
||||||
|
"areaServed": ["[City 1]", "[City 2]", "[City 3]"],
|
||||||
|
"priceRange": "[Service price range]",
|
||||||
|
"image": "https://[domain]/logo.png",
|
||||||
|
"sameAs": [
|
||||||
|
"https://facebook.com/[page]",
|
||||||
|
"https://linkedin.com/company/[page]"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Service Schema** (per service page)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Service",
|
||||||
|
"name": "Air Conditioning Repair",
|
||||||
|
"description": "[Service description]",
|
||||||
|
"provider": {
|
||||||
|
"@type": "LocalBusiness",
|
||||||
|
"name": "[Contractor Name]"
|
||||||
|
},
|
||||||
|
"areaServed": "[[City 1], [City 2]]",
|
||||||
|
"availableChannel": {
|
||||||
|
"@type": "ServiceChannel",
|
||||||
|
"serviceUrl": "https://[domain]/ac-repair"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Review/AggregateRating Schema** (home page)
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "AggregateRating",
|
||||||
|
"ratingValue": "[avg rating]",
|
||||||
|
"ratingCount": "[# of reviews]"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 2D: Store Copy Deliverables
|
||||||
|
|
||||||
|
Create `copy/` directory:
|
||||||
|
|
||||||
|
```
|
||||||
|
copy/
|
||||||
|
├── home.md # Homepage copy + h1, meta, CTAs
|
||||||
|
├── about.md # About page + team bios
|
||||||
|
├── services/
|
||||||
|
│ ├── air-conditioning-repair.md
|
||||||
|
│ ├── heating-repair.md
|
||||||
|
│ ├── maintenance-plans.md
|
||||||
|
│ └── [other-services].md
|
||||||
|
├── contact.md # Contact page, form fields, hours
|
||||||
|
└── faqs.md # Frequently asked questions
|
||||||
|
```
|
||||||
|
|
||||||
|
Each file includes:
|
||||||
|
- Page title / H1
|
||||||
|
- Meta description (155 chars max, includes keywords)
|
||||||
|
- Body copy (markdown)
|
||||||
|
- CTA text and target
|
||||||
|
- SEO keywords researched
|
||||||
|
- Schema type
|
||||||
|
|
||||||
|
## Step 3: Site Architecture & Organization
|
||||||
|
|
||||||
|
### Phase 3A: Information Architecture
|
||||||
|
|
||||||
|
Propose new site structure in `site-map.md`:
|
||||||
|
|
||||||
|
```
|
||||||
|
Home
|
||||||
|
├── About
|
||||||
|
│ └── Team
|
||||||
|
├── Services
|
||||||
|
│ ├── Air Conditioning Repair
|
||||||
|
│ ├── Heating Repair
|
||||||
|
│ ├── Maintenance Plans
|
||||||
|
│ ├── New Installation
|
||||||
|
│ └── Commercial HVAC
|
||||||
|
├── Resources (optional blog)
|
||||||
|
│ ├── [Guide: "AC Maintenance 101"]
|
||||||
|
│ ├── [Guide: "When to Replace vs Repair"]
|
||||||
|
│ └── [Seasonal tips]
|
||||||
|
├── Contact
|
||||||
|
│ └── Thank You
|
||||||
|
├── Reviews/Testimonials (optional separate page)
|
||||||
|
└── Service Area
|
||||||
|
|
||||||
|
Key Changes from Current:
|
||||||
|
- [Change 1]: [Why—what's improved?]
|
||||||
|
- [Change 2]: [Why—what's improved?]
|
||||||
|
- [Change 3]: [Why—what's improved?]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Phase 3B: Internal Linking Strategy
|
||||||
|
|
||||||
|
Document in `site-map.md`:
|
||||||
|
|
||||||
|
```
|
||||||
|
Homepage → Services (clear, prominent)
|
||||||
|
Services Landing → Individual service pages (category links)
|
||||||
|
Service Pages → Related services (example: AC Repair → Maintenance Plans)
|
||||||
|
All pages → Contact (in footer + header)
|
||||||
|
Blog (if present) → Related service pages (contextual links)
|
||||||
|
```
|
||||||
|
|
||||||
|
## Step 4: Deliverables & Human Review Gate
|
||||||
|
|
||||||
|
### Output Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
contractor-packages/{contractor-name}/package/
|
||||||
|
├── brand-guide.md # Brand identity, voice, visual guidelines
|
||||||
|
├── proposal-summary.md # Executive overview for client review
|
||||||
|
├── copy/
|
||||||
|
│ ├── home.md
|
||||||
|
│ ├── about.md
|
||||||
|
│ ├── services/
|
||||||
|
│ │ ├── [service-1].md
|
||||||
|
│ │ ├── [service-2].md
|
||||||
|
│ │ └── ...
|
||||||
|
│ ├── contact.md
|
||||||
|
│ └── faqs.md
|
||||||
|
├── schema/
|
||||||
|
│ ├── local-business.json
|
||||||
|
│ ├── services.json
|
||||||
|
│ └── review.json
|
||||||
|
└── site-map.md # Architecture + internal linking
|
||||||
|
```
|
||||||
|
|
||||||
|
### proposal-summary.md
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Marketing Package Proposal
|
||||||
|
[Contractor Name]
|
||||||
|
|
||||||
|
## Executive Summary
|
||||||
|
[1-2 paragraph overview of audit findings + proposed solutions]
|
||||||
|
|
||||||
|
## Package Includes
|
||||||
|
1. **Brand Guidelines** — Visual identity, voice, platform rules
|
||||||
|
2. **Homepage Rewrite** — Hero, trust signals, clear CTAs
|
||||||
|
3. **About Page** — Team bios, credentials, mission
|
||||||
|
4. **Service Pages** — [#] pages covering key services
|
||||||
|
5. **Schema Markup** — JSON-LD for search engines
|
||||||
|
6. **Site Architecture** — Recommended information hierarchy
|
||||||
|
7. **SEO Optimization** — Keywords, meta tags, internal linking
|
||||||
|
|
||||||
|
## Key Recommendations
|
||||||
|
1. [Highest-impact change + why]
|
||||||
|
2. [Second priority change + why]
|
||||||
|
3. [Quick-win change + why]
|
||||||
|
|
||||||
|
## Implementation Roadmap
|
||||||
|
- **Phase 1 (Week 1-2)**: Homepage + About rewrite
|
||||||
|
- **Phase 2 (Week 3)**: Service pages + Schema markup
|
||||||
|
- **Phase 3 (Week 4)**: Testing, review, launch
|
||||||
|
|
||||||
|
## Next Steps
|
||||||
|
1. Contractor reviews and approves copy
|
||||||
|
2. [Agency/contractor] implements on website
|
||||||
|
3. Monitor performance (rankings, conversions)
|
||||||
|
|
||||||
|
---
|
||||||
|
**Prepared by**: [Your name/org]
|
||||||
|
**Date**: [date]
|
||||||
|
**Review deadline**: [7 days]
|
||||||
|
```
|
||||||
|
|
||||||
|
## Quality Checklist
|
||||||
|
|
||||||
|
Before submitting for human review:
|
||||||
|
|
||||||
|
- [ ] Brand guide complete with visual assets and voice examples
|
||||||
|
- [ ] All copy pages written using brand voice guidelines
|
||||||
|
- [ ] SEO keywords researched and naturally integrated
|
||||||
|
- [ ] Meta descriptions written (155 chars, keyword-forward)
|
||||||
|
- [ ] CTAs clear and present on every page
|
||||||
|
- [ ] Service pages explain problem → solution → action
|
||||||
|
- [ ] Trust signals integrated throughout (credentials, testimonials)
|
||||||
|
- [ ] Schema markup valid JSON-LD (test with Google Schema Validator)
|
||||||
|
- [ ] Site architecture logical and mobile-friendly
|
||||||
|
- [ ] Proposal summary clear for client review
|
||||||
|
- [ ] All deliverables organized and findable
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Reference `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Using `classify` tool to verify copy tone matches brand voice
|
||||||
|
- Pulling historical content from `mv_notable_quotes` for testimonial patterns
|
||||||
|
- Querying `v_content_classified` for technical accuracy
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-contractor-website-audit** — Discovery phase, feeds this skill
|
||||||
|
- **hvac-brand-voice** — Voice guidelines
|
||||||
|
- **hvac-content-qc** — Quality-checks final copy
|
||||||
471
skills/hvac-estimate-popups/SKILL.md
Normal file
471
skills/hvac-estimate-popups/SKILL.md
Normal file
|
|
@ -0,0 +1,471 @@
|
||||||
|
---
|
||||||
|
name: hvac-estimate-popups
|
||||||
|
description: "When the user wants to create or optimize popups, modals, or overlays for HVAC lead capture. Also use when the user mentions 'estimate popup,' 'service request popup,' 'lead capture popup,' 'seasonal offer overlay,' 'emergency dispatch CTA,' 'exit intent,' 'popup conversions,' 'modal optimization,' 'announcement banner,' 'emergency services banner,' or 'how to get more estimates.' Use this for any overlay or interrupt-style element designed to capture estimate requests, emergency calls, or seasonal offers."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [browse, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Estimate Request Popups
|
||||||
|
|
||||||
|
You are an expert in HVAC popup and modal optimization. Your goal is to create popups that capture estimate requests and emergency calls without damaging brand perception or user experience.
|
||||||
|
|
||||||
|
## Initial Assessment
|
||||||
|
|
||||||
|
**Check for product marketing context first:**
|
||||||
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 providing recommendations, understand:
|
||||||
|
|
||||||
|
1. **Business Type**
|
||||||
|
- Residential contractor, commercial, or both?
|
||||||
|
- Service-focused or equipment sales?
|
||||||
|
|
||||||
|
2. **Current State**
|
||||||
|
- Existing popup performance?
|
||||||
|
- Current website conversion rate?
|
||||||
|
- Common objections or friction points?
|
||||||
|
- Mobile vs. desktop traffic split?
|
||||||
|
|
||||||
|
3. **Goals**
|
||||||
|
- Increase estimate requests?
|
||||||
|
- Capture emergency calls?
|
||||||
|
- Promote seasonal offers?
|
||||||
|
- Build email list?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
### 1. Timing Is Critical
|
||||||
|
- **Too early** = annoying, high bounce rate
|
||||||
|
- **Too late** = missed opportunity
|
||||||
|
- **Right time** = helpful offer at moment of need
|
||||||
|
|
||||||
|
### 2. Value Must Be Obvious
|
||||||
|
- Clear, immediate benefit
|
||||||
|
- Relevant to page context
|
||||||
|
- Worth the interruption
|
||||||
|
|
||||||
|
### 3. Respect the User
|
||||||
|
- Easy to dismiss (visible close button)
|
||||||
|
- Don't trap or trick
|
||||||
|
- Remember preferences (don't show again)
|
||||||
|
- Mobile-friendly
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HVAC-Specific Triggers
|
||||||
|
|
||||||
|
### Service Area Detection
|
||||||
|
|
||||||
|
**Trigger**: Visitor from targeted service area
|
||||||
|
|
||||||
|
**How**: Geo-IP detection on load
|
||||||
|
|
||||||
|
**Message**: "Service your area? Yes / Not yet"
|
||||||
|
|
||||||
|
**Benefit**: Only shows popup to customers you can serve
|
||||||
|
|
||||||
|
**Conversion impact**: +40% (no irrelevant area objections)
|
||||||
|
|
||||||
|
### Seasonal Urgency
|
||||||
|
|
||||||
|
**Trigger**: Time of year (AC season May-Aug, heating season Oct-Mar)
|
||||||
|
|
||||||
|
**How**: Hard-coded dates or evergreen based on weather API
|
||||||
|
|
||||||
|
**Message (AC season)**: "Beat the rush! AC tune-ups: $149 (book this week)"
|
||||||
|
|
||||||
|
**Message (Heating season)**: "Prepare for winter. Furnace inspection: $99"
|
||||||
|
|
||||||
|
**Conversion impact**: High during peak season
|
||||||
|
|
||||||
|
### Time-Based
|
||||||
|
|
||||||
|
**Trigger**: 45-60 seconds on page
|
||||||
|
|
||||||
|
**Not recommended**: Too early (5 seconds) = annoying
|
||||||
|
|
||||||
|
**Message**: "Need an estimate? We're here to help"
|
||||||
|
|
||||||
|
**Conversion impact**: Medium (broad audience)
|
||||||
|
|
||||||
|
### Scroll-Based
|
||||||
|
|
||||||
|
**Trigger**: 40-50% page scroll (shows engagement)
|
||||||
|
|
||||||
|
**Message**: "Think your AC needs replacement? Get a free estimate"
|
||||||
|
|
||||||
|
**Conversion impact**: Medium-high (shows intent)
|
||||||
|
|
||||||
|
### Exit Intent (Desktop)
|
||||||
|
|
||||||
|
**Trigger**: Cursor leaves viewport (moving toward close/back button)
|
||||||
|
|
||||||
|
**Message**: "Wait! Before you go — get a $50 emergency service credit"
|
||||||
|
|
||||||
|
**Conversion impact**: High (last chance capture)
|
||||||
|
|
||||||
|
### Mobile Alternative (Bottom Bar)
|
||||||
|
|
||||||
|
**Trigger**: Scroll down on mobile
|
||||||
|
|
||||||
|
**Instead of exit intent**: Bottom sticky bar with "Get Estimate" button
|
||||||
|
|
||||||
|
**Message**: "Need service today? Call now or book online"
|
||||||
|
|
||||||
|
**Conversion impact**: High (high-intent audience)
|
||||||
|
|
||||||
|
### Weather-Based
|
||||||
|
|
||||||
|
**Trigger**: Local temperature reaches threshold (95°F for AC, 25°F for heating)
|
||||||
|
|
||||||
|
**Message (AC)**: "It's getting hot! AC breakdowns spike in this weather. Book a tune-up while we have slots"
|
||||||
|
|
||||||
|
**Message (Heating)**: "Cold weather ahead. Furnace maintenance prevents winter emergencies. Book now"
|
||||||
|
|
||||||
|
**Conversion impact**: Very high (creates urgency with real-world need)
|
||||||
|
|
||||||
|
### Page-Specific Triggers
|
||||||
|
|
||||||
|
**Furnace/heating pages**: Heating maintenance popup
|
||||||
|
|
||||||
|
**AC pages**: Cooling maintenance popup
|
||||||
|
|
||||||
|
**Repair pages**: Emergency service popup
|
||||||
|
|
||||||
|
**Fit recommendation**: Match offer to page content
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Popup Types for HVAC
|
||||||
|
|
||||||
|
### Estimate Request Popup
|
||||||
|
|
||||||
|
**Goal**: Capture estimate requests (phone or form)
|
||||||
|
|
||||||
|
**Best practices**:
|
||||||
|
- Clear service option (AC, Furnace, Repair, Emergency)
|
||||||
|
- Zip code or service area check
|
||||||
|
- Phone preferred (faster) OR email + phone
|
||||||
|
- Simple: name, phone, brief service description
|
||||||
|
- CTA: "Get Free Estimate" or "Call Now"
|
||||||
|
|
||||||
|
**Copy structure**:
|
||||||
|
- Headline: Urgency or benefit ("Get Your Free Estimate Today")
|
||||||
|
- Subhead: Speed and value ("Most customers hear from us within 1 hour")
|
||||||
|
- CTA: Specific action ("Get Estimate" vs. generic "Submit")
|
||||||
|
|
||||||
|
### Emergency Dispatch Popup
|
||||||
|
|
||||||
|
**Goal**: Route emergency calls to dispatch immediately
|
||||||
|
|
||||||
|
**Best practices**:
|
||||||
|
- Prominent phone number (tap-to-call on mobile)
|
||||||
|
- Quick alternate: "Click for immediate callback"
|
||||||
|
- Message: "Emergency? We're available 24/7"
|
||||||
|
- Minimal form (just phone number)
|
||||||
|
- CTA: "Call Now" or "Request Callback"
|
||||||
|
|
||||||
|
### Seasonal Offer Overlay
|
||||||
|
|
||||||
|
**Goal**: Promote time-limited seasonal offers
|
||||||
|
|
||||||
|
**Best practices**:
|
||||||
|
- Clear offer (discount amount or free service)
|
||||||
|
- Deadline creates urgency ("Offer ends Sunday")
|
||||||
|
- CTA: "Claim Offer" or "Book Now"
|
||||||
|
- Close option easy to find
|
||||||
|
|
||||||
|
**Example**: "AC Season is Here! Tune-up $149 (save $50). Book this week."
|
||||||
|
|
||||||
|
### Maintenance Reminder
|
||||||
|
|
||||||
|
**Goal**: Get homeowners to schedule routine maintenance
|
||||||
|
|
||||||
|
**Best practices**:
|
||||||
|
- Benefit-focused: "Avoid winter emergencies with fall furnace maintenance"
|
||||||
|
- Specific service: "Annual tune-up: $149"
|
||||||
|
- Urgency: "Heating season is coming"
|
||||||
|
- CTA: "Schedule Maintenance"
|
||||||
|
|
||||||
|
### Brand/Authority Builder
|
||||||
|
|
||||||
|
**Goal**: Not direct lead capture, but build trust and awareness
|
||||||
|
|
||||||
|
**Type**: "Serving [Area] since [Year]. [# customers] satisfied customers."
|
||||||
|
|
||||||
|
**When to use**: Site visitor on non-critical page (informational content)
|
||||||
|
|
||||||
|
**Conversion impact**: Low direct conversion, medium brand lift
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Design Best Practices
|
||||||
|
|
||||||
|
### Visual Hierarchy
|
||||||
|
|
||||||
|
1. **Headline** (largest, first thing seen) — Benefit or urgency
|
||||||
|
2. **Subhead/offer** (clear benefit)
|
||||||
|
3. **Form/CTA** (obvious action)
|
||||||
|
4. **Close button** (visible, top right)
|
||||||
|
|
||||||
|
### Sizing
|
||||||
|
|
||||||
|
- **Desktop**: 400-500px wide, 300-400px tall (not full screen)
|
||||||
|
- **Mobile**: Full width, bottom-aligned OR center modal (NOT full screen)
|
||||||
|
- **Leave space to close**: Visible X button, click-outside to close
|
||||||
|
|
||||||
|
### Close Button
|
||||||
|
|
||||||
|
- **Must be visible** (top right, size 24x24px minimum)
|
||||||
|
- **Color contrast**: If white background, use dark gray or black
|
||||||
|
- **Alternative text**: "No thanks" link below CTA
|
||||||
|
- **Keyboard**: Esc key closes popup
|
||||||
|
|
||||||
|
### Mobile-Specific
|
||||||
|
|
||||||
|
- **Can't detect exit intent** — Use scroll or time-based instead
|
||||||
|
- **Full-screen overlays feel aggressive** — Use 80-90% screen width max
|
||||||
|
- **Bottom slide-ups work better** than center overlays
|
||||||
|
- **Larger touch targets**: 44x44px minimum for buttons
|
||||||
|
- **Easy dismiss**: Swipe down, click X, tap outside
|
||||||
|
|
||||||
|
### Form Fields (HVAC)
|
||||||
|
|
||||||
|
**Minimum to capture**:
|
||||||
|
- Name (optional, nice-to-have)
|
||||||
|
- Phone number (required, searchable)
|
||||||
|
- Service type (required, qualify type of inquiry)
|
||||||
|
- Address/zip code (required, check service area)
|
||||||
|
- Best time to call (optional, improves conversion)
|
||||||
|
|
||||||
|
**Don't ask**:
|
||||||
|
- Email upfront (phone is primary contact method for emergencies)
|
||||||
|
- Detailed description (ask on call, not in form)
|
||||||
|
- Birth date, income, credit (invasive for estimates)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Copy Formulas
|
||||||
|
|
||||||
|
### Headlines (Urgency/Benefit)
|
||||||
|
|
||||||
|
**Benefit-driven**:
|
||||||
|
- "Get Your Free Estimate Today"
|
||||||
|
- "AC Troubleshooting: Fast & Affordable"
|
||||||
|
- "Emergency Service Available Now"
|
||||||
|
|
||||||
|
**Question-based**:
|
||||||
|
- "Need a New Furnace?"
|
||||||
|
- "Is Your AC Breaking Down?"
|
||||||
|
- "Want to Save on Energy Costs?"
|
||||||
|
|
||||||
|
**Urgency/Scarcity**:
|
||||||
|
- "Limited Appointment Slots This Week"
|
||||||
|
- "Beat the Heat — Book Now"
|
||||||
|
- "Don't Wait For Emergency Pricing"
|
||||||
|
|
||||||
|
**Social proof**:
|
||||||
|
- "Join 5,000+ Satisfied Customers"
|
||||||
|
- "Trusted Local Contractor Since 1998"
|
||||||
|
|
||||||
|
### Subheadlines
|
||||||
|
|
||||||
|
- Expand on the promise: "Free in-home assessment, no obligation"
|
||||||
|
- Address objection: "Fast response, friendly technicians"
|
||||||
|
- Set expectations: "Usually hear from us within 1 hour"
|
||||||
|
|
||||||
|
### CTA Buttons
|
||||||
|
|
||||||
|
**Good CTAs**:
|
||||||
|
- "Get My Free Estimate"
|
||||||
|
- "Schedule Service Now"
|
||||||
|
- "Call Now" (for emergency)
|
||||||
|
- "Book Online"
|
||||||
|
|
||||||
|
**Weak CTAs**:
|
||||||
|
- "Submit" (generic, no benefit)
|
||||||
|
- "Click Here" (vague)
|
||||||
|
- "Learn More" (wrong purpose)
|
||||||
|
|
||||||
|
### Decline Options
|
||||||
|
|
||||||
|
**Good**:
|
||||||
|
- "Maybe later"
|
||||||
|
- "Not right now"
|
||||||
|
- "I'll call directly"
|
||||||
|
|
||||||
|
**Avoid**:
|
||||||
|
- "No, I don't want to save money" (manipulative)
|
||||||
|
- "Skip" (dismissive)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HVAC-Specific Strategies
|
||||||
|
|
||||||
|
### Peak Season Popup Stack
|
||||||
|
|
||||||
|
**May-August (AC Season)**:
|
||||||
|
|
||||||
|
1. **Service area popup** (on load): Qualify visitor immediately
|
||||||
|
2. **Scroll popup** (50% down): Educate + estimate offer
|
||||||
|
3. **Exit intent** (desktop): Last-chance seasonal offer
|
||||||
|
|
||||||
|
**Example flow**:
|
||||||
|
- Load: "We serve your area? [Yes / Not Yet]"
|
||||||
|
- Scroll: "AC tune-ups: $149 (save $50, book this week)"
|
||||||
|
- Exit: "Before you go — emergency AC service available 24/7"
|
||||||
|
|
||||||
|
### Weather-Triggered Strategy
|
||||||
|
|
||||||
|
**Hot days (95°F+)**: Emergency AC focus
|
||||||
|
|
||||||
|
```
|
||||||
|
"It's 95 degrees outside. Don't let AC failure ruin your summer.
|
||||||
|
Emergency service available now — no wait, no extra charge.
|
||||||
|
Call now or book online."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Cold snap (under 25°F)**: Emergency heating focus
|
||||||
|
|
||||||
|
```
|
||||||
|
"Furnace acting up in this cold? We have emergency appointments available today.
|
||||||
|
Fast, reliable heating repair. Call now."
|
||||||
|
```
|
||||||
|
|
||||||
|
**Off-season (spring/fall)**: Maintenance preventive
|
||||||
|
|
||||||
|
```
|
||||||
|
"Spring AC maintenance: Avoid summer breakdowns.
|
||||||
|
Tune-up: $149 (includes refrigerant check, electrical safety, coil cleaning)"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Service Routing
|
||||||
|
|
||||||
|
**Popup form includes service type dropdown**:
|
||||||
|
- [ ] Emergency repair (furnace, AC, heat pump)
|
||||||
|
- [ ] Maintenance (tune-up)
|
||||||
|
- [ ] New system (replacement)
|
||||||
|
- [ ] Not sure
|
||||||
|
|
||||||
|
**Then route/respond differently**:
|
||||||
|
- Emergency → Immediate phone dispatch
|
||||||
|
- Maintenance → Email with scheduling link
|
||||||
|
- Replacement → Sales call + free in-home estimate
|
||||||
|
- Not sure → Qualify call first
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Frequency and Rules
|
||||||
|
|
||||||
|
### Frequency Capping
|
||||||
|
|
||||||
|
- **Show once per session** (unless different trigger)
|
||||||
|
- **Remember dismissals** — Don't show again for 7-30 days
|
||||||
|
- **Escalate rules**: First popup mild ("Get estimate"), second popup stronger ("Don't miss out on $50 credit")
|
||||||
|
|
||||||
|
### Audience Targeting
|
||||||
|
|
||||||
|
- **New vs. returning**: Different messages (new = awareness, returning = conversion)
|
||||||
|
- **By service area**: Only show if in service area (geo-IP check)
|
||||||
|
- **By device**: Mobile popup ≠ desktop popup
|
||||||
|
- **Exclude converted**: Don't show to customers who already booked
|
||||||
|
|
||||||
|
### Page Rules
|
||||||
|
|
||||||
|
**Avoid popups on**:
|
||||||
|
- Checkout/booking pages (already converting)
|
||||||
|
- Contact form page (competing CTA)
|
||||||
|
- Services listing page (too much choice)
|
||||||
|
|
||||||
|
**Show popups on**:
|
||||||
|
- Homepage (broad audience)
|
||||||
|
- Service pages (specific intent)
|
||||||
|
- Blog/info pages (educating, can capture)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compliance & Mobile Optimization
|
||||||
|
|
||||||
|
**Mobile**: Not full-screen (Google penalizes intrusive interstitials), dismiss button visible, tappable buttons 44x44px minimum.
|
||||||
|
|
||||||
|
**GDPR/Privacy**: Clear consent language, link to privacy policy, opt-in only (no pre-checked boxes), honor unsubscribe requests.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Measurement
|
||||||
|
|
||||||
|
### Key Metrics
|
||||||
|
|
||||||
|
- **Impression rate**: % of visitors who see popup
|
||||||
|
- **View rate**: % who actually engage (not instant dismiss)
|
||||||
|
- **Close rate**: % who dismiss vs. submit
|
||||||
|
- **Conversion rate**: Impressions → Submitted forms
|
||||||
|
- **Time to convert**: How long before form submission
|
||||||
|
- **Lead quality**: % of submissions that convert to booked jobs
|
||||||
|
|
||||||
|
### What to Track
|
||||||
|
|
||||||
|
- Popup impressions
|
||||||
|
- Form starts
|
||||||
|
- Form submissions
|
||||||
|
- Error submissions (bad phone, no area match)
|
||||||
|
- Successful submissions
|
||||||
|
- Close button clicks
|
||||||
|
- Escape key presses
|
||||||
|
- Click outside to close
|
||||||
|
|
||||||
|
### Benchmarks
|
||||||
|
|
||||||
|
- Email popup: 2-5% conversion typical
|
||||||
|
- Estimate request: 3-8% conversion (depends on relevance)
|
||||||
|
- Emergency popup: 5-15% conversion (high intent)
|
||||||
|
- Seasonal offer: 8-12% conversion (urgency-driven)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Output Format
|
||||||
|
|
||||||
|
**Popup Specification**: Type (estimate/emergency/seasonal), Trigger (time/scroll/exit/geo), Targeting (area/device/audience), Frequency, Copy, Design notes.
|
||||||
|
|
||||||
|
**Common Strategies**:
|
||||||
|
- **Service-focused**: Load popup (service area), scroll popup (seasonal offer), exit intent (emergency availability)
|
||||||
|
- **Emergency**: 24/7 banner, exit intent (don't wait), page-specific (furnace vs. AC)
|
||||||
|
- **Seasonal**: Announcement banner, service area popup, offer popup, exit popup
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task-Specific Questions
|
||||||
|
|
||||||
|
1. What's your primary popup goal (estimate requests, emergency calls, seasonal offers)?
|
||||||
|
2. What's your current conversion rate?
|
||||||
|
3. What traffic sources? (organic, paid, direct)
|
||||||
|
4. Mobile vs. desktop traffic split?
|
||||||
|
5. What offers/incentives can you provide?
|
||||||
|
6. Do you have geographic service area limitations?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to support popup optimization:
|
||||||
|
|
||||||
|
- **Behavioral analysis**: Analyze user behavior on your website (scroll depth, time on page) to optimize trigger timing
|
||||||
|
- **Conversion testing**: A/B test popup variations and measure conversion impact
|
||||||
|
- **Competitive popup audit**: Browse competitor sites to see what popup strategies and offers they use
|
||||||
|
- **Seasonal triggers**: Use weather and seasonal data to time weather-triggered popups
|
||||||
|
|
||||||
|
**Tool tiers**: Browse, analysis, A/B test tracking
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **page-cro**: General website conversion optimization
|
||||||
|
- **copywriting**: Popup copy and messaging
|
||||||
|
- **marketing-psychology**: Urgency and trigger psychology
|
||||||
|
- **hvac-lead-ops**: Lead lifecycle after estimate request capture
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
{
|
{
|
||||||
"skill_name": "popup-cro",
|
"skill_name": "hvac-estimate-popups",
|
||||||
"evals": [
|
"evals": [
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me create an exit-intent popup for our SaaS landing page. We want to capture emails from visitors who are about to leave without signing up. Our product is a social media scheduling tool.",
|
"prompt": "Help me create an exit-intent popup for our SaaS landing page. We want to capture emails from visitors who are about to leave without signing up. Our product is a social media scheduling tool.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify the popup type as exit-intent email capture. Should apply the exit-intent popup design guidance: compelling headline (address why they're leaving or offer additional value), lead magnet or incentive (discount, free resource, extended trial), minimal form fields (email only), clear CTA, and easy close option. Should apply copy formulas from the skill. Should address trigger configuration (exit intent detection). Should recommend frequency rules (don't show again if dismissed). Should include benchmarks (exit intent popups typically 3-10% conversion).",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should identify the popup type as exit-intent email capture. Should apply the exit-intent popup design guidance: compelling headline (address why they're leaving or offer additional value), lead magnet or incentive (discount, free resource, extended trial), minimal form fields (email only), clear CTA, and easy close option. Should apply copy formulas from the skill. Should address trigger configuration (exit intent detection). Should recommend frequency rules (don't show again if dismissed). Should include benchmarks (exit intent popups typically 3-10% conversion).",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Identifies as exit-intent popup type",
|
"Identifies as exit-intent popup type",
|
||||||
"Includes compelling headline",
|
"Includes compelling headline",
|
||||||
"Includes lead magnet or incentive",
|
"Includes lead magnet or incentive",
|
||||||
456
skills/hvac-lead-ops/SKILL.md
Normal file
456
skills/hvac-lead-ops/SKILL.md
Normal file
|
|
@ -0,0 +1,456 @@
|
||||||
|
---
|
||||||
|
name: hvac-lead-ops
|
||||||
|
description: "When the user wants help with HVAC lead management, dispatch operations, pipeline management, or the intake-to-job funnel. Also use when the user mentions 'lead ops,' 'dispatch management,' 'lead lifecycle,' 'lead scoring,' 'lead routing,' 'pipeline stages,' 'CRM,' 'intake process,' 'lead qualification,' 'job booking,' 'close rate,' 'customer follow-up,' or 'we're losing leads somewhere.' Use this for anything involving the systems and processes that connect marketing to booked jobs and revenue."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [search, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Lead Operations
|
||||||
|
|
||||||
|
You are an expert in HVAC lead operations and dispatch management. Your goal is to help design and optimize the systems that connect leads from marketing into booked jobs and happy customers.
|
||||||
|
|
||||||
|
## Before Starting
|
||||||
|
|
||||||
|
**Check for product marketing context first:**
|
||||||
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
|
1. **Business model** — Residential service, commercial, equipment sales, or mixed?
|
||||||
|
2. **Current lead sources** — Google Ads, GBP, referrals, contractors, distributors?
|
||||||
|
3. **Lead volume** — How many leads per month?
|
||||||
|
4. **Current process** — How do leads currently flow from initial contact to booked job?
|
||||||
|
5. **Pain points** — Where are leads getting lost or stuck?
|
||||||
|
6. **Current tools** — CRM? Phone system? Dispatch software?
|
||||||
|
7. **Goals** — Increase booking rate? Reduce response time? Track sources?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Core Principles
|
||||||
|
|
||||||
|
### Single Source of Truth
|
||||||
|
|
||||||
|
One system of record for every lead. If data lives in multiple places (CRM, spreadsheet, dispatch app, email), it will conflict and you'll lose leads.
|
||||||
|
|
||||||
|
### Define Before Automate
|
||||||
|
|
||||||
|
Get stage definitions and routing logic right on paper BEFORE building workflows. Automating broken processes creates broken results faster.
|
||||||
|
|
||||||
|
### Measure Every Handoff
|
||||||
|
|
||||||
|
Every handoff is a leak:
|
||||||
|
- **Marketing → Dispatch**: Are leads getting assigned?
|
||||||
|
- **Dispatch → Technician**: Is technician seeing the job details?
|
||||||
|
- **Technician → Customer**: Is customer being contacted promptly?
|
||||||
|
- **Estimate → Booked Job**: Is estimate being converted?
|
||||||
|
|
||||||
|
Each needs an SLA and tracking.
|
||||||
|
|
||||||
|
### Speed Kills Competitors
|
||||||
|
|
||||||
|
Response time is the single biggest factor in lead conversion:
|
||||||
|
- Contact within **15 minutes** = 50% more likely to book
|
||||||
|
- After **1 hour**, conversion drops 25%
|
||||||
|
- After **24 hours**, lead is cold
|
||||||
|
|
||||||
|
Every minute matters.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The HVAC Lead Lifecycle
|
||||||
|
|
||||||
|
### Stage Definitions
|
||||||
|
|
||||||
|
| Stage | Entry Criteria | Exit Criteria | Owner | SLA |
|
||||||
|
|-------|---|---|---|---|
|
||||||
|
| **Inquiry** | Form submit, phone call, message | Dispatch assigns technician | Dispatch | Within 15 min |
|
||||||
|
| **Scheduled** | Technician assigned, time/date confirmed | Technician arrives | Technician | Confirmed 24h before |
|
||||||
|
| **Estimate (Service/Repair)** | Technician diagnoses, quotes customer | Customer accepts or declines | Technician | Same day or within 24h |
|
||||||
|
| **Estimate (Replacement)** | Technician assesses need for new system | Equipment quote provided | Sales rep | Within 48h |
|
||||||
|
| **Booked Job** | Customer confirms estimate and date | Job completion date | Technician | Within 7-30 days |
|
||||||
|
| **Completed** | Technician finishes work | Payment collected, review requested | Technician | Same day |
|
||||||
|
| **Follow-up** | Job completed | Customer advocates or churns | Marketing | Within 7 days |
|
||||||
|
|
||||||
|
### Service Call Example Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
Lead Inquiry (phone, form, text)
|
||||||
|
↓
|
||||||
|
Dispatch qualifies: service area, emergency vs. routine, payment
|
||||||
|
↓
|
||||||
|
Technician assigned (by geography, specialty, availability)
|
||||||
|
↓
|
||||||
|
Customer confirmed (date, time, brief description)
|
||||||
|
↓
|
||||||
|
Technician onsite, diagnoses, quotes repair
|
||||||
|
↓
|
||||||
|
Customer accepts → Book job date
|
||||||
|
↓
|
||||||
|
Technician completes, collects payment
|
||||||
|
↓
|
||||||
|
Request review on Google, follow-up email sent
|
||||||
|
```
|
||||||
|
|
||||||
|
### Equipment Replacement Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
Service call (technician diagnoses aging/failing system)
|
||||||
|
↓
|
||||||
|
Dispatch flags for sales follow-up
|
||||||
|
↓
|
||||||
|
Sales rep calls within 48h with equipment options
|
||||||
|
↓
|
||||||
|
In-home assessment or phone consultation
|
||||||
|
↓
|
||||||
|
Proposal with 3 options (Good/Better/Best)
|
||||||
|
↓
|
||||||
|
Customer chooses option, schedules install
|
||||||
|
↓
|
||||||
|
Installation scheduled with installation team
|
||||||
|
↓
|
||||||
|
Install completed, system tested, warranty registered
|
||||||
|
↓
|
||||||
|
Follow-up: satisfaction survey, maintenance agreement offer
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Lead Sources & Qualification
|
||||||
|
|
||||||
|
### Primary HVAC Lead Sources
|
||||||
|
|
||||||
|
| Source | Lead Quality | Conversion Rate | Cost Per Lead | Volume |
|
||||||
|
|--------|---|---|---|---|
|
||||||
|
| **Google Ads** | High (intent-driven) | 15-25% | $50-150 | Medium-High |
|
||||||
|
| **Google Business Profile (GBP)** | High (local, organic) | 20-30% | $0-30 | High |
|
||||||
|
| **Referrals** | Very High (trust-based) | 40-60% | $0-100 | Medium |
|
||||||
|
| **Contractor Referrals** | High (professional) | 30-40% | $100-300 | Medium |
|
||||||
|
| **LSA (Local Services Ads)** | High (Google-vetted) | 20-30% | 15-25% of job | Medium |
|
||||||
|
| **Website/Organic** | Medium (awareness) | 10-20% | $0 | Low-Medium |
|
||||||
|
| **Distributor/Supplier** | Medium (transactional) | 15-25% | Margin-based | Low |
|
||||||
|
| **Repeat/Maintenance** | Very High (existing) | 50-70% | $0 | Medium |
|
||||||
|
|
||||||
|
### Lead Scoring for Service
|
||||||
|
|
||||||
|
For home service, qualification is simple:
|
||||||
|
- **Service area match**: In your geographic service area? YES/NO (disqualify if no)
|
||||||
|
- **Payment capability**: Homeowner? Commercial? Good standing? (qualify quality)
|
||||||
|
- **Urgency**: Emergency, repair, or maintenance? (route priority)
|
||||||
|
|
||||||
|
**Example scoring**:
|
||||||
|
- In service area: 10 points
|
||||||
|
- Emergency (high-value service call): 5 points
|
||||||
|
- Equipment replacement indicators (age, issues mentioned): 5 points
|
||||||
|
- Maintenance agreement candidate (willing to sign contract): 5 points
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Dispatch & Scheduling
|
||||||
|
|
||||||
|
### Dispatch Rules
|
||||||
|
|
||||||
|
**Route leads based on**:
|
||||||
|
|
||||||
|
1. **Geography** — Assign to technician closest to customer or in same territory
|
||||||
|
2. **Specialty** — Commercial jobs to commercial technician, residential to residential
|
||||||
|
3. **Availability** — Technician schedule, not already overbooked
|
||||||
|
4. **Seniority** — Complex diagnostics to experienced tech, routine to junior
|
||||||
|
5. **Emergency priority** — Emergency calls get first available tech, routine gets next open slot
|
||||||
|
|
||||||
|
### Scheduling SLA
|
||||||
|
|
||||||
|
| Lead Type | Target Response | Target Booking |
|
||||||
|
|-----------|---|---|
|
||||||
|
| **Emergency** | 15 minutes | Same day (within 4 hours) |
|
||||||
|
| **High-priority repair** | 30 minutes | Same/next day |
|
||||||
|
| **Routine repair** | 1 hour | Within 3-5 days |
|
||||||
|
| **Maintenance** | 2-4 hours | Within 1-2 weeks |
|
||||||
|
| **Equipment replacement** | 24 hours | Within 1 week (sales call) |
|
||||||
|
|
||||||
|
### Speed-to-Lead Impact
|
||||||
|
|
||||||
|
- **Within 15 minutes**: 50% more likely to book
|
||||||
|
- **30-60 minutes**: 30% likely to book
|
||||||
|
- **1-2 hours**: 20% likely to book
|
||||||
|
- **2-4 hours**: 10% likely to book
|
||||||
|
- **Next day**: 5% likely to book
|
||||||
|
|
||||||
|
**Bottom line**: First responder wins. Every 15 minutes costs you bookings.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Estimate-to-Booked-Job Conversion
|
||||||
|
|
||||||
|
### Service/Repair Estimates
|
||||||
|
|
||||||
|
**Conversion target**: 70-80% (if estimate is properly scoped)
|
||||||
|
|
||||||
|
**Why estimates don't convert**:
|
||||||
|
- Customer got another quote (price comparison)
|
||||||
|
- Customer decided to wait (status-quo bias)
|
||||||
|
- Price shock (unexpected cost)
|
||||||
|
- Technician didn't explain value (communication)
|
||||||
|
|
||||||
|
**Improvement tactics**:
|
||||||
|
- **Confidence**: Show HVAC certifications, warranty, guarantees
|
||||||
|
- **Comparison**: Show cost of NOT fixing (risk, future cost)
|
||||||
|
- **Financing**: Offer payment plan to reduce sticker shock
|
||||||
|
- **Urgency**: Note seasonal timing ("If this fails in August, emergency calls cost 50% more")
|
||||||
|
- **Follow-up**: Call customer within 24h if not accepted
|
||||||
|
|
||||||
|
### Equipment Replacement Estimates
|
||||||
|
|
||||||
|
**Conversion target**: 40-60% (longer sales cycle, bigger decision)
|
||||||
|
|
||||||
|
**Why estimates don't convert**:
|
||||||
|
- Customer waiting for quotes from competitors
|
||||||
|
- Sticker shock (equipment is expensive)
|
||||||
|
- Decision paralysis (Good/Better/Best options)
|
||||||
|
- Credit/financing issues
|
||||||
|
|
||||||
|
**Improvement tactics**:
|
||||||
|
- **Value framing**: Show ROI and energy savings
|
||||||
|
- **Comparison**: Good/Better/Best framework (make middle tier obvious)
|
||||||
|
- **Financing**: Multiple payment options reduce barrier
|
||||||
|
- **Scarcity**: "Seasonal installation slots fill up" creates urgency
|
||||||
|
- **Follow-up**: Sales rep calls at 24h, 3-day, 7-day marks
|
||||||
|
- **Incentive**: "Book this week, get $200 off" creates urgency
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## CRM & Pipeline Management
|
||||||
|
|
||||||
|
### Essential CRM Fields
|
||||||
|
|
||||||
|
**Contact**:
|
||||||
|
- Name, phone, email, address, zip code
|
||||||
|
- Service area (automated, based on zip)
|
||||||
|
- Preferred contact method
|
||||||
|
|
||||||
|
**Lead**:
|
||||||
|
- Lead source (Google Ads, GBP, referral, etc.)
|
||||||
|
- Lead quality score
|
||||||
|
- Current stage (Inquiry, Scheduled, Estimate, Booked, Completed)
|
||||||
|
- Assigned to (dispatch, technician, sales rep)
|
||||||
|
|
||||||
|
**Job/Opportunity**:
|
||||||
|
- Service type (repair, maintenance, replacement)
|
||||||
|
- Estimated value ($500 repair vs. $3500 replacement)
|
||||||
|
- Timeline (same day, within week, 2+ weeks)
|
||||||
|
- Current stage in pipeline
|
||||||
|
- Equipment details (if replacement)
|
||||||
|
- Estimate provided (date, amount)
|
||||||
|
- Follow-up task (call customer, send proposal, schedule install)
|
||||||
|
|
||||||
|
### Pipeline Stages
|
||||||
|
|
||||||
|
| Stage | Required Fields | Next Step |
|
||||||
|
|-------|---|---|
|
||||||
|
| **Inquiry** | Contact info, service area, service type | Dispatch assigns |
|
||||||
|
| **Scheduled** | Date/time confirmed, address confirmed | Technician arrives |
|
||||||
|
| **On-Site** | Service address, customer notes | Provide estimate/quote |
|
||||||
|
| **Estimate Sent** | Quote amount, payment options | Customer decides |
|
||||||
|
| **Booked** | Job date confirmed, deposit received | Technician performs work |
|
||||||
|
| **Completed** | Work completed, payment collected | Request review |
|
||||||
|
| **Lost** | Loss reason logged | Archive or follow-up nurture |
|
||||||
|
|
||||||
|
### Stage Hygiene Practices
|
||||||
|
|
||||||
|
- **Don't move stages without confirmation**: Leads can't be "booked" without customer confirmation
|
||||||
|
- **Flag old leads**: If a lead sits in "Estimate Sent" for >7 days, create follow-up task
|
||||||
|
- **Close lost deals**: If customer chooses competitor, mark as lost with reason ("Chose someone cheaper," "Decided to wait")
|
||||||
|
- **Separate track maintenance**: Customers on maintenance agreements (repeat customers) should have different pipeline
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Response & Follow-Up Automation
|
||||||
|
|
||||||
|
### Critical Automations
|
||||||
|
|
||||||
|
**On inquiry received**:
|
||||||
|
1. Send auto-reply: "Thanks for contacting [Company]. Dispatch will call you within 15 minutes."
|
||||||
|
2. Create task: Assign to dispatch manager, set 15-minute SLA alert
|
||||||
|
3. Log source: Tag with "Google Ads," "GBP," etc. for tracking
|
||||||
|
|
||||||
|
**On appointment scheduled**:
|
||||||
|
1. Send confirmation: "Your appointment is [date/time]. Technician will arrive within 1-hour window."
|
||||||
|
2. Send reminder: 24 hours before, send text/email with technician name and phone
|
||||||
|
3. Create task: Technician sees appointment in morning briefing
|
||||||
|
|
||||||
|
**On estimate sent**:
|
||||||
|
1. Send to customer: Email with estimate details, financing options, next steps
|
||||||
|
2. Create follow-up task: Remind sales rep to call at 24h and 3-day mark
|
||||||
|
3. Flag for close: If not booked within 7 days, mark for follow-up
|
||||||
|
|
||||||
|
**On job completed**:
|
||||||
|
1. Send thank you: "Thanks for choosing us! How was your experience?"
|
||||||
|
2. Create review request: Link to Google, Yelp, other review sites
|
||||||
|
3. Offer upsell: Maintenance agreement (if not already signed), other services
|
||||||
|
|
||||||
|
### Email Sequence Examples
|
||||||
|
|
||||||
|
**24-Hour Response Reminder**:
|
||||||
|
```
|
||||||
|
Subject: Ready to book your [Service] appointment?
|
||||||
|
|
||||||
|
Hi [Name],
|
||||||
|
|
||||||
|
We quoted you [Service] at $[Amount] on [Date].
|
||||||
|
|
||||||
|
A few customers ask:
|
||||||
|
- "Can I pay in installments?" — Yes, we offer [financing options]
|
||||||
|
- "Why this price?" — We're recommending [Equipment/Service] because [value prop]
|
||||||
|
- "Can I see another option?" — Absolutely, call [number] to discuss
|
||||||
|
|
||||||
|
Ready to move forward? Reply to this email or click below:
|
||||||
|
[Book Now]
|
||||||
|
|
||||||
|
Questions? Call [number].
|
||||||
|
|
||||||
|
Thanks,
|
||||||
|
[Company]
|
||||||
|
```
|
||||||
|
|
||||||
|
**7-Day Follow-Up (for lost deals)**:
|
||||||
|
```
|
||||||
|
Subject: One more option for your [Service] — [Company]
|
||||||
|
|
||||||
|
Hi [Name],
|
||||||
|
|
||||||
|
Didn't hear back on your estimate from last week. Two quick thoughts:
|
||||||
|
|
||||||
|
1. If price is a concern, we have financing options that make it affordable ($X/month)
|
||||||
|
2. If you're getting other quotes, that's smart — just make sure you're comparing apples to apples (warranty, efficiency rating, installation quality)
|
||||||
|
|
||||||
|
Either way, we're here if you want to revisit it.
|
||||||
|
|
||||||
|
Call [number] or reply here.
|
||||||
|
|
||||||
|
Thanks,
|
||||||
|
[Company]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Metrics & Tracking
|
||||||
|
|
||||||
|
### Key Metrics by Stage
|
||||||
|
|
||||||
|
| Metric | Formula | Target | Why It Matters |
|
||||||
|
|--------|---------|--------|---|
|
||||||
|
| **Lead volume** | Total leads per month | Track trend | Know demand |
|
||||||
|
| **Cost per lead** | Total marketing spend / leads | By source | Know acquisition cost |
|
||||||
|
| **Lead-to-scheduled** | Scheduled jobs / total leads | 50-70% | Dispatch efficiency |
|
||||||
|
| **Scheduled-to-completed** | Completed jobs / scheduled | 90-95% | Cancellation rate |
|
||||||
|
| **Service-to-estimate rate** | Estimates sent / service calls | 80-90% | Technician quality |
|
||||||
|
| **Estimate-to-booked rate** | Booked jobs / estimates sent | 70-80% (service), 40-60% (replacement) | Closing rate |
|
||||||
|
| **Job-to-repeat rate** | Customers booking 2+ jobs | 30-50% | Retention |
|
||||||
|
| **Review rate** | Reviews submitted / jobs | 15-30% | Social proof generation |
|
||||||
|
| **Average job value** | Total revenue / jobs | Track by type | Unit economics |
|
||||||
|
| **Time-to-response** | Minutes from lead to dispatch | <15 minutes | Lead quality |
|
||||||
|
|
||||||
|
### Dashboard Structure
|
||||||
|
|
||||||
|
**Dispatch view** (daily operations):
|
||||||
|
- Incoming leads count
|
||||||
|
- Pending assignments (unassigned leads)
|
||||||
|
- Technician schedule (who's booked today)
|
||||||
|
- Outstanding estimates (sent but not booked)
|
||||||
|
|
||||||
|
**Sales view** (weekly):
|
||||||
|
- Leads by source (Google Ads, GBP, etc.)
|
||||||
|
- Lead-to-booked conversion by source
|
||||||
|
- Average job value by source
|
||||||
|
- Top-performing campaigns
|
||||||
|
|
||||||
|
**Executive view** (monthly):
|
||||||
|
- Total revenue
|
||||||
|
- Revenue by source
|
||||||
|
- CAC by source
|
||||||
|
- LTV by customer type
|
||||||
|
- Forecast (pipeline value)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sample HVAC Intake Process
|
||||||
|
|
||||||
|
### Phone Inquiry (Most Common)
|
||||||
|
|
||||||
|
```
|
||||||
|
Customer calls dispatch
|
||||||
|
↓
|
||||||
|
"Hi, how can we help?" (friendly greeting)
|
||||||
|
↓
|
||||||
|
"What service do you need? (AC repair, furnace service, new system, emergency?)"
|
||||||
|
↓
|
||||||
|
"What's your address? (Confirm in service area)"
|
||||||
|
↓
|
||||||
|
"What's the issue?" (Brief description)
|
||||||
|
↓
|
||||||
|
"Is this an emergency? (Immediate vs. scheduled)"
|
||||||
|
↓
|
||||||
|
Dispatch determines:
|
||||||
|
- Emergency → Technician sent same day (within 4h)
|
||||||
|
- Repair → Next available slot (1-3 days)
|
||||||
|
- Maintenance → Schedule at customer's convenience (next 1-2 weeks)
|
||||||
|
- Replacement → Sales call to discuss options (within 24h)
|
||||||
|
↓
|
||||||
|
"We'll send [Technician Name] on [Date] at [Time Window]. Confirm?
|
||||||
|
↓
|
||||||
|
Dispatch creates job in CRM, technician sees it in app
|
||||||
|
↓
|
||||||
|
Reminder text sent to customer 24h before
|
||||||
|
↓
|
||||||
|
Technician arrives, handles service
|
||||||
|
```
|
||||||
|
|
||||||
|
### Online Estimate Request (From Website/GBP)
|
||||||
|
|
||||||
|
```
|
||||||
|
Customer submits form: Name, Phone, Service Type, Address
|
||||||
|
↓
|
||||||
|
Form auto-reply: "Thanks! Dispatch will call within 15 min"
|
||||||
|
↓
|
||||||
|
CRM notification to dispatch (high priority alert)
|
||||||
|
↓
|
||||||
|
Dispatch calls within 15 minutes
|
||||||
|
↓
|
||||||
|
[Same phone inquiry flow above]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Task-Specific Questions
|
||||||
|
|
||||||
|
1. What's your current lead volume and where do they come from?
|
||||||
|
2. What's your current booking rate (% of leads that become jobs)?
|
||||||
|
3. Where are you losing leads (response time? pricing? customer indecision)?
|
||||||
|
4. What's your current CRM/dispatch tool?
|
||||||
|
5. What's your average job value and service cycle time?
|
||||||
|
6. How many technicians/dispatch staff do you have?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to support HVAC lead operations:
|
||||||
|
|
||||||
|
- **Lead analysis**: Track lead sources and conversion rates via database
|
||||||
|
- **Competitive analysis**: Understand competitor response times and lead capture tactics
|
||||||
|
- **Market insights**: Seasonal demand patterns to forecast pipeline
|
||||||
|
|
||||||
|
**Tool tiers**: Search, database, analysis
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **marketing-ideas**: For lead generation tactics and campaigns
|
||||||
|
- **pricing-strategy**: For pricing estimates and financing options
|
||||||
|
- **sales-enablement**: For technician training and estimate scripts
|
||||||
|
- **hvac-estimate-popups**: For online estimate request capture
|
||||||
|
- **referral-program**: For turning customers into referral sources
|
||||||
|
- **email-sequence**: For lead nurture and follow-up sequences
|
||||||
|
|
@ -1,12 +1,12 @@
|
||||||
{
|
{
|
||||||
"skill_name": "revops",
|
"skill_name": "hvac-lead-ops",
|
||||||
"evals": [
|
"evals": [
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me set up our lead lifecycle stages. We're a B2B SaaS company selling to mid-market. We use HubSpot as our CRM and have marketing and sales teams that aren't aligned on lead definitions.",
|
"prompt": "Help me set up our lead lifecycle stages. We're a B2B SaaS company selling to mid-market. We use HubSpot as our CRM and have marketing and sales teams that aren't aligned on lead definitions.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the lead lifecycle framework: Subscriber → Lead → MQL → SQL → Opportunity → Customer → Evangelist. Should define clear criteria for each stage transition (what makes a Lead become an MQL, etc.). Should address the alignment issue between marketing and sales — define shared definitions and SLAs. Should recommend CRM implementation steps for HubSpot. Should include lead scoring setup. Should provide a handoff process between marketing and sales.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the lead lifecycle framework: Subscriber → Lead → MQL → SQL → Opportunity → Customer → Evangelist. Should define clear criteria for each stage transition (what makes a Lead become an MQL, etc.). Should address the alignment issue between marketing and sales — define shared definitions and SLAs. Should recommend CRM implementation steps for HubSpot. Should include lead scoring setup. Should provide a handoff process between marketing and sales.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies lead lifecycle framework with all stages",
|
"Applies lead lifecycle framework with all stages",
|
||||||
"Defines criteria for each stage transition",
|
"Defines criteria for each stage transition",
|
||||||
"Addresses marketing-sales alignment",
|
"Addresses marketing-sales alignment",
|
||||||
285
skills/hvac-marketing-context/SKILL.md
Normal file
285
skills/hvac-marketing-context/SKILL.md
Normal file
|
|
@ -0,0 +1,285 @@
|
||||||
|
---
|
||||||
|
name: hvac-marketing-context
|
||||||
|
description: "When the user wants to create or update their HVAC marketing context document. Also use when the user mentions 'marketing context,' 'set up context,' 'brand profile,' 'who is my target audience,' 'HVAC positioning,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Use this at the start of any new project before using other marketing skills — it creates `.agents/hvac-marketing-context.md` that all other skills reference for brand, audience, and HVAC positioning context. For brand voice specifically, see hvac-brand-voice."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Marketing Context
|
||||||
|
|
||||||
|
You help users create and maintain an HVAC marketing context document. This captures foundational brand positioning, audience segments, and industry context that all other HVAC marketing skills reference.
|
||||||
|
|
||||||
|
The document is stored at `.agents/hvac-marketing-context.md`.
|
||||||
|
|
||||||
|
## Workflow
|
||||||
|
|
||||||
|
### Step 1: Check for Existing Context
|
||||||
|
|
||||||
|
First, check if `.agents/hvac-marketing-context.md` already exists. Also check `.claude/hvac-marketing-context.md` for older setups — if found there but not in `.agents/`, offer to move it.
|
||||||
|
|
||||||
|
**If it exists:**
|
||||||
|
- Read it and summarize what's captured
|
||||||
|
- Ask which sections they want to update
|
||||||
|
- Only gather info for those sections
|
||||||
|
|
||||||
|
**If it doesn't exist, offer two options:**
|
||||||
|
|
||||||
|
1. **Auto-draft from Compendium data** (recommended): Query the Compendium database for brand data, influencer profiles, and content patterns. Draft a V1 of the context document from existing intelligence.
|
||||||
|
|
||||||
|
2. **Start from scratch**: Walk through each section conversationally, gathering info one section at a time.
|
||||||
|
|
||||||
|
### Step 2: Gather Information
|
||||||
|
|
||||||
|
**If auto-drafting from Compendium:**
|
||||||
|
1. Query `mv_influencer_activity` for primary brand profiles
|
||||||
|
2. Query `mv_brand_content_tracker` for brand content patterns
|
||||||
|
3. Query `v_content_classified` for audience segment distribution
|
||||||
|
4. Query `intelligence.statistics` for key industry data points
|
||||||
|
5. Draft all sections based on what you find
|
||||||
|
6. Present the draft and ask what needs correcting or is missing
|
||||||
|
7. Iterate until the user is satisfied
|
||||||
|
|
||||||
|
**If Compendium is unavailable or starting from scratch:**
|
||||||
|
Walk through each section below conversationally, one at a time. Don't dump all questions at once.
|
||||||
|
|
||||||
|
For each section:
|
||||||
|
1. Briefly explain what you're capturing
|
||||||
|
2. Ask relevant questions
|
||||||
|
3. Confirm accuracy
|
||||||
|
4. Move to the next
|
||||||
|
|
||||||
|
Push for verbatim language — exact phrases techs and homeowners use are more valuable than polished descriptions.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sections to Capture
|
||||||
|
|
||||||
|
### 1. Brand Overview
|
||||||
|
|
||||||
|
- Brand name and tagline
|
||||||
|
- What the brand does (2-3 sentences)
|
||||||
|
- Brand type: content creator, manufacturer, contractor, distributor, tool/app, training
|
||||||
|
- Primary platforms (YouTube, Instagram, LinkedIn, podcast, website)
|
||||||
|
- Content format focus (video, articles, social, courses)
|
||||||
|
|
||||||
|
**Pre-populated brands** (if user is working with Compendium primary brands):
|
||||||
|
|
||||||
|
**HVAC Know It All** — Gary McCreadie
|
||||||
|
- Canadian HVAC technician and content creator
|
||||||
|
- YouTube, Instagram, Facebook focused
|
||||||
|
- Educational content: diagnostics, repairs, equipment reviews
|
||||||
|
- Tone: hands-on, practical, no-BS, occasional humor
|
||||||
|
- Audience: apprentice to journeyman technicians
|
||||||
|
|
||||||
|
**measureQuick** — Jim Bergmann
|
||||||
|
- HVAC measurement and diagnostics app
|
||||||
|
- YouTube, LinkedIn, website focused
|
||||||
|
- Technical content: system performance, measurement accuracy, data-driven HVAC
|
||||||
|
- Tone: data-driven, precise, engineering-minded
|
||||||
|
- Audience: journeyman to master technicians, contractors
|
||||||
|
|
||||||
|
### 2. Target Audience Segments
|
||||||
|
|
||||||
|
HVAC content has distinct audience tiers. Identify which segments the brand serves:
|
||||||
|
|
||||||
|
| Segment | Technical Level | Content Needs |
|
||||||
|
|---------|----------------|---------------|
|
||||||
|
| **Homeowner** | None-Low | Maintenance tips, buying guides, comfort advice, cost expectations |
|
||||||
|
| **Apprentice** | Learning | Fundamentals, tool usage, basic troubleshooting, career guidance |
|
||||||
|
| **Journeyman** | Working | Advanced diagnostics, equipment-specific guides, efficiency optimization |
|
||||||
|
| **Master Tech** | Expert | Complex systems, code compliance, business management, mentoring |
|
||||||
|
| **Business Owner** | Varies | Marketing, hiring, pricing, operations, growth strategy |
|
||||||
|
|
||||||
|
For each active segment, capture:
|
||||||
|
- Primary pain points
|
||||||
|
- Content preferences (video vs written, length, format)
|
||||||
|
- Where they consume content (platform habits)
|
||||||
|
- Language they use (trade slang vs formal)
|
||||||
|
|
||||||
|
### 3. HVAC Content Pillars
|
||||||
|
|
||||||
|
Which pillars does this brand focus on?
|
||||||
|
|
||||||
|
| Pillar | Description | Examples |
|
||||||
|
|--------|-------------|----------|
|
||||||
|
| **Efficiency** | Energy savings, SEER2/HSPF2 ratings, system performance | "How to Calculate Manual J Load" |
|
||||||
|
| **Regulations** | EPA rules, refrigerant handling, building codes, permits | "2025 Refrigerant Phase-Down Guide" |
|
||||||
|
| **Seasonal** | Maintenance schedules, seasonal campaigns, weather-driven content | "Spring AC Tune-Up Checklist" |
|
||||||
|
| **Troubleshooting** | Diagnostic guides, common failures, repair walkthroughs | "No Cool Call: Step-by-Step Diagnosis" |
|
||||||
|
| **Equipment** | Reviews, comparisons, installation guides, new product launches | "Carrier vs Trane: 2025 Comparison" |
|
||||||
|
| **IAQ** | Indoor air quality, filtration, humidity, ventilation | "When to Recommend a Whole-Home Dehumidifier" |
|
||||||
|
|
||||||
|
### 4. HVAC Industry Calendar
|
||||||
|
|
||||||
|
Map seasonal content opportunities:
|
||||||
|
|
||||||
|
| Season | Months | Campaign Focus |
|
||||||
|
|--------|--------|----------------|
|
||||||
|
| **Spring** | Mar-Apr | AC tune-up push, pre-season inspections, equipment upgrade promotions |
|
||||||
|
| **Summer** | May-Aug | Emergency repair awareness, efficiency tips, IAQ (allergens, humidity) |
|
||||||
|
| **Fall** | Sep-Oct | Heating prep, furnace inspections, winterization content |
|
||||||
|
| **Winter** | Nov-Feb | Emergency heating, carbon monoxide safety, IAQ (dry air, ventilation) |
|
||||||
|
| **Shoulder** | Apr-May, Sep-Oct | Equipment replacement promotions, financing offers, off-season deals |
|
||||||
|
|
||||||
|
### 5. Competitive Landscape
|
||||||
|
|
||||||
|
- **Direct competitors**: Same type of brand, same audience
|
||||||
|
- **Adjacent brands**: Different angle, overlapping audience (e.g., HVAC School vs HVAC Know It All)
|
||||||
|
- **Industry voices**: Influential techs, trainers, or companies whose content competes for attention
|
||||||
|
- What each does well and where they fall short
|
||||||
|
|
||||||
|
### 6. Differentiation
|
||||||
|
|
||||||
|
- What makes this brand's content unique
|
||||||
|
- Credibility signals (years in trade, certifications, notable projects)
|
||||||
|
- Content quality differentiators (production value, depth, humor, accessibility)
|
||||||
|
- Why the audience follows this brand over alternatives
|
||||||
|
|
||||||
|
### 7. Brand Voice
|
||||||
|
|
||||||
|
- Tone: technical-casual, authoritative, approachable, humorous, data-driven
|
||||||
|
- Communication style: direct, conversational, educational
|
||||||
|
- Brand personality (3-5 adjectives)
|
||||||
|
- Language to use: trade terminology level, acceptable slang
|
||||||
|
- Language to avoid: corporate speak, overly formal, condescending
|
||||||
|
|
||||||
|
For detailed brand voice development, use the `hvac-brand-voice` skill after creating this context document.
|
||||||
|
|
||||||
|
### 8. Proof Points
|
||||||
|
|
||||||
|
- Key metrics (subscribers, views, app downloads, installs completed)
|
||||||
|
- Notable partnerships or endorsements
|
||||||
|
- Community engagement (comments, shares, user-generated content)
|
||||||
|
- Industry recognition (awards, speaking engagements, certifications)
|
||||||
|
|
||||||
|
### 9. Goals
|
||||||
|
|
||||||
|
- Primary business goal (grow audience, drive app adoption, generate leads, sell training)
|
||||||
|
- Key conversion actions (subscribe, download app, book service, enroll in course)
|
||||||
|
- Current metrics (if known)
|
||||||
|
- Content frequency targets
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 3: Create the Document
|
||||||
|
|
||||||
|
After gathering information, create `.agents/hvac-marketing-context.md` with this structure:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# HVAC Marketing Context
|
||||||
|
|
||||||
|
*Last updated: [date]*
|
||||||
|
|
||||||
|
## Brand Overview
|
||||||
|
**Brand name:**
|
||||||
|
**Tagline:**
|
||||||
|
**What it does:**
|
||||||
|
**Brand type:**
|
||||||
|
**Primary platforms:**
|
||||||
|
**Content focus:**
|
||||||
|
|
||||||
|
## Target Audience
|
||||||
|
| Segment | Active | Primary Pain Points | Content Preferences |
|
||||||
|
|---------|--------|--------------------|--------------------|
|
||||||
|
| Homeowner | | | |
|
||||||
|
| Apprentice | | | |
|
||||||
|
| Journeyman | | | |
|
||||||
|
| Master Tech | | | |
|
||||||
|
| Business Owner | | | |
|
||||||
|
|
||||||
|
## Content Pillars
|
||||||
|
- [ ] Efficiency
|
||||||
|
- [ ] Regulations
|
||||||
|
- [ ] Seasonal
|
||||||
|
- [ ] Troubleshooting
|
||||||
|
- [ ] Equipment
|
||||||
|
- [ ] IAQ
|
||||||
|
|
||||||
|
**Primary pillars:**
|
||||||
|
**Secondary pillars:**
|
||||||
|
|
||||||
|
## Seasonal Calendar
|
||||||
|
| Season | Months | Key Campaigns |
|
||||||
|
|--------|--------|---------------|
|
||||||
|
| Spring | Mar-Apr | |
|
||||||
|
| Summer | May-Aug | |
|
||||||
|
| Fall | Sep-Oct | |
|
||||||
|
| Winter | Nov-Feb | |
|
||||||
|
|
||||||
|
## Competitive Landscape
|
||||||
|
**Direct:** [Brand] — strengths/weaknesses
|
||||||
|
**Adjacent:** [Brand] — overlap areas
|
||||||
|
**Industry voices:** [Names]
|
||||||
|
|
||||||
|
## Differentiation
|
||||||
|
**Unique angle:**
|
||||||
|
**Credibility:**
|
||||||
|
**Content quality:**
|
||||||
|
**Why they follow us:**
|
||||||
|
|
||||||
|
## Brand Voice
|
||||||
|
**Tone:**
|
||||||
|
**Style:**
|
||||||
|
**Personality:**
|
||||||
|
**Use:** [terms/phrases]
|
||||||
|
**Avoid:** [terms/phrases]
|
||||||
|
|
||||||
|
## Proof Points
|
||||||
|
**Metrics:**
|
||||||
|
**Partnerships:**
|
||||||
|
**Community:**
|
||||||
|
**Recognition:**
|
||||||
|
|
||||||
|
## Goals
|
||||||
|
**Business goal:**
|
||||||
|
**Conversion actions:**
|
||||||
|
**Current metrics:**
|
||||||
|
**Content frequency:**
|
||||||
|
|
||||||
|
## Compendium Access
|
||||||
|
**Database**: See COMPENDIUM_INTEGRATION.md for query templates
|
||||||
|
**Key views**: mv_influencer_activity, mv_brand_content_tracker, v_content_classified
|
||||||
|
**Statistics**: intelligence.statistics (1,400+ industry data points)
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Step 4: Confirm and Save
|
||||||
|
|
||||||
|
- Show the completed document
|
||||||
|
- Ask if anything needs adjustment
|
||||||
|
- Save to `.agents/hvac-marketing-context.md`
|
||||||
|
- Tell them: "Other HVAC marketing skills will now use this context automatically. Run `/hvac-marketing-context` anytime to update it."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for full details.
|
||||||
|
|
||||||
|
**Applicable tiers**: DB Query, Analyze
|
||||||
|
|
||||||
|
**Key queries**:
|
||||||
|
- `influencer-activity` — pull brand profiles and engagement data
|
||||||
|
- `brand-content` — track brand content output
|
||||||
|
- `classified-content` — understand audience segment distribution
|
||||||
|
|
||||||
|
When Compendium is unavailable, the skill works standalone — just requires more manual input from the user.
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-brand-voice**: Deep dive into voice, tone, and personality development
|
||||||
|
- **content-strategy**: Plan content using the context established here
|
||||||
|
- **hvac-content-from-data**: Create content directly from Compendium data
|
||||||
|
- **social-content**: Social media content using brand voice and audience context
|
||||||
|
|
||||||
|
## Tips
|
||||||
|
|
||||||
|
- **HVAC-specific**: Ask about certifications, years in trade, specialty areas (residential vs commercial, specific brands)
|
||||||
|
- **Capture field language**: "The unit's short-cycling" beats "the system is experiencing intermittent cycling"
|
||||||
|
- **Ask about seasonal patterns**: Every HVAC brand's content rhythm follows the seasons
|
||||||
|
- **Validate as you go**: Summarize each section and confirm before moving on
|
||||||
|
- **Skip what doesn't apply**: Not every brand covers all pillars or audience segments
|
||||||
|
|
@ -1,25 +1,25 @@
|
||||||
{
|
{
|
||||||
"skill_name": "product-marketing-context",
|
"skill_name": "hvac-marketing-context",
|
||||||
"evals": [
|
"evals": [
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "I want to set up my product marketing context. We're a B2B SaaS company that sells a customer feedback platform to product teams.",
|
"prompt": "I want to set up my product marketing context. We're a B2B SaaS company that sells a customer feedback platform to product teams.",
|
||||||
"expected_output": "Should check if .agents/product-marketing-context.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Product Overview, Target Audience, Personas, Problems You Solve, Competitive Landscape, Differentiation, Objections, Switching Dynamics, Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/product-marketing-context.md when complete.",
|
"expected_output": "Should check if .agents/hvac-marketing-context.md already exists. If not, should offer two options: (1) Auto-draft from codebase (recommended) or (2) Start from scratch. If user chooses start from scratch, should walk through sections conversationally one at a time. Should cover all applicable sections: Product Overview, Target Audience, Personas, Problems You Solve, Competitive Landscape, Differentiation, Objections, Switching Dynamics, Customer Language, Brand Voice, Proof Points, and Goals. Should create the file at .agents/hvac-marketing-context.md when complete.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for existing product-marketing-context.md",
|
"Checks for existing hvac-marketing-context.md",
|
||||||
"Offers two options: auto-draft or start from scratch",
|
"Offers two options: auto-draft or start from scratch",
|
||||||
"Covers applicable sections",
|
"Covers applicable sections",
|
||||||
"Walks through sections conversationally one at a time",
|
"Walks through sections conversationally one at a time",
|
||||||
"Creates file at .agents/product-marketing-context.md"
|
"Creates file at .agents/hvac-marketing-context.md"
|
||||||
],
|
],
|
||||||
"files": []
|
"files": []
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"id": 2,
|
"id": 2,
|
||||||
"prompt": "Update our product marketing context. We just added a new enterprise tier and our target audience has expanded to include VP of Engineering, not just Product Managers.",
|
"prompt": "Update our product marketing context. We just added a new enterprise tier and our target audience has expanded to include VP of Engineering, not just Product Managers.",
|
||||||
"expected_output": "Should check for existing .agents/product-marketing-context.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Product Overview (new enterprise tier, including pricing updates within that section), Objections (enterprise-specific), and Competitive Landscape (enterprise competitors). Should update only the relevant sections, preserving existing content that hasn't changed.",
|
"expected_output": "Should check for existing .agents/hvac-marketing-context.md and read it. Should identify which sections need updating based on the changes: Target Audience (add VP of Engineering), Personas (add new persona), Product Overview (new enterprise tier, including pricing updates within that section), Objections (enterprise-specific), and Competitive Landscape (enterprise competitors). Should update only the relevant sections, preserving existing content that hasn't changed.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Reads existing product-marketing-context.md",
|
"Reads existing hvac-marketing-context.md",
|
||||||
"Identifies sections that need updating",
|
"Identifies sections that need updating",
|
||||||
"Updates Target Audience with VP of Engineering",
|
"Updates Target Audience with VP of Engineering",
|
||||||
"Adds new persona for the expanded audience",
|
"Adds new persona for the expanded audience",
|
||||||
|
|
@ -39,14 +39,14 @@
|
||||||
"Adapts questions for early-stage B2C mobile app",
|
"Adapts questions for early-stage B2C mobile app",
|
||||||
"Notes some sections may be sparse early on",
|
"Notes some sections may be sparse early on",
|
||||||
"Skips non-applicable sections rather than forcing all 12",
|
"Skips non-applicable sections rather than forcing all 12",
|
||||||
"Creates file at .agents/product-marketing-context.md"
|
"Creates file at .agents/hvac-marketing-context.md"
|
||||||
],
|
],
|
||||||
"files": []
|
"files": []
|
||||||
},
|
},
|
||||||
{
|
{
|
||||||
"id": 4,
|
"id": 4,
|
||||||
"prompt": "Can you auto-draft our product marketing context from our existing codebase and marketing materials?",
|
"prompt": "Can you auto-draft our product marketing context from our existing codebase and marketing materials?",
|
||||||
"expected_output": "Should activate the auto-draft workflow mode. Should scan the codebase for existing marketing context: README, landing page copy, pricing page, about page, meta descriptions, any existing documentation. Should draft the product-marketing-context.md from what it finds, filling in sections where information is available and flagging sections that need manual input. Should present the draft for review before saving.",
|
"expected_output": "Should activate the auto-draft workflow mode. Should scan the codebase for existing marketing context: README, landing page copy, pricing page, about page, meta descriptions, any existing documentation. Should draft the hvac-marketing-context.md from what it finds, filling in sections where information is available and flagging sections that need manual input. Should present the draft for review before saving.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Activates auto-draft workflow mode",
|
"Activates auto-draft workflow mode",
|
||||||
"Scans codebase for existing marketing materials",
|
"Scans codebase for existing marketing materials",
|
||||||
|
|
@ -59,7 +59,7 @@
|
||||||
{
|
{
|
||||||
"id": 5,
|
"id": 5,
|
||||||
"prompt": "Do we have a product marketing context set up? I want to make sure the other marketing skills have context about our product.",
|
"prompt": "Do we have a product marketing context set up? I want to make sure the other marketing skills have context about our product.",
|
||||||
"expected_output": "Should check for .agents/product-marketing-context.md (and the older .claude/product-marketing-context.md location). Should report whether it exists and summarize its contents if found. If it doesn't exist, should offer to create one and explain why it's valuable (other skills like copywriting, page-cro, seo-audit check for it first). Should explain how other skills use this context document.",
|
"expected_output": "Should check for .agents/hvac-marketing-context.md (and the older .claude/hvac-marketing-context.md location). Should report whether it exists and summarize its contents if found. If it doesn't exist, should offer to create one and explain why it's valuable (other skills like copywriting, page-cro, seo-audit check for it first). Should explain how other skills use this context document.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks both file locations",
|
"Checks both file locations",
|
||||||
"Reports whether context doc exists",
|
"Reports whether context doc exists",
|
||||||
|
|
@ -72,10 +72,10 @@
|
||||||
{
|
{
|
||||||
"id": 6,
|
"id": 6,
|
||||||
"prompt": "Write homepage copy for our SaaS product.",
|
"prompt": "Write homepage copy for our SaaS product.",
|
||||||
"expected_output": "Should recognize this is a copywriting task, not a product marketing context task. Should check for product-marketing-context.md (as other skills do), and if it doesn't exist, may suggest creating one first. But should defer to the copywriting skill for actually writing the homepage copy.",
|
"expected_output": "Should recognize this is a copywriting task, not a product marketing context task. Should check for hvac-marketing-context.md (as other skills do), and if it doesn't exist, may suggest creating one first. But should defer to the copywriting skill for actually writing the homepage copy.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Recognizes this as a copywriting task",
|
"Recognizes this as a copywriting task",
|
||||||
"May check for or suggest creating product-marketing-context.md",
|
"May check for or suggest creating hvac-marketing-context.md",
|
||||||
"References or defers to copywriting skill for the actual copy",
|
"References or defers to copywriting skill for the actual copy",
|
||||||
"Does not attempt to write homepage copy using context creation patterns"
|
"Does not attempt to write homepage copy using context creation patterns"
|
||||||
],
|
],
|
||||||
452
skills/hvac-review-management/SKILL.md
Normal file
452
skills/hvac-review-management/SKILL.md
Normal file
|
|
@ -0,0 +1,452 @@
|
||||||
|
---
|
||||||
|
name: hvac-review-management
|
||||||
|
description: When the user wants to manage Google Business Profile reviews, improve review volume, respond to reviews, or create content from reviews. Use when they ask "review strategy," "how to get more reviews," "review response," "negative review," "fake review," "review monitoring," "review content," "competitor reviews," "GBP strategy," "local SEO," or "customer reputation." Reviews drive local SEO rankings and customer trust—this skill turns review management into a systematic marketing engine.
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools:
|
||||||
|
- db
|
||||||
|
- browse
|
||||||
|
- search
|
||||||
|
- analyze
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Review Management Strategy
|
||||||
|
|
||||||
|
You are a review management specialist who systematically solicits reviews, responds professionally, analyzes feedback, and transforms reviews into marketing content. Reviews are social proof, trust signals, and local SEO currency.
|
||||||
|
|
||||||
|
**Foundation:** Read `.agents/hvac-marketing-context.md` before starting. All review responses reflect brand voice and customer communication standards.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Review Strategy Stack
|
||||||
|
|
||||||
|
Reviews serve multiple purposes:
|
||||||
|
1. **Local SEO**: Google ranks higher for contractors with more reviews (quantity + recency + rating)
|
||||||
|
2. **Conversion**: Prospects read reviews before booking. 1-star review kills 25% of leads.
|
||||||
|
3. **Reputation**: Respond professionally to negative reviews—shows you care
|
||||||
|
4. **Content**: Extract quotes, stories, and social proof for marketing
|
||||||
|
5. **Product intelligence**: Customer feedback reveals pain points and opportunities
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: Review Generation System
|
||||||
|
|
||||||
|
### Build a Solicitation Workflow
|
||||||
|
|
||||||
|
Create a post-service review request process:
|
||||||
|
|
||||||
|
**Timing:** Ask within 24-48 hours of job completion (highest conversion rate)
|
||||||
|
|
||||||
|
**Channels:**
|
||||||
|
1. **Email** (highest quality): Send templated email with direct link to Google Business Profile review page
|
||||||
|
2. **SMS** (fastest): "Thanks for choosing us! Could you leave a quick Google review? [link]"
|
||||||
|
3. **QR code** (physical): Leave business card with QR code linking to review page
|
||||||
|
4. **Phone call** (highest effort, highest conversion for high-ticket jobs)
|
||||||
|
5. **In-person** (during checkout): "Would you mind sharing your experience with a Google review?"
|
||||||
|
|
||||||
|
**Email template:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Subject: "Thanks for choosing [Company]! One quick favor..."
|
||||||
|
|
||||||
|
Hi [Customer name],
|
||||||
|
|
||||||
|
We're so glad we could help with your [AC/heating/maintenance].
|
||||||
|
If you're happy with your experience, would you mind sharing a quick
|
||||||
|
Google review? It helps us serve more families in [City].
|
||||||
|
|
||||||
|
Leave a review (takes 2 minutes): [direct Google review link]
|
||||||
|
|
||||||
|
Thanks,
|
||||||
|
[Team name]
|
||||||
|
P.S. If you have any concerns, call us immediately at [phone].
|
||||||
|
We want to make it right.
|
||||||
|
```
|
||||||
|
|
||||||
|
**SMS template:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Hi [name]! Thanks for choosing [company]. We'd love your Google review—
|
||||||
|
takes 2 min. Reply REVIEW or click: [short link]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Calculate Review Request Volume
|
||||||
|
|
||||||
|
Target metrics per month:
|
||||||
|
- **Small company** (10 jobs/month): 5-8 review requests = 1-2 conversions
|
||||||
|
- **Medium company** (50 jobs/month): 30-40 review requests = 8-12 conversions
|
||||||
|
- **Large company** (100+ jobs/month): 75-100 review requests = 20-30 conversions
|
||||||
|
|
||||||
|
Conversion rate: 15-25% of requests → completed reviews
|
||||||
|
|
||||||
|
**Goal**: 1-2 new reviews per week minimum (4-8 per month)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: Response Protocol
|
||||||
|
|
||||||
|
### Positive Reviews (5 star)
|
||||||
|
|
||||||
|
**Goal**: Acknowledge, reinforce why they chose you, ask for referral
|
||||||
|
|
||||||
|
**Template (50-75 words):**
|
||||||
|
|
||||||
|
```
|
||||||
|
Thank you [name]! We appreciate your kind words about [specific service].
|
||||||
|
Our team takes pride in [quality attribute—reliability, attention to detail, etc.].
|
||||||
|
If you know anyone in [neighborhood/area] who needs HVAC help,
|
||||||
|
we'd be grateful for a referral. Thanks for choosing [company]!
|
||||||
|
|
||||||
|
—[Technician/Manager name]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pro tips:**
|
||||||
|
- Personalize: Mention specific service (AC tune-up, emergency repair)
|
||||||
|
- Add specific detail: Technician name, what they praised
|
||||||
|
- Create action: Ask for referral, mention loyalty program
|
||||||
|
- Sign with name: Shows real person responding
|
||||||
|
|
||||||
|
### Negative Reviews (1-4 stars)
|
||||||
|
|
||||||
|
**Goal**: Acknowledge concern, apologize, offer to resolve offline, show you care
|
||||||
|
|
||||||
|
**Template (75-100 words):**
|
||||||
|
|
||||||
|
```
|
||||||
|
Hi [name], thanks for taking the time to share this feedback.
|
||||||
|
I'm sorry we didn't meet your expectations with [specific issue].
|
||||||
|
This doesn't represent our standards, and I want to make it right.
|
||||||
|
|
||||||
|
I'm [role] here at [company]. Could you call me directly at [phone]
|
||||||
|
or email me at [email]? I'd like to understand what happened
|
||||||
|
and see how we can resolve this.
|
||||||
|
|
||||||
|
—[Manager name]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Pro tips:**
|
||||||
|
- DON'T: Defend, argue, or make excuses
|
||||||
|
- DO: Apologize, take responsibility, offer solution
|
||||||
|
- DO: Move conversation offline (call/email, not public)
|
||||||
|
- DO: Offer concrete fix (refund, redo work, discount next service)
|
||||||
|
- DO: Follow up in 48 hours with update
|
||||||
|
|
||||||
|
**Example response to common complaints:**
|
||||||
|
|
||||||
|
**"Technician was rude"**
|
||||||
|
```
|
||||||
|
I sincerely apologize that [technician] didn't treat you with respect.
|
||||||
|
That's unacceptable and doesn't reflect who we are. I'm removing him
|
||||||
|
from customer-facing roles and retraining him personally.
|
||||||
|
|
||||||
|
Can I offer you [50% discount on next service/full refund] to earn
|
||||||
|
your trust back? Call me directly: [phone].
|
||||||
|
```
|
||||||
|
|
||||||
|
**"Charge was higher than quote"**
|
||||||
|
```
|
||||||
|
I understand the frustration when a final bill exceeds estimate.
|
||||||
|
Let's review what happened—some repairs take longer than expected,
|
||||||
|
and we should have communicated that real-time.
|
||||||
|
|
||||||
|
I'm reviewing your invoice now. Call me to discuss: [phone].
|
||||||
|
I may be able to adjust charges or explain the difference.
|
||||||
|
```
|
||||||
|
|
||||||
|
**"Took too long to respond"**
|
||||||
|
```
|
||||||
|
I'm sorry you felt ignored. We try to respond to all requests
|
||||||
|
within 2 hours, and we dropped the ball. I've reviewed our
|
||||||
|
dispatch system and made changes to prevent this.
|
||||||
|
|
||||||
|
Can I earn back your confidence with [faster callback guarantee/discount]?
|
||||||
|
```
|
||||||
|
|
||||||
|
### Ambiguous Reviews (3 stars)
|
||||||
|
|
||||||
|
**Goal**: Ask clarifying question, offer to improve, move to positive if possible
|
||||||
|
|
||||||
|
**Template (50-75 words):**
|
||||||
|
|
||||||
|
```
|
||||||
|
Hi [name], thanks for the review. I notice you gave 3 stars—
|
||||||
|
I want to make sure we delivered fully. What could we have done better?
|
||||||
|
|
||||||
|
If there's something we can improve, I'd like to fix it.
|
||||||
|
Call me at [phone] or reply here.
|
||||||
|
|
||||||
|
—[Manager name]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3: Competitive Review Monitoring
|
||||||
|
|
||||||
|
### Weekly Review Audit
|
||||||
|
|
||||||
|
**Your reviews + competitor reviews:**
|
||||||
|
|
||||||
|
1. **Check your Google Business Profile**: Any new reviews? New rating?
|
||||||
|
2. **Check top 3 competitors**: How many reviews? Average rating? Latest feedback themes?
|
||||||
|
3. **Identify gaps**: What complaints do they get that you avoid? Vice versa?
|
||||||
|
|
||||||
|
**Use Compendium if available:**
|
||||||
|
```sql
|
||||||
|
SELECT
|
||||||
|
company_name,
|
||||||
|
gbp_rating,
|
||||||
|
review_count,
|
||||||
|
review_themes (top 5),
|
||||||
|
avg_response_time
|
||||||
|
FROM gbp.competitor_data
|
||||||
|
WHERE region = 'your_region'
|
||||||
|
ORDER BY gbp_rating DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
### Fake Review Detection
|
||||||
|
|
||||||
|
Red flags for fake reviews (yours or competitors'):
|
||||||
|
|
||||||
|
**Obvious fakes:**
|
||||||
|
- 5 stars with vague praise ("Great company!" with no detail)
|
||||||
|
- Multiple new 1-star reviews in one week from anonymous accounts
|
||||||
|
- Reviews from people with no history (no profile photo, no other reviews)
|
||||||
|
- Grammatically incorrect (suggests translator/outsourced writing)
|
||||||
|
- Generic praise unrelated to your services
|
||||||
|
|
||||||
|
**If you suspect competitor fraud:**
|
||||||
|
- Flag to Google: "This review may be fake" → Google investigates
|
||||||
|
- Document pattern (date, text) for Google support
|
||||||
|
- DON'T: Create fake positive reviews to counter (violates Google policy, hurts you more)
|
||||||
|
|
||||||
|
**To prevent fake reviews of YOUR company:**
|
||||||
|
- Monitor new reviews daily
|
||||||
|
- Flag suspicious ones immediately
|
||||||
|
- Ask satisfied customers directly (real reviews dominate over time)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4: Review-Driven Content
|
||||||
|
|
||||||
|
### Turn Reviews into Social Posts
|
||||||
|
|
||||||
|
**Template 1: Testimonial Post**
|
||||||
|
```
|
||||||
|
LinkedIn post:
|
||||||
|
"[Customer name] just shared this about us:
|
||||||
|
'[Quote from 5-star review]'
|
||||||
|
|
||||||
|
We take pride in [specific attribute]. If you need [service type]
|
||||||
|
in [area], we're here to help. [CTA: Call/Book]"
|
||||||
|
|
||||||
|
Attachment: Screenshot of review + rating
|
||||||
|
```
|
||||||
|
|
||||||
|
**Template 2: Before/After Story**
|
||||||
|
```
|
||||||
|
"When [customer name] called, their [AC/heating] was [problem].
|
||||||
|
Here's what they said after we fixed it:
|
||||||
|
|
||||||
|
'[Quote from review]'
|
||||||
|
|
||||||
|
This is why we do this work. [CTA: Schedule your service]"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Template 3: Address Objection**
|
||||||
|
```
|
||||||
|
LinkedIn:
|
||||||
|
"One concern prospects ask: 'Will the repair cost more than expected?'
|
||||||
|
|
||||||
|
Here's what [customer name] said:
|
||||||
|
'[Quote about honest pricing/communication]'
|
||||||
|
|
||||||
|
We believe in [pricing philosophy]. Read our reviews: [link to GBP]"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Create Review Highlight Page
|
||||||
|
|
||||||
|
On your website, create `/reviews` page featuring:
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
- **Star rating + count** (live feed from GBP if possible)
|
||||||
|
- **Highlighted testimonials** (5-7 best reviews with photos)
|
||||||
|
- **By service type** (AC reviews, heating reviews, emergency repairs)
|
||||||
|
- **Video testimonials** (if you have them)
|
||||||
|
- **Trust badges** (Google ratings, industry certifications)
|
||||||
|
- **CTA**: "See more reviews on Google" + "Schedule your service"
|
||||||
|
|
||||||
|
**Content:**
|
||||||
|
```
|
||||||
|
---
|
||||||
|
# Customer Reviews & Testimonials
|
||||||
|
|
||||||
|
4.9 stars (247 reviews) on Google
|
||||||
|
|
||||||
|
## AC Installation & Maintenance
|
||||||
|
[3-4 best AC-related testimonials with customer photos]
|
||||||
|
|
||||||
|
## Heating Repair & Installation
|
||||||
|
[3-4 best heating-related testimonials]
|
||||||
|
|
||||||
|
## Emergency Service
|
||||||
|
[3-4 best emergency/quick-response testimonials]
|
||||||
|
|
||||||
|
[Video testimonial 1]
|
||||||
|
[Video testimonial 2]
|
||||||
|
|
||||||
|
...
|
||||||
|
|
||||||
|
[CTA: See all reviews on Google] | [CTA: Schedule service]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Email Campaign: Leverage Reviews
|
||||||
|
|
||||||
|
**Segment 1: Prospects (haven't bought)**
|
||||||
|
|
||||||
|
Subject: "Why 247 families choose [Company] for HVAC"
|
||||||
|
|
||||||
|
```
|
||||||
|
Hi [prospect],
|
||||||
|
|
||||||
|
If you're researching HVAC contractors in [area], you're probably
|
||||||
|
comparing reviews. Here's what our customers say:
|
||||||
|
|
||||||
|
[3-4 best testimonials]
|
||||||
|
|
||||||
|
[Star rating visual] 4.9 stars on Google (247 reviews)
|
||||||
|
|
||||||
|
Ready to join them? Schedule a free inspection:
|
||||||
|
[CTA: Book now]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Segment 2: Past customers (bought 1+ year ago)**
|
||||||
|
|
||||||
|
Subject: "Thanks for your review of [Company]—here's a special offer"
|
||||||
|
|
||||||
|
```
|
||||||
|
Hi [customer],
|
||||||
|
|
||||||
|
We saw your recent review: "[quote]"
|
||||||
|
|
||||||
|
Your feedback means everything and helps other families find us.
|
||||||
|
As a thank you, here's 20% off your next service:
|
||||||
|
|
||||||
|
[Coupon code]
|
||||||
|
|
||||||
|
Valid until [date]. Questions? Call us anytime: [phone]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 5: Competitive Analysis & Response
|
||||||
|
|
||||||
|
### Monthly Review Competitive Report
|
||||||
|
|
||||||
|
Run this analysis quarterly:
|
||||||
|
|
||||||
|
```
|
||||||
|
Your company vs. competitors
|
||||||
|
├─ Review count: You [X] vs. Competitor A [Y] vs. Competitor B [Z]
|
||||||
|
├─ Average rating: You [4.9] vs. Competitor A [4.3] vs. Competitor B [4.6]
|
||||||
|
├─ Review velocity: You [8/month] vs. Competitor A [3/month] vs. Competitor B [5/month]
|
||||||
|
├─ Top complaint themes:
|
||||||
|
│ └─ Yours: [slow response, pricing]
|
||||||
|
│ └─ Competitor A: [poor communication, expensive]
|
||||||
|
│ └─ Competitor B: [scheduling issues, upselling]
|
||||||
|
└─ Messaging opportunity: You differentiate on [response time, transparency]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Develop Response to Common Competitor Advantages
|
||||||
|
|
||||||
|
If Competitor A has more reviews:
|
||||||
|
- **Your action**: Systematize review requests (post-service emails, SMS)
|
||||||
|
- **Your messaging**: "Quality over quantity—[rating] from verified customers"
|
||||||
|
- **Your timeline**: 3-6 months to close review gap
|
||||||
|
|
||||||
|
If Competitor B has higher rating:
|
||||||
|
- **Your action**: Identify what drives their reviews (speed? courtesy?)
|
||||||
|
- **Your messaging**: Match their strength or differentiate elsewhere
|
||||||
|
- **Your timeline**: 1-2 months to match rating
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to:
|
||||||
|
- Monitor competitor GBP profiles (if available in database)
|
||||||
|
- Identify themes in customer reviews (AI classification)
|
||||||
|
- Track seasonal review trends (do reviews spike in summer?)
|
||||||
|
- Analyze response patterns (do you respond faster than competitors?)
|
||||||
|
|
||||||
|
**Example queries:**
|
||||||
|
```sql
|
||||||
|
-- Your review themes by month
|
||||||
|
SELECT review_month, theme, sentiment, count
|
||||||
|
FROM gbp.review_analysis
|
||||||
|
WHERE company_id = 'your_company_id'
|
||||||
|
GROUP BY review_month, theme
|
||||||
|
ORDER BY review_month DESC;
|
||||||
|
|
||||||
|
-- Competitor comparison
|
||||||
|
SELECT company, avg_rating, review_count, avg_response_days
|
||||||
|
FROM gbp.competitor_benchmarking
|
||||||
|
WHERE region = 'your_region'
|
||||||
|
ORDER BY avg_rating DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for database connection details.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-marketing-context** — Foundation document. Run first.
|
||||||
|
- **social-content** — Turn reviews into LinkedIn/Instagram posts
|
||||||
|
- **email-sequence** — Review-based email campaigns
|
||||||
|
- **copy-editing** — Polish review responses and testimonial copy
|
||||||
|
- **hvac-content-from-data** — Use review data as content source
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Review Management Checklist
|
||||||
|
|
||||||
|
### Weekly (30 minutes)
|
||||||
|
- [ ] Check for new reviews on GBP
|
||||||
|
- [ ] Respond to all new reviews (positive + negative)
|
||||||
|
- [ ] Check competitor new reviews (spot trends)
|
||||||
|
- [ ] Assign new reviews to response queue if needed
|
||||||
|
|
||||||
|
### Monthly (2 hours)
|
||||||
|
- [ ] Review response metrics (avg response time, response rate)
|
||||||
|
- [ ] Identify top review themes (what do customers love? complain about?)
|
||||||
|
- [ ] Create 1-2 social posts from best reviews
|
||||||
|
- [ ] Brief team on feedback themes (speed, communication, quality)
|
||||||
|
|
||||||
|
### Quarterly (4 hours)
|
||||||
|
- [ ] Competitive review analysis
|
||||||
|
- [ ] Identify messaging gaps (how do you differentiate?)
|
||||||
|
- [ ] Update website testimonials page with new reviews
|
||||||
|
- [ ] Analyze: What drives positive reviews? Fix what drives negative ones.
|
||||||
|
|
||||||
|
### Annual (8 hours)
|
||||||
|
- [ ] Review strategy audit: Is your system working?
|
||||||
|
- [ ] Set review targets for next year
|
||||||
|
- [ ] Evaluate: Which service type gets best reviews? Most complaints?
|
||||||
|
- [ ] Plan improvements based on patterns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips for Success
|
||||||
|
|
||||||
|
1. **Speed matters**: Respond to reviews within 24 hours. Shows you care.
|
||||||
|
2. **Personalize**: Use customer name, mention specific service, show you read the review.
|
||||||
|
3. **Never argue**: Even if a review is unfair, apologize and move offline.
|
||||||
|
4. **Ask questions**: If a review is vague, ask what you could improve.
|
||||||
|
5. **Follow up**: If you resolved a negative review offline, ask customer to update their review.
|
||||||
|
6. **Incentivize reviews**: Post-service follow-up email should include direct review link.
|
||||||
|
7. **Make it easy**: QR code on business card, SMS link, email link—multiple options.
|
||||||
|
8. **Hire responsibly**: Your team's behavior directly impacts reviews. Train on customer service.
|
||||||
|
9. **Monitor fake competitors**: Some contractors post fake negative reviews on competitors. Flag them.
|
||||||
|
10. **Celebrate positive reviews**: Share them internally, on social, in email. Build culture of excellence.
|
||||||
337
skills/hvac-seasonal-campaign/SKILL.md
Normal file
337
skills/hvac-seasonal-campaign/SKILL.md
Normal file
|
|
@ -0,0 +1,337 @@
|
||||||
|
---
|
||||||
|
name: hvac-seasonal-campaign
|
||||||
|
description: When the user wants to plan seasonal HVAC marketing campaigns tied to demand cycles. Use when they ask "seasonal campaign," "spring AC push," "summer emergency," "fall heating prep," "winter demand," "seasonal content," "seasonal promotions," "when should I market," "seasonal email campaign," "quarterly campaign planning," or "seasonal blog schedule." HVAC demand varies drastically by season—this skill aligns your marketing (content, emails, ads, promotions) with when customers actually search and buy.
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools:
|
||||||
|
- db
|
||||||
|
- search
|
||||||
|
- analyze
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Seasonal Campaign Strategy
|
||||||
|
|
||||||
|
You are an HVAC marketing tactician who aligns campaigns with seasonal demand cycles. Spring AC maintenance, summer emergency response, fall heating installation, winter IAQ—each season requires different messaging, offers, and content.
|
||||||
|
|
||||||
|
**Foundation:** Read `.agents/hvac-marketing-context.md` before starting. All campaigns reflect brand voice, audience, and positioning.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The HVAC Seasonal Demand Cycle
|
||||||
|
|
||||||
|
### Spring (March - April): AC Tune-Up & Seasonal Prep
|
||||||
|
**Demand driver**: Homeowners preparing for hot season, AC units haven't run all winter
|
||||||
|
|
||||||
|
**Customer mindset:**
|
||||||
|
- "Is my AC ready for summer?"
|
||||||
|
- "How do I save on cooling costs?"
|
||||||
|
- "What maintenance should I do now?"
|
||||||
|
|
||||||
|
**Content themes**: Preventive maintenance, energy efficiency, spring inspections, tune-up value, DIY inspection tips
|
||||||
|
|
||||||
|
**Offer angle**: Pre-season tune-up discounts, efficiency audits, maintenance packages
|
||||||
|
|
||||||
|
**Campaign intensity**: Medium (higher toward April)
|
||||||
|
|
||||||
|
### Summer (June - August): Emergency Repairs & High-Ticket Service
|
||||||
|
**Demand driver**: Peak cooling demand, breakdowns during extreme heat, emergency calls spike
|
||||||
|
|
||||||
|
**Customer mindset:**
|
||||||
|
- "My AC is broken and it's 95 degrees!"
|
||||||
|
- "Why is my bill so high?"
|
||||||
|
- "Can I trust this contractor?"
|
||||||
|
- "How do I stay cool without breaking the bank?"
|
||||||
|
|
||||||
|
**Content themes**: Troubleshooting guides, emergency response, warranty claims, cost-saving hacks, common repair types, air quality
|
||||||
|
|
||||||
|
**Offer angle**: Emergency response guarantees, extended warranties, summer maintenance plans, financing for repairs
|
||||||
|
|
||||||
|
**Campaign intensity**: HIGH (June-August peak, especially July-August)
|
||||||
|
|
||||||
|
### Fall (September - October): Heating Installation & Prep
|
||||||
|
**Demand driver**: Homeowners preparing heating systems before winter, boiler/furnace replacements before crunch
|
||||||
|
|
||||||
|
**Customer mindset:**
|
||||||
|
- "Is my heating ready?"
|
||||||
|
- "Should I replace my old furnace?"
|
||||||
|
- "What's a good heating system?"
|
||||||
|
- "How much will it cost?"
|
||||||
|
|
||||||
|
**Content themes**: Furnace/boiler guides, system replacements, heating efficiency, cost comparisons, installation prep, rebates/tax credits
|
||||||
|
|
||||||
|
**Offer angle**: Installation discounts, rebate packages, winter maintenance plans, financing for equipment, inspection bundling
|
||||||
|
|
||||||
|
**Campaign intensity**: Medium-HIGH (ramps up September, peaks October before winter)
|
||||||
|
|
||||||
|
### Winter (November - February): Emergency Service & Indoor Air Quality
|
||||||
|
**Demand driver**: Extreme cold events, system breakdowns under stress, IAQ concerns (dry air, humidity control)
|
||||||
|
|
||||||
|
**Customer mindset:**
|
||||||
|
- "My heat just went out!"
|
||||||
|
- "Why is my air so dry/stuffy?"
|
||||||
|
- "Is my system working efficiently?"
|
||||||
|
- "How do I save on heating?"
|
||||||
|
|
||||||
|
**Content themes**: Emergency response, system failures, indoor air quality, humidity control, energy savings, carbon monoxide safety
|
||||||
|
|
||||||
|
**Offer angle**: 24/7 emergency response, emergency repair guarantees, IAQ assessments, rebates for upgrades, winter savings packages
|
||||||
|
|
||||||
|
**Campaign intensity**: HIGH (peak during cold snaps Dec-Feb)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seasonal Campaign Template
|
||||||
|
|
||||||
|
### Phase 1: Awareness (8-12 weeks before season peak)
|
||||||
|
|
||||||
|
**Goal**: Build interest and education before demand peaks. Capture early searchers.
|
||||||
|
|
||||||
|
**Content strategy:**
|
||||||
|
- How-to guides: "Spring AC Maintenance Checklist" (target: spring maintenance keywords)
|
||||||
|
- Educational blog series: System types, efficiency ratings, cost factors
|
||||||
|
- Topic clusters: Group 5-7 posts around theme (e.g., "AC Prep Week")
|
||||||
|
|
||||||
|
**Email campaign:**
|
||||||
|
- Nurture sequence: 4-5 emails over 6 weeks
|
||||||
|
- Email 1: Educational hook ("5 reasons your AC isn't ready")
|
||||||
|
- Email 2: Product education ("What's an SEER rating and why it matters")
|
||||||
|
- Email 3: Social proof ("How contractors score on [rating site]")
|
||||||
|
- Email 4: Offer reveal ("Book your inspection before March 31")
|
||||||
|
- Email 5: Urgency reminder ("Only 10 days left")
|
||||||
|
|
||||||
|
**Paid ads (if budget):**
|
||||||
|
- Keyword targeting: High-intent seasonal keywords
|
||||||
|
- Bid strategy: Moderate (awareness phase, build volume)
|
||||||
|
- Message: Education + value, light on hard sell
|
||||||
|
|
||||||
|
**Social content:**
|
||||||
|
- 3-4 posts/week on LinkedIn (contractor education, tips)
|
||||||
|
- 2-3 posts/week on Instagram (visual how-tos, testimonials)
|
||||||
|
- 1-2 posts/week on Facebook (community, local contractor stories)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 2: Conversion (4-8 weeks until peak)
|
||||||
|
|
||||||
|
**Goal**: Drive quotes, bookings, service calls. Shift from education to offer.
|
||||||
|
|
||||||
|
**Content strategy:**
|
||||||
|
- Comparison guides: "AC vs. furnace" or "DIY vs. professional"
|
||||||
|
- Case studies: Homeowner saves, comfort improves
|
||||||
|
- Objection content: "FAQ: What to expect from an inspection"
|
||||||
|
- Free tools/resources: Calculator, checklist, assessment PDF
|
||||||
|
|
||||||
|
**Email campaign:**
|
||||||
|
- Promotional sequence: 3-4 emails
|
||||||
|
- Email 1: Limited-time offer reveal
|
||||||
|
- Email 2: Social proof + urgency ("Only 5 spots left this week")
|
||||||
|
- Email 3: Objection handling ("Not sure if you need it?")
|
||||||
|
- Email 4: Final reminder ("Offer ends [date]")
|
||||||
|
|
||||||
|
**Paid ads (if budget):**
|
||||||
|
- Keyword targeting: More transactional (e.g., "AC installation near me")
|
||||||
|
- Bid strategy: Aggressive (conversion phase)
|
||||||
|
- Message: Offer details, urgency, trust signals
|
||||||
|
|
||||||
|
**Sales enablement:**
|
||||||
|
- Update homepage: Season-specific banner
|
||||||
|
- Create landing page: Dedicated to seasonal offer
|
||||||
|
- Brief sales team: Common objections, talking points
|
||||||
|
- Prepare scheduling: Extra appointment slots, faster callbacks
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 3: Retention (During peak season)
|
||||||
|
|
||||||
|
**Goal**: Upsells, referrals, retention during high-demand period.
|
||||||
|
|
||||||
|
**Content strategy:**
|
||||||
|
- Tip sheets: Seasonal energy-saving hacks
|
||||||
|
- Customer stories: Recent customer transformation
|
||||||
|
- Emergency content: "What to do if X breaks" (evergreen, high-intent)
|
||||||
|
- Thought leadership: Industry trends, contractor insights
|
||||||
|
|
||||||
|
**Email campaign:**
|
||||||
|
- Win-back sequence: Past customers ("We haven't heard from you...")
|
||||||
|
- Referral sequence: Recent customers ("Know someone who needs help?")
|
||||||
|
- Educational drips: 1 email per week, low sell
|
||||||
|
- VIP sequence: High-value past customers
|
||||||
|
|
||||||
|
**Customer communications:**
|
||||||
|
- Post-service follow-up email: "How did we do?"
|
||||||
|
- Seasonal check-in: "Is your [system] ready for winter?"
|
||||||
|
- Referral incentive: "Refer a friend, get [discount]"
|
||||||
|
- Loyalty offer: "Maintenance club members get [benefit]"
|
||||||
|
|
||||||
|
**Social content:**
|
||||||
|
- Customer testimonials: Video, photos, quotes
|
||||||
|
- Behind-the-scenes: Team at work, service day, equipment install
|
||||||
|
- Educational quick-tips: 15-30 second video tips
|
||||||
|
- Community engagement: Reply to comments, answer questions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Phase 4: Off-Season (Months with lower demand)
|
||||||
|
|
||||||
|
**Goal**: Maintain visibility, plan ahead, stay top-of-mind.
|
||||||
|
|
||||||
|
**Content strategy:**
|
||||||
|
- Long-form guides: 2000+ word definitive guides
|
||||||
|
- Video content: How-tos, webinars, customer interviews
|
||||||
|
- Topic clusters: Deep-dive into related niches
|
||||||
|
- Competitor analysis: Who's winning in off-season?
|
||||||
|
|
||||||
|
**Email campaign:**
|
||||||
|
- Lighter schedule: 1-2 emails per month
|
||||||
|
- Educational only: No hard sell
|
||||||
|
- Spotlight: Contractor expertise, new services
|
||||||
|
- Planning: "Prepare now for [next season]"
|
||||||
|
|
||||||
|
**Paid strategy:**
|
||||||
|
- Pause or reduce spend
|
||||||
|
- Focus on brand/awareness over conversion
|
||||||
|
- Test new messaging, creatives, audiences
|
||||||
|
- Retarget past visitors (lower cost)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seasonal Campaign Calendar Template
|
||||||
|
|
||||||
|
```
|
||||||
|
MARCH-APRIL: Spring AC Campaign
|
||||||
|
├─ Content: 8 blog posts (AC maintenance, efficiency, comparisons)
|
||||||
|
├─ Email: 5-email nurture sequence
|
||||||
|
├─ Ads: Seasonal keywords, $X/day budget
|
||||||
|
├─ Social: Daily tips, maintenance tips, before/after
|
||||||
|
└─ Offer: "Spring Tune-Up Special: $X off inspection"
|
||||||
|
|
||||||
|
JUNE-AUGUST: Summer Emergency Campaign
|
||||||
|
├─ Content: Troubleshooting guides, emergency response, cost-saving
|
||||||
|
├─ Email: Conversion + urgency sequence
|
||||||
|
├─ Ads: Emergency keywords, high bid, top-of-funnel
|
||||||
|
├─ Social: Daily testimonials, quick-fix tips, emergency hotline
|
||||||
|
└─ Offer: "Same-day service available, extended warranty options"
|
||||||
|
|
||||||
|
SEPTEMBER-OCTOBER: Fall Heating Campaign
|
||||||
|
├─ Content: Furnace buying guide, replacement cost, efficiency ratings
|
||||||
|
├─ Email: Education + comparison + offer
|
||||||
|
├─ Ads: Installation keywords, seasonal demand, financing offers
|
||||||
|
├─ Social: System comparisons, contractor interviews, energy tips
|
||||||
|
└─ Offer: "Fall Installation Special: $X off, financing available"
|
||||||
|
|
||||||
|
NOVEMBER-FEBRUARY: Winter IAQ/Emergency Campaign
|
||||||
|
├─ Content: IAQ guides, emergency prep, energy savings, safety
|
||||||
|
├─ Email: Maintenance reminders, emergency hotline, IAQ tips
|
||||||
|
├─ Ads: Emergency + IAQ keywords, high bids during cold snaps
|
||||||
|
├─ Social: Winter safety tips, customer stories, emergency response
|
||||||
|
└─ Offer: "24/7 emergency response guarantee, winter savings packages"
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## How to Use Database for Seasonal Planning
|
||||||
|
|
||||||
|
Query Compendium to validate seasonal messaging and timing:
|
||||||
|
|
||||||
|
**Step 1: Identify trending topics by season**
|
||||||
|
```sql
|
||||||
|
SELECT topic, seasonality, avg_search_volume
|
||||||
|
FROM mv_topic_trends_weekly
|
||||||
|
WHERE seasonality IN ('spring', 'summer', 'fall', 'winter')
|
||||||
|
ORDER BY seasonality, avg_search_volume DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 2: Find customer pain points by season**
|
||||||
|
```sql
|
||||||
|
SELECT issue_type, reported_frequency, peak_season
|
||||||
|
FROM intelligence.seasonal_issues
|
||||||
|
WHERE peak_season IS NOT NULL
|
||||||
|
ORDER BY peak_season, reported_frequency DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Step 3: Research competitor seasonal messaging**
|
||||||
|
- Query `mv_competitor_content_calendar` if available
|
||||||
|
- Or manually check 3-5 competitor websites monthly
|
||||||
|
- Note: What offers, messaging, and promotions do they run?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill uses Compendium data to:
|
||||||
|
- Validate seasonal timing with search volume data
|
||||||
|
- Identify trending topics per season
|
||||||
|
- Track competitor seasonal campaigns
|
||||||
|
- Analyze customer pain points by season
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for:
|
||||||
|
- Database connection details
|
||||||
|
- Rate limits
|
||||||
|
- Fallback strategies if DB is unavailable
|
||||||
|
|
||||||
|
**If Compendium unavailable:** Use search trends (Google Trends, industry reports) and past sales/lead data to time campaigns.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-marketing-context** — Foundation. Run this first.
|
||||||
|
- **content-strategy** — Long-term editorial planning
|
||||||
|
- **hvac-content-from-data** — Power seasonal content with data insights
|
||||||
|
- **social-content** — Platform-specific social scheduling
|
||||||
|
- **email-sequence** — Detailed email campaign mechanics
|
||||||
|
- **ad-creative** — Paid ad creative for seasonal campaigns
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Seasonal Campaign Checklist
|
||||||
|
|
||||||
|
### 8 Weeks Before Peak
|
||||||
|
- [ ] Plan content calendar (10-12 posts)
|
||||||
|
- [ ] Write top-performing posts (first 3)
|
||||||
|
- [ ] Draft email nurture sequence
|
||||||
|
- [ ] Identify seasonal offer/discount
|
||||||
|
- [ ] Plan paid ad strategy (if budget exists)
|
||||||
|
|
||||||
|
### 4 Weeks Before Peak
|
||||||
|
- [ ] Publish blog posts (1-2 per week)
|
||||||
|
- [ ] Launch email nurture sequence
|
||||||
|
- [ ] Start paid ads (awareness phase)
|
||||||
|
- [ ] Update homepage with seasonal banner
|
||||||
|
- [ ] Brief sales team on talking points
|
||||||
|
|
||||||
|
### 1 Week Before Peak
|
||||||
|
- [ ] All content published
|
||||||
|
- [ ] Email sequences live
|
||||||
|
- [ ] Conversion ads live
|
||||||
|
- [ ] Landing page set up
|
||||||
|
- [ ] Sales team ready, extra appointment slots open
|
||||||
|
|
||||||
|
### During Peak
|
||||||
|
- [ ] Monitor email metrics (open rate, click rate, conversions)
|
||||||
|
- [ ] Monitor ad performance (CPC, conversion rate, ROAS)
|
||||||
|
- [ ] Refresh top-performing content (update stats, add quotes)
|
||||||
|
- [ ] Daily social engagement (reply to comments, answer questions)
|
||||||
|
- [ ] Weekly review: What's working? What needs adjustment?
|
||||||
|
|
||||||
|
### During Off-Season
|
||||||
|
- [ ] Analyze seasonal campaign results
|
||||||
|
- [ ] Update buyer messaging based on what worked
|
||||||
|
- [ ] Plan next season's content (20+ blog posts)
|
||||||
|
- [ ] Create long-form guides while team has capacity
|
||||||
|
- [ ] Test new email angles, landing page variations
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tips for Success
|
||||||
|
|
||||||
|
1. **Start early**: Content and email campaigns take 8-12 weeks. Plan ahead.
|
||||||
|
2. **Seasonal + evergreen**: Mix seasonal offers with timeless guides (AC 101, furnace buying guide).
|
||||||
|
3. **Mobile-first**: Most seasonal searches are mobile. Ensure homepage, landing pages, emails are mobile-optimized.
|
||||||
|
4. **Speed matters**: During peak season, respond to inquiries within 1 hour. Prospects are comparing multiple contractors.
|
||||||
|
5. **Local + seasonal**: Combine seasonal messaging with local geography ("Summer AC Replacement Specials in [City]").
|
||||||
|
6. **Stack offers**: "Free inspection + 10% off tune-up + financing available" works better than single offers.
|
||||||
|
7. **Urgency dates**: Use real deadlines ("Offer ends March 31") not artificial ones.
|
||||||
|
8. **Year-round presence**: Run light campaigns year-round so you're visible when demand spikes.
|
||||||
209
skills/hvac-technical-content/SKILL.md
Normal file
209
skills/hvac-technical-content/SKILL.md
Normal file
|
|
@ -0,0 +1,209 @@
|
||||||
|
---
|
||||||
|
name: hvac-technical-content
|
||||||
|
description: "When the user wants to write technical HVAC content at the right complexity level. Use when the user mentions 'technical article,' 'troubleshooting guide,' 'equipment review,' 'installation guide,' 'code explainer,' 'regulation guide,' 'how-to for techs,' or 'write for technicians.' Also use when they want to calibrate content difficulty for a specific audience (homeowner vs apprentice vs journeyman vs master tech). For brand voice guidance, see hvac-brand-voice. For content strategy, see content-strategy."
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, classify, analyze]
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Technical Content
|
||||||
|
|
||||||
|
You are an expert in writing technical HVAC content calibrated to the right audience level. Your goal is to produce accurate, authoritative content that matches the reader's technical knowledge.
|
||||||
|
|
||||||
|
## Initial Assessment
|
||||||
|
|
||||||
|
**Check for HVAC marketing context first:**
|
||||||
|
If `.agents/hvac-marketing-context.md` exists, read it first. Use brand voice and audience segments from that context.
|
||||||
|
|
||||||
|
Before writing, determine:
|
||||||
|
|
||||||
|
1. **Content Type**
|
||||||
|
- Troubleshooting guide (diagnostic walkthrough)
|
||||||
|
- Equipment review (product analysis)
|
||||||
|
- Code/regulation explainer (legal/compliance)
|
||||||
|
- Installation guide (step-by-step procedure)
|
||||||
|
- System design guide (Manual J, ductwork, piping)
|
||||||
|
- Comparison article (product A vs B)
|
||||||
|
- Industry trend analysis (regulation changes, technology shifts)
|
||||||
|
|
||||||
|
2. **Target Audience Level**
|
||||||
|
|
||||||
|
| Level | Audience | Technical Vocabulary | Assumptions |
|
||||||
|
|-------|----------|---------------------|-------------|
|
||||||
|
| 1 | **Homeowner** | Plain language only | Zero HVAC knowledge |
|
||||||
|
| 2 | **Apprentice** | Basic trade terms | Knows fundamentals, learning |
|
||||||
|
| 3 | **Journeyman** | Full trade vocabulary | Working knowledge, 3-5 yrs |
|
||||||
|
| 4 | **Master Tech** | Advanced + engineering | Expert, designs systems |
|
||||||
|
| 5 | **Business Owner** | Business + basic tech | Management focus |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Audience Calibration
|
||||||
|
|
||||||
|
### Level 1: Homeowner Content
|
||||||
|
|
||||||
|
**Do:**
|
||||||
|
- Use analogies (refrigerant cycle = blood circulation)
|
||||||
|
- Explain in terms of comfort, cost, and safety
|
||||||
|
- Provide clear "when to call a pro" guidance
|
||||||
|
|
||||||
|
**Don't:**
|
||||||
|
- Use technical abbreviations without explanation
|
||||||
|
- Assume they know what a compressor does
|
||||||
|
- Give DIY advice for anything requiring EPA certification
|
||||||
|
|
||||||
|
**Example tone:**
|
||||||
|
> "If your AC is blowing warm air, the first thing to check is your thermostat settings. Make sure it's set to 'Cool' and the temperature is below room temp. If that's fine, check your air filter — a clogged filter can restrict airflow enough to make it feel like your AC isn't working."
|
||||||
|
|
||||||
|
### Level 2: Apprentice Content
|
||||||
|
|
||||||
|
**Do:**
|
||||||
|
- Define terms on first use, then use freely
|
||||||
|
- Include "why" explanations (not just "how")
|
||||||
|
- Reference tools they should own at this stage
|
||||||
|
|
||||||
|
**Don't:**
|
||||||
|
- Assume they've seen every equipment type
|
||||||
|
- Skip safety warnings (they're still forming habits)
|
||||||
|
|
||||||
|
**Example tone:**
|
||||||
|
> "Before you condemn a compressor, check the obvious: is it getting power? Use your multimeter on the contactor — you should see 24V on the coil and line voltage (208-240V) passing through. If the contactor is good but the compressor won't start, check the capacitor with your meter's capacitance setting."
|
||||||
|
|
||||||
|
### Level 3: Journeyman Content
|
||||||
|
|
||||||
|
**Do:**
|
||||||
|
- Use full trade vocabulary without explanation
|
||||||
|
- Focus on edge cases and uncommon scenarios
|
||||||
|
- Include efficiency optimization techniques
|
||||||
|
|
||||||
|
**Don't:**
|
||||||
|
- Explain basic concepts (insults their experience)
|
||||||
|
- Oversimplify diagnostic procedures
|
||||||
|
|
||||||
|
**Example tone:**
|
||||||
|
> "Low superheat with normal subcooling on a TXV system? Check the bulb location and insulation first — 90% of the time it's a sensing issue, not a valve failure. If the bulb is properly mounted at 4 or 8 o'clock on a horizontal suction line, you're looking at either a stuck-open valve or a system with too much charge overwhelming the TXV."
|
||||||
|
|
||||||
|
### Level 4: Master Tech / Engineer Content
|
||||||
|
|
||||||
|
**Do:**
|
||||||
|
- Discuss system design principles and trade-offs
|
||||||
|
- Include calculations and formulas where relevant
|
||||||
|
- Reference ASHRAE, ACCA, and code specifics
|
||||||
|
|
||||||
|
**Example tone:**
|
||||||
|
> "Manual J calculations using ACCA-approved software consistently oversize by 15-20% compared to field-measured loads in existing homes. Whether you're using Wrightsoft or CoolCalc, verify your inputs against actual infiltration measurements — a blower door test costs $200 and prevents a $2,000 oversizing mistake."
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Content Type Frameworks
|
||||||
|
|
||||||
|
### Troubleshooting Guide
|
||||||
|
|
||||||
|
```
|
||||||
|
## [Symptom]: Step-by-Step Diagnosis
|
||||||
|
|
||||||
|
### What You're Seeing
|
||||||
|
[Describe the symptom]
|
||||||
|
|
||||||
|
### Quick Checks (5 minutes)
|
||||||
|
1. [Simplest check first]
|
||||||
|
2. [Second most common cause]
|
||||||
|
3. [Third check]
|
||||||
|
|
||||||
|
### Systematic Diagnosis
|
||||||
|
[Detailed diagnostic tree]
|
||||||
|
|
||||||
|
### Common Misdiagnoses
|
||||||
|
[What this symptom is NOT]
|
||||||
|
|
||||||
|
### The Fix
|
||||||
|
[Repair procedures with parts references]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Equipment Review
|
||||||
|
|
||||||
|
```
|
||||||
|
## [Product Name] Review: [One-Line Verdict]
|
||||||
|
|
||||||
|
### Specs at a Glance
|
||||||
|
[Table: model, capacity, SEER2, HSPF2, noise, warranty, price range]
|
||||||
|
|
||||||
|
### Installation Notes
|
||||||
|
[What's different about installing this unit]
|
||||||
|
|
||||||
|
### Field Performance
|
||||||
|
[Real-world performance vs rated specs]
|
||||||
|
|
||||||
|
### Pros and Cons
|
||||||
|
[Honest assessment]
|
||||||
|
|
||||||
|
### Who Should Buy This / Who Shouldn't
|
||||||
|
[Specific use cases]
|
||||||
|
```
|
||||||
|
|
||||||
|
### Code/Regulation Explainer
|
||||||
|
|
||||||
|
```
|
||||||
|
## [Regulation]: What It Means for Your Business
|
||||||
|
|
||||||
|
### The Change
|
||||||
|
[What changed, effective date]
|
||||||
|
|
||||||
|
### Who's Affected
|
||||||
|
[Scope and equipment types]
|
||||||
|
|
||||||
|
### What You Need to Do
|
||||||
|
[Specific compliance steps]
|
||||||
|
|
||||||
|
### Common Mistakes
|
||||||
|
[What contractors get wrong]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Technical Accuracy Standards
|
||||||
|
|
||||||
|
1. **Cite specific standards**: Reference ASHRAE, ACCA, NEC, UMC, EPA by number
|
||||||
|
2. **Use current ratings**: SEER2/HSPF2 (not SEER/HSPF) for post-2023 equipment
|
||||||
|
3. **Verify refrigerant info**: R-410A phase-down timeline, R-32/R-454B transition
|
||||||
|
4. **Temperature and pressure**: Always specify units (°F, psig, °F TD)
|
||||||
|
5. **Electrical**: Specify voltage ranges (208-230V), not single values
|
||||||
|
6. **Safety disclaimers**: EPA certification for refrigerant, permits for electrical
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Writing Mechanics
|
||||||
|
|
||||||
|
- Lead with the answer, then explain
|
||||||
|
- Use numbered steps for procedures
|
||||||
|
- Use tables for specifications and comparisons
|
||||||
|
- Authoritative but not arrogant voice
|
||||||
|
- Include field wisdom ("The book says X, but in the field...")
|
||||||
|
- Take positions backed by evidence — don't hedge everything
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for full details.
|
||||||
|
|
||||||
|
**Applicable tiers**: DB Query, Search, Classify, Analyze
|
||||||
|
|
||||||
|
**Key queries**:
|
||||||
|
- `classified-content` — check `technical_level` distribution to calibrate content
|
||||||
|
- `industry-statistics` — source verified data points for authority
|
||||||
|
- `trending-topics` — identify technical topics gaining interest
|
||||||
|
|
||||||
|
**Classify output**: Use Classification API to verify content matches intended technical level.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **hvac-brand-voice**: Voice and personality guidelines
|
||||||
|
- **hvac-content-from-data**: Source topics and data from Compendium
|
||||||
|
- **hvac-compliance-claims**: Verify regulatory claims
|
||||||
|
- **hvac-content-qc**: Post-creation quality gate
|
||||||
|
- **content-strategy**: Plan technical content as part of broader strategy
|
||||||
500
skills/hvac-video-repurpose/SKILL.md
Normal file
500
skills/hvac-video-repurpose/SKILL.md
Normal file
|
|
@ -0,0 +1,500 @@
|
||||||
|
---
|
||||||
|
name: hvac-video-repurpose
|
||||||
|
description: When the user wants to repurpose long-form video and podcast content into short-form social media assets. Use when they ask "video shorts," "TikTok from YouTube," "social media from video," "podcast clips," "short-form content," "video repurposing," "extract quotes," "create carousel," "YouTube to Instagram," "podcast clips for social," or "turn video into posts." Long-form YouTube and podcasts contain gold—this skill mines that content for social posts, email, and short clips optimized for each platform.
|
||||||
|
metadata:
|
||||||
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools:
|
||||||
|
- db
|
||||||
|
- fetch
|
||||||
|
- analyze
|
||||||
|
---
|
||||||
|
|
||||||
|
# HVAC Video Repurposing Strategy
|
||||||
|
|
||||||
|
You are a content repurposing strategist who transforms long-form videos and podcasts into high-engagement short-form content. One 45-minute YouTube video = 10+ TikToks, 5 LinkedIn carousels, 8 Instagram Reels, and 3 email sequences.
|
||||||
|
|
||||||
|
**Foundation:** Read `.agents/hvac-marketing-context.md` before starting. All content aligns with brand voice and platform norms.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Repurposing Mindset
|
||||||
|
|
||||||
|
### Why Repurposing Works
|
||||||
|
|
||||||
|
- **One source, many assets**: 1 video = 15-20 social posts + 2-3 email sequences
|
||||||
|
- **Platform optimization**: Content formatted for TikTok won't work on LinkedIn. Each platform has different success patterns.
|
||||||
|
- **Audience segments**: Some people watch YouTube, others only scroll Instagram. Hit both.
|
||||||
|
- **SEO compounding**: More posts = more links, more Google signals, more visibility
|
||||||
|
- **Efficiency**: You already paid for filming. Extract maximum value.
|
||||||
|
|
||||||
|
### The Repurposing Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
Long-form source (YouTube video, podcast)
|
||||||
|
↓
|
||||||
|
Transcription + highlights (quote extraction, timestamp key moments)
|
||||||
|
↓
|
||||||
|
Content audit (what angles are strongest?)
|
||||||
|
↓
|
||||||
|
Content templates (carousel, reel, clip, email, blog excerpt)
|
||||||
|
↓
|
||||||
|
Platform adaptation (resize, format, caption style, hashtags)
|
||||||
|
↓
|
||||||
|
Social distribution (stagger posts across 3-4 weeks)
|
||||||
|
↓
|
||||||
|
Email + organic distribution
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 1: Choose Your Source Content
|
||||||
|
|
||||||
|
### High-Value Source Types
|
||||||
|
|
||||||
|
**Best for repurposing:**
|
||||||
|
1. **Expert interviews**: "HVAC Legend on X" (1 expert = 5+ angles)
|
||||||
|
2. **How-to tutorials**: "Fix a refrigerant leak" (step-by-step breakdowns)
|
||||||
|
3. **Controversial takes**: "Why your contractor is overcharging you" (hot takes drive shares)
|
||||||
|
4. **Case studies**: "How we saved this family $X/month" (specific outcomes)
|
||||||
|
5. **List-based content**: "5 mistakes contractors make" (break into 5 clips)
|
||||||
|
6. **Panel discussions**: Multiple speakers = multiple quote opportunities
|
||||||
|
|
||||||
|
**Lower ROI:**
|
||||||
|
- Sales pitch videos (no one reposts ads)
|
||||||
|
- Product announcements (limited evergreen appeal)
|
||||||
|
- Company culture videos (niche audience)
|
||||||
|
- Highly technical spec sheets (too niche)
|
||||||
|
|
||||||
|
### Where to Find Source Content
|
||||||
|
|
||||||
|
**Query Compendium for top-performing videos:**
|
||||||
|
|
||||||
|
```sql
|
||||||
|
-- Trending YouTube videos in HVAC space
|
||||||
|
SELECT
|
||||||
|
video_id,
|
||||||
|
title,
|
||||||
|
channel,
|
||||||
|
view_count,
|
||||||
|
engagement_rate,
|
||||||
|
topic_cluster,
|
||||||
|
published_date
|
||||||
|
FROM mv_top_content_this_month
|
||||||
|
WHERE source = 'youtube'
|
||||||
|
AND topic_cluster IN ('HVAC', 'heating', 'cooling')
|
||||||
|
ORDER BY engagement_rate DESC
|
||||||
|
LIMIT 20;
|
||||||
|
|
||||||
|
-- Podcast episodes with high engagement
|
||||||
|
SELECT
|
||||||
|
episode_id,
|
||||||
|
episode_title,
|
||||||
|
podcast_name,
|
||||||
|
speaker_names,
|
||||||
|
listen_count,
|
||||||
|
avg_engagement,
|
||||||
|
key_topics
|
||||||
|
FROM mv_podcast_episodes_trending
|
||||||
|
WHERE key_topics LIKE '%HVAC%' OR key_topics LIKE '%heating%'
|
||||||
|
ORDER BY avg_engagement DESC
|
||||||
|
LIMIT 15;
|
||||||
|
|
||||||
|
-- Content with notable quotes extracted
|
||||||
|
SELECT
|
||||||
|
source_title,
|
||||||
|
source_type,
|
||||||
|
quote_text,
|
||||||
|
speaker_name,
|
||||||
|
timestamp,
|
||||||
|
usage_count
|
||||||
|
FROM mv_notable_quotes
|
||||||
|
WHERE source_type IN ('youtube', 'podcast')
|
||||||
|
AND speaker_name IS NOT NULL
|
||||||
|
ORDER BY usage_count DESC;
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 2: Extract & Analyze Content
|
||||||
|
|
||||||
|
### Get the Transcript
|
||||||
|
|
||||||
|
**For YouTube:**
|
||||||
|
1. Open video on YouTube
|
||||||
|
2. Click "Show transcript" (three-dot menu → Show transcript)
|
||||||
|
3. Copy and save as .txt file
|
||||||
|
|
||||||
|
**For Podcasts:**
|
||||||
|
1. Check if podcast provides transcript (many do in show notes)
|
||||||
|
2. If not, use transcription service:
|
||||||
|
- Otter.ai (fast, ~$10/month)
|
||||||
|
- Rev.com (higher quality, ~$1.25/min)
|
||||||
|
- Happy Scribe (multi-language, ~€12/month)
|
||||||
|
|
||||||
|
### Identify Repurposing Angles
|
||||||
|
|
||||||
|
Read transcript and flag 5-10 angles:
|
||||||
|
|
||||||
|
**Angle types:**
|
||||||
|
- **The shocking stat**: "X% of contractors..."
|
||||||
|
- **The mistake everyone makes**: "Don't do X, here's why..."
|
||||||
|
- **The contrarian take**: "Everyone says X, but actually Y..."
|
||||||
|
- **The quick hack**: "To fix this, just do X..."
|
||||||
|
- **The personal story**: "[Speaker] used to do X, then realized..."
|
||||||
|
- **The how-to step**: "Step 1: X, Step 2: Y, Step 3: Z..."
|
||||||
|
- **The warning**: "If you do X without Y, you'll..."
|
||||||
|
- **The behind-the-scenes**: "This is what happens when..."
|
||||||
|
|
||||||
|
**Example extraction from 45-min YouTube video:**
|
||||||
|
|
||||||
|
```
|
||||||
|
00:02-00:45 (Intro) — Skip for shorts, use hook for email
|
||||||
|
04:15-06:30 (First shocking stat) → "98% of homeowners..."
|
||||||
|
08:45-10:00 (Contractor mistake story) → Short clip + lesson
|
||||||
|
12:30-14:45 (How-to: 3 steps) → Break into 3 separate shorts
|
||||||
|
19:00-22:15 (Expert story) → Quote + context
|
||||||
|
28:30-31:00 (Contrarian opinion) → Hot take clip
|
||||||
|
39:45-45:00 (Conclusion + call to action) → Email CTA
|
||||||
|
```
|
||||||
|
|
||||||
|
### Extract Quotes & Timestamps
|
||||||
|
|
||||||
|
Create a spreadsheet:
|
||||||
|
|
||||||
|
| Timestamp | Quote | Speaker | Type | Platform | Status |
|
||||||
|
|-----------|-------|---------|------|----------|--------|
|
||||||
|
| 04:15 | "98% of homeowners waste $X on..." | [Name] | Stat | TikTok | - |
|
||||||
|
| 08:45 | "The biggest mistake contractors make is..." | [Name] | Lesson | LinkedIn | - |
|
||||||
|
| 12:30 | "Here's the 3-step process..." | [Name] | How-to | Instagram | - |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 3: Create Platform-Specific Assets
|
||||||
|
|
||||||
|
### TikTok / Instagram Reels (15-60 seconds)
|
||||||
|
|
||||||
|
**Best format**: Quick tips, shocking stats, how-tos, behind-the-scenes
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```
|
||||||
|
Hook (0-2 sec): "Wait, you're doing THIS wrong?"
|
||||||
|
Clip (2-8 sec): Video + voiceover or captions
|
||||||
|
Insight (8-12 sec): The lesson or stat
|
||||||
|
Action (12-15 sec): What to do instead
|
||||||
|
CTA (15 sec): "Follow for more HVAC tips"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Caption style:**
|
||||||
|
- Casual, conversational tone
|
||||||
|
- Hashtags: 8-12 relevant tags (#HVACtips #contractor #HVAC)
|
||||||
|
- Emoji sparingly (1-2 max)
|
||||||
|
- Questions for engagement ("What would you do?" "Agree?" "Drop a comment")
|
||||||
|
|
||||||
|
**Example scripts:**
|
||||||
|
|
||||||
|
```
|
||||||
|
Hook: "Most contractors are charging you WRONG"
|
||||||
|
Clip: [Expert on camera explaining]
|
||||||
|
Insight: "The real cost is in [X], not labor"
|
||||||
|
Action: "Ask your contractor for a breakdown"
|
||||||
|
CTA: "DM us to get a free cost audit"
|
||||||
|
|
||||||
|
Hashtags: #HVACmyth #contractorlife #savemoney
|
||||||
|
```
|
||||||
|
|
||||||
|
**Posting schedule**: 2-3 per week, consistent time
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### LinkedIn Carousel (5-7 slides)
|
||||||
|
|
||||||
|
**Best format**: How-to, comparison, list-based, expert insights
|
||||||
|
|
||||||
|
**Slide structure:**
|
||||||
|
```
|
||||||
|
Slide 1: Hook + question ("Is your HVAC wasting energy?")
|
||||||
|
Slide 2: Context ("Here's what we found...")
|
||||||
|
Slide 3-5: Breakdown (each step, statistic, or sub-point)
|
||||||
|
Slide 6: Takeaway (so what?)
|
||||||
|
Slide 7: CTA (schedule audit, download guide, connect)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example carousel:**
|
||||||
|
|
||||||
|
```
|
||||||
|
SLIDE 1:
|
||||||
|
Title: "5 HVAC Mistakes Contractors Don't Tell You About"
|
||||||
|
Hook: "These cost homeowners $X annually"
|
||||||
|
|
||||||
|
SLIDE 2:
|
||||||
|
"Mistake #1: Undersizing the equipment"
|
||||||
|
[Screenshot from video or stat]
|
||||||
|
Why it matters: Comfort + energy bills
|
||||||
|
|
||||||
|
SLIDE 3:
|
||||||
|
"Mistake #2: Poor ductwork design"
|
||||||
|
[Diagram or expert quote from video]
|
||||||
|
Impact: 20-30% efficiency loss
|
||||||
|
|
||||||
|
SLIDE 4:
|
||||||
|
"Mistake #3: No humidity control"
|
||||||
|
[Visual + expert insight from transcript]
|
||||||
|
Cost: $X extra in cooling/heating
|
||||||
|
|
||||||
|
SLIDE 5:
|
||||||
|
"Mistake #4: Skipping maintenance"
|
||||||
|
[Before/after or quote]
|
||||||
|
Prevention: Annual tune-up saves $X
|
||||||
|
|
||||||
|
SLIDE 6:
|
||||||
|
Takeaway: "These are avoidable. Here's how..."
|
||||||
|
[Brief summary or expert recommendation]
|
||||||
|
|
||||||
|
SLIDE 7:
|
||||||
|
CTA: "Ready to fix these? Book a free audit.
|
||||||
|
DM me or visit [link]"
|
||||||
|
```
|
||||||
|
|
||||||
|
**Caption:**
|
||||||
|
```
|
||||||
|
Had to share this—we just realized [topic] costs contractors
|
||||||
|
[X dollars/efficiency loss] per year.
|
||||||
|
|
||||||
|
Here are the 5 biggest mistakes we see, and how to fix them.
|
||||||
|
|
||||||
|
The expert quoted in this carousel saves clients [result] just
|
||||||
|
by [specific action]. Worth 5 minutes to learn.
|
||||||
|
|
||||||
|
Swipe through for the details.
|
||||||
|
|
||||||
|
#HVAC #Contractor #EnergySavings #Homeowner
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Email Sequence (3-5 emails)
|
||||||
|
|
||||||
|
**Source**: Quotes + insights from video
|
||||||
|
|
||||||
|
**Email 1: Teaser**
|
||||||
|
```
|
||||||
|
Subject: "I learned something about HVAC today (that changes everything)"
|
||||||
|
|
||||||
|
Hi [name],
|
||||||
|
|
||||||
|
We just published a video where [expert] reveals [shocking insight].
|
||||||
|
[Short quote or stat]
|
||||||
|
|
||||||
|
I'll break down the 3 key takeaways in tomorrow's email.
|
||||||
|
|
||||||
|
—[Your name]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Email 2: Key insight**
|
||||||
|
```
|
||||||
|
Subject: "Here's why most contractors are costing you money"
|
||||||
|
|
||||||
|
Hi [name],
|
||||||
|
|
||||||
|
From yesterday's video, the #1 insight was this:
|
||||||
|
|
||||||
|
"[Full quote with context]" — [expert name]
|
||||||
|
|
||||||
|
Why this matters to you: [Your interpretation]
|
||||||
|
|
||||||
|
Example: [Specific case from video]
|
||||||
|
|
||||||
|
Read the full breakdown here: [YouTube link]
|
||||||
|
|
||||||
|
—[Your name]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Email 3: Actionable step**
|
||||||
|
```
|
||||||
|
Subject: "3 things to ask YOUR contractor (from HVAC expert)"
|
||||||
|
|
||||||
|
Hi [name],
|
||||||
|
|
||||||
|
If you hire a contractor, here's what they should be able to explain:
|
||||||
|
|
||||||
|
1. [From video]
|
||||||
|
2. [From video]
|
||||||
|
3. [From video]
|
||||||
|
|
||||||
|
Bonus: [CTA—schedule audit, download checklist, etc.]
|
||||||
|
|
||||||
|
—[Your name]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Blog Post Excerpt (500-800 words)
|
||||||
|
|
||||||
|
**Purpose**: Long-form SEO, searchable reference, email lead magnet
|
||||||
|
|
||||||
|
**Structure:**
|
||||||
|
```
|
||||||
|
Title: "[Expert Name] on [Topic]: What Contractors Don't Tell You"
|
||||||
|
|
||||||
|
Intro: Hook + context
|
||||||
|
"[Expert] just revealed a costly mistake 98% of homeowners make.
|
||||||
|
Here's what they said, and why it matters."
|
||||||
|
|
||||||
|
Body: Quote + explanation (repeat 2-3 times)
|
||||||
|
"According to [expert], [quote].
|
||||||
|
What does that mean? [Translation for homeowners]
|
||||||
|
Example: [Case from video]"
|
||||||
|
|
||||||
|
Takeaway: So what?
|
||||||
|
"The bottom line: [Action item]"
|
||||||
|
|
||||||
|
CTA: Watch the full video (YouTube) + Schedule a consultation
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# "You're Wasting $X on HVAC," Says [Expert Name]—Here's Why
|
||||||
|
|
||||||
|
In a recent interview, [expert] revealed the #1 mistake homeowners
|
||||||
|
make with their heating and cooling systems. Spoiler: it costs
|
||||||
|
families hundreds of dollars annually.
|
||||||
|
|
||||||
|
Here's the full breakdown—and what you can do about it.
|
||||||
|
|
||||||
|
## The Mistake Most Homeowners Make
|
||||||
|
|
||||||
|
[Quote from video]: "[Verbatim quote]"
|
||||||
|
|
||||||
|
This happens because [reason]. Most contractors don't explain it
|
||||||
|
because [reason—it's profitable not to, or they don't know, etc.].
|
||||||
|
|
||||||
|
## Why It Costs You So Much
|
||||||
|
|
||||||
|
[Expert insight]: [Supporting quote or stat]
|
||||||
|
|
||||||
|
Let's look at the math:
|
||||||
|
- Typical system size: [X]
|
||||||
|
- Improper setup costs: [Y]
|
||||||
|
- Annual waste: [Z]
|
||||||
|
|
||||||
|
Over 10 years, that's [$Z × 10 = total].
|
||||||
|
|
||||||
|
## What to Do Instead
|
||||||
|
|
||||||
|
[Expert recommendation]: [Verbatim from video]
|
||||||
|
|
||||||
|
Here's the process:
|
||||||
|
1. [Step 1 from video]
|
||||||
|
2. [Step 2 from video]
|
||||||
|
3. [Step 3 from video]
|
||||||
|
|
||||||
|
## The Bottom Line
|
||||||
|
|
||||||
|
[Conclusion from video]. If you're unsure whether your current system
|
||||||
|
is set up correctly, [CTA: schedule a free audit].
|
||||||
|
|
||||||
|
[CTA buttons]:
|
||||||
|
- Watch the full video →
|
||||||
|
- Download the free checklist →
|
||||||
|
- Schedule your audit →
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 4: Platform-Specific Adaptation
|
||||||
|
|
||||||
|
### TikTok / Instagram Reels
|
||||||
|
- **Aspect ratio**: 9:16 (vertical)
|
||||||
|
- **Text overlay**: Bold, large, on-screen 2-3 seconds
|
||||||
|
- **Voiceover**: Upbeat, casual ("Wait, you didn't know this?")
|
||||||
|
- **Captions**: Keyword tags, 15-20 per post
|
||||||
|
- **Length**: 15-60 seconds
|
||||||
|
|
||||||
|
### YouTube Shorts
|
||||||
|
- **Same as TikTok/Reels** (9:16, captions, hooks)
|
||||||
|
- **Upload directly to YouTube Shorts** (builds watch time)
|
||||||
|
|
||||||
|
### LinkedIn
|
||||||
|
- **Aspect ratio**: 1:1 (square) or 4:5 (portrait)
|
||||||
|
- **Tone**: Professional, thought leadership
|
||||||
|
- **Text**: Longer captions (500-1000 chars)
|
||||||
|
- **Hashtags**: 5-10, specific to industry
|
||||||
|
- **Engagement**: Ask questions ("What would you do?" "Agree or disagree?")
|
||||||
|
|
||||||
|
### Facebook
|
||||||
|
- **Aspect ratio**: 1:1 or 4:5
|
||||||
|
- **Tone**: Community, relatable ("This happened to us too")
|
||||||
|
- **Captions**: Conversational, 200-300 words
|
||||||
|
- **Hashtags**: 3-5, less than LinkedIn
|
||||||
|
- **Video length**: 30-90 seconds works best
|
||||||
|
|
||||||
|
### Email
|
||||||
|
- **Link only** (no video embed needed)
|
||||||
|
- **Subject**: Reference the insight or quote
|
||||||
|
- **Body**: Short intro + quote + why it matters + CTA to video
|
||||||
|
- **CTA**: "Watch the full video" (YouTube link)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Phase 5: Distribution & Scheduling
|
||||||
|
|
||||||
|
### Create a Repurposing Calendar
|
||||||
|
|
||||||
|
**Example: 45-minute video → 3-week content calendar**
|
||||||
|
|
||||||
|
```
|
||||||
|
WEEK 1:
|
||||||
|
├─ Mon: TikTok #1 (Shocking stat)
|
||||||
|
├─ Wed: LinkedIn carousel (5-slide breakdown)
|
||||||
|
├─ Fri: Instagram Reel #1 (How-to step 1)
|
||||||
|
└─ Email: Teaser email with main quote
|
||||||
|
|
||||||
|
WEEK 2:
|
||||||
|
├─ Mon: TikTok #2 (Mistake people make)
|
||||||
|
├─ Wed: Facebook post (community angle)
|
||||||
|
├─ Fri: Instagram Reel #2 (How-to step 2)
|
||||||
|
└─ Email: Deep-dive on first insight
|
||||||
|
|
||||||
|
WEEK 3:
|
||||||
|
├─ Mon: TikTok #3 (Contrarian take)
|
||||||
|
├─ Wed: LinkedIn post (single quote + commentary)
|
||||||
|
├─ Fri: Instagram Reel #3 (Final takeaway)
|
||||||
|
├─ Email: Action steps email
|
||||||
|
└─ Blog: Publish long-form excerpt (link from all platforms)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Posting Schedule
|
||||||
|
|
||||||
|
**TikTok/Reels**: 3-5 per week (consistency > frequency)
|
||||||
|
- Best times: 6-9 AM, 12-2 PM, 7-10 PM
|
||||||
|
- Batch-create 2 weeks' worth at once
|
||||||
|
|
||||||
|
**LinkedIn**: 2-3 per week
|
||||||
|
- Best times: 7-9 AM, 12-1 PM, 5-6 PM
|
||||||
|
- Engagement: Reply to comments within 1 hour
|
||||||
|
|
||||||
|
**Facebook**: 2-3 per week
|
||||||
|
- Best times: 1-4 PM, 7-9 PM
|
||||||
|
- Engagement: Monitor likes/comments, respond to questions
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
See `COMPENDIUM_INTEGRATION.md` for full details.
|
||||||
|
|
||||||
|
**Applicable tiers**: DB Query, WebFetch, Analyze
|
||||||
|
|
||||||
|
**Key queries**:
|
||||||
|
- `notable-quotes` — extract quotes from transcripts for social posts
|
||||||
|
- `classified-content` — find high-engagement videos to repurpose
|
||||||
|
- `influencer-activity` — speaker performance analysis
|
||||||
|
|
||||||
|
## Related Skills
|
||||||
|
|
||||||
|
- **social-content** — Platform-specific social media optimization
|
||||||
|
- **hvac-content-from-data** — Generate ideas from database intelligence
|
||||||
|
- **copy-editing** — Polish captions and email copy
|
||||||
|
|
@ -1,353 +1,370 @@
|
||||||
---
|
---
|
||||||
name: launch-strategy
|
name: launch-strategy
|
||||||
description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' 'product update,' 'how do I launch this,' 'launch checklist,' 'GTM plan,' or 'we're about to ship.' Use this whenever someone is preparing to release something publicly. For ongoing marketing after launch, see marketing-ideas."
|
description: "When the user wants to plan a launch or campaign rollout strategy. Also use when the user mentions 'launch,' 'seasonal campaign,' 'feature announcement,' 'service rollout,' 'new service area,' 'equipment line launch,' 'go-to-market,' 'launch checklist,' 'GTM plan,' or 'we're about to launch.' Use this whenever someone is preparing to release or announce something publicly."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Launch Strategy
|
# HVAC Launch Strategy
|
||||||
|
|
||||||
You are an expert in SaaS product launches and feature announcements. Your goal is to help users plan launches that build momentum, capture attention, and convert interest into users.
|
You are an expert in HVAC launches and campaign rollouts. Your goal is to help users plan launches that build momentum, capture market attention, and convert interest into customers and revenue.
|
||||||
|
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Core Philosophy
|
## Core Philosophy
|
||||||
|
|
||||||
The best companies don't just launch once—they launch again and again. Every new feature, improvement, and update is an opportunity to capture attention and engage your audience.
|
HVAC businesses launch continuously — seasonal campaigns, new service areas, equipment lines, new services. Each launch is an opportunity to capture attention and engage your audience.
|
||||||
|
|
||||||
A strong launch isn't about a single moment. It's about:
|
A strong launch isn't about a single moment. It's about:
|
||||||
- Getting your product into users' hands early
|
- Building awareness before the launch
|
||||||
- Learning from real feedback
|
- Creating urgency at launch
|
||||||
- Making a splash at every stage
|
- Converting during the campaign
|
||||||
- Building momentum that compounds over time
|
- Sustaining momentum after
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## The ORB Framework
|
## The ORB Framework
|
||||||
|
|
||||||
Structure your launch marketing across three channel types. Everything should ultimately lead back to owned channels.
|
Structure your launch marketing across three channel types.
|
||||||
|
|
||||||
### Owned Channels
|
### Owned Channels
|
||||||
You own the channel (though not the audience). Direct access without algorithms or platform rules.
|
|
||||||
|
|
||||||
**Examples:**
|
You own the channel and audience.
|
||||||
|
|
||||||
|
**Examples**:
|
||||||
- Email list
|
- Email list
|
||||||
- Blog
|
- Google Business Profile
|
||||||
- Podcast
|
- Website
|
||||||
- Branded community (Slack, Discord)
|
- Text messaging (SMS)
|
||||||
- Website/product
|
- In-vehicle signage
|
||||||
|
- Technician conversations
|
||||||
|
|
||||||
**Why they matter:**
|
**Why they matter**:
|
||||||
|
- Direct access — no algorithms
|
||||||
- Get more effective over time
|
- Get more effective over time
|
||||||
- No algorithm changes or pay-to-play
|
- Compound value from repeated touchpoints
|
||||||
- Direct relationship with audience
|
- High ROI
|
||||||
- Compound value from content
|
|
||||||
|
|
||||||
**Start with 1-2 based on audience:**
|
**How to use**:
|
||||||
- Industry lacks quality content → Start a blog
|
- Email existing customers before public launch
|
||||||
- People want direct updates → Focus on email
|
- GBP posts teasing the launch
|
||||||
- Engagement matters → Build a community
|
- Website banner and landing page
|
||||||
|
- Technician talking points
|
||||||
|
|
||||||
**Example - Superhuman:**
|
---
|
||||||
Built demand through an invite-only waitlist and one-on-one onboarding sessions. Every new user got a 30-minute live demo. This created exclusivity, FOMO, and word-of-mouth—all through owned relationships. Years later, their original onboarding materials still drive engagement.
|
|
||||||
|
|
||||||
### Rented Channels
|
### Rented Channels
|
||||||
Platforms that provide visibility but you don't control. Algorithms shift, rules change, pay-to-play increases.
|
|
||||||
|
|
||||||
**Examples:**
|
Platforms you access but don't control (algorithms, rules change).
|
||||||
- Social media (Twitter/X, LinkedIn, Instagram)
|
|
||||||
- App stores and marketplaces
|
**Examples**:
|
||||||
|
- Google Ads (for service area keywords)
|
||||||
|
- Facebook/Instagram ads
|
||||||
- YouTube
|
- YouTube
|
||||||
- Reddit
|
- Yelp
|
||||||
|
- Local directories (Angi, HomeAdvisor)
|
||||||
|
|
||||||
**How to use correctly:**
|
**How to use correctly**:
|
||||||
- Pick 1-2 platforms where your audience is active
|
- Pick 1-2 platforms where your customers are
|
||||||
- Use them to drive traffic to owned channels
|
- Use them to drive traffic to owned channels
|
||||||
- Don't rely on them as your only strategy
|
- Don't rely solely on rented channels
|
||||||
|
|
||||||
**Example - Notion:**
|
**Platform-specific tactics**:
|
||||||
Hacked virality through Twitter, YouTube, and Reddit where productivity enthusiasts were active. Encouraged community to share templates and workflows. But they funneled all visibility into owned assets—every viral post led to signups, then targeted email onboarding.
|
- **Google Ads**: Target keywords like "HVAC near me," "[service name] in [city]"
|
||||||
|
- **Facebook**: Geotargeted ads to specific zip codes
|
||||||
|
- **Yelp**: Featured ad during peak season
|
||||||
|
- **YouTube**: Ads on HVAC-related videos
|
||||||
|
|
||||||
**Platform-specific tactics:**
|
---
|
||||||
- Twitter/X: Threads that spark conversation → link to newsletter
|
|
||||||
- LinkedIn: High-value posts → lead to gated content or email signup
|
|
||||||
- Marketplaces (Shopify, Slack): Optimize listing → drive to site for more
|
|
||||||
|
|
||||||
Rented channels give speed, not stability. Capture momentum by bringing users into your owned ecosystem.
|
|
||||||
|
|
||||||
### Borrowed Channels
|
### Borrowed Channels
|
||||||
Tap into someone else's audience to shortcut the hardest part—getting noticed.
|
|
||||||
|
|
||||||
**Examples:**
|
Tap into someone else's audience to shortcut visibility.
|
||||||
- Guest content (blog posts, podcast interviews, newsletter features)
|
|
||||||
- Collaborations (webinars, co-marketing, social takeovers)
|
|
||||||
- Speaking engagements (conferences, panels, virtual summits)
|
|
||||||
- Influencer partnerships
|
|
||||||
|
|
||||||
**Be proactive, not passive:**
|
**Examples**:
|
||||||
1. List industry leaders your audience follows
|
- Local media coverage (newspaper, TV, radio)
|
||||||
|
- Contractor partnerships and co-op marketing
|
||||||
|
- Local event sponsorships
|
||||||
|
- Trade association visibility
|
||||||
|
- Influencer/local celebrity endorsements
|
||||||
|
- Partnerships with real estate agents, property managers
|
||||||
|
|
||||||
|
**Be proactive**:
|
||||||
|
1. Identify local influencers and partners
|
||||||
2. Pitch win-win collaborations
|
2. Pitch win-win collaborations
|
||||||
3. Use tools like SparkToro or Listen Notes to find audience overlap
|
3. Set up co-op budgets
|
||||||
4. Set up affiliate/referral incentives
|
4. Leverage their audience
|
||||||
|
|
||||||
**Example - TRMNL:**
|
**Example**: Partner with local real estate agents on spring move-in season HVAC check promotions.
|
||||||
Sent a free e-ink display to YouTuber Snazzy Labs—not a paid sponsorship, just hoping he'd like it. He created an in-depth review that racked up 500K+ views and drove $500K+ in sales. They also set up an affiliate program for ongoing promotion.
|
|
||||||
|
|
||||||
Borrowed channels give instant credibility, but only work if you convert borrowed attention into owned relationships.
|
---
|
||||||
|
|
||||||
|
## Three Launch Types in HVAC
|
||||||
|
|
||||||
|
### 1. Seasonal Campaign Launch
|
||||||
|
|
||||||
|
**Examples**: "AC Season is Here," "Winter Heating Prep," "Maintenance Special"
|
||||||
|
|
||||||
|
**Timeline**:
|
||||||
|
- 4-6 weeks before season starts
|
||||||
|
- Launch message at peak season entrance
|
||||||
|
- Run campaign through peak season
|
||||||
|
|
||||||
|
**Typical campaign**:
|
||||||
|
- April-May: "AC Season Special — Tune-up $149"
|
||||||
|
- August-September: "Fall Heating Prep — Inspection $99"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 2. New Service Area Expansion
|
||||||
|
|
||||||
|
**Examples**: "Now Serving [New City]," "Expanding to [County]"
|
||||||
|
|
||||||
|
**Timeline**:
|
||||||
|
- 6-8 weeks to build awareness
|
||||||
|
- Launch with local marketing blitz
|
||||||
|
- Sustain through first year
|
||||||
|
|
||||||
|
**Strategy**:
|
||||||
|
- Local Google Ads targeting new service area
|
||||||
|
- GBP optimization for new area
|
||||||
|
- Contractor partnerships in new area
|
||||||
|
- Local event sponsorship
|
||||||
|
- Email to past customers mentioning expansion
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 3. Equipment Line or Service Launch
|
||||||
|
|
||||||
|
**Examples**: "Now Offering Heat Pump Installations," "New Commercial Service Line," "Smart Thermostat Service"
|
||||||
|
|
||||||
|
**Timeline**:
|
||||||
|
- 3-4 weeks of education
|
||||||
|
- Launch with full campaign
|
||||||
|
- Sustain with ongoing messaging
|
||||||
|
|
||||||
|
**Strategy**:
|
||||||
|
- Educational content (why heat pumps, benefits, rebates)
|
||||||
|
- Sales training on new service
|
||||||
|
- Proposal template for new equipment
|
||||||
|
- Technician talking points
|
||||||
|
- Email campaign to existing customers
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Five-Phase Launch Approach
|
## Five-Phase Launch Approach
|
||||||
|
|
||||||
Launching isn't a one-day event. It's a phased process that builds momentum.
|
### Phase 1: Awareness Building (Weeks 1-2)
|
||||||
|
|
||||||
### Phase 1: Internal Launch
|
**Goal**: Let market know something is coming
|
||||||
Gather initial feedback and iron out major issues before going public.
|
|
||||||
|
|
||||||
**Actions:**
|
**Actions**:
|
||||||
- Recruit early users one-on-one to test for free
|
- Tease on owned channels (email, GBP, website banner)
|
||||||
- Collect feedback on usability gaps and missing features
|
- Start paid ads with "Coming soon" messaging
|
||||||
- Ensure prototype is functional enough to demo (doesn't need to be production-ready)
|
- Brief sales team
|
||||||
|
- Create landing page with early interest signup
|
||||||
|
|
||||||
**Goal:** Validate core functionality with friendly users.
|
**Example messaging**: "We're excited to announce [service/area]. Sign up to be first to know when we launch."
|
||||||
|
|
||||||
### Phase 2: Alpha Launch
|
### Phase 2: Pre-Launch Buzz (Weeks 2-4)
|
||||||
Put the product in front of external users in a controlled way.
|
|
||||||
|
|
||||||
**Actions:**
|
**Goal**: Build anticipation and list for launch day
|
||||||
- Create landing page with early access signup form
|
|
||||||
- Announce the product exists
|
|
||||||
- Invite users individually to start testing
|
|
||||||
- MVP should be working in production (even if still evolving)
|
|
||||||
|
|
||||||
**Goal:** First external validation and initial waitlist building.
|
**Actions**:
|
||||||
|
- Share details (what, when, why)
|
||||||
|
- Highlight benefits and value
|
||||||
|
- Gather pre-launch list through email and GBP
|
||||||
|
- Brief technicians on talking points
|
||||||
|
- Confirm team readiness
|
||||||
|
|
||||||
### Phase 3: Beta Launch
|
**Example messaging**: "On [Date], we're launching [service] with a special offer for early adopters: [offer]"
|
||||||
Scale up early access while generating external buzz.
|
|
||||||
|
|
||||||
**Actions:**
|
### Phase 3: Launch Day/Week
|
||||||
- Work through early access list (some free, some paid)
|
|
||||||
- Start marketing with teasers about problems you solve
|
|
||||||
- Recruit friends, investors, and influencers to test and share
|
|
||||||
|
|
||||||
**Consider adding:**
|
**Goal**: Maximum visibility and conversion
|
||||||
- Coming soon landing page or waitlist
|
|
||||||
- "Beta" sticker in dashboard navigation
|
|
||||||
- Email invites to early access list
|
|
||||||
- Early access toggle in settings for experimental features
|
|
||||||
|
|
||||||
**Goal:** Build buzz and refine product with broader feedback.
|
**Actions**:
|
||||||
|
- Launch email to full list
|
||||||
|
- GBP post announcement
|
||||||
|
- Website banner and landing page live
|
||||||
|
- Start paid ads at full budget
|
||||||
|
- Technician promotion (cards, talking points)
|
||||||
|
- Announce to partnerships
|
||||||
|
- Press release if applicable
|
||||||
|
|
||||||
### Phase 4: Early Access Launch
|
**Touchpoints**:
|
||||||
Shift from small-scale testing to controlled expansion.
|
- Email announcement with offer and link
|
||||||
|
- GBP post with service area map or offer
|
||||||
|
- Google Ads for relevant keywords
|
||||||
|
- Landing page with clear CTA (call, book, learn more)
|
||||||
|
- Social posts (if applicable)
|
||||||
|
|
||||||
**Actions:**
|
### Phase 4: Momentum Period (Weeks 2-6)
|
||||||
- Leak product details: screenshots, feature GIFs, demos
|
|
||||||
- Gather quantitative usage data and qualitative feedback
|
|
||||||
- Run user research with engaged users (incentivize with credits)
|
|
||||||
- Optionally run product/market fit survey to refine messaging
|
|
||||||
|
|
||||||
**Expansion options:**
|
**Goal**: Sustain engagement and conversions
|
||||||
- Option A: Throttle invites in batches (5-10% at a time)
|
|
||||||
- Option B: Invite all users at once under "early access" framing
|
|
||||||
|
|
||||||
**Goal:** Validate at scale and prepare for full launch.
|
**Actions**:
|
||||||
|
- Follow-up emails to list
|
||||||
|
- Continue paid ads
|
||||||
|
- Share customer results/testimonials
|
||||||
|
- Retargeting ads for website visitors
|
||||||
|
- Technician promotion continues
|
||||||
|
- Monitor conversion metrics
|
||||||
|
|
||||||
### Phase 5: Full Launch
|
**Timing**:
|
||||||
Open the floodgates.
|
- Day 7: Follow-up email to non-responders
|
||||||
|
- Day 14: Success story or offer reminder
|
||||||
|
- Day 21: Final push before offer expires
|
||||||
|
- Day 28: Post-campaign email
|
||||||
|
|
||||||
**Actions:**
|
### Phase 5: Long-Term Sustain (Ongoing)
|
||||||
- Open self-serve signups
|
|
||||||
- Start charging (if not already)
|
|
||||||
- Announce general availability across all channels
|
|
||||||
|
|
||||||
**Launch touchpoints:**
|
**Goal**: Normalize new service/area into business
|
||||||
- Customer emails
|
|
||||||
- In-app popups and product tours
|
|
||||||
- Website banner linking to launch assets
|
|
||||||
- "New" sticker in dashboard navigation
|
|
||||||
- Blog post announcement
|
|
||||||
- Social posts across platforms
|
|
||||||
- Product Hunt, BetaList, Hacker News, etc.
|
|
||||||
|
|
||||||
**Goal:** Maximum visibility and conversion to paying users.
|
**Actions**:
|
||||||
|
- Integrate into regular email campaigns
|
||||||
|
- Include in monthly GBP posts
|
||||||
|
- Update website permanently
|
||||||
|
- Measure impact on revenue and bookings
|
||||||
|
- Optimize based on performance
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Product Hunt Launch Strategy
|
## Seasonal Campaign Example: AC Season Launch
|
||||||
|
|
||||||
Product Hunt can be powerful for reaching early adopters, but it's not magic—it requires preparation.
|
**Kickoff**: April 1
|
||||||
|
|
||||||
### Pros
|
**Pre-launch (March 15-31)**:
|
||||||
- Exposure to tech-savvy early adopter audience
|
- Email: "AC Season is coming — get $50 off tune-ups booked in April"
|
||||||
- Credibility bump (especially if Product of the Day)
|
- GBP post: "Prepare your AC for summer. Schedule your tune-up now."
|
||||||
- Potential PR coverage and backlinks
|
- Website: "AC Season Special" banner above the fold
|
||||||
|
|
||||||
### Cons
|
**Launch Week (April 1-7)**:
|
||||||
- Very competitive to rank well
|
- Email blast to entire customer list
|
||||||
- Short-lived traffic spikes
|
- Google Ads targeting "AC tune-up near me," "HVAC near me"
|
||||||
- Requires significant pre-launch planning
|
- Facebook ads geotargeted to service area
|
||||||
|
- GBP featured ad (if budget allows)
|
||||||
|
- Technicians promote during every service call
|
||||||
|
- Landing page with offer and booking link
|
||||||
|
|
||||||
### How to Launch Successfully
|
**Momentum (April 8-May 31)**:
|
||||||
|
- Weekly GBP posts about AC tips, maintenance benefits
|
||||||
|
- Email to non-converters (Day 7, 14, 21)
|
||||||
|
- Continue paid ads through peak season
|
||||||
|
- Share customer testimonials
|
||||||
|
- Retargeting ads for website visitors
|
||||||
|
- Text messages to existing customers (if opted in)
|
||||||
|
|
||||||
**Before launch day:**
|
**Offer structure**:
|
||||||
1. Build relationships with influential supporters, content hubs, and communities
|
- "$50 off AC tune-up" (limited to April-May)
|
||||||
2. Optimize your listing: compelling tagline, polished visuals, short demo video
|
- Bundle offer: "Tune-up + filter + inspection: $149 (save $50)"
|
||||||
3. Study successful launches to identify what worked
|
- Maintenance agreement incentive: "Sign a 1-year agreement, get first tune-up free"
|
||||||
4. Engage in relevant communities—provide value before pitching
|
|
||||||
5. Prepare your team for all-day engagement
|
|
||||||
|
|
||||||
**On launch day:**
|
|
||||||
1. Treat it as an all-day event
|
|
||||||
2. Respond to every comment in real-time
|
|
||||||
3. Answer questions and spark discussions
|
|
||||||
4. Encourage your existing audience to engage
|
|
||||||
5. Direct traffic back to your site to capture signups
|
|
||||||
|
|
||||||
**After launch day:**
|
|
||||||
1. Follow up with everyone who engaged
|
|
||||||
2. Convert Product Hunt traffic into owned relationships (email signups)
|
|
||||||
3. Continue momentum with post-launch content
|
|
||||||
|
|
||||||
### Case Studies
|
|
||||||
|
|
||||||
**SavvyCal** (Scheduling tool):
|
|
||||||
- Optimized landing page and onboarding before launch
|
|
||||||
- Built relationships with productivity/SaaS influencers in advance
|
|
||||||
- Responded to every comment on launch day
|
|
||||||
- Result: #2 Product of the Month
|
|
||||||
|
|
||||||
**Reform** (Form builder):
|
|
||||||
- Studied successful launches and applied insights
|
|
||||||
- Crafted clear tagline, polished visuals, demo video
|
|
||||||
- Engaged in communities before launch (provided value first)
|
|
||||||
- Treated launch as all-day engagement event
|
|
||||||
- Directed traffic to capture signups
|
|
||||||
- Result: #1 Product of the Day
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Post-Launch Product Marketing
|
## New Service Area Launch Example: "Now Serving Oakland"
|
||||||
|
|
||||||
Your launch isn't over when the announcement goes live. Now comes adoption and retention work.
|
**Timeline**: 6 weeks before launch
|
||||||
|
|
||||||
### Immediate Post-Launch Actions
|
**Phase 1: Awareness (Weeks 1-2)**
|
||||||
|
- Email to existing customers: "We're expanding to Oakland — stay tuned"
|
||||||
|
- GBP post: "Coming soon to Oakland"
|
||||||
|
- Website update: "Expanding service areas"
|
||||||
|
|
||||||
**Educate new users:**
|
**Phase 2: Buzz (Weeks 3-4)**
|
||||||
Set up automated onboarding email sequence introducing key features and use cases.
|
- Details announced: "Official launch June 1 in Oakland"
|
||||||
|
- Email with offer: "First 50 Oakland customers: $100 off furnace service"
|
||||||
|
- Partner outreach: Contact contractors, real estate agents, property managers in Oakland
|
||||||
|
|
||||||
**Reinforce the launch:**
|
**Phase 3: Launch (Week 5-6)**
|
||||||
Include announcement in your weekly/biweekly/monthly roundup email to catch people who missed it.
|
- Google Ads go live for Oakland keywords ("HVAC Oakland," "furnace repair Oakland")
|
||||||
|
- Email: Launch announcement with booking link
|
||||||
|
- GBP post: "Now serving Oakland — here's how to book"
|
||||||
|
- Facebook ads: Geotargeted to Oakland zip codes
|
||||||
|
- Press release (local news, chamber of commerce)
|
||||||
|
- Partnerships: Co-op marketing with local contractors
|
||||||
|
|
||||||
**Differentiate against competitors:**
|
**Offer**:
|
||||||
Publish comparison pages highlighting why you're the obvious choice.
|
- "First 100 Oakland customers: $100 off service"
|
||||||
|
- Maintenance agreement discount: "3 months free (normally $79/month)"
|
||||||
|
|
||||||
**Update web pages:**
|
**Measurement**:
|
||||||
Add dedicated sections about the new feature/product across your site.
|
- Track number of Oakland bookings per week
|
||||||
|
- Monitor CAC (cost per acquisition) in new area
|
||||||
**Offer hands-on preview:**
|
- Compare to other service areas
|
||||||
Create no-code interactive demo (using tools like Navattic) so visitors can explore before signing up.
|
- Measure conversion rate from initial contact to booked job
|
||||||
|
|
||||||
### Keep Momentum Going
|
|
||||||
It's easier to build on existing momentum than start from scratch. Every touchpoint reinforces the launch.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Ongoing Launch Strategy
|
|
||||||
|
|
||||||
Don't rely on a single launch event. Regular updates and feature rollouts sustain engagement.
|
|
||||||
|
|
||||||
### How to Prioritize What to Announce
|
|
||||||
|
|
||||||
Use this matrix to decide how much marketing each update deserves:
|
|
||||||
|
|
||||||
**Major updates** (new features, product overhauls):
|
|
||||||
- Full campaign across multiple channels
|
|
||||||
- Blog post, email campaign, in-app messages, social media
|
|
||||||
- Maximize exposure
|
|
||||||
|
|
||||||
**Medium updates** (new integrations, UI enhancements):
|
|
||||||
- Targeted announcement
|
|
||||||
- Email to relevant segments, in-app banner
|
|
||||||
- Don't need full fanfare
|
|
||||||
|
|
||||||
**Minor updates** (bug fixes, small tweaks):
|
|
||||||
- Changelog and release notes
|
|
||||||
- Signal that product is improving
|
|
||||||
- Don't dominate marketing
|
|
||||||
|
|
||||||
### Announcement Tactics
|
|
||||||
|
|
||||||
**Space out releases:**
|
|
||||||
Instead of shipping everything at once, stagger announcements to maintain momentum.
|
|
||||||
|
|
||||||
**Reuse high-performing tactics:**
|
|
||||||
If a previous announcement resonated, apply those insights to future updates.
|
|
||||||
|
|
||||||
**Keep engaging:**
|
|
||||||
Continue using email, social, and in-app messaging to highlight improvements.
|
|
||||||
|
|
||||||
**Signal active development:**
|
|
||||||
Even small changelog updates remind customers your product is evolving. This builds retention and word-of-mouth—customers feel confident you'll be around.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Launch Checklist
|
## Launch Checklist
|
||||||
|
|
||||||
### Pre-Launch
|
### Pre-Launch (4-6 weeks before)
|
||||||
- [ ] Landing page with clear value proposition
|
- [ ] Define what's launching, target audience, key dates
|
||||||
- [ ] Email capture / waitlist signup
|
- [ ] Build landing page or campaign assets
|
||||||
- [ ] Early access list built
|
- [ ] Create email campaign (pre-launch, launch, follow-up sequence)
|
||||||
- [ ] Owned channels established (email, blog, community)
|
- [ ] Prepare GBP posts and social content
|
||||||
- [ ] Rented channel presence (social profiles optimized)
|
- [ ] Set up Google Ads campaign with relevant keywords
|
||||||
- [ ] Borrowed channel opportunities identified (podcasts, influencers)
|
- [ ] Brief sales team and technicians
|
||||||
- [ ] Product Hunt listing prepared (if using)
|
- [ ] Prepare offer (discount amount, validity period, redemption)
|
||||||
- [ ] Launch assets created (screenshots, demo video, GIFs)
|
- [ ] Set up analytics/tracking
|
||||||
- [ ] Onboarding flow ready
|
|
||||||
- [ ] Analytics/tracking in place
|
|
||||||
|
|
||||||
### Launch Day
|
### Launch Day/Week
|
||||||
- [ ] Announcement email to list
|
- [ ] Email to full customer list
|
||||||
- [ ] Blog post published
|
- [ ] GBP post announcement
|
||||||
- [ ] Social posts scheduled and posted
|
- [ ] Website banner and landing page live
|
||||||
- [ ] Product Hunt listing live (if using)
|
- [ ] Google Ads live
|
||||||
- [ ] In-app announcement for existing users
|
- [ ] Paid ads budget allocated
|
||||||
- [ ] Website banner/notification active
|
- [ ] Technician talking points active
|
||||||
- [ ] Team ready to engage and respond
|
- [ ] Monitor for technical issues (website, booking system, emails)
|
||||||
- [ ] Monitor for issues and feedback
|
- [ ] Respond to inquiries quickly
|
||||||
|
|
||||||
### Post-Launch
|
### Post-Launch
|
||||||
- [ ] Onboarding email sequence active
|
- [ ] Follow-up emails (Day 7, 14, 21)
|
||||||
- [ ] Follow-up with engaged prospects
|
- [ ] Track conversion metrics daily
|
||||||
- [ ] Roundup email includes announcement
|
- [ ] Optimize ads based on performance
|
||||||
- [ ] Comparison pages published
|
- [ ] Share successes/testimonials
|
||||||
- [ ] Interactive demo created
|
- [ ] Monitor offer redemption rate
|
||||||
- [ ] Gather and act on feedback
|
- [ ] Measure impact on revenue
|
||||||
- [ ] Plan next launch moment
|
- [ ] Gather team feedback
|
||||||
|
- [ ] Plan next launch
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What are you launching? (New product, major feature, minor update)
|
1. What are you launching? (Seasonal campaign, new service, new area, equipment line)
|
||||||
2. What's your current audience size and engagement?
|
2. When? (Launch date and season)
|
||||||
3. What owned channels do you have? (Email list size, blog traffic, community)
|
3. Who's the target customer? (Homeowners, commercial, contractors, distributors)
|
||||||
4. What's your timeline for launch?
|
4. What's the primary offer/incentive?
|
||||||
5. Have you launched before? What worked/didn't work?
|
5. What's your current audience size (email list, past customers)?
|
||||||
6. Are you considering Product Hunt? What's your preparation status?
|
6. What's the budget (paid ads, team time)?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to support launch planning:
|
||||||
|
|
||||||
|
- **Market research**: Analyze seasonal demand patterns, competitor campaigns
|
||||||
|
- **Customer data**: Identify high-intent customers for targeted launch emails
|
||||||
|
- **Performance analysis**: Measure launch impact on bookings and revenue
|
||||||
|
|
||||||
|
**Tool tiers**: Database queries, analysis
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **marketing-ideas**: For additional launch tactics (#22 Product Hunt, #23 Early Access Referrals)
|
- **marketing-ideas**: For additional launch tactics and ideas
|
||||||
- **email-sequence**: For launch and onboarding email sequences
|
- **email-sequence**: For launch and follow-up email sequences
|
||||||
- **page-cro**: For optimizing launch landing pages
|
- **marketing-psychology**: For psychology behind urgency and scarcity in launches
|
||||||
- **marketing-psychology**: For psychology behind waitlists and exclusivity
|
- **sales-enablement**: For launch sales training and team enablement
|
||||||
- **programmatic-seo**: For comparison pages mentioned in post-launch
|
- **pricing-strategy**: For launch offer design and pricing
|
||||||
- **sales-enablement**: For launch sales collateral and enablement materials
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "We're launching a new B2B SaaS product for design teams in 6 weeks. It's a design review tool. We have a small audience (500 email subscribers, 2k Twitter followers). Help us plan the launch.",
|
"prompt": "We're launching a new B2B SaaS product for design teams in 6 weeks. It's a design review tool. We have a small audience (500 email subscribers, 2k Twitter followers). Help us plan the launch.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the ORB Framework (Owned, Rented, Borrowed channels) with the user's specific resources. Owned: email list (500 subscribers), website. Rented: Twitter (2k followers). Borrowed: partnerships, communities, Product Hunt. Should recommend the five-phase launch approach with a timeline mapped to the 6-week window: Internal prep, Alpha (existing network), Beta (expanded), Early Access, Full Launch. Should provide specific tactics for each phase. Should recommend building up the audience before launch day. Should include a launch day checklist.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the ORB Framework (Owned, Rented, Borrowed channels) with the user's specific resources. Owned: email list (500 subscribers), website. Rented: Twitter (2k followers). Borrowed: partnerships, communities, Product Hunt. Should recommend the five-phase launch approach with a timeline mapped to the 6-week window: Internal prep, Alpha (existing network), Beta (expanded), Early Access, Full Launch. Should provide specific tactics for each phase. Should recommend building up the audience before launch day. Should include a launch day checklist.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies ORB Framework (Owned, Rented, Borrowed)",
|
"Applies ORB Framework (Owned, Rented, Borrowed)",
|
||||||
"Maps to user's specific channels and audience sizes",
|
"Maps to user's specific channels and audience sizes",
|
||||||
"Recommends five-phase launch approach",
|
"Recommends five-phase launch approach",
|
||||||
|
|
|
||||||
|
|
@ -1,21 +1,24 @@
|
||||||
---
|
---
|
||||||
name: marketing-ideas
|
name: marketing-ideas
|
||||||
description: "When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow. For specific channel execution, see the relevant skill (paid-ads, social-content, email-sequence, etc.)."
|
description: "When the user needs marketing ideas, inspiration, or strategies for HVAC contractors, distributors, or equipment manufacturers. Also use when the user asks for 'marketing ideas,' 'growth ideas,' 'how to market,' 'marketing strategies,' 'marketing tactics,' 'ways to promote,' 'ideas to grow,' 'what else can I try,' 'I don't know how to market this,' 'brainstorm marketing,' or 'what marketing should I do.' Use this as a starting point whenever someone is stuck or looking for inspiration on how to grow the HVAC business. For specific channel execution, see the relevant skill (social-content, email-sequence, etc.)."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Marketing Ideas for SaaS
|
# Marketing Ideas for HVAC
|
||||||
|
|
||||||
You are a marketing strategist with a library of 139 proven marketing ideas. Your goal is to help users find the right marketing strategies for their specific situation, stage, and resources.
|
You are a marketing strategist specialized in HVAC, with a library of proven tactics for contractors, distributors, and equipment manufacturers. Your goal is to help users find the right marketing strategies for their specific situation, stage, and resources.
|
||||||
|
|
||||||
## How to Use This Skill
|
## How to Use This Skill
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
When asked for marketing ideas:
|
When asked for marketing ideas:
|
||||||
1. Ask about their product, audience, and current stage if not clear
|
1. Ask about their business, audience, and current stage if not clear
|
||||||
2. Suggest 3-5 most relevant ideas based on their context
|
2. Suggest 3-5 most relevant ideas based on their context
|
||||||
3. Provide details on implementation for chosen ideas
|
3. Provide details on implementation for chosen ideas
|
||||||
4. Consider their resources (time, budget, team size)
|
4. Consider their resources (time, budget, team size)
|
||||||
|
|
@ -24,27 +27,20 @@ When asked for marketing ideas:
|
||||||
|
|
||||||
## Ideas by Category (Quick Reference)
|
## Ideas by Category (Quick Reference)
|
||||||
|
|
||||||
| Category | Ideas | Examples |
|
| Category | Tactics |
|
||||||
|----------|-------|----------|
|
|----------|---------|
|
||||||
| Content & SEO | 1-10 | Programmatic SEO, Glossary marketing, Content repurposing |
|
| **Local & Geographic** | Geo-targeted ads, local events, contractor networks, service area domination |
|
||||||
| Competitor | 11-13 | Comparison pages, Marketing jiu-jitsu |
|
| **Trade & B2B** | Trade shows, distributor partnerships, HVAC associations, contractor co-ops |
|
||||||
| Free Tools | 14-22 | Calculators, Generators, Chrome extensions |
|
| **Review & Reputation** | Google reviews/GBP, Yelp, Angi (Angie's List), residential review sites |
|
||||||
| Paid Ads | 23-34 | LinkedIn, Google, Retargeting, Podcast ads |
|
| **Social & Community** | LinkedIn for commercial, Facebook for residential, contractor communities, TikTok DIY |
|
||||||
| Social & Community | 35-44 | LinkedIn audience, Reddit marketing, Short-form video |
|
| **Seasonal Campaigns** | AC season (May-Aug), heating season (Sep-Mar), maintenance programs, emergency dispatch |
|
||||||
| Email | 45-53 | Founder emails, Onboarding sequences, Win-back |
|
| **Content & SEO** | Service guides, equipment explainers, how-to videos, maintenance tips, landing pages |
|
||||||
| Partnerships | 54-64 | Affiliate programs, Integration marketing, Newsletter swaps |
|
| **Paid Ads** | Google Ads for "HVAC near me," Facebook/Instagram geotargeted, YouTube contractor tutorials |
|
||||||
| Events | 65-72 | Webinars, Conference speaking, Virtual summits |
|
| **Partnerships** | Real estate agents, property managers, builders, plumbers, electricians |
|
||||||
| PR & Media | 73-76 | Press coverage, Documentaries |
|
| **Direct Outreach** | Door-to-door for maintenance, contractor referral programs, distributor incentives |
|
||||||
| Launches | 77-86 | Product Hunt, Lifetime deals, Giveaways |
|
| **Loyalty & Retention** | Maintenance agreements, seasonal tune-ups, referral rewards, VIP programs |
|
||||||
| Product-Led | 87-96 | Viral loops, Powered-by marketing, Free migrations |
|
| **Free Tools & Resources** | Load calculators, energy savings estimators, ROI calculators, maintenance checklists |
|
||||||
| Content Formats | 97-109 | Podcasts, Courses, Annual reports, Year wraps |
|
| **Events** | Webinars for contractors, in-home seminars, contractor conferences, workshop tours |
|
||||||
| Unconventional | 110-122 | Awards, Challenges, Guerrilla marketing |
|
|
||||||
| Platforms | 123-130 | App marketplaces, Review sites, YouTube |
|
|
||||||
| International | 131-132 | Expansion, Price localization |
|
|
||||||
| Developer | 133-136 | DevRel, Certifications |
|
|
||||||
| Audience-Specific | 137-139 | Referrals, Podcast tours, Customer language |
|
|
||||||
|
|
||||||
**For the complete list with descriptions**: See [references/ideas-by-category.md](references/ideas-by-category.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -52,88 +48,97 @@ When asked for marketing ideas:
|
||||||
|
|
||||||
### By Stage
|
### By Stage
|
||||||
|
|
||||||
**Pre-launch:**
|
**Pre-service launch:**
|
||||||
- Waitlist referrals (#79)
|
- Geo-targeting setup for service area
|
||||||
- Early access pricing (#81)
|
- Local business directory listings (GBP, Yelp, Angi)
|
||||||
- Product Hunt prep (#78)
|
- Contractor partnership outreach
|
||||||
|
|
||||||
**Early stage:**
|
**Early traction:**
|
||||||
- Content & SEO (#1-10)
|
- Local Google Ads and review generation
|
||||||
- Community (#35)
|
- Referral program launch
|
||||||
- Founder-led sales (#47)
|
- Content & SEO for local keywords
|
||||||
|
|
||||||
**Growth stage:**
|
**Growth:**
|
||||||
- Paid acquisition (#23-34)
|
- Paid acquisition scaling (search + social)
|
||||||
- Partnerships (#54-64)
|
- Partnerships (real estate, property management)
|
||||||
- Events (#65-72)
|
- Maintenance agreements at scale
|
||||||
|
|
||||||
**Scale:**
|
**Scale:**
|
||||||
- Brand campaigns
|
- Brand campaigns in market
|
||||||
- International (#131-132)
|
- Multiple service area expansion
|
||||||
- Media acquisitions (#73)
|
- Distributor network expansion
|
||||||
|
|
||||||
### By Budget
|
### By Budget
|
||||||
|
|
||||||
**Free:**
|
**Free:**
|
||||||
- Content & SEO
|
- Google Business Profile optimization
|
||||||
- Community building
|
- Review generation campaigns
|
||||||
- Social media
|
- Social media (organic)
|
||||||
- Comment marketing
|
- Contractor networking
|
||||||
|
|
||||||
**Low budget:**
|
**Low budget:**
|
||||||
- Targeted ads
|
- Geo-targeted Google Ads
|
||||||
- Sponsorships
|
- Facebook/Instagram ads by zip code
|
||||||
- Free tools
|
- Local partnerships
|
||||||
|
- Referral incentives
|
||||||
|
|
||||||
**Medium budget:**
|
**Medium budget:**
|
||||||
- Events
|
- Paid ads across channels
|
||||||
- Partnerships
|
- Content creation (videos, guides)
|
||||||
- PR
|
- Events and sponsorships
|
||||||
|
- Distributor programs
|
||||||
|
|
||||||
**High budget:**
|
**High budget:**
|
||||||
- Acquisitions
|
|
||||||
- Conferences
|
|
||||||
- Brand campaigns
|
- Brand campaigns
|
||||||
|
- Expansion to new markets
|
||||||
|
- Free tool development
|
||||||
|
- Large-scale events and partnerships
|
||||||
|
|
||||||
### By Timeline
|
### By Timeline
|
||||||
|
|
||||||
**Quick wins:**
|
**Quick wins:**
|
||||||
- Ads, email, social posts
|
- GBP optimization, review generation
|
||||||
|
- Google Ads launch
|
||||||
|
|
||||||
**Medium-term:**
|
**Medium-term:**
|
||||||
- Content, SEO, community
|
- Content creation, SEO, referral program
|
||||||
|
|
||||||
**Long-term:**
|
**Long-term:**
|
||||||
- Brand, thought leadership, platform effects
|
- Brand building, partnerships, market expansion
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Top Ideas by Use Case
|
## Top Ideas by Use Case
|
||||||
|
|
||||||
### Need Leads Fast
|
### Need Leads Fast (Residential)
|
||||||
- Google Ads (#31) - High-intent search
|
- Google Ads for emergency/repair keywords ("HVAC near me," "furnace repair") — high-intent search
|
||||||
- LinkedIn Ads (#28) - B2B targeting
|
- Facebook/Instagram geotargeted ads — local reach
|
||||||
- Engineering as Marketing (#15) - Free tool lead gen
|
- Review generation campaign — social proof drives calls
|
||||||
|
|
||||||
|
### Need Commercial/Contractor Leads
|
||||||
|
- LinkedIn B2B targeting for property managers and facility managers
|
||||||
|
- Trade show presence and networking
|
||||||
|
- Distributor co-op programs
|
||||||
|
|
||||||
### Building Authority
|
### Building Authority
|
||||||
- Conference Speaking (#70)
|
- YouTube contractor tutorials and equipment reviews
|
||||||
- Book Marketing (#104)
|
- HVAC blog with service guides
|
||||||
- Podcasts (#107)
|
- Speaking at contractor associations
|
||||||
|
|
||||||
### Low Budget Growth
|
### Low Budget Growth
|
||||||
- Easy Keyword Ranking (#1)
|
- GBP optimization (free, high ROI)
|
||||||
- Reddit Marketing (#38)
|
- Reddit and contractor forums
|
||||||
- Comment Marketing (#44)
|
- Referral program for existing customers
|
||||||
|
|
||||||
### Product-Led Growth
|
### Seasonal Demand Capture
|
||||||
- Viral Loops (#93)
|
- Pre-AC-season preparation campaign (April-May)
|
||||||
- Powered By Marketing (#87)
|
- Pre-heating season campaign (August-September)
|
||||||
- In-App Upsells (#91)
|
- Emergency dispatch promotion during peak seasons
|
||||||
|
|
||||||
### Enterprise Sales
|
### Homeowner Retention
|
||||||
- Investor Marketing (#133)
|
- Maintenance agreement programs
|
||||||
- Expert Networks (#57)
|
- Seasonal tune-up reminders
|
||||||
- Conference Sponsorship (#72)
|
- Email campaigns to past customers
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -151,17 +156,31 @@ When recommending ideas, provide for each:
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What's your current stage and main growth goal?
|
1. What's your business type (residential contractor, distributor, equipment manufacturer)?
|
||||||
2. What's your marketing budget and team size?
|
2. What's your main growth goal (more leads, bigger jobs, contractor partnerships)?
|
||||||
3. What have you already tried that worked or didn't?
|
3. What's your marketing budget and team size?
|
||||||
4. What competitor tactics do you admire?
|
4. What have you already tried that worked or didn't?
|
||||||
|
5. Are you local, multi-market, or national?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use the Compendium intelligence platform to support HVAC marketing ideas:
|
||||||
|
|
||||||
|
- **Market intelligence**: 1,400+ HVAC industry statistics available via `intelligence.statistics`
|
||||||
|
- **Competitor analysis**: Search and analyze competitor tactics via search tools
|
||||||
|
- **Seasonal demand data**: Historical trends in AC/heating seasonality
|
||||||
|
- **Local contractor data**: GBP and review site scraping for local market insights
|
||||||
|
|
||||||
|
**Tool tiers**: Search, database queries, analysis
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **programmatic-seo**: For scaling SEO content (#4)
|
- **free-tool-strategy**: For building HVAC calculators and tools
|
||||||
- **competitor-alternatives**: For comparison pages (#11)
|
- **pricing-strategy**: For maintenance agreement and service pricing
|
||||||
- **email-sequence**: For email marketing tactics
|
- **sales-enablement**: For contractor proposals and equipment specs
|
||||||
- **free-tool-strategy**: For engineering as marketing (#15)
|
- **hvac-lead-ops**: For lead management and contractor intake-to-job funnel
|
||||||
- **referral-program**: For viral growth (#93)
|
- **hvac-estimate-popups**: For on-site estimate request popups
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "I need marketing ideas for my SaaS product. We're a bootstrapped team of 3, sell a $49/month analytics tool for e-commerce, and have about 200 customers. Budget is tight — maybe $500/month for marketing.",
|
"prompt": "I need marketing ideas for my SaaS product. We're a bootstrapped team of 3, sell a $49/month analytics tool for e-commerce, and have about 200 customers. Budget is tight — maybe $500/month for marketing.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should filter ideas by low budget and early-stage constraints. Should pull relevant ideas from the 139 marketing ideas organized by category. Should provide ideas appropriate for bootstrapped SaaS: content marketing, community building, SEO, partnerships, referral programs, social media, Product Hunt, and others that don't require large budgets. Output should follow the format: idea name, why it fits, how to start, expected outcome, resources needed. Should prioritize by likely impact given their stage.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should filter ideas by low budget and early-stage constraints. Should pull relevant ideas from the 139 marketing ideas organized by category. Should provide ideas appropriate for bootstrapped SaaS: content marketing, community building, SEO, partnerships, referral programs, social media, Product Hunt, and others that don't require large budgets. Output should follow the format: idea name, why it fits, how to start, expected outcome, resources needed. Should prioritize by likely impact given their stage.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Filters ideas by low budget constraint",
|
"Filters ideas by low budget constraint",
|
||||||
"Provides ideas from the 139 marketing ideas catalog",
|
"Provides ideas from the 139 marketing ideas catalog",
|
||||||
"Ideas are appropriate for bootstrapped SaaS stage",
|
"Ideas are appropriate for bootstrapped SaaS stage",
|
||||||
|
|
|
||||||
|
|
@ -1,18 +1,21 @@
|
||||||
---
|
---
|
||||||
name: marketing-psychology
|
name: marketing-psychology
|
||||||
description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' 'consumer behavior,' 'anchoring,' 'social proof,' 'scarcity,' 'loss aversion,' 'framing,' or 'nudge.' Use this whenever someone wants to understand or leverage how people think and make decisions in a marketing context."
|
description: "When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when the user mentions 'psychology,' 'mental models,' 'cognitive bias,' 'persuasion,' 'behavioral science,' 'why people buy,' 'decision-making,' 'consumer behavior,' 'anchoring,' 'social proof,' 'scarcity,' 'loss aversion,' 'framing,' 'urgency,' or 'nudge.' Use this whenever someone wants to understand or leverage how people think and make decisions in a marketing context."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: standalone
|
||||||
|
tools: []
|
||||||
---
|
---
|
||||||
|
|
||||||
# Marketing Psychology & Mental Models
|
# Marketing Psychology & Mental Models
|
||||||
|
|
||||||
You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions.
|
You are an expert in applying psychological principles and mental models to marketing. Your goal is to help users understand why people buy, how to influence behavior ethically, and how to make better marketing decisions — especially in the HVAC industry where purchase decisions involve urgency, trust, and significant investment.
|
||||||
|
|
||||||
## How to Use This Skill
|
## How to Use This Skill
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before applying mental models. Use that context to tailor recommendations to the specific product and audience.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before applying mental models. Use that context to tailor recommendations to the specific product and audience.
|
||||||
|
|
||||||
Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users:
|
Mental models are thinking tools that help you make better decisions, understand customer behavior, and create more effective marketing. When helping users:
|
||||||
|
|
||||||
|
|
@ -28,190 +31,120 @@ Mental models are thinking tools that help you make better decisions, understand
|
||||||
These models sharpen your strategy and help you solve the right problems.
|
These models sharpen your strategy and help you solve the right problems.
|
||||||
|
|
||||||
### First Principles
|
### First Principles
|
||||||
Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes. Use the 5 Whys technique to tunnel down to what really matters.
|
Break problems down to basic truths and build solutions from there. Instead of copying competitors, ask "why" repeatedly to find root causes.
|
||||||
|
|
||||||
**Marketing application**: Don't assume you need content marketing because competitors do. Ask why you need it, what problem it solves, and whether there's a better solution.
|
**Marketing application**: Don't assume you need TV ads because competitors do. Ask why customers choose you or a competitor. Seek the fundamental reason someone calls for a furnace repair.
|
||||||
|
|
||||||
### Jobs to Be Done
|
### Jobs to Be Done
|
||||||
People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
|
People don't buy products—they "hire" them to get a job done. Focus on the outcome customers want, not features.
|
||||||
|
|
||||||
**Marketing application**: A drill buyer doesn't want a drill—they want a hole. Frame your product around the job it accomplishes, not its specifications.
|
**HVAC application**: A homeowner doesn't want an air conditioner—they want comfortable summers and peace of mind. A facility manager doesn't want a boiler—they want reliable heating for their building.
|
||||||
|
|
||||||
### Circle of Competence
|
### Circle of Competence
|
||||||
Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
|
Know what you're good at and stay within it. Venture outside only with proper learning or expert help.
|
||||||
|
|
||||||
**Marketing application**: Don't chase every channel. Double down where you have genuine expertise and competitive advantage.
|
**HVAC application**: A plumber expanding into HVAC should understand the gaps in their expertise. A residential contractor moving to commercial needs new certifications and knowledge.
|
||||||
|
|
||||||
### Inversion
|
### Inversion
|
||||||
Instead of asking "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
|
Instead of "How do I succeed?", ask "What would guarantee failure?" Then avoid those things.
|
||||||
|
|
||||||
**Marketing application**: List everything that would make your campaign fail—confusing messaging, wrong audience, slow landing page—then systematically prevent each.
|
**HVAC application**: List what would lose a customer: slow response, rude technician, hidden fees, not showing up on time. Then systematically prevent each.
|
||||||
|
|
||||||
### Occam's Razor
|
### Occam's Razor
|
||||||
The simplest explanation is usually correct. Avoid overcomplicating strategies or attributing results to complex causes when simple ones suffice.
|
The simplest explanation is usually correct. Avoid overcomplicating strategies.
|
||||||
|
|
||||||
**Marketing application**: If conversions dropped, check the obvious first (broken form, page speed) before assuming complex attribution issues.
|
**HVAC application**: If AC service calls are down, check the obvious first—website down? Phone line broken? Slow Google Ads response? Before assuming complex attribution issues.
|
||||||
|
|
||||||
### Pareto Principle (80/20 Rule)
|
### Pareto Principle (80/20 Rule)
|
||||||
Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
|
Roughly 80% of results come from 20% of efforts. Identify and focus on the vital few.
|
||||||
|
|
||||||
**Marketing application**: Find the 20% of channels, customers, or content driving 80% of results. Cut or reduce the rest.
|
**HVAC application**: 80% of revenue might come from 20% of customers (maintenance agreements, large commercial). Focus there.
|
||||||
|
|
||||||
### Local vs. Global Optima
|
### Local vs. Global Optima
|
||||||
A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
|
A local optimum is the best solution nearby, but a global optimum is the best overall. Don't get stuck optimizing the wrong thing.
|
||||||
|
|
||||||
**Marketing application**: Optimizing email subject lines (local) won't help if email isn't the right channel (global). Zoom out before zooming in.
|
**HVAC application**: Perfecting the estimate form (local) won't help if you're not getting phone calls (global). Fix lead generation first.
|
||||||
|
|
||||||
### Theory of Constraints
|
### Theory of Constraints
|
||||||
Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
|
Every system has one bottleneck limiting throughput. Find and fix that constraint before optimizing elsewhere.
|
||||||
|
|
||||||
**Marketing application**: If your funnel converts well but traffic is low, more conversion optimization won't help. Fix the traffic bottleneck first.
|
**HVAC application**: If your funnel is: leads → dispatch → estimate → booked job — find the stage where most deals drop, then fix that.
|
||||||
|
|
||||||
### Opportunity Cost
|
|
||||||
Every choice has a cost—what you give up by not choosing alternatives. Consider what you're saying no to.
|
|
||||||
|
|
||||||
**Marketing application**: Time spent on a low-ROI channel is time not spent on high-ROI activities. Always compare against alternatives.
|
|
||||||
|
|
||||||
### Law of Diminishing Returns
|
|
||||||
After a point, additional investment yields progressively smaller gains.
|
|
||||||
|
|
||||||
**Marketing application**: The 10th blog post won't have the same impact as the first. Know when to diversify rather than double down.
|
|
||||||
|
|
||||||
### Second-Order Thinking
|
|
||||||
Consider not just immediate effects, but the effects of those effects.
|
|
||||||
|
|
||||||
**Marketing application**: A flash sale boosts revenue (first order) but may train customers to wait for discounts (second order).
|
|
||||||
|
|
||||||
### Map ≠ Territory
|
|
||||||
Models and data represent reality but aren't reality itself. Don't confuse your analytics dashboard with actual customer experience.
|
|
||||||
|
|
||||||
**Marketing application**: Your customer persona is a useful model, but real customers are more complex. Stay in touch with actual users.
|
|
||||||
|
|
||||||
### Probabilistic Thinking
|
|
||||||
Think in probabilities, not certainties. Estimate likelihoods and plan for multiple outcomes.
|
|
||||||
|
|
||||||
**Marketing application**: Don't bet everything on one campaign. Spread risk and plan for scenarios where your primary strategy underperforms.
|
|
||||||
|
|
||||||
### Barbell Strategy
|
|
||||||
Combine extreme safety with small high-risk/high-reward bets. Avoid the mediocre middle.
|
|
||||||
|
|
||||||
**Marketing application**: Put 80% of budget into proven channels, 20% into experimental bets. Avoid moderate-risk, moderate-reward middle.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Understanding Buyers & Human Psychology
|
## Understanding Buyers & Human Psychology
|
||||||
|
|
||||||
These models explain how customers think, decide, and behave.
|
These models explain how customers think, decide, and behave — especially relevant in high-stakes decisions like HVAC.
|
||||||
|
|
||||||
### Fundamental Attribution Error
|
### Fundamental Attribution Error
|
||||||
People attribute others' behavior to character, not circumstances. "They didn't buy because they're not serious" vs. "The checkout was confusing."
|
People attribute others' behavior to character, not circumstances.
|
||||||
|
|
||||||
**Marketing application**: When customers don't convert, examine your process before blaming them. The problem is usually situational, not personal.
|
**HVAC application**: When a homeowner doesn't schedule a maintenance call, don't assume laziness. They might have cash flow issues, forgetfulness, or a broken scheduling system. Solve the situational problem, not the character judgment.
|
||||||
|
|
||||||
### Mere Exposure Effect
|
### Mere Exposure Effect
|
||||||
People prefer things they've seen before. Familiarity breeds liking.
|
People prefer things they've seen before. Familiarity breeds liking.
|
||||||
|
|
||||||
**Marketing application**: Consistent brand presence builds preference over time. Repetition across channels creates comfort and trust.
|
**HVAC application**: Consistent presence in neighborhood (signage, repeat service, reviews) builds preference. A contractor with 50 local reviews is more trusted than a stranger.
|
||||||
|
|
||||||
### Availability Heuristic
|
### Availability Heuristic
|
||||||
People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
|
People judge likelihood by how easily examples come to mind. Recent or vivid events seem more common.
|
||||||
|
|
||||||
**Marketing application**: Case studies and testimonials make success feel more achievable. Make positive outcomes easy to imagine.
|
**HVAC application**: After a neighbor's furnace failure, homeowners are more likely to schedule maintenance. Reference stories make problems feel urgent.
|
||||||
|
|
||||||
### Confirmation Bias
|
### Confirmation Bias
|
||||||
People seek information confirming existing beliefs and ignore contradictory evidence.
|
People seek information confirming existing beliefs and ignore contradictory evidence.
|
||||||
|
|
||||||
**Marketing application**: Understand what your audience already believes and align messaging accordingly. Fighting beliefs head-on rarely works.
|
**HVAC application**: If someone believes "my current system works fine," they'll ignore efficiency warnings. Frame in terms of existing beliefs: "Save on winter heating costs" vs. "Your system is old."
|
||||||
|
|
||||||
### The Lindy Effect
|
|
||||||
The longer something has survived, the longer it's likely to continue. Old ideas often outlast new ones.
|
|
||||||
|
|
||||||
**Marketing application**: Proven marketing principles (clear value props, social proof) outlast trendy tactics. Don't abandon fundamentals for fads.
|
|
||||||
|
|
||||||
### Mimetic Desire
|
### Mimetic Desire
|
||||||
People want things because others want them. Desire is socially contagious.
|
People want things because others want them. Desire is socially contagious.
|
||||||
|
|
||||||
**Marketing application**: Show that desirable people want your product. Waitlists, exclusivity, and social proof trigger mimetic desire.
|
**HVAC application**: When neighbors upgrade to a new AC system, others follow. Social proof (neighborhood maps, review counts) trigger desire.
|
||||||
|
|
||||||
|
### Loss Aversion / Prospect Theory
|
||||||
|
Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
|
||||||
|
|
||||||
|
**HVAC application**: Frame in terms of what they'll lose by not acting. "Your aging furnace could fail this winter" > "A new furnace will save money." Loss of comfort/safety is urgent.
|
||||||
|
|
||||||
|
### Scarcity / Urgency Heuristic
|
||||||
|
Limited availability increases perceived value. Scarcity signals desirability.
|
||||||
|
|
||||||
|
**HVAC application**: "We have 2 slots available this week" creates urgency. Seasonal scheduling (spring AC install rush) is naturally scarce.
|
||||||
|
|
||||||
### Sunk Cost Fallacy
|
### Sunk Cost Fallacy
|
||||||
People continue investing in something because of past investment, even when it's no longer rational.
|
People continue investing in something because of past investment, even when irrational.
|
||||||
|
|
||||||
**Marketing application**: Know when to kill underperforming campaigns. Past spend shouldn't justify future spend if results aren't there.
|
**HVAC application**: Know when to kill underperforming ad campaigns. Past spend on failed ads shouldn't justify future spend if results aren't there.
|
||||||
|
|
||||||
### Endowment Effect
|
### Endowment Effect
|
||||||
People value things more once they own them.
|
People value things more once they own them.
|
||||||
|
|
||||||
**Marketing application**: Free trials, samples, and freemium models let customers "own" the product, making them reluctant to give it up.
|
**HVAC application**: Free maintenance inspections let homeowners "own" the experience. They're more reluctant to switch after tasting your service.
|
||||||
|
|
||||||
### IKEA Effect
|
|
||||||
People value things more when they've put effort into creating them.
|
|
||||||
|
|
||||||
**Marketing application**: Let customers customize, configure, or build something. Their investment increases perceived value and commitment.
|
|
||||||
|
|
||||||
### Zero-Price Effect
|
### Zero-Price Effect
|
||||||
Free isn't just a low price—it's psychologically different. "Free" triggers irrational preference.
|
Free isn't just a low price—it's psychologically different.
|
||||||
|
|
||||||
**Marketing application**: Free tiers, free trials, and free shipping have disproportionate appeal. The jump from $1 to $0 is bigger than $2 to $1.
|
**HVAC application**: "Free 29-point inspection" has disproportionate appeal. "Inspection $99" won't generate the same response.
|
||||||
|
|
||||||
### Hyperbolic Discounting / Present Bias
|
### Hyperbolic Discounting / Present Bias
|
||||||
People strongly prefer immediate rewards over future ones, even when waiting is more rational.
|
People strongly prefer immediate rewards over future ones, even when waiting is more rational.
|
||||||
|
|
||||||
**Marketing application**: Emphasize immediate benefits ("Start saving time today") over future ones ("You'll see ROI in 6 months").
|
**HVAC application**: Emphasize immediate comfort restoration ("We'll have your heat fixed today") over future savings ("Save $500 this winter").
|
||||||
|
|
||||||
### Status-Quo Bias
|
### Status-Quo Bias
|
||||||
People prefer the current state of affairs. Change requires effort and feels risky.
|
People prefer the current state of affairs. Change requires effort and feels risky.
|
||||||
|
|
||||||
**Marketing application**: Reduce friction to switch. Make the transition feel safe and easy. "Import your data in one click."
|
**HVAC application**: Reduce friction to switch. "We'll handle the paperwork and coordinate installation" makes new systems easier to adopt.
|
||||||
|
|
||||||
### Default Effect
|
|
||||||
People tend to accept pre-selected options. Defaults are powerful.
|
|
||||||
|
|
||||||
**Marketing application**: Pre-select the plan you want customers to choose. Opt-out beats opt-in for subscriptions (ethically applied).
|
|
||||||
|
|
||||||
### Paradox of Choice
|
|
||||||
Too many options overwhelm and paralyze. Fewer choices often lead to more decisions.
|
|
||||||
|
|
||||||
**Marketing application**: Limit options. Three pricing tiers beat seven. Recommend a single "best for most" option.
|
|
||||||
|
|
||||||
### Goal-Gradient Effect
|
### Goal-Gradient Effect
|
||||||
People accelerate effort as they approach a goal. Progress visualization motivates action.
|
People accelerate effort as they approach a goal. Progress visualization motivates action.
|
||||||
|
|
||||||
**Marketing application**: Show progress bars, completion percentages, and "almost there" messaging to drive completion.
|
**HVAC application**: "You're 80% scheduled—complete your spring maintenance today" leverages progress momentum.
|
||||||
|
|
||||||
### Peak-End Rule
|
### Peak-End Rule
|
||||||
People judge experiences by the peak (best or worst moment) and the end, not the average.
|
People judge experiences by the peak moment and the end, not the average.
|
||||||
|
|
||||||
**Marketing application**: Design memorable peaks (surprise upgrades, delightful moments) and strong endings (thank you pages, follow-up emails).
|
**HVAC application**: Design memorable peaks (technician courtesy, surprise efficiency upgrade) and strong endings (thank-you note, follow-up call).
|
||||||
|
|
||||||
### Zeigarnik Effect
|
|
||||||
Unfinished tasks occupy the mind more than completed ones. Open loops create tension.
|
|
||||||
|
|
||||||
**Marketing application**: "You're 80% done" creates pull to finish. Incomplete profiles, abandoned carts, and cliffhangers leverage this.
|
|
||||||
|
|
||||||
### Pratfall Effect
|
|
||||||
Competent people become more likable when they show a small flaw. Perfection is less relatable.
|
|
||||||
|
|
||||||
**Marketing application**: Admitting a weakness ("We're not the cheapest, but...") can increase trust and differentiation.
|
|
||||||
|
|
||||||
### Curse of Knowledge
|
|
||||||
Once you know something, you can't imagine not knowing it. Experts struggle to explain simply.
|
|
||||||
|
|
||||||
**Marketing application**: Your product seems obvious to you but confusing to newcomers. Test copy with people unfamiliar with your space.
|
|
||||||
|
|
||||||
### Mental Accounting
|
|
||||||
People treat money differently based on its source or intended use, even though money is fungible.
|
|
||||||
|
|
||||||
**Marketing application**: Frame costs in favorable mental accounts. "$3/day" feels different than "$90/month" even though it's the same.
|
|
||||||
|
|
||||||
### Regret Aversion
|
|
||||||
People avoid actions that might cause regret, even if the expected outcome is positive.
|
|
||||||
|
|
||||||
**Marketing application**: Address regret directly. Money-back guarantees, free trials, and "no commitment" messaging reduce regret fear.
|
|
||||||
|
|
||||||
### Bandwagon Effect / Social Proof
|
|
||||||
People follow what others are doing. Popularity signals quality and safety.
|
|
||||||
|
|
||||||
**Marketing application**: Show customer counts, testimonials, logos, reviews, and "trending" indicators. Numbers create confidence.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -222,223 +155,100 @@ These models help you ethically influence customer decisions.
|
||||||
### Reciprocity Principle
|
### Reciprocity Principle
|
||||||
People feel obligated to return favors. Give first, and people want to give back.
|
People feel obligated to return favors. Give first, and people want to give back.
|
||||||
|
|
||||||
**Marketing application**: Free content, free tools, and generous free tiers create reciprocal obligation. Give value before asking for anything.
|
**HVAC application**: Free maintenance tips, energy-saving guides, and honest assessments create reciprocal obligation. They're more likely to call you when they need a furnace.
|
||||||
|
|
||||||
### Commitment & Consistency
|
### Commitment & Consistency
|
||||||
Once people commit to something, they want to stay consistent with that commitment.
|
Once people commit to something, they want to stay consistent with that commitment.
|
||||||
|
|
||||||
**Marketing application**: Get small commitments first (email signup, free trial). People who've taken one step are more likely to take the next.
|
**HVAC application**: Get small commitments first (sign up for maintenance reminders, schedule a free inspection). People who take one step are more likely to take the next (book a service, buy a new system).
|
||||||
|
|
||||||
### Authority Bias
|
### Authority Bias
|
||||||
People defer to experts and authority figures. Credentials and expertise create trust.
|
People defer to experts and authority figures. Credentials and expertise create trust.
|
||||||
|
|
||||||
**Marketing application**: Feature expert endorsements, certifications, "featured in" logos, and thought leadership content.
|
**HVAC application**: Feature certifications (EPA, EPA-approved refrigerant training, manufacturer certifications), awards, and thought leadership content. "Certified by EPA" beats no credential.
|
||||||
|
|
||||||
### Liking / Similarity Bias
|
### Liking / Similarity Bias
|
||||||
People say yes to those they like and those similar to themselves.
|
People say yes to those they like and those similar to themselves.
|
||||||
|
|
||||||
**Marketing application**: Use relatable spokespeople, founder stories, and community language. "Built by marketers for marketers" signals similarity.
|
**HVAC application**: Use relatable spokespeople (local technicians as faces of the company), founder stories from HVAC backgrounds. "Built by contractors for contractors" signals similarity.
|
||||||
|
|
||||||
### Unity Principle
|
### Unity Principle
|
||||||
Shared identity drives influence. "One of us" is powerful.
|
Shared identity drives influence. "One of us" is powerful.
|
||||||
|
|
||||||
**Marketing application**: Position your brand as part of the customer's tribe. Use insider language and shared values.
|
**HVAC application**: Position your brand as part of the homeowner's or contractor's tribe. Use insider language, share local roots, celebrate the community you serve.
|
||||||
|
|
||||||
### Scarcity / Urgency Heuristic
|
|
||||||
Limited availability increases perceived value. Scarcity signals desirability.
|
|
||||||
|
|
||||||
**Marketing application**: Limited-time offers, low-stock warnings, and exclusive access create urgency. Only use when genuine.
|
|
||||||
|
|
||||||
### Foot-in-the-Door Technique
|
|
||||||
Start with a small request, then escalate. Compliance with small requests leads to compliance with larger ones.
|
|
||||||
|
|
||||||
**Marketing application**: Free trial → paid plan → annual plan → enterprise. Each step builds on the last.
|
|
||||||
|
|
||||||
### Door-in-the-Face Technique
|
|
||||||
Start with an unreasonably large request, then retreat to what you actually want. The contrast makes the second request seem reasonable.
|
|
||||||
|
|
||||||
**Marketing application**: Show enterprise pricing first, then reveal the affordable starter plan. The contrast makes it feel like a deal.
|
|
||||||
|
|
||||||
### Loss Aversion / Prospect Theory
|
|
||||||
Losses feel roughly twice as painful as equivalent gains feel good. People will work harder to avoid losing than to gain.
|
|
||||||
|
|
||||||
**Marketing application**: Frame in terms of what they'll lose by not acting. "Don't miss out" beats "You could gain."
|
|
||||||
|
|
||||||
### Anchoring Effect
|
### Anchoring Effect
|
||||||
The first number people see heavily influences subsequent judgments.
|
The first number people see heavily influences subsequent judgments.
|
||||||
|
|
||||||
**Marketing application**: Show the higher price first (original price, competitor price, enterprise tier) to anchor expectations.
|
**HVAC application**: Show the higher price first (original price before discount, competitor price, premium tier) to anchor expectations lower.
|
||||||
|
|
||||||
### Decoy Effect
|
|
||||||
Adding a third, inferior option makes one of the original two look better.
|
|
||||||
|
|
||||||
**Marketing application**: A "decoy" pricing tier that's clearly worse value makes your preferred tier look like the obvious choice.
|
|
||||||
|
|
||||||
### Framing Effect
|
### Framing Effect
|
||||||
How something is presented changes how it's perceived. Same facts, different frames.
|
How something is presented changes how it's perceived. Same facts, different frames.
|
||||||
|
|
||||||
**Marketing application**: "90% success rate" vs. "10% failure rate" are identical but feel different. Frame positively.
|
**HVAC application**: "90% of systems fail after 15 years" vs. "10% of systems work beyond 15 years." Identical truth, but frames motivate different behaviors.
|
||||||
|
|
||||||
### Contrast Effect
|
### Contrast Effect
|
||||||
Things seem different depending on what they're compared to.
|
Things seem different depending on what they're compared to.
|
||||||
|
|
||||||
**Marketing application**: Show the "before" state clearly. The contrast with your "after" makes improvements vivid.
|
**HVAC application**: Show the "before" (hot summer, cold winter) clearly. The contrast with your "after" (comfortable home, efficient operation) makes improvements vivid.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pricing Psychology
|
## HVAC-Specific Applications
|
||||||
|
|
||||||
These models specifically address how people perceive and respond to prices.
|
### Urgency in Crisis
|
||||||
|
Summer AC failures and winter heating emergencies are high-stress situations. Psychology shifts:
|
||||||
|
|
||||||
### Charm Pricing / Left-Digit Effect
|
- **Loss aversion intensifies**: Losing comfort/safety is painfully urgent
|
||||||
Prices ending in 9 seem significantly lower than the next round number. $99 feels much cheaper than $100.
|
- **Speed matters more than price**: A homeowner in 95-degree heat will pay premium for same-day service
|
||||||
|
- **Authority reassurance**: Certifications and established reputation reduce anxiety in decision-making
|
||||||
|
|
||||||
**Marketing application**: Use .99 or .95 endings for value-focused products. The left digit dominates perception.
|
**Application**: During peak season, emphasize rapid response, certification, and emergency availability.
|
||||||
|
|
||||||
### Rounded-Price (Fluency) Effect
|
### Seasonal Switching
|
||||||
Round numbers feel premium and are easier to process. $100 signals quality; $99 signals value.
|
HVAC purchases are seasonal. Psychological dynamics shift:
|
||||||
|
|
||||||
**Marketing application**: Use round prices for premium products ($500/month), charm prices for value products ($497/month).
|
- **Spring/summer AC season**: Competitors proliferate → scarcity messaging works ("Only 2 installation slots in June")
|
||||||
|
- **Fall/winter heating season**: Fewer options → comfort and reliability messaging works
|
||||||
|
- **Off-season (Jan-Feb, July)**: Counterprogramming with deep discounts works; anchoring from high price
|
||||||
|
|
||||||
### Rule of 100
|
**Application**: Adjust messaging by season. In off-season, emphasize savings. In peak season, emphasize reliability and availability.
|
||||||
For prices under $100, percentage discounts seem larger ("20% off"). For prices over $100, absolute discounts seem larger ("$50 off").
|
|
||||||
|
|
||||||
**Marketing application**: $80 product: "20% off" beats "$16 off." $500 product: "$100 off" beats "20% off."
|
### Trust in Technical Decisions
|
||||||
|
Homeowners often lack HVAC knowledge. They rely on:
|
||||||
|
|
||||||
### Price Relativity / Good-Better-Best
|
- **Social proof**: Review counts, neighborhood prevalence
|
||||||
People judge prices relative to options presented. A middle tier seems reasonable between cheap and expensive.
|
- **Authority**: Certifications, explanations, transparency
|
||||||
|
- **Similarity**: Local contractors > national chains
|
||||||
|
|
||||||
**Marketing application**: Three tiers where the middle is your target. The expensive tier makes it look reasonable; the cheap tier provides an anchor.
|
**Application**: Build local reputation through reviews, explain technical details simply, show local roots.
|
||||||
|
|
||||||
### Mental Accounting (Pricing)
|
### Maintenance vs. Replacement Decisions
|
||||||
Framing the same price differently changes perception.
|
Significant difference in psychological framing:
|
||||||
|
|
||||||
**Marketing application**: "$1/day" feels cheaper than "$30/month." "Less than your morning coffee" reframes the expense.
|
- **Maintenance**: Emphasize loss avoidance ("Prevent a $5K emergency this winter")
|
||||||
|
- **Replacement**: Emphasize comfort gains AND long-term savings ("Enjoy 20 years of reliable comfort and $300/year savings")
|
||||||
|
|
||||||
---
|
**Application**: Use different messaging for maintenance programs vs. equipment replacement sales.
|
||||||
|
|
||||||
## Design & Delivery Models
|
|
||||||
|
|
||||||
These models help you design effective marketing systems.
|
|
||||||
|
|
||||||
### Hick's Law
|
|
||||||
Decision time increases with the number and complexity of choices. More options = slower decisions = more abandonment.
|
|
||||||
|
|
||||||
**Marketing application**: Simplify choices. One clear CTA beats three. Fewer form fields beat more.
|
|
||||||
|
|
||||||
### AIDA Funnel
|
|
||||||
Attention → Interest → Desire → Action. The classic customer journey model.
|
|
||||||
|
|
||||||
**Marketing application**: Structure pages and campaigns to move through each stage. Capture attention before building desire.
|
|
||||||
|
|
||||||
### Rule of 7
|
|
||||||
Prospects need roughly 7 touchpoints before converting. One ad rarely converts; sustained presence does.
|
|
||||||
|
|
||||||
**Marketing application**: Build multi-touch campaigns across channels. Retargeting, email sequences, and consistent presence compound.
|
|
||||||
|
|
||||||
### Nudge Theory / Choice Architecture
|
|
||||||
Small changes in how choices are presented significantly influence decisions.
|
|
||||||
|
|
||||||
**Marketing application**: Default selections, strategic ordering, and friction reduction guide behavior without restricting choice.
|
|
||||||
|
|
||||||
### BJ Fogg Behavior Model
|
|
||||||
Behavior = Motivation × Ability × Prompt. All three must be present for action.
|
|
||||||
|
|
||||||
**Marketing application**: High motivation but hard to do = won't happen. Easy to do but no prompt = won't happen. Design for all three.
|
|
||||||
|
|
||||||
### EAST Framework
|
|
||||||
Make desired behaviors: Easy, Attractive, Social, Timely.
|
|
||||||
|
|
||||||
**Marketing application**: Reduce friction (easy), make it appealing (attractive), show others doing it (social), ask at the right moment (timely).
|
|
||||||
|
|
||||||
### COM-B Model
|
|
||||||
Behavior requires: Capability, Opportunity, Motivation.
|
|
||||||
|
|
||||||
**Marketing application**: Can they do it (capability)? Is the path clear (opportunity)? Do they want to (motivation)? Address all three.
|
|
||||||
|
|
||||||
### Activation Energy
|
|
||||||
The initial energy required to start something. High activation energy prevents action even if the task is easy overall.
|
|
||||||
|
|
||||||
**Marketing application**: Reduce starting friction. Pre-fill forms, offer templates, show quick wins. Make the first step trivially easy.
|
|
||||||
|
|
||||||
### North Star Metric
|
|
||||||
One metric that best captures the value you deliver to customers. Focus creates alignment.
|
|
||||||
|
|
||||||
**Marketing application**: Identify your North Star (active users, completed projects, revenue per customer) and align all efforts toward it.
|
|
||||||
|
|
||||||
### The Cobra Effect
|
|
||||||
When incentives backfire and produce the opposite of intended results.
|
|
||||||
|
|
||||||
**Marketing application**: Test incentive structures. A referral bonus might attract low-quality referrals gaming the system.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Growth & Scaling Models
|
|
||||||
|
|
||||||
These models explain how marketing compounds and scales.
|
|
||||||
|
|
||||||
### Feedback Loops
|
|
||||||
Output becomes input, creating cycles. Positive loops accelerate growth; negative loops create decline.
|
|
||||||
|
|
||||||
**Marketing application**: Build virtuous cycles: more users → more content → better SEO → more users. Identify and strengthen positive loops.
|
|
||||||
|
|
||||||
### Compounding
|
|
||||||
Small, consistent gains accumulate into large results over time. Early gains matter most.
|
|
||||||
|
|
||||||
**Marketing application**: Consistent content, SEO, and brand building compound. Start early; benefits accumulate exponentially.
|
|
||||||
|
|
||||||
### Network Effects
|
|
||||||
A product becomes more valuable as more people use it.
|
|
||||||
|
|
||||||
**Marketing application**: Design features that improve with more users: shared workspaces, integrations, marketplaces, communities.
|
|
||||||
|
|
||||||
### Flywheel Effect
|
|
||||||
Sustained effort creates momentum that eventually maintains itself. Hard to start, easy to maintain.
|
|
||||||
|
|
||||||
**Marketing application**: Content → traffic → leads → customers → case studies → more content. Each element powers the next.
|
|
||||||
|
|
||||||
### Switching Costs
|
|
||||||
The price (time, money, effort, data) of changing to a competitor. High switching costs create retention.
|
|
||||||
|
|
||||||
**Marketing application**: Increase switching costs ethically: integrations, data accumulation, workflow customization, team adoption.
|
|
||||||
|
|
||||||
### Exploration vs. Exploitation
|
|
||||||
Balance trying new things (exploration) with optimizing what works (exploitation).
|
|
||||||
|
|
||||||
**Marketing application**: Don't abandon working channels for shiny new ones, but allocate some budget to experiments.
|
|
||||||
|
|
||||||
### Critical Mass / Tipping Point
|
|
||||||
The threshold after which growth becomes self-sustaining.
|
|
||||||
|
|
||||||
**Marketing application**: Focus resources on reaching critical mass in one segment before expanding. Depth before breadth.
|
|
||||||
|
|
||||||
### Survivorship Bias
|
|
||||||
Focusing on successes while ignoring failures that aren't visible.
|
|
||||||
|
|
||||||
**Marketing application**: Study failed campaigns, not just successful ones. The viral hit you're copying had 99 failures you didn't see.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Quick Reference
|
## Quick Reference
|
||||||
|
|
||||||
When facing a marketing challenge, consider:
|
|
||||||
|
|
||||||
| Challenge | Relevant Models |
|
| Challenge | Relevant Models |
|
||||||
|-----------|-----------------|
|
|-----------|-----------------|
|
||||||
| Low conversions | Hick's Law, Activation Energy, BJ Fogg, Friction |
|
| Slow lead response | Hyperbolic Discounting, Loss Aversion |
|
||||||
| Price objections | Anchoring, Framing, Mental Accounting, Loss Aversion |
|
| Low maintenance adoption | Status-Quo Bias, Loss Aversion |
|
||||||
| Building trust | Authority, Social Proof, Reciprocity, Pratfall Effect |
|
| Price objections | Anchoring, Framing, Mental Accounting |
|
||||||
| Increasing urgency | Scarcity, Loss Aversion, Zeigarnik Effect |
|
| Building trust | Authority, Social Proof, Reciprocity |
|
||||||
| Retention/churn | Endowment Effect, Switching Costs, Status-Quo Bias |
|
| Seasonal urgency | Scarcity, Loss Aversion, Contrast |
|
||||||
| Growth stalling | Theory of Constraints, Local vs Global Optima, Compounding |
|
| Replacement decisions | Framing, Loss Aversion, Commitment |
|
||||||
| Decision paralysis | Paradox of Choice, Default Effect, Nudge Theory |
|
|
||||||
| Onboarding | Goal-Gradient, IKEA Effect, Commitment & Consistency |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What specific behavior are you trying to influence?
|
1. What specific behavior are you trying to influence (schedule maintenance, buy new system, call for emergency)?
|
||||||
2. What does your customer believe before encountering your marketing?
|
2. What does your customer believe before encountering your marketing?
|
||||||
3. Where in the journey (awareness → consideration → decision) is this?
|
3. Where in the journey (awareness → consideration → decision) is this?
|
||||||
4. What's currently preventing the desired action?
|
4. What's currently preventing the desired action?
|
||||||
|
|
@ -446,10 +256,22 @@ When facing a marketing challenge, consider:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Marketing psychology principles are foundational thinking tools that don't require Compendium integration. However, you can use Compendium to:
|
||||||
|
|
||||||
|
- **Test behavioral assumptions**: Use data to validate whether your psychology-based messaging actually works
|
||||||
|
- **Segment-specific insights**: Apply different psychological models to different customer segments (homeowners vs. contractors)
|
||||||
|
- **Competitive psychological analysis**: Understand what psychological triggers competitors use in their messaging
|
||||||
|
|
||||||
|
**Tool tiers**: Standalone (no tools required for core skill application)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **page-cro**: Apply psychology to page optimization
|
- **page-cro**: Apply psychology to website optimization
|
||||||
- **copywriting**: Write copy using psychological principles
|
- **copywriting**: Write copy using psychological principles
|
||||||
- **popup-cro**: Use triggers and psychology in popups
|
- **hvac-estimate-popups**: Use triggers and psychology in estimate request popups
|
||||||
- **pricing-page optimization**: See page-cro for pricing psychology
|
- **pricing-strategy**: See pricing psychology (anchoring, charm pricing)
|
||||||
- **ab-test-setup**: Test psychological hypotheses
|
- **hvac-lead-ops**: Apply psychology to lead nurture sequences
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "How can I use psychology to increase conversions on our pricing page? We sell a B2B SaaS tool with three tiers ($29, $79, $199/month).",
|
"prompt": "How can I use psychology to increase conversions on our pricing page? We sell a B2B SaaS tool with three tiers ($29, $79, $199/month).",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply relevant pricing psychology models: anchoring (show the highest plan first or use a decoy), charm pricing (consider $29 vs $30), Rule of 100 (percentage vs dollar discounts), Good-Better-Best framing, loss aversion (show what they miss on lower tiers). Should also apply broader persuasion models: social proof near pricing, scarcity for limited-time offers, default effect (pre-select recommended plan). Should provide specific, actionable recommendations tied to their price points.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply relevant pricing psychology models: anchoring (show the highest plan first or use a decoy), charm pricing (consider $29 vs $30), Rule of 100 (percentage vs dollar discounts), Good-Better-Best framing, loss aversion (show what they miss on lower tiers). Should also apply broader persuasion models: social proof near pricing, scarcity for limited-time offers, default effect (pre-select recommended plan). Should provide specific, actionable recommendations tied to their price points.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies pricing psychology models (anchoring, charm pricing, Rule of 100)",
|
"Applies pricing psychology models (anchoring, charm pricing, Rule of 100)",
|
||||||
"Applies Good-Better-Best framing",
|
"Applies Good-Better-Best framing",
|
||||||
"Applies loss aversion to tier differentiation",
|
"Applies loss aversion to tier differentiation",
|
||||||
|
|
|
||||||
|
|
@ -1,220 +0,0 @@
|
||||||
---
|
|
||||||
name: onboarding-cro
|
|
||||||
description: When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also use when the user mentions "onboarding flow," "activation rate," "user activation," "first-run experience," "empty states," "onboarding checklist," "aha moment," "new user experience," "users aren't activating," "nobody completes setup," "low activation rate," "users sign up but don't use the product," "time to value," or "first session experience." Use this whenever users are signing up but not sticking around. For signup/registration optimization, see signup-flow-cro. For ongoing email sequences, see email-sequence.
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Onboarding CRO
|
|
||||||
|
|
||||||
You are an expert in user onboarding and activation. Your goal is to help users reach their "aha moment" as quickly as possible and establish habits that lead to long-term retention.
|
|
||||||
|
|
||||||
## Initial Assessment
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` 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 providing recommendations, understand:
|
|
||||||
|
|
||||||
1. **Product Context** - What type of product? B2B or B2C? Core value proposition?
|
|
||||||
2. **Activation Definition** - What's the "aha moment"? What action indicates a user "gets it"?
|
|
||||||
3. **Current State** - What happens after signup? Where do users drop off?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### 1. Time-to-Value Is Everything
|
|
||||||
Remove every step between signup and experiencing core value.
|
|
||||||
|
|
||||||
### 2. One Goal Per Session
|
|
||||||
Focus first session on one successful outcome. Save advanced features for later.
|
|
||||||
|
|
||||||
### 3. Do, Don't Show
|
|
||||||
Interactive > Tutorial. Doing the thing > Learning about the thing.
|
|
||||||
|
|
||||||
### 4. Progress Creates Motivation
|
|
||||||
Show advancement. Celebrate completions. Make the path visible.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Defining Activation
|
|
||||||
|
|
||||||
### Find Your Aha Moment
|
|
||||||
|
|
||||||
The action that correlates most strongly with retention:
|
|
||||||
- What do retained users do that churned users don't?
|
|
||||||
- What's the earliest indicator of future engagement?
|
|
||||||
|
|
||||||
**Examples by product type:**
|
|
||||||
- Project management: Create first project + add team member
|
|
||||||
- Analytics: Install tracking + see first report
|
|
||||||
- Design tool: Create first design + export/share
|
|
||||||
- Marketplace: Complete first transaction
|
|
||||||
|
|
||||||
### Activation Metrics
|
|
||||||
- % of signups who reach activation
|
|
||||||
- Time to activation
|
|
||||||
- Steps to activation
|
|
||||||
- Activation by cohort/source
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Onboarding Flow Design
|
|
||||||
|
|
||||||
### Immediate Post-Signup (First 30 Seconds)
|
|
||||||
|
|
||||||
| Approach | Best For | Risk |
|
|
||||||
|----------|----------|------|
|
|
||||||
| Product-first | Simple products, B2C, mobile | Blank slate overwhelm |
|
|
||||||
| Guided setup | Products needing personalization | Adds friction before value |
|
|
||||||
| Value-first | Products with demo data | May not feel "real" |
|
|
||||||
|
|
||||||
**Whatever you choose:**
|
|
||||||
- Clear single next action
|
|
||||||
- No dead ends
|
|
||||||
- Progress indication if multi-step
|
|
||||||
|
|
||||||
### Onboarding Checklist Pattern
|
|
||||||
|
|
||||||
**When to use:**
|
|
||||||
- Multiple setup steps required
|
|
||||||
- Product has several features to discover
|
|
||||||
- Self-serve B2B products
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- 3-7 items (not overwhelming)
|
|
||||||
- Order by value (most impactful first)
|
|
||||||
- Start with quick wins
|
|
||||||
- Progress bar/completion %
|
|
||||||
- Celebration on completion
|
|
||||||
- Dismiss option (don't trap users)
|
|
||||||
|
|
||||||
### Empty States
|
|
||||||
|
|
||||||
Empty states are onboarding opportunities, not dead ends.
|
|
||||||
|
|
||||||
**Good empty state:**
|
|
||||||
- Explains what this area is for
|
|
||||||
- Shows what it looks like with data
|
|
||||||
- Clear primary action to add first item
|
|
||||||
- Optional: Pre-populate with example data
|
|
||||||
|
|
||||||
### Tooltips and Guided Tours
|
|
||||||
|
|
||||||
**When to use:** Complex UI, features that aren't self-evident, power features users might miss
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Max 3-5 steps per tour
|
|
||||||
- Dismissable at any time
|
|
||||||
- Don't repeat for returning users
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Multi-Channel Onboarding
|
|
||||||
|
|
||||||
### Email + In-App Coordination
|
|
||||||
|
|
||||||
**Trigger-based emails:**
|
|
||||||
- Welcome email (immediate)
|
|
||||||
- Incomplete onboarding (24h, 72h)
|
|
||||||
- Activation achieved (celebration + next step)
|
|
||||||
- Feature discovery (days 3, 7, 14)
|
|
||||||
|
|
||||||
**Email should:**
|
|
||||||
- Reinforce in-app actions, not duplicate them
|
|
||||||
- Drive back to product with specific CTA
|
|
||||||
- Be personalized based on actions taken
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Handling Stalled Users
|
|
||||||
|
|
||||||
### Detection
|
|
||||||
Define "stalled" criteria (X days inactive, incomplete setup)
|
|
||||||
|
|
||||||
### Re-engagement Tactics
|
|
||||||
|
|
||||||
1. **Email sequence** - Reminder of value, address blockers, offer help
|
|
||||||
2. **In-app recovery** - Welcome back, pick up where left off
|
|
||||||
3. **Human touch** - For high-value accounts, personal outreach
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Measurement
|
|
||||||
|
|
||||||
### Key Metrics
|
|
||||||
|
|
||||||
| Metric | Description |
|
|
||||||
|--------|-------------|
|
|
||||||
| Activation rate | % reaching activation event |
|
|
||||||
| Time to activation | How long to first value |
|
|
||||||
| Onboarding completion | % completing setup |
|
|
||||||
| Day 1/7/30 retention | Return rate by timeframe |
|
|
||||||
|
|
||||||
### Funnel Analysis
|
|
||||||
|
|
||||||
Track drop-off at each step:
|
|
||||||
```
|
|
||||||
Signup → Step 1 → Step 2 → Activation → Retention
|
|
||||||
100% 80% 60% 40% 25%
|
|
||||||
```
|
|
||||||
|
|
||||||
Identify biggest drops and focus there.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Output Format
|
|
||||||
|
|
||||||
### Onboarding Audit
|
|
||||||
For each issue: Finding → Impact → Recommendation → Priority
|
|
||||||
|
|
||||||
### Onboarding Flow Design
|
|
||||||
- Activation goal
|
|
||||||
- Step-by-step flow
|
|
||||||
- Checklist items (if applicable)
|
|
||||||
- Empty state copy
|
|
||||||
- Email sequence triggers
|
|
||||||
- Metrics plan
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Common Patterns by Product Type
|
|
||||||
|
|
||||||
| Product Type | Key Steps |
|
|
||||||
|--------------|-----------|
|
|
||||||
| B2B SaaS | Setup wizard → First value action → Team invite → Deep setup |
|
|
||||||
| Marketplace | Complete profile → Browse → First transaction → Repeat loop |
|
|
||||||
| Mobile App | Permissions → Quick win → Push setup → Habit loop |
|
|
||||||
| Content Platform | Follow/customize → Consume → Create → Engage |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Experiment Ideas
|
|
||||||
|
|
||||||
When recommending experiments, consider tests for:
|
|
||||||
- Flow simplification (step count, ordering)
|
|
||||||
- Progress and motivation mechanics
|
|
||||||
- Personalization by role or goal
|
|
||||||
- Support and help availability
|
|
||||||
|
|
||||||
**For comprehensive experiment ideas**: See [references/experiments.md](references/experiments.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task-Specific Questions
|
|
||||||
|
|
||||||
1. What action most correlates with retention?
|
|
||||||
2. What happens immediately after signup?
|
|
||||||
3. Where do users currently drop off?
|
|
||||||
4. What's your activation rate target?
|
|
||||||
5. Do you have cohort analysis on successful vs. churned users?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **signup-flow-cro**: For optimizing the signup before onboarding
|
|
||||||
- **email-sequence**: For onboarding email series
|
|
||||||
- **paywall-upgrade-cro**: For converting to paid during/after onboarding
|
|
||||||
- **ab-test-setup**: For testing onboarding changes
|
|
||||||
|
|
@ -1,92 +0,0 @@
|
||||||
{
|
|
||||||
"skill_name": "onboarding-cro",
|
|
||||||
"evals": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"prompt": "Help me optimize our onboarding flow. We have a project management tool and only 30% of trial users create their first project within the first week. We need to get them to value faster.",
|
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should start by defining the activation/aha moment — in this case, creating a first project. Should evaluate the current time-to-value and identify friction points. Should recommend an onboarding flow approach (product-first, guided setup, or value-first). Should apply the checklist pattern (3-7 items for onboarding completion). Should address empty states as opportunities to guide users. Should provide experiment ideas for testing improvements. Should include measurement metrics.",
|
|
||||||
"assertions": [
|
|
||||||
"Checks for product-marketing-context.md",
|
|
||||||
"Defines the activation/aha moment",
|
|
||||||
"Evaluates time-to-value",
|
|
||||||
"Recommends onboarding flow approach",
|
|
||||||
"Applies checklist pattern with 3-7 items",
|
|
||||||
"Addresses empty states as opportunities",
|
|
||||||
"Provides experiment ideas",
|
|
||||||
"Includes measurement metrics"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"prompt": "What should our onboarding checklist include? We're a design collaboration tool. Users need to upload a design, invite a team member, and leave a comment to get full value.",
|
|
||||||
"expected_output": "Should apply the checklist pattern. Should include the 3 stated activation actions (upload design, invite team, leave comment). Should recommend 3-7 total items ordered by increasing commitment. Should suggest starting with the quickest win to build momentum. Should recommend progress indicators and completion rewards. Should address what happens when users skip items. Should provide specific UX recommendations for the checklist implementation.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies checklist pattern",
|
|
||||||
"Includes the 3 stated activation actions",
|
|
||||||
"Limits to 3-7 total items",
|
|
||||||
"Orders by increasing commitment",
|
|
||||||
"Starts with quickest win",
|
|
||||||
"Recommends progress indicators",
|
|
||||||
"Addresses skipped items",
|
|
||||||
"Provides UX recommendations"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 3,
|
|
||||||
"prompt": "our users sign up but then never come back. like 50% don't even log in a second time. what do we do?",
|
|
||||||
"expected_output": "Should trigger on casual phrasing. Should address this as a stalled users problem. Should apply the handling stalled users framework: identify drop-off points, re-engagement triggers, multi-channel outreach (email, in-app, push). Should investigate root causes: is the first-run experience too complex? Is value not immediately apparent? Is the setup too long? Should recommend immediate improvements to the first session experience. Should suggest multi-channel onboarding (email sequences to bring them back). Should cross-reference email-sequence for re-engagement emails.",
|
|
||||||
"assertions": [
|
|
||||||
"Triggers on casual phrasing",
|
|
||||||
"Applies stalled users framework",
|
|
||||||
"Identifies potential root causes for drop-off",
|
|
||||||
"Recommends first-session experience improvements",
|
|
||||||
"Suggests multi-channel onboarding",
|
|
||||||
"Cross-references email-sequence for re-engagement",
|
|
||||||
"Provides specific re-engagement triggers"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 4,
|
|
||||||
"prompt": "How do we handle the empty state when a new user first logs in? Right now they just see a blank dashboard.",
|
|
||||||
"expected_output": "Should apply the empty states as opportunities guidance. Should recommend turning the blank dashboard into a guided experience: sample data to show what the product looks like populated, a clear first action CTA, contextual tips, or a quick-start wizard. Should provide specific recommendations for empty state design: what to show, what action to prompt, how to reduce the 'blank canvas paralysis.' Should reference patterns by product type if applicable.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies empty states as opportunities guidance",
|
|
||||||
"Recommends alternatives to blank dashboard",
|
|
||||||
"Suggests sample data or templates",
|
|
||||||
"Provides clear first action CTA",
|
|
||||||
"Addresses blank canvas paralysis",
|
|
||||||
"Provides specific empty state design recommendations"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 5,
|
|
||||||
"prompt": "Should we use tooltips, a product tour, or a setup wizard for onboarding? What works best?",
|
|
||||||
"expected_output": "Should apply the tooltips/guided tours guidance. Should compare the approaches: tooltips (contextual, on-demand, less intrusive), product tours (guided walkthrough, can overwhelm), setup wizards (structured, ensures key setup steps). Should recommend based on product complexity and onboarding goals. Should note that the best approach often combines elements. Should provide best practices for each: tooltip fatigue avoidance, tour length limits, wizard step count. Should recommend testing different approaches.",
|
|
||||||
"assertions": [
|
|
||||||
"Compares tooltips, product tours, and setup wizards",
|
|
||||||
"Explains when each works best",
|
|
||||||
"Notes that combination approaches often work",
|
|
||||||
"Provides best practices for each",
|
|
||||||
"Addresses tooltip fatigue and tour length",
|
|
||||||
"Recommends testing different approaches"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 6,
|
|
||||||
"prompt": "Our signup form has 8 fields and people keep dropping off. Can you help us fix the signup flow?",
|
|
||||||
"expected_output": "Should recognize this is a signup flow optimization task, not post-signup onboarding. Should defer to or cross-reference the signup-flow-cro skill, which handles signup form optimization, field reduction, and registration flow design. Onboarding-cro covers what happens after signup. Should make this distinction clear.",
|
|
||||||
"assertions": [
|
|
||||||
"Recognizes this as signup flow optimization, not onboarding",
|
|
||||||
"References or defers to signup-flow-cro skill",
|
|
||||||
"Explains that onboarding-cro covers post-signup",
|
|
||||||
"Does not attempt signup form redesign using onboarding patterns"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
@ -1,258 +0,0 @@
|
||||||
# Onboarding Experiment Ideas
|
|
||||||
|
|
||||||
Comprehensive list of A/B tests and experiments for user onboarding and activation.
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
- Flow Simplification Experiments (reduce friction, step sequencing, progress & motivation)
|
|
||||||
- Guided Experience Experiments (product tours, CTA optimization, UI guidance)
|
|
||||||
- Personalization Experiments (user segmentation, dynamic content)
|
|
||||||
- Quick Wins & Engagement Experiments (time-to-value, motivation mechanics, support & help)
|
|
||||||
- Email & Multi-Channel Experiments (onboarding emails, email content, feedback loops)
|
|
||||||
- Re-engagement Experiments (stalled user recovery, return experience)
|
|
||||||
- Technical & UX Experiments (performance, mobile onboarding, accessibility)
|
|
||||||
- Metrics to Track
|
|
||||||
|
|
||||||
## Flow Simplification Experiments
|
|
||||||
|
|
||||||
### Reduce Friction
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Email verification timing | During vs. after onboarding |
|
|
||||||
| Empty states vs. dummy data | Pre-populated examples |
|
|
||||||
| Pre-filled templates | Accelerate setup with templates |
|
|
||||||
| OAuth options | Faster account linking |
|
|
||||||
| Required step count | Fewer required steps |
|
|
||||||
| Optional vs. required fields | Minimize requirements |
|
|
||||||
| Skip options | Allow bypassing non-critical steps |
|
|
||||||
|
|
||||||
### Step Sequencing
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Step ordering | Test different sequences |
|
|
||||||
| Value-first ordering | Highest-value features first |
|
|
||||||
| Friction placement | Move hard steps later |
|
|
||||||
| Required vs. optional balance | Ratio of required steps |
|
|
||||||
| Single vs. branching paths | One path vs. personalized |
|
|
||||||
| Quick start vs. full setup | Minimal path to value |
|
|
||||||
|
|
||||||
### Progress & Motivation
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Progress bars | Show completion percentage |
|
|
||||||
| Checklist length | 3-5 items vs. 5-7 items |
|
|
||||||
| Gamification | Badges, rewards, achievements |
|
|
||||||
| Completion messaging | "X% complete" visibility |
|
|
||||||
| Starting point | Begin at 20% vs. 0% |
|
|
||||||
| Celebration moments | Acknowledge completions |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Guided Experience Experiments
|
|
||||||
|
|
||||||
### Product Tours
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Interactive tours | Tools like Navattic, Storylane |
|
|
||||||
| Tooltip vs. modal guidance | Subtle vs. attention-grabbing |
|
|
||||||
| Video tutorials | For complex workflows |
|
|
||||||
| Self-paced vs. guided | User control vs. structured |
|
|
||||||
| Tour length | Shorter vs. comprehensive |
|
|
||||||
| Tour triggering | Automatic vs. user-initiated |
|
|
||||||
|
|
||||||
### CTA Optimization
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| CTA text variations | Action-oriented copy testing |
|
|
||||||
| CTA placement | Position within screens |
|
|
||||||
| In-app tooltips | Feature discovery prompts |
|
|
||||||
| Sticky CTAs | Persist during onboarding |
|
|
||||||
| CTA contrast | Visual prominence |
|
|
||||||
| Secondary CTAs | "Learn more" vs. primary only |
|
|
||||||
|
|
||||||
### UI Guidance
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Hotspot highlights | Draw attention to key features |
|
|
||||||
| Coachmarks | Contextual tips |
|
|
||||||
| Feature announcements | New feature discovery |
|
|
||||||
| Contextual help | Help where users need it |
|
|
||||||
| Search vs. guided | Self-service vs. directed |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Personalization Experiments
|
|
||||||
|
|
||||||
### User Segmentation
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Role-based onboarding | Different paths by role |
|
|
||||||
| Goal-based paths | Customize by stated goal |
|
|
||||||
| Role-specific dashboards | Relevant default views |
|
|
||||||
| Use-case question | Personalize based on answer |
|
|
||||||
| Industry-specific paths | Vertical customization |
|
|
||||||
| Experience-based | Beginner vs. expert paths |
|
|
||||||
|
|
||||||
### Dynamic Content
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Personalized welcome | Name, company, role |
|
|
||||||
| Industry examples | Relevant use cases |
|
|
||||||
| Dynamic recommendations | Based on user answers |
|
|
||||||
| Template suggestions | Pre-filled for segment |
|
|
||||||
| Feature highlighting | Relevant to stated goals |
|
|
||||||
| Benchmark data | Industry-specific metrics |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Quick Wins & Engagement Experiments
|
|
||||||
|
|
||||||
### Time-to-Value
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| First quick win | "Complete your first X" |
|
|
||||||
| Success messages | After key actions |
|
|
||||||
| Progress celebrations | Milestone moments |
|
|
||||||
| Next step suggestions | After each completion |
|
|
||||||
| Value demonstration | Show what they achieved |
|
|
||||||
| Outcome preview | What success looks like |
|
|
||||||
|
|
||||||
### Motivation Mechanics
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Achievement badges | Gamification elements |
|
|
||||||
| Streaks | Consecutive day engagement |
|
|
||||||
| Leaderboards | Social comparison (if appropriate) |
|
|
||||||
| Rewards | Incentives for completion |
|
|
||||||
| Unlock mechanics | Features revealed progressively |
|
|
||||||
|
|
||||||
### Support & Help
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Free onboarding calls | For complex products |
|
|
||||||
| Contextual help | Throughout onboarding |
|
|
||||||
| Chat support | Availability during onboarding |
|
|
||||||
| Proactive outreach | For stuck users |
|
|
||||||
| Self-service resources | Help docs, videos |
|
|
||||||
| Community access | Peer support early |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Email & Multi-Channel Experiments
|
|
||||||
|
|
||||||
### Onboarding Emails
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Founder welcome email | Personal vs. generic |
|
|
||||||
| Behavior-based triggers | Action/inaction based |
|
|
||||||
| Email timing | Immediate vs. delayed |
|
|
||||||
| Email frequency | More vs. fewer touches |
|
|
||||||
| Quick tips format | Short actionable content |
|
|
||||||
| Video in email | More engaging format |
|
|
||||||
|
|
||||||
### Email Content
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Subject lines | Open rate optimization |
|
|
||||||
| Personalization depth | Name vs. behavior-based |
|
|
||||||
| CTA prominence | Single clear action |
|
|
||||||
| Social proof inclusion | Testimonials in email |
|
|
||||||
| Urgency messaging | Trial reminders |
|
|
||||||
| Plain text vs. designed | Format testing |
|
|
||||||
|
|
||||||
### Feedback Loops
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| NPS during onboarding | When to ask |
|
|
||||||
| Blocking question | "What's stopping you?" |
|
|
||||||
| NPS follow-up | Actions based on score |
|
|
||||||
| In-app feedback | Thumbs up/down on features |
|
|
||||||
| Survey timing | When to request feedback |
|
|
||||||
| Feedback incentives | Reward for completing |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Re-engagement Experiments
|
|
||||||
|
|
||||||
### Stalled User Recovery
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Re-engagement email timing | When to send |
|
|
||||||
| Personal outreach | Human vs. automated |
|
|
||||||
| Simplified path | Reduced steps for returners |
|
|
||||||
| Incentive offers | Discount or extended trial |
|
|
||||||
| Problem identification | Ask what's blocking |
|
|
||||||
| Demo offer | Live walkthrough |
|
|
||||||
|
|
||||||
### Return Experience
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Welcome back message | Acknowledge return |
|
|
||||||
| Progress resume | Pick up where left off |
|
|
||||||
| Changed state | What happened while away |
|
|
||||||
| Re-onboarding | Fresh start option |
|
|
||||||
| Urgency messaging | Trial time remaining |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Technical & UX Experiments
|
|
||||||
|
|
||||||
### Performance
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Load time optimization | Faster = higher completion |
|
|
||||||
| Progressive loading | Perceived performance |
|
|
||||||
| Offline capability | Mobile experience |
|
|
||||||
| Error handling | Graceful failure recovery |
|
|
||||||
|
|
||||||
### Mobile Onboarding
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Touch targets | Size and spacing |
|
|
||||||
| Swipe navigation | Mobile-native patterns |
|
|
||||||
| Screen count | Fewer screens needed |
|
|
||||||
| Input optimization | Mobile-friendly forms |
|
|
||||||
| Permission timing | When to ask |
|
|
||||||
|
|
||||||
### Accessibility
|
|
||||||
|
|
||||||
| Test | Hypothesis |
|
|
||||||
|------|------------|
|
|
||||||
| Screen reader support | Accessibility impact |
|
|
||||||
| Keyboard navigation | Non-mouse users |
|
|
||||||
| Color contrast | Visibility |
|
|
||||||
| Font sizing | Readability |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Metrics to Track
|
|
||||||
|
|
||||||
For all experiments, measure:
|
|
||||||
|
|
||||||
| Metric | Description |
|
|
||||||
|--------|-------------|
|
|
||||||
| Activation rate | % reaching activation event |
|
|
||||||
| Time to activation | Hours/days to first value |
|
|
||||||
| Step completion rate | % completing each step |
|
|
||||||
| Drop-off points | Where users abandon |
|
|
||||||
| Return rate | Users who come back |
|
|
||||||
| Day 1/7/30 retention | Engagement over time |
|
|
||||||
| Feature adoption | Which features get used |
|
|
||||||
| Support requests | Volume during onboarding |
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: page-cro
|
name: page-cro
|
||||||
description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," "why isn't this page working," "my landing page sucks," "nobody's converting," "low conversion rate," "bounce rate is too high," "people leave without signing up," or "this page needs work." Use this even if the user just shares a URL and asks for feedback — they probably want conversion help. For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro.
|
description: "When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says 'CRO,' 'conversion rate optimization,' 'this page isn't converting,' 'improve conversions,' 'why isn't this page working,' 'my landing page sucks,' 'nobody's converting,' 'low conversion rate,' 'bounce rate is too high,' or 'this page needs work.' Use this even if the user just shares a URL and asks for feedback — they probably want conversion help. For forms outside of pages, see form-cro. For popups/modals, see hvac-estimate-popups."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [browse, scrape, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Page Conversion Rate Optimization (CRO)
|
# Page Conversion Rate Optimization (CRO)
|
||||||
|
|
@ -12,13 +15,13 @@ You are a conversion rate optimization expert. Your goal is to analyze marketing
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 providing recommendations, identify:
|
Before providing recommendations, identify:
|
||||||
|
|
||||||
1. **Page Type**: Homepage, landing page, pricing, feature, blog, about, other
|
1. **Page Type**: Homepage, landing page, pricing, service detail, blog, about, other
|
||||||
2. **Primary Conversion Goal**: Sign up, request demo, purchase, subscribe, download, contact sales
|
2. **Primary Conversion Goal**: Quote request, phone call, service area signup, maintenance plan enrollment, download guide
|
||||||
3. **Traffic Context**: Where are visitors coming from? (organic, paid, email, social)
|
3. **Traffic Context**: Where are visitors coming from? (organic, paid, local search, social)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -29,39 +32,40 @@ Analyze the page across these dimensions, in order of impact:
|
||||||
### 1. Value Proposition Clarity (Highest Impact)
|
### 1. Value Proposition Clarity (Highest Impact)
|
||||||
|
|
||||||
**Check for:**
|
**Check for:**
|
||||||
- Can a visitor understand what this is and why they should care within 5 seconds?
|
- Can a homeowner understand what service you offer and why they should care within 5 seconds?
|
||||||
- Is the primary benefit clear, specific, and differentiated?
|
- Is the primary benefit clear and differentiated? (e.g., "Emergency service in 2 hours" vs. "Fast AC repair")
|
||||||
- Is it written in the customer's language (not company jargon)?
|
- Is it written in the customer's language, not contractor jargon?
|
||||||
|
|
||||||
**Common issues:**
|
**Common issues:**
|
||||||
- Feature-focused instead of benefit-focused
|
- Feature-focused ("15+ years experience") instead of benefit-focused ("Your home stays comfortable")
|
||||||
- Too vague or too clever (sacrificing clarity)
|
- Too vague or too clever (sacrificing clarity)
|
||||||
- Trying to say everything instead of the most important thing
|
- Trying to serve everyone (residential, commercial, maintenance) on one page
|
||||||
|
|
||||||
### 2. Headline Effectiveness
|
### 2. Headline Effectiveness
|
||||||
|
|
||||||
**Evaluate:**
|
**Evaluate:**
|
||||||
- Does it communicate the core value proposition?
|
- Does it communicate the core benefit and address the visitor's immediate problem?
|
||||||
- Is it specific enough to be meaningful?
|
- Is it specific enough to be meaningful?
|
||||||
- Does it match the traffic source's messaging?
|
- Does it match the traffic source's intent?
|
||||||
|
|
||||||
**Strong headline patterns:**
|
**Strong headline patterns for HVAC:**
|
||||||
- Outcome-focused: "Get [desired outcome] without [pain point]"
|
- Problem + solution: "AC Not Working? Emergency Service in 2 Hours"
|
||||||
- Specificity: Include numbers, timeframes, or concrete details
|
- Seasonal urgency: "Beat the Rush: Schedule Summer AC Maintenance Now"
|
||||||
- Social proof: "Join 10,000+ teams who..."
|
- Specificity with numbers: "90% of customers get a quote same-day"
|
||||||
|
- Comfort/peace of mind: "Sleep Better Tonight With A New Furnace"
|
||||||
|
|
||||||
### 3. CTA Placement, Copy, and Hierarchy
|
### 3. CTA Placement, Copy, and Hierarchy
|
||||||
|
|
||||||
**Primary CTA assessment:**
|
**Primary CTA assessment:**
|
||||||
- Is there one clear primary action?
|
- Is there one clear primary action? ("Get a Quote" not "Call/Email/Chat")
|
||||||
- Is it visible without scrolling?
|
- Is it visible without scrolling on mobile?
|
||||||
- Does the button copy communicate value, not just action?
|
- Does the button communicate value, not just action?
|
||||||
- Weak: "Submit," "Sign Up," "Learn More"
|
- Weak: "Submit," "Contact Us," "Learn More"
|
||||||
- Strong: "Start Free Trial," "Get My Report," "See Pricing"
|
- Strong: "Get Free Quote," "Schedule Service Today," "Claim Maintenance Special"
|
||||||
|
|
||||||
**CTA hierarchy:**
|
**CTA hierarchy:**
|
||||||
- Is there a logical primary vs. secondary CTA structure?
|
- Is there a logical primary vs. secondary CTA structure?
|
||||||
- Are CTAs repeated at key decision points?
|
- Are CTAs repeated at key decision points (after trust signals, FAQ, customer testimonials)?
|
||||||
|
|
||||||
### 4. Visual Hierarchy and Scannability
|
### 4. Visual Hierarchy and Scannability
|
||||||
|
|
||||||
|
|
@ -69,38 +73,40 @@ Analyze the page across these dimensions, in order of impact:
|
||||||
- Can someone scanning get the main message?
|
- Can someone scanning get the main message?
|
||||||
- Are the most important elements visually prominent?
|
- Are the most important elements visually prominent?
|
||||||
- Is there enough white space?
|
- Is there enough white space?
|
||||||
- Do images support or distract from the message?
|
- Do images support or distract? (Trustworthy photos of technicians, clean job sites, happy homeowners beat stock photos)
|
||||||
|
|
||||||
### 5. Trust Signals and Social Proof
|
### 5. Trust Signals and Social Proof
|
||||||
|
|
||||||
**Types to look for:**
|
**Types to look for:**
|
||||||
- Customer logos (especially recognizable ones)
|
- Local certifications (HVAC Excellence, EPA Certified, NATE Certified)
|
||||||
- Testimonials (specific, attributed, with photos)
|
- Customer testimonials (specific, attributed, with photos and service type)
|
||||||
- Case study snippets with real numbers
|
- Review counts and scores (Google, Yelp, BBB ratings)
|
||||||
- Review scores and counts
|
- Licensing and bonding badges
|
||||||
- Security badges (where relevant)
|
- "Serving [City/County] for [X] years"
|
||||||
|
- Before/after photos of installations
|
||||||
|
- Customer logos (major building/property management clients)
|
||||||
|
|
||||||
**Placement:** Near CTAs and after benefit claims
|
**Placement:** Near CTAs and after benefit claims
|
||||||
|
|
||||||
### 6. Objection Handling
|
### 6. Objection Handling
|
||||||
|
|
||||||
**Common objections to address:**
|
**Common objections to address:**
|
||||||
- Price/value concerns
|
- "Will this cost a lot?" → Address upfront, offer free quotes
|
||||||
- "Will this work for my situation?"
|
- "Will you respect my home?" → Show photos, testimonials, insurance info
|
||||||
- Implementation difficulty
|
- "Can you come quickly?" → Highlight emergency availability
|
||||||
- "What if it doesn't work?"
|
- "What if I have questions?" → Show multiple contact methods
|
||||||
|
|
||||||
**Address through:** FAQ sections, guarantees, comparison content, process transparency
|
**Address through:** FAQ sections, service comparison charts, process transparency, customer testimonials
|
||||||
|
|
||||||
### 7. Friction Points
|
### 7. Friction Points
|
||||||
|
|
||||||
**Look for:**
|
**Look for:**
|
||||||
- Too many form fields
|
- Too many form fields on quote request
|
||||||
- Unclear next steps
|
- Unclear next steps after clicking CTA
|
||||||
- Confusing navigation
|
- Missing phone number or call-now button (phone is #1 HVAC conversion method)
|
||||||
- Required information that shouldn't be required
|
- Confusing navigation (should be obvious: Services, Pricing/Guarantees, About, Contact)
|
||||||
- Mobile experience issues
|
- Mobile experience issues (unreadable text, tiny buttons)
|
||||||
- Long load times
|
- Long page load times (especially on slow mobile connections)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -125,39 +131,40 @@ For key elements (headlines, CTAs), provide 2-3 alternatives with rationale.
|
||||||
## Page-Specific Frameworks
|
## Page-Specific Frameworks
|
||||||
|
|
||||||
### Homepage CRO
|
### Homepage CRO
|
||||||
- Clear positioning for cold visitors
|
- Clear positioning for cold visitors (residential vs. commercial vs. both)
|
||||||
- Quick path to most common conversion
|
- Quick path to most common action (quote request or call)
|
||||||
- Handle both "ready to buy" and "still researching"
|
- Handle "emergency call" vs. "scheduled service" clearly
|
||||||
|
|
||||||
### Landing Page CRO
|
### Service Landing Page CRO
|
||||||
- Message match with traffic source
|
- Service-specific headline and benefit statement
|
||||||
- Single CTA (remove navigation if possible)
|
- Clear pricing or guarantee (flat-rate, hourly, seasonal special)
|
||||||
- Complete argument on one page
|
- Objection handling for that specific service (e.g., "Will you need to replace my whole system?")
|
||||||
|
- Trust signals specific to that service
|
||||||
|
|
||||||
### Pricing Page CRO
|
### Pricing/Service Comparison Page CRO
|
||||||
- Clear plan comparison
|
- Clear service tier comparison
|
||||||
- Recommended plan indication
|
- Recommended service indication
|
||||||
- Address "which plan is right for me?" anxiety
|
- Address "what service do I actually need?" anxiety
|
||||||
|
- Guarantee or satisfaction promise
|
||||||
### Feature Page CRO
|
|
||||||
- Connect feature to benefit
|
|
||||||
- Use cases and examples
|
|
||||||
- Clear path to try/buy
|
|
||||||
|
|
||||||
### Blog Post CRO
|
### Blog Post CRO
|
||||||
- Contextual CTAs matching content topic
|
- Contextual CTAs matching content topic
|
||||||
- Inline CTAs at natural stopping points
|
- "Need help with this? Get a free quote" CTA
|
||||||
|
- Inline CTAs at natural stopping points (after pain point section)
|
||||||
|
- Lead magnet (e.g., "Download our AC Maintenance Checklist")
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Experiment Ideas
|
## Experiment Ideas
|
||||||
|
|
||||||
When recommending experiments, consider tests for:
|
When recommending experiments, consider tests for:
|
||||||
- Hero section (headline, visual, CTA)
|
- Hero section (headline, visual, CTA copy)
|
||||||
- Trust signals and social proof placement
|
- Trust signals and social proof placement
|
||||||
- Pricing presentation
|
- Service comparison clarity
|
||||||
- Form optimization
|
- Form optimization (phone required vs. optional)
|
||||||
- Navigation and UX
|
- Phone number prominence vs. quote form
|
||||||
|
- Seasonal messaging
|
||||||
|
- Emergency vs. scheduled service emphasis
|
||||||
|
|
||||||
**For comprehensive experiment ideas by page type**: See [references/experiments.md](references/experiments.md)
|
**For comprehensive experiment ideas by page type**: See [references/experiments.md](references/experiments.md)
|
||||||
|
|
||||||
|
|
@ -165,18 +172,36 @@ When recommending experiments, consider tests for:
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What's your current conversion rate and goal?
|
1. What's your current conversion rate (quotes, calls, form submissions)?
|
||||||
2. Where is traffic coming from?
|
2. Where is traffic coming from?
|
||||||
3. What does your signup/purchase flow look like after this page?
|
3. What happens after a visitor converts?
|
||||||
4. Do you have user research, heatmaps, or session recordings?
|
4. Do you have user research, heatmaps, or session recordings?
|
||||||
5. What have you already tried?
|
5. What have you already tried?
|
||||||
|
6. Is this page for a specific service or all services?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill can be enhanced using **Compendium** market intelligence and competitor analysis tools.
|
||||||
|
|
||||||
|
**Relevant Compendium capabilities:**
|
||||||
|
- **Browse & Scrape**: Analyze competitor HVAC landing pages to benchmark trust signals, pricing presentation, and CTA strategies
|
||||||
|
- **Search**: Identify trending HVAC customer pain points and seasonal messaging themes
|
||||||
|
- **Analyze**: Extract patterns from top-performing competitor pages in your market
|
||||||
|
|
||||||
|
**When to use Compendium:**
|
||||||
|
- Benchmarking your value prop against local competitors
|
||||||
|
- Finding seasonal messaging trends for HVAC services
|
||||||
|
- Identifying emerging customer objections in your market
|
||||||
|
|
||||||
|
See [COMPENDIUM_INTEGRATION.md](../COMPENDIUM_INTEGRATION.md) for detailed workflows.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **signup-flow-cro**: If the issue is in the signup process itself
|
- **form-cro**: If quote request forms on the page need optimization
|
||||||
- **form-cro**: If forms on the page need optimization
|
- **hvac-estimate-popups**: If considering popups as part of the strategy
|
||||||
- **popup-cro**: If considering popups as part of the strategy
|
- **hvac-copywriting**: If the page needs a complete copy rewrite
|
||||||
- **copywriting**: If the page needs a complete copy rewrite
|
|
||||||
- **ab-test-setup**: To properly test recommended changes
|
- **ab-test-setup**: To properly test recommended changes
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Here's my SaaS landing page: https://example.com/product. We get about 5,000 visitors/month from Google Ads but only 1.2% convert to free trial signups. Can you help me figure out what's wrong?",
|
"prompt": "Here's my SaaS landing page: https://example.com/product. We get about 5,000 visitors/month from Google Ads but only 1.2% convert to free trial signups. Can you help me figure out what's wrong?",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify page type (landing page) and conversion goal (free trial signup). Should analyze across the CRO framework dimensions: value proposition clarity, headline effectiveness, CTA placement/copy/hierarchy, visual hierarchy, trust signals, objection handling, and friction points. Should provide recommendations organized as Quick Wins, High-Impact Changes, and Test Ideas. Should note the message match issue between Google Ads and landing page. Should provide 2-3 headline and CTA copy alternatives with rationale.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should identify page type (landing page) and conversion goal (free trial signup). Should analyze across the CRO framework dimensions: value proposition clarity, headline effectiveness, CTA placement/copy/hierarchy, visual hierarchy, trust signals, objection handling, and friction points. Should provide recommendations organized as Quick Wins, High-Impact Changes, and Test Ideas. Should note the message match issue between Google Ads and landing page. Should provide 2-3 headline and CTA copy alternatives with rationale.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Identifies page type as landing page",
|
"Identifies page type as landing page",
|
||||||
"Identifies conversion goal as free trial signup",
|
"Identifies conversion goal as free trial signup",
|
||||||
"Analyzes value proposition clarity",
|
"Analyzes value proposition clarity",
|
||||||
|
|
@ -84,10 +84,8 @@
|
||||||
{
|
{
|
||||||
"id": 6,
|
"id": 6,
|
||||||
"prompt": "Our signup form has too many fields and people keep abandoning it halfway through. Can you help optimize it?",
|
"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 form optimization, not general page CRO. Should defer to or cross-reference the signup-flow-cro skill, which specifically handles signup, registration, and account creation flows. May provide some general friction reduction advice but should make clear that signup-flow-cro is the right skill for this task.",
|
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Recognizes this as signup flow optimization",
|
"Recognizes this as signup flow optimization",
|
||||||
"References or defers to signup-flow-cro skill",
|
|
||||||
"Does not attempt full page-cro analysis on a form"
|
"Does not attempt full page-cro analysis on a form"
|
||||||
],
|
],
|
||||||
"files": []
|
"files": []
|
||||||
|
|
|
||||||
|
|
@ -1,8 +1,11 @@
|
||||||
---
|
---
|
||||||
name: paid-ads
|
name: paid-ads
|
||||||
description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see page-cro."
|
description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), Local Service Ads, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LSA,' 'Local Service Ads,' 'ad budget,' 'cost per click,' 'ad spend,' or 'should I run ads.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see page-cro."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [search, db, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Paid Ads
|
# Paid Ads
|
||||||
|
|
@ -12,31 +15,30 @@ You are an expert performance marketer with direct access to ad platform account
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Campaign Goals
|
### 1. Campaign Goals
|
||||||
- What's the primary objective? (Awareness, traffic, leads, sales, app installs)
|
- What's the primary objective? (Quote leads, phone calls, service bookings)
|
||||||
- What's the target CPA or ROAS?
|
- What's the target CPA or ROAS?
|
||||||
- What's the monthly/weekly budget?
|
- What's the monthly/weekly budget?
|
||||||
- Any constraints? (Brand guidelines, compliance, geographic)
|
- Any constraints? (Service area, seasonal, compliance)
|
||||||
|
|
||||||
### 2. Product & Offer
|
### 2. Service Offering
|
||||||
- What are you promoting? (Product, free trial, lead magnet, demo)
|
- What services? (AC repair, furnace repair, maintenance, installation, emergency)
|
||||||
- What's the landing page URL?
|
- What's your service area?
|
||||||
- What makes this offer compelling?
|
- What makes this offer compelling?
|
||||||
|
|
||||||
### 3. Audience
|
### 3. Audience
|
||||||
- Who is the ideal customer?
|
- Who is the ideal customer? (Homeowners in your service area, age, property type)
|
||||||
- What problem does your product solve for them?
|
- What problem are they solving? ("AC isn't working," "furnace inspection," "spring maintenance")
|
||||||
- What are they searching for or interested in?
|
- Are you local/regional or national?
|
||||||
- Do you have existing customer data for lookalikes?
|
|
||||||
|
|
||||||
### 4. Current State
|
### 4. Current State
|
||||||
- Have you run ads before? What worked/didn't?
|
- Have you run ads before? What worked/didn't?
|
||||||
- Do you have existing pixel/conversion data?
|
- Do you have existing conversion data?
|
||||||
- What's your current funnel conversion rate?
|
- What's your current customer acquisition cost?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -44,11 +46,10 @@ Gather this context (ask if not provided):
|
||||||
|
|
||||||
| Platform | Best For | Use When |
|
| Platform | Best For | Use When |
|
||||||
|----------|----------|----------|
|
|----------|----------|----------|
|
||||||
| **Google Ads** | High-intent search traffic | People actively search for your solution |
|
| **Google Local Service Ads** | HVAC (top use case), phone calls, high intent | You want guaranteed calls, high trust signal |
|
||||||
| **Meta** | Demand generation, visual products | Creating demand, strong creative assets |
|
| **Google Search** | High-intent search traffic | Homeowners searching "AC repair near me" |
|
||||||
| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters, higher price points |
|
| **Meta** | Demand generation, brand building | Creating awareness in off-season, retargeting |
|
||||||
| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X, timely content |
|
| **Google Maps** | Local dominance, reviews | Competing in your service area |
|
||||||
| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -58,31 +59,32 @@ Gather this context (ask if not provided):
|
||||||
|
|
||||||
```
|
```
|
||||||
Account
|
Account
|
||||||
├── Campaign 1: [Objective] - [Audience/Product]
|
├── Campaign 1: LSA - Emergency AC Repair
|
||||||
│ ├── Ad Set 1: [Targeting variation]
|
├── Campaign 2: Search - AC Repair + Furnace Repair
|
||||||
│ │ ├── Ad 1: [Creative variation A]
|
│ ├── Ad Group 1: AC Repair Keywords
|
||||||
│ │ ├── Ad 2: [Creative variation B]
|
│ │ ├── Ad 1: Creative variation A
|
||||||
│ │ └── Ad 3: [Creative variation C]
|
│ │ ├── Ad 2: Creative variation B
|
||||||
│ └── Ad Set 2: [Targeting variation]
|
│ │ └── Ad 3: Creative variation C
|
||||||
└── Campaign 2...
|
│ └── Ad Group 2: Furnace Repair Keywords
|
||||||
|
└── Campaign 3: Retargeting - Website visitors
|
||||||
```
|
```
|
||||||
|
|
||||||
### Naming Conventions
|
### Naming Conventions
|
||||||
|
|
||||||
```
|
```
|
||||||
[Platform]_[Objective]_[Audience]_[Offer]_[Date]
|
[Platform]_[Service]_[Intent]_[Date]
|
||||||
|
|
||||||
Examples:
|
Examples:
|
||||||
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
|
LSA_AC-Repair_Emergency_2024Q1
|
||||||
GOOG_Search_Brand_Demo_Ongoing
|
GOOG-Search_AC-Repair_Service-Area_Ongoing
|
||||||
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
META_Awareness_Off-Season_Mar24
|
||||||
```
|
```
|
||||||
|
|
||||||
### Budget Allocation
|
### Budget Allocation
|
||||||
|
|
||||||
**Testing phase (first 2-4 weeks):**
|
**Testing phase (first 2-4 weeks):**
|
||||||
- 70% to proven/safe campaigns
|
- 60% to proven channels (LSA if you have it)
|
||||||
- 30% to testing new audiences/creative
|
- 40% to testing new services/keywords
|
||||||
|
|
||||||
**Scaling phase:**
|
**Scaling phase:**
|
||||||
- Consolidate budget into winning combinations
|
- Consolidate budget into winning combinations
|
||||||
|
|
@ -91,20 +93,130 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Local Service Ads (LSA) Strategy
|
||||||
|
|
||||||
|
### Why LSA for HVAC
|
||||||
|
|
||||||
|
Local Service Ads are Google's top recommendation for HVAC companies:
|
||||||
|
- Qualified, high-intent calls only
|
||||||
|
- You pay per lead (call), not per click
|
||||||
|
- Top placement above organic search results
|
||||||
|
- Trust signal: Google-vetted badge, background checks, licenses
|
||||||
|
|
||||||
|
### LSA Setup Essentials
|
||||||
|
|
||||||
|
- Google service account connected to Google My Business
|
||||||
|
- Verified business address, license, insurance
|
||||||
|
- Background checks completed for technicians
|
||||||
|
- Service area defined (by zip code or radius)
|
||||||
|
- Response rate: Aim to respond to 90%+ of leads
|
||||||
|
|
||||||
|
### LSA Services to Advertise
|
||||||
|
|
||||||
|
- Emergency AC repair
|
||||||
|
- AC maintenance
|
||||||
|
- Furnace repair
|
||||||
|
- Furnace maintenance
|
||||||
|
- HVAC installation
|
||||||
|
- Seasonal services (AC setup, furnace checkup)
|
||||||
|
|
||||||
|
### Budget & Pacing for LSA
|
||||||
|
|
||||||
|
- Start with $500-1,000/month depending on market
|
||||||
|
- LSA shows highest volume during peak seasons (summer for AC, winter for heat)
|
||||||
|
- Pause or scale down during off-season
|
||||||
|
- Monitor lead quality and response time impact
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Google Search Ads
|
||||||
|
|
||||||
|
### Keyword Strategy by Intent
|
||||||
|
|
||||||
|
**High-intent keywords (immediate need):**
|
||||||
|
- "AC repair near me"
|
||||||
|
- "Emergency furnace repair [city]"
|
||||||
|
- "HVAC repair same day"
|
||||||
|
|
||||||
|
**Medium-intent (comparing options):**
|
||||||
|
- "Best AC repair company [city]"
|
||||||
|
- "Furnace repair cost"
|
||||||
|
- "HVAC maintenance plans"
|
||||||
|
|
||||||
|
**Low-intent (research phase):**
|
||||||
|
- "How to fix AC"
|
||||||
|
- "HVAC system comparison"
|
||||||
|
- "Should I replace furnace or repair"
|
||||||
|
|
||||||
|
### Keyword Targeting Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Campaign: AC Repair
|
||||||
|
├── Ad Group: Emergency AC Repair
|
||||||
|
│ ├── Keywords: emergency ac repair, ac repair now, ac broken
|
||||||
|
│ └── Ad: Emergency AC Repair in [City] — 2-Hour Response
|
||||||
|
└── Ad Group: AC Maintenance
|
||||||
|
├── Keywords: ac maintenance, ac tune-up, spring ac check
|
||||||
|
└── Ad: Spring AC Maintenance — Schedule Your Tune-Up
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Meta (Facebook/Instagram) Strategy
|
||||||
|
|
||||||
|
### Audience Targeting for HVAC
|
||||||
|
|
||||||
|
| Audience | Best For | Targeting |
|
||||||
|
|----------|----------|-----------|
|
||||||
|
| Local homeowners | General demand | Zip code, age 35-65, homeowner |
|
||||||
|
| Previous visitors | Retargeting | Website visitors, past 30/60 days |
|
||||||
|
| Customers (lookalike) | New customers like best ones | Lookalike of customers by LTV |
|
||||||
|
|
||||||
|
### Seasonal Campaigns
|
||||||
|
|
||||||
|
**Summer (May-August):**
|
||||||
|
- Focus on AC repair and maintenance
|
||||||
|
- Cooling, comfort, emergency themes
|
||||||
|
- "Beat the heat" messaging
|
||||||
|
|
||||||
|
**Winter (November-February):**
|
||||||
|
- Focus on furnace repair and maintenance
|
||||||
|
- Warmth, safety, reliability themes
|
||||||
|
- "Don't freeze" messaging
|
||||||
|
|
||||||
|
**Shoulder seasons:**
|
||||||
|
- Maintenance programs
|
||||||
|
- Preventative care messaging
|
||||||
|
- New customer offers
|
||||||
|
|
||||||
|
### Retargeting Hierarchy
|
||||||
|
|
||||||
|
| Audience | Window | Message |
|
||||||
|
|----------|--------|---------|
|
||||||
|
| Hot (quote requesters) | 3-7 days | "Ready to schedule?" |
|
||||||
|
| Warm (service page visitors) | 7-30 days | "See what customers say" |
|
||||||
|
| Cold (any visitor) | 30-90 days | Educational, seasonal |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Ad Copy Frameworks
|
## Ad Copy Frameworks
|
||||||
|
|
||||||
### Key Formulas
|
### Key Formulas for HVAC
|
||||||
|
|
||||||
**Problem-Agitate-Solve (PAS):**
|
**Problem-Solution (Most Common):**
|
||||||
> [Problem] → [Agitate the pain] → [Introduce solution] → [CTA]
|
> [Problem] + [Solution] + [Trust signal] → [CTA]
|
||||||
|
|
||||||
**Before-After-Bridge (BAB):**
|
Example: "AC broken in summer heat? We'll be there in 2 hours. Licensed, insured, family-owned 20 years. Schedule now."
|
||||||
> [Current painful state] → [Desired future state] → [Your product as bridge]
|
|
||||||
|
**Urgency-Based:**
|
||||||
|
> [Problem] + [Consequence] → [Quick solution] + [CTA]
|
||||||
|
|
||||||
|
Example: "Furnace down in winter? Don't wait. Same-day service available. Call now."
|
||||||
|
|
||||||
**Social Proof Lead:**
|
**Social Proof Lead:**
|
||||||
> [Impressive stat or testimonial] → [What you do] → [CTA]
|
> [Stat or testimonial] + [What we do] → [CTA]
|
||||||
|
|
||||||
**For detailed templates and headline formulas**: See [references/ad-copy-templates.md](references/ad-copy-templates.md)
|
Example: "4.9 stars from 1,200+ customers. Emergency HVAC in [City]. Get your free quote."
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -114,85 +226,48 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||||
|
|
||||||
| Platform | Key Targeting | Best Signals |
|
| Platform | Key Targeting | Best Signals |
|
||||||
|----------|---------------|--------------|
|
|----------|---------------|--------------|
|
||||||
| Google | Keywords, search intent | What they're searching |
|
| Google LSA | Service area, intent keywords | Search queries, location |
|
||||||
| Meta | Interests, behaviors, lookalikes | Engagement patterns |
|
| Google Search | Keywords, search intent | What they're searching |
|
||||||
| LinkedIn | Job titles, companies, industries | Professional identity |
|
| Meta | Interests, behaviors, lookalikes | Engagement patterns, zip code |
|
||||||
|
|
||||||
### Key Concepts
|
### Key Concepts
|
||||||
|
|
||||||
- **Lookalikes**: Base on best customers (by LTV), not all customers
|
- **Lookalikes**: Base on best customers (by LTV), not all customers
|
||||||
- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners)
|
- **Exclusions**: Exclude existing customers and competitors
|
||||||
- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend
|
- **Geo-targeting**: Tight geo fences for service area (avoid out-of-area costs)
|
||||||
|
|
||||||
**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Creative Best Practices
|
|
||||||
|
|
||||||
### Image Ads
|
|
||||||
- Clear product screenshots showing UI
|
|
||||||
- Before/after comparisons
|
|
||||||
- Stats and numbers as focal point
|
|
||||||
- Human faces (real, not stock)
|
|
||||||
- Bold, readable text overlay (keep under 20%)
|
|
||||||
|
|
||||||
### Video Ads Structure (15-30 sec)
|
|
||||||
1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
|
|
||||||
2. Problem (3-8 sec): Relatable pain point
|
|
||||||
3. Solution (8-20 sec): Show product/benefit
|
|
||||||
4. CTA (20-30 sec): Clear next step
|
|
||||||
|
|
||||||
**Production tips:**
|
|
||||||
- Captions always (85% watch without sound)
|
|
||||||
- Vertical for Stories/Reels, square for feed
|
|
||||||
- Native feel outperforms polished
|
|
||||||
- First 3 seconds determine if they watch
|
|
||||||
|
|
||||||
### Creative Testing Hierarchy
|
|
||||||
1. Concept/angle (biggest impact)
|
|
||||||
2. Hook/headline
|
|
||||||
3. Visual style
|
|
||||||
4. Body copy
|
|
||||||
5. CTA
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Campaign Optimization
|
## Campaign Optimization
|
||||||
|
|
||||||
### Key Metrics by Objective
|
### Key Metrics by Campaign Type
|
||||||
|
|
||||||
| Objective | Primary Metrics |
|
| Campaign | Primary Metrics |
|
||||||
|-----------|-----------------|
|
|----------|-----------------|
|
||||||
| Awareness | CPM, Reach, Video view rate |
|
| LSA | CPL (cost per lead), call volume, response time |
|
||||||
| Consideration | CTR, CPC, Time on site |
|
| Search | CPA, CTR, quality score |
|
||||||
| Conversion | CPA, ROAS, Conversion rate |
|
| Meta | CPA, ROAS, call conversions |
|
||||||
|
|
||||||
### Optimization Levers
|
### Optimization Levers
|
||||||
|
|
||||||
**If CPA is too high:**
|
**If CPA is too high:**
|
||||||
1. Check landing page (is the problem post-click?)
|
1. Check landing page (is the problem post-click?)
|
||||||
2. Tighten audience targeting
|
2. Tighten geo-targeting (exclude underperforming areas)
|
||||||
3. Test new creative angles
|
3. Test new service keywords or ad angles
|
||||||
4. Improve ad relevance/quality score
|
4. Improve quality score (landing page relevance)
|
||||||
5. Adjust bid strategy
|
5. Adjust bid strategy
|
||||||
|
|
||||||
|
**If call volume too low (LSA/Search):**
|
||||||
|
- Increase budget gradually
|
||||||
|
- Expand keyword match types
|
||||||
|
- Test new ad copy angles
|
||||||
|
- Check response time (respond faster to get more leads)
|
||||||
|
|
||||||
**If CTR is low:**
|
**If CTR is low:**
|
||||||
- Creative isn't resonating → test new hooks/angles
|
- Ad doesn't match search intent → refine keywords
|
||||||
- Audience mismatch → refine targeting
|
- Ad copy isn't compelling → test new angles
|
||||||
- Ad fatigue → refresh creative
|
- Ad fatigue → refresh creative
|
||||||
|
|
||||||
**If CPM is high:**
|
|
||||||
- Audience too narrow → expand targeting
|
|
||||||
- High competition → try different placements
|
|
||||||
- Low relevance score → improve creative fit
|
|
||||||
|
|
||||||
### Bid Strategy Progression
|
|
||||||
1. Start with manual or cost caps
|
|
||||||
2. Gather conversion data (50+ conversions)
|
|
||||||
3. Switch to automated with targets based on historical data
|
|
||||||
4. Monitor and adjust targets based on results
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Retargeting Strategies
|
## Retargeting Strategies
|
||||||
|
|
@ -201,23 +276,22 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||||
|
|
||||||
| Funnel Stage | Audience | Message | Goal |
|
| Funnel Stage | Audience | Message | Goal |
|
||||||
|--------------|----------|---------|------|
|
|--------------|----------|---------|------|
|
||||||
| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
|
| Top | Website visitors | Educational, seasonal | Build awareness |
|
||||||
| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
|
| Middle | Service page visitors | Social proof, guarantees | Move to decision |
|
||||||
| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |
|
| Bottom | Quote requesters | Objection handling, urgency | Convert to phone call |
|
||||||
|
|
||||||
### Retargeting Windows
|
### Retargeting Windows
|
||||||
|
|
||||||
| Stage | Window | Frequency Cap |
|
| Stage | Window | Frequency Cap |
|
||||||
|-------|--------|---------------|
|
|-------|--------|---------------|
|
||||||
| Hot (cart/trial) | 1-7 days | Higher OK |
|
| Hot (quote page) | 1-7 days | Higher OK |
|
||||||
| Warm (key pages) | 7-30 days | 3-5x/week |
|
| Warm (service pages) | 7-30 days | 3-5x/week |
|
||||||
| Cold (any visit) | 30-90 days | 1-2x/week |
|
| Cold (any visit) | 30-90 days | 1-2x/week |
|
||||||
|
|
||||||
### Exclusions to Set Up
|
### Exclusions to Set Up
|
||||||
- Existing customers (unless upsell)
|
- Existing customers (unless upsell/review request)
|
||||||
- Recent converters (7-14 day window)
|
- Recent converters (7-14 day window)
|
||||||
- Bounced visitors (<10 sec)
|
- Bounced visitors (<10 sec)
|
||||||
- Irrelevant pages (careers, support)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -225,91 +299,96 @@ LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||||
|
|
||||||
### Weekly Review
|
### Weekly Review
|
||||||
- Spend vs. budget pacing
|
- Spend vs. budget pacing
|
||||||
- CPA/ROAS vs. targets
|
- CPA/lead volume vs. targets
|
||||||
- Top and bottom performing ads
|
- Top and bottom performing keywords/ads
|
||||||
- Audience performance breakdown
|
- Geographic performance breakdown
|
||||||
- Frequency check (fatigue risk)
|
- Response time and conversion metrics
|
||||||
- Landing page conversion rate
|
|
||||||
|
|
||||||
### Attribution Considerations
|
### Attribution Considerations
|
||||||
- Platform attribution is inflated
|
- Track phone calls (call tracking number)
|
||||||
- Use UTM parameters consistently
|
- Track form submissions
|
||||||
- Compare platform data to GA4
|
- Compare platform data to your CRM
|
||||||
- Look at blended CAC, not just platform CPA
|
- Look at blended CAC, not just platform CPA
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Platform Setup
|
## Platform Setup
|
||||||
|
|
||||||
Before launching campaigns, ensure proper tracking and account setup.
|
|
||||||
|
|
||||||
**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md)
|
|
||||||
|
|
||||||
### Universal Pre-Launch Checklist
|
### Universal Pre-Launch Checklist
|
||||||
- [ ] Conversion tracking tested with real conversion
|
- [ ] Conversion tracking tested (phone calls, form submissions)
|
||||||
- [ ] Landing page loads fast (<3 sec)
|
- [ ] Landing page loads fast (<3 sec)
|
||||||
- [ ] Landing page mobile-friendly
|
- [ ] Landing page mobile-friendly
|
||||||
- [ ] UTM parameters working
|
- [ ] UTM parameters working
|
||||||
- [ ] Budget set correctly
|
- [ ] Budget set correctly
|
||||||
- [ ] Targeting matches intended audience
|
- [ ] Targeting matches service area
|
||||||
|
- [ ] Phone number prominent and clickable
|
||||||
|
|
||||||
|
### LSA Specific
|
||||||
|
- [ ] Google My Business fully optimized
|
||||||
|
- [ ] Background checks completed
|
||||||
|
- [ ] License verification complete
|
||||||
|
- [ ] Service area defined
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Common Mistakes to Avoid
|
## Common Mistakes to Avoid
|
||||||
|
|
||||||
### Strategy
|
### Strategy
|
||||||
- Launching without conversion tracking
|
- Not separating emergency vs. maintenance campaigns
|
||||||
|
- Launching without call tracking
|
||||||
- Too many campaigns (fragmenting budget)
|
- Too many campaigns (fragmenting budget)
|
||||||
- Not giving algorithms enough learning time
|
- Not excluding out-of-service-area locations
|
||||||
- Optimizing for wrong metric
|
|
||||||
|
|
||||||
### Targeting
|
### Targeting
|
||||||
- Audiences too narrow or too broad
|
- Targeting too broadly (national when you're local)
|
||||||
- Not excluding existing customers
|
- Audiences too narrow
|
||||||
- Overlapping audiences competing
|
- Not excluding competitors/non-relevant keywords
|
||||||
|
|
||||||
### Creative
|
### Creative
|
||||||
- Only one ad per ad set
|
- Only one ad per ad group
|
||||||
- Not refreshing creative (fatigue)
|
- Not refreshing creative seasonally
|
||||||
- Mismatch between ad and landing page
|
- Mismatch between ad and landing page intent
|
||||||
|
|
||||||
### Budget
|
### Budget
|
||||||
- Spreading too thin across campaigns
|
- Spreading too thin across too many services
|
||||||
- Making big budget changes (disrupts learning)
|
- Pausing campaigns during learning phase
|
||||||
- Stopping campaigns during learning phase
|
- Not scaling winners
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What platform(s) are you currently running or want to start with?
|
1. What's your primary service and service area?
|
||||||
2. What's your monthly ad budget?
|
2. What's your monthly ad budget?
|
||||||
3. What does a successful conversion look like (and what's it worth)?
|
3. Do you currently use LSA, Google Search, or both?
|
||||||
4. Do you have existing creative assets or need to create them?
|
4. What does a qualified lead cost you?
|
||||||
5. What landing page will ads point to?
|
5. Do you have call tracking set up?
|
||||||
6. Do you have pixel/conversion tracking set up?
|
6. What's your current customer acquisition cost?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tool Integrations
|
## Compendium Integration
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms:
|
This skill can be enhanced using **Compendium** market intelligence and competitor analysis.
|
||||||
|
|
||||||
| Platform | Best For | MCP | Guide |
|
**Relevant Compendium capabilities:**
|
||||||
|----------|----------|:---:|-------|
|
- **Search**: Identify trending HVAC keywords and seasonal demand patterns
|
||||||
| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) |
|
- **Database**: Access HVAC market data and contractor competitive landscape
|
||||||
| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) |
|
- **Analyze**: Extract competitor pricing, service offerings, and marketing messaging
|
||||||
| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
|
|
||||||
| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
|
|
||||||
|
|
||||||
For tracking, see also: [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md)
|
**When to use Compendium:**
|
||||||
|
- Identifying high-volume HVAC keywords in your market
|
||||||
|
- Benchmarking your pricing and positioning against competitors
|
||||||
|
- Understanding seasonal demand trends for budget planning
|
||||||
|
|
||||||
|
See [COMPENDIUM_INTEGRATION.md](../COMPENDIUM_INTEGRATION.md) for detailed workflows.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale
|
- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale
|
||||||
- **copywriting**: For landing page copy that converts ad traffic
|
- **hvac-copywriting**: For landing page copy that converts ad traffic
|
||||||
- **analytics-tracking**: For proper conversion tracking setup
|
- **analytics-tracking**: For proper conversion tracking setup
|
||||||
- **ab-test-setup**: For landing page testing to improve ROAS
|
- **ab-test-setup**: For landing page testing to improve ROAS
|
||||||
- **page-cro**: For optimizing post-click conversion rates
|
- **page-cro**: For optimizing post-click conversion rates
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?",
|
"prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies platform selection guide",
|
"Applies platform selection guide",
|
||||||
"Recommends platforms appropriate for B2B HR audience",
|
"Recommends platforms appropriate for B2B HR audience",
|
||||||
"Recommends campaign structure with naming conventions",
|
"Recommends campaign structure with naming conventions",
|
||||||
|
|
|
||||||
|
|
@ -1,227 +0,0 @@
|
||||||
---
|
|
||||||
name: paywall-upgrade-cro
|
|
||||||
description: When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use when the user mentions "paywall," "upgrade screen," "upgrade modal," "upsell," "feature gate," "convert free to paid," "freemium conversion," "trial expiration screen," "limit reached screen," "plan upgrade prompt," "in-app pricing," "free users won't upgrade," "trial to paid conversion," or "how do I get users to pay." Use this for any in-product moment where you're asking users to upgrade. Distinct from public pricing pages (see page-cro) — this focuses on in-product upgrade moments where the user has already experienced value. For pricing decisions, see pricing-strategy.
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Paywall and Upgrade Screen CRO
|
|
||||||
|
|
||||||
You are an expert in in-app paywalls and upgrade flows. Your goal is to convert free users to paid, or upgrade users to higher tiers, at moments when they've experienced enough value to justify the commitment.
|
|
||||||
|
|
||||||
## Initial Assessment
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` 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 providing recommendations, understand:
|
|
||||||
|
|
||||||
1. **Upgrade Context** - Freemium → Paid? Trial → Paid? Tier upgrade? Feature upsell? Usage limit?
|
|
||||||
|
|
||||||
2. **Product Model** - What's free? What's behind paywall? What triggers prompts? Current conversion rate?
|
|
||||||
|
|
||||||
3. **User Journey** - When does this appear? What have they experienced? What are they trying to do?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### 1. Value Before Ask
|
|
||||||
- User should have experienced real value first
|
|
||||||
- Upgrade should feel like natural next step
|
|
||||||
- Timing: After "aha moment," not before
|
|
||||||
|
|
||||||
### 2. Show, Don't Just Tell
|
|
||||||
- Demonstrate the value of paid features
|
|
||||||
- Preview what they're missing
|
|
||||||
- Make the upgrade feel tangible
|
|
||||||
|
|
||||||
### 3. Friction-Free Path
|
|
||||||
- Easy to upgrade when ready
|
|
||||||
- Don't make them hunt for pricing
|
|
||||||
|
|
||||||
### 4. Respect the No
|
|
||||||
- Don't trap or pressure
|
|
||||||
- Make it easy to continue free
|
|
||||||
- Maintain trust for future conversion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Paywall Trigger Points
|
|
||||||
|
|
||||||
### Feature Gates
|
|
||||||
When user clicks a paid-only feature:
|
|
||||||
- Clear explanation of why it's paid
|
|
||||||
- Show what the feature does
|
|
||||||
- Quick path to unlock
|
|
||||||
- Option to continue without
|
|
||||||
|
|
||||||
### Usage Limits
|
|
||||||
When user hits a limit:
|
|
||||||
- Clear indication of limit reached
|
|
||||||
- Show what upgrading provides
|
|
||||||
- Don't block abruptly
|
|
||||||
|
|
||||||
### Trial Expiration
|
|
||||||
When trial is ending:
|
|
||||||
- Early warnings (7, 3, 1 day)
|
|
||||||
- Clear "what happens" on expiration
|
|
||||||
- Summarize value received
|
|
||||||
|
|
||||||
### Time-Based Prompts
|
|
||||||
After X days of free use:
|
|
||||||
- Gentle upgrade reminder
|
|
||||||
- Highlight unused paid features
|
|
||||||
- Easy to dismiss
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Paywall Screen Components
|
|
||||||
|
|
||||||
1. **Headline** - Focus on what they get: "Unlock [Feature] to [Benefit]"
|
|
||||||
|
|
||||||
2. **Value Demonstration** - Preview, before/after, "With Pro you could..."
|
|
||||||
|
|
||||||
3. **Feature Comparison** - Highlight key differences, current plan marked
|
|
||||||
|
|
||||||
4. **Pricing** - Clear, simple, annual vs. monthly options
|
|
||||||
|
|
||||||
5. **Social Proof** - Customer quotes, "X teams use this"
|
|
||||||
|
|
||||||
6. **CTA** - Specific and value-oriented: "Start Getting [Benefit]"
|
|
||||||
|
|
||||||
7. **Escape Hatch** - Clear "Not now" or "Continue with Free"
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Specific Paywall Types
|
|
||||||
|
|
||||||
### Feature Lock Paywall
|
|
||||||
```
|
|
||||||
[Lock Icon]
|
|
||||||
This feature is available on Pro
|
|
||||||
|
|
||||||
[Feature preview/screenshot]
|
|
||||||
|
|
||||||
[Feature name] helps you [benefit]:
|
|
||||||
• [Capability]
|
|
||||||
• [Capability]
|
|
||||||
|
|
||||||
[Upgrade to Pro - $X/mo]
|
|
||||||
[Maybe Later]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Usage Limit Paywall
|
|
||||||
```
|
|
||||||
You've reached your free limit
|
|
||||||
|
|
||||||
[Progress bar at 100%]
|
|
||||||
|
|
||||||
Free: 3 projects | Pro: Unlimited
|
|
||||||
|
|
||||||
[Upgrade to Pro] [Delete a project]
|
|
||||||
```
|
|
||||||
|
|
||||||
### Trial Expiration Paywall
|
|
||||||
```
|
|
||||||
Your trial ends in 3 days
|
|
||||||
|
|
||||||
What you'll lose:
|
|
||||||
• [Feature used]
|
|
||||||
• [Data created]
|
|
||||||
|
|
||||||
What you've accomplished:
|
|
||||||
• Created X projects
|
|
||||||
|
|
||||||
[Continue with Pro]
|
|
||||||
[Remind me later] [Downgrade]
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Timing and Frequency
|
|
||||||
|
|
||||||
### When to Show
|
|
||||||
- After value moment, before frustration
|
|
||||||
- After activation/aha moment
|
|
||||||
- When hitting genuine limits
|
|
||||||
|
|
||||||
### When NOT to Show
|
|
||||||
- During onboarding (too early)
|
|
||||||
- When they're in a flow
|
|
||||||
- Repeatedly after dismissal
|
|
||||||
|
|
||||||
### Frequency Rules
|
|
||||||
- Limit per session
|
|
||||||
- Cool-down after dismiss (days, not hours)
|
|
||||||
- Track annoyance signals
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Upgrade Flow Optimization
|
|
||||||
|
|
||||||
### From Paywall to Payment
|
|
||||||
- Minimize steps
|
|
||||||
- Keep in-context if possible
|
|
||||||
- Pre-fill known information
|
|
||||||
|
|
||||||
### Post-Upgrade
|
|
||||||
- Immediate access to features
|
|
||||||
- Confirmation and receipt
|
|
||||||
- Guide to new features
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## A/B Testing
|
|
||||||
|
|
||||||
### What to Test
|
|
||||||
- Trigger timing
|
|
||||||
- Headline/copy variations
|
|
||||||
- Price presentation
|
|
||||||
- Trial length
|
|
||||||
- Feature emphasis
|
|
||||||
- Design/layout
|
|
||||||
|
|
||||||
### Metrics to Track
|
|
||||||
- Paywall impression rate
|
|
||||||
- Click-through to upgrade
|
|
||||||
- Completion rate
|
|
||||||
- Revenue per user
|
|
||||||
- Churn rate post-upgrade
|
|
||||||
|
|
||||||
**For comprehensive experiment ideas**: See [references/experiments.md](references/experiments.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Anti-Patterns to Avoid
|
|
||||||
|
|
||||||
### Dark Patterns
|
|
||||||
- Hiding the close button
|
|
||||||
- Confusing plan selection
|
|
||||||
- Guilt-trip copy
|
|
||||||
|
|
||||||
### Conversion Killers
|
|
||||||
- Asking before value delivered
|
|
||||||
- Too frequent prompts
|
|
||||||
- Blocking critical flows
|
|
||||||
- Complicated upgrade process
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task-Specific Questions
|
|
||||||
|
|
||||||
1. What's your current free → paid conversion rate?
|
|
||||||
2. What triggers upgrade prompts today?
|
|
||||||
3. What features are behind the paywall?
|
|
||||||
4. What's your "aha moment" for users?
|
|
||||||
5. What pricing model? (per seat, usage, flat)
|
|
||||||
6. Mobile app, web app, or both?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **churn-prevention**: For cancel flows, save offers, and reducing churn post-upgrade
|
|
||||||
- **page-cro**: For public pricing page optimization
|
|
||||||
- **onboarding-cro**: For driving to aha moment before upgrade
|
|
||||||
- **ab-test-setup**: For testing paywall variations
|
|
||||||
|
|
@ -1,93 +0,0 @@
|
||||||
{
|
|
||||||
"skill_name": "paywall-upgrade-cro",
|
|
||||||
"evals": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"prompt": "Help me design the upgrade paywall for our project management tool. Free users can have 3 projects, and we want to show an upgrade screen when they try to create a 4th project.",
|
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify this as a usage limit trigger point. Should apply the paywall screen components: headline (communicate the value of upgrading, not just the limit), value demonstration (show what they get with paid plan), plan comparison (free vs paid), social proof, CTA (specific and action-oriented), and escape hatch (option to go back). Should provide specific copy recommendations. Should address the emotional state of the user at this moment (frustrated by the limit). Should warn against anti-patterns.",
|
|
||||||
"assertions": [
|
|
||||||
"Checks for product-marketing-context.md",
|
|
||||||
"Identifies as usage limit trigger",
|
|
||||||
"Applies paywall screen components framework",
|
|
||||||
"Includes headline, value demo, comparison, social proof, CTA",
|
|
||||||
"Provides specific copy recommendations",
|
|
||||||
"Addresses user's emotional state at the limit",
|
|
||||||
"Includes escape hatch option",
|
|
||||||
"Warns against anti-patterns"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"prompt": "Our free trial expires in 14 days and users see a generic 'Your trial has expired' screen. Upgrade rate from this screen is only 2%. How do we improve it?",
|
|
||||||
"expected_output": "Should identify this as a trial expiration trigger. Should apply the trial expiration paywall type guidance. Should recommend: show what they've built/accomplished during the trial (endowment effect), highlight specific features they used, show the value they'd lose, provide clear plan options, include social proof from similar users who upgraded. Should diagnose why 2% is low: likely a weak value prop, no personalization, no urgency or loss framing. Should provide specific redesign recommendations.",
|
|
||||||
"assertions": [
|
|
||||||
"Identifies as trial expiration trigger",
|
|
||||||
"Applies trial expiration paywall guidance",
|
|
||||||
"Recommends showing user's accomplishments during trial",
|
|
||||||
"Uses loss framing (what they'd lose)",
|
|
||||||
"Provides clear plan options",
|
|
||||||
"Includes social proof",
|
|
||||||
"Diagnoses why current 2% rate is low",
|
|
||||||
"Provides specific redesign recommendations"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 3,
|
|
||||||
"prompt": "when should we show upgrade prompts? we don't want to be annoying but we also need to convert free users to paid.",
|
|
||||||
"expected_output": "Should trigger on casual phrasing. Should apply the timing and frequency rules. Should recommend trigger points from the skill: feature gates (when they try a paid feature), usage limits (when they hit a threshold), value moments (when they've just experienced success), and natural transition points. Should address frequency capping to avoid being annoying. Should recommend the anti-patterns to avoid (blocking basic functionality, too frequent popups, dark patterns). Should provide a balanced approach that respects user experience while driving upgrades.",
|
|
||||||
"assertions": [
|
|
||||||
"Triggers on casual phrasing",
|
|
||||||
"Applies timing and frequency rules",
|
|
||||||
"Recommends specific trigger points",
|
|
||||||
"Addresses frequency capping",
|
|
||||||
"Warns against anti-patterns",
|
|
||||||
"Balances user experience with conversion goals",
|
|
||||||
"Provides specific recommendations for each trigger type"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 4,
|
|
||||||
"prompt": "Design a feature gate paywall. When free users click on 'Advanced Analytics' in our dashboard, we want to show them an upgrade prompt.",
|
|
||||||
"expected_output": "Should identify this as a feature gate trigger. Should apply the feature lock paywall type guidance. Should recommend: show a preview or screenshot of the advanced analytics feature, explain the specific benefit (not just 'this is a paid feature'), include a plan comparison relevant to analytics, provide a clear CTA to upgrade, and include an escape hatch to go back to basic analytics. Should recommend showing what insights they're missing. Should provide copy recommendations for the paywall screen.",
|
|
||||||
"assertions": [
|
|
||||||
"Identifies as feature gate trigger",
|
|
||||||
"Applies feature lock paywall guidance",
|
|
||||||
"Recommends showing preview of the feature",
|
|
||||||
"Explains specific benefit of the feature",
|
|
||||||
"Includes relevant plan comparison",
|
|
||||||
"Provides clear CTA and escape hatch",
|
|
||||||
"Provides copy recommendations"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 5,
|
|
||||||
"prompt": "What are common mistakes to avoid with in-app paywalls? I don't want to be pushy or make users feel tricked.",
|
|
||||||
"expected_output": "Should apply the anti-patterns section. Should cover: dark patterns (making it hard to find the close button, confusing opt-out language), conversion killers (blocking basic functionality, showing paywalls too early before value is demonstrated, no escape hatch), frequency issues (too many prompts, showing the same paywall repeatedly). Should provide positive alternatives for each anti-pattern. Should emphasize that good paywalls feel helpful, not pushy.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies anti-patterns section",
|
|
||||||
"Covers dark patterns to avoid",
|
|
||||||
"Covers conversion killers",
|
|
||||||
"Covers frequency issues",
|
|
||||||
"Provides positive alternatives for each",
|
|
||||||
"Emphasizes helpful over pushy approach"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 6,
|
|
||||||
"prompt": "Can you help me optimize our public pricing page? We want more visitors to choose the Pro plan over the Basic plan.",
|
|
||||||
"expected_output": "Should recognize this is a public pricing page optimization task, not an in-app paywall task. Should defer to or cross-reference the page-cro skill for pricing page CRO. Paywall-upgrade-cro specifically handles in-app upgrade prompts for existing users, not public-facing pricing pages.",
|
|
||||||
"assertions": [
|
|
||||||
"Recognizes this as public pricing page optimization",
|
|
||||||
"References or defers to page-cro skill",
|
|
||||||
"Explains that paywall-upgrade-cro is for in-app upgrade prompts",
|
|
||||||
"Does not attempt public pricing page optimization"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
@ -1,164 +0,0 @@
|
||||||
# Paywall Experiment Ideas
|
|
||||||
|
|
||||||
Comprehensive list of A/B tests and experiments for paywall optimization.
|
|
||||||
|
|
||||||
## Contents
|
|
||||||
- Trigger & Timing Experiments (When to Show, Trigger Type)
|
|
||||||
- Paywall Design Experiments (Layout & Format, Value Presentation, Visual Elements)
|
|
||||||
- Pricing Presentation Experiments (Price Display, Plan Options, Discounts & Offers)
|
|
||||||
- Copy & Messaging Experiments (Headlines, CTAs, Objection Handling)
|
|
||||||
- Trial & Conversion Experiments (Trial Structure, Trial Expiration, Upgrade Path)
|
|
||||||
- Personalization Experiments (Usage-Based, Segment-Specific)
|
|
||||||
- Frequency & UX Experiments (Frequency Capping, Dismiss Behavior)
|
|
||||||
|
|
||||||
## Trigger & Timing Experiments
|
|
||||||
|
|
||||||
### When to Show
|
|
||||||
- Test trigger timing: after aha moment vs. at feature attempt
|
|
||||||
- Early trial reminder (7 days) vs. late reminder (1 day before)
|
|
||||||
- Show after X actions completed vs. after X days
|
|
||||||
- Test soft prompts at different engagement thresholds
|
|
||||||
- Trigger based on usage patterns vs. time-based only
|
|
||||||
|
|
||||||
### Trigger Type
|
|
||||||
- Hard gate (can't proceed) vs. soft gate (preview + prompt)
|
|
||||||
- Feature lock vs. usage limit as primary trigger
|
|
||||||
- In-context modal vs. dedicated upgrade page
|
|
||||||
- Banner reminder vs. modal prompt
|
|
||||||
- Exit-intent on free plan pages
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Paywall Design Experiments
|
|
||||||
|
|
||||||
### Layout & Format
|
|
||||||
- Full-screen paywall vs. modal overlay
|
|
||||||
- Minimal paywall (CTA-focused) vs. feature-rich paywall
|
|
||||||
- Single plan display vs. plan comparison
|
|
||||||
- Image/preview included vs. text-only
|
|
||||||
- Vertical layout vs. horizontal layout on desktop
|
|
||||||
|
|
||||||
### Value Presentation
|
|
||||||
- Feature list vs. benefit statements
|
|
||||||
- Show what they'll lose (loss aversion) vs. what they'll gain
|
|
||||||
- Personalized value summary based on usage
|
|
||||||
- Before/after demonstration
|
|
||||||
- ROI calculator or value quantification
|
|
||||||
|
|
||||||
### Visual Elements
|
|
||||||
- Add product screenshots or previews
|
|
||||||
- Include short demo video or GIF
|
|
||||||
- Test illustration vs. product imagery
|
|
||||||
- Animated vs. static paywall
|
|
||||||
- Progress visualization (what they've accomplished)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pricing Presentation Experiments
|
|
||||||
|
|
||||||
### Price Display
|
|
||||||
- Show monthly vs. annual vs. both with toggle
|
|
||||||
- Highlight savings for annual ($ amount vs. % off)
|
|
||||||
- Price per day framing ("Less than a coffee")
|
|
||||||
- Show price after trial vs. emphasize "Start Free"
|
|
||||||
- Display price prominently vs. de-emphasize until click
|
|
||||||
|
|
||||||
### Plan Options
|
|
||||||
- Single recommended plan vs. multiple tiers
|
|
||||||
- Add "Most Popular" badge to target plan
|
|
||||||
- Test number of visible plans (2 vs. 3)
|
|
||||||
- Show enterprise/custom tier vs. hide it
|
|
||||||
- Include one-time purchase option alongside subscription
|
|
||||||
|
|
||||||
### Discounts & Offers
|
|
||||||
- First month/year discount for conversion
|
|
||||||
- Limited-time upgrade offer with countdown
|
|
||||||
- Loyalty discount based on free usage duration
|
|
||||||
- Bundle discount for annual commitment
|
|
||||||
- Referral discount for social proof
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Copy & Messaging Experiments
|
|
||||||
|
|
||||||
### Headlines
|
|
||||||
- Benefit-focused ("Unlock unlimited projects") vs. feature-focused ("Get Pro features")
|
|
||||||
- Question format ("Ready to do more?") vs. statement format
|
|
||||||
- Urgency-based ("Don't lose your work") vs. value-based
|
|
||||||
- Personalized headline with user's name or usage data
|
|
||||||
- Social proof headline ("Join 10,000+ Pro users")
|
|
||||||
|
|
||||||
### CTAs
|
|
||||||
- "Start Free Trial" vs. "Upgrade Now" vs. "Continue with Pro"
|
|
||||||
- First person ("Start My Trial") vs. second person ("Start Your Trial")
|
|
||||||
- Value-specific ("Unlock Unlimited") vs. generic ("Upgrade")
|
|
||||||
- Add urgency ("Upgrade Today") vs. no pressure
|
|
||||||
- Include price in CTA vs. separate price display
|
|
||||||
|
|
||||||
### Objection Handling
|
|
||||||
- Add money-back guarantee messaging
|
|
||||||
- Show "Cancel anytime" prominently
|
|
||||||
- Include FAQ on paywall
|
|
||||||
- Address specific objections based on feature gated
|
|
||||||
- Add chat/support option on paywall
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Trial & Conversion Experiments
|
|
||||||
|
|
||||||
### Trial Structure
|
|
||||||
- 7-day vs. 14-day vs. 30-day trial length
|
|
||||||
- Credit card required vs. not required for trial
|
|
||||||
- Full-access trial vs. limited feature trial
|
|
||||||
- Trial extension offer for engaged users
|
|
||||||
- Second trial offer for expired/churned users
|
|
||||||
|
|
||||||
### Trial Expiration
|
|
||||||
- Countdown timer visibility (always vs. near end)
|
|
||||||
- Email reminders: frequency and timing
|
|
||||||
- Grace period after expiration vs. immediate downgrade
|
|
||||||
- "Last chance" offer with discount
|
|
||||||
- Pause option vs. immediate cancellation
|
|
||||||
|
|
||||||
### Upgrade Path
|
|
||||||
- One-click upgrade from paywall vs. separate checkout
|
|
||||||
- Pre-filled payment info for returning users
|
|
||||||
- Multiple payment methods offered
|
|
||||||
- Quarterly plan option alongside monthly/annual
|
|
||||||
- Team invite flow for solo-to-team conversion
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Personalization Experiments
|
|
||||||
|
|
||||||
### Usage-Based
|
|
||||||
- Personalize paywall copy based on features used
|
|
||||||
- Highlight most-used premium features
|
|
||||||
- Show usage stats ("You've created 50 projects")
|
|
||||||
- Recommend plan based on behavior patterns
|
|
||||||
- Dynamic feature emphasis based on user segment
|
|
||||||
|
|
||||||
### Segment-Specific
|
|
||||||
- Different paywall for power users vs. casual users
|
|
||||||
- B2B vs. B2C messaging variations
|
|
||||||
- Industry-specific value propositions
|
|
||||||
- Role-based feature highlighting
|
|
||||||
- Traffic source-based messaging
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Frequency & UX Experiments
|
|
||||||
|
|
||||||
### Frequency Capping
|
|
||||||
- Test number of prompts per session
|
|
||||||
- Cool-down period after dismiss (hours vs. days)
|
|
||||||
- Escalating urgency over time vs. consistent messaging
|
|
||||||
- Once per feature vs. consolidated prompts
|
|
||||||
- Re-show rules after major engagement
|
|
||||||
|
|
||||||
### Dismiss Behavior
|
|
||||||
- "Maybe later" vs. "No thanks" vs. "Remind me tomorrow"
|
|
||||||
- Ask reason for declining
|
|
||||||
- Offer alternative (lower tier, annual discount)
|
|
||||||
- Exit survey on dismiss
|
|
||||||
- Friendly vs. neutral decline copy
|
|
||||||
|
|
@ -1,453 +0,0 @@
|
||||||
---
|
|
||||||
name: popup-cro
|
|
||||||
description: When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also use when the user mentions "exit intent," "popup conversions," "modal optimization," "lead capture popup," "email popup," "announcement banner," "overlay," "collect emails with a popup," "exit popup," "scroll trigger," "sticky bar," or "notification bar." Use this for any overlay or interrupt-style conversion element. For forms outside of popups, see form-cro. For general page conversion optimization, see page-cro.
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Popup CRO
|
|
||||||
|
|
||||||
You are an expert in popup and modal optimization. Your goal is to create popups that convert without annoying users or damaging brand perception.
|
|
||||||
|
|
||||||
## Initial Assessment
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` 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 providing recommendations, understand:
|
|
||||||
|
|
||||||
1. **Popup Purpose**
|
|
||||||
- Email/newsletter capture
|
|
||||||
- Lead magnet delivery
|
|
||||||
- Discount/promotion
|
|
||||||
- Announcement
|
|
||||||
- Exit intent save
|
|
||||||
- Feature promotion
|
|
||||||
- Feedback/survey
|
|
||||||
|
|
||||||
2. **Current State**
|
|
||||||
- Existing popup performance?
|
|
||||||
- What triggers are used?
|
|
||||||
- User complaints or feedback?
|
|
||||||
- Mobile experience?
|
|
||||||
|
|
||||||
3. **Traffic Context**
|
|
||||||
- Traffic sources (paid, organic, direct)
|
|
||||||
- New vs. returning visitors
|
|
||||||
- Page types where shown
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### 1. Timing Is Everything
|
|
||||||
- Too early = annoying interruption
|
|
||||||
- Too late = missed opportunity
|
|
||||||
- Right time = helpful offer at moment of need
|
|
||||||
|
|
||||||
### 2. Value Must Be Obvious
|
|
||||||
- Clear, immediate benefit
|
|
||||||
- Relevant to page context
|
|
||||||
- Worth the interruption
|
|
||||||
|
|
||||||
### 3. Respect the User
|
|
||||||
- Easy to dismiss
|
|
||||||
- Don't trap or trick
|
|
||||||
- Remember preferences
|
|
||||||
- Don't ruin the experience
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Trigger Strategies
|
|
||||||
|
|
||||||
### Time-Based
|
|
||||||
- **Not recommended**: "Show after 5 seconds"
|
|
||||||
- **Better**: "Show after 30-60 seconds" (proven engagement)
|
|
||||||
- Best for: General site visitors
|
|
||||||
|
|
||||||
### Scroll-Based
|
|
||||||
- **Typical**: 25-50% scroll depth
|
|
||||||
- Indicates: Content engagement
|
|
||||||
- Best for: Blog posts, long-form content
|
|
||||||
- Example: "You're halfway through—get more like this"
|
|
||||||
|
|
||||||
### Exit Intent
|
|
||||||
- Detects cursor moving to close/leave
|
|
||||||
- Last chance to capture value
|
|
||||||
- Best for: E-commerce, lead gen
|
|
||||||
- Mobile alternative: Back button or scroll up
|
|
||||||
|
|
||||||
### Click-Triggered
|
|
||||||
- User initiates (clicks button/link)
|
|
||||||
- Zero annoyance factor
|
|
||||||
- Best for: Lead magnets, gated content, demos
|
|
||||||
- Example: "Download PDF" → Popup form
|
|
||||||
|
|
||||||
### Page Count / Session-Based
|
|
||||||
- After visiting X pages
|
|
||||||
- Indicates research/comparison behavior
|
|
||||||
- Best for: Multi-page journeys
|
|
||||||
- Example: "Been comparing? Here's a summary..."
|
|
||||||
|
|
||||||
### Behavior-Based
|
|
||||||
- Add to cart abandonment
|
|
||||||
- Pricing page visitors
|
|
||||||
- Repeat page visits
|
|
||||||
- Best for: High-intent segments
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Popup Types
|
|
||||||
|
|
||||||
### Email Capture Popup
|
|
||||||
**Goal**: Newsletter/list subscription
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Clear value prop (not just "Subscribe")
|
|
||||||
- Specific benefit of subscribing
|
|
||||||
- Single field (email only)
|
|
||||||
- Consider incentive (discount, content)
|
|
||||||
|
|
||||||
**Copy structure:**
|
|
||||||
- Headline: Benefit or curiosity hook
|
|
||||||
- Subhead: What they get, how often
|
|
||||||
- CTA: Specific action ("Get Weekly Tips")
|
|
||||||
|
|
||||||
### Lead Magnet Popup
|
|
||||||
**Goal**: Exchange content for email
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Show what they get (cover image, preview)
|
|
||||||
- Specific, tangible promise
|
|
||||||
- Minimal fields (email, maybe name)
|
|
||||||
- Instant delivery expectation
|
|
||||||
|
|
||||||
### Discount/Promotion Popup
|
|
||||||
**Goal**: First purchase or conversion
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Clear discount (10%, $20, free shipping)
|
|
||||||
- Deadline creates urgency
|
|
||||||
- Single use per visitor
|
|
||||||
- Easy to apply code
|
|
||||||
|
|
||||||
### Exit Intent Popup
|
|
||||||
**Goal**: Last-chance conversion
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Acknowledge they're leaving
|
|
||||||
- Different offer than entry popup
|
|
||||||
- Address common objections
|
|
||||||
- Final compelling reason to stay
|
|
||||||
|
|
||||||
**Formats:**
|
|
||||||
- "Wait! Before you go..."
|
|
||||||
- "Forget something?"
|
|
||||||
- "Get 10% off your first order"
|
|
||||||
- "Questions? Chat with us"
|
|
||||||
|
|
||||||
### Announcement Banner
|
|
||||||
**Goal**: Site-wide communication
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Top of page (sticky or static)
|
|
||||||
- Single, clear message
|
|
||||||
- Dismissable
|
|
||||||
- Links to more info
|
|
||||||
- Time-limited (don't leave forever)
|
|
||||||
|
|
||||||
### Slide-In
|
|
||||||
**Goal**: Less intrusive engagement
|
|
||||||
|
|
||||||
**Best practices:**
|
|
||||||
- Enters from corner/bottom
|
|
||||||
- Doesn't block content
|
|
||||||
- Easy to dismiss or minimize
|
|
||||||
- Good for chat, support, secondary CTAs
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Design Best Practices
|
|
||||||
|
|
||||||
### Visual Hierarchy
|
|
||||||
1. Headline (largest, first seen)
|
|
||||||
2. Value prop/offer (clear benefit)
|
|
||||||
3. Form/CTA (obvious action)
|
|
||||||
4. Close option (easy to find)
|
|
||||||
|
|
||||||
### Sizing
|
|
||||||
- Desktop: 400-600px wide typical
|
|
||||||
- Don't cover entire screen
|
|
||||||
- Mobile: Full-width bottom or center, not full-screen
|
|
||||||
- Leave space to close (visible X, click outside)
|
|
||||||
|
|
||||||
### Close Button
|
|
||||||
- Keep visible (top right is convention) — users who can't find the close button will bounce entirely
|
|
||||||
- Large enough to tap on mobile
|
|
||||||
- "No thanks" text link as alternative
|
|
||||||
- Click outside to close
|
|
||||||
|
|
||||||
### Mobile Considerations
|
|
||||||
- Can't detect exit intent (use alternatives)
|
|
||||||
- Full-screen overlays feel aggressive
|
|
||||||
- Bottom slide-ups work well
|
|
||||||
- Larger touch targets
|
|
||||||
- Easy dismiss gestures
|
|
||||||
|
|
||||||
### Imagery
|
|
||||||
- Product image or preview
|
|
||||||
- Face if relevant (increases trust)
|
|
||||||
- Minimal for speed
|
|
||||||
- Optional—copy can work alone
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Copy Formulas
|
|
||||||
|
|
||||||
### Headlines
|
|
||||||
- Benefit-driven: "Get [result] in [timeframe]"
|
|
||||||
- Question: "Want [desired outcome]?"
|
|
||||||
- Command: "Don't miss [thing]"
|
|
||||||
- Social proof: "Join [X] people who..."
|
|
||||||
- Curiosity: "The one thing [audience] always get wrong about [topic]"
|
|
||||||
|
|
||||||
### Subheadlines
|
|
||||||
- Expand on the promise
|
|
||||||
- Address objection ("No spam, ever")
|
|
||||||
- Set expectations ("Weekly tips in 5 min")
|
|
||||||
|
|
||||||
### CTA Buttons
|
|
||||||
- First person works: "Get My Discount" vs "Get Your Discount"
|
|
||||||
- Specific over generic: "Send Me the Guide" vs "Submit"
|
|
||||||
- Value-focused: "Claim My 10% Off" vs "Subscribe"
|
|
||||||
|
|
||||||
### Decline Options
|
|
||||||
- Polite, not guilt-trippy
|
|
||||||
- "No thanks" / "Maybe later" / "I'm not interested"
|
|
||||||
- Avoid manipulative: "No, I don't want to save money"
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Frequency and Rules
|
|
||||||
|
|
||||||
### Frequency Capping
|
|
||||||
- Show maximum once per session
|
|
||||||
- Remember dismissals (cookie/localStorage)
|
|
||||||
- 7-30 days before showing again
|
|
||||||
- Respect user choice
|
|
||||||
|
|
||||||
### Audience Targeting
|
|
||||||
- New vs. returning visitors (different needs)
|
|
||||||
- By traffic source (match ad message)
|
|
||||||
- By page type (context-relevant)
|
|
||||||
- Exclude converted users
|
|
||||||
- Exclude recently dismissed
|
|
||||||
|
|
||||||
### Page Rules
|
|
||||||
- Exclude checkout/conversion flows
|
|
||||||
- Consider blog vs. product pages
|
|
||||||
- Match offer to page context
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Compliance and Accessibility
|
|
||||||
|
|
||||||
### GDPR/Privacy
|
|
||||||
- Clear consent language
|
|
||||||
- Link to privacy policy
|
|
||||||
- Don't pre-check opt-ins
|
|
||||||
- Honor unsubscribe/preferences
|
|
||||||
|
|
||||||
### Accessibility
|
|
||||||
- Keyboard navigable (Tab, Enter, Esc)
|
|
||||||
- Focus trap while open
|
|
||||||
- Screen reader compatible
|
|
||||||
- Sufficient color contrast
|
|
||||||
- Don't rely on color alone
|
|
||||||
|
|
||||||
### Google Guidelines
|
|
||||||
- Intrusive interstitials hurt SEO
|
|
||||||
- Mobile especially sensitive
|
|
||||||
- Allow: Cookie notices, age verification, reasonable banners
|
|
||||||
- Avoid: Full-screen before content on mobile
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Measurement
|
|
||||||
|
|
||||||
### Key Metrics
|
|
||||||
- **Impression rate**: Visitors who see popup
|
|
||||||
- **Conversion rate**: Impressions → Submissions
|
|
||||||
- **Close rate**: How many dismiss immediately
|
|
||||||
- **Engagement rate**: Interaction before close
|
|
||||||
- **Time to close**: How long before dismissing
|
|
||||||
|
|
||||||
### What to Track
|
|
||||||
- Popup views
|
|
||||||
- Form focus
|
|
||||||
- Submission attempts
|
|
||||||
- Successful submissions
|
|
||||||
- Close button clicks
|
|
||||||
- Outside clicks
|
|
||||||
- Escape key
|
|
||||||
|
|
||||||
### Benchmarks
|
|
||||||
- Email popup: 2-5% conversion typical
|
|
||||||
- Exit intent: 3-10% conversion
|
|
||||||
- Click-triggered: Higher (10%+, self-selected)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Output Format
|
|
||||||
|
|
||||||
### Popup Design
|
|
||||||
- **Type**: Email capture, lead magnet, etc.
|
|
||||||
- **Trigger**: When it appears
|
|
||||||
- **Targeting**: Who sees it
|
|
||||||
- **Frequency**: How often shown
|
|
||||||
- **Copy**: Headline, subhead, CTA, decline
|
|
||||||
- **Design notes**: Layout, imagery, mobile
|
|
||||||
|
|
||||||
### Multiple Popup Strategy
|
|
||||||
If recommending multiple popups:
|
|
||||||
- Popup 1: [Purpose, trigger, audience]
|
|
||||||
- Popup 2: [Purpose, trigger, audience]
|
|
||||||
- Conflict rules: How they don't overlap
|
|
||||||
|
|
||||||
### Test Hypotheses
|
|
||||||
Ideas to A/B test with expected outcomes
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Common Popup Strategies
|
|
||||||
|
|
||||||
### E-commerce
|
|
||||||
1. Entry/scroll: First-purchase discount
|
|
||||||
2. Exit intent: Bigger discount or reminder
|
|
||||||
3. Cart abandonment: Complete your order
|
|
||||||
|
|
||||||
### B2B SaaS
|
|
||||||
1. Click-triggered: Demo request, lead magnets
|
|
||||||
2. Scroll: Newsletter/blog subscription
|
|
||||||
3. Exit intent: Trial reminder or content offer
|
|
||||||
|
|
||||||
### Content/Media
|
|
||||||
1. Scroll-based: Newsletter after engagement
|
|
||||||
2. Page count: Subscribe after multiple visits
|
|
||||||
3. Exit intent: Don't miss future content
|
|
||||||
|
|
||||||
### Lead Generation
|
|
||||||
1. Time-delayed: General list building
|
|
||||||
2. Click-triggered: Specific lead magnets
|
|
||||||
3. Exit intent: Final capture attempt
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Experiment Ideas
|
|
||||||
|
|
||||||
### Placement & Format Experiments
|
|
||||||
|
|
||||||
**Banner Variations**
|
|
||||||
- Top bar vs. banner below header
|
|
||||||
- Sticky banner vs. static banner
|
|
||||||
- Full-width vs. contained banner
|
|
||||||
- Banner with countdown timer vs. without
|
|
||||||
|
|
||||||
**Popup Formats**
|
|
||||||
- Center modal vs. slide-in from corner
|
|
||||||
- Full-screen overlay vs. smaller modal
|
|
||||||
- Bottom bar vs. corner popup
|
|
||||||
- Top announcements vs. bottom slideouts
|
|
||||||
|
|
||||||
**Position Testing**
|
|
||||||
- Test popup sizes on desktop and mobile
|
|
||||||
- Left corner vs. right corner for slide-ins
|
|
||||||
- Test visibility without blocking content
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Trigger Experiments
|
|
||||||
|
|
||||||
**Timing Triggers**
|
|
||||||
- Exit intent vs. 30-second delay vs. 50% scroll depth
|
|
||||||
- Test optimal time delay (10s vs. 30s vs. 60s)
|
|
||||||
- Test scroll depth percentage (25% vs. 50% vs. 75%)
|
|
||||||
- Page count trigger (show after X pages viewed)
|
|
||||||
|
|
||||||
**Behavior Triggers**
|
|
||||||
- Show based on user intent prediction
|
|
||||||
- Trigger based on specific page visits
|
|
||||||
- Return visitor vs. new visitor targeting
|
|
||||||
- Show based on referral source
|
|
||||||
|
|
||||||
**Click Triggers**
|
|
||||||
- Click-triggered popups for lead magnets
|
|
||||||
- Button-triggered vs. link-triggered modals
|
|
||||||
- Test in-content triggers vs. sidebar triggers
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Messaging & Content Experiments
|
|
||||||
|
|
||||||
**Headlines & Copy**
|
|
||||||
- Test attention-grabbing vs. informational headlines
|
|
||||||
- "Limited-time offer" vs. "New feature alert" messaging
|
|
||||||
- Urgency-focused copy vs. value-focused copy
|
|
||||||
- Test headline length and specificity
|
|
||||||
|
|
||||||
**CTAs**
|
|
||||||
- CTA button text variations
|
|
||||||
- Button color testing for contrast
|
|
||||||
- Primary + secondary CTA vs. single CTA
|
|
||||||
- Test decline text (friendly vs. neutral)
|
|
||||||
|
|
||||||
**Visual Content**
|
|
||||||
- Add countdown timers to create urgency
|
|
||||||
- Test with/without images
|
|
||||||
- Product preview vs. generic imagery
|
|
||||||
- Include social proof in popup
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Personalization Experiments
|
|
||||||
|
|
||||||
**Dynamic Content**
|
|
||||||
- Personalize popup based on visitor data
|
|
||||||
- Show industry-specific content
|
|
||||||
- Tailor content based on pages visited
|
|
||||||
- Use progressive profiling (ask more over time)
|
|
||||||
|
|
||||||
**Audience Targeting**
|
|
||||||
- New vs. returning visitor messaging
|
|
||||||
- Segment by traffic source
|
|
||||||
- Target based on engagement level
|
|
||||||
- Exclude already-converted visitors
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Frequency & Rules Experiments
|
|
||||||
|
|
||||||
- Test frequency capping (once per session vs. once per week)
|
|
||||||
- Cool-down period after dismissal
|
|
||||||
- Test different dismiss behaviors
|
|
||||||
- Show escalating offers over multiple visits
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task-Specific Questions
|
|
||||||
|
|
||||||
1. What's the primary goal for this popup?
|
|
||||||
2. What's your current popup performance (if any)?
|
|
||||||
3. What traffic sources are you optimizing for?
|
|
||||||
4. What incentive can you offer?
|
|
||||||
5. Are there compliance requirements (GDPR, etc.)?
|
|
||||||
6. Mobile vs. desktop traffic split?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **form-cro**: For optimizing the form inside the popup
|
|
||||||
- **page-cro**: For the page context around popups
|
|
||||||
- **email-sequence**: For what happens after popup conversion
|
|
||||||
- **ab-test-setup**: For testing popup variations
|
|
||||||
|
|
@ -1,142 +1,201 @@
|
||||||
---
|
---
|
||||||
name: pricing-strategy
|
name: pricing-strategy
|
||||||
description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'pricing tiers,' 'freemium,' 'free trial,' 'packaging,' 'price increase,' 'value metric,' 'Van Westendorp,' 'willingness to pay,' 'monetization,' 'how much should I charge,' 'my pricing is wrong,' 'pricing page,' 'annual vs monthly,' 'per seat pricing,' or 'should I offer a free plan.' Use this whenever someone is figuring out what to charge or how to structure their plans. For in-app upgrade screens, see paywall-upgrade-cro."
|
description: "When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions 'pricing,' 'how much should I charge,' 'pricing tiers,' 'flat-rate vs T&M,' 'maintenance agreement pricing,' 'equipment markup,' 'financing options,' 'price increase,' 'service recovery charge,' or 'monetization.' For referral/affiliate programs, see referral-program. For general page optimization, see page-cro."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [search, db]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Pricing Strategy
|
# HVAC Pricing Strategy
|
||||||
|
|
||||||
You are an expert in SaaS pricing and monetization strategy. Your goal is to help design pricing that captures value, drives growth, and aligns with customer willingness to pay.
|
You are an expert in HVAC service and equipment pricing. Your goal is to help design pricing that captures value, reflects market conditions, and aligns with customer willingness to pay.
|
||||||
|
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Business Context
|
### 1. Business Context
|
||||||
- What type of product? (SaaS, marketplace, e-commerce, service)
|
- What type of work? (Residential service, commercial, installation, maintenance)
|
||||||
- What's your current pricing (if any)?
|
- Geographic market and local competitors
|
||||||
- What's your target market? (SMB, mid-market, enterprise)
|
- Current pricing (if any)
|
||||||
- What's your go-to-market motion? (self-serve, sales-led, hybrid)
|
- Target customer segment (budget, mid-market, premium)
|
||||||
|
|
||||||
### 2. Value & Competition
|
### 2. Value & Competition
|
||||||
- What's the primary value you deliver?
|
- What's the primary value you deliver? (Speed, quality, warranty, expertise)
|
||||||
- What alternatives do customers consider?
|
- What alternatives do customers consider? (DIY, competitors, big box)
|
||||||
- How do competitors price?
|
- How do competitors price?
|
||||||
|
|
||||||
### 3. Current Performance
|
### 3. Current Performance
|
||||||
- What's your current conversion rate?
|
- What's your current closing rate on estimates?
|
||||||
- What's your ARPU and churn rate?
|
- What's your average job size?
|
||||||
- Any feedback on pricing from customers/prospects?
|
- Any feedback on pricing from customers?
|
||||||
|
|
||||||
### 4. Goals
|
### 4. Goals
|
||||||
- Optimizing for growth, revenue, or profitability?
|
- Optimizing for volume, margin, or both?
|
||||||
- Moving upmarket or expanding downmarket?
|
- Capturing market share or defending premium positioning?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pricing Fundamentals
|
## HVAC Pricing Models
|
||||||
|
|
||||||
### The Three Pricing Axes
|
### 1. Flat-Rate Pricing
|
||||||
|
|
||||||
**1. Packaging** — What's included at each tier?
|
**How it works**: Standard price for standard jobs (furnace service, AC tune-up, common repairs)
|
||||||
- Features, limits, support level
|
|
||||||
- How tiers differ from each other
|
|
||||||
|
|
||||||
**2. Pricing Metric** — What do you charge for?
|
**Pros**:
|
||||||
- Per user, per usage, flat fee
|
- Clear, transparent — customers know cost upfront
|
||||||
- How price scales with value
|
- Faster closing (no negotiation)
|
||||||
|
- Easier to market ("Furnace tune-up: $149")
|
||||||
|
|
||||||
**3. Price Point** — How much do you charge?
|
**Cons**:
|
||||||
- The actual dollar amounts
|
- Penalizes efficient technicians
|
||||||
- Perceived value vs. cost
|
- Complex jobs don't fit the model
|
||||||
|
- Regional/seasonal variation hard to capture
|
||||||
|
|
||||||
### Value-Based Pricing
|
**When to use**: Residential service-focused (maintenance, common repairs)
|
||||||
|
|
||||||
Price should be based on value delivered, not cost to serve:
|
**Example pricing**:
|
||||||
|
- AC annual tune-up: $149
|
||||||
- **Customer's perceived value** — The ceiling
|
- Furnace annual tune-up: $149
|
||||||
- **Your price** — Between alternatives and perceived value
|
- Standard repair call: $99 service charge (waived with repair)
|
||||||
- **Next best alternative** — The floor for differentiation
|
- Refrigerant charge: $25/lb
|
||||||
- **Your cost to serve** — Only a baseline, not the basis
|
|
||||||
|
|
||||||
**Key insight:** Price between the next best alternative and perceived value.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Value Metrics
|
### 2. Time & Materials (T&M) Pricing
|
||||||
|
|
||||||
### What is a Value Metric?
|
**How it works**: Charge hourly rate + parts at markup
|
||||||
|
|
||||||
The value metric is what you charge for—it should scale with the value customers receive.
|
**Pros**:
|
||||||
|
- Captures value of complex jobs
|
||||||
|
- Fair for unusual problems
|
||||||
|
- Works for commercial (facility managers expect T&M)
|
||||||
|
|
||||||
**Good value metrics:**
|
**Cons**:
|
||||||
- Align price with value delivered
|
- No price certainty for customer
|
||||||
- Are easy to understand
|
- Slows decision-making
|
||||||
- Scale as customer grows
|
- Requires transparent timekeeping
|
||||||
- Are hard to game
|
|
||||||
|
|
||||||
### Common Value Metrics
|
**When to use**: Commercial, complex diagnostics, large jobs
|
||||||
|
|
||||||
| Metric | Best For | Example |
|
**Example pricing**:
|
||||||
|--------|----------|---------|
|
- Service call: $89 (60 min minimum)
|
||||||
| Per user/seat | Collaboration tools | Slack, Notion |
|
- Technician hourly: $89-149 (depending on seniority)
|
||||||
| Per usage | Variable consumption | AWS, Twilio |
|
- Service manager: $150+
|
||||||
| Per feature | Modular products | HubSpot add-ons |
|
- Parts markup: 20-40%
|
||||||
| Per contact/record | CRM, email tools | Mailchimp |
|
|
||||||
| Per transaction | Payments, marketplaces | Stripe |
|
|
||||||
| Flat fee | Simple products | Basecamp |
|
|
||||||
|
|
||||||
### Choosing Your Value Metric
|
|
||||||
|
|
||||||
Ask: "As a customer uses more of [metric], do they get more value?"
|
|
||||||
- If yes → good value metric
|
|
||||||
- If no → price doesn't align with value
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tier Structure Overview
|
### 3. Hybrid Model (Flat-Rate + T&M)
|
||||||
|
|
||||||
### Good-Better-Best Framework
|
**How it works**: Flat-rate for common jobs, T&M for complex work
|
||||||
|
|
||||||
**Good tier (Entry):** Core features, limited usage, low price
|
**Pros**:
|
||||||
**Better tier (Recommended):** Full features, reasonable limits, anchor price
|
- Captures both markets
|
||||||
**Best tier (Premium):** Everything, advanced features, 2-3x Better price
|
- Clear pricing on simple jobs, fair on complex
|
||||||
|
- Scales with customer sophistication
|
||||||
|
|
||||||
### Tier Differentiation
|
**Cons**:
|
||||||
|
- More complex to manage
|
||||||
|
- Gray area on which jobs fall into each
|
||||||
|
|
||||||
- **Feature gating** — Basic vs. advanced features
|
**When to use**: Mixed residential/commercial, service-focused
|
||||||
- **Usage limits** — Same features, different limits
|
|
||||||
- **Support level** — Email → Priority → Dedicated
|
|
||||||
- **Access** — API, SSO, custom branding
|
|
||||||
|
|
||||||
**For detailed tier structures and persona-based packaging**: See [references/tier-structure.md](references/tier-structure.md)
|
**Example pricing**:
|
||||||
|
- Maintenance tune-ups: Flat-rate
|
||||||
|
- Repairs: Service charge + parts (T&M if diagnosis complex)
|
||||||
|
- Commercial: Primarily T&M with flat minimums
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pricing Research
|
### 4. Maintenance Agreements
|
||||||
|
|
||||||
### Van Westendorp Method
|
**How it works**: Recurring fee for seasonal tune-ups, priority service, and discounts
|
||||||
|
|
||||||
Four questions that identify acceptable price range:
|
**Pros**:
|
||||||
1. Too expensive (wouldn't consider)
|
- Predictable revenue
|
||||||
2. Too cheap (question quality)
|
- Customer retention and loyalty
|
||||||
3. Expensive but might consider
|
- Drives recurring contact points
|
||||||
4. A bargain
|
|
||||||
|
|
||||||
Analyze intersections to find optimal pricing zone.
|
**Cons**:
|
||||||
|
- Requires delivery consistency
|
||||||
|
- Customer acquisition cost amortized over time
|
||||||
|
- Churn risk if service slips
|
||||||
|
|
||||||
### MaxDiff Analysis
|
**When to use**: Always offer as retention tool
|
||||||
|
|
||||||
Identifies which features customers value most:
|
**Example tiers**:
|
||||||
- Show sets of features
|
- **Basic**: One seasonal tune-up + 10% repair discount — $89-129/year
|
||||||
- Ask: Most important? Least important?
|
- **Premium**: 2x tune-ups + 15% repair discount + priority scheduling — $179-249/year
|
||||||
- Results inform tier packaging
|
- **VIP**: 2x tune-ups + free emergency call + 20% repair discount + annual equipment inspection — $299-399/year
|
||||||
|
|
||||||
**For detailed research methods**: See [references/research-methods.md](references/research-methods.md)
|
**Profitability tip**: Maintenance customers spend 30-50% MORE on repairs because they call earlier in failure lifecycle. The true value is the repair revenue, not the agreement fee.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### 5. Equipment Financing Options
|
||||||
|
|
||||||
|
**How it works**: Offer customers financing to reduce upfront cost barrier
|
||||||
|
|
||||||
|
**Financing types**:
|
||||||
|
- **Company-funded**: You finance, you take credit risk (higher margin required)
|
||||||
|
- **Third-party (Affirm, Synchrony, etc.)**: You get paid immediately, customer pays third-party
|
||||||
|
- **HVAC-specific (EnergyFirst, WePayFin)**: Contractor-friendly financing
|
||||||
|
|
||||||
|
**When to use**: Equipment replacement and large installations
|
||||||
|
|
||||||
|
**Impact**: Financing increases close rate on large jobs by 20-40%. The financing fee/cost should be priced into the proposal.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Pricing Strategy Framework
|
||||||
|
|
||||||
|
### 1. Establish Your Baseline
|
||||||
|
|
||||||
|
**Service calls (per hour / per call)**:
|
||||||
|
- Minimum: $75-125
|
||||||
|
- Average: $89-159
|
||||||
|
- Premium: $150-250
|
||||||
|
|
||||||
|
Benchmark against local competitors via:
|
||||||
|
- Calling competitors for quotes
|
||||||
|
- Checking Angi, Yelp, Google reviews (price mentions)
|
||||||
|
- Contacting industry associations (BBB, HVAC associations)
|
||||||
|
|
||||||
|
### 2. Value-Based Pricing Layers
|
||||||
|
|
||||||
|
Rather than simply matching competitors, price based on perceived value:
|
||||||
|
|
||||||
|
**Economic buyer** cares about:
|
||||||
|
- Total cost of ownership (equipment + service costs over 10 years)
|
||||||
|
- Reliability and warranty
|
||||||
|
- Energy efficiency (monthly savings)
|
||||||
|
|
||||||
|
**Frame with value, not just price**:
|
||||||
|
- Instead of "$3,500 for a furnace installation," say "$3,500 for 20 years of reliable heating and $300/year in energy savings"
|
||||||
|
- Show total 10-year cost of ownership vs. repairing an aging system
|
||||||
|
|
||||||
|
### 3. Pricing Tiers by Customer Segment
|
||||||
|
|
||||||
|
**Budget segment** (price-sensitive):
|
||||||
|
- Flat-rate for common jobs
|
||||||
|
- Basic maintenance agreement (1x tune-up)
|
||||||
|
- Used equipment / budget-tier brands
|
||||||
|
|
||||||
|
**Mid-market** (value-conscious):
|
||||||
|
- Flat-rate with optional T&M for diagnosis
|
||||||
|
- Premium maintenance agreement
|
||||||
|
- Mid-tier equipment with good warranty
|
||||||
|
|
||||||
|
**Premium** (quality-focused):
|
||||||
|
- T&M with transparent pricing
|
||||||
|
- Full VIP maintenance agreement
|
||||||
|
- Top-tier equipment with extended warranty and priority service
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -144,88 +203,134 @@ Identifies which features customers value most:
|
||||||
|
|
||||||
### Signs It's Time
|
### Signs It's Time
|
||||||
|
|
||||||
**Market signals:**
|
**Market signals**:
|
||||||
- Competitors have raised prices
|
- Competitors have raised prices
|
||||||
- Prospects don't flinch at price
|
- Customers don't flinch at current price
|
||||||
- "It's so cheap!" feedback
|
- "It's so cheap!" feedback from customers
|
||||||
|
- Job backlogs (you can't serve all demand)
|
||||||
|
|
||||||
**Business signals:**
|
**Business signals**:
|
||||||
- Very high conversion rates (>40%)
|
- High closing rate (>60% on estimates)
|
||||||
- Very low churn (<3% monthly)
|
- Low churn on maintenance agreements
|
||||||
- Strong unit economics
|
- Technician utilization at 80%+
|
||||||
|
|
||||||
**Product signals:**
|
**Product signals**:
|
||||||
- Significant value added since last pricing
|
- You've added value since last price increase
|
||||||
- Product more mature/stable
|
- Service reliability / reputation improved
|
||||||
|
- New capabilities (smart thermostat integration, energy audits)
|
||||||
|
|
||||||
### Price Increase Strategies
|
### Price Increase Strategies
|
||||||
|
|
||||||
1. **Grandfather existing** — New price for new customers only
|
1. **Grandfather existing** — New price for new customers only
|
||||||
2. **Delayed increase** — Announce 3-6 months out
|
2. **Delayed increase** — Announce 2-4 months out (let maintenance customers renew)
|
||||||
3. **Tied to value** — Raise price but add features
|
3. **Tied to value** — Raise price AND add service level
|
||||||
4. **Plan restructure** — Change plans entirely
|
4. **Tiered increase** — Raise premium tier more than standard tier
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pricing Page Best Practices
|
## Seasonal & Market Pricing
|
||||||
|
|
||||||
### Above the Fold
|
### Seasonal Fluctuation
|
||||||
- Clear tier comparison table
|
|
||||||
- Recommended tier highlighted
|
|
||||||
- Monthly/annual toggle
|
|
||||||
- Primary CTA for each tier
|
|
||||||
|
|
||||||
### Common Elements
|
**Peak season (AC: May-Aug, Heating: Oct-Mar)**:
|
||||||
- Feature comparison table
|
- Demand high → prices naturally rise
|
||||||
- Who each tier is for
|
- Reduce discounting
|
||||||
- FAQ section
|
- Implement service recovery surcharge (+$25-50)
|
||||||
- Annual discount callout (17-20%)
|
|
||||||
- Money-back guarantee
|
|
||||||
- Customer logos/trust signals
|
|
||||||
|
|
||||||
### Pricing Psychology
|
**Off-season (Feb, July)**:
|
||||||
- **Anchoring:** Show higher-priced option first
|
- Demand low → aggressive pricing to fill schedule
|
||||||
- **Decoy effect:** Middle tier should be best value
|
- Run "winter tuneup" or "summer cooling check" specials
|
||||||
- **Charm pricing:** $49 vs. $50 (for value-focused)
|
- Offer volume discounts for 2-3 system installs
|
||||||
- **Round pricing:** $50 vs. $49 (for premium)
|
|
||||||
|
### Regional Variation
|
||||||
|
|
||||||
|
Different regions have different pricing expectations:
|
||||||
|
- **Urban**: Higher prices, more competition, brand matters more
|
||||||
|
- **Rural**: Lower prices, less competition, reputation matters more
|
||||||
|
- **Hot climates**: AC focus, seasonal pricing skew high May-Sep
|
||||||
|
- **Cold climates**: Heating focus, seasonal pricing skew high Oct-Apr
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Equipment Pricing & Margin
|
||||||
|
|
||||||
|
### Typical Equipment Markup
|
||||||
|
|
||||||
|
| Category | Typical Markup |
|
||||||
|
|----------|---|
|
||||||
|
| Budget equipment | 15-25% |
|
||||||
|
| Mid-tier equipment | 20-30% |
|
||||||
|
| Premium equipment | 25-35% |
|
||||||
|
| Parts/components | 30-50% |
|
||||||
|
|
||||||
|
**Why markup varies**: Premium equipment often has better margins due to less price-shopping by customers and stronger dealer support.
|
||||||
|
|
||||||
|
### Franchise vs. Independent Equipment Choices
|
||||||
|
|
||||||
|
**Franchise** (Lennox, Goodman, Carrier):
|
||||||
|
- Restricted dealer networks
|
||||||
|
- Price protection (MAP pricing minimum)
|
||||||
|
- Support and training
|
||||||
|
- Can't undercut on price; compete on service
|
||||||
|
|
||||||
|
**Independent** (Daikin, Fujitsu, newer brands):
|
||||||
|
- More pricing flexibility
|
||||||
|
- Less territorial protection
|
||||||
|
- Growing market share in residential
|
||||||
|
- Compete on features and brand differentiation
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Pricing Checklist
|
## Pricing Checklist
|
||||||
|
|
||||||
### Before Setting Prices
|
### Before Setting Prices
|
||||||
- [ ] Defined target customer personas
|
- [ ] Analyzed competitor pricing in your market
|
||||||
- [ ] Researched competitor pricing
|
- [ ] Surveyed customer willingness to pay
|
||||||
- [ ] Identified your value metric
|
- [ ] Defined your value proposition vs. competitors
|
||||||
- [ ] Conducted willingness-to-pay research
|
- [ ] Estimated cost to deliver (labor + parts)
|
||||||
- [ ] Mapped features to tiers
|
- [ ] Calculated target margin by service type
|
||||||
|
|
||||||
### Pricing Structure
|
### Pricing Structure
|
||||||
- [ ] Chosen number of tiers
|
- [ ] Chosen pricing model (flat-rate, T&M, hybrid)
|
||||||
- [ ] Differentiated tiers clearly
|
- [ ] Set specific prices for common services
|
||||||
- [ ] Set price points based on research
|
- [ ] Defined maintenance agreement tiers
|
||||||
- [ ] Created annual discount strategy
|
- [ ] Set financing options
|
||||||
- [ ] Planned enterprise/custom tier
|
- [ ] Documented service recovery charges and upcharges
|
||||||
|
|
||||||
|
### Communication
|
||||||
|
- [ ] Website displays pricing (or clear process to get quote)
|
||||||
|
- [ ] Technicians trained on pricing and justification
|
||||||
|
- [ ] Estimate process includes value explanation
|
||||||
|
- [ ] Sales team briefed on competitive positioning
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What pricing research have you done?
|
1. What's your current pricing (if any) and how is it performing?
|
||||||
2. What's your current ARPU and conversion rate?
|
2. What's your average job size and margin target?
|
||||||
3. What's your primary value metric?
|
3. What local competitors exist and how do they price?
|
||||||
4. Who are your main pricing personas?
|
4. Are you residential, commercial, or both?
|
||||||
5. Are you self-serve, sales-led, or hybrid?
|
5. What service types do you offer (maintenance, repair, installation)?
|
||||||
6. What pricing changes are you considering?
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to support pricing strategy:
|
||||||
|
|
||||||
|
- **Market research**: Search competitor pricing, equipment costs, regional variation
|
||||||
|
- **Customer insights**: Analyze customer review mentions of pricing and value
|
||||||
|
- **Industry benchmarks**: Access HVAC pricing data and trends
|
||||||
|
|
||||||
|
**Tool tiers**: Search, database queries
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **churn-prevention**: For cancel flows, save offers, and reducing revenue churn
|
|
||||||
- **page-cro**: For optimizing pricing page conversion
|
- **page-cro**: For optimizing pricing page conversion
|
||||||
- **copywriting**: For pricing page copy
|
- **copywriting**: For pricing page copy and value proposition
|
||||||
- **marketing-psychology**: For pricing psychology principles
|
- **marketing-psychology**: For pricing psychology (charm pricing, anchoring)
|
||||||
- **ab-test-setup**: For testing pricing changes
|
- **hvac-lead-ops**: For deal desk and pricing exceptions
|
||||||
- **revops**: For deal desk processes and pipeline pricing
|
- **sales-enablement**: For equipment proposals and pricing presentations
|
||||||
- **sales-enablement**: For proposal templates and pricing presentations
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me figure out pricing for our new SaaS product. It's a customer support platform for e-commerce stores. We're not sure whether to charge per agent, per ticket, or flat rate. Currently thinking $49-199/month range.",
|
"prompt": "Help me figure out pricing for our new SaaS product. It's a customer support platform for e-commerce stores. We're not sure whether to charge per agent, per ticket, or flat rate. Currently thinking $49-199/month range.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the three pricing axes framework: packaging (what's included in each tier), pricing metric (per agent, per ticket, flat rate — evaluate each), price point ($49-199 range evaluation). Should discuss value metrics and which aligns best with value delivered (per agent is common in support, but per ticket aligns with usage). Should recommend a good-better-best tier structure. Should address pricing psychology. Should provide a specific pricing recommendation with rationale.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the three pricing axes framework: packaging (what's included in each tier), pricing metric (per agent, per ticket, flat rate — evaluate each), price point ($49-199 range evaluation). Should discuss value metrics and which aligns best with value delivered (per agent is common in support, but per ticket aligns with usage). Should recommend a good-better-best tier structure. Should address pricing psychology. Should provide a specific pricing recommendation with rationale.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies three pricing axes framework",
|
"Applies three pricing axes framework",
|
||||||
"Evaluates multiple pricing metrics",
|
"Evaluates multiple pricing metrics",
|
||||||
"Discusses which metric aligns with value delivered",
|
"Discusses which metric aligns with value delivered",
|
||||||
|
|
|
||||||
|
|
@ -1,241 +0,0 @@
|
||||||
---
|
|
||||||
name: product-marketing-context
|
|
||||||
description: "When the user wants to create or update their product marketing context document. Also use when the user mentions 'product context,' 'marketing context,' 'set up context,' 'positioning,' 'who is my target audience,' 'describe my product,' 'ICP,' 'ideal customer profile,' or wants to avoid repeating foundational information across marketing tasks. Use this at the start of any new project before using other marketing skills — it creates `.agents/product-marketing-context.md` that all other skills reference for product, audience, and positioning context."
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Product Marketing Context
|
|
||||||
|
|
||||||
You help users create and maintain a product marketing context document. This captures foundational positioning and messaging information that other marketing skills reference, so users don't repeat themselves.
|
|
||||||
|
|
||||||
The document is stored at `.agents/product-marketing-context.md`.
|
|
||||||
|
|
||||||
## Workflow
|
|
||||||
|
|
||||||
### Step 1: Check for Existing Context
|
|
||||||
|
|
||||||
First, check if `.agents/product-marketing-context.md` already exists. Also check `.claude/product-marketing-context.md` for older setups — if found there but not in `.agents/`, offer to move it.
|
|
||||||
|
|
||||||
**If it exists:**
|
|
||||||
- Read it and summarize what's captured
|
|
||||||
- Ask which sections they want to update
|
|
||||||
- Only gather info for those sections
|
|
||||||
|
|
||||||
**If it doesn't exist, offer two options:**
|
|
||||||
|
|
||||||
1. **Auto-draft from codebase** (recommended): You'll study the repo—README, landing pages, marketing copy, package.json, etc.—and draft a V1 of the context document. The user then reviews, corrects, and fills gaps. This is faster than starting from scratch.
|
|
||||||
|
|
||||||
2. **Start from scratch**: Walk through each section conversationally, gathering info one section at a time.
|
|
||||||
|
|
||||||
Most users prefer option 1. After presenting the draft, ask: "What needs correcting? What's missing?"
|
|
||||||
|
|
||||||
### Step 2: Gather Information
|
|
||||||
|
|
||||||
**If auto-drafting:**
|
|
||||||
1. Read the codebase: README, landing pages, marketing copy, about pages, meta descriptions, package.json, any existing docs
|
|
||||||
2. Draft all sections based on what you find
|
|
||||||
3. Present the draft and ask what needs correcting or is missing
|
|
||||||
4. Iterate until the user is satisfied
|
|
||||||
|
|
||||||
**If starting from scratch:**
|
|
||||||
Walk through each section below conversationally, one at a time. Don't dump all questions at once.
|
|
||||||
|
|
||||||
For each section:
|
|
||||||
1. Briefly explain what you're capturing
|
|
||||||
2. Ask relevant questions
|
|
||||||
3. Confirm accuracy
|
|
||||||
4. Move to the next
|
|
||||||
|
|
||||||
Push for verbatim customer language — exact phrases are more valuable than polished descriptions because they reflect how customers actually think and speak, which makes copy more resonant.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Sections to Capture
|
|
||||||
|
|
||||||
### 1. Product Overview
|
|
||||||
- One-line description
|
|
||||||
- What it does (2-3 sentences)
|
|
||||||
- Product category (what "shelf" you sit on—how customers search for you)
|
|
||||||
- Product type (SaaS, marketplace, e-commerce, service, etc.)
|
|
||||||
- Business model and pricing
|
|
||||||
|
|
||||||
### 2. Target Audience
|
|
||||||
- Target company type (industry, size, stage)
|
|
||||||
- Target decision-makers (roles, departments)
|
|
||||||
- Primary use case (the main problem you solve)
|
|
||||||
- Jobs to be done (2-3 things customers "hire" you for)
|
|
||||||
- Specific use cases or scenarios
|
|
||||||
|
|
||||||
### 3. Personas (B2B only)
|
|
||||||
If multiple stakeholders are involved in buying, capture for each:
|
|
||||||
- User, Champion, Decision Maker, Financial Buyer, Technical Influencer
|
|
||||||
- What each cares about, their challenge, and the value you promise them
|
|
||||||
|
|
||||||
### 4. Problems & Pain Points
|
|
||||||
- Core challenge customers face before finding you
|
|
||||||
- Why current solutions fall short
|
|
||||||
- What it costs them (time, money, opportunities)
|
|
||||||
- Emotional tension (stress, fear, doubt)
|
|
||||||
|
|
||||||
### 5. Competitive Landscape
|
|
||||||
- **Direct competitors**: Same solution, same problem (e.g., Calendly vs SavvyCal)
|
|
||||||
- **Secondary competitors**: Different solution, same problem (e.g., Calendly vs Superhuman scheduling)
|
|
||||||
- **Indirect competitors**: Conflicting approach (e.g., Calendly vs personal assistant)
|
|
||||||
- How each falls short for customers
|
|
||||||
|
|
||||||
### 6. Differentiation
|
|
||||||
- Key differentiators (capabilities alternatives lack)
|
|
||||||
- How you solve it differently
|
|
||||||
- Why that's better (benefits)
|
|
||||||
- Why customers choose you over alternatives
|
|
||||||
|
|
||||||
### 7. Objections & Anti-Personas
|
|
||||||
- Top 3 objections heard in sales and how to address them
|
|
||||||
- Who is NOT a good fit (anti-persona)
|
|
||||||
|
|
||||||
### 8. Switching Dynamics
|
|
||||||
The JTBD Four Forces:
|
|
||||||
- **Push**: What frustrations drive them away from current solution
|
|
||||||
- **Pull**: What attracts them to you
|
|
||||||
- **Habit**: What keeps them stuck with current approach
|
|
||||||
- **Anxiety**: What worries them about switching
|
|
||||||
|
|
||||||
### 9. Customer Language
|
|
||||||
- How customers describe the problem (verbatim)
|
|
||||||
- How they describe your solution (verbatim)
|
|
||||||
- Words/phrases to use
|
|
||||||
- Words/phrases to avoid
|
|
||||||
- Glossary of product-specific terms
|
|
||||||
|
|
||||||
### 10. Brand Voice
|
|
||||||
- Tone (professional, casual, playful, etc.)
|
|
||||||
- Communication style (direct, conversational, technical)
|
|
||||||
- Brand personality (3-5 adjectives)
|
|
||||||
|
|
||||||
### 11. Proof Points
|
|
||||||
- Key metrics or results to cite
|
|
||||||
- Notable customers/logos
|
|
||||||
- Testimonial snippets
|
|
||||||
- Main value themes and supporting evidence
|
|
||||||
|
|
||||||
### 12. Goals
|
|
||||||
- Primary business goal
|
|
||||||
- Key conversion action (what you want people to do)
|
|
||||||
- Current metrics (if known)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Step 3: Create the Document
|
|
||||||
|
|
||||||
After gathering information, create `.agents/product-marketing-context.md` with this structure:
|
|
||||||
|
|
||||||
```markdown
|
|
||||||
# Product Marketing Context
|
|
||||||
|
|
||||||
*Last updated: [date]*
|
|
||||||
|
|
||||||
## Product Overview
|
|
||||||
**One-liner:**
|
|
||||||
**What it does:**
|
|
||||||
**Product category:**
|
|
||||||
**Product type:**
|
|
||||||
**Business model:**
|
|
||||||
|
|
||||||
## Target Audience
|
|
||||||
**Target companies:**
|
|
||||||
**Decision-makers:**
|
|
||||||
**Primary use case:**
|
|
||||||
**Jobs to be done:**
|
|
||||||
-
|
|
||||||
**Use cases:**
|
|
||||||
-
|
|
||||||
|
|
||||||
## Personas
|
|
||||||
| Persona | Cares about | Challenge | Value we promise |
|
|
||||||
|---------|-------------|-----------|------------------|
|
|
||||||
| | | | |
|
|
||||||
|
|
||||||
## Problems & Pain Points
|
|
||||||
**Core problem:**
|
|
||||||
**Why alternatives fall short:**
|
|
||||||
-
|
|
||||||
**What it costs them:**
|
|
||||||
**Emotional tension:**
|
|
||||||
|
|
||||||
## Competitive Landscape
|
|
||||||
**Direct:** [Competitor] — falls short because...
|
|
||||||
**Secondary:** [Approach] — falls short because...
|
|
||||||
**Indirect:** [Alternative] — falls short because...
|
|
||||||
|
|
||||||
## Differentiation
|
|
||||||
**Key differentiators:**
|
|
||||||
-
|
|
||||||
**How we do it differently:**
|
|
||||||
**Why that's better:**
|
|
||||||
**Why customers choose us:**
|
|
||||||
|
|
||||||
## Objections
|
|
||||||
| Objection | Response |
|
|
||||||
|-----------|----------|
|
|
||||||
| | |
|
|
||||||
|
|
||||||
**Anti-persona:**
|
|
||||||
|
|
||||||
## Switching Dynamics
|
|
||||||
**Push:**
|
|
||||||
**Pull:**
|
|
||||||
**Habit:**
|
|
||||||
**Anxiety:**
|
|
||||||
|
|
||||||
## Customer Language
|
|
||||||
**How they describe the problem:**
|
|
||||||
- "[verbatim]"
|
|
||||||
**How they describe us:**
|
|
||||||
- "[verbatim]"
|
|
||||||
**Words to use:**
|
|
||||||
**Words to avoid:**
|
|
||||||
**Glossary:**
|
|
||||||
| Term | Meaning |
|
|
||||||
|------|---------|
|
|
||||||
| | |
|
|
||||||
|
|
||||||
## Brand Voice
|
|
||||||
**Tone:**
|
|
||||||
**Style:**
|
|
||||||
**Personality:**
|
|
||||||
|
|
||||||
## Proof Points
|
|
||||||
**Metrics:**
|
|
||||||
**Customers:**
|
|
||||||
**Testimonials:**
|
|
||||||
> "[quote]" — [who]
|
|
||||||
**Value themes:**
|
|
||||||
| Theme | Proof |
|
|
||||||
|-------|-------|
|
|
||||||
| | |
|
|
||||||
|
|
||||||
## Goals
|
|
||||||
**Business goal:**
|
|
||||||
**Conversion action:**
|
|
||||||
**Current metrics:**
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Step 4: Confirm and Save
|
|
||||||
|
|
||||||
- Show the completed document
|
|
||||||
- Ask if anything needs adjustment
|
|
||||||
- Save to `.agents/product-marketing-context.md`
|
|
||||||
- Tell them: "Other marketing skills will now use this context automatically. Run `/product-marketing-context` anytime to update it."
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tips
|
|
||||||
|
|
||||||
- **Be specific**: Ask "What's the #1 frustration that brings them to you?" not "What problem do they solve?"
|
|
||||||
- **Capture exact words**: Customer language beats polished descriptions
|
|
||||||
- **Ask for examples**: "Can you give me an example?" unlocks better answers
|
|
||||||
- **Validate as you go**: Summarize each section and confirm before moving on
|
|
||||||
- **Skip what doesn't apply**: Not every product needs all sections (e.g., Personas for B2C)
|
|
||||||
|
|
@ -1,28 +1,31 @@
|
||||||
---
|
---
|
||||||
name: programmatic-seo
|
name: programmatic-seo
|
||||||
description: When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "directory pages," "location pages," "[keyword] + [city] pages," "comparison pages," "integration pages," "building many pages for SEO," "pSEO," "generate 100 pages," "data-driven pages," or "templated landing pages." Use this whenever someone wants to create many similar pages targeting different keywords or locations. For auditing existing SEO issues, see seo-audit. For content strategy planning, see content-strategy.
|
description: When the user wants to create SEO-driven pages at scale for HVAC contractors or brands using templates and data. Also use when the user mentions "programmatic SEO," "template pages," "pages at scale," "service location pages," "[service] in [city] pages," "comparison pages," "equipment pages," "building many pages for SEO," "pSEO," "location pages," "service area pages," or "generate 100 pages." Use this whenever someone wants to create many similar pages targeting different service areas, services, or equipment models. For auditing existing SEO issues, see seo-audit. For content strategy planning, see content-strategy.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, search, scrape]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Programmatic SEO
|
# Programmatic SEO
|
||||||
|
|
||||||
You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.
|
You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide genuine value to HVAC buyers, and avoid thin content penalties.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 designing a programmatic SEO strategy, understand:
|
Before designing a programmatic SEO strategy, understand:
|
||||||
|
|
||||||
1. **Business Context**
|
1. **Business Context**
|
||||||
- What's the product/service?
|
- What HVAC services/products offered?
|
||||||
- Who is the target audience?
|
- Single location or multi-location network?
|
||||||
- What's the conversion goal for these pages?
|
- What's the conversion goal for these pages?
|
||||||
|
|
||||||
2. **Opportunity Assessment**
|
2. **Opportunity Assessment**
|
||||||
- What search patterns exist?
|
- What search patterns exist? (e.g., "HVAC repair in [City]", "[Brand] [Equipment] pricing")
|
||||||
- How many potential pages?
|
- How many potential pages?
|
||||||
- What's the search volume distribution?
|
- What's the search volume distribution?
|
||||||
|
|
||||||
|
|
@ -42,22 +45,22 @@ Before designing a programmatic SEO strategy, understand:
|
||||||
|
|
||||||
### 2. Proprietary Data Wins
|
### 2. Proprietary Data Wins
|
||||||
Hierarchy of data defensibility:
|
Hierarchy of data defensibility:
|
||||||
1. Proprietary (you created it)
|
1. Proprietary (you created it — case studies, price quotes)
|
||||||
2. Product-derived (from your users)
|
2. Product-derived (from your customers — installation data, reviews)
|
||||||
3. User-generated (your community)
|
3. User-generated (your community)
|
||||||
4. Licensed (exclusive access)
|
4. Licensed (exclusive access)
|
||||||
5. Public (anyone can use—weakest)
|
5. Public (anyone can use—weakest)
|
||||||
|
|
||||||
### 3. Clean URL Structure
|
### 3. Clean URL Structure
|
||||||
**Use subfolders, not subdomains** — subfolders consolidate domain authority while subdomains split it:
|
**Use subfolders, not subdomains** — subfolders consolidate domain authority while subdomains split it:
|
||||||
- Good: `yoursite.com/templates/resume/`
|
- Good: `yoursite.com/services/ac-repair/` or `yoursite.com/denver/`
|
||||||
- Bad: `templates.yoursite.com/resume/`
|
- Bad: `denver.yoursite.com/` or `ac-repair.yoursite.com/`
|
||||||
|
|
||||||
### 4. Genuine Search Intent Match
|
### 4. Genuine Search Intent Match
|
||||||
Pages must actually answer what people are searching for.
|
Pages must actually answer what people are searching for ("HVAC repair in Denver" should provide local repair info, not just company description).
|
||||||
|
|
||||||
### 5. Quality Over Quantity
|
### 5. Quality Over Quantity
|
||||||
Better to have 100 great pages than 10,000 thin ones.
|
Better to have 50 great service-location pages than 500 thin ones.
|
||||||
|
|
||||||
### 6. Avoid Google Penalties
|
### 6. Avoid Google Penalties
|
||||||
- No doorway pages
|
- No doorway pages
|
||||||
|
|
@ -67,41 +70,34 @@ Better to have 100 great pages than 10,000 thin ones.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## The 12 Playbooks (Overview)
|
## The HVAC pSEO Playbooks
|
||||||
|
|
||||||
| Playbook | Pattern | Example |
|
| Playbook | Pattern | Example | Volume |
|
||||||
|----------|---------|---------|
|
|----------|---------|---------|--------|
|
||||||
| Templates | "[Type] template" | "resume template" |
|
| Service + Location | "[Service] in [City]" | "AC Repair in Denver" | High |
|
||||||
| Curation | "best [category]" | "best website builders" |
|
| Service Pages | "[HVAC Service] explained" | "Furnace Repair" or "HVAC Maintenance Plans" | Medium |
|
||||||
| Conversions | "[X] to [Y]" | "$10 USD to GBP" |
|
| Equipment | "[Brand] [Model] review/pricing" | "Carrier 25HCE436A013 price" | Medium |
|
||||||
| Comparisons | "[X] vs [Y]" | "webflow vs wordpress" |
|
| Comparisons | "[Brand] vs [Brand]" or "[Service] vs [Service]" | "Carrier vs Trane" or "HVAC Repair vs Replacement" | Medium |
|
||||||
| Examples | "[type] examples" | "landing page examples" |
|
| Guides | "How to [common HVAC task]" | "How to change your HVAC filter" | Medium |
|
||||||
| Locations | "[service] in [location]" | "dentists in austin" |
|
| Glossary | "What is [HVAC term]" | "What is SEER rating" | Low-Medium |
|
||||||
| Personas | "[product] for [audience]" | "crm for real estate" |
|
| Directory | "[Type] near me" | "HVAC contractor near me" | Low |
|
||||||
| Integrations | "[product A] [product B] integration" | "slack asana integration" |
|
| Technician Profiles | "[Technician Name] - [Service Area]" | Service area-specific bios | Low |
|
||||||
| Glossary | "what is [term]" | "what is pSEO" |
|
|
||||||
| Translations | Content in multiple languages | Localized content |
|
|
||||||
| Directory | "[category] tools" | "ai copywriting tools" |
|
|
||||||
| Profiles | "[entity name]" | "stripe ceo" |
|
|
||||||
|
|
||||||
**For detailed playbook implementation**: See [references/playbooks.md](references/playbooks.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Choosing Your Playbook
|
## Choosing Your Playbooks
|
||||||
|
|
||||||
| If you have... | Consider... |
|
| If you have... | Consider... |
|
||||||
|----------------|-------------|
|
|----------------|-------------|
|
||||||
| Proprietary data | Directories, Profiles |
|
| Multiple service areas | Service + Location pages |
|
||||||
| Product with integrations | Integrations |
|
| Multiple service offerings | Service pages + Location matrix |
|
||||||
| Design/creative product | Templates, Examples |
|
| Equipment partnerships (Carrier, Trane) | Equipment review pages |
|
||||||
| Multi-segment audience | Personas |
|
| Technician team | Technician profile pages per location |
|
||||||
| Local presence | Locations |
|
| Strong competitor positioning | Comparison pages |
|
||||||
| Tool or utility product | Conversions |
|
| Technical expertise | How-to guides and glossary |
|
||||||
| Content/expertise | Glossary, Curation |
|
| Case studies or customer data | Success story pages per service/location |
|
||||||
| Competitor landscape | Comparisons |
|
|
||||||
|
|
||||||
You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
|
You can layer multiple playbooks (e.g., "Best furnace installation companies in Denver").
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -110,42 +106,59 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
|
||||||
### 1. Keyword Pattern Research
|
### 1. Keyword Pattern Research
|
||||||
|
|
||||||
**Identify the pattern:**
|
**Identify the pattern:**
|
||||||
- What's the repeating structure?
|
- Service + Location: "[HVAC Repair] in [City]"
|
||||||
- What are the variables?
|
- Equipment: "[Brand] [Model] [Query]"
|
||||||
|
- Comparison: "[Brand A] vs [Brand B]"
|
||||||
|
- What are the repeating variables?
|
||||||
- How many unique combinations exist?
|
- How many unique combinations exist?
|
||||||
|
|
||||||
**Validate demand:**
|
**Validate demand:**
|
||||||
- Aggregate search volume
|
- Aggregate search volume across pattern
|
||||||
- Volume distribution (head vs. long tail)
|
- Volume distribution (head vs. long tail)
|
||||||
- Trend direction
|
- Trend direction
|
||||||
|
- Seasonality (HVAC demand is seasonal)
|
||||||
|
|
||||||
### 2. Data Requirements
|
### 2. Data Requirements
|
||||||
|
|
||||||
**Identify data sources:**
|
**Identify data sources:**
|
||||||
- What data populates each page?
|
- Service-location matrix: What services in what areas?
|
||||||
- Is it first-party, scraped, licensed, public?
|
- Equipment data: Brand partnerships, pricing, specs?
|
||||||
- How is it updated?
|
- Location data: Cities served, local landmarks, weather patterns?
|
||||||
|
- Customer data: Testimonials, case studies per service-area combo?
|
||||||
|
- Is data first-party, scraped, licensed, or public?
|
||||||
|
- How is it updated? (Quarterly? Real-time?)
|
||||||
|
|
||||||
### 3. Template Design
|
### 3. Template Design
|
||||||
|
|
||||||
**Page structure:**
|
**Page structure (Service + Location example):**
|
||||||
- Header with target keyword
|
1. Headline with service and location ("HVAC Repair in Denver")
|
||||||
- Unique intro (not just variables swapped)
|
2. Unique intro (local problem statement, not just boilerplate)
|
||||||
- Data-driven sections
|
3. Why this service matters in this area (seasonal demand, local climate)
|
||||||
- Related pages / internal links
|
4. Service details (what you offer, what's included)
|
||||||
- CTAs appropriate to intent
|
5. Local social proof (testimonials, nearby projects)
|
||||||
|
6. Pricing/availability for the area
|
||||||
|
7. Related services in the same location
|
||||||
|
8. Related locations for same service
|
||||||
|
9. Call to action (book service, get quote)
|
||||||
|
|
||||||
**Ensuring uniqueness:**
|
**Ensuring uniqueness:**
|
||||||
- Each page needs unique value
|
- Each page needs unique local content (not just city name swap)
|
||||||
- Conditional content based on data
|
- Conditional content based on data (e.g., if testimonials exist, include them)
|
||||||
- Original insights/analysis per page
|
- Original insights or analysis per page/location
|
||||||
|
|
||||||
### 4. Internal Linking Architecture
|
### 4. Internal Linking Architecture
|
||||||
|
|
||||||
**Hub and spoke model:**
|
**Hub and spoke model:**
|
||||||
- Hub: Main category page
|
- Hub: Main service page (e.g., `/services/ac-repair/`)
|
||||||
- Spokes: Individual programmatic pages
|
- Spokes: Location pages (e.g., `/services/ac-repair/denver/`, `/services/ac-repair/boulder/`)
|
||||||
- Cross-links between related spokes
|
- Cross-links between related spokes
|
||||||
|
- Hub links to all related spokes
|
||||||
|
|
||||||
|
**Grid linking (Service x Location):**
|
||||||
|
For 10 services x 20 locations (200 pages):
|
||||||
|
- Service hub pages link to all 20 location versions
|
||||||
|
- Location landing pages link to all 10 services
|
||||||
|
- Creates dense internal link structure
|
||||||
|
|
||||||
**Avoid orphan pages:**
|
**Avoid orphan pages:**
|
||||||
- Every page reachable from main site
|
- Every page reachable from main site
|
||||||
|
|
@ -154,10 +167,11 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
|
||||||
|
|
||||||
### 5. Indexation Strategy
|
### 5. Indexation Strategy
|
||||||
|
|
||||||
- Prioritize high-volume patterns
|
- Prioritize high-volume patterns (Service + Location usually highest ROI)
|
||||||
- Noindex very thin variations
|
- Noindex very thin variations or low-search-volume combinations
|
||||||
- Manage crawl budget thoughtfully
|
- Manage crawl budget thoughtfully for large sites
|
||||||
- Separate sitemaps by page type
|
- Separate sitemaps by page type
|
||||||
|
- Test ranking potential before scaling to all combinations
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -166,25 +180,29 @@ You can layer multiple playbooks (e.g., "Best coworking spaces in San Diego").
|
||||||
### Pre-Launch Checklist
|
### Pre-Launch Checklist
|
||||||
|
|
||||||
**Content quality:**
|
**Content quality:**
|
||||||
- [ ] Each page provides unique value
|
- [ ] Each page provides unique value (not just city name swapped)
|
||||||
- [ ] Answers search intent
|
- [ ] Answers search intent
|
||||||
- [ ] Readable and useful
|
- [ ] Readable and useful for actual HVAC buyers
|
||||||
|
- [ ] No duplicate content across pages
|
||||||
|
|
||||||
**Technical SEO:**
|
**Technical SEO:**
|
||||||
- [ ] Unique titles and meta descriptions
|
- [ ] Unique titles and meta descriptions
|
||||||
- [ ] Proper heading structure
|
- [ ] Proper heading structure
|
||||||
- [ ] Schema markup implemented
|
- [ ] Schema markup implemented (LocalBusiness + Service)
|
||||||
- [ ] Page speed acceptable
|
- [ ] Page speed acceptable
|
||||||
|
- [ ] Mobile-friendly
|
||||||
|
|
||||||
**Internal linking:**
|
**Internal linking:**
|
||||||
- [ ] Connected to site architecture
|
- [ ] Connected to site architecture
|
||||||
- [ ] Related pages linked
|
- [ ] Related pages linked (hub to spokes)
|
||||||
|
- [ ] Breadcrumbs implemented
|
||||||
- [ ] No orphan pages
|
- [ ] No orphan pages
|
||||||
|
|
||||||
**Indexation:**
|
**Indexation:**
|
||||||
- [ ] In XML sitemap
|
- [ ] In XML sitemap
|
||||||
- [ ] Crawlable
|
- [ ] Crawlable (robots.txt allows)
|
||||||
- [ ] No conflicting noindex
|
- [ ] No conflicting noindex
|
||||||
|
- [ ] Canonicals correct
|
||||||
|
|
||||||
### Post-Launch Monitoring
|
### Post-Launch Monitoring
|
||||||
|
|
||||||
|
|
@ -194,45 +212,125 @@ Watch for: Thin content warnings, Ranking drops, Manual actions, Crawl errors
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Service + Location Pages (Most Common for HVAC)
|
||||||
|
|
||||||
|
### Data Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Services: [AC Repair, AC Installation, Furnace Repair, Furnace Installation, Maintenance Plans, ...]
|
||||||
|
Locations: [Denver, Boulder, Fort Collins, ...]
|
||||||
|
Per combo: description, testimonials, local details, pricing availability
|
||||||
|
```
|
||||||
|
|
||||||
|
### URL Pattern Options
|
||||||
|
|
||||||
|
- `/services/[service]/[location]/` — Good for dense internal linking
|
||||||
|
- `/[location]/[service]/` — Good for local SEO emphasis
|
||||||
|
- `/[location]/services/[service]/` — Good for site hierarchy
|
||||||
|
|
||||||
|
### Title Tag Template
|
||||||
|
|
||||||
|
"[Service] in [City] | [Company Name]"
|
||||||
|
- AC Repair in Denver | ProHVAC Solutions
|
||||||
|
- Furnace Installation in Boulder | ProHVAC Solutions
|
||||||
|
|
||||||
|
### Page Template Structure
|
||||||
|
|
||||||
|
1. **Headline** — "[Service] in [Location]"
|
||||||
|
2. **Local intro** — Why this service is important here (seasonal demand, climate, common issues)
|
||||||
|
3. **Service overview** — What the service includes, why it matters
|
||||||
|
4. **Why choose us** — Local presence, technician credentials, response time
|
||||||
|
5. **Local proof** — Testimonials from customers in this area, nearby projects
|
||||||
|
6. **Service details** — Step-by-step what happens, timeline, what to expect
|
||||||
|
7. **FAQ** — Common questions for this service + location combo
|
||||||
|
8. **Related services in [Location]** — Links to other services in same area
|
||||||
|
9. **Related locations** — Links to same service in nearby areas
|
||||||
|
10. **CTA** — Schedule, quote, call
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Equipment Pages
|
||||||
|
|
||||||
|
### Data Structure
|
||||||
|
|
||||||
|
Leverage HVAC equipment partnerships (Carrier, Trane, Lennox, etc.):
|
||||||
|
|
||||||
|
```
|
||||||
|
Equipment: [Brand + Model code]
|
||||||
|
Per item: specs, SEER rating, price, availability, financing, installation timeline
|
||||||
|
```
|
||||||
|
|
||||||
|
### URL Pattern
|
||||||
|
|
||||||
|
- `/equipment/[brand]/` — Brand category page
|
||||||
|
- `/equipment/[brand]/[model]/` — Specific model page
|
||||||
|
- `/equipment/[brand]/[model]-reviews/` — Reviews page
|
||||||
|
|
||||||
|
### Page Template
|
||||||
|
|
||||||
|
1. **Product name and overview**
|
||||||
|
2. **Key specs and SEER/AFUE ratings**
|
||||||
|
3. **Price range** (helps searchers)
|
||||||
|
4. **Comparison table** (this model vs. comparable models)
|
||||||
|
5. **Installation info** — Compatibility, timeline
|
||||||
|
6. **Customer reviews** — Real feedback, warranties
|
||||||
|
7. **Where to buy/install** — Your availability by location
|
||||||
|
8. **Related equipment** — Complementary products
|
||||||
|
9. **CTA** — Get quote, schedule inspection
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Common Mistakes
|
## Common Mistakes
|
||||||
|
|
||||||
- **Thin content**: Just swapping city names in identical content
|
- **Thin content** — Just swapping city names in identical content
|
||||||
- **Keyword cannibalization**: Multiple pages targeting same keyword
|
- **Keyword cannibalization** — Multiple pages targeting "[Service]" without location distinction
|
||||||
- **Over-generation**: Creating pages with no search demand
|
- **Over-generation** — Creating pages for service-location combos with zero search volume
|
||||||
- **Poor data quality**: Outdated or incorrect information
|
- **Poor data quality** — Outdated pricing, incomplete service descriptions
|
||||||
- **Ignoring UX**: Pages exist for Google, not users
|
- **Ignoring UX** — Pages exist for Google, not users trying to find local HVAC help
|
||||||
|
- **No internal linking** — Orphan pages don't rank
|
||||||
|
- **Missing local signals** — No testimonials, no service area details, generic content
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
### Strategy Document
|
### Strategy Document
|
||||||
- Opportunity analysis
|
- Opportunity analysis (playbooks chosen, volume per pattern)
|
||||||
- Implementation plan
|
- Implementation plan (phases, priority order)
|
||||||
- Content guidelines
|
- Content guidelines (what makes a unique page)
|
||||||
|
- Data requirements (what fields needed)
|
||||||
|
|
||||||
### Page Template
|
### Page Template
|
||||||
- URL structure
|
- URL structure
|
||||||
- Title/meta templates
|
- Title/meta templates
|
||||||
- Content outline
|
- Content outline (sections, word count targets)
|
||||||
- Schema markup
|
- Schema markup example
|
||||||
|
- Internal linking plan
|
||||||
|
|
||||||
|
### Prioritized Page List
|
||||||
|
- First 50 pages (quick wins, high volume)
|
||||||
|
- Next 100 pages (medium volume, medium effort)
|
||||||
|
- Long tail (low volume, validation phase)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What keyword patterns are you targeting?
|
1. What HVAC services/products do you offer?
|
||||||
2. What data do you have (or can acquire)?
|
2. What geographic areas do you serve? (Single city? Multi-state?)
|
||||||
3. How many pages are you planning?
|
3. Do you have equipment partnerships (Carrier, Trane, etc.) to feature?
|
||||||
4. What does your site authority look like?
|
4. What data do you have (testimonials, specs, pricing, projects)?
|
||||||
5. Who currently ranks for these terms?
|
5. How many pages are you targeting? (50? 500? 5000?)
|
||||||
6. What's your technical stack?
|
6. What's your site authority currently?
|
||||||
|
7. Who currently ranks for your target terms?
|
||||||
|
8. What's your technical stack for content generation/publishing?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **seo-audit**: For auditing programmatic pages after launch
|
- **seo-audit**: For auditing programmatic pages after launch
|
||||||
- **schema-markup**: For adding structured data
|
- **schema-markup**: For adding LocalBusiness + Service structured data
|
||||||
- **site-architecture**: For page hierarchy, URL structure, and internal linking
|
- **site-architecture**: For page hierarchy, URL structure, and internal linking
|
||||||
|
- **hvac-estimate-popups**: For conversion optimization on service pages
|
||||||
- **competitor-alternatives**: For comparison page frameworks
|
- **competitor-alternatives**: For comparison page frameworks
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "We want to create programmatic SEO pages for our CRM. We're thinking of 'CRM for [industry]' pages — like 'CRM for Real Estate,' 'CRM for Healthcare,' etc. How should we approach this?",
|
"prompt": "We want to create programmatic SEO pages for our CRM. We're thinking of 'CRM for [industry]' pages — like 'CRM for Real Estate,' 'CRM for Healthcare,' etc. How should we approach this?",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify this as the Personas playbook (industry-specific pages). Should apply the core principles: unique value per page (not just swapping the industry name), proprietary data or insights per industry, clean URL structure. Should recommend the implementation framework: keyword research for each industry variation, data requirements (what industry-specific content makes each page unique), template design, internal linking strategy between industry pages and main pages, and indexation strategy. Should warn against thin content (just template + keyword swap).",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should identify this as the Personas playbook (industry-specific pages). Should apply the core principles: unique value per page (not just swapping the industry name), proprietary data or insights per industry, clean URL structure. Should recommend the implementation framework: keyword research for each industry variation, data requirements (what industry-specific content makes each page unique), template design, internal linking strategy between industry pages and main pages, and indexation strategy. Should warn against thin content (just template + keyword swap).",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Identifies as Personas playbook",
|
"Identifies as Personas playbook",
|
||||||
"Applies core principles (unique value, proprietary data, clean URLs)",
|
"Applies core principles (unique value, proprietary data, clean URLs)",
|
||||||
"Recommends keyword research per variation",
|
"Recommends keyword research per variation",
|
||||||
|
|
|
||||||
|
|
@ -1,72 +1,110 @@
|
||||||
---
|
---
|
||||||
name: referral-program
|
name: referral-program
|
||||||
description: "When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions 'referral,' 'affiliate,' 'ambassador,' 'word of mouth,' 'viral loop,' 'refer a friend,' 'partner program,' 'referral incentive,' 'how to get referrals,' 'customers referring customers,' or 'affiliate payout.' Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch-strategy."
|
description: "When the user wants to create, optimize, or analyze a referral program for contractors, distributors, or homeowners. Also use when the user mentions 'referral,' 'contractor referral,' 'homeowner referral,' 'word of mouth,' 'refer a friend,' 'distributor incentive,' 'contractor co-op,' 'referral incentive,' 'how to get referrals,' or 'customers referring customers.' Use this whenever someone wants existing customers or partners to bring in new business."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [search, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Referral & Affiliate Programs
|
# HVAC Referral & Partnership Programs
|
||||||
|
|
||||||
You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.
|
You are an expert in viral growth and referral marketing for HVAC. Your goal is to help design and optimize programs that turn customers, contractors, and partners into growth engines.
|
||||||
|
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Program Type
|
### 1. Program Type
|
||||||
- Customer referral program, affiliate program, or both?
|
- Homeowner referrals, contractor referrals, or both?
|
||||||
- B2B or B2C?
|
- B2C or B2B?
|
||||||
- What's the average customer LTV?
|
- What's the average job value?
|
||||||
- What's your current CAC from other channels?
|
- What's your current CAC from other channels?
|
||||||
|
|
||||||
### 2. Current State
|
### 2. Current State
|
||||||
- Existing referral/affiliate program?
|
- Existing referral program?
|
||||||
- Current referral rate (% who refer)?
|
- Current referral rate (% who refer)?
|
||||||
- What incentives have you tried?
|
- What incentives have you tried?
|
||||||
|
|
||||||
### 3. Product Fit
|
### 3. Audience
|
||||||
- Is your product shareable?
|
- Are customers/contractors natural advocates for your work?
|
||||||
- Does it have network effects?
|
- Do they talk about you to others?
|
||||||
- Do customers naturally talk about it?
|
|
||||||
|
|
||||||
### 4. Resources
|
### 4. Resources
|
||||||
- Tools/platforms you use or consider?
|
|
||||||
- Budget for referral incentives?
|
- Budget for referral incentives?
|
||||||
|
- Ability to track referrals (CRM)?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Referral vs. Affiliate
|
## Referral Types in HVAC
|
||||||
|
|
||||||
### Customer Referral Programs
|
### Homeowner Referral Programs
|
||||||
|
|
||||||
**Best for:**
|
**Best for**: Residential HVAC contractors with strong local reputation
|
||||||
- Existing customers recommending to their network
|
|
||||||
- Products with natural word-of-mouth
|
|
||||||
- Lower-ticket or self-serve products
|
|
||||||
|
|
||||||
**Characteristics:**
|
**Characteristics**:
|
||||||
- Referrer is an existing customer
|
- Referred customers are high-quality (come from trusted source)
|
||||||
- One-time or limited rewards
|
- Higher lifetime value (referred customers have 25-40% higher LTV)
|
||||||
- Higher trust, lower volume
|
- Natural word-of-mouth from satisfied customers
|
||||||
|
|
||||||
### Affiliate Programs
|
**Typical incentive**: $50-150 per referred customer who books service or completes job
|
||||||
|
|
||||||
**Best for:**
|
**Example**: "Refer a neighbor and get $100 toward your next service"
|
||||||
- Reaching audiences you don't have access to
|
|
||||||
- Content creators, influencers, bloggers
|
|
||||||
- Higher-ticket products that justify commissions
|
|
||||||
|
|
||||||
**Characteristics:**
|
|
||||||
- Affiliates may not be customers
|
|
||||||
- Ongoing commission relationship
|
|
||||||
- Higher volume, variable trust
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Referral Program Design
|
### Contractor-to-Contractor Referral Programs
|
||||||
|
|
||||||
|
**Best for**: HVAC contractors referring overflow work to other contractors (non-competing areas)
|
||||||
|
|
||||||
|
**Characteristics**:
|
||||||
|
- Contractors naturally refer overflow/out-of-area work
|
||||||
|
- Higher job values than homeowner referrals
|
||||||
|
- B2B relationship-based
|
||||||
|
|
||||||
|
**Typical incentive**: 5-10% of job value OR flat $100-300 per referral
|
||||||
|
|
||||||
|
**Example**: "Refer an out-of-area job and earn 8% commission"
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Distributor Incentive Programs
|
||||||
|
|
||||||
|
**Best for**: Equipment manufacturers and distributors incentivizing contractor adoption
|
||||||
|
|
||||||
|
**Characteristics**:
|
||||||
|
- Drive equipment sales through contractor partners
|
||||||
|
- Ongoing relationship (not one-time)
|
||||||
|
- Tiered rewards based on volume
|
||||||
|
|
||||||
|
**Typical incentive structure**:
|
||||||
|
- Volume discounts: 5% off at $5K/month, 10% off at $10K/month
|
||||||
|
- Cash rebates: $50-200 per piece of equipment sold
|
||||||
|
- Tiered bonuses: Hit $50K quarterly volume → $500 bonus
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### Property Manager / Real Estate Partner Referrals
|
||||||
|
|
||||||
|
**Best for**: Commercial HVAC contractors and equipment companies
|
||||||
|
|
||||||
|
**Characteristics**:
|
||||||
|
- High-value, recurring relationships
|
||||||
|
- Multiple buildings per partner
|
||||||
|
- Long sales cycle (relationship-based)
|
||||||
|
|
||||||
|
**Typical incentive**:
|
||||||
|
- Referral fee: $500-1000 per building/property onboarded
|
||||||
|
- Ongoing commission: 2-5% of annual maintenance contract value
|
||||||
|
- Co-marketing funds: $1000-5000 annually for joint marketing
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Referral Program Design Framework
|
||||||
|
|
||||||
### The Referral Loop
|
### The Referral Loop
|
||||||
|
|
||||||
|
|
@ -76,65 +114,81 @@ Trigger Moment → Share Action → Convert Referred → Reward → (Loop)
|
||||||
|
|
||||||
### Step 1: Identify Trigger Moments
|
### Step 1: Identify Trigger Moments
|
||||||
|
|
||||||
**High-intent moments:**
|
**High-intent moments for referral**:
|
||||||
- Right after first "aha" moment
|
- Right after excellent service experience (technician did great job)
|
||||||
- After achieving a milestone
|
- After completing a large installation (customer excited, just paid)
|
||||||
- After exceptional support
|
- After solving an emergency (gratitude is high)
|
||||||
- After renewing or upgrading
|
- During seasonal tune-up (annual reminder touchpoint)
|
||||||
|
- When customer mentions knowing others with same problem
|
||||||
|
|
||||||
### Step 2: Design Share Mechanism
|
### Step 2: Design Share Mechanism
|
||||||
|
|
||||||
**Ranked by effectiveness:**
|
**Ranked by effectiveness**:
|
||||||
1. In-product sharing (highest conversion)
|
1. **Referral card/flyer** (technician hands out after service) — easy, tangible
|
||||||
2. Personalized link
|
2. **Personalized link or referral code** — trackable, low friction
|
||||||
3. Email invitation
|
3. **Email/text campaign** — permission-based, high reach
|
||||||
4. Social sharing
|
4. **Word-of-mouth incentive** — customer tells friend, you track by referring customer name
|
||||||
5. Referral code (works offline)
|
5. **Social sharing** — low conversion but high reach
|
||||||
|
|
||||||
### Step 3: Choose Incentive Structure
|
### Step 3: Choose Incentive Structure
|
||||||
|
|
||||||
**Single-sided rewards** (referrer only): Simpler, works for high-value products
|
**Single-sided** (referred customer gets reward):
|
||||||
|
- Simpler, lower cost
|
||||||
|
- Works for low-touch ("First service $50 off")
|
||||||
|
- Less motivation for existing customer to share
|
||||||
|
|
||||||
**Double-sided rewards** (both parties): Higher conversion, win-win framing
|
**Double-sided** (both get reward):
|
||||||
|
- Higher conversion
|
||||||
|
- Win-win framing
|
||||||
|
- More cost but higher ROI
|
||||||
|
|
||||||
**Tiered rewards**: Gamifies referral process, increases engagement
|
**Tiered rewards** (escalate as customer refers more):
|
||||||
|
- Gamifies process
|
||||||
**For examples and incentive sizing**: See [references/program-examples.md](references/program-examples.md)
|
- Increases repeat referrers
|
||||||
|
- Example: 1st referral = $50, 2nd = $75, 3rd = $100
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Program Optimization
|
## Program Mechanics
|
||||||
|
|
||||||
### Improving Referral Rate
|
### Homeowner Referral Example
|
||||||
|
|
||||||
**If few customers are referring:**
|
```
|
||||||
- Ask at better moments
|
Existing Customer Refers → Friend Calls with Code/Referrer Name → Friend Books Service
|
||||||
- Simplify sharing process
|
→ Friend's First Service Complete → Both Get Reward (e.g., $50 off next service)
|
||||||
- Test different incentive types
|
```
|
||||||
- Make referral prominent in product
|
|
||||||
|
|
||||||
**If referrals aren't converting:**
|
**Incentive structure**:
|
||||||
- Improve landing experience for referred users
|
- **Referrer** (existing customer): $50 credit toward next service
|
||||||
- Strengthen incentive for new users
|
- **Referred** (new customer): $50 off first service
|
||||||
- Ensure referrer's endorsement is visible
|
- **Cost per acquisition**: $100 (vs. typical $150-250 CAC from ads)
|
||||||
|
- **Lifetime value of referred customer**: $800-1200 (higher than average due to trust)
|
||||||
|
- **ROI**: 8-12x
|
||||||
|
|
||||||
### A/B Tests to Run
|
### Contractor Referral Example
|
||||||
|
|
||||||
**Incentive tests:** Amount, type, single vs. double-sided, timing
|
```
|
||||||
|
Contractor A Gets Out-of-Area Inquiry → Refers to Contractor B in That Area
|
||||||
|
→ Contractor B Completes Job ($5000) → Contractor A Gets 8% Commission ($400)
|
||||||
|
```
|
||||||
|
|
||||||
**Messaging tests:** Program description, CTA copy, landing page copy
|
**Mechanics**:
|
||||||
|
- Clear tracking: Referred contractor mentions Contractor A by name to homeowner
|
||||||
|
- Payment: Net-30 after job completion and customer payment
|
||||||
|
- Tax: 1099 to referring contractor for commissions
|
||||||
|
- Cap: None, unlimited referral earnings
|
||||||
|
|
||||||
**Placement tests:** Where and when the referral prompt appears
|
### Distributor Program Example
|
||||||
|
|
||||||
### Common Problems & Fixes
|
```
|
||||||
|
Contractor Orders Equipment → Reaches Volume Milestone → Gets Tiered Rebate
|
||||||
|
→ Repeat Purchases Increase → Annual Bonus for Top 20 Contractors
|
||||||
|
```
|
||||||
|
|
||||||
| Problem | Fix |
|
**Incentive structure**:
|
||||||
|---------|-----|
|
- Volume tiers: $0-25K (standard pricing), $25K-50K (5% rebate), $50K+ (10% rebate)
|
||||||
| Low awareness | Add prominent in-app prompts |
|
- Annual bonus: Top 10 contractors ($1000 bonus), Top 11-20 ($500 bonus)
|
||||||
| Low share rate | Simplify to one click |
|
- Co-op marketing fund: All participants get $500 annually for local marketing
|
||||||
| Low conversion | Optimize referred user experience |
|
|
||||||
| Fraud/abuse | Add verification, limits |
|
|
||||||
| One-time referrers | Add tiered/gamified rewards |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -142,114 +196,126 @@ Trigger Moment → Share Action → Convert Referred → Reward → (Loop)
|
||||||
|
|
||||||
### Key Metrics
|
### Key Metrics
|
||||||
|
|
||||||
**Program health:**
|
**Program health**:
|
||||||
- Active referrers (referred someone in last 30 days)
|
- % of customers who refer (target: 10-20% for high-satisfaction programs)
|
||||||
- Referral conversion rate
|
- Average referrals per referrer (target: 2-3)
|
||||||
- Rewards earned/paid
|
- Referral conversion rate (referred leads who book/buy)
|
||||||
|
- Cost per referred customer acquired (referral incentive cost)
|
||||||
|
|
||||||
**Business impact:**
|
**Business impact**:
|
||||||
- % of new customers from referrals
|
- % of new customers from referrals (target: 20-40%)
|
||||||
- CAC via referral vs. other channels
|
- CAC via referral vs. other channels
|
||||||
- LTV of referred customers
|
- LTV of referred customers
|
||||||
- Referral program ROI
|
- Referral program ROI (rewards paid / revenue from referred customers)
|
||||||
|
|
||||||
### Typical Findings
|
### Typical Benchmarks
|
||||||
|
|
||||||
- Referred customers have 16-25% higher LTV
|
- Referred customers have 25-40% higher LTV than paid-acquisition
|
||||||
- Referred customers have 18-37% lower churn
|
- Referred customers have 15-25% lower churn
|
||||||
- Referred customers refer others at 2-3x rate
|
- Referral CAC is 50-70% lower than other channels
|
||||||
|
- Referral program ROI: 5-10x
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Launch Checklist
|
## Launch Checklist
|
||||||
|
|
||||||
### Before Launch
|
### Before Launch
|
||||||
- [ ] Define program goals and success metrics
|
- [ ] Define incentive structure and reward amounts
|
||||||
- [ ] Design incentive structure
|
- [ ] Build tracking system (spreadsheet, CRM field, or dedicated tool)
|
||||||
- [ ] Build or configure referral tool
|
- [ ] Create collateral (referral cards, email template, flyer)
|
||||||
- [ ] Create referral landing page
|
- [ ] Train technicians and sales team on program
|
||||||
- [ ] Set up tracking and attribution
|
- [ ] Set up fulfillment process (how rewards are delivered)
|
||||||
- [ ] Define fraud prevention rules
|
- [ ] Create program terms and conditions
|
||||||
- [ ] Create terms and conditions
|
- [ ] Test tracking with small pilot (10 customers)
|
||||||
- [ ] Test complete referral flow
|
|
||||||
|
|
||||||
### Launch
|
### Launch
|
||||||
- [ ] Announce to existing customers
|
- [ ] Announce to existing customer base via email, text, in-service handouts
|
||||||
- [ ] Add in-app referral prompts
|
- [ ] Train all technicians on presenting the program
|
||||||
- [ ] Update website with program details
|
- [ ] Update website with program details
|
||||||
- [ ] Brief support team
|
- [ ] Brief support team
|
||||||
|
|
||||||
### Post-Launch (First 30 Days)
|
### Post-Launch (First 30 Days)
|
||||||
- [ ] Review conversion funnel
|
- [ ] Track conversions daily
|
||||||
- [ ] Identify top referrers
|
- [ ] Identify and reward top referrers publicly
|
||||||
- [ ] Gather feedback
|
- [ ] Gather feedback from customers and technicians
|
||||||
- [ ] Fix friction points
|
- [ ] Fix friction points (unclear reward, hard to share)
|
||||||
- [ ] Send reminder emails to non-referrers
|
- [ ] Send reminder emails to top customers ("You have $X in referral credits available")
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Email Sequences
|
## Email Sequences
|
||||||
|
|
||||||
### Referral Program Launch
|
### Program Launch
|
||||||
|
|
||||||
```
|
```
|
||||||
Subject: You can now earn [reward] for sharing [Product]
|
Subject: You can now earn $[reward] for sharing us with friends
|
||||||
|
|
||||||
We just launched our referral program!
|
Hi [Name],
|
||||||
|
|
||||||
Share [Product] with friends and earn [reward] for each signup.
|
We just launched our referral program! It's our way of saying thank you for the great reviews and recommendations you've given us.
|
||||||
They get [their reward] too.
|
|
||||||
|
|
||||||
[Unique referral link]
|
Here's how it works:
|
||||||
|
|
||||||
1. Share your link
|
1. When you know someone who needs HVAC service, just mention us or give them this code: [REFERRAL_CODE]
|
||||||
2. Friend signs up
|
2. They book a service using your code
|
||||||
3. You both get [reward]
|
3. You both get $[reward] — they get it off their first service, you get it off your next one
|
||||||
|
|
||||||
|
[Simple explanatory graphic]
|
||||||
|
|
||||||
|
Questions? Reply to this email or call [number].
|
||||||
|
|
||||||
|
Best,
|
||||||
|
[Company Name]
|
||||||
```
|
```
|
||||||
|
|
||||||
### Referral Nurture Sequence
|
### Referral Nurture Sequence
|
||||||
|
|
||||||
- Day 7: Remind about referral program
|
- **Day 7**: Highlight benefit ("You could earn $200 this month if 4 friends sign up")
|
||||||
- Day 30: "Know anyone who'd benefit?"
|
- **Day 30**: Share a success story ("John earned $150 last month by referring neighbors")
|
||||||
- Day 60: Success story + referral prompt
|
- **Day 60**: Seasonal reminder ("Spring is busy season for referrals — share now!")
|
||||||
- After milestone: "You achieved [X]—know others who'd want this?"
|
- **On referral**: Immediate notification ("Your friend just booked! You're $X closer to your reward")
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Affiliate Programs
|
## Common Problems & Fixes
|
||||||
|
|
||||||
**For detailed affiliate program design, commission structures, recruitment, and tools**: See [references/affiliate-programs.md](references/affiliate-programs.md)
|
| Problem | Cause | Fix |
|
||||||
|
|---------|-------|-----|
|
||||||
|
| Low awareness | Customers don't know program exists | Train technicians to mention it; include in every invoice; email campaign |
|
||||||
|
| Low share rate | Unclear how to participate | Make it one step: just give referral card or mention name |
|
||||||
|
| Low conversion | Referred prospects aren't following through | Make referral seamless: gift card, discount applied automatically |
|
||||||
|
| Fraud/abuse | People gaming the system | Require actual service completion; track by phone/email; approve manually |
|
||||||
|
| One-time referrers | Customers refer once then stop | Gamify with tiers: $50 → $75 → $100 per referral |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What type of program (referral, affiliate, or both)?
|
1. What type of referral program (homeowner, contractor, distributor)?
|
||||||
2. What's your customer LTV and current CAC?
|
2. What's your average job size or customer LTV?
|
||||||
3. Existing program or starting from scratch?
|
3. Existing program or starting from scratch?
|
||||||
4. What tools/platforms are you considering?
|
4. What incentive budget do you have?
|
||||||
5. What's your budget for rewards/commissions?
|
5. Do you have a CRM to track referrals?
|
||||||
6. Is your product naturally shareable?
|
6. Are your current customers naturally advocates for your work?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Tool Integrations
|
## Compendium Integration
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for referral programs:
|
Use Compendium to support referral program optimization:
|
||||||
|
|
||||||
| Tool | Best For | Guide |
|
- **Competitive analysis**: Research competitor referral programs
|
||||||
|------|----------|-------|
|
- **Customer analysis**: Identify high-LTV customers most likely to refer
|
||||||
| **Rewardful** | Stripe-native affiliate programs | [rewardful.md](../../tools/integrations/rewardful.md) |
|
- **Incentive testing**: Analyze which incentive levels drive most referrals
|
||||||
| **Tolt** | SaaS affiliate programs | [tolt.md](../../tools/integrations/tolt.md) |
|
|
||||||
| **Mention Me** | Enterprise referral programs | [mention-me.md](../../tools/integrations/mention-me.md) |
|
**Tool tiers**: Search, analysis
|
||||||
| **Dub.co** | Link tracking and attribution | [dub-co.md](../../tools/integrations/dub-co.md) |
|
|
||||||
| **Stripe** | Payment processing (for commission tracking) | [stripe.md](../../tools/integrations/stripe.md) |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **launch-strategy**: For launching referral program effectively
|
- **marketing-ideas**: For integrated referral campaign strategy
|
||||||
- **email-sequence**: For referral nurture campaigns
|
- **email-sequence**: For referral nurture campaigns
|
||||||
- **marketing-psychology**: For understanding referral motivation
|
- **marketing-psychology**: For understanding referral motivation
|
||||||
- **analytics-tracking**: For tracking referral attribution
|
- **sales-enablement**: For training teams on referral pitch
|
||||||
|
- **pricing-strategy**: For incentive sizing and margin impact
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",
|
"prompt": "Help me design a referral program for our SaaS product. We're a $49/month project management tool with about 1,000 customers. We want to encourage word-of-mouth growth.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should distinguish between referral and affiliate programs (this is referral — existing customers referring peers). Should design the referral loop: trigger point (when to ask for referral), share mechanism (unique link, email invite, social share), conversion flow (what the referred person experiences), and reward structure. Should recommend incentive type: double-sided recommended (both referrer and referred get value). Should suggest specific incentives appropriate for $49/month SaaS (e.g., free month for both). Should include the launch checklist. Should recommend tool integrations (Rewardful, Tolt, etc.).",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Distinguishes referral from affiliate",
|
"Distinguishes referral from affiliate",
|
||||||
"Designs the referral loop (trigger, share, convert, reward)",
|
"Designs the referral loop (trigger, share, convert, reward)",
|
||||||
"Recommends double-sided incentive structure",
|
"Recommends double-sided incentive structure",
|
||||||
|
|
|
||||||
|
|
@ -1,343 +0,0 @@
|
||||||
---
|
|
||||||
name: revops
|
|
||||||
description: "When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes. Also use when the user mentions 'RevOps,' 'revenue operations,' 'lead scoring,' 'lead routing,' 'MQL,' 'SQL,' 'pipeline stages,' 'deal desk,' 'CRM automation,' 'marketing-to-sales handoff,' 'data hygiene,' 'leads aren't getting to sales,' 'pipeline management,' 'lead qualification,' or 'when should marketing hand off to sales.' Use this for anything involving the systems and processes that connect marketing to revenue. For cold outreach emails, see cold-email. For email drip campaigns, see email-sequence. For pricing decisions, see pricing-strategy."
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# RevOps
|
|
||||||
|
|
||||||
You are an expert in revenue operations. Your goal is to help design and optimize the systems that connect marketing, sales, and customer success into a unified revenue engine.
|
|
||||||
|
|
||||||
## Before Starting
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
|
||||||
|
|
||||||
1. **GTM motion** — Product-led (PLG), sales-led, or hybrid?
|
|
||||||
2. **ACV range** — What's the average contract value?
|
|
||||||
3. **Sales cycle length** — Days from first touch to closed-won?
|
|
||||||
4. **Current stack** — CRM, marketing automation, scheduling, enrichment tools?
|
|
||||||
5. **Current state** — How are leads managed today? What's working and what's not?
|
|
||||||
6. **Goals** — Increase conversion? Reduce speed-to-lead? Fix handoff leaks? Build from scratch?
|
|
||||||
|
|
||||||
Work with whatever the user gives you. If they have a clear problem area, start there. Don't block on missing inputs — use what you have and note what would strengthen the solution.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### Single Source of Truth
|
|
||||||
One system of record for every lead and account. If data lives in multiple places, it will conflict. Pick a CRM as the canonical source and sync everything to it.
|
|
||||||
|
|
||||||
### Define Before Automate
|
|
||||||
Get stage definitions, scoring criteria, and routing rules right on paper before building workflows. Automating a broken process just creates broken results faster.
|
|
||||||
|
|
||||||
### Measure Every Handoff
|
|
||||||
Every handoff between teams is a potential leak. Marketing-to-sales, SDR-to-AE, AE-to-CS — each needs an SLA, a tracking mechanism, and someone accountable for follow-through.
|
|
||||||
|
|
||||||
### Revenue Team Alignment
|
|
||||||
Marketing, sales, and customer success must agree on definitions. If marketing calls something an MQL but sales won't work it, the definition is wrong. Alignment meetings aren't optional.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Lead Lifecycle Framework
|
|
||||||
|
|
||||||
### Stage Definitions
|
|
||||||
|
|
||||||
| Stage | Entry Criteria | Exit Criteria | Owner |
|
|
||||||
|-------|---------------|---------------|-------|
|
|
||||||
| **Subscriber** | Opts in to content (blog, newsletter) | Provides company info or shows engagement | Marketing |
|
|
||||||
| **Lead** | Identified contact with basic info | Meets minimum fit criteria | Marketing |
|
|
||||||
| **MQL** | Passes fit + engagement threshold | Sales accepts or rejects within SLA | Marketing |
|
|
||||||
| **SQL** | Sales accepts and qualifies via conversation | Opportunity created or recycled | Sales (SDR/AE) |
|
|
||||||
| **Opportunity** | Budget, authority, need, timeline confirmed | Closed-won or closed-lost | Sales (AE) |
|
|
||||||
| **Customer** | Closed-won deal | Expands, renews, or churns | CS / Account Mgmt |
|
|
||||||
| **Evangelist** | High NPS, referral activity, case study | Ongoing program participation | CS / Marketing |
|
|
||||||
|
|
||||||
### MQL Definition
|
|
||||||
|
|
||||||
An MQL requires both **fit** and **engagement**:
|
|
||||||
|
|
||||||
- **Fit score** — Does this person match your ICP? (company size, industry, role, tech stack)
|
|
||||||
- **Engagement score** — Have they shown buying intent? (pricing page, demo request, multiple visits)
|
|
||||||
|
|
||||||
Neither alone is sufficient. A perfect-fit company that never engages isn't an MQL. A student downloading every ebook isn't an MQL.
|
|
||||||
|
|
||||||
### MQL-to-SQL Handoff SLA
|
|
||||||
|
|
||||||
Define response times and document them:
|
|
||||||
- MQL alert sent to assigned rep
|
|
||||||
- Rep contacts within **4 hours** (business hours)
|
|
||||||
- Rep qualifies or rejects within **48 hours**
|
|
||||||
- Rejected MQLs go to recycling nurture with reason code
|
|
||||||
|
|
||||||
**For complete lifecycle stage templates and SLA examples**: See [references/lifecycle-definitions.md](references/lifecycle-definitions.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Lead Scoring
|
|
||||||
|
|
||||||
### Scoring Dimensions
|
|
||||||
|
|
||||||
**Explicit scoring (fit)** — Who they are:
|
|
||||||
- Company size, industry, revenue
|
|
||||||
- Job title, seniority, department
|
|
||||||
- Tech stack, geography
|
|
||||||
|
|
||||||
**Implicit scoring (engagement)** — What they do:
|
|
||||||
- Page visits (especially pricing, demo, case studies)
|
|
||||||
- Content downloads, webinar attendance
|
|
||||||
- Email engagement (opens, clicks)
|
|
||||||
- Product usage (for PLG)
|
|
||||||
|
|
||||||
**Negative scoring** — Disqualifying signals:
|
|
||||||
- Competitor email domains
|
|
||||||
- Student/personal email
|
|
||||||
- Unsubscribes, spam complaints
|
|
||||||
- Job title mismatches (intern, student)
|
|
||||||
|
|
||||||
### Building a Scoring Model
|
|
||||||
|
|
||||||
1. Define your ICP attributes and weight them
|
|
||||||
2. Identify high-intent behavioral signals from closed-won data
|
|
||||||
3. Set point values for each attribute and behavior
|
|
||||||
4. Set MQL threshold (typically 50-80 points on a 100-point scale)
|
|
||||||
5. Test against historical data — does the model correctly identify past wins?
|
|
||||||
6. Launch, measure, and recalibrate quarterly
|
|
||||||
|
|
||||||
### Common Scoring Mistakes
|
|
||||||
|
|
||||||
- Weighting content downloads too heavily (research ≠ buying intent)
|
|
||||||
- Not including negative scoring (lets bad leads through)
|
|
||||||
- Setting and forgetting (buyer behavior changes; recalibrate quarterly)
|
|
||||||
- Scoring all page visits equally (pricing page ≠ blog post)
|
|
||||||
|
|
||||||
**For detailed scoring templates and example models**: See [references/scoring-models.md](references/scoring-models.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Lead Routing
|
|
||||||
|
|
||||||
### Routing Methods
|
|
||||||
|
|
||||||
| Method | How It Works | Best For |
|
|
||||||
|--------|-------------|----------|
|
|
||||||
| **Round-robin** | Distribute evenly across reps | Equal territories, similar deal sizes |
|
|
||||||
| **Territory-based** | Assign by geography, vertical, or segment | Regional teams, industry specialists |
|
|
||||||
| **Account-based** | Named accounts go to named reps | ABM motions, strategic accounts |
|
|
||||||
| **Skill-based** | Route by deal complexity, product line, or language | Diverse product lines, global teams |
|
|
||||||
|
|
||||||
### Routing Rules Essentials
|
|
||||||
|
|
||||||
- Route to the **most specific match** first, then fall back to general
|
|
||||||
- Include a **fallback owner** — unassigned leads go cold fast and waste pipeline
|
|
||||||
- Round-robin should account for **rep capacity and availability** (PTO, quota attainment)
|
|
||||||
- Log every routing decision for audit and optimization
|
|
||||||
|
|
||||||
### Speed-to-Lead
|
|
||||||
|
|
||||||
Response time is the single biggest factor in lead conversion:
|
|
||||||
- Contact within **5 minutes** = 21x more likely to qualify (Lead Connect)
|
|
||||||
- After **30 minutes**, conversion drops by 10x
|
|
||||||
- After **24 hours**, the lead is effectively cold
|
|
||||||
|
|
||||||
Build routing rules that prioritize speed. Alert reps immediately. Escalate if SLA is missed.
|
|
||||||
|
|
||||||
**For routing decision trees and platform-specific setup**: See [references/routing-rules.md](references/routing-rules.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Pipeline Stage Management
|
|
||||||
|
|
||||||
### Pipeline Stages
|
|
||||||
|
|
||||||
| Stage | Required Fields | Exit Criteria |
|
|
||||||
|-------|----------------|---------------|
|
|
||||||
| **Qualified** | Contact info, company, source, fit score | Discovery call scheduled |
|
|
||||||
| **Discovery** | Pain points, current solution, timeline | Needs confirmed, demo scheduled |
|
|
||||||
| **Demo/Evaluation** | Technical requirements, decision makers | Positive evaluation, proposal requested |
|
|
||||||
| **Proposal** | Pricing, terms, stakeholder map | Proposal delivered and reviewed |
|
|
||||||
| **Negotiation** | Redlines, approval chain, close date | Terms agreed, contract sent |
|
|
||||||
| **Closed Won** | Signed contract, payment terms | Handoff to CS complete |
|
|
||||||
| **Closed Lost** | Loss reason, competitor (if any) | Post-mortem logged |
|
|
||||||
|
|
||||||
### Stage Hygiene
|
|
||||||
|
|
||||||
- **Required fields per stage** — Don't let reps advance a deal without filling in required data
|
|
||||||
- **Stale deal alerts** — Flag deals that sit in a stage beyond the average time (e.g., 2x average days)
|
|
||||||
- **Stage skip detection** — Alert when deals jump stages (Qualified → Proposal skipping Discovery)
|
|
||||||
- **Close date discipline** — Push dates must include a reason; no silent pushes
|
|
||||||
|
|
||||||
### Pipeline Metrics
|
|
||||||
|
|
||||||
| Metric | What It Tells You |
|
|
||||||
|--------|-------------------|
|
|
||||||
| Stage conversion rates | Where deals die |
|
|
||||||
| Average time in stage | Where deals stall |
|
|
||||||
| Pipeline velocity | Revenue per day through the funnel |
|
|
||||||
| Coverage ratio | Pipeline value vs. quota (target 3-4x) |
|
|
||||||
| Win rate by source | Which channels produce real revenue |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## CRM Automation Workflows
|
|
||||||
|
|
||||||
### Essential Automations
|
|
||||||
|
|
||||||
- **Lifecycle stage updates** — Auto-advance stages when criteria are met
|
|
||||||
- **Task creation on handoff** — Create follow-up task when MQL assigned to rep
|
|
||||||
- **SLA alerts** — Notify manager if rep misses response time SLA
|
|
||||||
- **Deal stage triggers** — Auto-send proposals, update forecasts, notify CS on close
|
|
||||||
|
|
||||||
### Marketing-to-Sales Automations
|
|
||||||
|
|
||||||
- **MQL alert** — Instant notification to assigned rep with lead context
|
|
||||||
- **Meeting booked** — Notify AE when prospect books via scheduling tool
|
|
||||||
- **Lead activity digest** — Daily summary of high-intent actions by active leads
|
|
||||||
- **Re-engagement trigger** — Alert sales when a dormant lead returns to site
|
|
||||||
|
|
||||||
### Calendar Scheduling Integration
|
|
||||||
|
|
||||||
- **Round-robin scheduling** — Distribute meetings evenly across team
|
|
||||||
- **Routing by criteria** — Send enterprise leads to senior AEs, SMB to junior reps
|
|
||||||
- **Pre-meeting enrichment** — Auto-populate CRM record before the call
|
|
||||||
- **No-show workflows** — Auto-follow-up if prospect misses meeting
|
|
||||||
|
|
||||||
**For platform-specific workflow recipes**: See [references/automation-playbooks.md](references/automation-playbooks.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Deal Desk Processes
|
|
||||||
|
|
||||||
### When You Need a Deal Desk
|
|
||||||
|
|
||||||
- ACV above **$25K** (or your threshold for non-standard deals)
|
|
||||||
- Non-standard payment terms (net-90, quarterly billing)
|
|
||||||
- Multi-year contracts with custom pricing
|
|
||||||
- Volume discounts beyond published tiers
|
|
||||||
- Custom legal terms or SLAs
|
|
||||||
|
|
||||||
### Approval Workflow Tiers
|
|
||||||
|
|
||||||
| Deal Size | Approval Required |
|
|
||||||
|-----------|-------------------|
|
|
||||||
| Standard pricing | Auto-approved |
|
|
||||||
| 10-20% discount | Sales manager |
|
|
||||||
| 20-40% discount | VP Sales |
|
|
||||||
| 40%+ discount or custom terms | Deal desk review |
|
|
||||||
| Multi-year / enterprise | Finance + Legal |
|
|
||||||
|
|
||||||
### Non-Standard Terms Handling
|
|
||||||
|
|
||||||
Document every exception. Track which non-standard terms get requested most — if everyone asks for the same exception, it should become standard. Review quarterly.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Data Hygiene & Enrichment
|
|
||||||
|
|
||||||
### Dedup Strategy
|
|
||||||
|
|
||||||
- **Matching rules** — Email domain + company name + phone as primary match keys
|
|
||||||
- **Merge priority** — CRM record wins over marketing automation; most recent activity wins for fields
|
|
||||||
- **Scheduled dedup** — Run weekly automated dedup with manual review for edge cases
|
|
||||||
|
|
||||||
### Required Fields Enforcement
|
|
||||||
|
|
||||||
- Enforce required fields at each lifecycle stage
|
|
||||||
- Block stage advancement if fields are empty
|
|
||||||
- Use progressive profiling — don't require everything upfront
|
|
||||||
|
|
||||||
### Enrichment Tools
|
|
||||||
|
|
||||||
| Tool | Strength |
|
|
||||||
|------|----------|
|
|
||||||
| Clearbit | Real-time enrichment, good for tech companies |
|
|
||||||
| Apollo | Contact data + sequences, strong for prospecting |
|
|
||||||
| ZoomInfo | Enterprise-grade, largest B2B database |
|
|
||||||
|
|
||||||
### Quarterly Audit Checklist
|
|
||||||
|
|
||||||
- Review and merge duplicates
|
|
||||||
- Validate email deliverability on stale contacts
|
|
||||||
- Archive contacts with no activity in 12+ months
|
|
||||||
- Audit lifecycle stage distribution (look for bottlenecks)
|
|
||||||
- Verify enrichment data accuracy on a sample set
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## RevOps Metrics Dashboard
|
|
||||||
|
|
||||||
### Key Metrics
|
|
||||||
|
|
||||||
| Metric | Formula / Definition | Benchmark |
|
|
||||||
|--------|---------------------|-----------|
|
|
||||||
| Lead-to-MQL rate | MQLs / Total leads | 5-15% |
|
|
||||||
| MQL-to-SQL rate | SQLs / MQLs | 30-50% |
|
|
||||||
| SQL-to-Opportunity | Opportunities / SQLs | 50-70% |
|
|
||||||
| Pipeline velocity | (# deals x avg deal size x win rate) / avg sales cycle | Varies by ACV |
|
|
||||||
| CAC | Total sales + marketing spend / new customers | LTV:CAC > 3:1 |
|
|
||||||
| LTV:CAC ratio | Customer lifetime value / CAC | 3:1 to 5:1 healthy |
|
|
||||||
| Speed-to-lead | Time from form fill to first rep contact | < 5 minutes ideal |
|
|
||||||
| Win rate | Closed-won / total opportunities | 20-30% (varies) |
|
|
||||||
|
|
||||||
### Dashboard Structure
|
|
||||||
|
|
||||||
Build three views:
|
|
||||||
1. **Marketing view** — Lead volume, MQL rate, source attribution, cost per MQL
|
|
||||||
2. **Sales view** — Pipeline value, stage conversion, velocity, forecast accuracy
|
|
||||||
3. **Executive view** — CAC, LTV:CAC, revenue vs. target, pipeline coverage
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Output Format
|
|
||||||
|
|
||||||
When delivering RevOps recommendations, provide:
|
|
||||||
|
|
||||||
1. **Lifecycle stage document** — Stage definitions with entry/exit criteria, owners, and SLAs
|
|
||||||
2. **Scoring specification** — Fit and engagement attributes with point values and MQL threshold
|
|
||||||
3. **Routing rules document** — Decision tree with assignment logic and fallbacks
|
|
||||||
4. **Pipeline configuration** — Stage definitions, required fields, and automation triggers
|
|
||||||
5. **Metrics dashboard spec** — Key metrics, data sources, and target benchmarks
|
|
||||||
|
|
||||||
Format each as a standalone document the user can implement directly. Include platform-specific guidance when the CRM is known.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task-Specific Questions
|
|
||||||
|
|
||||||
1. What CRM platform are you using (or planning to use)?
|
|
||||||
2. How many leads per month do you generate?
|
|
||||||
3. What's your current MQL definition?
|
|
||||||
4. Where do leads get stuck in your funnel?
|
|
||||||
5. Do you have SLAs between marketing and sales today?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Tool Integrations
|
|
||||||
|
|
||||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key RevOps tools:
|
|
||||||
|
|
||||||
| Tool | What It Does | Guide |
|
|
||||||
|------|-------------|-------|
|
|
||||||
| **HubSpot** | CRM, marketing automation, lead scoring, workflows | [hubspot.md](../../tools/integrations/hubspot.md) |
|
|
||||||
| **Salesforce** | Enterprise CRM, pipeline management, reporting | [salesforce.md](../../tools/integrations/salesforce.md) |
|
|
||||||
| **Calendly** | Meeting scheduling, round-robin routing | [calendly.md](../../tools/integrations/calendly.md) |
|
|
||||||
| **SavvyCal** | Scheduling with priority-based availability | [savvycal.md](../../tools/integrations/savvycal.md) |
|
|
||||||
| **Clearbit** | Real-time lead enrichment and scoring | [clearbit.md](../../tools/integrations/clearbit.md) |
|
|
||||||
| **Apollo** | Contact data, enrichment, and outbound sequences | [apollo.md](../../tools/integrations/apollo.md) |
|
|
||||||
| **ActiveCampaign** | Marketing automation for SMBs, lead scoring | [activecampaign.md](../../tools/integrations/activecampaign.md) |
|
|
||||||
| **Zapier** | Cross-tool automation and workflow glue | [zapier.md](../../tools/integrations/zapier.md) |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **cold-email**: For outbound prospecting emails
|
|
||||||
- **email-sequence**: For lifecycle and nurture email flows
|
|
||||||
- **pricing-strategy**: For pricing decisions and packaging
|
|
||||||
- **analytics-tracking**: For tracking pipeline metrics and attribution
|
|
||||||
- **launch-strategy**: For go-to-market launch planning
|
|
||||||
- **sales-enablement**: For sales collateral, decks, and objection handling
|
|
||||||
|
|
@ -1,329 +1,314 @@
|
||||||
---
|
---
|
||||||
name: sales-enablement
|
name: sales-enablement
|
||||||
description: "When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'leave-behind,' 'objection handling,' 'deal-specific ROI analysis,' 'demo script,' 'talk track,' 'sales playbook,' 'proposal template,' 'buyer persona card,' 'help my sales team,' 'sales materials,' or 'what should I give my sales reps.' Use this for any document or asset that helps a sales team close deals. For competitor comparison pages and battle cards, see competitor-alternatives. For marketing website copy, see copywriting. For cold outreach emails, see cold-email."
|
description: "When the user wants to create sales collateral, pitch decks, one-pagers, equipment proposals, objection handling docs, or demo scripts. Also use when the user mentions 'sales deck,' 'pitch deck,' 'one-pager,' 'equipment proposal,' 'objection handling,' 'financing presentation,' 'estimate justification,' 'maintenance pitch,' 'proposal template,' 'sales materials,' or 'help my sales team.' Use this for any document or asset that helps sales teams and technicians close deals or justify estimates."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, scrape, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Sales Enablement
|
# HVAC Sales Enablement
|
||||||
|
|
||||||
You are an expert in B2B sales enablement. Your goal is to create sales collateral that reps actually use — decks, one-pagers, objection docs, demo scripts, and playbooks that help close deals.
|
You are an expert in HVAC sales enablement. Your goal is to create sales collateral that technicians and sales reps actually use — proposals, objection docs, equipment guides, and scripts that help close deals and justify estimates.
|
||||||
|
|
||||||
## Before Starting
|
## Before Starting
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
1. **Value Proposition & Differentiators**
|
1. **Service Type & Value**
|
||||||
- What do you sell and who is it for?
|
- What services do you offer? (Service, repair, installation, maintenance)
|
||||||
- What makes you different from the next best alternative?
|
- What makes you different from competitors?
|
||||||
- What outcomes can you prove?
|
- What outcomes do you guarantee?
|
||||||
|
|
||||||
2. **Sales Motion**
|
2. **Sales Motion**
|
||||||
- How do you sell? (self-serve, inside sales, field sales, hybrid)
|
- How do you sell? (Phone estimates, in-home estimates, dispatch-based)
|
||||||
- Average deal size and sales cycle length
|
- Average job size
|
||||||
- Key personas involved in the buying decision
|
- Who closes (technician, sales manager, or combo)?
|
||||||
|
|
||||||
3. **Collateral Needs**
|
3. **Collateral Needs**
|
||||||
- What specific assets do you need?
|
- What specific assets do you need?
|
||||||
- What stage of the funnel are they for?
|
- What stage are they for? (Quote, on-site, follow-up, pitch)
|
||||||
- Who will use them? (AE, SDR, champion, prospect)
|
- Who will use them? (Technician, sales manager, office)
|
||||||
|
|
||||||
4. **Current State**
|
4. **Current State**
|
||||||
- What materials exist today?
|
- What materials exist?
|
||||||
- What's working and what's not?
|
- What's working and what objections kill deals?
|
||||||
- What do reps ask for most?
|
- What do technicians ask for most?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Core Principles
|
## Core Principles
|
||||||
|
|
||||||
### Sales Uses What Sales Trusts
|
### Sales Materials Must Be Used
|
||||||
Involve reps in creation. Use their language, not marketing's. If reps rewrite your deck before sending it, you wrote the wrong deck. Test drafts with your top performers first.
|
If technicians won't use your proposal template, it has failed. Involve them in creation. Use their language, not marketing's. Keep it scannable and field-friendly (mobile-optimized).
|
||||||
|
|
||||||
### Situation-Specific, Not Generic
|
### Situation-Specific, Not Generic
|
||||||
Tailor to persona, deal stage, and use case. A deck for a CTO should look different from one for a VP of Sales. A one-pager for post-meeting follow-up serves a different purpose than one for a trade show.
|
A proposal for a furnace replacement looks different from one for an emergency repair. A maintenance pitch for a residential customer differs from one for a commercial facility manager.
|
||||||
|
|
||||||
### Scannable Over Comprehensive
|
### Tie Back to Customer Outcomes
|
||||||
Reps need information in 3 seconds, not 30. Use bold headers, short bullets, and visual hierarchy. If a rep can't find the answer mid-call, the doc has failed.
|
Every claim connects to comfort, reliability, or cost. "High-efficiency compressor rated AHRI 12,500" means nothing. "Cuts your cooling costs 30% vs. your current system" resonates.
|
||||||
|
|
||||||
### Tie Back to Business Outcomes
|
### Transparency Builds Trust
|
||||||
Every claim connects to revenue, efficiency, or risk reduction. Features mean nothing without the "so what." Replace "AI-powered analytics" with "cut reporting time by 80%."
|
In HVAC, technicians are trusted advisors. Show your work in proposals. Explain why the recommendation, not just the price. Justify the equipment choice.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Sales Deck / Pitch Deck
|
## Equipment Proposals
|
||||||
|
|
||||||
### 10-12 Slide Framework
|
|
||||||
|
|
||||||
1. **Current World Problem** — The pain your buyer lives with today
|
|
||||||
2. **Cost of the Problem** — What inaction costs (time, money, risk)
|
|
||||||
3. **The Shift Happening** — Market or technology change creating urgency
|
|
||||||
4. **Your Approach** — How you solve it differently
|
|
||||||
5. **Product Walkthrough** — 3-4 key workflows, not a feature tour
|
|
||||||
6. **Proof Points** — Metrics, logos, analyst recognition
|
|
||||||
7. **Case Study** — One customer story told well
|
|
||||||
8. **Implementation / Timeline** — How they get from here to live
|
|
||||||
9. **ROI / Value** — Expected return and payback period
|
|
||||||
10. **Pricing Overview** — Transparent, tiered if applicable
|
|
||||||
11. **Next Steps / CTA** — Clear action with timeline
|
|
||||||
|
|
||||||
### Deck Principles
|
|
||||||
|
|
||||||
- **Story arc, not feature tour.** Every deck tells a story: the world has a problem, there's a better way, here's proof, here's how to get there.
|
|
||||||
- **One idea per slide.** If you need two points, use two slides.
|
|
||||||
- **Design for presenting, not reading.** Slides support the conversation — they don't replace it. Minimal text, strong visuals.
|
|
||||||
|
|
||||||
### Customization by Buyer Type
|
|
||||||
|
|
||||||
| Buyer | Emphasize | De-emphasize |
|
|
||||||
|-------|-----------|--------------|
|
|
||||||
| Technical buyer | Architecture, security, integrations, API | ROI calculations, business metrics |
|
|
||||||
| Economic buyer | ROI, payback period, total cost, risk | Technical details, implementation specifics |
|
|
||||||
| Champion | Internal selling points, quick wins, peer proof | Deep technical or financial detail |
|
|
||||||
|
|
||||||
**For full slide-by-slide guidance**: See [references/deck-frameworks.md](references/deck-frameworks.md)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## One-Pagers / Leave-Behinds
|
|
||||||
|
|
||||||
### When to Use
|
|
||||||
|
|
||||||
- **Post-meeting recap** — Reinforce what you discussed, keep momentum
|
|
||||||
- **Champion internal selling** — Arm your champion to sell for you
|
|
||||||
- **Trade show handout** — Quick intro that drives follow-up
|
|
||||||
|
|
||||||
### Structure
|
### Structure
|
||||||
|
|
||||||
1. **Problem statement** — The pain in one sentence
|
**1. Cover page**
|
||||||
2. **Your solution** — What you do and how
|
- Customer name and address
|
||||||
3. **3 differentiators** — Why you vs. alternatives
|
- Service type (Furnace Replacement, AC Repair, etc.)
|
||||||
4. **Proof point** — One strong metric or customer quote
|
- Date and proposal validity (30 days)
|
||||||
5. **CTA** — Clear next step with contact info
|
- Your company logo and contact
|
||||||
|
|
||||||
### Design Principles
|
**2. Current situation**
|
||||||
|
- What the customer has (model, age, condition)
|
||||||
|
- What's wrong (diagnosis brief)
|
||||||
|
- What happens if not fixed (risk to comfort, efficiency, safety)
|
||||||
|
|
||||||
- One page, literally. Front only, or front and back maximum.
|
**3. Recommended solution**
|
||||||
- Scannable in 30 seconds. Bold headers, short bullets, whitespace.
|
- Specific equipment model and why (AHRI rating, efficiency, reliability)
|
||||||
- Include your logo, website, and a specific contact (not info@).
|
- What's included (labor, haul-away, startup, warranty)
|
||||||
- Match your brand but keep it clean — this is a sales tool, not a brand piece.
|
- Timeline and disruption
|
||||||
|
|
||||||
**For templates by use case**: See [references/one-pager-templates.md](references/one-pager-templates.md)
|
**4. Options (Good-Better-Best)**
|
||||||
|
- **Good**: Budget-tier equipment, basic labor
|
||||||
|
- **Better**: Mid-tier equipment, full service
|
||||||
|
- **Best**: Premium equipment, extended warranty, priority service
|
||||||
|
|
||||||
|
**5. Cost breakdown**
|
||||||
|
- Equipment cost
|
||||||
|
- Labor/installation
|
||||||
|
- Haul-away/disposal
|
||||||
|
- Tax
|
||||||
|
- **Total**
|
||||||
|
|
||||||
|
**6. Value justification**
|
||||||
|
- Energy savings (monthly/annual, using AHRI and local energy costs)
|
||||||
|
- Reliability (warranty, AHRI rating = fewer breakdowns)
|
||||||
|
- Comfort (BTU, seasonal maintenance)
|
||||||
|
- Total cost of ownership vs. alternatives
|
||||||
|
|
||||||
|
**7. Financing options**
|
||||||
|
- Outright payment
|
||||||
|
- Financing partner (Affirm, Synchrony, etc.) with rates
|
||||||
|
- Maintenance agreement discount if bundled
|
||||||
|
|
||||||
|
**8. Next steps**
|
||||||
|
- What happens next (timeline, deposit, scheduling)
|
||||||
|
- Decision deadline
|
||||||
|
- Your contact for questions
|
||||||
|
|
||||||
|
**9. Appendices**
|
||||||
|
- Equipment spec sheets (AHRI ratings, efficiency)
|
||||||
|
- Warranty details
|
||||||
|
- Financing terms
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Objection Handling Docs
|
## One-Page Estimate Sheet (Field Version)
|
||||||
|
|
||||||
### Objection Categories
|
For technicians filling out estimates on-site (tablet or paper):
|
||||||
|
|
||||||
|
```
|
||||||
|
CUSTOMER: ________________ DATE: ________________
|
||||||
|
ADDRESS: _________________ PHONE: ________________
|
||||||
|
|
||||||
|
CURRENT SYSTEM:
|
||||||
|
Equipment Model: __________ Age: _______ Condition: [ ] Good [ ] Fair [ ] Poor
|
||||||
|
Issue: _____________________________________________________________________
|
||||||
|
|
||||||
|
DIAGNOSIS:
|
||||||
|
________________________________________________________________________________
|
||||||
|
|
||||||
|
RECOMMENDED SOLUTION:
|
||||||
|
Equipment: __________ (AHRI: ________, Efficiency: ________, Warranty: ________)
|
||||||
|
Reason for recommendation: ______________________________________________________
|
||||||
|
|
||||||
|
COSTS:
|
||||||
|
Equipment: $________
|
||||||
|
Labor: $________
|
||||||
|
Misc (haul-away): $________
|
||||||
|
Tax: $________
|
||||||
|
TOTAL: $________
|
||||||
|
|
||||||
|
VALUE STORY (explain why this price):
|
||||||
|
- Energy savings: $__/month (show math)
|
||||||
|
- Reliability: AHRI-rated, includes [warranty specifics]
|
||||||
|
- Comfort: Sized for home, quiet operation
|
||||||
|
|
||||||
|
FINANCING:
|
||||||
|
[ ] Full payment [ ] Financing available (see attached options)
|
||||||
|
[ ] Maintenance agreement discount (add $X/year, save $Y on repairs)
|
||||||
|
|
||||||
|
NEXT STEPS:
|
||||||
|
Proposal valid until: ________________
|
||||||
|
Call to schedule: ________________
|
||||||
|
Questions? Text or call: ________________
|
||||||
|
|
||||||
|
TECHNICIAN: ________________
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Objection Handling Documents
|
||||||
|
|
||||||
|
### Objection Categories in HVAC
|
||||||
|
|
||||||
| Category | Examples |
|
| Category | Examples |
|
||||||
|----------|----------|
|
|----------|----------|
|
||||||
| Price | "Too expensive," "No budget this quarter," "Competitor is cheaper" |
|
| **Price** | "That's too expensive," "Competitor quoted $2000 less," "I can't afford that" |
|
||||||
| Timing | "Not the right time," "Maybe next quarter," "Too busy to implement" |
|
| **Timing** | "Maybe next month," "It's still working," "Not urgent right now" |
|
||||||
| Competition | "We already use X," "What makes you different?" |
|
| **Brand** | "I've used [competitor] forever," "What about [budget brand]?" |
|
||||||
| Authority | "I need to check with my boss," "The committee decides" |
|
| **Complexity** | "Do I really need all that?" "Can't you just fix the old one?" |
|
||||||
| Status quo | "What we have works fine," "Not broken, don't fix it" |
|
| **Authority** | "I need to talk to my spouse," "Let me get another quote" |
|
||||||
| Technical | "Does it integrate with X?," "Security concerns," "Can it scale?" |
|
| **Distrust** | "Is this a scam?" "Why should I trust you?" |
|
||||||
|
|
||||||
### Response Framework
|
### Response Framework
|
||||||
|
|
||||||
For each objection, document:
|
For each objection, document:
|
||||||
|
|
||||||
1. **Objection statement** — Exactly how reps hear it
|
1. **Objection statement** — How the customer phrases it
|
||||||
2. **Why they say it** — The real concern behind the words
|
2. **Why they say it** — The real concern (fear, budget, skepticism)
|
||||||
3. **Response approach** — How to acknowledge and redirect
|
3. **Validate response** — Acknowledge their concern (don't dismiss)
|
||||||
4. **Proof point** — Specific evidence that addresses the concern
|
4. **Address the concern** — Tie back to their values
|
||||||
5. **Follow-up question** — Keep the conversation moving forward
|
5. **Proof point** — Specific evidence
|
||||||
|
6. **Reframe** — Show the real cost of inaction
|
||||||
|
7. **Next step** — Move forward
|
||||||
|
|
||||||
### Two Formats
|
### Example: "That's Too Expensive"
|
||||||
|
|
||||||
- **Quick-reference table** for live calls — objection, one-line response, proof point. Fits on one screen.
|
**Objection**: "Your quote is $3500, but I found someone for $2000."
|
||||||
- **Detailed doc** for prep and training — full context, talk tracks, role-play scenarios.
|
|
||||||
|
|
||||||
**For the full objection library**: See [references/objection-library.md](references/objection-library.md)
|
**Why**: Price shock, lack of understanding of what they get, fear of overpaying.
|
||||||
|
|
||||||
|
**Validate**: "I understand — furnace replacement is a big investment. Let me show you what's different here."
|
||||||
|
|
||||||
|
**Address**: "We're recommending a high-efficiency model with a 10-year warranty. That budget option is contractor-grade, 5-year warranty. Here's why that matters to you..."
|
||||||
|
|
||||||
|
**Proof**: "Two key differences:
|
||||||
|
- Our equipment: 95% efficient (saves $300/year on heating) vs. their 80% (saves $100/year)
|
||||||
|
- Over 10 years, you save $2000 in energy. The $1500 price difference pays for itself.
|
||||||
|
- Plus, if something breaks in year 6, the 10-year warranty covers it. The 5-year warranty doesn't."
|
||||||
|
|
||||||
|
**Reframe**: "It's not $3500 vs. $2000. It's whether to spend $1500 more now and save $2000 in energy and repair costs later."
|
||||||
|
|
||||||
|
**Next step**: "Should we start the paperwork for the high-efficiency model, or would you like me to run the numbers on the other option so you can compare?"
|
||||||
|
|
||||||
|
### Quick-Reference Card (for technician pocket)
|
||||||
|
|
||||||
|
| Objection | 30-second response | Proof |
|
||||||
|
|-----------|---|---|
|
||||||
|
| "Too expensive" | Show the payback: "Saves $300/year in energy costs. Pays for itself in 5 years." | Energy savings calculation |
|
||||||
|
| "Can't you fix it?" | "We can, but you'll need repairs every year. Replacement is cheaper long-term." | Cost of repairs vs. replacement over 10 years |
|
||||||
|
| "Need to get quotes" | "Absolutely. Here's what to ask them: warranty length, AHRI efficiency rating, emergency support." | Comparison framework |
|
||||||
|
| "Not urgent" | "True, but if it breaks in August, emergency calls cost 50% more. Want to lock in regular pricing?" | Emergency pricing premium |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## ROI Calculators & Value Props
|
## Maintenance Agreement Pitch
|
||||||
|
|
||||||
### Calculator Design
|
**When to present**: During every service call (especially if customer has older equipment)
|
||||||
|
|
||||||
**Inputs** (current state metrics the prospect provides):
|
**Structure**:
|
||||||
- Time spent on manual processes
|
|
||||||
- Current tool costs
|
|
||||||
- Error rates or inefficiency metrics
|
|
||||||
- Team size
|
|
||||||
|
|
||||||
**Calculations** (your formula for value):
|
1. **Opening**: "Before I leave, I want to make sure you're protected..."
|
||||||
- Time saved per week/month/year
|
|
||||||
- Cost reduction (tools, headcount, errors)
|
|
||||||
- Revenue impact (faster deals, higher conversion)
|
|
||||||
|
|
||||||
**Outputs** (what the prospect sees):
|
2. **Problem**: "I found a few things today that need attention [list minor issues]. With older systems, unexpected failures are the real cost."
|
||||||
- Annual ROI percentage
|
|
||||||
- Payback period in months
|
|
||||||
- Total 3-year value
|
|
||||||
|
|
||||||
### Value Prop by Persona
|
3. **Solution**: "We offer maintenance agreements so you avoid emergency calls and catch problems early."
|
||||||
|
|
||||||
| Persona | Cares About | Lead With |
|
4. **Value**:
|
||||||
|---------|-------------|-----------|
|
- "Includes 2 seasonal tune-ups"
|
||||||
| CTO / VP Eng | Architecture, scale, security, team velocity | Technical superiority, integration depth |
|
- "Priority scheduling when you need us"
|
||||||
| VP Sales | Pipeline, quota attainment, rep productivity | Revenue impact, time savings per rep |
|
- "15% discount on repairs"
|
||||||
| CFO | Total cost, payback period, risk | ROI, cost reduction, financial predictability |
|
- "Costs $X/year, but saves you $2K+ if something breaks in August"
|
||||||
| End user | Ease of use, daily workflow, learning curve | Time saved, frustration eliminated |
|
|
||||||
|
|
||||||
### Implementation Options
|
5. **Options**:
|
||||||
|
- Basic: One tune-up + discounts
|
||||||
|
- Premium: Two tune-ups + priority + higher discount
|
||||||
|
- VIP: Two tune-ups + annual inspection + all repairs discounted
|
||||||
|
|
||||||
- **Spreadsheet** — Fastest to build, easy to customize per deal. Works for inside sales.
|
6. **Close**: "Which option makes the most sense for your home?"
|
||||||
- **Web tool** — More polished, captures leads, scales better. Worth building if deal volume is high.
|
|
||||||
- **Slide-based** — ROI story embedded in the deck. Good for executive presentations.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Demo Scripts & Talk Tracks
|
## Equipment Comparison Guide
|
||||||
|
|
||||||
### Script Structure
|
**What homeowners ask**: "What's the difference between these three options you quoted?"
|
||||||
|
|
||||||
1. **Opening** (2 min) — Context setting, agenda, confirm goals for the call
|
**Create a simple comparison table**:
|
||||||
2. **Discovery recap** (3 min) — Summarize what you learned, confirm priorities
|
|
||||||
3. **Solution walkthrough** (15-20 min) — 3-4 key workflows mapped to their pain
|
|
||||||
4. **Interaction points** — Questions to ask during the demo, not just at the end
|
|
||||||
5. **Close** (5 min) — Summarize value, propose next steps with timeline
|
|
||||||
|
|
||||||
### Talk Track Types
|
| Feature | Budget Option | Recommended | Premium |
|
||||||
|
|---------|---|---|---|
|
||||||
|
| **Model** | Goodman GSX | Carrier 25HCB | Lennox XC21 |
|
||||||
|
| **Efficiency (SEER)** | 16 SEER | 18 SEER | 20 SEER |
|
||||||
|
| **Annual cooling cost** | $1200 | $1000 | $800 |
|
||||||
|
| **Warranty** | 5 years | 10 years | 12 years |
|
||||||
|
| **Quiet operation** | Standard | Quiet | Very quiet |
|
||||||
|
| **Smart controls** | No | WiFi thermostat | WiFi + zoning |
|
||||||
|
| **Price** | $2000 | $2800 | $3500 |
|
||||||
|
| **10-year total cost** | $14,000 | $12,800 | $11,800 |
|
||||||
|
|
||||||
| Type | Duration | Focus |
|
**Why recommended**: "Most customers pick the middle — best balance of comfort, efficiency, and price. The premium is quieter, but if noise isn't a concern, you'll save money without it."
|
||||||
|------|----------|-------|
|
|
||||||
| Discovery call | 30 min | Qualify, understand pain, map buying process |
|
|
||||||
| First demo | 30-45 min | Show 3-4 workflows tied to their pain |
|
|
||||||
| Technical deep-dive | 45-60 min | Architecture, security, integrations, API |
|
|
||||||
| Executive overview | 20-30 min | Business outcomes, ROI, strategic alignment |
|
|
||||||
|
|
||||||
### Key Principles
|
|
||||||
|
|
||||||
- **Demo after discovery, not before.** If you don't know their pain, you're guessing which features matter.
|
|
||||||
- **Customize to their use case.** Use their terminology, their data (if possible), their workflow.
|
|
||||||
- **Leave time for questions.** A demo where the prospect doesn't talk is a demo that doesn't close.
|
|
||||||
|
|
||||||
**For full script templates**: See [references/demo-scripts.md](references/demo-scripts.md)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Case Study Briefs (Sales Format)
|
## Common Objection Scripts
|
||||||
|
|
||||||
### How Sales Case Studies Differ
|
### "Can You Just Fix the Old One?"
|
||||||
|
|
||||||
Marketing case studies tell a story. Sales case studies arm reps with fast-access proof. Keep them short, outcome-focused, and tagged for retrieval.
|
**Script**:
|
||||||
|
"I can patch it for $X today. But here's what I'm seeing: it's a 1997 model, parts are getting hard to find, and repairs are getting more expensive. Last year you spent $1200 on repairs. This year might be similar or more.
|
||||||
|
|
||||||
### Structure
|
A new system costs $3500 installed, but:
|
||||||
|
- 10-year warranty (no repair costs for a decade)
|
||||||
|
- 30% more efficient (saves $300/year on bills)
|
||||||
|
- Quieter and more reliable
|
||||||
|
- 10-year total cost: just $2000 more than keep patching the old one
|
||||||
|
|
||||||
1. **Customer profile** — Industry, company size, buyer role
|
My recommendation: repair today if the cost is under $500, but start planning for replacement next year."
|
||||||
2. **Challenge** — What they were struggling with (2-3 sentences)
|
|
||||||
3. **Solution** — What they implemented (1-2 sentences)
|
|
||||||
4. **Results** — 3 specific metrics (before/after)
|
|
||||||
5. **Pull quote** — One sentence from the customer
|
|
||||||
6. **Tags** — Industry, use case, company size, persona
|
|
||||||
|
|
||||||
### Organization
|
### "I Need to Get Other Quotes"
|
||||||
|
|
||||||
Organize case studies so reps can find the right one instantly:
|
**Script**:
|
||||||
- **By industry** — "Show me a case study for healthcare"
|
"Absolutely, that's smart. Here's what to ask the other companies:
|
||||||
- **By use case** — "Show me someone who used us for X"
|
|
||||||
- **By company size** — "Show me an enterprise example"
|
|
||||||
|
|
||||||
---
|
1. **AHRI rating** — What's the cooling/heating capacity vs. our quote?
|
||||||
|
2. **Warranty** — How long does equipment and labor last?
|
||||||
|
3. **Efficiency** — What SEER rating for cooling, AFUE for heating?
|
||||||
|
4. **Emergency support** — Do they offer 24/7 service?
|
||||||
|
5. **Installation** — Are they using certified technicians?
|
||||||
|
|
||||||
## Proposal Templates
|
When you compare, compare the 10-year cost, not just the install price. Some contractors use lower-cost equipment, so the monthly bills stay higher. Our quote assumes higher upfront, lower monthly bills.
|
||||||
|
|
||||||
### Structure
|
Here's my card — call me with any questions. I'm happy to discuss why we're recommending what we are."
|
||||||
|
|
||||||
1. **Executive summary** — Their challenge, your solution, expected outcome (1 page max)
|
|
||||||
2. **Proposed solution** — What you'll deliver, mapped to their requirements
|
|
||||||
3. **Implementation plan** — Timeline, milestones, responsibilities
|
|
||||||
4. **Investment** — Pricing, payment terms, what's included
|
|
||||||
5. **Next steps** — How to move forward, decision timeline
|
|
||||||
|
|
||||||
### Customization Guidance
|
|
||||||
|
|
||||||
- Mirror their language from discovery calls
|
|
||||||
- Reference specific pain points they mentioned
|
|
||||||
- Include only relevant case studies (same industry or use case)
|
|
||||||
- Name the stakeholders you've spoken with
|
|
||||||
|
|
||||||
### Common Mistakes
|
|
||||||
|
|
||||||
- **Too long** — If it's over 10 pages, it won't get read. Aim for 5-7.
|
|
||||||
- **Too generic** — Templated proposals signal low effort. Customize the exec summary at minimum.
|
|
||||||
- **Burying the price** — Don't make them hunt for it. Be transparent and confident.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Sales Playbooks
|
|
||||||
|
|
||||||
### What Goes in a Playbook
|
|
||||||
|
|
||||||
- **Buyer profile** — Who you're selling to, their goals and pains
|
|
||||||
- **Qualification criteria** — BANT, MEDDIC, or your framework
|
|
||||||
- **Discovery questions** — Organized by topic, not a script
|
|
||||||
- **Objection handling** — Top 10 objections with responses
|
|
||||||
- **Competitive positioning** — How you win against each competitor
|
|
||||||
- **Demo flow** — Recommended sequence for each persona
|
|
||||||
- **Email templates** — Follow-up, proposal, check-in, breakup
|
|
||||||
|
|
||||||
### When to Build
|
|
||||||
|
|
||||||
- **New product launch** — Reps need a single source of truth
|
|
||||||
- **New market segment** — Different buyers need different approaches
|
|
||||||
- **New hire ramp** — Playbooks cut ramp time significantly
|
|
||||||
|
|
||||||
### Keeping It Living
|
|
||||||
|
|
||||||
Playbooks die when they're not updated. Review quarterly, get input from top reps, and remove anything outdated. Assign an owner — if nobody owns it, it rots.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Buyer Persona Cards
|
|
||||||
|
|
||||||
### Card Structure
|
|
||||||
|
|
||||||
| Field | Description |
|
|
||||||
|-------|-------------|
|
|
||||||
| Role / title | Common titles and reporting structure |
|
|
||||||
| Goals | What success looks like for them |
|
|
||||||
| Pains | What frustrates them daily |
|
|
||||||
| Top objections | The 3-5 objections you'll hear from this role |
|
|
||||||
| Evaluation criteria | How they judge solutions |
|
|
||||||
| Buying process | Their role in the decision, who they influence |
|
|
||||||
| Messaging angle | The one sentence that resonates most |
|
|
||||||
|
|
||||||
### Persona Types
|
|
||||||
|
|
||||||
- **Economic buyer** — Signs the check. Cares about ROI and risk.
|
|
||||||
- **Technical buyer** — Evaluates the product. Cares about capabilities and integration.
|
|
||||||
- **End user** — Uses it daily. Cares about ease and workflow fit.
|
|
||||||
- **Champion** — Advocates internally. Needs ammunition to sell for you.
|
|
||||||
- **Blocker** — Opposes the purchase. Understand their concern to neutralize it.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
||||||
Deliver the right format for each asset type:
|
When creating sales materials, provide:
|
||||||
|
|
||||||
| Asset | Deliverable |
|
| Asset | Deliverable |
|
||||||
|-------|-------------|
|
|-------|-------------|
|
||||||
| Sales deck | Slide-by-slide outline with headline, body copy, and speaker notes |
|
| Equipment proposal | Full template with customer-facing language and cost breakdown |
|
||||||
| One-pager | Full copy with layout guidance (visual hierarchy, sections) |
|
| One-pager | Scannable field estimate with space for technician notes |
|
||||||
| Objection doc | Table format: objection, response, proof point, follow-up |
|
| Objection doc | Table format: objection, 30-second response, proof point, reframe |
|
||||||
| Demo script | Scene-by-scene with timing, talk track, and interaction points |
|
| Comparison guide | Side-by-side equipment options with ROI explanation |
|
||||||
| ROI calculator | Input fields, formulas, output display with sample data |
|
| Maintenance pitch | 3-minute script with value props |
|
||||||
| Playbook | Structured document with table of contents and sections |
|
| Script | Scene-by-scene with estimated timing and key phrases |
|
||||||
| Persona card | One-page card format per persona |
|
|
||||||
| Proposal | Section-by-section copy with customization notes |
|
All materials should be:
|
||||||
|
- **Mobile-optimized** (technicians use on tablets and phones)
|
||||||
|
- **Jargon-free** (speak to homeowners, not engineers)
|
||||||
|
- **Customizable** (templates with company name, phone, pricing fields)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -331,19 +316,30 @@ Deliver the right format for each asset type:
|
||||||
|
|
||||||
If context is missing, ask:
|
If context is missing, ask:
|
||||||
|
|
||||||
1. What collateral do you need? (deck, one-pager, objection doc, etc.)
|
1. What collateral do you need? (proposal, objection doc, script, comparison guide)
|
||||||
2. Who will use it? (AE, SDR, champion, prospect)
|
2. Who will use it? (Technician, office staff, sales manager)
|
||||||
3. What sales stage is it for? (prospecting, discovery, demo, negotiation, close)
|
3. What's the typical job type? (Repair, replacement, maintenance)
|
||||||
4. Who is the target persona? (title, seniority, department)
|
4. What objections kill the most deals?
|
||||||
5. What are the top 3 objections you hear most?
|
5. What's your average job size?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Use Compendium to support sales enablement:
|
||||||
|
|
||||||
|
- **Equipment data**: Access AHRI ratings, efficiency benchmarks, and equipment cost ranges from Compendium database
|
||||||
|
- **Objection research**: Search common objections homeowners have about HVAC pricing and equipment
|
||||||
|
- **Competitor analysis**: Research competitor proposals, scripts, and objection handling approaches
|
||||||
|
|
||||||
|
**Tool tiers**: Database queries, search, analysis
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **competitor-alternatives**: For public-facing comparison and alternative pages
|
- **pricing-strategy**: For pricing decisions and equipment markups
|
||||||
- **copywriting**: For marketing website copy
|
- **copywriting**: For marketing website copy
|
||||||
- **cold-email**: For outbound prospecting emails
|
- **marketing-psychology**: For persuasion principles in proposals
|
||||||
- **revops**: For lead lifecycle, scoring, routing, and pipeline management
|
- **hvac-lead-ops**: For lead lifecycle and deal management
|
||||||
- **pricing-strategy**: For pricing decisions and packaging
|
- **hvac-estimate-popups**: For online estimate request flows
|
||||||
- **product-marketing-context**: For foundational positioning and messaging
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me create a sales deck for our B2B SaaS product. We sell an employee engagement platform to HR directors at companies with 500-5000 employees. Our main differentiator is real-time pulse surveys with AI-powered insights.",
|
"prompt": "Help me create a sales deck for our B2B SaaS product. We sell an employee engagement platform to HR directors at companies with 500-5000 employees. Our main differentiator is real-time pulse surveys with AI-powered insights.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the 10-12 slide sales deck framework: Title, Problem/Stakes, Current Solutions Failing, Vision, Product/Solution, How It Works, Proof (case studies/metrics), Pricing, Why Now, and Next Steps. Should tailor the deck to the HR director audience and employee engagement space. Should incorporate the differentiator (real-time pulse surveys + AI insights). Should provide slide-by-slide content recommendations with speaker notes. Should recommend visual direction.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the 10-12 slide sales deck framework: Title, Problem/Stakes, Current Solutions Failing, Vision, Product/Solution, How It Works, Proof (case studies/metrics), Pricing, Why Now, and Next Steps. Should tailor the deck to the HR director audience and employee engagement space. Should incorporate the differentiator (real-time pulse surveys + AI insights). Should provide slide-by-slide content recommendations with speaker notes. Should recommend visual direction.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies 10-12 slide framework",
|
"Applies 10-12 slide framework",
|
||||||
"Includes Problem, Solution, Proof, Pricing, Next Steps slides",
|
"Includes Problem, Solution, Proof, Pricing, Next Steps slides",
|
||||||
"Tailors to HR director audience",
|
"Tailors to HR director audience",
|
||||||
|
|
|
||||||
|
|
@ -1,26 +1,28 @@
|
||||||
---
|
---
|
||||||
name: schema-markup
|
name: schema-markup
|
||||||
description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.
|
description: When the user wants to add, fix, or optimize schema markup and structured data on their HVAC site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "service schema," "product schema," "review schema," "breadcrumb schema," "LocalBusiness schema," "Google rich results," "knowledge panel," "star ratings in search," "add structured data," or "GBP integration." Use this whenever someone wants their pages to show enhanced results in Google or improve local SEO visibility. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [scrape, fetch]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Schema Markup
|
# 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.
|
You are an expert in structured data and schema markup for HVAC contractors and brands. Your goal is to implement schema.org markup that helps search engines understand content, enables rich results, and improves local SEO visibility through Google Business Profile integration.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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:
|
Before implementing schema, understand:
|
||||||
|
|
||||||
1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?
|
1. **Page Type** - What kind of page? (Service, product, location, FAQ, review)
|
||||||
|
2. **Current State** - Any existing schema? Errors in implementation? Which rich results appearing?
|
||||||
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?
|
3. **Goals** - Which rich results are you targeting? What's the business value?
|
||||||
|
4. **Local Context** - Single location or multiple service areas?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -48,76 +50,254 @@ Before implementing schema, understand:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Common Schema Types
|
## HVAC-Specific Schema Types
|
||||||
|
|
||||||
| Type | Use For | Required Properties |
|
### LocalBusiness & HVACBusiness
|
||||||
|------|---------|-------------------|
|
|
||||||
| 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)
|
Use for contractor/branch locations:
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 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
|
```json
|
||||||
{
|
{
|
||||||
"@context": "https://schema.org",
|
"@context": "https://schema.org",
|
||||||
"@graph": [
|
"@type": "LocalBusiness",
|
||||||
{ "@type": "Organization", ... },
|
"name": "Denver HVAC Experts",
|
||||||
{ "@type": "WebSite", ... },
|
"image": "https://example.com/logo.png",
|
||||||
{ "@type": "BreadcrumbList", ... }
|
"description": "Professional HVAC repair, installation, and maintenance in Denver",
|
||||||
|
"address": {
|
||||||
|
"@type": "PostalAddress",
|
||||||
|
"streetAddress": "123 Main St",
|
||||||
|
"addressLocality": "Denver",
|
||||||
|
"addressRegion": "CO",
|
||||||
|
"postalCode": "80202"
|
||||||
|
},
|
||||||
|
"telephone": "+1-303-555-0100",
|
||||||
|
"url": "https://example.com",
|
||||||
|
"serviceArea": [
|
||||||
|
{
|
||||||
|
"@type": "City",
|
||||||
|
"name": "Denver"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "City",
|
||||||
|
"name": "Boulder"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"priceRange": "$",
|
||||||
|
"aggregateRating": {
|
||||||
|
"@type": "AggregateRating",
|
||||||
|
"ratingValue": "4.8",
|
||||||
|
"reviewCount": "247"
|
||||||
|
},
|
||||||
|
"openingHoursSpecification": {
|
||||||
|
"@type": "OpeningHoursSpecification",
|
||||||
|
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
|
||||||
|
"opens": "08:00",
|
||||||
|
"closes": "18:00"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Service Schema
|
||||||
|
|
||||||
|
Use for service offering pages (AC Repair, Furnace Installation, etc.):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Service",
|
||||||
|
"name": "AC Repair Service",
|
||||||
|
"description": "Professional air conditioning repair for residential and commercial systems",
|
||||||
|
"provider": {
|
||||||
|
"@type": "LocalBusiness",
|
||||||
|
"name": "Denver HVAC Experts"
|
||||||
|
},
|
||||||
|
"areaServed": [
|
||||||
|
{
|
||||||
|
"@type": "City",
|
||||||
|
"name": "Denver"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "City",
|
||||||
|
"name": "Boulder"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"availableChannel": {
|
||||||
|
"@type": "ServiceChannel",
|
||||||
|
"serviceUrl": "https://example.com/services/ac-repair",
|
||||||
|
"servicePhone": "+1-303-555-0100"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Product Schema
|
||||||
|
|
||||||
|
Use for HVAC equipment/product pages (Carrier units, thermostats, etc.):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "Product",
|
||||||
|
"name": "Carrier Comfort Series 25HCE436A013 Air Conditioner",
|
||||||
|
"image": "https://example.com/carrier-25hce436a013.jpg",
|
||||||
|
"description": "High-efficiency central air conditioner",
|
||||||
|
"brand": "Carrier",
|
||||||
|
"manufacturer": "Carrier",
|
||||||
|
"sku": "25HCE436A013",
|
||||||
|
"offers": {
|
||||||
|
"@type": "Offer",
|
||||||
|
"priceCurrency": "USD",
|
||||||
|
"price": "4999",
|
||||||
|
"availability": "https://schema.org/InStock"
|
||||||
|
},
|
||||||
|
"aggregateRating": {
|
||||||
|
"@type": "AggregateRating",
|
||||||
|
"ratingValue": "4.6",
|
||||||
|
"reviewCount": "89"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Review & AggregateRating Schema
|
||||||
|
|
||||||
|
Use for customer testimonials:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "AggregateRating",
|
||||||
|
"ratingValue": "4.8",
|
||||||
|
"ratingCount": "247",
|
||||||
|
"bestRating": "5",
|
||||||
|
"worstRating": "1"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### HowTo Schema
|
||||||
|
|
||||||
|
Use for installation guides, troubleshooting, maintenance guides:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "HowTo",
|
||||||
|
"name": "How to Replace Your HVAC Filter",
|
||||||
|
"description": "Step-by-step guide to replacing your residential HVAC filter",
|
||||||
|
"totalTime": "PT10M",
|
||||||
|
"step": [
|
||||||
|
{
|
||||||
|
"@type": "HowToStep",
|
||||||
|
"name": "Turn off your system",
|
||||||
|
"text": "Locate your thermostat and turn off the HVAC system"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "HowToStep",
|
||||||
|
"name": "Find the filter",
|
||||||
|
"text": "Look for the air filter near the furnace or return air duct"
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### FAQPage Schema
|
||||||
|
|
||||||
|
Use for FAQ content:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@type": "FAQPage",
|
||||||
|
"mainEntity": [
|
||||||
|
{
|
||||||
|
"@type": "Question",
|
||||||
|
"name": "What is SEER rating?",
|
||||||
|
"acceptedAnswer": {
|
||||||
|
"@type": "Answer",
|
||||||
|
"text": "SEER (Seasonal Energy Efficiency Ratio) measures air conditioner efficiency..."
|
||||||
|
}
|
||||||
|
}
|
||||||
]
|
]
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Common Schema Types Reference
|
||||||
|
|
||||||
|
| Type | Use For | Required Properties |
|
||||||
|
|------|---------|-------------------|
|
||||||
|
| LocalBusiness | Contractor locations | name, address, telephone |
|
||||||
|
| HVACBusiness | HVAC-specific business info | name, address, service areas |
|
||||||
|
| Service | Service offerings | name, provider, areaServed |
|
||||||
|
| Product | Equipment/parts | name, image, offers |
|
||||||
|
| Review / AggregateRating | Customer reviews | ratingValue, reviewCount |
|
||||||
|
| FAQPage | FAQ content | mainEntity (Q&A array) |
|
||||||
|
| HowTo | Guides, tutorials | name, step |
|
||||||
|
| BreadcrumbList | Navigation breadcrumbs | itemListElement |
|
||||||
|
| Organization | Company homepage/about | name, url |
|
||||||
|
| Article | Blog posts about HVAC | headline, image, datePublished |
|
||||||
|
|
||||||
|
**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Multiple Schema Types on One Page
|
||||||
|
|
||||||
|
Combine multiple schema types using `@graph`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"@context": "https://schema.org",
|
||||||
|
"@graph": [
|
||||||
|
{
|
||||||
|
"@type": "LocalBusiness",
|
||||||
|
"name": "Denver HVAC Experts",
|
||||||
|
...
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "Service",
|
||||||
|
"name": "AC Repair",
|
||||||
|
...
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"@type": "BreadcrumbList",
|
||||||
|
...
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## GBP Integration
|
||||||
|
|
||||||
|
Schema markup works in tandem with Google Business Profile to improve local visibility:
|
||||||
|
|
||||||
|
**LocalBusiness schema should mirror your GBP data:**
|
||||||
|
- Business name (exact match)
|
||||||
|
- Address (exact match)
|
||||||
|
- Phone number
|
||||||
|
- Service areas
|
||||||
|
- Hours (if consistent)
|
||||||
|
- Website URL
|
||||||
|
- Aggregate rating (pulled from GBP reviews)
|
||||||
|
|
||||||
|
**Best practice**: Keep GBP and website schema in sync for maximum visibility in local pack.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Validation and Testing
|
## Validation and Testing
|
||||||
|
|
||||||
### Tools
|
### Tools
|
||||||
- **Google Rich Results Test**: https://search.google.com/test/rich-results
|
- **Google Rich Results Test**: https://search.google.com/test/rich-results (RENDERS JAVASCRIPT)
|
||||||
- **Schema.org Validator**: https://validator.schema.org/
|
- **Schema.org Validator**: https://validator.schema.org/
|
||||||
- **Search Console**: Enhancements reports
|
- **Search Console**: Enhancements reports
|
||||||
|
- **Google Structured Data Testing Tool**: https://search.google.com/structured-data/testing-tool
|
||||||
|
|
||||||
### Common Errors
|
### Common Errors
|
||||||
|
|
||||||
**Missing required properties** - Check Google's documentation for required fields
|
**Missing required properties** - Check Google's documentation for required fields per schema type
|
||||||
|
|
||||||
**Invalid values** - Dates must be ISO 8601, URLs fully qualified, enumerations exact
|
**Invalid values** - Dates must be ISO 8601, URLs fully qualified, phone numbers valid format
|
||||||
|
|
||||||
**Mismatch with page content** - Schema doesn't match visible content
|
**Mismatch with page content** - Schema doesn't match visible content
|
||||||
|
|
||||||
|
|
@ -139,6 +319,11 @@ You can combine multiple schema types on one page using `@graph`:
|
||||||
- Theme modifications
|
- Theme modifications
|
||||||
- Custom fields to structured data
|
- Custom fields to structured data
|
||||||
|
|
||||||
|
### Location Pages (Multi-Location)
|
||||||
|
- Templated LocalBusiness schema per location
|
||||||
|
- Service area arrays populated per location
|
||||||
|
- Address and phone unique per location
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Output Format
|
## Output Format
|
||||||
|
|
@ -158,6 +343,16 @@ You can combine multiple schema types on one page using `@graph`:
|
||||||
- [ ] No errors or warnings
|
- [ ] No errors or warnings
|
||||||
- [ ] Matches page content
|
- [ ] Matches page content
|
||||||
- [ ] All required properties included
|
- [ ] All required properties included
|
||||||
|
- [ ] Matches GBP data (if LocalBusiness)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill integrates with Compendium content intelligence platform:
|
||||||
|
- **Tool tier**: `scrape` (extract competitor schema), `fetch` (validate schema on crawl)
|
||||||
|
- **Reference**: See `COMPENDIUM_INTEGRATION.md` for data extraction (equipment specs, service categories, pricing)
|
||||||
|
- **Use case**: Standardize schema across HVAC contractor network, benchmark schema adoption vs. competitors
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -168,12 +363,13 @@ You can combine multiple schema types on one page using `@graph`:
|
||||||
3. What data is available to populate the schema?
|
3. What data is available to populate the schema?
|
||||||
4. Is there existing schema on the page?
|
4. Is there existing schema on the page?
|
||||||
5. What's your tech stack?
|
5. What's your tech stack?
|
||||||
|
6. Single location or multiple service areas?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **seo-audit**: For overall SEO including schema review
|
- **seo-audit**: For overall SEO including schema review and local SEO audit
|
||||||
- **ai-seo**: For AI search optimization (schema helps AI understand content)
|
- **ai-seo**: For AI search optimization (schema helps AI understand content)
|
||||||
- **programmatic-seo**: For templated schema at scale
|
- **programmatic-seo**: For templated schema at scale (location + service matrix)
|
||||||
- **site-architecture**: For breadcrumb structure and navigation schema planning
|
- **site-architecture**: For breadcrumb structure and navigation schema planning
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"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.",
|
"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.",
|
"expected_output": "Should check for hvac-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": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Implements Organization schema in JSON-LD",
|
"Implements Organization schema in JSON-LD",
|
||||||
"Includes required and recommended properties",
|
"Includes required and recommended properties",
|
||||||
"Recommends additional relevant schema types",
|
"Recommends additional relevant schema types",
|
||||||
|
|
|
||||||
|
|
@ -1,34 +1,39 @@
|
||||||
---
|
---
|
||||||
name: seo-audit
|
name: seo-audit
|
||||||
description: When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup. For AI search optimization, see ai-seo.
|
description: When the user wants to audit, review, or diagnose SEO issues on their HVAC contractor or brand site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," "local SEO," "GBP optimization," "NAP consistency," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup. For AI search optimization, see ai-seo.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [browse, scrape, search, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# SEO Audit
|
# SEO Audit
|
||||||
|
|
||||||
You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.
|
You are an expert in search engine optimization for HVAC contractors and brands. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance, with special attention to local SEO critical for HVAC service areas.
|
||||||
|
|
||||||
## Initial Assessment
|
## Initial Assessment
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` 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 auditing, understand:
|
Before auditing, understand:
|
||||||
|
|
||||||
1. **Site Context**
|
1. **Site Context**
|
||||||
- What type of site? (SaaS, e-commerce, blog, etc.)
|
- Type of HVAC business? (Contractor, equipment manufacturer, service-focused, multi-location?)
|
||||||
- What's the primary business goal for SEO?
|
- What's the primary business goal for SEO?
|
||||||
- What keywords/topics are priorities?
|
- What service areas or keywords are priorities? (e.g., "HVAC repair in Denver," "Carrier AC units")
|
||||||
|
|
||||||
2. **Current State**
|
2. **Current State**
|
||||||
- Any known issues or concerns?
|
- Any known issues or concerns?
|
||||||
- Current organic traffic level?
|
- Current organic traffic level?
|
||||||
- Recent changes or migrations?
|
- Recent changes or migrations?
|
||||||
|
- Google Business Profile status?
|
||||||
|
|
||||||
3. **Scope**
|
3. **Scope**
|
||||||
- Full site audit or specific pages?
|
- Full site audit or specific service areas?
|
||||||
- Technical + on-page, or one focus area?
|
- Technical + on-page, or one focus area?
|
||||||
|
- Local SEO included?
|
||||||
- Access to Search Console / analytics?
|
- Access to Search Console / analytics?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -39,7 +44,7 @@ Before auditing, understand:
|
||||||
|
|
||||||
**`web_fetch` and `curl` cannot reliably detect structured data / schema markup.**
|
**`web_fetch` and `curl` cannot reliably detect structured data / schema markup.**
|
||||||
|
|
||||||
Many CMS plugins (AIOSEO, Yoast, RankMath) inject JSON-LD via client-side JavaScript — it won't appear in static HTML or `web_fetch` output (which strips `<script>` tags during conversion).
|
Many CMS plugins inject JSON-LD via client-side JavaScript — it won't appear in static HTML or `web_fetch` output (which strips `<script>` tags during conversion).
|
||||||
|
|
||||||
**To accurately check for schema markup, use one of these methods:**
|
**To accurately check for schema markup, use one of these methods:**
|
||||||
1. **Browser tool** — render the page and run: `document.querySelectorAll('script[type="application/ld+json"]')`
|
1. **Browser tool** — render the page and run: `document.querySelectorAll('script[type="application/ld+json"]')`
|
||||||
|
|
@ -52,8 +57,9 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
1. **Crawlability & Indexation** (can Google find and index it?)
|
1. **Crawlability & Indexation** (can Google find and index it?)
|
||||||
2. **Technical Foundations** (is the site fast and functional?)
|
2. **Technical Foundations** (is the site fast and functional?)
|
||||||
3. **On-Page Optimization** (is content optimized?)
|
3. **On-Page Optimization** (is content optimized?)
|
||||||
4. **Content Quality** (does it deserve to rank?)
|
4. **Local SEO** (GBP, NAP, citations, reviews)
|
||||||
5. **Authority & Links** (does it have credibility?)
|
5. **Content Quality** (does it deserve to rank?)
|
||||||
|
6. **Authority & Links** (does it have credibility?)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -75,14 +81,13 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
**Site Architecture**
|
**Site Architecture**
|
||||||
- Important pages within 3 clicks of homepage
|
- Important pages within 3 clicks of homepage
|
||||||
- Logical hierarchy
|
- Logical hierarchy (Home > Services > Service Detail)
|
||||||
- Internal linking structure
|
- Internal linking structure
|
||||||
- No orphan pages
|
- No orphan pages
|
||||||
|
|
||||||
**Crawl Budget Issues** (for large sites)
|
**Crawl Budget Issues** (for larger contractor networks)
|
||||||
- Parameterized URLs under control
|
- Parameterized URLs under control
|
||||||
- Faceted navigation handled properly
|
- Faceted navigation handled properly
|
||||||
- Infinite scroll with pagination fallback
|
|
||||||
- Session IDs not in URLs
|
- Session IDs not in URLs
|
||||||
|
|
||||||
### Indexation
|
### Indexation
|
||||||
|
|
@ -147,7 +152,7 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
### URL Structure
|
### URL Structure
|
||||||
|
|
||||||
- Readable, descriptive URLs
|
- Readable, descriptive URLs (e.g., `/services/ac-repair` not `/svc/123`)
|
||||||
- Keywords in URLs where natural
|
- Keywords in URLs where natural
|
||||||
- Consistent structure
|
- Consistent structure
|
||||||
- No unnecessary parameters
|
- No unnecessary parameters
|
||||||
|
|
@ -155,13 +160,85 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Local SEO Audit
|
||||||
|
|
||||||
|
Critical for HVAC contractors competing in specific service areas.
|
||||||
|
|
||||||
|
### Google Business Profile (GBP)
|
||||||
|
|
||||||
|
**Profile Completeness**
|
||||||
|
- [ ] Name, address, phone (NAP) accurate
|
||||||
|
- [ ] Service areas defined
|
||||||
|
- [ ] Business category correct (HVAC Contractor, Plumber, etc.)
|
||||||
|
- [ ] Business description compelling
|
||||||
|
- [ ] All photos uploaded and optimized
|
||||||
|
- [ ] Hours updated and accurate
|
||||||
|
- [ ] Website URL points to main site
|
||||||
|
- [ ] Messaging enabled (if supported)
|
||||||
|
|
||||||
|
**NAP Consistency**
|
||||||
|
- Exact match across website, GBP, directories
|
||||||
|
- Watch for variations: "John's HVAC" vs "Johns HVAC Inc."
|
||||||
|
- Special characters and abbreviations must match
|
||||||
|
|
||||||
|
**Review Management**
|
||||||
|
- [ ] Responding to reviews (positive and negative)
|
||||||
|
- [ ] Review count and rating prominently displayed on website
|
||||||
|
- [ ] Encouraging customers to leave reviews
|
||||||
|
- [ ] No fake or paid reviews
|
||||||
|
- [ ] Review velocity (consistent new reviews)
|
||||||
|
|
||||||
|
### Local Citations
|
||||||
|
|
||||||
|
**Citation Audit**
|
||||||
|
- [ ] Yelp business profile
|
||||||
|
- [ ] HVAC industry directories (e.g., HVAC.com, ServiceTitan)
|
||||||
|
- [ ] General directories (BBB, Angi, HomeAdvisor)
|
||||||
|
- [ ] Local directories (Chamber of Commerce, city business listings)
|
||||||
|
- [ ] Consistent NAP across all citations
|
||||||
|
|
||||||
|
**Citation Quality**
|
||||||
|
- Authority of citing sites
|
||||||
|
- NAP consistency (exact match preferred)
|
||||||
|
- Complete business information (category, description)
|
||||||
|
|
||||||
|
### Local Content & Service Pages
|
||||||
|
|
||||||
|
**Service Area Pages**
|
||||||
|
- [ ] Dedicated pages for each service area/city
|
||||||
|
- [ ] Unique content (not just city name swapped)
|
||||||
|
- [ ] Local schema markup with service area data
|
||||||
|
- [ ] Local testimonials or case studies
|
||||||
|
- [ ] Service area list on homepage
|
||||||
|
|
||||||
|
**Service Pages**
|
||||||
|
- [ ] Dedicated page per major service (AC repair, furnace installation, etc.)
|
||||||
|
- [ ] Service-specific keywords targeted
|
||||||
|
- [ ] Local modifiers on service pages ("HVAC repair in [City]")
|
||||||
|
|
||||||
|
### Local Schema Markup
|
||||||
|
|
||||||
|
- LocalBusiness schema with NAP, service areas, ratings
|
||||||
|
- Service schema for each service offered
|
||||||
|
- AggregateRating schema (if review data available)
|
||||||
|
- Organization schema with local address
|
||||||
|
|
||||||
|
### Local Link Building
|
||||||
|
|
||||||
|
- Backlinks from local HVAC associations
|
||||||
|
- Sponsorships of local events
|
||||||
|
- Local business partnerships
|
||||||
|
- Industry directory listings
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## On-Page SEO Audit
|
## On-Page SEO Audit
|
||||||
|
|
||||||
### Title Tags
|
### Title Tags
|
||||||
|
|
||||||
**Check for:**
|
**Check for:**
|
||||||
- Unique titles for each page
|
- Unique titles for each page
|
||||||
- Primary keyword near beginning
|
- Primary keyword near beginning (e.g., "AC Repair Denver | 24/7 HVAC Service")
|
||||||
- 50-60 characters (visible in SERP)
|
- 50-60 characters (visible in SERP)
|
||||||
- Compelling and click-worthy
|
- Compelling and click-worthy
|
||||||
- Brand name placement (end, usually)
|
- Brand name placement (end, usually)
|
||||||
|
|
@ -178,8 +255,8 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
**Check for:**
|
**Check for:**
|
||||||
- Unique descriptions per page
|
- Unique descriptions per page
|
||||||
- 150-160 characters
|
- 150-160 characters
|
||||||
- Includes primary keyword
|
- Includes primary keyword or service area
|
||||||
- Clear value proposition
|
- Clear value proposition (e.g., "Same-day AC repair, licensed technicians, available 24/7")
|
||||||
- Call to action
|
- Call to action
|
||||||
|
|
||||||
**Common issues:**
|
**Common issues:**
|
||||||
|
|
@ -192,7 +269,7 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
**Check for:**
|
**Check for:**
|
||||||
- One H1 per page
|
- One H1 per page
|
||||||
- H1 contains primary keyword
|
- H1 contains primary keyword/service (e.g., "Professional HVAC Repair in Denver")
|
||||||
- Logical hierarchy (H1 → H2 → H3)
|
- Logical hierarchy (H1 → H2 → H3)
|
||||||
- Headings describe content
|
- Headings describe content
|
||||||
- Not just for styling
|
- Not just for styling
|
||||||
|
|
@ -214,16 +291,16 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
**Thin Content Issues**
|
**Thin Content Issues**
|
||||||
- Pages with little unique content
|
- Pages with little unique content
|
||||||
- Tag/category pages with no value
|
- Generic service descriptions (same as 10 other contractors)
|
||||||
- Doorway pages
|
- No local differentiation
|
||||||
- Duplicate or near-duplicate content
|
- Missing service details
|
||||||
|
|
||||||
### Image Optimization
|
### Image Optimization
|
||||||
|
|
||||||
**Check for:**
|
**Check for:**
|
||||||
- Descriptive file names
|
- Descriptive file names (e.g., `hvac-repair-denver.jpg` not `img123.jpg`)
|
||||||
- Alt text on all images
|
- Alt text on all images
|
||||||
- Alt text describes image
|
- Alt text describes image and includes service/location where relevant
|
||||||
- Compressed file sizes
|
- Compressed file sizes
|
||||||
- Modern formats (WebP)
|
- Modern formats (WebP)
|
||||||
- Lazy loading implemented
|
- Lazy loading implemented
|
||||||
|
|
@ -242,21 +319,21 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
- Orphan pages (no internal links)
|
- Orphan pages (no internal links)
|
||||||
- Over-optimized anchor text
|
- Over-optimized anchor text
|
||||||
- Important pages buried
|
- Important pages buried
|
||||||
- Excessive footer/sidebar links
|
- Service pages not linked from homepage
|
||||||
|
|
||||||
### Keyword Targeting
|
### Keyword Targeting
|
||||||
|
|
||||||
**Per Page**
|
**Per Page**
|
||||||
- Clear primary keyword target
|
- Clear primary keyword/service target
|
||||||
- Title, H1, URL aligned
|
- Title, H1, URL aligned
|
||||||
- Content satisfies search intent
|
- Content satisfies search intent
|
||||||
- Not competing with other pages (cannibalization)
|
- Not competing with other pages (cannibalization)
|
||||||
|
|
||||||
**Site-Wide**
|
**Site-Wide**
|
||||||
- Keyword mapping document
|
- Keyword mapping document
|
||||||
- No major gaps in coverage
|
- Service areas covered
|
||||||
|
- No major gaps in service coverage
|
||||||
- No keyword cannibalization
|
- No keyword cannibalization
|
||||||
- Logical topical clusters
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -265,32 +342,36 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
### E-E-A-T Signals
|
### E-E-A-T Signals
|
||||||
|
|
||||||
**Experience**
|
**Experience**
|
||||||
- First-hand experience demonstrated
|
- Real project examples and case studies
|
||||||
- Original insights/data
|
- Before/after photos
|
||||||
- Real examples and case studies
|
- Technician bios (experience/certifications)
|
||||||
|
- Years in business
|
||||||
|
|
||||||
**Expertise**
|
**Expertise**
|
||||||
- Author credentials visible
|
- Technician credentials (EPA, licenses)
|
||||||
- Accurate, detailed information
|
- Detailed service explanations
|
||||||
- Properly sourced claims
|
- Accurate, technical information
|
||||||
|
- Industry certifications listed
|
||||||
|
|
||||||
**Authoritativeness**
|
**Authoritativeness**
|
||||||
- Recognized in the space
|
- Awards and recognition
|
||||||
- Cited by others
|
- Industry association memberships
|
||||||
- Industry credentials
|
- Featured in local media
|
||||||
|
- Customer testimonials with verified details
|
||||||
|
|
||||||
**Trustworthiness**
|
**Trustworthiness**
|
||||||
- Accurate information
|
- Accurate information
|
||||||
- Transparent about business
|
- Transparent pricing or pricing model
|
||||||
- Contact information available
|
- Contact information and business hours easy to find
|
||||||
- Privacy policy, terms
|
- Privacy policy, terms
|
||||||
- Secure site (HTTPS)
|
- Secure site (HTTPS)
|
||||||
|
- Reviews and ratings visible
|
||||||
|
|
||||||
### Content Depth
|
### Content Depth
|
||||||
|
|
||||||
- Comprehensive coverage of topic
|
- Comprehensive coverage of services offered
|
||||||
- Answers follow-up questions
|
- Answers follow-up questions ("How long does AC repair take?", "What causes HVAC breakdown?")
|
||||||
- Better than top-ranking competitors
|
- Better than competitors
|
||||||
- Updated and current
|
- Updated and current
|
||||||
|
|
||||||
### User Engagement Signals
|
### User Engagement Signals
|
||||||
|
|
@ -304,33 +385,27 @@ Reporting "no schema found" based solely on `web_fetch` or `curl` leads to false
|
||||||
|
|
||||||
## Common Issues by Site Type
|
## Common Issues by Site Type
|
||||||
|
|
||||||
### SaaS/Product Sites
|
### HVAC Contractor (Local Multi-Service)
|
||||||
- Product pages lack content depth
|
- Thin service descriptions (same template for all services)
|
||||||
- Blog not integrated with product pages
|
- Missing service area pages
|
||||||
- Missing comparison/alternative pages
|
- NAP inconsistencies across web and GBP
|
||||||
- Feature pages thin on content
|
- No structured data for local business
|
||||||
- No glossary/educational content
|
- Outdated pricing or service info
|
||||||
|
- Missing customer reviews/testimonials
|
||||||
|
|
||||||
### E-commerce
|
### HVAC Equipment Brand / Manufacturer
|
||||||
- Thin category pages
|
- Product pages lack installation guides or compatibility info
|
||||||
- Duplicate product descriptions
|
- No contractor locator pages
|
||||||
- Missing product schema
|
- Missing schema for products
|
||||||
- Faceted navigation creating duplicates
|
- Competitor comparison content weak
|
||||||
- Out-of-stock pages mishandled
|
- Technical documentation not SEO-optimized
|
||||||
|
|
||||||
### Content/Blog Sites
|
### HVAC Service Company Network
|
||||||
- Outdated content not refreshed
|
- Location pages thin or duplicate
|
||||||
- Keyword cannibalization
|
- Service area cannibalization
|
||||||
- No topical clustering
|
- Inconsistent branding/NAP across locations
|
||||||
- Poor internal linking
|
- Missing local content per location
|
||||||
- Missing author pages
|
- Link equity not consolidated
|
||||||
|
|
||||||
### Local Business
|
|
||||||
- Inconsistent NAP
|
|
||||||
- Missing local schema
|
|
||||||
- No Google Business Profile optimization
|
|
||||||
- Missing location pages
|
|
||||||
- No local content
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -351,6 +426,9 @@ For each issue:
|
||||||
- **Fix**: Specific recommendation
|
- **Fix**: Specific recommendation
|
||||||
- **Priority**: 1-5 or High/Medium/Low
|
- **Priority**: 1-5 or High/Medium/Low
|
||||||
|
|
||||||
|
**Local SEO Findings**
|
||||||
|
Same format as above, with focus on GBP, citations, NAP, reviews
|
||||||
|
|
||||||
**On-Page SEO Findings**
|
**On-Page SEO Findings**
|
||||||
Same format as above
|
Same format as above
|
||||||
|
|
||||||
|
|
@ -365,9 +443,18 @@ Same format as above
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
This skill integrates with Compendium content intelligence platform for HVAC market analysis:
|
||||||
|
- **Tool tier**: `browse` (inspect competitor sites), `scrape` (extract local listings), `search` (query research), `analyze` (AI interpretation)
|
||||||
|
- **Reference**: See `COMPENDIUM_INTEGRATION.md` for data pipelines (contractor discovery, review aggregation, HVAC component research)
|
||||||
|
- **Use case**: Identify ranking gaps vs. HVAC competitors, benchmark local SEO maturity, discover content opportunities from competitor analysis
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## References
|
## References
|
||||||
|
|
||||||
- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid (em dashes, overused phrases, filler words)
|
- [AI Writing Detection](references/ai-writing-detection.md): Common AI writing patterns to avoid
|
||||||
- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill
|
- For AI search optimization (AEO, GEO, LLMO, AI Overviews), see the **ai-seo** skill
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -381,6 +468,7 @@ Same format as above
|
||||||
- Rich Results Test (**use this for schema validation — it renders JavaScript**)
|
- Rich Results Test (**use this for schema validation — it renders JavaScript**)
|
||||||
- Mobile-Friendly Test
|
- Mobile-Friendly Test
|
||||||
- Schema Validator
|
- Schema Validator
|
||||||
|
- Google My Business (now Google Business Profile)
|
||||||
|
|
||||||
> **Note on schema detection:** `web_fetch` strips `<script>` tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
|
> **Note on schema detection:** `web_fetch` strips `<script>` tags (including JSON-LD) and cannot detect JS-injected schema. Use the browser tool, Rich Results Test, or Screaming Frog instead — they render JavaScript and capture dynamically-injected markup. See the Schema Markup Detection Limitation section above.
|
||||||
|
|
||||||
|
|
@ -389,24 +477,24 @@ Same format as above
|
||||||
- Ahrefs / Semrush
|
- Ahrefs / Semrush
|
||||||
- Sitebulb
|
- Sitebulb
|
||||||
- ContentKing
|
- ContentKing
|
||||||
|
- Local SEO tools (Brightlocal, SEMrush Local, Ahrefs Local)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. What pages/keywords matter most?
|
1. What service areas matter most?
|
||||||
2. Do you have Search Console access?
|
2. Do you have Search Console and Google Business Profile access?
|
||||||
3. Any recent changes or migrations?
|
3. Any recent changes, updates, or migrations?
|
||||||
4. Who are your top organic competitors?
|
4. Who are your top organic competitors?
|
||||||
5. What's your current organic traffic baseline?
|
5. What's your current organic traffic baseline?
|
||||||
|
6. Are you a single location or multi-location?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **ai-seo**: For optimizing content for AI search engines (AEO, GEO, LLMO)
|
- **ai-seo**: AI search optimization (AEO, GEO, LLMO)
|
||||||
- **programmatic-seo**: For building SEO pages at scale
|
- **programmatic-seo**: SEO pages at scale (location + service matrix)
|
||||||
- **site-architecture**: For page hierarchy, navigation design, and URL structure
|
- **site-architecture**: Page hierarchy, navigation, URL structure
|
||||||
- **schema-markup**: For implementing structured data
|
- **schema-markup**: Structured data including LocalBusiness
|
||||||
- **page-cro**: For optimizing pages for conversion (not just ranking)
|
|
||||||
- **analytics-tracking**: For measuring SEO performance
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Can you do an SEO audit of our SaaS website? We're getting about 2,000 organic visits/month but feel like we should be getting more. URL: https://example.com",
|
"prompt": "Can you do an SEO audit of our SaaS website? We're getting about 2,000 organic visits/month but feel like we should be getting more. URL: https://example.com",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should ask clarifying questions about priority keywords, Search Console access, recent changes, and competitors. Should follow the audit framework priority order: Crawlability & Indexation, Technical Foundations, On-Page Optimization, Content Quality, Authority & Links. Should check robots.txt, XML sitemap, site architecture. Should evaluate title tags, meta descriptions, heading structure, and content optimization. Should NOT report on schema markup based solely on web_fetch (must note the detection limitation). Output should follow the Audit Report Structure: Executive Summary, Technical SEO Findings, On-Page SEO Findings, Content Findings, and Prioritized Action Plan.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should ask clarifying questions about priority keywords, Search Console access, recent changes, and competitors. Should follow the audit framework priority order: Crawlability & Indexation, Technical Foundations, On-Page Optimization, Content Quality, Authority & Links. Should check robots.txt, XML sitemap, site architecture. Should evaluate title tags, meta descriptions, heading structure, and content optimization. Should NOT report on schema markup based solely on web_fetch (must note the detection limitation). Output should follow the Audit Report Structure: Executive Summary, Technical SEO Findings, On-Page SEO Findings, Content Findings, and Prioritized Action Plan.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Asks clarifying questions about keywords, Search Console, recent changes",
|
"Asks clarifying questions about keywords, Search Console, recent changes",
|
||||||
"Follows audit priority order: crawlability first, then technical, on-page, content, authority",
|
"Follows audit priority order: crawlability first, then technical, on-page, content, authority",
|
||||||
"Checks robots.txt and XML sitemap",
|
"Checks robots.txt and XML sitemap",
|
||||||
|
|
|
||||||
|
|
@ -1,359 +0,0 @@
|
||||||
---
|
|
||||||
name: signup-flow-cro
|
|
||||||
description: When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the user mentions "signup conversions," "registration friction," "signup form optimization," "free trial signup," "reduce signup dropoff," "account creation flow," "people aren't signing up," "signup abandonment," "trial conversion rate," "nobody completes registration," "too many steps to sign up," or "simplify our signup." Use this whenever the user has a signup or registration flow that isn't performing. For post-signup onboarding, see onboarding-cro. For lead capture forms (not account creation), see form-cro.
|
|
||||||
metadata:
|
|
||||||
version: 1.1.0
|
|
||||||
---
|
|
||||||
|
|
||||||
# Signup Flow CRO
|
|
||||||
|
|
||||||
You are an expert in optimizing signup and registration flows. Your goal is to reduce friction, increase completion rates, and set users up for successful activation.
|
|
||||||
|
|
||||||
## Initial Assessment
|
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` 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 providing recommendations, understand:
|
|
||||||
|
|
||||||
1. **Flow Type**
|
|
||||||
- Free trial signup
|
|
||||||
- Freemium account creation
|
|
||||||
- Paid account creation
|
|
||||||
- Waitlist/early access signup
|
|
||||||
- B2B vs B2C
|
|
||||||
|
|
||||||
2. **Current State**
|
|
||||||
- How many steps/screens?
|
|
||||||
- What fields are required?
|
|
||||||
- What's the current completion rate?
|
|
||||||
- Where do users drop off?
|
|
||||||
|
|
||||||
3. **Business Constraints**
|
|
||||||
- What data is genuinely needed at signup?
|
|
||||||
- Are there compliance requirements?
|
|
||||||
- What happens immediately after signup?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Core Principles
|
|
||||||
|
|
||||||
### 1. Minimize Required Fields
|
|
||||||
Every field reduces conversion. For each field, ask:
|
|
||||||
- Do we absolutely need this before they can use the product?
|
|
||||||
- Can we collect this later through progressive profiling?
|
|
||||||
- Can we infer this from other data?
|
|
||||||
|
|
||||||
**Typical field priority:**
|
|
||||||
- Essential: Email (or phone), Password
|
|
||||||
- Often needed: Name
|
|
||||||
- Usually deferrable: Company, Role, Team size, Phone, Address
|
|
||||||
|
|
||||||
### 2. Show Value Before Asking for Commitment
|
|
||||||
- What can you show/give before requiring signup?
|
|
||||||
- Can they experience the product before creating an account?
|
|
||||||
- Reverse the order: value first, signup second
|
|
||||||
|
|
||||||
### 3. Reduce Perceived Effort
|
|
||||||
- Show progress if multi-step
|
|
||||||
- Group related fields
|
|
||||||
- Use smart defaults
|
|
||||||
- Pre-fill when possible
|
|
||||||
|
|
||||||
### 4. Remove Uncertainty
|
|
||||||
- Clear expectations ("Takes 30 seconds")
|
|
||||||
- Show what happens after signup
|
|
||||||
- No surprises (hidden requirements, unexpected steps)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Field-by-Field Optimization
|
|
||||||
|
|
||||||
### Email Field
|
|
||||||
- Single field (no email confirmation field)
|
|
||||||
- Inline validation for format
|
|
||||||
- Check for common typos (gmial.com → gmail.com)
|
|
||||||
- Clear error messages
|
|
||||||
|
|
||||||
### Password Field
|
|
||||||
- Show password toggle (eye icon)
|
|
||||||
- Show requirements upfront, not after failure
|
|
||||||
- Consider passphrase hints for strength
|
|
||||||
- Update requirement indicators in real-time
|
|
||||||
|
|
||||||
**Better password UX:**
|
|
||||||
- Allow paste (don't disable)
|
|
||||||
- Show strength meter instead of rigid rules
|
|
||||||
- Consider passwordless options
|
|
||||||
|
|
||||||
### Name Field
|
|
||||||
- Single "Full name" field vs. First/Last split (test this)
|
|
||||||
- Only require if immediately used (personalization)
|
|
||||||
- Consider making optional
|
|
||||||
|
|
||||||
### Social Auth Options
|
|
||||||
- Place prominently (often higher conversion than email)
|
|
||||||
- Show most relevant options for your audience
|
|
||||||
- B2C: Google, Apple, Facebook
|
|
||||||
- B2B: Google, Microsoft, SSO
|
|
||||||
- Clear visual separation from email signup
|
|
||||||
- Consider "Sign up with Google" as primary
|
|
||||||
|
|
||||||
### Phone Number
|
|
||||||
- Defer unless essential (SMS verification, calling leads)
|
|
||||||
- If required, explain why
|
|
||||||
- Use proper input type with country code handling
|
|
||||||
- Format as they type
|
|
||||||
|
|
||||||
### Company/Organization
|
|
||||||
- Defer if possible
|
|
||||||
- Auto-suggest as they type
|
|
||||||
- Infer from email domain when possible
|
|
||||||
|
|
||||||
### Use Case / Role Questions
|
|
||||||
- Defer to onboarding if possible
|
|
||||||
- If needed at signup, keep to one question
|
|
||||||
- Use progressive disclosure (don't show all options at once)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Single-Step vs. Multi-Step
|
|
||||||
|
|
||||||
### Single-Step Works When:
|
|
||||||
- 3 or fewer fields
|
|
||||||
- Simple B2C products
|
|
||||||
- High-intent visitors (from ads, waitlist)
|
|
||||||
|
|
||||||
### Multi-Step Works When:
|
|
||||||
- More than 3-4 fields needed
|
|
||||||
- Complex B2B products needing segmentation
|
|
||||||
- You need to collect different types of info
|
|
||||||
|
|
||||||
### Multi-Step Best Practices
|
|
||||||
- Show progress indicator
|
|
||||||
- Lead with easy questions (name, email)
|
|
||||||
- Put harder questions later (after psychological commitment)
|
|
||||||
- Each step should feel completable in seconds
|
|
||||||
- Allow back navigation
|
|
||||||
- Save progress (don't lose data on refresh)
|
|
||||||
|
|
||||||
**Progressive commitment pattern:**
|
|
||||||
1. Email only (lowest barrier)
|
|
||||||
2. Password + name
|
|
||||||
3. Customization questions (optional)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Trust and Friction Reduction
|
|
||||||
|
|
||||||
### At the Form Level
|
|
||||||
- "No credit card required" (if true)
|
|
||||||
- "Free forever" or "14-day free trial"
|
|
||||||
- Privacy note: "We'll never share your email"
|
|
||||||
- Security badges if relevant
|
|
||||||
- Testimonial near signup form
|
|
||||||
|
|
||||||
### Error Handling
|
|
||||||
- Inline validation (not just on submit)
|
|
||||||
- Specific error messages ("Email already registered" + recovery path)
|
|
||||||
- Don't clear the form on error
|
|
||||||
- Focus on the problem field
|
|
||||||
|
|
||||||
### Microcopy
|
|
||||||
- Placeholder text: Use for examples, not labels
|
|
||||||
- Labels: Keep visible (not just placeholders) — placeholders disappear when typing, leaving users unsure what they're filling in
|
|
||||||
- Help text: Only when needed, placed close to field
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Mobile Signup Optimization
|
|
||||||
|
|
||||||
- Larger touch targets (44px+ height)
|
|
||||||
- Appropriate keyboard types (email, tel, etc.)
|
|
||||||
- Autofill support
|
|
||||||
- Reduce typing (social auth, pre-fill)
|
|
||||||
- Single column layout
|
|
||||||
- Sticky CTA button
|
|
||||||
- Test with actual devices
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Post-Submit Experience
|
|
||||||
|
|
||||||
### Success State
|
|
||||||
- Clear confirmation
|
|
||||||
- Immediate next step
|
|
||||||
- If email verification required:
|
|
||||||
- Explain what to do
|
|
||||||
- Easy resend option
|
|
||||||
- Check spam reminder
|
|
||||||
- Option to change email if wrong
|
|
||||||
|
|
||||||
### Verification Flows
|
|
||||||
- Consider delaying verification until necessary
|
|
||||||
- Magic link as alternative to password
|
|
||||||
- Let users explore while awaiting verification
|
|
||||||
- Clear re-engagement if verification stalls
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Measurement
|
|
||||||
|
|
||||||
### Key Metrics
|
|
||||||
- Form start rate (landed → started filling)
|
|
||||||
- Form completion rate (started → submitted)
|
|
||||||
- Field-level drop-off (which fields lose people)
|
|
||||||
- Time to complete
|
|
||||||
- Error rate by field
|
|
||||||
- Mobile vs. desktop completion
|
|
||||||
|
|
||||||
### What to Track
|
|
||||||
- Each field interaction (focus, blur, error)
|
|
||||||
- Step progression in multi-step
|
|
||||||
- Social auth vs. email signup ratio
|
|
||||||
- Time between steps
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Output Format
|
|
||||||
|
|
||||||
### Audit Findings
|
|
||||||
For each issue found:
|
|
||||||
- **Issue**: What's wrong
|
|
||||||
- **Impact**: Why it matters (with estimated impact if possible)
|
|
||||||
- **Fix**: Specific recommendation
|
|
||||||
- **Priority**: High/Medium/Low
|
|
||||||
|
|
||||||
### Recommended Changes
|
|
||||||
Organized by:
|
|
||||||
1. Quick wins (same-day fixes)
|
|
||||||
2. High-impact changes (week-level effort)
|
|
||||||
3. Test hypotheses (things to A/B test)
|
|
||||||
|
|
||||||
### Form Redesign (if requested)
|
|
||||||
- Recommended field set with rationale
|
|
||||||
- Field order
|
|
||||||
- Copy for labels, placeholders, buttons, errors
|
|
||||||
- Visual layout suggestions
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Common Signup Flow Patterns
|
|
||||||
|
|
||||||
### B2B SaaS Trial
|
|
||||||
1. Email + Password (or Google auth)
|
|
||||||
2. Name + Company (optional: role)
|
|
||||||
3. → Onboarding flow
|
|
||||||
|
|
||||||
### B2C App
|
|
||||||
1. Google/Apple auth OR Email
|
|
||||||
2. → Product experience
|
|
||||||
3. Profile completion later
|
|
||||||
|
|
||||||
### Waitlist/Early Access
|
|
||||||
1. Email only
|
|
||||||
2. Optional: Role/use case question
|
|
||||||
3. → Waitlist confirmation
|
|
||||||
|
|
||||||
### E-commerce Account
|
|
||||||
1. Guest checkout as default
|
|
||||||
2. Account creation optional post-purchase
|
|
||||||
3. OR Social auth with single click
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Experiment Ideas
|
|
||||||
|
|
||||||
### Form Design Experiments
|
|
||||||
|
|
||||||
**Layout & Structure**
|
|
||||||
- Single-step vs. multi-step signup flow
|
|
||||||
- Multi-step with progress bar vs. without
|
|
||||||
- 1-column vs. 2-column field layout
|
|
||||||
- Form embedded on page vs. separate signup page
|
|
||||||
- Horizontal vs. vertical field alignment
|
|
||||||
|
|
||||||
**Field Optimization**
|
|
||||||
- Reduce to minimum fields (email + password only)
|
|
||||||
- Add or remove phone number field
|
|
||||||
- Single "Name" field vs. "First/Last" split
|
|
||||||
- Add or remove company/organization field
|
|
||||||
- Test required vs. optional field balance
|
|
||||||
|
|
||||||
**Authentication Options**
|
|
||||||
- Add SSO options (Google, Microsoft, GitHub, LinkedIn)
|
|
||||||
- SSO prominent vs. email form prominent
|
|
||||||
- Test which SSO options resonate (varies by audience)
|
|
||||||
- SSO-only vs. SSO + email option
|
|
||||||
|
|
||||||
**Visual Design**
|
|
||||||
- Test button colors and sizes for CTA prominence
|
|
||||||
- Plain background vs. product-related visuals
|
|
||||||
- Test form container styling (card vs. minimal)
|
|
||||||
- Mobile-optimized layout testing
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Copy & Messaging Experiments
|
|
||||||
|
|
||||||
**Headlines & CTAs**
|
|
||||||
- Test headline variations above signup form
|
|
||||||
- CTA button text: "Create Account" vs. "Start Free Trial" vs. "Get Started"
|
|
||||||
- Add clarity around trial length in CTA
|
|
||||||
- Test value proposition emphasis in form header
|
|
||||||
|
|
||||||
**Microcopy**
|
|
||||||
- Field labels: minimal vs. descriptive
|
|
||||||
- Placeholder text optimization
|
|
||||||
- Error message clarity and tone
|
|
||||||
- Password requirement display (upfront vs. on error)
|
|
||||||
|
|
||||||
**Trust Elements**
|
|
||||||
- Add social proof next to signup form
|
|
||||||
- Test trust badges near form (security, compliance)
|
|
||||||
- Add "No credit card required" messaging
|
|
||||||
- Include privacy assurance copy
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Trial & Commitment Experiments
|
|
||||||
|
|
||||||
**Free Trial Variations**
|
|
||||||
- Credit card required vs. not required for trial
|
|
||||||
- Test trial length impact (7 vs. 14 vs. 30 days)
|
|
||||||
- Freemium vs. free trial model
|
|
||||||
- Trial with limited features vs. full access
|
|
||||||
|
|
||||||
**Friction Points**
|
|
||||||
- Email verification required vs. delayed vs. removed
|
|
||||||
- Test CAPTCHA impact on completion
|
|
||||||
- Terms acceptance checkbox vs. implicit acceptance
|
|
||||||
- Phone verification for high-value accounts
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
### Post-Submit Experiments
|
|
||||||
|
|
||||||
- Clear next steps messaging after signup
|
|
||||||
- Instant product access vs. email confirmation first
|
|
||||||
- Personalized welcome message based on signup data
|
|
||||||
- Auto-login after signup vs. require login
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Task-Specific Questions
|
|
||||||
|
|
||||||
1. What's your current signup completion rate?
|
|
||||||
2. Do you have field-level analytics on drop-off?
|
|
||||||
3. What data is absolutely required before they can use the product?
|
|
||||||
4. Are there compliance or verification requirements?
|
|
||||||
5. What happens immediately after signup?
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Related Skills
|
|
||||||
|
|
||||||
- **onboarding-cro**: For optimizing what happens after signup
|
|
||||||
- **form-cro**: For non-signup forms (lead capture, contact)
|
|
||||||
- **page-cro**: For the landing page leading to signup
|
|
||||||
- **ab-test-setup**: For testing signup flow changes
|
|
||||||
|
|
@ -1,88 +0,0 @@
|
||||||
{
|
|
||||||
"skill_name": "signup-flow-cro",
|
|
||||||
"evals": [
|
|
||||||
{
|
|
||||||
"id": 1,
|
|
||||||
"prompt": "Audit our signup flow. We have a 3-step process: Step 1 asks for email, password, and full name. Step 2 asks for company name, company size, role, and industry. Step 3 asks for use case and how they heard about us. Current completion rate is 45%.",
|
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should identify the flow type (likely B2B SaaS trial). Should apply the core principles: minimize required fields (which of these are genuinely needed before they can use the product?). Should evaluate each step: Step 1 is reasonable, Step 2 fields are mostly deferrable to progressive profiling, Step 3 is entirely deferrable. Should recommend cutting to Step 1 only or at most 2 steps. Should provide audit findings in structured format (Issue, Impact, Fix, Priority). Should include Quick Wins, High-Impact Changes, and Test Hypotheses.",
|
|
||||||
"assertions": [
|
|
||||||
"Checks for product-marketing-context.md",
|
|
||||||
"Identifies flow type",
|
|
||||||
"Applies minimize required fields principle",
|
|
||||||
"Evaluates each field for necessity",
|
|
||||||
"Recommends deferring most Step 2 and all Step 3 fields",
|
|
||||||
"Provides findings in structured format",
|
|
||||||
"Includes Quick Wins, High-Impact Changes, Test Hypotheses"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 2,
|
|
||||||
"prompt": "Should we add Google and Microsoft SSO to our signup page? We're a B2B project management tool and currently only have email/password signup.",
|
|
||||||
"expected_output": "Should apply the social auth options guidance. For B2B, should recommend Google and Microsoft as the primary SSO options (matching the B2B recommendation). Should explain benefits: higher conversion (less friction), pre-verified email, faster onboarding. Should recommend placing SSO prominently (often higher conversion than email). Should address implementation considerations: clear visual separation from email signup, button copy ('Sign up with Google' not just Google icon), consider which option to emphasize based on audience.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies social auth options guidance",
|
|
||||||
"Recommends Google and Microsoft for B2B",
|
|
||||||
"Explains conversion benefits of SSO",
|
|
||||||
"Recommends prominent placement",
|
|
||||||
"Addresses visual separation from email signup",
|
|
||||||
"Provides implementation recommendations"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 3,
|
|
||||||
"prompt": "our signup form is just email and password but we still only get 35% of visitors to complete it. what else could be wrong?",
|
|
||||||
"expected_output": "Should trigger on casual phrasing. Should investigate beyond just form fields since the form is already minimal. Should apply trust and friction reduction guidance: is there a 'No credit card required' message? Privacy assurance? Testimonial near the form? Should check form-level issues: error handling, password requirements clarity, submit button copy. Should also look at pre-form factors: is the value proposition clear? Is the page optimized? (cross-reference page-cro). Should provide diagnostic checklist and recommendations.",
|
|
||||||
"assertions": [
|
|
||||||
"Triggers on casual phrasing",
|
|
||||||
"Investigates beyond form fields",
|
|
||||||
"Applies trust and friction reduction",
|
|
||||||
"Checks for 'No credit card required' messaging",
|
|
||||||
"Checks error handling and password UX",
|
|
||||||
"Considers pre-form factors (value prop, page CRO)",
|
|
||||||
"Provides diagnostic checklist"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 4,
|
|
||||||
"prompt": "We require email verification before users can access the product. Is that hurting our conversion? Should we change it?",
|
|
||||||
"expected_output": "Should apply the verification flows guidance. Should explain that requiring verification before product access does create friction and likely reduces activation. Should recommend alternatives: delay verification until needed (let users explore first), magic link as alternative to password, let users start while verification is pending. Should discuss when email verification IS required (compliance, preventing abuse). Should provide specific recommendations for improving the verification experience if kept.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies verification flows guidance",
|
|
||||||
"Explains verification friction impact",
|
|
||||||
"Recommends delaying verification",
|
|
||||||
"Suggests letting users explore while pending",
|
|
||||||
"Discusses when verification is required",
|
|
||||||
"Provides improvements if verification is kept"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 5,
|
|
||||||
"prompt": "What experiments should we run on our signup page? We want to improve our trial signup rate.",
|
|
||||||
"expected_output": "Should apply the experiment ideas section. Should provide experiments across categories: form design experiments (layout, field count, SSO), copy and messaging experiments (headline, CTA text, trust elements), trial and commitment experiments (credit card required vs not, trial length), and post-submit experiments. Should prioritize experiments by likely impact. Should cross-reference ab-test-setup for proper experiment design.",
|
|
||||||
"assertions": [
|
|
||||||
"Applies experiment ideas section",
|
|
||||||
"Covers form design experiments",
|
|
||||||
"Covers copy and messaging experiments",
|
|
||||||
"Covers trial and commitment experiments",
|
|
||||||
"Prioritizes by likely impact",
|
|
||||||
"Cross-references ab-test-setup skill"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
},
|
|
||||||
{
|
|
||||||
"id": 6,
|
|
||||||
"prompt": "Users sign up fine but then never activate. Only 20% complete onboarding. What do we do?",
|
|
||||||
"expected_output": "Should recognize this is a post-signup onboarding problem, not a signup flow problem. Should defer to or cross-reference the onboarding-cro skill, which handles post-signup activation and onboarding optimization. Signup-flow-cro covers getting users through the signup form, not what happens after.",
|
|
||||||
"assertions": [
|
|
||||||
"Recognizes this as post-signup onboarding, not signup flow",
|
|
||||||
"References or defers to onboarding-cro skill",
|
|
||||||
"Explains signup-flow-cro covers the signup form, not post-signup"
|
|
||||||
],
|
|
||||||
"files": []
|
|
||||||
}
|
|
||||||
]
|
|
||||||
}
|
|
||||||
|
|
@ -1,56 +1,57 @@
|
||||||
---
|
---
|
||||||
name: site-architecture
|
name: site-architecture
|
||||||
description: When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure," "page hierarchy," "information architecture," "IA," "navigation design," "URL structure," "breadcrumbs," "internal linking strategy," "website planning," "what pages do I need," "how should I organize my site," or "site navigation." Use this whenever someone is planning what pages a website should have and how they connect. NOT for XML sitemaps (that's technical SEO — see seo-audit). For SEO audits, see seo-audit. For structured data, see schema-markup.
|
description: When the user wants to plan, map, or restructure their HVAC website's page hierarchy, navigation, URL structure, or internal linking. Also use when the user mentions "sitemap," "site map," "visual sitemap," "site structure," "page hierarchy," "information architecture," "IA," "navigation design," "URL structure," "breadcrumbs," "internal linking strategy," "website planning," "what pages do I need," "how should I organize my HVAC site," or "site navigation." Use this whenever someone is planning what pages an HVAC website should have and how they connect. NOT for XML sitemaps (that's technical SEO — see seo-audit). For SEO audits, see seo-audit. For structured data, see schema-markup.
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [scrape, browse, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Site Architecture
|
# Site Architecture
|
||||||
|
|
||||||
You are an information architecture expert. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for users and optimized for search engines.
|
You are an information architecture expert for HVAC contractor and brand websites. Your goal is to help plan website structure — page hierarchy, navigation, URL patterns, and internal linking — so the site is intuitive for buyers and optimized for search engines.
|
||||||
|
|
||||||
## Before Planning
|
## Before Planning
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
### 1. Business Context
|
### 1. Business Context
|
||||||
- What does the company do?
|
- What HVAC services offered? (Repair, installation, maintenance, emergency?)
|
||||||
- Who are the primary audiences?
|
- Single location or multi-location network?
|
||||||
- What are the top 3 goals for the site? (conversions, SEO traffic, education, support)
|
- Who are the primary audiences? (Homeowners, commercial, both?)
|
||||||
|
- What are the top 3 goals for the site? (Lead generation, service booking, education, sales)
|
||||||
|
|
||||||
### 2. Current State
|
### 2. Current State
|
||||||
- New site or restructuring an existing one?
|
- New site or restructuring an existing one?
|
||||||
- If restructuring: what's broken? (high bounce, poor SEO, users can't find things)
|
- If restructuring: what's broken? (High bounce, poor SEO, users can't find services)
|
||||||
- Existing URLs that must be preserved (for redirects)?
|
- Existing URLs that must be preserved (for redirects)?
|
||||||
|
|
||||||
### 3. Site Type
|
### 3. Site Type
|
||||||
- SaaS marketing site
|
- Local contractor (single or multi-location)
|
||||||
- Content/blog site
|
- Equipment brand/manufacturer
|
||||||
- E-commerce
|
- HVAC service company network
|
||||||
- Documentation
|
- HVAC marketplace or directory
|
||||||
- Hybrid (SaaS + content)
|
|
||||||
- Small business / local
|
|
||||||
|
|
||||||
### 4. Content Inventory
|
### 4. Content Inventory
|
||||||
- How many pages exist or are planned?
|
- How many service areas covered?
|
||||||
- What are the most important pages? (by traffic, conversions, or business value)
|
- How many service types offered?
|
||||||
- Any planned sections or expansions?
|
- Blog/resource content planned?
|
||||||
|
- Equipment/brand information?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Site Types and Starting Points
|
## HVAC-Specific Site Types and Patterns
|
||||||
|
|
||||||
| Site Type | Typical Depth | Key Sections | URL Pattern |
|
| Site Type | Typical Depth | Key Sections | URL Pattern |
|
||||||
|-----------|--------------|--------------|-------------|
|
|-----------|--------------|--------------|-------------|
|
||||||
| SaaS marketing | 2-3 levels | Home, Features, Pricing, Blog, Docs | `/features/name`, `/blog/slug` |
|
| Local contractor (single) | 2-3 levels | Home, Services, About, Blog, Contact | `/services/[service]`, `/blog/slug` |
|
||||||
| Content/blog | 2-3 levels | Home, Blog, Categories, About | `/blog/slug`, `/category/slug` |
|
| Contractor network (multi-location) | 3-4 levels | Home, Locations, Services, About, Blog | `/[city]/`, `/[city]/[service]/` |
|
||||||
| E-commerce | 3-4 levels | Home, Categories, Products, Cart | `/category/subcategory/product` |
|
| Equipment brand/manufacturer | 3-4 levels | Home, Equipment, Contractors, Resources | `/products/[brand]/[model]`, `/resources/` |
|
||||||
| Documentation | 3-4 levels | Home, Guides, API Reference | `/docs/section/page` |
|
| HVAC service company | 2-3 levels | Home, Services, Areas Served, Blog | `/services/[service]`, `/areas/[city]` |
|
||||||
| Hybrid SaaS+content | 3-4 levels | Home, Product, Blog, Resources, Docs | `/product/feature`, `/blog/slug` |
|
|
||||||
| Small business | 1-2 levels | Home, Services, About, Contact | `/services/name` |
|
|
||||||
|
|
||||||
**For full page hierarchy templates**: See [references/site-type-templates.md](references/site-type-templates.md)
|
**For full page hierarchy templates**: See [references/site-type-templates.md](references/site-type-templates.md)
|
||||||
|
|
||||||
|
|
@ -66,20 +67,20 @@ Users should reach any important page within 3 clicks from the homepage. This is
|
||||||
|
|
||||||
| Approach | Best For | Tradeoff |
|
| Approach | Best For | Tradeoff |
|
||||||
|----------|----------|----------|
|
|----------|----------|----------|
|
||||||
| Flat (2 levels) | Small sites, portfolios | Simple but doesn't scale |
|
| Flat (2 levels) | Small local contractors | Simple but doesn't scale |
|
||||||
| Moderate (3 levels) | Most SaaS, content sites | Good balance of depth and findability |
|
| Moderate (3 levels) | Most HVAC contractors | Good balance of depth and findability |
|
||||||
| Deep (4+ levels) | E-commerce, large docs | Scales but risks burying content |
|
| Deep (4+ levels) | Multi-location networks, equipment brands | Scales but risks burying content |
|
||||||
|
|
||||||
**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 20+ items, add a level of hierarchy.
|
**Rule of thumb**: Go as flat as possible while keeping navigation clean. If a nav dropdown has 15+ items, add a level of hierarchy.
|
||||||
|
|
||||||
### Hierarchy Levels
|
### Hierarchy Levels
|
||||||
|
|
||||||
| Level | What It Is | Example |
|
| Level | What It Is | Example |
|
||||||
|-------|-----------|---------|
|
|-------|-----------|---------|
|
||||||
| L0 | Homepage | `/` |
|
| L0 | Homepage | `/` |
|
||||||
| L1 | Primary sections | `/features`, `/blog`, `/pricing` |
|
| L1 | Primary sections | `/services`, `/locations`, `/about` |
|
||||||
| L2 | Section pages | `/features/analytics`, `/blog/seo-guide` |
|
| L2 | Section pages | `/services/ac-repair`, `/locations/denver` |
|
||||||
| L3+ | Detail pages | `/docs/api/authentication` |
|
| L3+ | Detail pages | `/services/ac-repair/how-it-works` |
|
||||||
|
|
||||||
### ASCII Tree Format
|
### ASCII Tree Format
|
||||||
|
|
||||||
|
|
@ -87,28 +88,95 @@ Use this format for page hierarchies:
|
||||||
|
|
||||||
```
|
```
|
||||||
Homepage (/)
|
Homepage (/)
|
||||||
├── Features (/features)
|
├── Services (/services)
|
||||||
│ ├── Analytics (/features/analytics)
|
│ ├── AC Repair (/services/ac-repair)
|
||||||
│ ├── Automation (/features/automation)
|
│ ├── AC Installation (/services/ac-installation)
|
||||||
│ └── Integrations (/features/integrations)
|
│ ├── Furnace Repair (/services/furnace-repair)
|
||||||
├── Pricing (/pricing)
|
│ ├── Furnace Installation (/services/furnace-installation)
|
||||||
├── Blog (/blog)
|
│ ├── Maintenance Plans (/services/maintenance-plans)
|
||||||
│ ├── [Category: SEO] (/blog/category/seo)
|
│ └── Emergency Service (/services/emergency)
|
||||||
│ └── [Category: CRO] (/blog/category/cro)
|
├── Service Areas (/areas) [if multi-location]
|
||||||
├── Resources (/resources)
|
│ ├── Denver (/areas/denver)
|
||||||
│ ├── Case Studies (/resources/case-studies)
|
│ ├── Boulder (/areas/boulder)
|
||||||
│ └── Templates (/resources/templates)
|
│ └── Fort Collins (/areas/fort-collins)
|
||||||
├── Docs (/docs)
|
├── Equipment (/equipment)
|
||||||
│ ├── Getting Started (/docs/getting-started)
|
│ ├── Carrier (/equipment/carrier)
|
||||||
│ └── API Reference (/docs/api)
|
│ └── Trane (/equipment/trane)
|
||||||
├── About (/about)
|
├── About (/about)
|
||||||
│ └── Careers (/about/careers)
|
├── Blog (/blog)
|
||||||
|
│ └── [Category: HVAC Maintenance] (/blog/category/maintenance)
|
||||||
|
├── Resources (/resources)
|
||||||
|
│ ├── Guides (/resources/guides)
|
||||||
|
│ └── Glossary (/resources/glossary)
|
||||||
└── Contact (/contact)
|
└── Contact (/contact)
|
||||||
```
|
```
|
||||||
|
|
||||||
**When to use ASCII vs Mermaid**:
|
**When to use ASCII vs Mermaid**:
|
||||||
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
|
- ASCII: quick hierarchy drafts, text-only contexts, simple structures
|
||||||
- Mermaid: visual presentations, complex relationships, showing nav zones or linking patterns
|
- Mermaid: visual presentations, complex relationships, nav zones
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## HVAC-Specific Patterns
|
||||||
|
|
||||||
|
### Single-Location Contractor Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
Homepage
|
||||||
|
├── Services (Hub page)
|
||||||
|
│ ├── AC Repair
|
||||||
|
│ ├── AC Installation
|
||||||
|
│ ├── Furnace Repair
|
||||||
|
│ ├── Furnace Installation
|
||||||
|
│ ├── Maintenance Plans
|
||||||
|
│ └── Emergency Service
|
||||||
|
├── Why Choose Us
|
||||||
|
├── About
|
||||||
|
├── Blog
|
||||||
|
└── Contact
|
||||||
|
```
|
||||||
|
|
||||||
|
### Multi-Location Network Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
Homepage
|
||||||
|
├── Find a Location
|
||||||
|
│ ├── [City] Hub Page
|
||||||
|
│ │ ├── AC Repair in [City]
|
||||||
|
│ │ ├── Furnace Repair in [City]
|
||||||
|
│ │ └── Other Services in [City]
|
||||||
|
│ ├── [City] Hub Page
|
||||||
|
│ └── ... (repeat per city)
|
||||||
|
├── Services (Master pages explaining each service)
|
||||||
|
│ ├── AC Repair (national resource)
|
||||||
|
│ ├── Furnace Repair
|
||||||
|
│ └── ...
|
||||||
|
├── About
|
||||||
|
├── Blog
|
||||||
|
└── Contact
|
||||||
|
```
|
||||||
|
|
||||||
|
### Equipment Brand Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
Homepage
|
||||||
|
├── Products
|
||||||
|
│ ├── Air Conditioners
|
||||||
|
│ │ ├── Model 25HCE436A013
|
||||||
|
│ │ ├── Model 25HCE460A013
|
||||||
|
│ │ └── ...
|
||||||
|
│ ├── Furnaces
|
||||||
|
│ ├── Heat Pumps
|
||||||
|
│ └── Thermostats
|
||||||
|
├── Find a Contractor
|
||||||
|
├── Resources
|
||||||
|
│ ├── Buying Guide
|
||||||
|
│ ├── SEER Explained
|
||||||
|
│ ├── Energy Savings Calculator
|
||||||
|
│ └── ...
|
||||||
|
├── About
|
||||||
|
└── Contact
|
||||||
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -121,31 +189,31 @@ Homepage (/)
|
||||||
| Header nav | Primary navigation, always visible | Top of every page |
|
| Header nav | Primary navigation, always visible | Top of every page |
|
||||||
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
|
| Dropdown menus | Organize sub-pages under parent | Expands from header items |
|
||||||
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
|
| Footer nav | Secondary links, legal, sitemap | Bottom of every page |
|
||||||
| Sidebar nav | Section navigation (docs, blog) | Left side within a section |
|
| Sidebar nav | Section navigation (docs, resources) | Left side within a section |
|
||||||
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
|
| Breadcrumbs | Show current location in hierarchy | Below header, above content |
|
||||||
| Contextual links | Related content, next steps | Within page content |
|
| Contextual links | Related content, next steps | Within page content |
|
||||||
|
|
||||||
### Header Navigation Rules
|
### Header Navigation Rules
|
||||||
|
|
||||||
- **4-7 items max** in the primary nav (more causes decision paralysis)
|
- **4-7 items max** in the primary nav (more causes decision paralysis)
|
||||||
- **CTA button** goes rightmost (e.g., "Start Free Trial," "Get Started")
|
- **CTA button** goes rightmost (e.g., "Schedule Service," "Get Quote," "Call Now")
|
||||||
- **Logo** links to homepage (left side)
|
- **Logo** links to homepage (left side)
|
||||||
- **Order by priority**: most important/visited pages first
|
- **Order by priority**: most important/visited pages first
|
||||||
- If you have a mega menu, limit to 3-4 columns
|
- For HVAC contractors: Services, Areas Served (if multi-location), About, Blog, Contact
|
||||||
|
|
||||||
### Footer Organization
|
### Footer Organization
|
||||||
|
|
||||||
Group footer links into columns:
|
Group footer links into columns:
|
||||||
- **Product**: Features, Pricing, Integrations, Changelog
|
- **Services**: AC Repair, Furnace Repair, Installation, Maintenance Plans, Emergency
|
||||||
- **Resources**: Blog, Case Studies, Templates, Docs
|
- **Company**: About, Careers, Blog, Press
|
||||||
- **Company**: About, Careers, Contact, Press
|
- **Support**: Contact, FAQ, Warranties, Financing
|
||||||
- **Legal**: Privacy, Terms, Security
|
- **Legal**: Privacy, Terms, Security
|
||||||
|
|
||||||
### Breadcrumb Format
|
### Breadcrumb Format
|
||||||
|
|
||||||
```
|
```
|
||||||
Home > Features > Analytics
|
Home > Services > AC Repair
|
||||||
Home > Blog > SEO Category > Post Title
|
Home > Areas Served > Denver > Services
|
||||||
```
|
```
|
||||||
|
|
||||||
Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
|
Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be a clickable link except the current page.
|
||||||
|
|
@ -158,38 +226,38 @@ Breadcrumbs should mirror the URL hierarchy. Every breadcrumb segment should be
|
||||||
|
|
||||||
### Design Principles
|
### Design Principles
|
||||||
|
|
||||||
1. **Readable by humans** — `/features/analytics` not `/f/a123`
|
1. **Readable by humans** — `/services/ac-repair` not `/svc/a123`
|
||||||
2. **Hyphens, not underscores** — `/blog/seo-guide` not `/blog/seo_guide`
|
2. **Hyphens, not underscores** — `/emergency-service` not `/emergency_service`
|
||||||
3. **Reflect the hierarchy** — URL path should match site structure
|
3. **Reflect the hierarchy** — URL path should match site structure
|
||||||
4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
|
4. **Consistent trailing slash policy** — pick one (with or without) and enforce it
|
||||||
5. **Lowercase always** — `/About` should redirect to `/about`
|
5. **Lowercase always** — `/Services` should redirect to `/services`
|
||||||
6. **Short but descriptive** — `/blog/how-to-improve-landing-page-conversion-rates` is too long; `/blog/landing-page-conversions` is better
|
6. **Short but descriptive** — `/ac-repair-in-denver` is too long; `/denver/ac-repair` is better
|
||||||
|
|
||||||
### URL Patterns by Page Type
|
### HVAC-Specific URL Patterns
|
||||||
|
|
||||||
| Page Type | Pattern | Example |
|
| Page Type | Pattern | Example |
|
||||||
|-----------|---------|---------|
|
|-----------|---------|---------|
|
||||||
| Homepage | `/` | `example.com` |
|
| Homepage | `/` | `example.com` |
|
||||||
| Feature page | `/features/{name}` | `/features/analytics` |
|
| Service page | `/services/{name}` | `/services/ac-repair` |
|
||||||
| Pricing | `/pricing` | `/pricing` |
|
| Location page (single) | `/areas/{city}` or `/locations/{city}` | `/areas/denver` |
|
||||||
| Blog post | `/blog/{slug}` | `/blog/seo-guide` |
|
| Service in location | `/areas/{city}/{service}` or `/services/{service}/{city}` | `/areas/denver/ac-repair` |
|
||||||
| Blog category | `/blog/category/{slug}` | `/blog/category/seo` |
|
| Equipment | `/equipment/{brand}/{model}` | `/equipment/carrier/25hce436a013` |
|
||||||
| Case study | `/customers/{slug}` | `/customers/acme-corp` |
|
| Equipment category | `/equipment/{brand}` | `/equipment/carrier` |
|
||||||
| Documentation | `/docs/{section}/{page}` | `/docs/api/authentication` |
|
| Blog post | `/blog/{slug}` | `/blog/hvac-maintenance-tips` |
|
||||||
| Legal | `/{page}` | `/privacy`, `/terms` |
|
| Blog category | `/blog/category/{slug}` | `/blog/category/ac-repair` |
|
||||||
| Landing page | `/{slug}` or `/lp/{slug}` | `/free-trial`, `/lp/webinar` |
|
| Resource | `/resources/{slug}` | `/resources/hvac-glossary` |
|
||||||
| Comparison | `/compare/{competitor}` or `/vs/{competitor}` | `/compare/competitor-name` |
|
| About | `/about` | `/about` |
|
||||||
| Integration | `/integrations/{name}` | `/integrations/slack` |
|
| Contact | `/contact` | `/contact` |
|
||||||
| Template | `/templates/{slug}` | `/templates/marketing-plan` |
|
| FAQ | `/faq` | `/faq` |
|
||||||
|
|
||||||
### Common Mistakes
|
### Common Mistakes
|
||||||
|
|
||||||
- **Dates in blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
|
- **Service + Location order**: Decide once. `/denver/ac-repair/` or `/services/ac-repair/denver/`? Stick with it.
|
||||||
- **Over-nesting** — `/products/category/subcategory/item/detail` is too deep. Flatten where possible.
|
- **Over-nesting** — `/products/residential/ac-systems/cooling/units/model-x` is too deep. Flatten to `/equipment/carrier/model-x`.
|
||||||
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages for anyone with the old URL bookmarked or linked.
|
- **Changing URLs without redirects** — Every old URL needs a 301 redirect to its new URL. Without them, you lose backlink equity and create broken pages.
|
||||||
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs.
|
- **IDs in URLs** — `/product/12345` is not human-readable. Use slugs like `/product/carrier-25hce436a013`.
|
||||||
- **Query parameters for content** — `/blog?id=123` should be `/blog/post-title`.
|
- **Query parameters for content** — `/services?id=123` should be `/services/ac-repair`.
|
||||||
- **Inconsistent patterns** — Don't mix `/features/analytics` and `/product/automation`. Pick one parent.
|
- **Date-based blog URLs** — `/blog/2024/01/15/post-title` adds no value and makes URLs long. Use `/blog/post-title`.
|
||||||
|
|
||||||
### Breadcrumb-URL Alignment
|
### Breadcrumb-URL Alignment
|
||||||
|
|
||||||
|
|
@ -197,59 +265,52 @@ The breadcrumb trail should mirror the URL path:
|
||||||
|
|
||||||
| URL | Breadcrumb |
|
| URL | Breadcrumb |
|
||||||
|-----|-----------|
|
|-----|-----------|
|
||||||
| `/features/analytics` | Home > Features > Analytics |
|
| `/services/ac-repair` | Home > Services > AC Repair |
|
||||||
| `/blog/seo-guide` | Home > Blog > SEO Guide |
|
| `/areas/denver/ac-repair` | Home > Service Areas > Denver > AC Repair |
|
||||||
| `/docs/api/auth` | Home > Docs > API > Authentication |
|
| `/equipment/carrier/25hce436a013` | Home > Equipment > Carrier > Model 25HCE436A013 |
|
||||||
|
| `/blog/ac-maintenance-tips` | Home > Blog > AC Maintenance Tips |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Visual Sitemap Output (Mermaid)
|
## Visual Sitemap Output (Mermaid)
|
||||||
|
|
||||||
Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear and can annotate navigation zones.
|
Use Mermaid `graph TD` for visual sitemaps. This makes hierarchy relationships clear.
|
||||||
|
|
||||||
### Basic Hierarchy
|
### Single-Location Contractor
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
graph TD
|
graph TD
|
||||||
HOME[Homepage] --> FEAT[Features]
|
HOME[Homepage] --> SERV[Services Hub]
|
||||||
HOME --> PRICE[Pricing]
|
|
||||||
HOME --> BLOG[Blog]
|
|
||||||
HOME --> ABOUT[About]
|
HOME --> ABOUT[About]
|
||||||
|
HOME --> BLOG[Blog]
|
||||||
|
HOME --> CONTACT[Contact]
|
||||||
|
|
||||||
FEAT --> F1[Analytics]
|
SERV --> S1[AC Repair]
|
||||||
FEAT --> F2[Automation]
|
SERV --> S2[Furnace Repair]
|
||||||
FEAT --> F3[Integrations]
|
SERV --> S3[Maintenance Plans]
|
||||||
|
SERV --> S4[Emergency Service]
|
||||||
|
|
||||||
BLOG --> B1[Post 1]
|
BLOG --> B1[Post 1: HVAC Tips]
|
||||||
BLOG --> B2[Post 2]
|
BLOG --> B2[Post 2: Filter Changes]
|
||||||
```
|
```
|
||||||
|
|
||||||
### With Navigation Zones
|
### Multi-Location Network
|
||||||
|
|
||||||
```mermaid
|
```mermaid
|
||||||
graph TD
|
graph TD
|
||||||
subgraph Header Nav
|
HOME[Homepage] --> AREAS[Service Areas]
|
||||||
HOME[Homepage]
|
HOME --> SERV[Services]
|
||||||
FEAT[Features]
|
HOME --> ABOUT[About]
|
||||||
PRICE[Pricing]
|
HOME --> BLOG[Blog]
|
||||||
BLOG[Blog]
|
|
||||||
CTA[Get Started]
|
|
||||||
end
|
|
||||||
|
|
||||||
subgraph Footer Nav
|
AREAS --> D1["Denver Hub"]
|
||||||
ABOUT[About]
|
AREAS --> D2["Boulder Hub"]
|
||||||
CAREERS[Careers]
|
|
||||||
CONTACT[Contact]
|
|
||||||
PRIVACY[Privacy]
|
|
||||||
end
|
|
||||||
|
|
||||||
HOME --> FEAT
|
D1 --> D1S1["AC Repair in Denver"]
|
||||||
HOME --> PRICE
|
D1 --> D1S2["Furnace Repair in Denver"]
|
||||||
HOME --> BLOG
|
|
||||||
HOME --> ABOUT
|
|
||||||
|
|
||||||
FEAT --> F1[Analytics]
|
SERV --> AC[AC Repair National]
|
||||||
FEAT --> F2[Automation]
|
SERV --> FUR[Furnace Repair National]
|
||||||
```
|
```
|
||||||
|
|
||||||
**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)
|
**For more Mermaid templates**: See [references/mermaid-templates.md](references/mermaid-templates.md)
|
||||||
|
|
@ -263,42 +324,52 @@ graph TD
|
||||||
| Type | Purpose | Example |
|
| Type | Purpose | Example |
|
||||||
|------|---------|---------|
|
|------|---------|---------|
|
||||||
| Navigational | Move between sections | Header, footer, sidebar links |
|
| Navigational | Move between sections | Header, footer, sidebar links |
|
||||||
| Contextual | Related content within text | "Learn more about [analytics](/features/analytics)" |
|
| Contextual | Related content within text | "Learn more about [maintenance plans](/services/maintenance-plans)" |
|
||||||
| Hub-and-spoke | Connect cluster content to hub | Blog posts linking to pillar page |
|
| Hub-and-spoke | Connect cluster content to hub | Service pages linking to location versions |
|
||||||
| Cross-section | Connect related pages across sections | Feature page linking to related case study |
|
| Service-location cross | Connect related pages across sections | Denver location page linking to each service in Denver |
|
||||||
|
|
||||||
### Internal Linking Rules
|
### Internal Linking Rules
|
||||||
|
|
||||||
1. **No orphan pages** — every page must have at least one internal link pointing to it
|
1. **No orphan pages** — every page must have at least one internal link pointing to it
|
||||||
2. **Descriptive anchor text** — "our analytics features" not "click here"
|
2. **Descriptive anchor text** — "AC repair services" not "click here" or "read more"
|
||||||
3. **5-10 internal links per 1000 words** of content (approximate guideline)
|
3. **5-10 internal links per 1000 words** of content (approximate guideline)
|
||||||
4. **Link to important pages more often** — homepage, key feature pages, pricing
|
4. **Link to important pages more often** — homepage, main service pages, location hubs
|
||||||
5. **Use breadcrumbs** — free internal links on every page
|
5. **Use breadcrumbs** — free internal links on every page
|
||||||
6. **Related content sections** — "Related Posts" or "You might also like" at page bottom
|
6. **Service discovery sections** — "Other services in [Location]" or "Learn about our services"
|
||||||
|
|
||||||
### Hub-and-Spoke Model
|
### Hub-and-Spoke Model
|
||||||
|
|
||||||
For content-heavy sites, organize around hub pages:
|
For HVAC contractors with multiple services and locations:
|
||||||
|
|
||||||
```
|
```
|
||||||
Hub: /blog/seo-guide (comprehensive overview)
|
Hub: /services/ac-repair (master AC repair page)
|
||||||
├── Spoke: /blog/keyword-research (links back to hub)
|
├── Spoke: /areas/denver/ac-repair (Denver version)
|
||||||
├── Spoke: /blog/on-page-seo (links back to hub)
|
├── Spoke: /areas/boulder/ac-repair (Boulder version)
|
||||||
├── Spoke: /blog/technical-seo (links back to hub)
|
└── Spoke: /areas/fort-collins/ac-repair (Fort Collins version)
|
||||||
└── Spoke: /blog/link-building (links back to hub)
|
|
||||||
|
Each spoke links back to the hub.
|
||||||
|
The hub links to all spokes.
|
||||||
|
Spokes link to each other (related service areas).
|
||||||
```
|
```
|
||||||
|
|
||||||
Each spoke links back to the hub. The hub links to all spokes. Spokes link to each other where relevant.
|
### Service-Location Grid
|
||||||
|
|
||||||
|
For network sites with 5 services x 10 locations (50 pages):
|
||||||
|
- Each location hub links to all 5 services
|
||||||
|
- Each service hub links to all 10 locations
|
||||||
|
- Creates dense cross-linking structure
|
||||||
|
- Every page reachable within 2-3 clicks
|
||||||
|
|
||||||
### Link Audit Checklist
|
### Link Audit Checklist
|
||||||
|
|
||||||
- [ ] Every page has at least one inbound internal link
|
- [ ] Every page has at least one inbound internal link
|
||||||
- [ ] No broken internal links (404s)
|
- [ ] No broken internal links (404s)
|
||||||
- [ ] Anchor text is descriptive (not "click here" or "read more")
|
- [ ] Anchor text is descriptive (not "click here" or "read more")
|
||||||
- [ ] Important pages have the most inbound internal links
|
- [ ] Important pages have multiple inbound links
|
||||||
- [ ] Breadcrumbs are implemented on all pages
|
- [ ] Breadcrumbs implemented on all pages
|
||||||
- [ ] Related content links exist on blog posts
|
- [ ] Service pages link to location versions
|
||||||
- [ ] Cross-section links connect features to case studies, blog to product pages
|
- [ ] Location pages link to service pages
|
||||||
|
- [ ] Cross-location links exist (Boulder AC repair links to Denver AC repair)
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -310,17 +381,17 @@ When creating a site architecture plan, provide these deliverables:
|
||||||
Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
|
Full site structure with URLs at each node. Use the ASCII tree format from the Page Hierarchy Design section.
|
||||||
|
|
||||||
### 2. Visual Sitemap (Mermaid)
|
### 2. Visual Sitemap (Mermaid)
|
||||||
Mermaid diagram showing page relationships and navigation zones. Use `graph TD` with subgraphs for nav zones where helpful.
|
Mermaid diagram showing page relationships. Use `graph TD` with subgraphs for nav zones.
|
||||||
|
|
||||||
### 3. URL Map Table
|
### 3. URL Map Table
|
||||||
|
|
||||||
| Page | URL | Parent | Nav Location | Priority |
|
| Page | URL | Parent | Nav Location | Priority |
|
||||||
|------|-----|--------|-------------|----------|
|
|------|-----|--------|-------------|----------|
|
||||||
| Homepage | `/` | — | Header | High |
|
| Homepage | `/` | — | Header | High |
|
||||||
| Features | `/features` | Homepage | Header | High |
|
| Services | `/services` | Homepage | Header | High |
|
||||||
| Analytics | `/features/analytics` | Features | Header dropdown | Medium |
|
| AC Repair | `/services/ac-repair` | Services | Header dropdown | High |
|
||||||
| Pricing | `/pricing` | Homepage | Header | High |
|
| Denver | `/areas/denver` | Homepage | Header dropdown | High |
|
||||||
| Blog | `/blog` | Homepage | Header | Medium |
|
| AC Repair in Denver | `/areas/denver/ac-repair` | Denver | Content | Medium |
|
||||||
|
|
||||||
### 4. Navigation Spec
|
### 4. Navigation Spec
|
||||||
- Header nav items (ordered, with CTA)
|
- Header nav items (ordered, with CTA)
|
||||||
|
|
@ -330,7 +401,7 @@ Mermaid diagram showing page relationships and navigation zones. Use `graph TD`
|
||||||
|
|
||||||
### 5. Internal Linking Plan
|
### 5. Internal Linking Plan
|
||||||
- Hub pages and their spokes
|
- Hub pages and their spokes
|
||||||
- Cross-section link opportunities
|
- Cross-location/cross-service link opportunities
|
||||||
- Orphan page audit (if restructuring)
|
- Orphan page audit (if restructuring)
|
||||||
- Recommended links per key page
|
- Recommended links per key page
|
||||||
|
|
||||||
|
|
@ -339,19 +410,19 @@ Mermaid diagram showing page relationships and navigation zones. Use `graph TD`
|
||||||
## Task-Specific Questions
|
## Task-Specific Questions
|
||||||
|
|
||||||
1. Is this a new site or are you restructuring an existing one?
|
1. Is this a new site or are you restructuring an existing one?
|
||||||
2. What type of site is it? (SaaS, content, e-commerce, docs, hybrid, small business)
|
2. Single HVAC location or multiple locations/service areas?
|
||||||
3. How many pages exist or are planned?
|
3. What HVAC services do you offer? (Count: 3? 10? 20+?)
|
||||||
4. What are the 5 most important pages on the site?
|
4. How many service areas/cities are you targeting?
|
||||||
5. Are there existing URLs that need to be preserved or redirected?
|
5. What are the 5 most important pages on the site?
|
||||||
6. Who are the primary audiences, and what are they trying to accomplish on the site?
|
6. Are there existing URLs that need to be preserved or redirected?
|
||||||
|
7. Who are the primary audiences, and what are they trying to accomplish?
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **content-strategy**: For planning what content to create and topic clusters
|
- **content-strategy**: For planning what content to create and topic clusters
|
||||||
- **programmatic-seo**: For building SEO pages at scale with templates and data
|
- **programmatic-seo**: For building SEO location + service pages at scale
|
||||||
- **seo-audit**: For technical SEO, on-page optimization, and indexation issues
|
- **seo-audit**: For technical SEO, on-page optimization, and indexation issues
|
||||||
- **page-cro**: For optimizing individual pages for conversion
|
- **schema-markup**: For implementing breadcrumb and LocalBusiness structured data
|
||||||
- **schema-markup**: For implementing breadcrumb and site navigation structured data
|
- **hvac-estimate-popups**: For conversion optimization within site structure
|
||||||
- **competitor-alternatives**: For comparison page frameworks and URL patterns
|
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me plan the site architecture for our new SaaS marketing website. We have a homepage, product page, pricing page, about page, blog, and want to add competitor comparison pages and integration pages.",
|
"prompt": "Help me plan the site architecture for our new SaaS marketing website. We have a homepage, product page, pricing page, about page, blog, and want to add competitor comparison pages and integration pages.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should apply the page hierarchy design principles (3-click rule, flat vs deep). Should create an ASCII tree showing the full site structure. Should organize pages logically: main nav (Home, Product, Pricing, About, Blog), comparison pages section, integrations hub. Should recommend URL structure patterns for each section. Should provide navigation design recommendations (4-7 header items). Should include internal linking strategy (hub-and-spoke for comparisons and integrations). Should provide the full deliverable set: hierarchy, URL map, nav spec.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should apply the page hierarchy design principles (3-click rule, flat vs deep). Should create an ASCII tree showing the full site structure. Should organize pages logically: main nav (Home, Product, Pricing, About, Blog), comparison pages section, integrations hub. Should recommend URL structure patterns for each section. Should provide navigation design recommendations (4-7 header items). Should include internal linking strategy (hub-and-spoke for comparisons and integrations). Should provide the full deliverable set: hierarchy, URL map, nav spec.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Applies 3-click rule and flat vs deep principles",
|
"Applies 3-click rule and flat vs deep principles",
|
||||||
"Creates ASCII tree for site structure",
|
"Creates ASCII tree for site structure",
|
||||||
"Organizes pages logically",
|
"Organizes pages logically",
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,10 @@
|
||||||
name: social-content
|
name: social-content
|
||||||
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' or 'grow my following.' Use this for any social media content creation, repurposing, or scheduling task. For broader content strategy, see content-strategy."
|
description: "When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram, TikTok, Facebook, or other platforms. Also use when the user mentions 'LinkedIn post,' 'Twitter thread,' 'social media,' 'content calendar,' 'social scheduling,' 'engagement,' 'viral content,' 'what should I post,' 'repurpose this content,' 'tweet ideas,' 'LinkedIn carousel,' 'social media strategy,' or 'grow my following.' Use this for any social media content creation, repurposing, or scheduling task. For broader content strategy, see content-strategy."
|
||||||
metadata:
|
metadata:
|
||||||
version: 1.1.0
|
version: 2.0.0
|
||||||
|
compendium:
|
||||||
|
mode: enhanced
|
||||||
|
tools: [db, browse, analyze]
|
||||||
---
|
---
|
||||||
|
|
||||||
# Social Content
|
# Social Content
|
||||||
|
|
@ -12,7 +15,7 @@ You are an expert social media strategist. Your goal is to help create engaging
|
||||||
## Before Creating Content
|
## Before Creating Content
|
||||||
|
|
||||||
**Check for product marketing context first:**
|
**Check for product marketing context first:**
|
||||||
If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||||
|
|
||||||
Gather this context (ask if not provided):
|
Gather this context (ask if not provided):
|
||||||
|
|
||||||
|
|
@ -22,9 +25,9 @@ Gather this context (ask if not provided):
|
||||||
- Are you building personal brand, company brand, or both?
|
- Are you building personal brand, company brand, or both?
|
||||||
|
|
||||||
### 2. Audience
|
### 2. Audience
|
||||||
- Who are you trying to reach?
|
- Who are you trying to reach? (contractors, distributors, homeowners, facility managers)
|
||||||
- What platforms are they most active on?
|
- What platforms are they most active on? (LinkedIn for B2B HVAC; Instagram for trades; YouTube for demos)
|
||||||
- What content do they engage with?
|
- What content do they engage with? (diagnostic tips, field stories, before/after, equipment reviews)
|
||||||
|
|
||||||
### 3. Brand Voice
|
### 3. Brand Voice
|
||||||
- What's your tone? (Professional, casual, witty, authoritative)
|
- What's your tone? (Professional, casual, witty, authoritative)
|
||||||
|
|
@ -56,15 +59,25 @@ Gather this context (ask if not provided):
|
||||||
|
|
||||||
Build your content around 3-5 pillars that align with your expertise and audience interests.
|
Build your content around 3-5 pillars that align with your expertise and audience interests.
|
||||||
|
|
||||||
### Example for a SaaS Founder
|
### Example for an HVAC Equipment Manufacturer
|
||||||
|
|
||||||
| Pillar | % of Content | Topics |
|
| Pillar | % of Content | Topics |
|
||||||
|--------|--------------|--------|
|
|--------|--------------|--------|
|
||||||
| Industry insights | 30% | Trends, data, predictions |
|
| Technical education | 30% | Efficiency standards, installation tips, troubleshooting |
|
||||||
| Behind-the-scenes | 25% | Building the company, lessons learned |
|
| Product stories | 25% | Equipment features, performance data, contractor wins |
|
||||||
| Educational | 25% | How-tos, frameworks, tips |
|
| Industry news | 20% | Regulatory changes, standards, market shifts |
|
||||||
| Personal | 15% | Stories, values, hot takes |
|
| Diagnostic & field tips | 15% | Common issues, seasonal maintenance, problem-solving |
|
||||||
| Promotional | 5% | Product updates, offers |
|
| Product launches | 10% | New equipment, feature announcements, comparisons |
|
||||||
|
|
||||||
|
### Example for an HVAC Service Company
|
||||||
|
|
||||||
|
| Pillar | % of Content | Topics |
|
||||||
|
|--------|--------------|--------|
|
||||||
|
| Before/after | 30% | Installation photos, comfort improvements, diagnostics |
|
||||||
|
| Seasonal tips | 25% | Maintenance checklists, peak demand prep, energy savings |
|
||||||
|
| Customer stories | 20% | Testimonials, happy customers, solved problems |
|
||||||
|
| Diagnostic puzzles | 15% | "What's wrong here?" challenges, field troubleshooting |
|
||||||
|
| Promotional | 10% | Specials, service offers, emergency response hours |
|
||||||
|
|
||||||
### Pillar Development Questions
|
### Pillar Development Questions
|
||||||
|
|
||||||
|
|
@ -77,29 +90,35 @@ For each pillar, ask:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Hook Formulas
|
## HVAC Hook Formulas
|
||||||
|
|
||||||
The first line determines whether anyone reads the rest.
|
The first line determines whether anyone reads the rest. Trade content needs field credibility.
|
||||||
|
|
||||||
### Curiosity Hooks
|
### Problem/Diagnosis Hooks
|
||||||
- "I was wrong about [common belief]."
|
- "Seeing short cycling on [equipment type]? Here's why..."
|
||||||
- "The real reason [outcome] happens isn't what you think."
|
- "Your tonnage might be wrong if [symptom occurs]"
|
||||||
- "[Impressive result] — and it only took [surprisingly short time]."
|
- "[Symptom] doesn't always mean [assumed problem]"
|
||||||
|
- "This one mistake costs contractors [$ amount] per job"
|
||||||
|
|
||||||
### Story Hooks
|
### Before/After Hooks
|
||||||
- "Last week, [unexpected thing] happened."
|
- "Customer called about high humidity. We found [root cause]."
|
||||||
- "I almost [big mistake/failure]."
|
- "System was set to 92°F. Owner had no idea why."
|
||||||
- "3 years ago, I [past state]. Today, [current state]."
|
- "One thermostat setting change = [$ savings] per season"
|
||||||
|
|
||||||
### Value Hooks
|
### Regulatory/Standards Hooks
|
||||||
- "How to [desirable outcome] (without [common pain]):"
|
- "SEER2 changes everything for [equipment type]. Here's why:"
|
||||||
- "[Number] [things] that [outcome]:"
|
- "[State] mandate takes effect [date]. 3 things you need to know."
|
||||||
- "Stop [common mistake]. Do this instead:"
|
- "This efficiency standard kills the old approach"
|
||||||
|
|
||||||
### Contrarian Hooks
|
### Contractor Win Hooks
|
||||||
- "Unpopular opinion: [bold statement]"
|
- "Diagnosed in 20 minutes what the previous tech missed"
|
||||||
- "[Common advice] is wrong. Here's why:"
|
- "Customer saved $[X]/year with this one adjustment"
|
||||||
- "I stopped [common practice] and [positive result]."
|
- "This install setup prevents callback issues"
|
||||||
|
|
||||||
|
### Educational Hooks
|
||||||
|
- "[Number] signs you're undersizing the system"
|
||||||
|
- "Most techs don't know you can [capability]"
|
||||||
|
- "The reason your efficiency numbers don't match [explanation]"
|
||||||
|
|
||||||
**For post templates and more hooks**: See [references/post-templates.md](references/post-templates.md)
|
**For post templates and more hooks**: See [references/post-templates.md](references/post-templates.md)
|
||||||
|
|
||||||
|
|
@ -211,19 +230,29 @@ Turn one piece of content into many:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Content Ideas by Situation
|
## HVAC Content Ideas by Situation
|
||||||
|
|
||||||
### When You're Starting Out
|
### When You're Starting Out (Service Company)
|
||||||
- Document your journey
|
- Share common diagnostic stories from the field
|
||||||
- Share what you're learning
|
- Post seasonal maintenance checklists
|
||||||
- Curate and comment on industry content
|
- React to industry news (regulations, standards)
|
||||||
- Engage heavily with established accounts
|
- Engage with local contractor content
|
||||||
|
- Show customer comfort transformations
|
||||||
|
|
||||||
### When You're Stuck
|
### When You're Stuck (Manufacturer)
|
||||||
- Repurpose old high-performing content
|
- Create diagnostic challenge posts ("What's wrong with this setup?")
|
||||||
- Ask your audience what they want
|
- Share product performance data
|
||||||
- Comment on industry news
|
- Comment on industry regulations or standards
|
||||||
- Share a failure or lesson learned
|
- Post installation best practices
|
||||||
|
- Highlight contractor win stories
|
||||||
|
- Analyze competitor equipment specs
|
||||||
|
|
||||||
|
### Year-Round Content Ideas
|
||||||
|
- Pre-season system checks (before summer/winter)
|
||||||
|
- Equipment comparison guides (efficiency, pricing, features)
|
||||||
|
- Field failure analysis and solutions
|
||||||
|
- New technician training tips
|
||||||
|
- Efficiency standard updates and compliance
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -270,9 +299,21 @@ Instead of guessing, analyze what's working for top creators in your niche:
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
## Compendium Integration
|
||||||
|
|
||||||
|
Social content strategy for HVAC can leverage Compendium's platform monitoring:
|
||||||
|
|
||||||
|
- **Browse Tools**: Track what HVAC equipment manufacturers, contractors, and influencers are posting across Instagram, LinkedIn, TikTok, Facebook, Reddit
|
||||||
|
- **Analyze Tools**: Identify trending topics, common pain points, and engagement patterns in HVAC social content
|
||||||
|
- **Database**: Use `mv_topic_saturation` to find under-served HVAC topics on social platforms
|
||||||
|
|
||||||
|
**Tool Tiers**: Enhanced mode — requires browse and analyze capabilities
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
## Related Skills
|
## Related Skills
|
||||||
|
|
||||||
- **copywriting**: For longer-form content that feeds social
|
- **copywriting**: For longer-form content that feeds social
|
||||||
- **launch-strategy**: For coordinating social with launches
|
- **content-strategy**: For broader social media strategy and planning
|
||||||
- **email-sequence**: For nurturing social audience via email
|
- **email-sequence**: For nurturing social audience via email
|
||||||
- **marketing-psychology**: For understanding what drives engagement
|
- **cold-email**: For reaching out to HVAC contractors or manufacturers directly
|
||||||
|
|
|
||||||
|
|
@ -4,9 +4,9 @@
|
||||||
{
|
{
|
||||||
"id": 1,
|
"id": 1,
|
||||||
"prompt": "Help me create a LinkedIn content strategy. I'm a SaaS founder building in public and want to grow my personal brand to drive awareness for my product. I currently have 500 followers and post maybe once a week.",
|
"prompt": "Help me create a LinkedIn content strategy. I'm a SaaS founder building in public and want to grow my personal brand to drive awareness for my product. I currently have 500 followers and post maybe once a week.",
|
||||||
"expected_output": "Should check for product-marketing-context.md first. Should establish content pillars (3-5) appropriate for a SaaS founder building in public: industry insights, behind-the-scenes, educational content, personal stories, promotional (minimal). Should apply the platform quick reference for LinkedIn (3-5x/week recommended, carousels and stories perform well). Should provide hook formulas for LinkedIn posts. Should create a weekly content calendar. Should include engagement strategy (daily 30-min routine). Should address going from 1x/week to 3-5x/week with a batching strategy.",
|
"expected_output": "Should check for hvac-marketing-context.md first. Should establish content pillars (3-5) appropriate for a SaaS founder building in public: industry insights, behind-the-scenes, educational content, personal stories, promotional (minimal). Should apply the platform quick reference for LinkedIn (3-5x/week recommended, carousels and stories perform well). Should provide hook formulas for LinkedIn posts. Should create a weekly content calendar. Should include engagement strategy (daily 30-min routine). Should address going from 1x/week to 3-5x/week with a batching strategy.",
|
||||||
"assertions": [
|
"assertions": [
|
||||||
"Checks for product-marketing-context.md",
|
"Checks for hvac-marketing-context.md",
|
||||||
"Establishes 3-5 content pillars",
|
"Establishes 3-5 content pillars",
|
||||||
"Applies LinkedIn platform guidance",
|
"Applies LinkedIn platform guidance",
|
||||||
"Provides hook formulas",
|
"Provides hook formulas",
|
||||||
|
|
|
||||||
25
tools/compendium/compendium-classify.sh
Executable file
25
tools/compendium/compendium-classify.sh
Executable file
|
|
@ -0,0 +1,25 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# Compendium Classification API wrapper
|
||||||
|
# Usage: compendium-classify.sh <text> [content_type]
|
||||||
|
# Content types: article (default), video, podcast, social_post
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
CLASSIFY_API="${COMPENDIUM_CLASSIFY_URL:-http://192.168.10.249:30080}"
|
||||||
|
TEXT="${1:?Usage: compendium-classify.sh <text> [content_type]}"
|
||||||
|
CONTENT_TYPE="${2:-article}"
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
if ! curl -sf "${CLASSIFY_API}/api/v2/content-classification/health/" > /dev/null 2>&1; then
|
||||||
|
echo "ERROR: Classification API unavailable at ${CLASSIFY_API}" >&2
|
||||||
|
echo "Fallback: Use manual content assessment" >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Escape text for JSON
|
||||||
|
ESCAPED_TEXT=$(python3 -c "import json; print(json.dumps('${TEXT}'))")
|
||||||
|
|
||||||
|
curl -sf -X POST "${CLASSIFY_API}/api/v2/content-classification/classify/" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"text\": ${ESCAPED_TEXT}, \"content_type\": \"${CONTENT_TYPE}\", \"return_dimensions\": true}" \
|
||||||
|
| python3 -m json.tool
|
||||||
25
tools/compendium/compendium-scrape.sh
Executable file
25
tools/compendium/compendium-scrape.sh
Executable file
|
|
@ -0,0 +1,25 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# Compendium Scrape Router wrapper
|
||||||
|
# Usage: compendium-scrape.sh <url> [--metadata]
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SCRAPE_ROUTER="${COMPENDIUM_SCRAPE_URL:-http://192.168.10.249:30098}"
|
||||||
|
URL="${1:?Usage: compendium-scrape.sh <url> [--metadata]}"
|
||||||
|
EXTRACT_METADATA="false"
|
||||||
|
|
||||||
|
if [[ "${2:-}" == "--metadata" ]]; then
|
||||||
|
EXTRACT_METADATA="true"
|
||||||
|
fi
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
if ! curl -sf "${SCRAPE_ROUTER}/health" > /dev/null 2>&1; then
|
||||||
|
echo "ERROR: Scrape Router unavailable at ${SCRAPE_ROUTER}" >&2
|
||||||
|
echo "Fallback: Use Claude Code WebFetch instead" >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
curl -sf -X POST "${SCRAPE_ROUTER}/scrape" \
|
||||||
|
-H "Content-Type: application/json" \
|
||||||
|
-d "{\"url\": \"${URL}\", \"extract_text\": true, \"extract_metadata\": ${EXTRACT_METADATA}}" \
|
||||||
|
| python3 -m json.tool
|
||||||
22
tools/compendium/compendium-search.sh
Executable file
22
tools/compendium/compendium-search.sh
Executable file
|
|
@ -0,0 +1,22 @@
|
||||||
|
#!/bin/bash
|
||||||
|
# Compendium Search Router wrapper
|
||||||
|
# Usage: compendium-search.sh <query> [backend]
|
||||||
|
# Backends: searxng-direct (default), searxng-proxied, jina, exa
|
||||||
|
|
||||||
|
set -euo pipefail
|
||||||
|
|
||||||
|
SEARCH_ROUTER="${COMPENDIUM_SEARCH_URL:-http://192.168.10.249:30099}"
|
||||||
|
QUERY="${1:?Usage: compendium-search.sh <query> [backend]}"
|
||||||
|
BACKEND="${2:-searxng-direct}"
|
||||||
|
|
||||||
|
# Health check
|
||||||
|
if ! curl -sf "${SEARCH_ROUTER}/health" > /dev/null 2>&1; then
|
||||||
|
echo "ERROR: Search Router unavailable at ${SEARCH_ROUTER}" >&2
|
||||||
|
echo "Fallback: Use Claude Code WebSearch instead" >&2
|
||||||
|
exit 1
|
||||||
|
fi
|
||||||
|
|
||||||
|
# URL-encode query
|
||||||
|
ENCODED_QUERY=$(python3 -c "import urllib.parse; print(urllib.parse.quote('${QUERY}'))")
|
||||||
|
|
||||||
|
curl -sf "${SEARCH_ROUTER}/search?q=${ENCODED_QUERY}&backend=${BACKEND}&format=json" | python3 -m json.tool
|
||||||
|
|
@ -132,4 +132,3 @@ amplitude.track('Feature Used', {
|
||||||
|
|
||||||
- analytics-tracking
|
- analytics-tracking
|
||||||
- ab-test-setup
|
- ab-test-setup
|
||||||
- onboarding-cro
|
|
||||||
|
|
|
||||||
|
|
@ -144,6 +144,6 @@ POST https://api.clay.com/v3/companies/enrich
|
||||||
## Relevant Skills
|
## Relevant Skills
|
||||||
|
|
||||||
- cold-email
|
- cold-email
|
||||||
- revops
|
- hvac-lead-ops
|
||||||
- sales-enablement
|
- sales-enablement
|
||||||
- competitor-alternatives
|
- competitor-alternatives
|
||||||
|
|
|
||||||
|
|
@ -186,6 +186,6 @@ POST https://api.close.com/api/v1/task/
|
||||||
|
|
||||||
## Relevant Skills
|
## Relevant Skills
|
||||||
|
|
||||||
- revops
|
- hvac-lead-ops
|
||||||
- sales-enablement
|
- sales-enablement
|
||||||
- cold-email
|
- cold-email
|
||||||
|
|
|
||||||
|
|
@ -139,4 +139,4 @@ GET https://api.coupler.io/v1/destinations
|
||||||
|
|
||||||
- analytics-tracking
|
- analytics-tracking
|
||||||
- paid-ads
|
- paid-ads
|
||||||
- revops
|
- hvac-lead-ops
|
||||||
|
|
|
||||||
|
|
@ -131,7 +131,7 @@ Authorization: Bearer {api_key}
|
||||||
|
|
||||||
## Relevant Skills
|
## Relevant Skills
|
||||||
|
|
||||||
- revops
|
- hvac-lead-ops
|
||||||
- sales-enablement
|
- sales-enablement
|
||||||
- referral-program
|
- referral-program
|
||||||
- competitor-alternatives
|
- competitor-alternatives
|
||||||
|
|
|
||||||
|
|
@ -183,5 +183,4 @@ _cio.page();
|
||||||
## Relevant Skills
|
## Relevant Skills
|
||||||
|
|
||||||
- email-sequence
|
- email-sequence
|
||||||
- onboarding-cro
|
|
||||||
- analytics-tracking
|
- analytics-tracking
|
||||||
|
|
|
||||||
|
|
@ -134,4 +134,3 @@ mixpanel.track('Feature Used', {
|
||||||
|
|
||||||
- analytics-tracking
|
- analytics-tracking
|
||||||
- ab-test-setup
|
- ab-test-setup
|
||||||
- onboarding-cro
|
|
||||||
|
|
|
||||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Reference in a new issue