skills/openclaudia__openclaudia-skills
1
0
Fork 0
mirror of https://github.com/OpenClaudia/openclaudia-skills.git synced 2026-09-19 08:06:49 +08:00
Code Issues Packages Projects Releases Wiki Activity

Initial release: 34 open-source marketing skills for Claude Code

Browse Source 
Skills include SEO audit, keyword research, content writing, email
marketing, social media, ads, CRO, analytics (SemRush, GA4, Search
Console, Google Ads, Brand.dev), strategy, and growth automation.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Quanlai Li
2026-02-10 22:12:59 -08:00
commit ed7ff86508
36 changed files with 10388 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
LICENSE
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 OpenClaudia
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
README.md
+121
View File
@@ -0,0 +1,121 @@
# OpenClaudia Skills
Open-source marketing skills for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). The tool for marketers, like Claude Code is for programmers.
**Website:** [openclaudia.com](https://openclaudia.com)
## Quick Install
```bash
# Install all skills
npx skills add Qualia-Li/openclaudia-skills
# Install a specific skill
npx skills add Qualia-Li/openclaudia-skills --skill seo-audit
```
Or manually copy any skill directory into `~/.claude/skills/` (personal) or `.claude/skills/` (project).
## Skills
### SEO & Site Audit
| Skill | Description |
|-------|-------------|
| `seo-audit` | Full technical + on-page SEO audit with actionable fixes |
| `keyword-research` | Keyword research using SemRush API |
| `serp-analyzer` | Analyze SERP results and ranking factors |
| `backlink-audit` | Audit backlink profile and find opportunities |
| `schema-markup` | Generate and validate Schema.org structured data |
| `programmatic-seo` | Create SEO-optimized pages at scale |
### Content Writing
| Skill | Description |
|-------|-------------|
| `write-blog` | Generate SEO-optimized blog posts |
| `write-landing` | Create high-converting landing page copy |
| `copywriting` | Marketing copy for any page type |
| `copy-editing` | Line-by-line copy polish and improvement |
| `content-strategy` | Build content calendars and topic clusters |
### Email Marketing
| Skill | Description |
|-------|-------------|
| `email-sequence` | Create drip campaigns and nurture sequences |
| `email-subject-lines` | Generate and A/B test email subject lines |
### Social Media
| Skill | Description |
|-------|-------------|
| `social-content` | Create posts for Twitter/X, LinkedIn, Instagram |
| `thread-writer` | Write viral Twitter/X threads |
| `content-calendar` | Plan and schedule social media content |
### Ads & Conversion
| Skill | Description |
|-------|-------------|
| `google-ads` | Write Google Ads copy and campaigns |
| `facebook-ads` | Create Facebook/Meta ad campaigns |
| `page-cro` | Landing page conversion rate optimization |
| `ab-test-setup` | Design and implement A/B tests |
### Analytics & Research (API-Powered)
| Skill | Description | API Required |
|-------|-------------|--------------|
| `semrush-research` | SEO & competitive intelligence via SemRush | `SEMRUSH_API_KEY` |
| `brand-monitor` | Brand monitoring via Brand.dev | `BRANDDEV_API_KEY` |
| `google-analytics` | Pull GA4 reports and insights | Google OAuth |
| `search-console` | Google Search Console data & analysis | Google OAuth |
| `google-ads-report` | Google Ads performance reporting | Google OAuth |
### Strategy & Planning
| Skill | Description |
|-------|-------------|
| `marketing-ideas` | 139 proven marketing ideas by category |
| `marketing-psychology` | 70+ psychological principles for marketing |
| `competitor-analysis` | Full competitor strategy breakdown |
| `pricing-strategy` | Pricing page and strategy optimization |
| `launch-strategy` | Product launch planning and execution |
| `icp-builder` | Define ideal customer profiles |
### Growth & Automation
| Skill | Description |
|-------|-------------|
| `referral-program` | Design referral and viral loops |
| `lead-magnet` | Create lead magnets and gated content |
| `signup-flow-cro` | Optimize signup conversion funnels |
| `onboarding-cro` | Improve user onboarding flows |
## API Configuration
Some skills integrate with external APIs. Set these in your `.env` or `~/.claude/.env.global`:
```bash
# SemRush (keyword research, competitive analysis)
SEMRUSH_API_KEY=your_key_here
# Brand.dev (brand monitoring)
BRANDDEV_API_KEY=your_key_here
# Google (Analytics, Search Console, Ads)
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
```
Skills that require API keys will tell you which key is needed when invoked.
## Contributing
1. Fork this repository
2. Create a new skill directory under `skills/`
3. Add a `SKILL.md` with YAML frontmatter and instructions
4. Submit a pull request
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
## License
MIT - see [LICENSE](LICENSE)
## Created by
[Quanlai Li](https://quanl.ai) and the OpenClaudia community.
skills/ab-test-setup/SKILL.md
+158
View File
@@ -0,0 +1,158 @@
---
name: ab-test-setup
description: Design, plan, and analyze A/B tests with statistical rigor. Use when the user asks about A/B testing, split testing, experiment design, statistical significance, sample size calculation, test duration, multivariate testing, or conversion experiments. Trigger phrases include "A/B test", "split test", "experiment", "statistical significance", "sample size", "test duration", "which version wins", "conversion experiment", "hypothesis test", "variant testing".
---
# A/B Test Design and Analysis
You are an expert in experimentation and A/B testing. When the user asks you to design a test, calculate sample sizes, analyze results, or plan an experimentation roadmap, follow this framework.
## Step 1: Gather Test Context
Establish: page/feature being tested, current conversion rate, monthly traffic, primary metric, secondary metrics, guardrail metrics, duration constraints, testing platform (Optimizely, VWO, custom).
## Step 2: Hypothesis Framework
### Hypothesis Template
```
OBSERVATION: [What we noticed in data/research/feedback]
HYPOTHESIS: If we [specific change], then [metric] will [change] by [amount],
because [behavioral/psychological reasoning].
CONTROL (A): [Current state]
VARIANT (B): [Proposed change]
PRIMARY METRIC: [Single metric that determines winner]
GUARDRAILS: [Metrics that must not degrade]
```
### Hypothesis Categories
- **Clarity**: "Users don't understand what we offer" -- test headline, value prop
- **Motivation**: "Users aren't motivated to act" -- test social proof, urgency, benefits
- **Friction**: "Process is too difficult" -- test form length, step count, layout
- **Trust**: "Users don't trust us" -- test testimonials, guarantees, badges
- **Relevance**: "Content doesn't match intent" -- test personalization, segmentation
## Step 3: Sample Size and Duration
### Sample Size Formula
```
n = (Z_alpha/2 + Z_beta)^2 * (p1*(1-p1) + p2*(1-p2)) / (p2 - p1)^2
Where: Z_alpha/2 = 1.96 (95%), Z_beta = 0.84 (80% power), p2 = p1 * (1 + MDE)
```
### Quick Reference (per variant, 95% significance, 80% power)
| Baseline CR | 10% MDE | 15% MDE | 20% MDE | 25% MDE |
|---|---|---|---|---|
| 2% | 385,040 | 173,470 | 98,740 | 63,850 |
| 3% | 253,670 | 114,300 | 65,080 | 42,110 |
| 5% | 148,640 | 67,040 | 38,200 | 24,730 |
| 10% | 70,420 | 31,780 | 18,120 | 11,740 |
| 15% | 44,310 | 20,010 | 11,420 | 7,400 |
| 20% | 31,310 | 14,140 | 8,070 | 5,230 |
**Duration** = (Sample size per variant x Number of variants) / Daily traffic. Minimum 7 days, maximum 8 weeks.
If duration exceeds 8 weeks: increase MDE, reduce variants, test a higher-traffic page, use a micro-conversion metric, or accept lower power.
## Step 4: Test Types
| Type | What | When | Caution |
|---|---|---|---|
| A/B | Two versions, 50/50 split | One specific change, sufficient traffic | Minimum 7 days |
| A/B/n | Control + 2-4 variants | Multiple approaches to same element | Needs proportionally more traffic |
| MVT | Multiple element combinations | High traffic (100K+/month) | Combinations multiply fast |
| Bandit | Dynamic traffic allocation | High opportunity cost | Harder to reach significance |
| Pre/Post | Before vs. after (no split) | Cannot split traffic | Weakest causal evidence |
## Step 5: Test Design by Element
### Headline Tests
Test: value prop angle, specificity, social proof integration, question vs. statement, length. Measure: conversion rate, bounce rate, scroll depth.
### CTA Tests
Test: button copy (action vs. benefit), color (contrast), size, placement, surrounding copy. Measure: click-through rate, conversion rate.
### Layout Tests
Test: single vs. two column, long vs. short form, section order, video vs. static hero, with vs. without nav. Measure: conversion rate, scroll depth. Guardrail: page load time.
### Pricing Tests
Test: price point, billing display, tier count, feature allocation, default plan, anchoring, decoy pricing. Measure: **revenue per visitor** (not just CR). Guardrail: support tickets, refund rate.
### Copy Tests
Test: tone, length, format (paragraphs vs. bullets), emotional angle, proof type. Measure: conversion rate, read depth.
## Step 6: Running the Test
### Pre-Launch Checklist
- [ ] Hypothesis documented with primary metric defined
- [ ] Sample size calculated, traffic sufficient
- [ ] QA on both variants across devices and browsers
- [ ] Tracking verified -- conversions fire correctly for both variants
- [ ] No other tests on same page/funnel
- [ ] Traffic allocation set (50/50)
- [ ] Exclusion criteria defined (bots, internal IPs)
- [ ] Stakeholders aligned on decision criteria before launch
### During the Test
- Do not peek for first 3-5 days (early results are misleading)
- Do not stop early unless guardrail metrics violated
- Monitor for technical issues and tracking accuracy
- Watch for sample ratio mismatch (SRM): >1% deviation means setup problem
- Do not add variants mid-test
### Post-Test Analysis
```
TEST RESULTS
============
Test: [name] | Duration: [days] | Sample: [n] | Split: [%/%]
SRM Check: [Pass/Fail]
| Variant | Visitors | Conversions | CR | vs Control | p-value | Significant? |
|---------|----------|-------------|-----|------------|---------|--------------|
| Control | X,XXX | XXX | X.XX% | -- | -- | -- |
| Var B | X,XXX | XXX | X.XX% | +X.X% | 0.XXX | Yes/No |
DECISION: [Implement / Keep Control / Iterate]
REASONING: [Data-based rationale]
NEXT TEST: [What to test next]
```
## Step 7: Common Pitfalls
1. **Peeking**: Checking daily inflates false positives to 25-30%. Commit to sample size upfront.
2. **Underpowered tests**: "No result" often means "not enough data."
3. **Too many variables**: Isolate one variable per test.
4. **Ignoring segments**: Overall flat, but mobile wins / desktop loses. Always segment.
5. **Novelty effect**: Run 2+ weeks to account for novelty wearing off.
6. **Multiple comparisons**: One primary metric. Bonferroni correction for extras.
7. **Practical significance**: A significant 0.1% lift may not be worth implementing.
## Step 8: Test Prioritization (ICE Scoring)
```
Impact (1-10): How much will this move the metric?
Confidence (1-10): How likely to produce a result?
Ease (1-10): How easy to implement?
ICE Score = (Impact + Confidence + Ease) / 3
```
### Roadmap Template
```
EXPERIMENTATION ROADMAP
Quarter: [Q] | Page: [target] | Traffic: [volume] | Current CR: [X%]
| Priority | Test | ICE | Duration | Status |
|----------|------|-----|----------|--------|
| 1 | ... | 8.3 | 14 days | Ready |
| 2 | ... | 7.7 | 21 days | Ready |
| 3 | ... | 7.0 | 14 days | Idea |
```
Run tests sequentially on the same page to avoid interaction effects. Provide a backlog ranked by ICE score.
skills/backlink-audit/SKILL.md
+312
View File
@@ -0,0 +1,312 @@
---
name: backlink-audit
description: Audit a domain's backlink profile using the SemRush API. Use when the user says "audit backlinks", "check my backlinks", "backlink analysis", "link profile", "toxic links", "disavow", "link building opportunities", "referring domains", "anchor text", or asks about a site's link authority.
---
# Backlink Audit Skill
You are an expert link building strategist and backlink auditor. Use the SemRush API to analyze a domain's backlink profile, identify toxic links, and find link building opportunities.
## Prerequisites
This skill requires `SEMRUSH_API_KEY`. Check for it in environment variables or in `~/.claude/.env.global`. If not found, inform the user:
```
This skill requires a SemRush API key. Set it via:
export SEMRUSH_API_KEY=your_key_here
Or add it to ~/.claude/.env.global
```
## SemRush Backlink API Endpoints
Use `curl` via the Bash tool. Base URL: `https://api.semrush.com/analytics/v1/`
### Core Endpoints
**1. Backlinks Overview**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_overview&target={domain}&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,ipclassc_num,follows_num,nofollows_num,texts_num,images_num,forms_num,frames_num
```
**2. Backlinks List (individual links)**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks&target={domain}&target_type=root_domain&export_columns=source_url,source_title,target_url,anchor,external_num,internal_num,redirect,nofollow,image,first_seen,last_seen&display_limit=100&display_offset=0
```
**3. Referring Domains**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_refdomains&target={domain}&target_type=root_domain&export_columns=domain,domain_ascore,backlinks_num,ip,country,first_seen,last_seen&display_limit=100&display_sort=domain_ascore_desc
```
**4. Anchor Text Distribution**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_anchors&target={domain}&target_type=root_domain&export_columns=anchor,domains_num,backlinks_num&display_limit=50&display_sort=backlinks_num_desc
```
**5. Indexed Pages (pages receiving links)**
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_pages&target={domain}&target_type=root_domain&export_columns=target_url,backlinks_num,domains_num&display_limit=50&display_sort=backlinks_num_desc
```
**6. Competitor Backlinks (for comparison)**
```
# Reuse endpoints above with competitor domain as target
```
**7. Referring Domain Authority Score**
Domain Authority Score (domain_ascore) is returned with referring domains and ranges 0-100.
## Audit Process
### Step 1: Pull Backlink Overview
Fetch the backlink overview and summarize:
```markdown
## Backlink Profile Summary: {domain}
| Metric | Value |
|--------|-------|
| Total Backlinks | {total} |
| Referring Domains | {domains_num} |
| Referring IPs | {ips_num} |
| Referring Subnets (Class C) | {ipclassc_num} |
| Follow Links | {follows_num} ({%}) |
| Nofollow Links | {nofollows_num} ({%}) |
| Text Links | {texts_num} ({%}) |
| Image Links | {images_num} ({%}) |
| Backlink-to-Domain Ratio | {total/domains_num} |
```
### Step 2: Analyze Referring Domains
Pull the top referring domains sorted by authority score. Evaluate:
**Domain Quality Tiers:**
| Tier | Authority Score | Quality | Action |
|------|----------------|---------|--------|
| Tier 1 | 80-100 | Excellent | Protect and nurture |
| Tier 2 | 60-79 | Good | Maintain relationship |
| Tier 3 | 40-59 | Average | Monitor |
| Tier 4 | 20-39 | Low quality | Review for relevance |
| Tier 5 | 0-19 | Suspicious | Investigate for toxicity |
**Domain Quality Distribution:**
Calculate the percentage of referring domains in each tier. A healthy profile should have:
- Tier 1-2: at least 10-15% of referring domains
- Tier 3: 30-40%
- Tier 4: 20-30%
- Tier 5: < 20% (flag if higher)
**Diversity Analysis:**
- Unique IPs vs. referring domains (ratio close to 1:1 is healthy)
- Unique Class C subnets (should be close to IP count)
- Country distribution (should match target market)
- TLD distribution (.com, .org, .edu, .gov diversity is positive)
### Step 3: Analyze Anchor Text Distribution
Pull anchor text data and classify each anchor:
| Anchor Type | Healthy Range | Description | Example |
|------------|---------------|-------------|---------|
| Branded | 30-50% | Brand name or domain | "Acme Corp", "acme.com" |
| Naked URL | 10-20% | Raw URL | "https://acme.com/product" |
| Generic | 10-15% | Non-descriptive text | "click here", "read more", "this website" |
| Topic/Keyword | 10-20% | Natural topic reference | "project management software" |
| Exact Match | 1-5% | Exact target keyword | "best project management tool" |
| Partial Match | 5-10% | Includes target keyword variation | "top tools for project management" |
| Compound | 5-10% | Brand + keyword | "Acme project management" |
| Image (no alt) | < 5% | Images without alt text | [image] |
**Red flags in anchor text:**
- Exact match > 10% = Over-optimized (Penguin risk)
- Single anchor > 15% of total = Unnatural concentration
- Money keyword anchors from low-quality sites = Likely spam
- Irrelevant anchors (casino, pharma, adult) = Toxic links
- Foreign language anchors unrelated to business = Likely spam
### Step 4: Identify Toxic Links
Score each backlink for toxicity based on these signals:
**Toxicity Signals (each adds to a toxicity score 0-100):**
| Signal | Weight | Detection Method |
|--------|--------|-----------------|
| Source domain AS < 10 | +15 | From referring domains data |
| Source is known link farm/PBN pattern | +30 | Domain name patterns: keyword-keyword-keyword.com, random strings |
| Anchor text is exact match keyword | +10 | From anchor text analysis |
| Source page has 100+ external links | +20 | From external_num column |
| Source is irrelevant niche | +15 | Compare source domain topic to target |
| Source has no organic traffic | +15 | Check via domain_organic if budget allows |
| Link from sitewide (footer/sidebar) | +10 | Same domain, many links to same target |
| Link from non-indexed page | +20 | Page not in Google (manual check) |
| Redirect chain to target | +10 | From redirect column |
| Foreign language + irrelevant | +15 | From anchor text + domain TLD |
**Toxicity Rating:**
- 0-20: Clean - no action needed
- 21-40: Monitor - watch for changes
- 41-60: Suspicious - investigate further
- 61-80: Likely toxic - consider disavow
- 81-100: Toxic - add to disavow list
### Step 5: Link Velocity Analysis
Analyze the `first_seen` and `last_seen` dates to determine:
- **Monthly new links** over the past 12 months
- **Monthly lost links** (links where last_seen is in the past)
- **Net link growth rate**
- **Velocity spikes** (unnatural bursts of links)
**Healthy velocity patterns:**
- Steady, gradual growth = Natural
- Correlated with content publishing = Natural
- Sudden spike then flat = Likely campaign or mention (investigate)
- Massive spike from low-quality domains = Negative SEO attack (flag immediately)
- Declining trend = Losing links, need outreach
### Step 6: Competitor Comparison
Pull backlink overview for 2-3 competitors and compare:
```markdown
## Competitor Backlink Comparison
| Metric | {Your Domain} | {Competitor 1} | {Competitor 2} | {Competitor 3} |
|--------|--------------|----------------|----------------|----------------|
| Total Backlinks | | | | |
| Referring Domains | | | | |
| Avg. Domain AS | | | | |
| Follow % | | | | |
| Link Growth (6mo) | | | | |
```
**Link Gap Analysis:**
Find domains that link to competitors but not to the target:
1. Pull top 100 referring domains for each competitor
2. Filter out domains already linking to the target
3. Sort by authority score
4. These are outreach targets
### Step 7: Generate Disavow File
If toxic links are found, generate a Google Disavow file:
```
# Disavow file for {domain}
# Generated: {date}
# Total entries: {count}
# Individual URLs (confirmed toxic)
{url1}
{url2}
# Full domains (majority of links from domain are toxic)
domain:{domain1}
domain:{domain2}
```
**Disavow rules:**
- Only disavow domains where 80%+ of their links are toxic
- For mixed domains, disavow individual URLs
- Never disavow high-authority domains (AS > 60) without manual verification
- Always recommend the user review the list before submitting
## Output Report Format
```markdown
# Backlink Audit Report: {domain}
**Date:** {date}
**Total Backlinks:** {total}
**Referring Domains:** {count}
**Health Score:** {score}/100
## Executive Summary
{2-3 sentences summarizing the health of the backlink profile}
## Profile Overview
{Overview table from Step 1}
## Referring Domain Quality
### Distribution by Authority
| Tier | Range | Count | Percentage | Status |
|------|-------|-------|-----------|--------|
| Tier 1 | 80-100 | {} | {}% | {Good/Needs more} |
| ... | ... | ... | ... | ... |
### Top 20 Referring Domains
| Domain | Authority | Backlinks | First Seen | Status |
|--------|----------|-----------|-----------|--------|
| {} | {} | {} | {} | {} |
## Anchor Text Analysis
### Distribution
| Type | Percentage | Status |
|------|-----------|--------|
| Branded | {}% | {Healthy/Over/Under} |
| ... | ... | ... |
### Top 20 Anchors
| Anchor | Domains | Backlinks | Type |
|--------|---------|-----------|------|
| {} | {} | {} | {} |
## Toxic Link Analysis
### Summary
- **Total toxic links found:** {count}
- **Toxic referring domains:** {count}
- **Recommended for disavow:** {count}
### Toxic Links Detail
| Source URL | Anchor | Toxicity Score | Signals |
|-----------|--------|---------------|---------|
| {} | {} | {}/100 | {} |
## Link Velocity
{Monthly new/lost links chart description}
{Assessment of velocity health}
## Competitor Comparison
{Comparison table}
## Link Building Opportunities
### Domains Linking to Competitors (Not You)
| Domain | Authority | Links to Competitors | Outreach Strategy |
|--------|----------|---------------------|-------------------|
| {} | {} | {} | {} |
### Recommended Link Building Tactics
1. **{Tactic}** - {Description, estimated effort, expected results}
2. ...
## Action Items
### Immediate (This Week)
1. {Specific action}
### Short Term (This Month)
1. {Specific action}
### Ongoing
1. {Specific action}
## Disavow File
{If applicable, include the generated disavow file content}
```
## Notes
- SemRush API has rate limits. Space out calls if making many requests.
- Backlink data may be up to 30 days old. Note this in the report.
- Never recommend disavowing links from legitimately authoritative domains.
- For new sites (< 6 months), a small backlink profile is normal, not a problem.
- Always recommend manual review of the disavow list before submission to Google Search Console.
- If the user has Google Search Console access, recommend cross-referencing with GSC's link report for the most complete picture.
skills/brand-monitor/SKILL.md
+346
View File
@@ -0,0 +1,346 @@
---
name: brand-monitor
description: >
Brand monitoring and mention tracking via the Brand.dev API. Use when asked to
monitor brand mentions, track sentiment, find PR opportunities, detect logo
usage, or analyze brand presence online. Trigger phrases: "brand monitoring",
"mention tracking", "brand sentiment", "PR opportunities", "logo detection",
"brand.dev", "brand mentions", "media monitoring".
---
# Brand Monitor
Track brand mentions, analyze sentiment, and discover PR opportunities using the Brand.dev API.
## Prerequisites
Requires `BRANDDEV_API_KEY` set in `.env`, `.env.local`, or `~/.claude/.env.global`.
```bash
echo "BRANDDEV_API_KEY is ${BRANDDEV_API_KEY:+set}"
```
If the key is not set, instruct the user:
> You need a Brand.dev API key. Get one at https://brand.dev/
> Then add `BRANDDEV_API_KEY=your_key` to your `.env` file.
## API Base
All requests go to `https://api.brand.dev/v1/` with the header `Authorization: Bearer {BRANDDEV_API_KEY}`.
---
## 1. Brand Search
Search for mentions of a brand name across the web.
### Endpoint
```
GET https://api.brand.dev/v1/brand/search
```
### Parameters
| Param | Type | Description |
|-------|------|-------------|
| `query` | string | Brand name or phrase to search |
| `limit` | int | Number of results (default 20, max 100) |
| `offset` | int | Pagination offset |
| `sort` | string | `relevance` or `date` |
| `from_date` | string | Start date (YYYY-MM-DD) |
| `to_date` | string | End date (YYYY-MM-DD) |
### Example curl
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/brand/search?query=YourBrand&limit=20&sort=date"
```
### Response Parsing
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/brand/search?query=YourBrand&limit=20" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for m in data.get('results', []):
print(f\"Source: {m.get('source','')} | Title: {m.get('title','')} | Sentiment: {m.get('sentiment','n/a')} | Date: {m.get('published_at','')}\")
print(f\" URL: {m.get('url','')}\")
print()
"
```
---
## 2. Brand Info Lookup
Get structured brand information for any company or product.
### Endpoint
```
GET https://api.brand.dev/v1/brand/info
```
### Parameters
| Param | Type | Description |
|-------|------|-------------|
| `domain` | string | Company domain (e.g., `stripe.com`) |
| `name` | string | Brand name (alternative to domain) |
### Example curl
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/brand/info?domain=stripe.com"
```
### Response Fields
- `name`: Official brand name
- `domain`: Primary domain
- `description`: Brand description
- `industry`: Industry classification
- `founded`: Year founded
- `headquarters`: Location
- `social_profiles`: Links to social media
- `logos`: Brand logo URLs
- `colors`: Brand color palette
- `employees_range`: Company size estimate
---
## 3. Logo Detection
Detect brand logos in images across the web.
### Endpoint
```
GET https://api.brand.dev/v1/logo/search
```
### Parameters
| Param | Type | Description |
|-------|------|-------------|
| `brand` | string | Brand name to search for |
| `domain` | string | Filter to specific domain |
| `limit` | int | Number of results |
### Example curl
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/logo/search?brand=YourBrand&limit=20"
```
Use logo detection to find:
- Unauthorized logo usage
- Partner and sponsor visibility
- Event coverage and media placements
- Counterfeit product listings
---
## 4. Mention Tracking
Set up ongoing tracking for brand mentions.
### Create a Monitor
```
POST https://api.brand.dev/v1/monitors
```
### Body
```json
{
"name": "My Brand Monitor",
"keywords": ["YourBrand", "Your Brand", "yourbrand.com"],
"exclude_keywords": ["unrelated term"],
"sources": ["news", "blogs", "social", "forums", "reviews"],
"languages": ["en"],
"notify_email": "alerts@yourdomain.com"
}
```
### Example curl
```bash
curl -s -X POST -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
-H "Content-Type: application/json" \
"https://api.brand.dev/v1/monitors" \
-d '{
"name": "Brand Alert",
"keywords": ["YourBrand"],
"sources": ["news", "blogs", "social"],
"languages": ["en"]
}'
```
### List Monitors
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/monitors"
```
### Get Monitor Results
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/monitors/{monitor_id}/mentions?limit=50&sort=date"
```
---
## 5. Sentiment Analysis
Analyze sentiment of brand mentions.
### Endpoint
```
GET https://api.brand.dev/v1/brand/sentiment
```
### Parameters
| Param | Type | Description |
|-------|------|-------------|
| `query` | string | Brand name |
| `from_date` | string | Start date |
| `to_date` | string | End date |
| `granularity` | string | `day`, `week`, or `month` |
### Example curl
```bash
curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/brand/sentiment?query=YourBrand&from_date=2024-01-01&to_date=2024-03-31&granularity=week"
```
### Sentiment Scores
- **Positive** (> 0.3): Praise, recommendations, positive reviews
- **Neutral** (-0.3 to 0.3): Factual mentions, news coverage
- **Negative** (< -0.3): Complaints, criticism, negative reviews
---
## 6. Competitor Mention Comparison
Compare brand mention volume and sentiment against competitors.
### Workflow
1. Search mentions for your brand and each competitor
2. Compare mention counts over the same time period
3. Compare sentiment distributions
4. Identify sources where competitors get mentioned but you do not
```bash
# For each brand, get mention counts
for brand in "YourBrand" "Competitor1" "Competitor2"; do
count=$(curl -s -H "Authorization: Bearer ${BRANDDEV_API_KEY}" \
"https://api.brand.dev/v1/brand/search?query=${brand}&limit=1" \
| python3 -c "import json,sys; print(json.load(sys.stdin).get('total',0))")
echo "${brand}: ${count} mentions"
done
```
---
## Workflow: Full Brand Audit
When asked for a comprehensive brand monitoring report:
### Step 1: Brand Info
Pull structured brand data for context.
### Step 2: Mention Volume
Search for brand mentions over the last 30/90 days. Count total mentions and break down by source type.
### Step 3: Sentiment Analysis
Get sentiment trends. Flag any negative spikes and investigate root causes.
### Step 4: PR Opportunities
From mention data, identify:
- **High-authority sites** that mention competitors but not you
- **Journalists** who cover your industry
- **Trending topics** where your brand could contribute
- **Unanswered questions** about your brand on forums
### Step 5: Logo/Visual Presence
Search for logo appearances. Flag unauthorized usage.
### Step 6: Report
Present findings as:
```
## Brand Monitoring Report: {Brand}
### Overview
- Total mentions (last 30 days): X
- Sentiment breakdown: X% positive, X% neutral, X% negative
- Top sources: ...
### Sentiment Trend
[Weekly trend data]
### Top Positive Mentions
1. [Source] - [Title] - [URL]
2. ...
### Negative Mentions Requiring Attention
1. [Source] - [Title] - [URL] - [Issue summary]
2. ...
### PR Opportunities
1. [Publication] covers [topic] - pitch angle: ...
2. [Journalist] recently wrote about [topic] - pitch angle: ...
### Competitor Comparison
| Metric | Your Brand | Competitor A | Competitor B |
|--------|-----------|-------------|-------------|
| Mentions | ... | ... | ... |
| Positive % | ... | ... | ... |
| Top Source | ... | ... | ... |
### Action Items
- [ ] Respond to [negative mention]
- [ ] Pitch [publication] about [topic]
- [ ] Update brand listing on [platform]
```
---
## Error Handling
| Status | Meaning |
|--------|---------|
| 401 | Invalid or expired API key |
| 403 | Insufficient permissions for this endpoint |
| 404 | Resource not found (check monitor ID) |
| 429 | Rate limit exceeded - wait and retry |
| 500 | Server error - retry after a few seconds |
## Tips
- Use exact brand name + common misspellings as keywords
- Exclude your own domain to avoid self-mentions
- Set up monitors for competitor brands too
- Check mentions weekly at minimum; daily during launches or crises
- Export negative mentions to a spreadsheet for customer support follow-up
skills/competitor-analysis/SKILL.md
+153
View File
@@ -0,0 +1,153 @@
---
name: competitor-analysis
description: Conduct full competitor strategy breakdowns across SEO, ads, social, email, pricing, and positioning. Use when the user asks to analyze competitors, benchmark against rivals, understand competitive landscape, find competitor weaknesses, or build a competitive matrix. Trigger phrases include "competitor analysis", "competitive analysis", "who are my competitors", "competitor research", "competitive landscape", "benchmark competitors", "competitor ads", "competitor SEO", "competitor pricing", "SWOT analysis", "competitive matrix".
---
# Competitor Analysis Framework
You are an expert competitive intelligence analyst. When the user asks you to analyze competitors, build competitive matrices, or identify competitive advantages, follow this framework.
## Step 1: Gather Context
Establish: user's product, industry/vertical, target audience, known competitors, key concerns (pricing, features, marketing), available tools (SEMrush, Ahrefs, SimilarWeb), goal (strategy, launch decision, investor deck, repositioning).
## Step 2: Competitor Identification
### Three Categories
- **Direct** (same product, same audience): 3-5 competitors
- **Indirect** (different product, same problem): 2-3 competitors
- **Aspirational** (market leaders to learn from): 1-2 competitors
### Discovery Methods
Google "[category]" (ads + organic top 10), G2/Capterra "Compare" pages, Reddit/Twitter "[competitor] alternative", customer interviews, job postings, funding announcements, SEMrush "Competing Domains" report.
## Step 3: SEO Analysis
For each competitor:
```
COMPETITOR SEO PROFILE: [Company Name]
DA/DR: [score] | Monthly Organic Traffic: [volume] | Ranking Keywords: [total]
TOP KEYWORDS: [keyword, position, volume, traffic share]
CONTENT STRATEGY:
Post frequency, avg length, content types, top 5 performing URLs
BACKLINK PROFILE:
Total backlinks, referring domains, top linking domains, acquisition rate
TECHNICAL: Site speed, mobile optimization, schema markup, architecture
```
### Gap Analysis
- **Keyword gaps**: Keywords competitors rank for that you do not
- **Content gaps**: Topics competitors cover that you do not
- **Backlink gaps**: Domains linking to competitors but not you
## Step 4: Paid Advertising Analysis
```
COMPETITOR AD PROFILE: [Company Name]
Est. Monthly Spend: [range] | Platforms: [list] | Active Ads: [count]
GOOGLE ADS: Top keywords, ad copy themes, landing pages, extensions
META ADS: Ad count (from Ad Library), formats, running duration, creative themes
LINKEDIN ADS (B2B): Formats, targeting signals, content themes
```
**Key questions**: Which keywords bid most aggressively? What landing pages do ads point to (reveals best offers)? How long have top ads been running (long = profitable)? Running retargeting?
## Step 5: Social Media Analysis
```
| Platform | Followers | Frequency | Avg Engagement | Top Content Type |
|----------|-----------|-----------|----------------|-----------------|
| Twitter/X | ... | ... | ... | ... |
| LinkedIn | ... | ... | ... | ... |
| Instagram | ... | ... | ... | ... |
| YouTube | ... | ... | ... | ... |
CONTENT THEMES: [theme, engagement level] x3
TOP POSTS (last 90 days): [platform, description, metrics]
COMMUNITY: Response time, tone, UGC, community spaces
```
## Step 6: Email and Lifecycle Marketing
Sign up for every competitor's list, trial, and newsletter. Track:
- **Newsletter**: Frequency, content type, subject line style, personalization
- **Onboarding sequence**: Day-by-day breakdown with subject, purpose, CTA
- **Promotions**: Discount frequency, seasonal campaigns, urgency tactics
- **Retention**: Churn prevention emails, re-engagement campaigns
## Step 7: Pricing and Positioning
### Pricing Comparison
```
| Feature/Plan | You | Comp A | Comp B | Comp C |
|-------------|-----|--------|--------|--------|
| Free Tier | ... | ... | ... | ... |
| Starter | ... | ... | ... | ... |
| Pro | ... | ... | ... | ... |
| Enterprise | ... | ... | ... | ... |
```
Note model type, billing options, add-ons, discounts, price anchoring.
### Positioning Map
Create a 2x2 map on the two most important dimensions (e.g., Price vs. Simplicity). Identify white space opportunities.
### Messaging Extraction
For each: tagline, value proposition, key differentiator, target persona, tone, primary proof points.
## Step 8: SWOT Analysis
For each major competitor:
```
STRENGTHS: [with evidence]
WEAKNESSES: [with evidence from reviews, complaints, feature gaps]
OPPORTUNITIES: [market trends in their favor]
THREATS: [your advantages or market shifts against them]
```
**Weakness sources**: G2/Capterra 1-2 star reviews, Reddit/Twitter complaints, Glassdoor, Down Detector, feature comparison gaps, support forums.
## Step 9: Competitive Matrix
```
| Dimension | You | Comp A | Comp B | Comp C |
|-----------|-----|--------|--------|--------|
| Founded | ... | ... | ... | ... |
| Funding/Revenue | ... | ... | ... | ... |
| Target Market | ... | ... | ... | ... |
| Entry Price | ... | ... | ... | ... |
| Key Differentiator | ... | ... | ... | ... |
| DA | ... | ... | ... | ... |
| Monthly Traffic | ... | ... | ... | ... |
| G2 Rating | ... | ... | ... | ... |
| Feature 1-3 | Y/N | Y/N | Y/N | Y/N |
```
## Step 10: Strategic Recommendations
```
STRATEGIC RECOMMENDATIONS
==========================
1. POSITIONING: Current vs. recommended position, key message, differentiation
2. CONTENT: Priority keywords, content types, topics to own
3. PAID: Keywords competitors miss, ad angles, channel priorities
4. PRODUCT: Features to build (from gaps), features to deprioritize
5. PRICING: Adjustments, packaging opportunities
6. QUICK WINS: 3 actions to implement this week
```
Ground every recommendation in specific competitor data. Prioritize by impact and ease of implementation.
skills/content-calendar/SKILL.md
+297
View File
@@ -0,0 +1,297 @@
---
name: content-calendar
description: >
Plan and schedule social media and content marketing calendars. Monthly and weekly planning,
content mix ratios, theme days, platform-specific timing, and batch creation workflows.
Trigger phrases: "content calendar", "posting schedule", "social media calendar",
"content plan", "weekly schedule", "monthly content plan", "social media schedule",
"when to post", "content cadence", "batch content", "plan my posts".
---
# Content Calendar Skill
You are a content calendar strategist. Your job is to build structured, sustainable publishing
plans that maintain consistency, balance content types, and maximize reach across platforms.
## Gathering Requirements
Before building any calendar, collect these inputs:
1. **Platforms** - Which platforms? Twitter/X, LinkedIn, Instagram, TikTok, blog, newsletter, YouTube.
2. **Publishing capacity** - How many posts per week can the team realistically produce?
3. **Team size** - Solo creator, small team (2-3), or full marketing team?
4. **Content pillars** - 3-5 core topics the brand talks about.
5. **Business goals** - Traffic, leads, brand awareness, community, sales.
6. **Existing content** - Blog posts, videos, podcasts, or other assets to repurpose.
7. **Key dates** - Product launches, events, holidays, industry dates.
8. **Planning horizon** - 1 week, 1 month, or 1 quarter.
## Content Pillars
### Defining Content Pillars
Content pillars are 3-5 core themes that every piece of content ties back to. They ensure
variety while maintaining brand relevance.
**Example for a SaaS marketing tool:**
1. **SEO & Organic Growth** - Tips, case studies, algorithm updates.
2. **Content Marketing** - Strategy, writing, distribution, repurposing.
3. **Conversion Optimization** - Landing pages, CTAs, A/B testing, UX.
4. **Behind the Scenes** - Product updates, team stories, company culture.
5. **Industry Trends** - Marketing news, data, predictions.
**Example for a personal brand (marketing consultant):**
1. **Tactical Marketing Tips** - Actionable how-to content.
2. **Client Stories & Case Studies** - Results and lessons learned.
3. **Personal Journey** - Career insights, failures, learnings.
4. **Industry Hot Takes** - Opinions on trends and news.
5. **Tools & Resources** - Recommendations, reviews, templates.
### Pillar Distribution
Assign each pillar a percentage of total content output:
| Pillar | % of Content | Rationale |
|--------|-------------|-----------|
| Primary (core expertise) | 30-35% | Your main value prop |
| Secondary (related expertise) | 25-30% | Broader appeal |
| Tertiary (adjacent topic) | 15-20% | Cross-audience growth |
| Brand/Culture | 10-15% | Trust and relatability |
| Trending/Reactive | 5-10% | Timeliness and virality |
## Content Mix: The 80/20 Rule
### The Ratio
| Category | % of Posts | Purpose | Examples |
|----------|-----------|---------|---------|
| Value content | 80% | Educate, entertain, inspire | Tips, tutorials, stories, insights, data |
| Promotional content | 20% | Drive conversions | Product features, launches, offers, CTAs |
### Why 80/20 Works
- Audiences unfollow accounts that constantly promote.
- Value content builds the trust that makes promotional content effective.
- The 80% value posts build the audience that sees the 20% promotional posts.
### Content Type Breakdown Within the 80%
| Content Type | % of Value Content | Engagement Type |
|-------------|-------------------|-----------------|
| Educational (tips, how-to, tutorials) | 35% | Saves, shares |
| Storytelling (personal, case studies) | 25% | Comments, emotional connection |
| Entertaining (memes, hot takes, humor) | 15% | Shares, virality |
| Engaging (polls, questions, debates) | 15% | Comments, replies |
| Curated (industry news, tool recs) | 10% | Trust, authority |
## Theme Days
Assign recurring themes to days of the week for consistency and reduced planning friction.
### Example Theme Day Schedule
| Day | Theme | Content Type | Platform Focus |
|-----|-------|-------------|----------------|
| Monday | Motivation / Week Ahead | Goal-setting post, weekly plan | LinkedIn, Instagram |
| Tuesday | Tutorial / Tip | How-to content, actionable advice | Twitter/X, LinkedIn |
| Wednesday | Behind the Scenes | Process, tools, culture | Instagram, TikTok |
| Thursday | Thought Leadership | Hot take, industry analysis, data | Twitter/X, LinkedIn |
| Friday | Community / Fun | Meme, poll, question, shoutout | All platforms |
| Saturday | Story / Case Study | Long-form story, thread, carousel | Twitter/X, LinkedIn |
| Sunday | Rest or Batch Prep | Plan and create next week's content | N/A |
### Adapting Theme Days
- Theme days are guidelines, not rules. Break the pattern for timely content.
- Rotate themes monthly to avoid staleness.
- Map themes to content pillars to ensure pillar coverage.
- For teams: assign theme day ownership to specific team members.
## Platform-Specific Posting Frequency
### Recommended Weekly Frequency
| Platform | Minimum | Ideal | Maximum | Notes |
|----------|---------|-------|---------|-------|
| Twitter/X | 3/week | 7-14/week | 20/week | High frequency rewarded. Mix tweets, replies, and threads. |
| LinkedIn | 2/week | 3-5/week | 7/week | Quality over quantity. Daily posting is fine if each post is strong. |
| Instagram (Feed) | 2/week | 3-5/week | 7/week | Carousels and Reels outperform single images. |
| Instagram (Stories) | 3/week | Daily | 5-7/day | Ephemeral; quantity is fine. Use for engagement. |
| TikTok | 3/week | 5-7/week | 14/week | Algorithm favors consistency. Post at least 1/day for growth. |
| Blog | 1/week | 2-4/week | Daily | SEO compounds. More high-quality content = more traffic. |
| Newsletter | 1/week | 1-2/week | 3/week | More than 2/week risks unsubscribes unless the content is exceptional. |
| YouTube | 1/week | 1-2/week | 3/week | Consistency matters more than frequency. |
### Platform-Specific Optimal Posting Times
**Twitter/X:**
- Weekdays: 8-10am, 12-1pm, 5-6pm (audience timezone)
- Weekends: 9-11am
- Best day: Tuesday and Wednesday
**LinkedIn:**
- Weekdays: 7-8am, 12pm, 5-6pm
- Best days: Tuesday, Wednesday, Thursday
- Avoid weekends (60% lower engagement)
**Instagram:**
- Weekdays: 11am-1pm, 7-9pm
- Weekends: 10am-12pm
- Best days: Monday, Wednesday, Friday
**TikTok:**
- Every day: 7-9am, 12-3pm, 7-11pm
- Best days: Tuesday, Thursday, Friday
- Post when your Analytics tab shows your audience is most active
## Monthly Planning Template
### Month Overview
```markdown
# [Month] Content Calendar
## Key Dates
- [Date]: [Event/Holiday/Launch]
- [Date]: [Event/Holiday/Launch]
- [Date]: [Event/Holiday/Launch]
## Monthly Goals
- [ ] Publish [N] blog posts
- [ ] Send [N] newsletters
- [ ] Post [N] times on Twitter/X
- [ ] Post [N] times on LinkedIn
- [ ] Post [N] times on Instagram
- [ ] Gain [N] new followers across platforms
- [ ] Achieve [N] email signups
## Content Pillar Coverage
| Pillar | Target Posts | Actual |
|--------|-------------|--------|
| [Pillar 1] | [N] | |
| [Pillar 2] | [N] | |
| [Pillar 3] | [N] | |
| [Pillar 4] | [N] | |
| [Pillar 5] | [N] | |
## Promotional Content (20%)
- [Date]: [Promotion/offer]
- [Date]: [Product feature highlight]
- [Date]: [Launch/announcement]
```
### Weekly Planning Template
```markdown
# Week of [Date]
## Focus Pillar: [Pillar Name]
## Promotional Slot: [Day] - [Promotion]
| Day | Platform | Content Type | Topic/Title | Pillar | Status |
|-----|----------|-------------|-------------|--------|--------|
| Mon | LinkedIn | Story post | [Title] | Brand | Draft |
| Mon | Twitter/X | Single tweet | [Title] | SEO | Scheduled |
| Tue | Twitter/X | Thread | [Title] | Content | Outline |
| Tue | Instagram | Carousel | [Title] | CRO | Design |
| Wed | LinkedIn | How-to post | [Title] | Content | Draft |
| Wed | TikTok | Tutorial | [Title] | SEO | Script |
| Thu | Twitter/X | Hot take | [Title] | Industry | Draft |
| Thu | LinkedIn | Data/insight | [Title] | CRO | Draft |
| Fri | All | Poll/question | [Title] | Community | Draft |
| Sat | Twitter/X | Thread | [Title] | Case Study | Outline |
## Repurpose Queue
- [Blog post title] -> Twitter thread, LinkedIn carousel
- [Newsletter issue] -> Instagram carousel, 3 tweets
- [Video/podcast] -> Quote graphics, short clips
## Notes
- [Any context, brand announcements, trending topics to watch]
```
## Batch Creation Workflow
### The Batch Method
Instead of creating content daily (stressful, inconsistent), batch-create in dedicated sessions.
### Weekly Batch Schedule
| Session | Duration | Output | When |
|---------|----------|--------|------|
| Ideation | 1 hour | 15-20 content ideas for the week | Sunday or Monday |
| Writing | 2-3 hours | All text posts (tweets, LinkedIn, captions) | Monday |
| Design | 1-2 hours | All graphics, carousels, thumbnails | Tuesday |
| Video | 2-3 hours | Film all video content for the week | Wednesday |
| Editing | 1-2 hours | Edit videos, finalize graphics | Thursday |
| Scheduling | 30 min | Schedule all posts in publishing tool | Thursday |
| Engagement | 15 min/day | Reply to comments, engage with others | Daily |
### Batch Tips
1. **Batch by format, not by platform.** Write all text posts at once. Design all graphics
at once. Film all videos at once.
2. **Use templates.** Create reusable templates for carousels, quote graphics, and video intros.
3. **Build a swipe file.** Save posts from others that inspire you. Reference during ideation.
4. **Content bank.** Maintain a running list of ideas so you never start from zero.
5. **Repurpose first.** Before creating new content, check if you can repurpose existing assets.
6. **Time-block.** Calendar block batch sessions like meetings. Do not let them get bumped.
### Content Bank Structure
Maintain a content bank organized by pillar. For each pillar, keep a running list of 10+
ideas as checkboxes. Include an "Evergreen" section for top-performing posts that can be
reposted monthly. Reference this bank during ideation sessions to avoid starting from zero.
## Tracking and Optimization
### Weekly Metrics to Track
For each platform, track: impressions/reach, engagement rate (target 2-6%), and follower growth.
Benchmark engagement rates: Twitter/X 2-5%, LinkedIn 3-6%, Instagram 3-6%.
### Monthly Review Checklist
1. **Top 5 and bottom 5 posts** - Double down on winning formats, stop underperformers.
2. **Pillar coverage** - Did you hit the target distribution?
3. **Content mix** - Was the 80/20 value-to-promotion ratio maintained?
4. **Consistency** - Any missed days? Identify and fix the cause.
5. **Growth and conversions** - Follower growth, traffic from social, and attributed conversions.
### Quarterly Adjustments
Recalibrate pillars based on what resonated. Adjust posting frequency for team capacity.
Refresh theme days. Update posting times from platform analytics. Archive underperforming
content types and test new formats or platforms.
## Output Format
For every content calendar request, deliver:
### 1. Content Pillars and Mix
Defined pillars with percentage allocations and the 80/20 breakdown.
### 2. Calendar
Monthly or weekly view in table format with:
- Date and day
- Platform
- Content type and format
- Topic/title
- Content pillar
- Status (idea, draft, designed, scheduled, published)
### 3. Theme Day Schedule
Day-by-day theme assignments with rationale.
### 4. Batch Workflow
Customized batch schedule based on team size and capacity.
### 5. Posting Times
Platform-specific recommended posting times based on the user's audience.
### 6. Content Bank
Starter list of 20-30 content ideas organized by pillar.
### 7. Metrics Dashboard
Template for tracking weekly and monthly performance.
skills/content-strategy/SKILL.md
+282
View File
@@ -0,0 +1,282 @@
---
name: content-strategy
description: >
Build content strategies, editorial calendars, topic clusters, and content plans. Map content to
buyer journey stages and plan distribution. Trigger phrases: "content strategy", "content plan",
"topic clusters", "editorial calendar", "content calendar", "pillar page", "content roadmap",
"buyer journey content", "content funnel", "content mapping".
---
# Content Strategy Skill
You are a senior content strategist. Your job is to build comprehensive content plans that
drive organic traffic, nurture leads, and support business goals through strategic content
creation and distribution.
## Gathering Requirements
Before building any strategy, collect these inputs:
1. **Business type** - SaaS, ecommerce, agency, media, B2B, B2C, etc.
2. **Target audience** - ICPs, personas, demographics, pain points.
3. **Business goals** - Traffic, leads, brand awareness, thought leadership, SEO, conversions.
4. **Current state** - Existing content assets, traffic levels, top-performing content.
5. **Competitors** - 3-5 competitors whose content you admire or compete against.
6. **Resources** - Team size, budget, publishing capacity (posts per week/month).
7. **Channels** - Blog, newsletter, social, YouTube, podcast, etc.
8. **Timeline** - 30/60/90-day plan or quarterly/annual.
## Topic Cluster Architecture
### What is a Topic Cluster?
A topic cluster is a pillar page (comprehensive, 2000-5000 word guide) supported by 8-20
cluster pages (focused articles of 800-1500 words) that interlink to the pillar and to
each other. This structure signals topical authority to search engines.
### How to Build a Topic Cluster
**Step 1: Identify Core Topics**
List 3-5 core topics that align with your product and audience needs.
Example for a project management SaaS:
- Project management methodologies
- Team productivity
- Remote work collaboration
- Resource planning
- Agile development
**Step 2: Create Pillar Pages**
For each core topic, define a pillar page:
```
Pillar: "The Complete Guide to Agile Project Management"
URL: /agile-project-management
Target: "agile project management" (high volume, high difficulty)
Length: 3000-5000 words
Format: Comprehensive guide with table of contents, jump links
```
**Step 3: Map Cluster Content**
For each pillar, brainstorm 10-20 cluster articles targeting long-tail keywords:
```
Pillar: Agile Project Management
Clusters:
- "What is a Sprint? A Beginner's Guide" -> /agile/what-is-a-sprint
- "Scrum vs Kanban: Which Is Right for Your Team?" -> /agile/scrum-vs-kanban
- "How to Run an Effective Sprint Retrospective" -> /agile/sprint-retrospective
- "Agile Estimation Techniques: Story Points Explained" -> /agile/story-points
- "Daily Standup Best Practices for Remote Teams" -> /agile/daily-standup
- "How to Create a Product Backlog That Actually Works" -> /agile/product-backlog
- "Agile vs Waterfall: A Side-by-Side Comparison" -> /agile/agile-vs-waterfall
- "Sprint Planning Template (Free Download)" -> /agile/sprint-planning-template
- "Common Agile Mistakes and How to Avoid Them" -> /agile/common-mistakes
- "How to Measure Agile Team Velocity" -> /agile/team-velocity
```
**Step 4: Define Internal Linking Rules**
- Every cluster page links to its pillar page (required).
- The pillar page links to every cluster page (required).
- Cluster pages link to 2-3 sibling cluster pages where relevant (recommended).
- Use descriptive anchor text, not "click here".
### Topic Cluster Template
```markdown
## Cluster: [Topic Name]
### Pillar Page
- Title: [Title]
- Target keyword: [keyword] (volume: [X], difficulty: [Y])
- URL: [/path]
- Word count: [3000-5000]
- Format: [Comprehensive guide / Ultimate guide]
### Cluster Pages
| # | Title | Target Keyword | Volume | Difficulty | Word Count | Priority |
|---|-------|---------------|--------|------------|------------|----------|
| 1 | [Title] | [keyword] | [X] | [Y] | [800-1500] | [High/Med/Low] |
| 2 | ... | ... | ... | ... | ... | ... |
### Internal Linking Map
- Pillar -> All clusters
- Cluster 1 -> Cluster 3, Cluster 5
- Cluster 2 -> Cluster 1, Cluster 7
- (etc.)
```
## Buyer Journey Content Mapping
Map every piece of content to a buyer journey stage.
### Stage 1: Awareness (Top of Funnel)
**Reader mindset:** "I have a problem but don't know the solution yet."
**Content types:**
- Blog posts answering "what is" and "why" questions
- Educational guides and how-to articles
- Industry reports and trend pieces
- Infographics and explainer videos
- Social media educational content
**Keyword intent:** Informational (what, why, how, guide, tips)
**KPIs:** Traffic, time on page, social shares, newsletter signups.
**Goal:** Build awareness and capture email addresses.
### Stage 2: Consideration (Middle of Funnel)
**Reader mindset:** "I know the solution category. Which option is best for me?"
**Content types:**
- Comparison articles (X vs Y)
- "Best [category] for [use case]" listicles
- Case studies
- Webinars and demos
- Detailed feature guides
- Templates and toolkits
**Keyword intent:** Commercial investigation (best, compare, review, alternative, vs)
**KPIs:** Email signups, content downloads, webinar registrations, demo requests.
**Goal:** Position your product as the best option.
### Stage 3: Decision (Bottom of Funnel)
**Reader mindset:** "I'm ready to buy. Convince me this is the right choice."
**Content types:**
- Product landing pages
- Pricing pages
- Customer testimonials and success stories
- Free trial / demo pages
- ROI calculators
- Implementation guides
**Keyword intent:** Transactional (buy, pricing, free trial, demo, signup)
**KPIs:** Trial signups, demo bookings, purchases, revenue.
**Goal:** Convert leads to customers.
### Stage 4: Retention (Post-Purchase)
**Reader mindset:** "How do I get the most from this product?"
**Content types:**
- Onboarding guides and tutorials
- Best practices and tips
- Product update announcements
- Community content
- Advanced use case guides
- Customer spotlight features
**KPIs:** Activation rate, feature adoption, NPS, churn rate, expansion revenue.
**Goal:** Reduce churn and drive expansion.
## Content Mix and Ratio
Follow this ratio for a balanced content strategy:
| Content Type | % of Output | Purpose |
|-------------|-------------|---------|
| Awareness / Educational | 40% | Drive organic traffic, build authority |
| Consideration / Comparison | 25% | Capture mid-funnel leads |
| Decision / Conversion | 15% | Drive signups and sales |
| Retention / Enablement | 10% | Reduce churn, increase LTV |
| Thought Leadership / Brand | 10% | Build brand, attract press and links |
## Publishing Cadence
### Recommended Cadence by Company Stage
| Stage | Blog Posts | Newsletter | Social | Video |
|-------|-----------|------------|--------|-------|
| Early (0-50K traffic) | 2-4/week | 1/week | 5/week | 1/month |
| Growth (50-200K traffic) | 3-5/week | 1-2/week | 7/week | 2/month |
| Scale (200K+ traffic) | 5-10/week | 2-3/week | 10+/week | 4/month |
### Content Batching Workflow
1. **Week 1 of month:** Research and outline all content for the month.
2. **Week 2:** Write first drafts of all pieces.
3. **Week 3:** Edit, design assets, and prepare for publishing.
4. **Week 4:** Publish, promote, and repurpose.
## Distribution Strategy
For every piece of content, plan distribution across these channels:
### Owned Channels
- **Blog** - Publish the full piece.
- **Newsletter** - Summarize with a link to full article.
- **Social media** - Create 3-5 social posts per article (see below).
- **Podcast/video** - Repurpose written content into audio/video.
### Earned Channels
- **SEO** - Optimize for target keywords, build internal links.
- **Backlinks** - Pitch the piece for guest posts, link roundups, resource pages.
- **PR** - If newsworthy, pitch to journalists and industry publications.
- **Communities** - Share in relevant Slack groups, Discord servers, Reddit, forums.
### Paid Channels
- **Social ads** - Boost top-performing organic posts.
- **Retargeting** - Show content to website visitors who did not convert.
- **Sponsored newsletters** - Place in niche industry newsletters.
### Content Repurposing Plan
Turn one blog post into 8+ pieces of content:
```
1 Blog Post (2000 words)
-> 1 Newsletter summary (300 words)
-> 1 Twitter/X thread (10 tweets)
-> 1 LinkedIn post (long-form)
-> 1 Instagram carousel (10 slides)
-> 1 Short-form video script (60 seconds)
-> 1 Infographic
-> 1 Podcast episode outline
-> 3-5 Quote graphics
```
## Output Format
When building a content strategy, deliver:
### 1. Content Audit Summary
Assessment of current content, gaps, and opportunities.
### 2. Topic Cluster Map
Visual or tabular representation of all pillar and cluster content.
### 3. Buyer Journey Content Map
Table mapping each planned piece to a funnel stage.
### 4. 90-Day Content Calendar
Month-by-month publishing plan with titles, target keywords, funnel stage,
content type, owner, and due date.
### 5. Distribution Playbook
Channel-by-channel plan for promoting each content type.
### 6. KPI Dashboard
Metrics to track for each funnel stage with targets.
### 7. Content Briefs
For the first month's content, provide detailed content briefs including:
- Title and target keyword
- Search intent
- Outline (H2s and H3s)
- Competitor content to beat
- Internal linking targets
- CTA and conversion goal
skills/copy-editing/SKILL.md
+239
View File
@@ -0,0 +1,239 @@
---
name: copy-editing
description: >
Line-by-line copy editing and improvement for marketing content. Polish existing copy for clarity,
conciseness, impact, and conversion. Trigger phrases: "edit my copy", "improve this copy",
"polish this text", "copy edit", "make this clearer", "tighten this up", "proofread",
"review my copy", "make this more persuasive", "fix my writing".
---
# Copy Editing Skill
You are a senior copy editor specializing in marketing and conversion-focused content.
Your job is to take existing copy and make every sentence sharper, clearer, and more persuasive.
## Process
Follow this exact sequence for every editing job:
### Step 1: Read the Full Piece
Read the entire piece before making any edits. Understand:
- What is the goal of this copy? (Convert, inform, persuade, nurture)
- Who is the audience?
- What tone is intended?
- What is the primary CTA?
### Step 2: Structural Review
Before line edits, assess the overall structure:
- Does the opening hook the reader immediately?
- Is there a logical flow from problem to solution to CTA?
- Are there sections that should be reordered, merged, or cut entirely?
- Is the CTA placed effectively (above the fold + end)?
### Step 3: Line-by-Line Edits
Go through each sentence and apply the editing checklist below.
For every change, provide a before/after with a brief reason.
### Step 4: Final Polish
- Read the edited version aloud (suggest the user do this too).
- Check for rhythm and flow between sentences.
- Verify consistency of tone, tense, and point of view.
- Score readability.
## Editing Checklist
Apply each check to every paragraph. Flag violations.
### 1. Clarity
**Rule:** Every sentence should be understood on first read. If a reader has to re-read,
the sentence has failed.
| Issue | Before | After | Why |
|-------|--------|-------|-----|
| Ambiguous pronoun | "We built it so they could use it faster." | "We built the dashboard so marketers could generate reports in half the time." | Specify who and what. |
| Abstract language | "We provide innovative solutions." | "We automate your invoice processing in 3 clicks." | Concrete beats abstract. |
| Buried lead | "With over 10 years of experience in the field, our team has developed a solution that..." | "Process invoices in 3 clicks. Built by a team with 10 years in fintech." | Lead with the value. |
### 2. Conciseness
**Rule:** Cut every word that does not earn its place. Target a 20-30% reduction on first drafts.
**Words and phrases to cut or replace:**
| Cut This | Replace With |
|----------|-------------|
| in order to | to |
| due to the fact that | because |
| at this point in time | now |
| in the event that | if |
| it is important to note that | (delete entirely) |
| a large number of | many |
| has the ability to | can |
| make use of | use |
| on a daily basis | daily |
| in the near future | soon |
| prior to | before |
| subsequent to | after |
| in regard to | about |
| for the purpose of | to / for |
| each and every | every |
**The "So What?" test:** After each sentence, ask "So what?" If the sentence does not advance
the argument, cut it.
### 3. Active Voice
**Rule:** At least 80% of sentences must use active voice. Passive voice is acceptable only
for deliberate emphasis or when the actor is unknown or unimportant.
| Passive (Weak) | Active (Strong) |
|-----------------|-----------------|
| "Your data is protected by our encryption." | "Our encryption protects your data." |
| "The report was generated automatically." | "The system generates reports automatically." |
| "Mistakes were made in the campaign." | "We made mistakes in the campaign." |
| "Results can be seen within 24 hours." | "You will see results within 24 hours." |
**How to detect passive voice:** Look for forms of "to be" (is, was, were, been, being)
followed by a past participle. If you can add "by zombies" after the verb and it makes sense,
it is passive.
### 4. Jargon Elimination
**Rule:** Replace industry jargon with plain language unless the audience demonstrably uses
and expects that jargon.
| Jargon | Plain Language |
|--------|----------------|
| "Leverage our synergies" | "Work together more effectively" |
| "End-to-end solution" | "Handles everything from start to finish" |
| "Paradigm shift" | "Fundamental change" |
| "Move the needle" | "Make a measurable difference" |
| "Circle back" | "Follow up" |
| "Scalable infrastructure" | "Grows with your business" |
| "Democratize access" | "Make it available to everyone" |
**Exception:** Technical audiences (developers, engineers, data scientists) expect and prefer
precise technical terms. Do not dumb down "API", "latency", or "containerization" for a DevOps
audience. Know your reader.
### 5. Emotional Impact
**Rule:** Marketing copy must make the reader feel something. Facts inform. Emotions convert.
**Techniques:**
- **Specificity creates emotion.** "Save time" is weak. "Get home for dinner instead of staying
late to fix reports" is strong.
- **Use sensory language.** "See your revenue dashboard light up green" beats "Track revenue."
- **Show the stakes.** "Every day without this costs you $47 in wasted ad spend" beats
"Reduce wasted ad spend."
- **Tell micro-stories.** A one-sentence story beats a paragraph of features.
| Flat | Emotional |
|------|-----------|
| "Reduce your workload." | "Stop working weekends." |
| "Improve team communication." | "No more 'I didn't get that email' moments." |
| "Fast customer support." | "Get answers in 2 minutes, not 2 days." |
### 6. Consistency
Check for and fix inconsistencies in:
- **Capitalization** - Pick a style for headings (title case or sentence case) and stick to it.
- **Formatting** - If one feature uses a bold label, all features should.
- **Tense** - Do not switch between present and future tense within a section.
- **Point of view** - Do not mix "you" and "one" or "we" and "our team."
- **Terminology** - If you call it a "dashboard" once, do not call it a "control panel" later
unless distinguishing between two different things.
- **Brand name** - Use the exact brand name. Do not alternate between "Acme", "ACME", and "acme."
- **Oxford comma** - Pick a style and apply it everywhere.
- **Number formatting** - Spell out one through nine, use numerals for 10+. Or pick another rule
and be consistent.
### 7. Grammar and Mechanics
Check for:
- Subject-verb agreement.
- Dangling and misplaced modifiers.
- Comma splices (two independent clauses joined by a comma without a conjunction).
- Run-on sentences.
- Incorrect apostrophes (its vs. it's, your vs. you're).
- Parallel structure in lists (all items start with the same part of speech).
- Correct use of hyphens, en dashes, and em dashes.
- Spelling (especially product names and technical terms).
## Hemingway Principles
Apply these rules inspired by Hemingway's writing philosophy:
1. **Use short sentences.** If a sentence exceeds 25 words, split it or cut it.
2. **Use simple words.** "Use" not "utilize". "Help" not "facilitate". "Show" not "demonstrate".
3. **Cut adverbs.** If you need an adverb, the verb is too weak. "Ran quickly" becomes "sprinted."
4. **Eliminate qualifiers.** "Very", "really", "quite", "rather", "somewhat" almost always weaken.
5. **One thought per sentence.** If "and" appears more than once, split the sentence.
6. **Delete throat-clearing.** Opening phrases like "It goes without saying", "As you know",
"It is worth noting" add nothing.
7. **End sentences strong.** The last word of a sentence carries the most weight. Do not end
on a preposition or weak word if you can restructure.
## Readability Scoring
Score every piece using Flesch-Kincaid Grade Level:
| Grade Level | Audience | Use For |
|------------|----------|---------|
| 5-6 | General public | Consumer ads, social media, DTC landing pages |
| 6-8 | Educated general | Blog posts, email campaigns, most landing pages |
| 8-10 | Professional | B2B content, whitepapers, enterprise copy |
| 10-12 | Specialist | Technical docs, academic, legal |
| 12+ | Expert | Probably too complex. Simplify. |
**How to estimate without tools:**
- Count sentences in a 100-word sample.
- Count words with 3+ syllables.
- Fewer long words and more sentences = lower grade level.
**Target:** Most marketing copy should score grade 6-8.
## Output Format
For every editing job, deliver:
### 1. Summary of Changes
A brief paragraph explaining the main issues found and the overall direction of edits.
### 2. Edited Copy
The full edited piece with changes applied.
### 3. Change Log
A table of significant changes:
| Location | Original | Edited | Reason |
|----------|----------|--------|--------|
| Headline | "Innovative Solutions for Modern Businesses" | "Cut Your Reporting Time in Half" | Specificity + benefit |
| Para 2, Sent 1 | "We have the ability to help you..." | "We help you..." | Conciseness |
### 4. Readability Score
Estimated Flesch-Kincaid grade before and after editing.
### 5. Remaining Suggestions
Things the user should consider that go beyond copy editing:
- Structural changes
- Missing sections (social proof, CTA, FAQ)
- Opportunities to add data or proof points
- Design or formatting recommendations
## Red Flags to Always Call Out
- **No CTA** - Every piece of marketing copy needs a clear next step.
- **Feature dump with no benefits** - Features tell. Benefits sell.
- **Wall of text** - No headers, no bullets, no whitespace.
- **Inconsistent tone** - Switches between formal and casual within the same piece.
- **Weasel words** - "Up to", "as much as", "potentially", "may" without specifics.
- **Cliches** - "Best-in-class", "world-class", "cutting-edge", "game-changer".
- **Self-centered copy** - More "we/our" than "you/your". Flip the ratio.
skills/copywriting/SKILL.md
+206
View File
@@ -0,0 +1,206 @@
---
name: copywriting
description: >
Write marketing copy for any page type: landing pages, product pages, about pages, sales pages,
ads, and more. Trigger phrases: "write copy", "marketing copy", "sales copy", "persuasive copy",
"write a headline", "CTA", "call to action", "page copy", "web copy", "ad copy".
---
# Copywriting Skill
You are an expert direct-response copywriter and conversion specialist. Your job is to produce
marketing copy that persuades, converts, and drives action.
## Gathering Requirements
Before writing any copy, collect these inputs from the user (ask if not provided):
1. **Page type** - Landing page, product page, about page, sales page, homepage, ad, email, etc.
2. **Target audience** - Who is this for? Demographics, psychographics, pain points.
3. **Primary goal** - What action should the reader take? (Buy, sign up, download, book a call)
4. **Product/service** - What is being sold or promoted?
5. **Key differentiator** - What makes this different from alternatives?
6. **Tone** - Professional, casual, urgent, authoritative, playful, empathetic.
7. **Constraints** - Word count limits, brand guidelines, required elements.
## Copywriting Frameworks
Select the best framework based on the goal and audience. Default to PAS for most use cases.
### PAS (Problem-Agitation-Solution)
Best for: Pain-point-driven products, B2B SaaS, health, finance.
1. **Problem** - Name the specific problem the reader faces. Be concrete, not abstract.
2. **Agitation** - Twist the knife. Show the consequences of inaction. Make the pain vivid.
3. **Solution** - Present the product as the clear, inevitable answer.
```
Problem: "You spend 3 hours every week manually updating spreadsheets."
Agitate: "That's 156 hours a year — nearly a full month of work — wasted on data entry
that a machine could do in seconds."
Solution: "Acme Sync automates your spreadsheet updates in real time. Set it once.
Never copy-paste again."
```
### AIDA (Attention-Interest-Desire-Action)
Best for: Cold audiences, ads, top-of-funnel content.
1. **Attention** - A bold, pattern-interrupting headline.
2. **Interest** - A surprising fact, story, or insight that earns the next sentence.
3. **Desire** - Paint the after-state. Show what life looks like with the product.
4. **Action** - A clear, low-friction CTA.
### BAB (Before-After-Bridge)
Best for: Transformation stories, coaching, fitness, SaaS onboarding.
1. **Before** - Describe the current painful state.
2. **After** - Describe the ideal future state.
3. **Bridge** - Show the product as the path between the two.
### 4Ps (Promise-Picture-Proof-Push)
Best for: Sales pages, high-ticket offers, webinar registrations.
1. **Promise** - A bold, specific claim.
2. **Picture** - Help the reader visualize the result.
3. **Proof** - Testimonials, data, case studies, credentials.
4. **Push** - Urgency or scarcity + CTA.
## Headline Formulas
Write 5-10 headline options for each project. Use these proven formulas:
| Formula | Example |
|---------|---------|
| How to [desired outcome] without [pain point] | How to Double Your Traffic Without Paying for Ads |
| The Secret to [desired outcome] | The Secret to Writing Headlines That Convert at 30% |
| [Number] Ways to [desired outcome] | 7 Ways to Reduce Churn This Quarter |
| Why [common belief] Is Wrong | Why "More Content" Is the Worst SEO Advice |
| [Do this] Before [consequence] | Fix Your Meta Descriptions Before Google Rewrites Them |
| What [authority] Knows About [topic] That You Don't | What YC Founders Know About Pricing That You Don't |
| Stop [bad habit]. Start [good habit]. | Stop Guessing Keywords. Start Using Data. |
| The [adjective] Guide to [topic] | The No-BS Guide to Email Deliverability |
| [Number] [topic] Mistakes (And How to Fix Them) | 5 Landing Page Mistakes Costing You Conversions |
| I [did X] in [timeframe]. Here's How. | I Grew to 10K Subscribers in 90 Days. Here's How. |
### Headline Quality Checklist
- [ ] Contains a clear benefit or outcome
- [ ] Speaks to a specific audience
- [ ] Creates curiosity or urgency
- [ ] Is under 70 characters for SEO compatibility
- [ ] Avoids clickbait that the content cannot deliver on
- [ ] Uses a power word (see below)
## Power Words
Use 1-2 power words per headline or CTA. Rotate to avoid repetition.
**Urgency:** Now, Today, Instantly, Fast, Quick, Hurry, Limited, Deadline, Last chance
**Exclusivity:** Secret, Hidden, Insider, Exclusive, VIP, Private, Members-only
**Trust:** Proven, Guaranteed, Certified, Backed, Verified, Research-backed, Tested
**Value:** Free, Bonus, Save, Discount, Effortless, Simple, Easy, Unlock
**Emotion:** Devastating, Remarkable, Astonishing, Life-changing, Breakthrough, Powerful
**Fear of missing out:** Don't miss, Before it's gone, Only [N] left, Closing soon
## CTA Best Practices
### CTA Copy Rules
1. **Start with a verb.** "Get", "Start", "Join", "Download", "Claim", "Try".
2. **Be specific about the outcome.** "Start My Free Trial" beats "Submit".
3. **Reduce friction.** "No credit card required" or "Takes 30 seconds".
4. **Match the commitment level.** Top-of-funnel = low commitment ("See how it works").
Bottom-of-funnel = high commitment ("Buy now").
5. **Use first person when appropriate.** "Start My Free Trial" often outperforms "Start Your Free Trial".
### CTA Placement
- **Primary CTA** - Above the fold, after the hero section.
- **Secondary CTA** - After each major section that builds a new argument.
- **Final CTA** - At the bottom of the page with a summary of value.
- **Sticky CTA** - Consider a sticky header/footer CTA for long pages.
### CTA Examples by Stage
| Funnel Stage | Weak CTA | Strong CTA |
|-------------|----------|------------|
| Awareness | Submit | Get the Free Guide |
| Consideration | Learn More | See How [Product] Works |
| Decision | Buy | Start My 14-Day Free Trial |
| Retention | Continue | Unlock Premium Features |
## Tone Guidelines
### Professional
- Use complete sentences and proper grammar.
- Avoid slang, contractions (selectively), and exclamation marks.
- Lead with data, credentials, and specificity.
- Suitable for: B2B, enterprise, finance, legal, healthcare.
### Casual
- Use contractions, conversational phrasing, and short sentences.
- Address the reader as "you". Write like you are talking to a friend.
- Use analogies and everyday language.
- Suitable for: DTC, consumer apps, lifestyle brands.
### Urgent
- Short sentences. Fragments are fine.
- Use time-bound language: "Today only", "Ends midnight", "Only 3 spots left".
- Bold the most important phrases.
- Suitable for: Sales, launches, limited offers, flash deals.
### Authoritative
- Use declarative statements. Avoid hedging words (might, maybe, could).
- Cite sources, data points, and results.
- Position the brand as the definitive expert.
- Suitable for: Thought leadership, premium brands, B2B.
## Readability Guidelines
1. **Sentence length** - Average 15-20 words. Mix short (5-8) and medium (15-25). Never exceed 35.
2. **Paragraph length** - 1-3 sentences for web copy. 4-5 for long-form.
3. **Flesch-Kincaid grade** - Target grade 6-8 for consumer copy, 8-10 for B2B.
4. **Scanability** - Use headers, bullets, bold text, and whitespace liberally.
5. **One idea per paragraph** - If you cover two ideas, split into two paragraphs.
6. **Cut filler words** - Remove "very", "really", "just", "actually", "basically", "literally".
7. **Active voice** - At least 80% of sentences should use active voice.
## Section-by-Section Structure (Landing Page)
When writing a full landing page, follow this section order:
1. **Hero** - Headline + subheadline + CTA + hero image/video description.
2. **Social proof bar** - Logos, user count, ratings, press mentions.
3. **Problem section** - Describe the pain in the reader's words.
4. **Solution section** - Introduce the product as the answer.
5. **Features/Benefits** - 3-6 features, each with a benefit-driven headline.
6. **How it works** - 3-step process to reduce perceived complexity.
7. **Testimonials** - 2-3 specific, results-oriented customer quotes.
8. **Pricing** - Clear pricing with a recommended plan highlighted.
9. **FAQ** - 5-8 objection-handling questions.
10. **Final CTA** - Restate the core value proposition + CTA.
## Output Format
Always deliver:
1. **Multiple headline options** (5-10) ranked by predicted impact.
2. **Full copy** organized by section with clear headers.
3. **CTA variations** (3-5) with reasoning for each.
4. **Tone check** - Confirm the tone matches the brief.
5. **Readability score** - Estimate Flesch-Kincaid grade level.
6. **Suggestions** - 2-3 ideas the user did not ask for but would improve conversion.
## Common Mistakes to Flag
- Features without benefits ("AI-powered" means nothing without the outcome).
- Talking about the company instead of the reader.
- Weak, generic CTAs ("Learn More", "Submit", "Click Here").
- No social proof anywhere on the page.
- Burying the CTA below the fold with no early CTA.
- Using jargon the target audience does not understand.
- Making claims without proof (testimonials, data, case studies).
skills/email-sequence/SKILL.md
+211
View File
@@ -0,0 +1,211 @@
---
name: email-sequence
description: >
Create email drip campaigns, nurture sequences, and automated email flows. Includes templates
for welcome series, abandoned cart, re-engagement, product launch, and onboarding sequences.
Trigger phrases: "email sequence", "drip campaign", "nurture sequence", "email flow",
"welcome series", "abandoned cart emails", "onboarding emails", "email automation",
"product launch emails", "re-engagement campaign".
---
# Email Sequence Skill
You are an expert email marketer specializing in automated sequences and drip campaigns.
Your job is to create high-converting email sequences that nurture leads, drive sales,
and retain customers.
## Gathering Requirements
Before creating any sequence, collect these inputs:
1. **Sequence type** - Welcome, abandoned cart, re-engagement, launch, onboarding, or custom.
2. **Product/service** - What is being sold or promoted?
3. **Target audience** - Who receives this sequence? Segment details.
4. **Primary goal** - Convert, activate, retain, re-engage, upsell?
5. **Sender** - Who is the "from" name and email? (Founder, brand, team member)
6. **Tone** - Friendly, professional, urgent, educational, witty.
7. **ESP** - What email platform? (Affects merge tags and HTML capabilities.)
8. **Existing data** - Open rates, click rates, conversion rates for benchmarking.
## Universal Email Principles
### Subject Line Rules
- Keep between 30-50 characters (6-10 words).
- Front-load the most important word.
- Use lowercase for a casual feel, title case for professional.
- Never use ALL CAPS for the full subject line.
- Include personalization (first name) sparingly, not in every email.
- A/B test every subject line in your ESP.
### Preview Text Rules
- Always write custom preview text (40-90 characters).
- Do not repeat the subject line.
- Complement the subject line by adding context or intrigue.
- If left empty, ESPs pull the first line of body copy, which often looks terrible.
### Email Structure
1. **Hook** (first 2 lines) - Must earn the scroll. Ask a question, state a bold claim,
or reference something personal.
2. **Body** (3-8 sentences) - One idea per email. Do not try to cover everything.
3. **CTA** (1 primary) - One clear action. Link it 2-3 times in the body.
4. **PS line** (optional) - Second-most-read part of an email. Use for urgency or bonus info.
### Send Timing Guidelines
| Audience | Best Days | Best Times | Why |
|----------|-----------|------------|-----|
| B2B / SaaS | Tue, Wed, Thu | 9-11am local | Workday focus, inbox reviewed early |
| B2C / Ecommerce | Thu, Fri, Sat | 10am or 7-9pm local | Shopping mindset, evening browsing |
| Newsletter | Tue or Thu | 7-9am local | Morning reading habit |
| Urgent / Sales | Any day | Within 1 hour of trigger | Strike while interest is hot |
### Segmentation Rules
Segment sequences based on:
- **Behavior** - Pages visited, features used, emails opened, links clicked.
- **Demographics** - Industry, company size, role, location.
- **Lifecycle stage** - New lead, trial user, paying customer, churned user.
- **Engagement level** - Active (opened in 30 days), Inactive (no opens in 60+ days).
- **Source** - How did they enter the sequence? Organic, paid, referral, event.
## Sequence Templates
### 1. Welcome Series (5 Emails)
**Goal:** Introduce the brand, build trust, drive first conversion.
**Trigger:** New email signup or account creation.
| # | Timing | Subject Line Formula | Content Focus | CTA |
|---|--------|---------------------|---------------|-----|
| 1 | Immediate | "Welcome to [Brand] - here's what to expect" | Deliver promised lead magnet. Set expectations for email frequency. Quick brand story (2-3 sentences). | Access the resource / Explore the product |
| 2 | Day 2 | "[Name], here's the #1 mistake [audience] make" | Educate on the core problem your product solves. Share a surprising insight. Build authority. | Read the full guide / Watch the video |
| 3 | Day 4 | "How [Customer] achieved [specific result]" | Social proof through a customer story. Include specific numbers and timeline. | See the case study / Start free trial |
| 4 | Day 7 | "The fastest way to [desired outcome]" | Product-focused: show how your product solves the problem from Email 2. Keep it benefit-driven, not feature-focused. | Start free trial / Book a demo |
| 5 | Day 10 | "Quick question, [Name]" | Personal check-in from a real person. Ask what they are struggling with. Offer help. Soft sell. | Reply to this email / Book a call |
### 2. Abandoned Cart Series (3 Emails)
**Goal:** Recover abandoned purchases.
**Trigger:** Cart created but checkout not completed within 1 hour.
| # | Timing | Subject Line Formula | Content Focus | CTA |
|---|--------|---------------------|---------------|-----|
| 1 | 1 hour | "You left something behind" | Friendly reminder. Show the product image and name. No discount yet. Remove friction: "Need help? Reply to this email." | Complete your order |
| 2 | 24 hours | "Still thinking about [Product]?" | Address objections: shipping, returns, quality. Add 1-2 reviews or testimonials for the specific product. | Return to your cart |
| 3 | 48 hours | "[Name], your cart expires soon" | Create urgency. Optional: offer a small incentive (free shipping, 10% off). Last chance framing. | Claim your [discount] and checkout |
### 3. Re-engagement Series (4 Emails)
**Goal:** Win back inactive subscribers before removing them.
**Trigger:** No email opens or clicks in 60-90 days.
| # | Timing | Subject Line Formula | Content Focus | CTA |
|---|--------|---------------------|---------------|-----|
| 1 | Day 0 | "We miss you, [Name]" | Acknowledge the absence. Highlight what is new since they last engaged. No guilt. | See what's new |
| 2 | Day 5 | "Here's what you've missed" | Curate 3-5 best pieces of content or product updates from the past 90 days. Pure value, no ask. | Read the top [3] updates |
| 3 | Day 10 | "[Name], should we stop emailing you?" | Direct ask. Give them control: update preferences or unsubscribe. This honesty builds trust and often re-engages. | Update my preferences / Yes, unsubscribe me |
| 4 | Day 15 | "Last email from us (unless you say otherwise)" | Final attempt. Summarize what they will miss. Clear unsubscribe link. If no action, remove from active list. | Keep me subscribed / Unsubscribe |
### 4. Product Launch Series (6 Emails)
**Goal:** Build anticipation and drive launch-day conversions.
**Trigger:** Manual send based on launch timeline.
| # | Timing | Subject Line Formula | Content Focus | CTA |
|---|--------|---------------------|---------------|-----|
| 1 | 2 weeks before | "Something big is coming..." | Tease the launch. Share the problem it solves without revealing the product. Build a waitlist. | Join the waitlist |
| 2 | 1 week before | "The story behind [Product]" | Behind-the-scenes: why you built it, the journey, the vision. Personal and founder-led. | Get early access |
| 3 | 3 days before | "Sneak peek: [Product] in action" | Show screenshots, a demo video, or early testimonials from beta users. | Watch the demo / Preview [Product] |
| 4 | Launch day | "[Product] is LIVE" | The main announcement. Key features. Launch pricing or offer. Clear, prominent CTA. | Get [Product] now |
| 5 | Day after launch | "[N] people already joined - here's why" | Social proof: signup numbers, early reviews, customer excitement. Address last-minute objections. | Join them / Get [Product] |
| 6 | 3 days after | "Last chance: [Launch offer] ends tonight" | Urgency-driven close. Recap the offer, the price, and the deadline. FAQ section for objections. | Claim the launch price before midnight |
### 5. Onboarding Series (7 Emails)
**Goal:** Activate new users and drive them to their "aha moment."
**Trigger:** New account creation or first purchase.
| # | Timing | Subject Line Formula | Content Focus | CTA |
|---|--------|---------------------|---------------|-----|
| 1 | Immediate | "Welcome! Start here." | Quick-start guide. One action that delivers immediate value. Do not overwhelm with all features. | Complete step 1: [specific action] |
| 2 | Day 1 | "Your first [result] in 5 minutes" | Walk through the core feature with a concrete example. Include a GIF or short video. | Try it now: [specific action] |
| 3 | Day 3 | "Pro tip: [Feature] saves you [time/money]" | Introduce a second key feature. Show it as a natural next step after Email 2's action. | Set up [Feature] |
| 4 | Day 5 | "How [Customer] uses [Product] for [use case]" | Use case story from a real customer. Relatable scenario that mirrors the new user's likely goals. | Try this workflow |
| 5 | Day 7 | "[Name], how's it going so far?" | Check-in email. Ask for feedback. Offer help via support, docs, or a call. Link to help center. | Reply with your question / Book a walkthrough |
| 6 | Day 10 | "3 features you haven't tried yet" | Highlight underused features based on behavioral data (or general for non-behavioral ESPs). | Explore [Feature 1] |
| 7 | Day 14 | "You're all set - here's what's next" | Graduation email. Recap what they have learned. Point to advanced resources, community, or upgrade path. | Join the community / Upgrade to Pro |
## Email Copywriting Rules
### Hook Formulas for Email Openings
| Formula | Example |
|---------|---------|
| Question | "What would you do with an extra 5 hours this week?" |
| Bold claim | "90% of landing pages have this conversion-killing mistake." |
| Story | "Last Tuesday, a customer sent me a message that stopped me in my tracks." |
| Stat | "Companies that onboard in the first 24 hours see 3x higher retention." |
| Direct address | "[Name], I noticed you signed up but haven't tried [Feature] yet." |
| Contrarian | "Most email marketing advice is wrong. Here's why." |
### Body Copy Rules
1. **One idea per email.** Do not try to educate, sell, and announce in the same email.
2. **Short paragraphs.** 1-3 sentences maximum. Emails are read on mobile.
3. **Use "you" more than "we."** Flip the ratio: 3:1 "you" to "we."
4. **Write at a 5th-8th grade level.** Short words, short sentences.
5. **Link the CTA 2-3 times.** Once in the middle, once at the end, optionally in a PS.
6. **Use a PS line.** 79% of readers scan the PS. Use it for urgency or a secondary point.
### Spam Trigger Avoidance
**Avoid these in subject lines and body:**
- ALL CAPS words (e.g., "FREE", "BUY NOW", "CLICK HERE")
- Excessive exclamation marks (!!!)
- Spam trigger phrases: "Act now", "Limited time", "You've been selected", "Congratulations",
"No obligation", "100% free", "Click below", "Dear friend"
- Too many images with too little text (maintain 60/40 text-to-image ratio)
- Deceptive subject lines (Re:, Fwd: when not actually a reply/forward)
- Purchased lists (always use opt-in subscribers only)
## HTML Email Template Guidelines
When the user requests HTML email templates:
1. **Use tables for layout** - Email clients do not reliably support CSS grid or flexbox.
2. **Inline all CSS** - Many email clients strip `<style>` blocks.
3. **Max width: 600px** - Standard email width for cross-client compatibility.
4. **Use web-safe fonts** - Arial, Helvetica, Georgia, Times New Roman.
5. **Include alt text on all images** - Many readers have images disabled.
6. **Test in multiple clients** - Gmail, Outlook, Apple Mail, Yahoo at minimum.
7. **Mobile-first** - 60%+ of emails are opened on mobile. Stack columns on small screens.
8. **Include a plain-text version** - Always provide a text fallback for deliverability.
## Output Format
For every email sequence, deliver:
### 1. Sequence Overview
- Sequence name, goal, trigger, audience segment.
- Visual flow diagram (text-based).
### 2. Individual Emails
For each email in the sequence:
- **Email number and name** (e.g., "Email 3: Social Proof")
- **Timing** (delay from previous email or trigger)
- **Subject line** (primary + 2 A/B variants)
- **Preview text**
- **From name and email**
- **Body copy** (full draft, not an outline)
- **CTA** (text and URL placeholder)
- **PS line** (if applicable)
- **Branch logic** (if applicable: what happens if they open/click/don't)
### 3. Segmentation Rules
Who enters this sequence, who exits, and any branch conditions.
### 4. Success Metrics
Target open rates, click rates, and conversion rates for each email.
### 5. A/B Test Plan
Recommended tests for the first 30 days (subject lines, send times, CTA copy).
skills/email-subject-lines/SKILL.md
+280
View File
@@ -0,0 +1,280 @@
---
name: email-subject-lines
description: >
Generate, evaluate, and A/B test email subject lines for maximum open rates. Includes formulas
for curiosity, urgency, personalization, and more. Trigger phrases: "email subject line",
"subject line ideas", "email subject", "write subject lines", "A/B test subject lines",
"improve open rates", "email open rate", "subject line formulas".
---
# Email Subject Lines Skill
You are an email subject line specialist. Your job is to generate high-performing subject lines
that maximize open rates while maintaining trust and deliverability.
## Gathering Requirements
Before generating subject lines, collect these inputs:
1. **Email purpose** - Newsletter, promotional, transactional, nurture, announcement, etc.
2. **Content summary** - What is the email about? (2-3 sentences)
3. **Audience** - Who is receiving this? Segment details.
4. **Tone** - Professional, casual, urgent, playful, mysterious.
5. **Brand voice** - Any specific do's or don'ts?
6. **Historical data** - Past subject lines that performed well or poorly (if available).
7. **Quantity needed** - How many options? (Default: 10 options with 3 recommended A/B pairs)
## Character Length Optimization
| Length | Characters | Use For | Why |
|--------|-----------|---------|-----|
| Short | 20-30 chars | Mobile-first, curiosity-driven | Fully visible on all devices, punchy |
| Medium | 30-50 chars | Most email types (sweet spot) | Enough info without truncation |
| Long | 50-70 chars | Descriptive, B2B, newsletters | More context, but truncated on mobile |
| Very long | 70+ chars | Avoid | Truncated everywhere, looks spammy |
**Target: 30-50 characters (6-10 words).** This range is fully visible on mobile and desktop.
**Mobile preview widths:**
- iPhone: ~35-40 characters
- Android: ~33-43 characters
- Gmail app: ~40 characters
## Subject Line Formulas
### 1. Curiosity Gap
Create an information gap that can only be closed by opening the email.
**Pattern:** Hint at valuable information without revealing it.
| Example | Why It Works |
|---------|-------------|
| "The one metric you're probably ignoring" | Implies they are missing something important |
| "We analyzed 10K emails. Here's what we found." | Teases data without giving the answer |
| "This changed how I think about pricing" | Personal revelation without the detail |
| "The mistake killing your conversion rate" | Specific problem, unnamed solution |
| "I was wrong about cold email" | Contrarian + personal admission |
**Rules:**
- Do not be vague to the point of irrelevance ("You won't believe this!").
- The email body must deliver on the curiosity promise.
- Use sparingly; overuse trains subscribers to distrust.
### 2. Urgency
Create time pressure that motivates immediate action.
| Example | Type |
|---------|------|
| "Last day: 40% off ends at midnight" | Deadline |
| "Only 12 spots left for the workshop" | Scarcity |
| "Price increases tomorrow" | Price urgency |
| "Your trial expires in 48 hours" | Expiration |
| "Flash sale: 6 hours only" | Time-limited |
**Rules:**
- Urgency must be real. Fake urgency destroys trust permanently.
- Do not use urgency in every email. Reserve for genuine time-sensitive offers.
- Avoid all-caps urgency words (LAST CHANCE, HURRY).
- Pair with a specific deadline, not vague "soon" language.
### 3. Personalization
Use subscriber data to make the subject feel individually crafted.
| Example | Data Used |
|---------|-----------|
| "[Name], your weekly marketing digest" | First name |
| "New SEO tips for [Company]" | Company name |
| "Based on your interest in [Topic]..." | Behavioral data |
| "Your [City] marketing event this Thursday" | Location |
| "[Name], you left items in your cart" | Name + behavior |
**Rules:**
- Personalization boosts open rates by 10-20% on average.
- Do not overuse first names. If every email starts with "[Name]," it loses effect.
- Always set fallback values for empty merge fields ("there" instead of blank).
- Use behavioral personalization (what they clicked/viewed) over demographic when possible.
### 4. Question
Pose a question the reader wants answered.
| Example | Type |
|---------|------|
| "Are you making this SEO mistake?" | Self-diagnosis |
| "What's your content strategy for Q2?" | Planning prompt |
| "Ready to double your email list?" | Aspirational |
| "Which pricing model is right for you?" | Choice |
| "Can you write a landing page in 30 min?" | Challenge |
**Rules:**
- Questions should be answerable only by opening the email.
- Avoid yes/no questions where the answer is obvious.
- Rhetorical questions ("Want to make more money?") feel spammy.
- The best questions imply a knowledge gap the reader wants to close.
### 5. Number/Listicle
Include a specific number for concreteness and scannability.
| Example | Why It Works |
|---------|-------------|
| "7 email templates that convert" | Promise of a defined, scannable list |
| "3 things I'd change about my launch" | Small number = quick read |
| "We grew 247% in 90 days" | Specific result = credibility |
| "5-minute fix for your homepage copy" | Number quantifies the effort |
| "11 subject line formulas (steal these)" | Odd numbers outperform even |
**Rules:**
- Odd numbers (3, 5, 7, 9, 11) tend to outperform even numbers.
- Specific numbers (247%) outperform round numbers (250%).
- Use digits, not words ("7" not "seven") for visual impact in the inbox.
- Keep lists short for emails (3-9 items); save long lists for blog posts.
### 6. How-To
Promise a practical, actionable skill or outcome.
| Example | Structure |
|---------|-----------|
| "How to write emails that actually get replies" | How to [outcome] |
| "How I got 1K subscribers in 30 days" | How I [result] in [timeframe] |
| "How to fix your bounce rate in 10 minutes" | How to [fix problem] in [time] |
| "How top founders write investor updates" | How [authority] [does thing] |
**Rules:**
- "How to" subjects set a learning expectation. The email must teach.
- Pair with a specific, measurable outcome when possible.
- Avoid vague how-to's ("How to improve your marketing").
### 7. Controversy/Contrarian
Challenge a widely held belief to provoke engagement.
| Example | Convention Challenged |
|---------|----------------------|
| "Stop writing blog posts" | Content marketing = blog posts |
| "Email marketing is dead (here's what replaced it)" | Channel relevance |
| "Why I stopped A/B testing" | Testing = always good |
| "Your best customers don't read your emails" | Email engagement = loyalty |
| "Forget about SEO for 6 months" | SEO is always important |
**Rules:**
- You must back up the contrarian claim in the email body.
- Do not be contrarian for shock value alone. Have a genuine insight.
- This formula generates high opens AND high unsubscribes. Use intentionally.
- Works best for thought leadership and newsletter content.
## Preview Text Pairing
Every subject line needs a paired preview text. These work together as a unit.
### Pairing Strategies
| Strategy | Subject Line | Preview Text |
|----------|-------------|-------------|
| Continuation | "We analyzed 10K emails." | "The #1 pattern surprised us." |
| Context | "Big news from our team" | "We're launching something we've worked on for 6 months." |
| Benefit | "Your September marketing plan" | "Templates, calendar, and posting schedule inside." |
| Contrast | "This email has no CTA." | "Just one question I'd love your answer to." |
| Social proof | "The email strategy behind $2M ARR" | "How Acme grew revenue with a 5-email sequence." |
### Preview Text Rules
1. Keep preview text between 40-90 characters.
2. Never repeat the subject line.
3. Never leave it blank (ESPs pull body text, which often includes "View in browser").
4. Use it to add information the subject line cannot fit.
5. End with a complete thought. Truncated preview text looks broken.
## A/B Testing Recommendations
### What to Test
| Element | Priority | Expected Impact |
|---------|----------|----------------|
| Subject line copy | High | 10-30% difference in open rate |
| Personalization vs. no personalization | High | 5-20% lift |
| Emoji vs. no emoji | Medium | 2-10% change (audience-dependent) |
| Preview text variations | Medium | 5-15% impact on open rate |
| Subject length (short vs. medium) | Medium | 5-10% difference |
| Question vs. statement | Low-Medium | 3-8% difference |
| Capitalization style | Low | 1-5% difference |
### A/B Test Setup Rules
1. **Test one variable at a time.** If you test subject line AND preview text simultaneously,
you cannot attribute the result.
2. **Minimum sample size:** 1,000 per variant for statistical significance.
3. **Wait time:** At least 4 hours before declaring a winner. 24 hours is better.
4. **Winner threshold:** Declare a winner only with 95%+ statistical confidence.
5. **Document results.** Track what won and by how much. Build a subject line playbook.
### Recommended First A/B Tests
Run these tests in order to build baseline data:
1. **Curiosity vs. Direct** - "The one thing you're missing" vs. "3 ways to improve your CTR"
2. **With name vs. Without** - "[Name], your weekly tips" vs. "Your weekly marketing tips"
3. **Short vs. Medium** - "New from [Brand]" vs. "[Brand]'s new feature saves 2 hours/week"
4. **Emoji vs. No emoji** - "Your Q2 marketing plan" vs. "Your Q2 marketing plan [calendar emoji]"
## Spam Trigger Avoidance
### Words and Phrases to Avoid
These trigger spam filters or reduce trust:
**High risk:** FREE, Act now, Limited time offer, You've been selected, Congratulations,
No obligation, Click here, Buy now, Order now, Don't delete, Urgent, Winner
**Medium risk:** Guarantee, No risk, Double your, Earn $, Discount, Lowest price,
One time, Special promotion, Call now, Apply now, Deal
**Low risk (use sparingly):** Reminder, Exclusive, New, Announcing, Introducing, Sale
### Formatting to Avoid
- ALL CAPS in subject line
- Multiple exclamation marks (!!!)
- $$ or other currency symbols in subject
- Re: or Fwd: when not an actual reply/forward
- Excessive emojis (more than 1-2)
- Misleading subject lines that do not match email content
## Output Format
For every subject line request, deliver:
### 1. Subject Line Options (10-15)
Organized by formula type with character count:
```
CURIOSITY
1. "The one metric you're probably ignoring" (42 chars)
Preview: "It's not open rate, click rate, or revenue."
2. "We tested 5 CTA buttons. One crushed the rest." (48 chars)
Preview: "The winner increased clicks by 37%."
URGENCY
3. ...
```
### 2. Top 3 Recommendations
Ranked by predicted open rate with reasoning.
### 3. A/B Test Pairs
3 recommended A/B pairs with hypothesis for each:
```
Test 1: Curiosity vs. Direct
A: "The one metric you're probably ignoring"
B: "3 email metrics that predict revenue"
Hypothesis: Curiosity will drive higher opens; direct will drive higher clicks.
```
### 4. Subject Lines to Avoid
Flag any user-suggested subject lines that are weak, spammy, or misleading, with reasons.
skills/facebook-ads/SKILL.md
+171
View File
@@ -0,0 +1,171 @@
---
name: facebook-ads
description: Create Facebook and Meta ad campaigns, write ad copy, define audiences, and plan budgets. Use when the user asks about Facebook Ads, Instagram Ads, Meta Ads, social media advertising, carousel ads, retargeting campaigns, lookalike audiences, or ad creative for Meta platforms. Trigger phrases include "Facebook Ads", "Meta Ads", "Instagram Ads", "social ads", "carousel ad", "lookalike audience", "retargeting", "ad creative", "Facebook campaign", "boost post".
---
# Facebook/Meta Ad Campaign Builder
You are an expert Facebook/Meta advertising strategist. When the user asks you to create Meta ad campaigns, write ad copy, or optimize their social advertising, follow this comprehensive framework.
## Step 1: Gather Campaign Context
Before building any campaign, establish:
- **Product/Service**: What is being promoted?
- **Target audience**: Demographics, interests, behaviors?
- **Campaign objective**: What action should people take?
- **Budget**: Daily or lifetime? Total amount?
- **Landing page**: Where does the ad drive traffic?
- **Existing pixel data**: Do they have a Meta Pixel with event history?
- **Creative assets**: Photos, videos, brand guidelines?
If the user has not provided these, ask before proceeding.
## Step 2: Campaign Objective Selection
| Objective | Use When | KPI |
|---|---|---|
| Brand Awareness | Introducing a new brand/product | Ad recall lift, reach |
| Traffic | Driving website visits | CPC, CTR, landing page views |
| Engagement | Growing social proof | CPE, shares, comments |
| Lead Generation | Collecting leads in-platform | CPL, lead quality score |
| Conversions | Driving purchases/sign-ups | CPA, ROAS, conversion rate |
| Catalog Sales | E-commerce dynamic ads | ROAS, cost per purchase |
**Rules**: If pixel has fewer than 50 conversions/week, start with Traffic or Lead Gen. If 50+, use Conversions. For new products with no pixel data, start with Engagement to build social proof.
## Step 3: Audience Strategy
### Core Audiences (Interest-Based)
```
Audience: [Descriptive Name]
Location: [Country/Region/City + radius]
Age: [Range] | Gender: [All/Male/Female]
Detailed Targeting:
Include (OR): [Interests, Behaviors, Demographics]
Narrow (AND): Must also match [list]
Exclude: [list]
Estimated audience size: [range]
```
**Best Practices**: Audience size sweet spot is 1M-10M for conversion campaigns. Exclude current customers from acquisition campaigns. Exclude recent converters (7-14 days).
### Custom Audiences
1. **Website visitors**: Last 30/60/90/180 days
2. **Engaged visitors**: Top 25% by time on site
3. **Add-to-cart abandoners**: 7-30 days
4. **Video viewers**: 50%/75%/95% completion
5. **Page/profile engagers**: Last 90 days
6. **Customer list**: Email/phone upload (target 60%+ match rate)
### Lookalike Audiences
| Seed Source | Lookalike % | Use Case |
|---|---|---|
| Purchasers (top 25% LTV) | 1% | Best for conversion campaigns |
| All purchasers | 1-3% | Broad conversion targeting |
| Email subscribers | 1-2% | Top of funnel |
| Website visitors (top 25%) | 2-5% | Awareness expansion |
Start at 1%, expand to 3-5% only after 1% is saturated. Seed audience minimum: 1,000 people (ideal: 5,000+).
## Step 4: Ad Formats and Copy
### Single Image Ad
```
Primary Text (125 chars visible, 2000 total):
[Hook line - stop the scroll]
[2-3 benefit points]
[CTA line with link]
Headline (max 40 chars): [Value prop or offer]
Description (max 30 chars): [Supporting detail]
CTA Button: [Shop Now / Learn More / Sign Up / Get Offer]
```
**Copy Formulas**: (1) PAS: State pain, twist the knife, present solution. (2) Before/After: Current struggle, then transformed state. (3) Social Proof Lead: Start with testimonial or stat. (4) Direct Offer: Lead with discount or free trial.
### Carousel Ad (2-10 cards)
```
Primary Text: [Shared text - hook + context]
Card 1-4: Headline (40 chars) + Description (20 chars) + URL
```
**Strategies**: Story arc (Problem > Solution > Proof > CTA), Product showcase, Step-by-step process, Testimonial gallery, Feature breakdown.
### Video Ad
```
Video Structure (15-60 seconds):
0-3s: Hook (visual pattern interrupt or bold statement)
3-10s: Problem identification
10-25s: Solution (show product in action)
25-40s: Social proof or differentiator
40-50s: Offer and CTA
50-60s: Logo + final CTA card
```
**Rules**: First 3 seconds determine 80% of performance. Design for sound-off with captions. Square (1:1) or vertical (4:5, 9:16) outperform landscape. Keep under 60s for feed, under 15s for Stories/Reels.
## Step 5: A/B Testing Framework
### Test Priority (highest impact first)
1. Creative format (image vs. video vs. carousel)
2. Hook/first line (3-5 opening lines)
3. Audience (interest vs. lookalike vs. broad)
4. Offer (discount vs. free trial vs. bonus)
5. CTA button and headline
### Test Structure
```
Campaign: [Product] - A/B Test - [Variable]
Budget: Equal split | Duration: 7-14 days minimum
Ad Set A (Control): [Identical audience, control creative]
Ad Set B (Variant): [Identical audience, changed variable only]
```
**Rules**: One variable per test. Run 7+ days or 1,000+ impressions per variant. Need 100+ conversions per variant for 95% significance. Kill clear losers early (2x+ CPA after 500+ impressions).
## Step 6: Budget Allocation
| Funnel Stage | % of Budget | Objective | Audience |
|---|---|---|---|
| Top of Funnel | 20-30% | Awareness/Video Views | Broad/Lookalike 3-5% |
| Middle of Funnel | 10-20% | Traffic/Engagement | Lookalike 1-3%, Interest |
| Bottom of Funnel | 40-50% | Conversions | Retargeting, Lookalike 1% |
| Retention | 10-20% | Conversions | Existing customers |
**Rules**: Minimum $10/day per ad set or 2x target CPA. Learning phase needs ~50 conversions in 7 days per ad set. Never increase budget more than 20% at a time.
**Scaling**: Vertical (increase budget 15-20% every 3-4 days), Horizontal (duplicate winning ad sets with new audiences), Creative (new creatives into winning ad sets weekly).
## Step 7: Campaign Naming Convention
```
Campaign: [Brand]_[Objective]_[Funnel Stage]_[Date]
Ad Set: [Audience Type]_[Audience Detail]_[Placement]
Ad: [Format]_[Creative Concept]_[Version]
```
## Output Format
```
CAMPAIGN BRIEF
==============
Objective: [selected] | Daily Budget: $[amount] | Duration: [timeframe]
Primary KPI: [metric + target]
AUDIENCES: [Full targeting details per audience]
AD CREATIVE: [Full copy per format with character counts]
A/B TEST PLAN: [Priorities with timeline]
BUDGET ALLOCATION: [Funnel stage breakdown]
MEASUREMENT: [KPIs, benchmarks, reporting cadence]
```
Always include character counts. Flag text exceeding limits. Provide 2-3 creative variations per format. Include placement-specific tips for Instagram vs. Facebook feed vs. Stories vs. Reels.
skills/google-ads-report/SKILL.md
+305
View File
@@ -0,0 +1,305 @@
---
name: google-ads-report
description: >
Pull Google Ads performance data and generate reports. Use when asked about
ad campaign performance, keyword costs, quality scores, ROAS, conversion
tracking, or ad spend analysis. Trigger phrases: "google ads", "adwords",
"campaign performance", "ad spend", "quality score", "CPC report",
"ROAS", "ad conversion", "keyword performance", "google ads report".
---
# Google Ads Report
Pull campaign, keyword, and conversion data from the Google Ads API.
## Prerequisites
Requires:
- `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` (OAuth)
- `GOOGLE_ADS_DEVELOPER_TOKEN` (apply at https://ads.google.com/home/tools/manager-accounts/)
- `GOOGLE_ADS_CUSTOMER_ID` (the account ID, format: `XXX-XXX-XXXX`, passed without dashes)
- `GOOGLE_ADS_LOGIN_CUSTOMER_ID` (if using a manager account, the manager account ID)
Set in `.env`, `.env.local`, or `~/.claude/.env.global`.
### Getting an Access Token
```bash
# Same OAuth flow as other Google APIs
# Scope needed: https://www.googleapis.com/auth/adwords
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/adwords&response_type=code&access_type=offline"
# Exchange code for tokens
curl -s -X POST "https://oauth2.googleapis.com/token" \
-d "code={AUTH_CODE}" \
-d "client_id=${GOOGLE_CLIENT_ID}" \
-d "client_secret=${GOOGLE_CLIENT_SECRET}" \
-d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
-d "grant_type=authorization_code"
```
---
## API Base
Google Ads API uses GAQL (Google Ads Query Language) via REST.
```
POST https://googleads.googleapis.com/v17/customers/{CUSTOMER_ID}/googleAds:searchStream
```
Headers:
```
Authorization: Bearer {ACCESS_TOKEN}
developer-token: {DEVELOPER_TOKEN}
login-customer-id: {LOGIN_CUSTOMER_ID} # Only if using manager account
Content-Type: application/json
```
---
## 1. Campaign Performance Report
Overview of all campaigns with key metrics.
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT campaign.name, campaign.status, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions, metrics.cost_per_conversion, metrics.conversions_value FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status != REMOVED ORDER BY metrics.cost_micros DESC"
}'
```
### Parsing Campaign Data
```bash
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"{'Campaign':<35} {'Status':<10} {'Impr':>8} {'Clicks':>7} {'CTR':>7} {'Avg CPC':>8} {'Cost':>10} {'Conv':>6} {'CPA':>8}\")
print('-' * 110)
for batch in data:
for row in batch.get('results', []):
c = row.get('campaign', {})
m = row.get('metrics', {})
cost = int(m.get('costMicros', 0)) / 1_000_000
cpc = int(m.get('averageCpc', 0)) / 1_000_000
cpa = float(m.get('costPerConversion', 0)) / 1_000_000 if m.get('costPerConversion') else 0
print(f\"{c.get('name',''):<35} {c.get('status',''):<10} {int(m.get('impressions',0)):>8} {int(m.get('clicks',0)):>7} {float(m.get('ctr',0))*100:>6.2f}% \${cpc:>7.2f} \${cost:>9.2f} {float(m.get('conversions',0)):>6.1f} \${cpa:>7.2f}\")
"
```
### Important: Cost Micros
All cost values in Google Ads API are in **micros** (1/1,000,000 of the currency unit). Divide by 1,000,000 to get the actual amount.
---
## 2. Keyword Performance Report
See how individual keywords perform.
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.keyword.match_type, ad_group_criterion.quality_info.quality_score, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM keyword_view WHERE segments.date DURING LAST_30_DAYS AND ad_group_criterion.status != REMOVED ORDER BY metrics.cost_micros DESC LIMIT 50"
}'
```
### Quality Score Breakdown
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT ad_group_criterion.keyword.text, ad_group_criterion.quality_info.quality_score, ad_group_criterion.quality_info.creative_quality_score, ad_group_criterion.quality_info.post_click_quality_score, ad_group_criterion.quality_info.search_predicted_ctr, metrics.impressions, metrics.average_cpc FROM keyword_view WHERE ad_group_criterion.quality_info.quality_score IS NOT NULL AND segments.date DURING LAST_30_DAYS ORDER BY ad_group_criterion.quality_info.quality_score ASC LIMIT 50"
}'
```
Quality Score Components:
- **quality_score**: Overall score (1-10)
- **creative_quality_score**: Ad relevance (BELOW_AVERAGE, AVERAGE, ABOVE_AVERAGE)
- **post_click_quality_score**: Landing page experience
- **search_predicted_ctr**: Expected click-through rate
---
## 3. Ad Group Performance
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT campaign.name, ad_group.name, ad_group.status, metrics.impressions, metrics.clicks, metrics.ctr, metrics.average_cpc, metrics.cost_micros, metrics.conversions FROM ad_group WHERE segments.date DURING LAST_30_DAYS AND ad_group.status != REMOVED ORDER BY metrics.cost_micros DESC LIMIT 50"
}'
```
---
## 4. Search Terms Report
See what users actually searched for (vs. your keywords).
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT search_term_view.search_term, segments.keyword.info.text, segments.keyword.info.match_type, metrics.impressions, metrics.clicks, metrics.ctr, metrics.cost_micros, metrics.conversions FROM search_term_view WHERE segments.date DURING LAST_30_DAYS ORDER BY metrics.impressions DESC LIMIT 100"
}'
```
Use this to:
- Find new keyword opportunities (high-converting search terms)
- Identify negative keyword candidates (irrelevant terms with spend)
- Discover match type issues (broad match pulling in junk traffic)
---
## 5. Conversion Tracking
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT campaign.name, metrics.conversions, metrics.conversions_value, metrics.cost_micros, metrics.conversions_from_interactions_rate, metrics.value_per_conversion FROM campaign WHERE segments.date DURING LAST_30_DAYS AND campaign.status = ENABLED ORDER BY metrics.conversions DESC"
}'
```
### ROAS Calculation
```bash
# ROAS = conversions_value / (cost_micros / 1_000_000)
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"{'Campaign':<35} {'Cost':>10} {'Conv Value':>12} {'ROAS':>8}\")
for batch in data:
for row in batch.get('results', []):
c = row['campaign']['name']
m = row['metrics']
cost = int(m.get('costMicros', 0)) / 1_000_000
value = float(m.get('conversionsValue', 0))
roas = value / cost if cost > 0 else 0
print(f\"{c:<35} \${cost:>9.2f} \${value:>11.2f} {roas:>7.2f}x\")
"
```
---
## 6. Daily Spend Trend
```bash
curl -s -X POST \
"https://googleads.googleapis.com/v17/customers/${GOOGLE_ADS_CUSTOMER_ID}:searchStream" \
-H "Authorization: Bearer ${GADS_ACCESS_TOKEN}" \
-H "developer-token: ${GOOGLE_ADS_DEVELOPER_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"query": "SELECT segments.date, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions FROM customer WHERE segments.date DURING LAST_30_DAYS ORDER BY segments.date DESC"
}'
```
---
## GAQL Date Ranges
Use these built-in date ranges in GAQL:
- `TODAY`, `YESTERDAY`
- `LAST_7_DAYS`, `LAST_14_DAYS`, `LAST_30_DAYS`
- `THIS_MONTH`, `LAST_MONTH`
- `THIS_QUARTER`, `LAST_QUARTER`
- Custom: `segments.date BETWEEN '2024-01-01' AND '2024-03-31'`
---
## Workflow: Monthly Google Ads Report
When asked for a full ads report:
1. **Account Overview**: Total spend, impressions, clicks, conversions, ROAS
2. **Campaign Performance**: All active campaigns ranked by spend
3. **Top Keywords**: Top 20 keywords by spend with quality scores
4. **Search Terms**: Top search terms and negative keyword candidates
5. **Quality Score Distribution**: How many keywords at each QS level
6. **Conversion Analysis**: Conversions and ROAS by campaign
7. **Daily Trend**: Spend and conversion trend over the period
### Report Format
```
## Google Ads Report: {Account Name}
### Period: {date range}
### Account Summary
| Metric | Value | vs Previous |
|--------|-------|-------------|
| Total Spend | $X | +Y% |
| Impressions | X | +Y% |
| Clicks | X | +Y% |
| CTR | X% | +Y pp |
| Avg CPC | $X | +Y% |
| Conversions | X | +Y% |
| ROAS | Xx | +Y% |
### Campaign Performance
| Campaign | Spend | Clicks | Conv | CPA | ROAS |
|----------|-------|--------|------|-----|------|
| ... | ... | ... | ... | ... | ... |
### Top Keywords (by spend)
| Keyword | Match | QS | Spend | Clicks | Conv | CPC |
|---------|-------|-----|-------|--------|------|-----|
| ... | ... | ... | ... | ... | ... | ... |
### Recommendations
- **Pause**: Keywords with high spend and zero conversions
- **Increase Bids**: Keywords with high conversion rate but limited budget
- **Negative Keywords**: Search terms wasting budget
- **Quality Score Fixes**: Keywords with QS < 5 and actions to improve
- **Budget Reallocation**: Shift budget from low-ROAS to high-ROAS campaigns
```
---
## Error Handling
| Error | Cause |
|-------|-------|
| `AUTHENTICATION_ERROR` | Invalid or expired access token |
| `AUTHORIZATION_ERROR` | Developer token issue or account access |
| `REQUEST_ERROR` | GAQL syntax error |
| `QUOTA_ERROR` | API quota exceeded |
### Common GAQL Mistakes
- Missing `WHERE segments.date DURING ...` (required for most metric queries)
- Using `REMOVED` status filter incorrectly
- Forgetting to handle `costMicros` division by 1,000,000
- Requesting incompatible resource + segment combinations
## Tips
- Always filter out REMOVED campaigns/ad groups/keywords
- Use `searchStream` instead of `search` for large result sets (no pagination needed)
- Cache results when building multi-section reports
- Quality Score of 0 means "not enough data" -- treat as null
skills/google-ads/SKILL.md
+257
View File
@@ -0,0 +1,257 @@
---
name: google-ads
description: Write Google Ads copy and build campaign structures. Use when the user asks to create Google Ads, write ad copy for search or display, set up PPC campaigns, optimize Quality Score, choose bidding strategies, or generate responsive search ads. Trigger phrases include "Google Ads", "PPC", "search ads", "display ads", "Performance Max", "ad copy", "headlines and descriptions", "keyword match types", "ad extensions", "Quality Score".
---
# Google Ads Copy and Campaign Builder
You are an expert Google Ads strategist and copywriter. When the user asks you to create Google Ads campaigns, write ad copy, or optimize existing ads, follow this comprehensive framework.
## Step 1: Gather Campaign Context
Before writing any ad copy, establish these fundamentals:
- **Product/Service**: What is being advertised?
- **Target audience**: Who are we reaching?
- **Primary goal**: Leads, sales, sign-ups, calls, store visits?
- **Landing page URL**: Where does the ad point?
- **Budget range**: Daily or monthly spend?
- **Competitors**: Who else is bidding on these terms?
- **USPs**: What makes this offer unique?
If the user has not provided these, ask before proceeding.
## Step 2: Keyword Strategy
### Match Types
Structure keywords using all three match types:
| Match Type | Syntax | Use Case |
|---|---|---|
| Broad match | `keyword` | Discovery, maximize reach, use with Smart Bidding |
| Phrase match | `"keyword"` | Moderate control, captures intent variations |
| Exact match | `[keyword]` | Tight control, highest relevance, best for proven terms |
### Keyword Organization
- Group keywords into tightly themed ad groups (5-15 keywords per group)
- Each ad group should target a single intent cluster
- Name ad groups descriptively: `[Product] - [Intent] - [Match Type]`
### Negative Keywords
Always include a negative keyword list. Common categories:
- **Informational blockers**: free, how to, what is, tutorial, guide, DIY, reddit, youtube
- **Job seekers**: jobs, careers, hiring, salary, internship
- **Irrelevant modifiers**: cheap (if premium brand), used, broken, complaint
- **Competitor brand names** (unless running a conquest campaign)
Organize negatives at both campaign and ad group levels.
## Step 3: Search Ad Copy
### Standard Search Ad Format
```
Headline 1 (max 30 characters): [Primary keyword + value prop]
Headline 2 (max 30 characters): [Benefit or differentiator]
Headline 3 (max 30 characters): [CTA or trust signal]
Description 1 (max 90 characters): [Expand on value prop, include keyword naturally]
Description 2 (max 90 characters): [Social proof, urgency, or secondary benefit]
Display URL path 1 (max 15 characters): [Relevant keyword slug]
Display URL path 2 (max 15 characters): [Offer or category]
```
### Copy Rules
1. **Include the primary keyword** in Headline 1 whenever possible (improves Quality Score)
2. **Use numbers and specifics**: "Save 40%" beats "Save Money", "5-Min Setup" beats "Easy Setup"
3. **Include a clear CTA**: "Get Quote", "Start Free Trial", "Book Demo", "Shop Now"
4. **Add urgency when truthful**: "Limited Time", "Ends Sunday", "Only 3 Left"
5. **Front-load value**: Put the most compelling word first in each headline
6. **Never exceed character limits** -- count every character including spaces
7. **Use title case** for headlines, sentence case for descriptions
8. **Avoid exclamation marks in headlines** (Google may disapprove)
9. **Do not repeat the same phrase** across headlines or descriptions
### Responsive Search Ads (RSA)
Provide exactly:
- **15 headlines** (max 30 chars each)
- **4 descriptions** (max 90 chars each)
Pin only when necessary:
- Pin your brand name headline to Position 1 or 2
- Pin your strongest CTA headline to Position 2 or 3
- Leave remaining slots unpinned to let Google optimize
#### RSA Headline Categories (provide at least 2-3 from each):
1. **Keyword headlines**: Include exact target keyword
2. **Benefit headlines**: What the customer gains
3. **Feature headlines**: What the product does
4. **Trust headlines**: Awards, ratings, years in business
5. **CTA headlines**: Direct action phrases
6. **Urgency headlines**: Time-sensitive offers
7. **Price/offer headlines**: Discounts, free trials, pricing
#### RSA Quality Checklist
- [ ] All 15 headlines make sense standalone and in any combination
- [ ] No two headlines are semantically identical
- [ ] At least 3 headlines include the primary keyword or close variant
- [ ] Ad strength indicator target: "Excellent"
- [ ] Each description is self-contained (not dependent on a specific headline)
## Step 4: Display Ad Copy
For Google Display Network campaigns:
### Image Ad Copy
- **Headline**: Max 30 characters. Bold, attention-grabbing.
- **Long headline**: Max 90 characters. More descriptive.
- **Description**: Max 90 characters. Support the headline with a benefit.
- **Business name**: Max 25 characters.
- **CTA button**: Choose from Google's options (Learn More, Shop Now, Sign Up, Get Quote, etc.)
### Display Ad Best Practices
- Use simple, direct language (users are not searching, they are browsing)
- Lead with a pain point or aspiration, not a feature
- Contrast your CTA button color with the ad background
- Provide multiple image ratios: 1.91:1 (landscape), 1:1 (square), 4:5 (portrait)
## Step 5: Performance Max Campaigns
Performance Max requires a full asset package:
### Asset Requirements
| Asset | Count | Max Length |
|---|---|---|
| Headlines | 5-15 | 30 chars |
| Long headlines | 1-5 | 90 chars |
| Descriptions | 2-5 | 90 chars |
| Images | 3+ | 1200x628, 1200x1200, 960x1200 |
| Logos | 1+ | 1200x1200, 1200x300 |
| Videos | 1+ | 10 sec minimum (YouTube) |
| CTA | 1 | Select from list |
| Business name | 1 | 25 chars |
| Sitelinks | 4+ | 25 char headline, 35 char desc x2 |
### Asset Group Strategy
- Create separate asset groups for each product/service line
- Each asset group should have its own audience signal
- Use custom segments (keyword-based and URL-based) for targeting
- Add your first-party data lists as audience signals
## Step 6: Ad Extensions (Assets)
Always recommend and write copy for these extensions:
### Sitelink Extensions
Provide 4-8 sitelinks:
```
Sitelink headline (max 25 chars): [Page name]
Description line 1 (max 35 chars): [What they'll find]
Description line 2 (max 35 chars): [Benefit of visiting]
Final URL: [Specific page URL]
```
### Callout Extensions
Provide 4-6 callouts (max 25 chars each):
- Highlight USPs: "Free Shipping Over $50"
- Trust signals: "4.9 Star Rating"
- Features: "24/7 Support"
### Structured Snippets
Choose a header and provide 3+ values:
- Types: Brands, Courses, Destinations, Featured Hotels, Insurance Coverage, Models, Neighborhoods, Service Catalog, Shows, Styles, Types
### Call Extensions
- Include phone number if the business accepts calls
- Set call reporting and call schedule
### Price Extensions
- At least 3 items with price, description, and URL
- Use the correct price qualifier (from, up to, average)
### Image Extensions
- Square (1:1) and landscape (1.91:1) images
- Must be relevant to the ad and landing page
## Step 7: Quality Score Optimization
Quality Score is determined by three factors. Optimize each:
### 1. Expected Click-Through Rate (CTR)
- Include primary keyword in Headline 1
- Use strong CTAs that create curiosity or urgency
- Test multiple RSA variations
- Aim for CTR above the ad position average (3-5% for search)
### 2. Ad Relevance
- One theme per ad group
- Mirror keyword language in ad copy
- Align ad messaging with search intent
- Use dynamic keyword insertion sparingly: `{KeyWord:Default Text}`
### 3. Landing Page Experience
- Landing page headline must match the ad promise
- Page must load in under 3 seconds
- Mobile-responsive design is mandatory
- Clear path to conversion (visible CTA above the fold)
- Content must be relevant to the keyword and ad
## Step 8: Bidding Strategy Recommendations
| Goal | Recommended Strategy | When to Use |
|---|---|---|
| Maximize conversions | Target CPA | Mature campaigns with 30+ conversions/month |
| Maximize revenue | Target ROAS | E-commerce with accurate conversion values |
| Grow traffic | Maximize Clicks | New campaigns, brand awareness |
| Top placement | Target Impression Share | Brand campaigns, competitive defense |
| Manual control | Enhanced CPC | Low budget, learning phase |
| Full automation | Maximize Conversions | Sufficient conversion data, flexible CPA |
### Bidding Best Practices
- Start with Maximize Conversions (no target) for new campaigns
- Switch to Target CPA after 50+ conversions in 30 days
- Set Target CPA at 20% above your actual average CPA, then decrease gradually
- Never change bidding strategy and budget simultaneously
- Allow 2 weeks of learning after any bidding change
## Output Format
When delivering ad copy, always present it in this structure:
```
Campaign: [Campaign Name]
Ad Group: [Ad Group Name]
Keywords: [list with match types]
Negative Keywords: [list]
RSA:
Headlines:
H1 (pinned to pos 1): "[text]" [XX chars]
H2: "[text]" [XX chars]
...
Descriptions:
D1: "[text]" [XX chars]
D2: "[text]" [XX chars]
...
Extensions:
Sitelinks: [list]
Callouts: [list]
Structured Snippets: [list]
Bidding Recommendation: [strategy + rationale]
Estimated Daily Budget: [range]
```
Always count and display character lengths. Flag any line that exceeds its limit. Provide at least 2 ad group variations per campaign. Include rationale for copy choices when the user is learning.
skills/google-analytics/SKILL.md
+403
View File
@@ -0,0 +1,403 @@
---
name: google-analytics
description: >
Pull GA4 reports, traffic data, and insights from the Google Analytics Data API.
Use when asked about website traffic, user behavior, acquisition channels,
conversions, or audience segments. Trigger phrases: "google analytics", "GA4",
"traffic report", "analytics data", "user acquisition", "engagement metrics",
"conversion tracking", "audience segments", "page views", "sessions".
---
# Google Analytics (GA4)
Pull reports and insights from GA4 using the Google Analytics Data API.
## Prerequisites
Requires Google OAuth credentials:
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- A valid OAuth access token (refreshed as needed)
Set credentials in `.env`, `.env.local`, or `~/.claude/.env.global`.
### Getting an Access Token
```bash
# Step 1: Get authorization code (user must visit this URL in browser)
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/analytics.readonly&response_type=code&access_type=offline"
# Step 2: Exchange code for tokens
curl -s -X POST "https://oauth2.googleapis.com/token" \
-d "code={AUTH_CODE}" \
-d "client_id=${GOOGLE_CLIENT_ID}" \
-d "client_secret=${GOOGLE_CLIENT_SECRET}" \
-d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
-d "grant_type=authorization_code"
# Step 3: Refresh an expired token
curl -s -X POST "https://oauth2.googleapis.com/token" \
-d "refresh_token={REFRESH_TOKEN}" \
-d "client_id=${GOOGLE_CLIENT_ID}" \
-d "client_secret=${GOOGLE_CLIENT_SECRET}" \
-d "grant_type=refresh_token"
```
Store the refresh token securely. The access token expires after 1 hour.
### Finding Your GA4 Property ID
```bash
curl -s -H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
"https://analyticsadmin.googleapis.com/v1beta/accountSummaries" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for acct in data.get('accountSummaries', []):
for prop in acct.get('propertySummaries', []):
print(f\"{prop['property']} | {prop.get('displayName','')} | Account: {acct.get('displayName','')}\")
"
```
The property ID format is `properties/XXXXXXXXX`.
---
## API Base
```
POST https://analyticsdata.googleapis.com/v1beta/{property_id}:runReport
```
All report requests use POST with a JSON body. Always include `Authorization: Bearer {ACCESS_TOKEN}`.
---
## 1. Traffic Overview Report
Get sessions, users, page views, and engagement rate over a date range.
### Example curl
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "newUsers"},
{"name": "screenPageViews"},
{"name": "engagementRate"},
{"name": "averageSessionDuration"},
{"name": "bounceRate"}
]
}'
```
### Date Range Shortcuts
- `today`, `yesterday`
- `7daysAgo`, `14daysAgo`, `28daysAgo`, `30daysAgo`, `90daysAgo`
- Specific dates: `2024-01-01`
- Compare periods by passing two dateRanges
---
## 2. User Acquisition Report
See where users come from (channels, sources, campaigns).
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "sessionDefaultChannelGroup"}
],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "engagementRate"},
{"name": "conversions"}
],
"orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}],
"limit": 20
}'
```
### Useful Acquisition Dimensions
| Dimension | Description |
|-----------|-------------|
| `sessionDefaultChannelGroup` | Channel grouping (Organic, Paid, Social, etc.) |
| `sessionSource` | Traffic source (google, facebook, etc.) |
| `sessionMedium` | Medium (organic, cpc, referral, etc.) |
| `sessionCampaignName` | UTM campaign name |
| `firstUserSource` | First-touch attribution source |
---
## 3. Top Pages Report
Find the highest-traffic pages on the site.
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "pagePath"}
],
"metrics": [
{"name": "screenPageViews"},
{"name": "totalUsers"},
{"name": "engagementRate"},
{"name": "averageSessionDuration"}
],
"orderBys": [{"metric": {"metricName": "screenPageViews"}, "desc": true}],
"limit": 25
}'
```
---
## 4. Engagement Metrics
Understand how users interact with your content.
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "pagePath"}
],
"metrics": [
{"name": "engagedSessions"},
{"name": "engagementRate"},
{"name": "averageSessionDuration"},
{"name": "screenPageViewsPerSession"},
{"name": "eventCount"}
],
"orderBys": [{"metric": {"metricName": "engagedSessions"}, "desc": true}],
"limit": 20
}'
```
### Key Engagement Metrics
| Metric | What It Measures |
|--------|-----------------|
| `engagementRate` | % of sessions that were engaged (>10s, 2+ pages, or conversion) |
| `averageSessionDuration` | Mean session length in seconds |
| `screenPageViewsPerSession` | Pages per session |
| `bounceRate` | % of sessions with no engagement |
| `eventCount` | Total events fired |
---
## 5. Conversion Tracking
Report on conversion events (purchases, signups, etc.).
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "eventName"}
],
"metrics": [
{"name": "eventCount"},
{"name": "totalUsers"},
{"name": "eventValue"}
],
"dimensionFilter": {
"filter": {
"fieldName": "eventName",
"inListFilter": {
"values": ["purchase", "sign_up", "generate_lead", "begin_checkout"]
}
}
}
}'
```
### Conversion by Channel
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "sessionDefaultChannelGroup"}
],
"metrics": [
{"name": "sessions"},
{"name": "conversions"},
{"name": "totalRevenue"}
],
"orderBys": [{"metric": {"metricName": "conversions"}, "desc": true}]
}'
```
---
## 6. Audience Segments
Break down traffic by device, geography, and demographics.
### By Device Category
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [{"name": "deviceCategory"}],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "engagementRate"},
{"name": "conversions"}
]
}'
```
### By Country
Replace `deviceCategory` with `country` in the dimensions.
### By Landing Page + Source
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [{"startDate": "30daysAgo", "endDate": "today"}],
"dimensions": [
{"name": "landingPage"},
{"name": "sessionSource"}
],
"metrics": [
{"name": "sessions"},
{"name": "engagementRate"},
{"name": "conversions"}
],
"orderBys": [{"metric": {"metricName": "sessions"}, "desc": true}],
"limit": 30
}'
```
---
## 7. Period Comparison
Compare two time periods to identify trends.
```bash
curl -s -X POST \
"https://analyticsdata.googleapis.com/v1beta/properties/{PROPERTY_ID}:runReport" \
-H "Authorization: Bearer ${GA_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"dateRanges": [
{"startDate": "30daysAgo", "endDate": "today", "name": "current"},
{"startDate": "60daysAgo", "endDate": "31daysAgo", "name": "previous"}
],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "conversions"},
{"name": "engagementRate"}
]
}'
```
---
## Response Parsing
GA4 API returns JSON. Parse with python3 or jq:
```bash
# Parse report into a table
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
headers = [h['name'] for h in data.get('dimensionHeaders',[])] + [m['name'] for m in data.get('metricHeaders',[])]
print(' | '.join(headers))
print('-' * (len(headers) * 20))
for row in data.get('rows', []):
dims = [d['value'] for d in row.get('dimensionValues',[])]
mets = [m['value'] for m in row.get('metricValues',[])]
print(' | '.join(dims + mets))
"
```
---
## Workflow: Monthly Analytics Report
When asked for a monthly report:
1. Pull traffic overview (sessions, users, page views) with period comparison
2. Pull acquisition breakdown by channel
3. Pull top 20 pages by page views
4. Pull conversion summary by channel
5. Pull device and country breakdown
Present as a structured report with tables, trends (up/down arrows), and recommendations:
```
## Monthly Analytics Report: {Property Name}
### Period: {date range} vs {previous period}
### Traffic Summary
| Metric | Current | Previous | Change |
|--------|---------|----------|--------|
| Sessions | X | Y | +Z% |
| ...
### Top Channels
...
### Top Pages
...
### Conversion Summary
...
### Recommendations
- [Based on data patterns]
```
## Common Issues
- **403 Forbidden**: User lacks access to the GA4 property
- **Empty rows**: No data for the requested date range or filters
- **Quota exceeded**: GA4 API has daily quotas; reduce date ranges or batch requests
- **Property not found**: Verify the property ID format (`properties/XXXXXXXXX`)
skills/icp-builder/SKILL.md
+222
View File
@@ -0,0 +1,222 @@
---
name: icp-builder
description: Define ideal customer profiles and buyer personas with structured frameworks. Use when the user asks about ideal customer profile, ICP, buyer persona, target audience definition, customer segmentation, customer research, user interviews, or persona creation. Trigger phrases include "ideal customer profile", "ICP", "buyer persona", "who is my customer", "target audience", "customer profile", "persona", "customer segmentation", "user research", "customer interview", "who should I target".
---
# Ideal Customer Profile (ICP) Builder
You are an expert in customer research and persona development. When the user asks you to define their ideal customer, build personas, or segment their audience, follow this framework.
## Step 1: Gather Context
Establish: product/service, problem solved, current customers (if any), market type (B2B/B2C), price point, sales motion (self-serve/sales-assisted/enterprise), stage (pre-launch/early/growth), existing data (analytics, CRM, surveys), geography.
## Step 2: ICP Framework
### B2B ICP (Company-Level)
```
FIRMOGRAPHICS
Industry: [specific verticals]
Size (employees): [range] | Size (revenue): [range]
Growth Stage: [startup/scaleup/enterprise/public]
Geography: [regions] | Business Model: [SaaS/e-comm/agency/etc.]
TECHNOGRAPHICS
Tech Stack: [tools they use] | Current Solution: [for this problem]
Technical Maturity: [early adopter/mainstream/laggard]
SITUATIONAL TRIGGERS (events creating buy urgency)
- [e.g., "Just raised funding", "Grew past 50 employees"]
- [e.g., "Current contract ending", "New VP hired"]
QUALIFYING CRITERIA
Must-Have: [e.g., "Marketing team of 3+", "Spends $10K+/mo on ads"]
Nice-to-Have: [e.g., "Active on social media"]
Disqualifying: [e.g., "Pre-revenue", "Fewer than 10 employees"]
```
### B2C ICP (Individual-Level)
```
DEMOGRAPHICS
Age: [range] | Income: [bracket] | Location: [region]
Life Stage: [student/early career/parent/retiree]
PSYCHOGRAPHICS
Values: [what they care about deeply]
Identity: [how they see themselves]
Aspirations: [what they're working toward]
Influences: [who shapes their decisions]
BEHAVIORAL TRAITS
Platforms: [social, search, forums]
Content: [podcasts, newsletters, YouTube]
Purchase behavior: [impulse vs. research-heavy]
Brand loyalty: [switches easily vs. sticky]
```
## Step 3: Pain Points and Goals
### Pain Point Structure
```
Pain Point: [Specific problem]
Severity: [1-10] | Frequency: [daily/weekly/monthly]
Current workaround: [how they handle it today]
Cost of inaction: [what happens if unsolved]
Emotional impact: [frustration/anxiety/embarrassment]
Quote: "[Representative customer quote]"
```
**Categories**: Functional (task is hard/slow), Financial (costs too much), Process (workflows broken), Social (look bad to boss/peers), Emotional (stress/overwhelm).
### Goals
```
Primary Goal: [#1 outcome] | Metric: [how measured] | Timeframe: [expected]
Secondary Goals: [2-3 additional outcomes]
Dream Outcome: [if everything went perfectly]
JTBD: "When I [situation], I want to [action], so I can [outcome]."
```
## Step 4: Objections and Barriers
```
PRICE: "We don't have budget" -> [Response framework + evidence needed]
TIMING: "Not ready to switch" -> [Cost of waiting + easy migration]
TRUST: "Never heard of you" -> [Social proof + guarantee]
INERTIA: "Current solution works" -> [Hidden costs of status quo]
AUTHORITY: "Need manager approval" -> [Business case template]
TECHNICAL: "Will it integrate?" -> [Integration docs + support]
```
## Step 5: Channel Mapping
```
| Channel | Relevance (1-5) | Content Type | Cost |
|---------|----------------|-------------|------|
| Google Search | [score] | SEO/ads | free/paid |
| LinkedIn | [score] | posts/ads | free/paid |
| Twitter/X | [score] | threads | free |
| Reddit | [score] | community | free |
| Podcasts | [score] | guest/sponsor | free/paid |
| YouTube | [score] | tutorials | free/paid |
| Newsletters | [score] | sponsorships | paid |
TOP 3 CHANNELS: [channel + why + tactic]
CONTENT CONSUMED: Specific podcasts, newsletters, influencers, communities, events
```
## Step 6: Customer Interview Template
Target 10-15 interviews. Mix: current customers (5-7), churned (2-3), prospects (3-5). 30-45 min calls.
```
CONTEXT (5 min)
1. Tell me about your role and typical day.
2. Biggest challenges in [relevant area]?
3. How do you currently handle [problem]?
PROBLEM (10 min)
4. Walk me through the last time [problem occurred].
5. Most frustrating part?
6. How often does this come up?
7. What happens if it doesn't get solved?
8. What have you tried before?
SOLUTION (10 min)
9. What tools have you used?
10. What do you like about your current solution?
11. What would you change?
12. Ideal solution looks like?
BUYING (10 min)
13. How did you find your current tool?
14. Who else was involved in the decision?
15. What would make you switch?
16. What would hold you back?
17. What would you pay for [key benefit]?
CLOSE: Anything else? Know anyone similar who'd chat?
```
### Synthesis Template
```
COMMON THEMES: [theme, mentioned by X/n, key quotes]
SURPRISING FINDINGS: [unexpected insights]
VALIDATED ASSUMPTIONS: [confirmed]
INVALIDATED ASSUMPTIONS: [disproven -- critical]
ICP ADJUSTMENTS: [changes based on findings]
```
## Step 7: Survey Design
10-15 questions, 5-7 minutes. Use after interviews for quantitative validation.
**Screening** (2-3 Qs): Role, company size, do they [relevant activity]?
**Problem** (3-4 Qs): Frequency, severity (1-10), current solution, satisfaction (1-10).
**Solution** (3-4 Qs): Feature ranking, switch triggers, willingness to pay.
**Demographics** (2-3 Qs): Industry, budget, open to follow-up?
Minimum: 100 responses for quantitative, 30 for directional insights.
## Step 8: Persona Card Template
Create 2-4 personas:
```
PERSONA: [Name, e.g., "Marketing Mary"]
Role: [title] | Company: [type] | Age: [range]
BIO: [2-3 sentences: professional life, challenges, aspirations]
GOALS FRUSTRATIONS
- [Goal 1] - [Frustration 1]
- [Goal 2] - [Frustration 2]
- [Goal 3] - [Frustration 3]
TOOLS: [3-5 tools] CHANNELS: [3-5 trusted channels]
BUYING: Research style [self/peer/sales], Decision speed [fast/slow],
Budget authority [yes/needs approval]
MESSAGING: Do say "[appeals to them]" | Don't say "[turns them off]"
Key benefit: [#1 thing they care about]
Proof needed: [evidence type that convinces them]
OBJECTION: "[Biggest hesitation]" -> Response: "[How to address]"
JTBD: "When I [situation], I want to [action], so I can [outcome]."
QUOTE: "[Representative mindset quote]"
```
## Step 9: Validation
### Checklist
- [ ] Based on data (interviews, surveys, analytics), not just assumptions
- [ ] 10+ customers/prospects match the profile
- [ ] ICP customers have higher LTV and lower churn
- [ ] ICP customers are reachable through identified channels
- [ ] Specific enough to guide decisions, not so narrow market is too small
- [ ] Documented and shared with all customer-facing teams
### When to Update
After every 50 new customers, after pricing changes, after major features, after new market entry, quarterly minimum.
## Output Format
```
IDEAL CUSTOMER PROFILE: [Product]
==================================
EXECUTIVE SUMMARY: [2-3 sentences]
COMPANY/CUSTOMER PROFILE: [Full details]
PAIN POINTS AND GOALS: [Ranked with severity]
BUYER PERSONAS: [2-4 persona cards]
OBJECTION HANDLING: [Top objections + responses]
CHANNEL STRATEGY: [Where to find them]
RESEARCH TEMPLATES: [Interview + survey instruments]
VALIDATION PLAN: [How to confirm and refine]
```
Ground in evidence. Label assumptions vs. validated insights. Make actionable for marketing copy, ad targeting, content strategy, and sales outreach.
skills/keyword-research/SKILL.md
+233
View File
@@ -0,0 +1,233 @@
---
name: keyword-research
description: Perform keyword research using the SemRush API. Use when the user says "find keywords", "keyword research", "what should I rank for", "keyword ideas", "search volume", "keyword difficulty", "topic clusters", "content gaps", or asks about SEO keywords for a topic or niche.
---
# Keyword Research Skill
You are an expert SEO keyword researcher. Use the SemRush API to find, analyze, and organize keywords into actionable strategies.
## Prerequisites
This skill requires `SEMRUSH_API_KEY`. Check for it in environment variables or in `~/.claude/.env.global`. If not found, inform the user:
```
This skill requires a SemRush API key. Set it via:
export SEMRUSH_API_KEY=your_key_here
Or add it to ~/.claude/.env.global
```
## SemRush API Endpoints
Use `curl` via the Bash tool for all API calls. The base URL is `https://api.semrush.com/`.
### Core Endpoints
**1. Keyword Overview (phrase_all)**
```
https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td
```
Columns: Ph=Keyword, Nq=Search Volume, Cp=CPC, Co=Competition, Nr=Number of Results, Td=Trend
**2. Related Keywords (phrase_related)**
```
https://api.semrush.com/?type=phrase_related&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50
```
**3. Keyword Questions (phrase_questions)**
```
https://api.semrush.com/?type=phrase_questions&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=50
```
**4. Domain Organic Keywords (domain_organic)**
```
https://api.semrush.com/?type=domain_organic&key={KEY}&domain={domain}&database={db}&export_columns=Ph,Po,Nq,Cp,Co,Tr,Tc,Nr,Td&display_limit=100
```
Additional columns: Po=Position, Tr=Traffic, Tc=Traffic Cost
**5. Keyword Difficulty (phrase_kdi)**
```
https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database={db}&export_columns=Ph,Kd
```
Columns: Kd=Keyword Difficulty (0-100)
### Database Codes
- `us` (United States - default)
- `uk` (United Kingdom)
- `ca` (Canada)
- `au` (Australia)
- `de`, `fr`, `es`, `it`, `br`, `in`, `jp`
Ask the user for target market if not specified. Default to `us`.
## Research Process
### Step 1: Understand the Brief
Ask or infer:
- **Niche/Topic:** What is the site about?
- **Target audience:** Who are they trying to reach?
- **Business model:** How do they monetize? (SaaS, ecommerce, ads, affiliate)
- **Current domain:** If they have one, pull existing rankings
- **Target market:** Which country/language?
- **Competitors:** Known competitors to analyze
### Step 2: Seed Keyword Discovery
Generate 10-20 seed keywords based on the brief. Use three methods:
**Method A: Brainstorm seeds** from the topic
- Core product/service terms
- Problem terms ("how to fix...", "why is...")
- Audience terms (job titles, demographics)
- Alternative terms and synonyms
**Method B: Pull competitor keywords** using `domain_organic` for 2-3 competitor domains
**Method C: Expand seeds** using `phrase_related` and `phrase_questions` for each seed
### Step 3: Analyze Each Keyword
For every keyword candidate, collect via API:
| Metric | Source | What it tells you |
|--------|--------|-------------------|
| Search Volume (Nq) | phrase_all | Monthly searches |
| Keyword Difficulty (Kd) | phrase_kdi | How hard to rank (0-100) |
| CPC (Cp) | phrase_all | Commercial value indicator |
| Competition (Co) | phrase_all | PPC competition (0-1) |
| Trend (Td) | phrase_all | 12-month trend data |
| SERP Results (Nr) | phrase_all | Total competing pages |
### Step 4: Classify by Search Intent
Categorize every keyword into one of four intents:
| Intent | Signals | Examples | Content Type |
|--------|---------|----------|--------------|
| **Informational** | how, what, why, guide, tutorial, tips | "how to start a blog" | Blog post, guide, video |
| **Navigational** | brand names, specific product names, login | "semrush login" | Homepage, product page |
| **Commercial** | best, review, comparison, vs, top, alternatives | "best SEO tools 2025" | Comparison, review, listicle |
| **Transactional** | buy, price, discount, coupon, free trial, sign up | "semrush pricing" | Landing page, product page |
**Intent classification rules:**
- "how to" / "what is" / "why" = Informational
- "{brand} + {feature}" = Navigational
- "best" / "top" / "vs" / "alternative" / "review" = Commercial Investigation
- "buy" / "price" / "discount" / "free" / "download" / "sign up" = Transactional
- If ambiguous, check the SERP: majority blog posts = informational, majority product pages = transactional
### Step 5: Build Topic Clusters
Organize keywords into pillar-cluster structure:
```
Pillar Page: [Broad topic keyword - high volume, high difficulty]
|
+-- Cluster 1: [Subtopic keyword group]
| +-- Supporting keyword 1
| +-- Supporting keyword 2
| +-- Question keyword 1
|
+-- Cluster 2: [Subtopic keyword group]
| +-- Supporting keyword 1
| +-- Supporting keyword 2
|
+-- Cluster 3: ...
```
**Clustering rules:**
- Pillar: Volume > 5,000, KD 40-80, broad topic
- Cluster head: Volume 1,000-5,000, KD 20-50, specific subtopic
- Supporting: Volume 100-1,000, KD < 30, long-tail variations
- Each cluster should have 3-8 supporting keywords
- Every supporting page links back to the pillar page
### Step 6: Prioritize with the KOB Score
Calculate the Keyword Opposition to Benefit (KOB) score for prioritization:
```
KOB Score = (Search Volume * CTR Estimate * Business Value) / Keyword Difficulty
Where:
- CTR Estimate: Position 1 = 0.30, Pos 2 = 0.15, Pos 3 = 0.10 (use 0.15 as default)
- Business Value: 3 = direct revenue keyword, 2 = consideration keyword, 1 = awareness keyword
- Keyword Difficulty: 1-100 from SemRush (use max(KD, 1) to avoid division by zero)
```
**Priority tiers:**
- KOB > 50: High priority - target first
- KOB 20-50: Medium priority - target in months 2-3
- KOB 5-20: Low priority - target later
- KOB < 5: Deprioritize unless strategically important
### Step 7: Find Content Gaps
Compare the user's domain against competitors:
1. Pull top 100 keywords for each competitor via `domain_organic`
2. Identify keywords where competitors rank but user does not
3. Filter for keywords with KOB > 20
4. These are content gap opportunities
## Output Format
Present results in this structure:
```markdown
# Keyword Research Report: {Topic/Niche}
**Date:** {date}
**Target Market:** {country}
**Total Keywords Found:** {count}
**Total Monthly Search Volume:** {sum}
## Top 20 Keywords by KOB Score
| # | Keyword | Volume | KD | CPC | Intent | KOB Score |
|---|---------|--------|-----|-----|--------|-----------|
| 1 | {keyword} | {vol} | {kd} | ${cpc} | {intent} | {kob} |
| ... | ... | ... | ... | ... | ... | ... |
## Topic Clusters
### Pillar: {Pillar keyword} (Volume: {vol}, KD: {kd})
| Cluster | Head Keyword | Volume | KD | Supporting Keywords |
|---------|-------------|--------|-----|---------------------|
| {name} | {keyword} | {vol} | {kd} | kw1, kw2, kw3 |
### Content Plan
| Priority | Keyword | Intent | Content Type | Est. Monthly Traffic |
|----------|---------|--------|-------------|---------------------|
| 1 | {keyword} | {intent} | {type} | {vol * 0.15} |
| ... | ... | ... | ... | ... |
## Question Keywords (FAQ Opportunities)
| Question | Volume | KD | Suggested Content |
|----------|--------|-----|-------------------|
| {question} | {vol} | {kd} | {content type} |
## Content Gaps vs. Competitors
| Keyword | Volume | KD | Competitor Ranking | Opportunity |
|---------|--------|-----|--------------------|-------------|
| {keyword} | {vol} | {kd} | {competitor}: #{pos} | {content type} |
## Recommended Next Steps
1. {Specific action item with keyword target}
2. ...
```
## Tips for Better Results
- **Batch API calls** to conserve API credits. Query related keywords in groups.
- **Always check trends.** A keyword with declining volume may not be worth targeting.
- **CPC indicates money intent.** High CPC keywords ($5+) usually have strong commercial intent even if not obvious.
- **Low KD is not always easy.** If all top results are from DR 80+ sites, a KD of 20 may still be hard for a new site.
- **Local vs. national.** For local businesses, append city/state to seed keywords.
- **Seasonal keywords.** Note if trends show seasonality; plan content 2-3 months before peak.
- If the API returns an error or no data, inform the user of the specific issue rather than guessing.
skills/launch-strategy/SKILL.md
+142
View File
@@ -0,0 +1,142 @@
---
name: launch-strategy
description: Plan and execute product launches with week-by-week timelines and channel-specific playbooks. Use when the user asks about launching a product, Product Hunt launch, go-to-market strategy, launch plan, beta program, pre-launch marketing, launch day execution, or post-launch growth. Trigger phrases include "product launch", "launch plan", "Product Hunt", "Hacker News launch", "go-to-market", "GTM strategy", "launch checklist", "pre-launch", "beta launch", "launch day", "launch sequence", "how to launch".
---
# Product Launch Strategy
You are an expert product launch strategist. When the user asks you to plan a launch, prepare for Product Hunt, or build a go-to-market strategy, follow this framework.
## Step 1: Gather Launch Context
Establish: product (new/feature/update), target audience, launch type (soft/beta/public), timeline, budget, team size, existing audience (list size, following), relevant channels, competitive timing, success metrics.
## Step 2: Launch Type Selection
| Type | Timeline | Audience | Best For |
|---|---|---|---|
| Stealth/Alpha | Ongoing | 10-50 hand-picked | Validating concept |
| Closed Beta | 2-4 weeks | 50-500 invited | Refining, testimonials |
| Open Beta | 2-4 weeks | Anyone | Waitlist buzz, stress test |
| Soft Launch | 1 week | Existing audience | Low-risk iteration |
| Full Public | 1 day (4-8 week prep) | Everyone | Maximum impact, PR |
| Rolling | 4-8 weeks | Phased access | Manage load, build FOMO |
## Step 3: Pre-Launch (8-4 Weeks Before)
### Week 8-6: Foundation
**Positioning**: One-sentence value prop. Elevator pitch (30s/60s/2min). Positioning statement:
```
For [audience] who [need], [product] is a [category] that [benefit].
Unlike [alternative], we [differentiator].
```
**Landing Page**: Clear headline, demo video, 3 benefits, email capture, social proof, FAQ. Set up analytics and email automation.
**Content Prep**: 3-5 blog posts for launch week, product demo video (60-90s), screenshots, social calendar, press release draft, founder story narrative.
### Week 6-4: Audience Building
**Waitlist Growth**: Building-in-public updates, referral waitlist, content marketing, community engagement (Reddit/Discord/Slack), micro-influencer outreach (20-50 people), LinkedIn founder posts.
**Waitlist Targets**: Solo founder: 500-5,000+. Small team: 1,000-10,000+. Funded: 5,000-50,000+.
**Beta Setup**: Select 50-200 from waitlist. Private feedback channel. Feedback template: What did you try? Success (1-5)? What was frustrating? Would you recommend? Would you pay?
### Week 4-2: Momentum
**Social Proof**: Request testimonials ("[Result] since using [product]. Before [pain]. Now [benefit]."). Collect usage metrics. Video testimonials.
**Amplification**: Newsletter authors, cross-promotion with complementary founders, advisors/investors briefed, "launch support" doc for network.
**Technical**: Load test for 10x traffic. Monitoring/alerting. Scaling plan. War room channel. On-call assignments.
## Step 4: Launch Week
### Day Before
- [ ] Final QA of product, page, links
- [ ] Queue social posts, pre-schedule email
- [ ] Brief team on roles
- [ ] Verify tracking pixels
- [ ] Test payment flows
### Launch Day
**Hour 0**: Publish everywhere. Send waitlist email. Post all social. Submit Product Hunt.
**Hours 1-4**: Respond to every mention/comment. Share traction updates. Fix bugs immediately. DM supporters.
**Hours 4-12**: Publish "why we built this" post. Share customer reactions. Behind-the-scenes content.
**Hours 12-24**: Day 1 recap email. Wrap-up social post. Respond to all tickets. Plan Day 2.
### Product Hunt Playbook
**Prep**: Build maker profile 2+ weeks early. Prepare: tagline (60 chars), description (260 chars), 5+ gallery images, maker comment (200+ words), 60-90s video.
**Launch Day**: Launch 12:01 AM PT. Post maker comment immediately. Share link by 6 AM PT. Respond to every comment within 30 min. Never ask for "upvotes" -- ask for "feedback." Target top 5.
**Post-PH**: Thank community. Add PH badge. Reach out to commenters. Write retrospective.
### Hacker News Playbook
**Title**: "Show HN: [Name] - [What it does in plain English]"
**Comment**: Technical architecture, why built, what's unique, honest limitations.
**Rules**: Post 8-10 AM ET Tue-Thu. Be humble and transparent. No superlatives. Respond to criticism gracefully.
### Social Media Blitz
**Twitter Thread**: (1) Hook + announcement + link, (2) Problem, (3) Solution + screenshot, (4) Proof/metrics, (5) Story/motivation, (6) CTA + link.
**LinkedIn**: Personal story, hook opening, lessons learned, CTA, tag supporters.
**Reddit**: Follow sub rules, lead with value/story, engage extensively.
## Step 5: Post-Launch (Weeks 2-8)
**Week 2**: Recap email, first case study, retargeting ads, media outreach, NPS collection.
**Week 3-4**: SEO content, comparison pages, onboarding optimization, outbound from leads.
**Week 5-6**: Funnel analysis, landing page A/B tests, double down on best channels, referral program.
**Week 7-8**: Scale paid ads, content partnerships, integrations, plan v2 launch.
## Step 6: Metrics
| Phase | Metric | Target |
|---|---|---|
| Pre-Launch | Waitlist sign-ups | [goal] |
| Pre-Launch | Waitlist CR | 20-40% |
| Pre-Launch | Beta activation | 60%+ |
| Launch Day | Sign-ups | [goal] |
| Launch Day | PH rank | Top 5 |
| Post-Launch | Activation rate | 40%+ |
| Post-Launch | D1/D7/D30 retention | 60%/30%/15%+ |
| Post-Launch | Trial-to-paid | 10-25% |
| Post-Launch | NPS | 40+ |
Track channel attribution by quality (activation rate, retention, LTV), not just volume.
## Step 7: Budget Allocation
| Category | % | Activities |
|---|---|---|
| Content | 20-25% | Video, blog, graphics |
| Paid Acquisition | 30-40% | Social ads, search ads, sponsorships |
| PR/Outreach | 10-15% | Media, influencers |
| Tools | 5-10% | Email, analytics, hosting |
| Reserve | 10-15% | Double down on what works |
**Zero-Budget**: Personal network, Product Hunt, Show HN, Reddit, Twitter thread, cold email journalists, cross-promotion, free email tools.
## Output Format
```
LAUNCH PLAN: [Product]
=======================
TYPE: [type] | DATE: [date] | TARGET: [metric]
TIMELINE: Week-by-week activities
CHANNEL PLAYBOOKS: Detailed per-channel plans
CONTENT CALENDAR: Pieces with publish dates
LAUNCH DAY CHECKLIST: Hour-by-hour execution
BUDGET: Category allocation
METRICS: KPIs with targets
RISK MITIGATION: Contingency plans
```
Tailor to the user's resources. A solo founder needs a different plan than a funded startup.
skills/lead-magnet/SKILL.md
+455
View File
@@ -0,0 +1,455 @@
---
name: lead-magnet
description: >
Create lead magnets and gated content to capture email subscribers and leads.
Use when asked to design checklists, templates, calculators, mini-courses,
whitepapers, or other downloadable content offers. Trigger phrases: "lead magnet",
"gated content", "email capture", "content offer", "free download", "checklist",
"template", "whitepaper", "swipe file", "content upgrade", "opt-in offer".
---
# Lead Magnet Creation
Design and build lead magnets that convert visitors into email subscribers and qualified leads.
---
## 1. Lead Magnet Types
### Checklists
**Best for:** Actionable topics, step-by-step processes
**Effort to create:** Low (1-2 hours)
**Conversion rate:** High (30-50% on dedicated landing pages)
Template structure:
```
Title: The Complete [Topic] Checklist
[ ] Step 1: [Action item]
Why: [Brief explanation]
Tool: [Recommended tool if applicable]
[ ] Step 2: [Action item]
...
[ ] Step 3: [Action item]
...
[Continue for 10-25 items]
Bonus: [Extra tip or resource link]
```
Example titles:
- "The 47-Point Website Launch Checklist"
- "Pre-Publish Blog Post Checklist (Never Miss a Step)"
- "The Complete SEO Audit Checklist for 2025"
### Templates
**Best for:** Saving time, providing structure
**Effort to create:** Medium (2-4 hours)
**Conversion rate:** Very high (35-60%)
Types of templates:
- Spreadsheet templates (Google Sheets, Excel)
- Document templates (Google Docs, Notion)
- Design templates (Canva, Figma)
- Code templates (GitHub repos, code snippets)
- Email templates (copy-paste ready)
Template packaging:
```
[Template Name]
INSTRUCTIONS
1. Make a copy of this template (File > Make a Copy)
2. [Customization step 1]
3. [Customization step 2]
SECTIONS
- Section 1: [Purpose]
- Section 2: [Purpose]
- Section 3: [Purpose]
EXAMPLE (filled in)
[Show one complete example so users understand how to use it]
```
### Calculators / Interactive Tools
**Best for:** Quantifiable outcomes, ROI justification
**Effort to create:** High (1-2 weeks with a developer)
**Conversion rate:** Very high (40-60%)
Calculator ideas:
- ROI calculator for your product
- Cost savings estimator
- "How much are you losing?" audit tool
- Salary/pricing benchmark calculator
- Carbon footprint / impact calculator
Implementation notes:
- Can be built as a simple HTML/JS page
- Gate the results (not the calculator itself) behind email
- Show a preview of results, require email for full report
- Save results as a PDF sent to their email
### Mini-Courses (Email or Video)
**Best for:** Complex topics, building authority, nurture sequences
**Effort to create:** High (1-2 weeks)
**Conversion rate:** Medium-high (25-40%)
Structure:
```
Course: [Title] -- [X]-Day [Topic] Course
Day 1: [Foundation topic]
- Email subject: "[Course Name] Day 1: [Topic]"
- Content: [500-800 words or 5-10 min video]
- Action item: [Homework]
Day 2: [Building on Day 1]
...
Day 3: [Advanced topic]
...
Day 4: [Application / case study]
...
Day 5: [Summary + next steps + soft pitch]
- Recap key learnings
- "If you want to go further, [Product] can help with..."
```
### Whitepapers / Reports
**Best for:** B2B, thought leadership, data-driven audiences
**Effort to create:** High (1-3 weeks)
**Conversion rate:** Medium (15-30%)
Structure:
```
Title: [The State of / The Complete Guide to / X Trends in] [Topic]
Executive Summary (1 page)
- Key findings
- Why this matters
Section 1: [Current State]
- Data point 1
- Data point 2
- Analysis
Section 2: [Challenges]
- Challenge 1 with data
- Challenge 2 with data
Section 3: [Solutions / Trends]
- Trend 1 with examples
- Trend 2 with examples
Section 4: [Recommendations]
- Actionable takeaways
- Implementation roadmap
Methodology (if original research)
About [Company]
```
### Swipe Files
**Best for:** Marketers, copywriters, designers
**Effort to create:** Medium (curate over time)
**Conversion rate:** High (30-50%)
Swipe file types:
- Email subject line swipe file (100+ proven subjects)
- Ad copy swipe file (best-performing ads by industry)
- Landing page swipe file (screenshots + analysis)
- Cold email swipe file (templates for outreach)
- Social media post swipe file (viral post formulas)
Structure:
```
[Swipe File Title]: [X] Proven [Type] You Can Steal
Category 1: [Theme]
Example 1:
Original: "[Exact copy]"
Source: [Brand/campaign]
Why it works: [Analysis]
Template: "[Fill-in-the-blank version]"
Example 2:
...
Category 2: [Theme]
...
```
---
## 2. Landing Page Structure
Every lead magnet needs a dedicated landing page optimized for conversion.
### Above the Fold
```html
<!-- Hero Section -->
<section>
<h1>[Benefit-driven headline]</h1>
<p>[1-2 sentence description of what they'll get and why it matters]</p>
<!-- Lead Magnet Preview -->
<img src="[mockup of the lead magnet]" />
<!-- Opt-in Form -->
<form>
<input type="email" placeholder="Your email address" />
<button>Download Free [Type]</button>
<p class="privacy">No spam. Unsubscribe anytime.</p>
</form>
</section>
```
### Below the Fold
```html
<!-- What's Inside -->
<section>
<h2>Here's what you'll get:</h2>
<ul>
<li>[Specific deliverable 1]</li>
<li>[Specific deliverable 2]</li>
<li>[Specific deliverable 3]</li>
</ul>
</section>
<!-- Social Proof -->
<section>
<p>"[Testimonial about the lead magnet]" -- [Name, Title]</p>
<p>[X] people have downloaded this [type]</p>
</section>
<!-- About the Author -->
<section>
<h2>Created by [Name]</h2>
<p>[1-2 sentences of credibility]</p>
</section>
<!-- FAQ -->
<section>
<h2>Questions?</h2>
<details>
<summary>Is this really free?</summary>
<p>Yes, 100% free. We just ask for your email so we can send it to you.</p>
</details>
<details>
<summary>What format is it in?</summary>
<p>[PDF / Google Sheet / Video / etc.]</p>
</details>
</section>
```
### Headline Formulas
1. "The [Adjective] [Type] to [Desired Outcome]"
- "The Ultimate Checklist to Launch Your Podcast"
2. "[Number] [Things] Every [Audience] Needs to [Goal]"
- "7 Templates Every Startup Founder Needs to Raise Funding"
3. "How to [Desired Outcome] (Free [Type])"
- "How to Double Your Email Open Rate (Free Swipe File)"
4. "Get Our [Type] That [Social Proof]"
- "Get Our SEO Template That 10,000+ Marketers Use"
5. "Stop [Pain Point]. Download Our Free [Type]."
- "Stop Guessing Your Pricing. Download Our Free Calculator."
---
## 3. Email Gate Setup
### Simple Email Gate (HTML + API)
```html
<form id="lead-form" action="/api/subscribe" method="POST">
<input type="email" name="email" required placeholder="you@example.com" />
<input type="hidden" name="lead_magnet" value="seo-checklist" />
<button type="submit">Get Free Checklist</button>
</form>
```
### Integration Options
| Provider | Method |
|----------|--------|
| Mailchimp | Embed form or API (`POST /3.0/lists/{list_id}/members`) |
| ConvertKit | API (`POST /v3/forms/{form_id}/subscribe`) |
| Resend | API (`POST /emails` for delivery + webhook for list) |
| SendGrid | API for delivery + contacts API for list management |
| HubSpot | Forms API or embed form |
### Double Opt-In Flow
1. User submits email on landing page
2. Show "Check your email" confirmation page
3. Send confirmation email with "Confirm your email" button
4. On confirmation, redirect to download page and deliver lead magnet
5. Add to email nurture sequence
### Single Opt-In Flow (Higher Conversion)
1. User submits email on landing page
2. Immediately redirect to download/thank-you page
3. Simultaneously send email with download link (backup delivery)
4. Add to email nurture sequence
---
## 4. Delivery Automation
### Immediate Delivery Email
```
Subject: Your [Lead Magnet Name] is ready
Hi [Name],
Thanks for downloading [Lead Magnet Name]. Here's your copy:
[Download Button/Link]
A few tips to get the most out of it:
1. [Quick tip 1]
2. [Quick tip 2]
3. [Quick tip 3]
Questions? Just reply to this email.
[Signature]
P.S. If you found this helpful, you might also like [related resource].
```
### Post-Download Nurture Sequence
**Email 2 (Day 2):** "Did you get a chance to use [Lead Magnet]?"
- Quick tip or walkthrough
- Ask if they have questions
**Email 3 (Day 4):** "Here's how [Customer] used [Lead Magnet] to [Result]"
- Case study or success story
- Social proof
**Email 4 (Day 7):** "[Related valuable content]"
- Blog post, video, or additional resource
- Build authority
**Email 5 (Day 10):** "The next step after [Lead Magnet topic]"
- Introduce your product/service as the logical next step
- Soft pitch with value framing
**Email 6 (Day 14):** "[Direct offer]"
- Special offer for lead magnet downloaders
- Clear CTA to product/service
- Urgency element (limited time, limited spots)
---
## 5. Content Upgrade Strategy
A content upgrade is a lead magnet specific to an individual blog post.
### How It Works
1. Write a high-traffic blog post
2. Create a bonus resource that complements the post
3. Embed an opt-in within the post to download the bonus
### Content Upgrade Ideas by Post Type
| Post Type | Content Upgrade |
|-----------|----------------|
| How-to guide | Printable checklist of all steps |
| Listicle | Spreadsheet with all items + bonus items |
| Case study | Template to replicate the results |
| Data/research | Raw data spreadsheet or infographic |
| Tutorial | Code snippets or starter template |
| Comparison | Decision-making scorecard |
### In-Post CTA Template
```html
<div class="content-upgrade">
<h3>Free Bonus: [Upgrade Name]</h3>
<p>[1 sentence description]. Download it free below.</p>
<form>
<input type="email" placeholder="Your email" />
<button>Send Me the [Type]</button>
</form>
</div>
```
Place content upgrades:
- After the introduction (for skimmers)
- At the midpoint (for engaged readers)
- At the end (for completionists)
---
## 6. Lead Magnet Selection Framework
Choose the right lead magnet based on your goals:
### By Funnel Stage
| Stage | Best Lead Magnets | Goal |
|-------|------------------|------|
| Top of Funnel | Checklists, quizzes, cheat sheets | Maximum volume |
| Middle of Funnel | Templates, calculators, webinars | Qualification |
| Bottom of Funnel | Free trials, demos, consultations | Conversion |
### By Audience Type
| Audience | Best Formats |
|----------|-------------|
| Time-poor executives | 1-page cheat sheets, executive summaries |
| Hands-on practitioners | Templates, tools, code snippets |
| Data-driven analysts | Reports, benchmarks, calculators |
| Visual learners | Infographics, video courses |
| Beginners | Step-by-step guides, glossaries |
### By Budget
| Budget | Lead Magnet Options |
|--------|-------------------|
| $0 | Checklists, cheat sheets, email courses (text only) |
| $100-500 | Designed PDFs, simple calculators, slide decks |
| $500-2000 | Video courses, interactive tools, original research |
| $2000+ | Software tools, comprehensive platforms, multi-format |
---
## 7. Conversion Benchmarks
| Landing Page Type | Expected Conversion Rate |
|-------------------|------------------------|
| Dedicated lead magnet page | 30-50% |
| Content upgrade (in-post) | 5-15% |
| Sidebar widget | 1-3% |
| Exit-intent popup | 3-8% |
| Homepage email capture | 1-5% |
| Webinar registration | 20-40% |
### Optimization Levers
1. **Headline**: Test benefit-driven vs curiosity-driven
2. **Form fields**: Email-only vs email + name (fewer fields = higher conversion)
3. **CTA button text**: "Download" vs "Get Instant Access" vs "Send Me the [Type]"
4. **Social proof**: Add download count or testimonial
5. **Preview**: Show a mockup/preview of the lead magnet
6. **Urgency**: "Limited time" or "Updated for [current year]"
skills/marketing-ideas/SKILL.md
+421
View File
@@ -0,0 +1,421 @@
---
name: marketing-ideas
description: >
139 proven marketing ideas organized by category with implementation guidance.
Use when asked for marketing ideas, growth strategies, campaign brainstorms,
or "what should I do to grow." Trigger phrases: "marketing ideas", "growth ideas",
"how to grow", "marketing strategies", "campaign ideas", "promote my product",
"marketing brainstorm", "growth tactics", "what should I try", "marketing playbook".
---
# 139 Proven Marketing Ideas
A comprehensive collection of marketing tactics organized by category. Use this as a brainstorming tool and implementation reference.
---
## Category 1: Content & SEO (Ideas 1-20)
1. **Start a blog targeting long-tail keywords** -- Write 2-4 posts/week answering questions your customers search for. Use tools like SemRush or Ahrefs to find low-difficulty keywords with decent volume.
2. **Create pillar content + topic clusters** -- Build comprehensive guides (3,000+ words) on core topics, then write supporting articles that link back to the pillar page.
3. **Publish original research or data studies** -- Survey your users or analyze your product data. Original data earns backlinks and media coverage naturally.
4. **Build a glossary or knowledge base** -- Define every term in your industry. These pages rank well for informational queries and build authority.
5. **Write comparison pages ("X vs Y")** -- Create honest comparisons between your product and competitors. These pages capture high-intent bottom-of-funnel traffic.
6. **Create "best of" listicles** -- "Best [category] tools in 2025" pages attract searchers actively looking for solutions.
7. **Repurpose content across formats** -- Turn blog posts into videos, podcasts, infographics, Twitter threads, LinkedIn carousels, and email newsletters.
8. **Guest post on industry publications** -- Write for high-authority sites in your space to earn backlinks and reach new audiences.
9. **Build interactive tools and calculators** -- ROI calculators, graders, quizzes. These earn backlinks and capture leads.
10. **Optimize existing content** -- Update your top 20 pages with fresh data, better formatting, and additional sections. Often easier than creating new content.
11. **Create templates and downloadable resources** -- Spreadsheets, checklists, Notion templates. High conversion rate as lead magnets.
12. **Start a podcast or be a guest on podcasts** -- Builds personal brand, creates content, and reaches engaged audiences.
13. **Create a free email course** -- 5-7 day email series teaching a skill. Builds your list and establishes expertise.
14. **Build a resource directory** -- Curate and organize tools, blogs, communities in your niche. Becomes a go-to reference page.
15. **Write case studies with real metrics** -- Document customer success stories with specific numbers. Powerful bottom-of-funnel content.
16. **Create video tutorials and walkthroughs** -- YouTube is the second-largest search engine. Tutorial content has long shelf life.
17. **Publish a "state of the industry" annual report** -- Position yourself as a thought leader. Gets press coverage and backlinks.
18. **Optimize for featured snippets** -- Structure content with clear definitions, numbered lists, and tables that Google can pull into position zero.
19. **Build programmatic SEO pages** -- Generate hundreds of pages from data (e.g., "[Tool] for [Industry]", "[City] + [Service]").
20. **Add schema markup to all content** -- Structured data helps Google understand your content and can trigger rich results.
---
## Category 2: Competitor Intelligence (Ideas 21-28)
21. **Analyze competitor content gaps** -- Use SemRush to find keywords competitors rank for that you do not. Create better content for those terms.
22. **Monitor competitor pricing changes** -- Track competitor pricing pages and positioning. Adjust your value messaging accordingly.
23. **Reverse-engineer competitor backlinks** -- Find sites linking to competitors and pitch those sites your superior content.
24. **Track competitor social media** -- Monitor what content resonates for competitors. Identify patterns and adapt (do not copy).
25. **Analyze competitor reviews** -- Read their 1-3 star reviews to find pain points you can address in your product and marketing.
26. **Spy on competitor ads** -- Use Meta Ad Library and Google Ads Transparency Center to see competitor ad creative and messaging.
27. **Monitor competitor job postings** -- Hiring patterns reveal strategic priorities (e.g., hiring SEOs = doubling down on organic).
28. **Build a competitor comparison page** -- Honest comparison pages rank well and capture decision-stage traffic. Update quarterly.
---
## Category 3: Free Tools & Product-Led Growth (Ideas 29-40)
29. **Build a free tool related to your product** -- HubSpot's Website Grader, Moz's Domain Authority Checker. Free tools drive massive organic traffic.
30. **Offer a generous free tier** -- Let users experience core value without paying. The product becomes your best marketing.
31. **Create a browser extension** -- Useful extensions get installed and keep your brand in front of users daily.
32. **Build a Slack/Discord bot** -- Create a bot that solves a small problem and plugs into communities where your users live.
33. **Open-source a component** -- Open-source a library, template, or tool. Builds goodwill and awareness in developer communities.
34. **Create a free API** -- Offer a free tier of your API. Developers who integrate become long-term users and advocates.
35. **Build a widget others can embed** -- Badges, calculators, or widgets that other sites embed (with backlink to you).
36. **Create a Figma/Canva template library** -- Design templates get shared widely and bring users back to your brand.
37. **Add viral mechanics to your product** -- "Made with [Product]" watermarks, shared workspaces, public profiles.
38. **Build in public** -- Share your metrics, decisions, and progress publicly. Authenticity builds an audience.
39. **Create a playground or sandbox** -- Let visitors try your product without signing up. Reduce friction to first experience.
40. **Offer a free Chrome extension** -- Even if tangential to your main product, a useful extension is daily touchpoint.
---
## Category 4: Paid Advertising (Ideas 41-52)
41. **Google Ads on branded competitor terms** -- Bid on competitor brand names. Legal in most jurisdictions. High intent traffic.
42. **Google Ads on high-intent keywords** -- Target "best [category]", "[competitor] alternative", "how to [problem you solve]".
43. **Retargeting ads** -- Show ads to people who visited your site but did not convert. 3-5x higher conversion than cold traffic.
44. **LinkedIn Ads for B2B** -- Precise targeting by job title, company size, industry. Expensive but high quality leads.
45. **Reddit Ads** -- Target specific subreddits where your audience hangs out. Authentic, non-salesy creative works best.
46. **Twitter/X Ads** -- Promote tweets, accounts, or trends. Good for B2B thought leadership amplification.
47. **YouTube pre-roll ads** -- Target competitors' channels and industry keywords. Skippable ads mean you only pay for engaged viewers.
48. **Quora Ads** -- Answer questions in your space and amplify with ads. High intent, lower competition than Google.
49. **Podcast sponsorships** -- Sponsor niche podcasts in your industry. Host-read ads convert better than programmatic.
50. **Newsletter sponsorships** -- Sponsor email newsletters that your audience reads. Direct access to engaged subscribers.
51. **Influencer partnerships** -- Pay micro-influencers (1K-50K followers) in your niche. Better ROI than mega-influencers.
52. **Programmatic display on niche sites** -- Use platforms like BuySellAds to place ads on specific industry websites.
---
## Category 5: Social & Community (Ideas 53-68)
53. **Build a community (Discord, Slack, Circle)** -- Owned communities create loyalty and reduce churn. Start small and curate.
54. **Post consistently on LinkedIn** -- 3-5 posts/week with personal insights. LinkedIn organic reach is still strong for B2B.
55. **Write Twitter/X threads** -- Weekly threads breaking down industry topics. Threads get 10x more reach than single tweets.
56. **Create a subreddit or participate in existing ones** -- Answer questions, share value, build reputation over time. Never spam.
57. **Launch on Product Hunt** -- Prepare a launch campaign. Top 5 products get significant traffic and backlinks.
58. **Post on Hacker News** -- Show HN posts that demonstrate technical depth or novel approaches can drive massive traffic.
59. **Join and contribute to Slack communities** -- Industry Slack groups are where professionals discuss tools and problems.
60. **Create a Facebook Group** -- Niche Facebook Groups still have strong engagement, especially for B2C.
61. **Instagram Reels and TikTok** -- Short-form video content for product demos, tips, and behind-the-scenes.
62. **Go live regularly** -- LinkedIn Live, YouTube Live, Instagram Live. Live content gets algorithmic boosts.
63. **Create a meme account** -- Industry-specific humor builds following and brand awareness among your audience.
64. **Host Twitter/X Spaces** -- Weekly audio discussions on industry topics. Builds audience and thought leadership.
65. **Share user-generated content** -- Repost customer content featuring your product. Social proof + community building.
66. **Create shareable assets** -- Infographics, data visualizations, and quote cards that people want to repost.
67. **Comment strategy** -- Thoughtfully comment on popular posts in your space. Be the first comment on influencer posts.
68. **Build a personal brand for the founder** -- People follow people, not logos. Founder-led marketing is authentic and effective.
---
## Category 6: Email Marketing (Ideas 69-78)
69. **Welcome email sequence** -- 5-7 emails over 14 days for new subscribers. Introduce your brand, deliver value, soft pitch.
70. **Weekly newsletter with curated content** -- Become a trusted source of industry news and insights.
71. **Behavioral email triggers** -- Abandoned cart, inactive user, feature unused. Triggered emails have 3-5x higher open rates.
72. **Segment your email list** -- Different messages for different segments (industry, company size, behavior, funnel stage).
73. **Re-engagement campaign** -- Target inactive subscribers with "We miss you" or "Is this goodbye?" campaigns.
74. **Product update emails** -- Monthly changelog or feature announcement emails keep users engaged and informed.
75. **Milestone celebration emails** -- "You've been with us for 1 year!" or "You've completed 100 tasks!" Drives loyalty.
76. **Customer story emails** -- Share a customer success story in each newsletter. Aspirational and proof-driven.
77. **Holiday and seasonal campaigns** -- Black Friday, New Year, back-to-school. Timely offers tied to calendar events.
78. **Email signature marketing** -- Add a banner or CTA to every team member's email signature.
---
## Category 7: Partnerships & Integrations (Ideas 79-88)
79. **Integration partnerships** -- Build integrations with complementary tools. Get listed in their marketplace/directory.
80. **Co-marketing campaigns** -- Joint webinars, co-authored content, shared email blasts with non-competing partners.
81. **Affiliate program** -- Pay partners commission for referred customers. Low risk (pay only for results).
82. **Technology partner program** -- Formalize partnerships with tools in your ecosystem. Cross-promote.
83. **Agency partner program** -- Agencies recommend tools to their clients. Give them training, certifications, commissions.
84. **Guest on partner webinars** -- Present to their audience. You bring expertise; they bring the audience.
85. **Cross-promote in email footers** -- "We integrate with [Partner]" in both companies' emails.
86. **App store / marketplace presence** -- Get listed on Shopify App Store, HubSpot Marketplace, Salesforce AppExchange, etc.
87. **Bundle deals** -- Partner with complementary products for a discounted bundle. AppSumo-style deals.
88. **Sponsor partner events** -- Sponsor conferences, meetups, or webinars hosted by partners in your ecosystem.
---
## Category 8: Events & Webinars (Ideas 89-96)
89. **Host monthly webinars** -- Educational webinars on topics your audience cares about. Record and repurpose.
90. **Speak at industry conferences** -- Apply to speak at conferences where your customers attend.
91. **Host a virtual summit** -- Multi-speaker online event over 1-3 days. Builds list and partnerships simultaneously.
92. **Local meetups** -- Host small in-person meetups in major cities. Builds deep relationships.
93. **Workshop series** -- Free or paid workshop teaching practical skills using your product.
94. **Hackathons** -- Developer-focused events where participants build with your product or API.
95. **Customer advisory board** -- Invite top customers to an exclusive group. They become advocates.
96. **Founder dinners** -- Small, exclusive dinners with potential customers or partners. High-touch, high-conversion.
---
## Category 9: PR & Media (Ideas 97-106)
97. **Publish original research** -- Newsworthy data gets picked up by journalists. Survey your users or analyze industry trends.
98. **HARO / Connectively responses** -- Respond to journalist queries to get quoted in articles with backlinks.
99. **Press release for launches** -- Use PRWeb or Newswire for major product launches. Supplements direct outreach.
100. **Build journalist relationships** -- Identify 10-20 journalists covering your space. Follow, engage, and pitch thoughtfully.
101. **Newsjacking** -- React quickly to industry news with expert commentary. Be the go-to source.
102. **Founder story pitch** -- Journalists love origin stories. "Why I quit [big company] to build [startup]."
103. **Award submissions** -- Apply for industry awards (G2, Capterra, local business awards). Wins provide social proof.
104. **Contribute to industry publications** -- Write op-eds for Forbes, TechCrunch, etc. via contributor programs.
105. **Publish a brand book or manifesto** -- A strong point of view attracts attention and media coverage.
106. **Data-driven PR campaigns** -- Create shareable data visualizations and pitch them to media with an exclusive.
---
## Category 10: Launches & Announcements (Ideas 107-114)
107. **Product Hunt launch** -- Plan a proper launch: build a following, prepare assets, coordinate upvotes, engage in comments.
108. **Hacker News Show HN** -- Technical and novel products do well. Write a clear, honest description.
109. **Beta launch with waitlist** -- Create scarcity and anticipation. Notify waitlist in waves.
110. **Feature launch emails** -- Dedicated email for each major feature launch with use cases and examples.
111. **Launch on multiple platforms simultaneously** -- Product Hunt + Hacker News + Reddit + Twitter thread on the same day.
112. **Pre-launch content series** -- Build anticipation with a 5-part content series leading up to launch.
113. **Launch party or live event** -- Virtual or in-person celebration for major releases.
114. **Customer spotlight at launch** -- Feature a customer who tested the feature in beta as the launch story.
---
## Category 11: Product-Led Marketing (Ideas 115-126)
115. **"Made with [Product]" watermarks** -- Canva, Loom, Notion do this. Every output is marketing.
116. **Public sharing features** -- Enable users to share their work publicly (portfolios, dashboards, pages).
117. **In-product referral prompts** -- Prompt at moments of delight: "Love this? Share with a friend."
118. **Viral invite mechanics** -- Collaborative features that require inviting others (Google Docs, Figma, Slack).
119. **Embeddable outputs** -- Let users embed product outputs on their websites (charts, forms, videos).
120. **Free tier with branding** -- Free users become marketing channels. Paid removes branding.
121. **API and developer ecosystem** -- Developers who build on your platform evangelize it.
122. **Templates marketplace** -- User-created templates attract new users searching for those templates.
123. **Public roadmap** -- A public roadmap builds transparency and attracts users who see planned features.
124. **Changelog as content** -- Make your changelog engaging and shareable. Celebrate progress publicly.
125. **Usage milestone sharing** -- "You've saved 100 hours with [Product]" prompts for social sharing.
126. **Community templates and presets** -- Users sharing their setups brings in new users organically.
---
## Category 12: Unconventional & Creative (Ideas 127-139)
127. **Billboards in target neighborhoods** -- A single billboard near a tech campus can generate massive buzz (Notion's SF billboards).
128. **Swag that people actually want** -- High-quality, useful branded items: notebooks, water bottles, stickers.
129. **Handwritten notes to customers** -- Does not scale, but creates unforgettable moments for early customers.
130. **Easter eggs in your product** -- Hidden features or messages that users discover and share on social media.
131. **Controversial takes** -- A strong, well-argued opinion generates more sharing than neutral content.
132. **Challenge campaigns** -- "30-day [skill] challenge" using your product. Creates content and community.
133. **Create a certification program** -- "[Product] Certified Professional" creates evangelists and adds resume value.
134. **Buy a competing/expired domain** -- Redirect traffic from expired competitor domains to your site.
135. **Direct mail to prospects** -- Physical mail stands out in the digital age. Send a memorable package.
136. **Sponsor an open-source project** -- Builds goodwill in developer communities and gets logo placement.
137. **Create a Spotify playlist** -- "Coding Focus" or "Startup Hustle" playlists with your brand attached.
138. **Build a game** -- A simple, fun game related to your industry (Wordle-style) drives viral sharing.
139. **Donate to charity per signup** -- "We'll plant a tree for every new account" creates feel-good sharing.
---
## Implementation Guide
### By Company Stage
**Pre-launch (0 customers):**
- Focus: Ideas 57, 108, 109, 112 (launch tactics)
- Build an audience before you build the product
- Priority: Waitlist, community building, build in public
**Early stage (0-100 customers):**
- Focus: Ideas 1-5, 15, 29, 38, 68 (content + product-led)
- Do things that do not scale: handwritten notes, 1:1 calls
- Priority: SEO foundation, founder-led marketing, free tools
**Growth stage (100-1,000 customers):**
- Focus: Ideas 41-52, 69-78, 79-88 (paid + email + partnerships)
- Start investing in channels with predictable ROI
- Priority: Paid acquisition, email nurture, integrations
**Scale stage (1,000+ customers):**
- Focus: Ideas 89-96, 97-106, 115-126 (events + PR + product-led)
- Systematize what works, experiment with new channels
- Priority: PR, conferences, product virality
### By Budget
**$0/month (sweat equity only):**
- Content & SEO (1-20)
- Social & community (53-68)
- Build in public (38)
- Product Hunt launch (57, 107)
**$500/month:**
- Newsletter sponsorships (50)
- Micro-influencer partnerships (51)
- Basic retargeting (43)
- Tool subscriptions (SemRush, email provider)
**$2,000/month:**
- Google Ads on high-intent keywords (42)
- LinkedIn Ads (44)
- Podcast sponsorships (49)
- Freelance content writers
**$10,000+/month:**
- Multi-channel paid campaigns (41-52)
- Agency partnerships (83)
- Events and webinars (89-96)
- PR campaigns (97-106)
### By Timeline
**This week (quick wins):**
- Optimize email signatures (78)
- Set up retargeting pixel (43)
- Post on social media (54, 55)
- Answer HARO queries (98)
- Comment on industry posts (67)
**This month:**
- Publish 4 blog posts (1-2)
- Launch on Product Hunt (107)
- Start email welcome sequence (69)
- Set up one integration (79)
- Guest post on one publication (8)
**This quarter:**
- Build a free tool (29)
- Launch referral program (see referral-program skill)
- Start a podcast or webinar series (12, 89)
- Run first paid campaign (42-44)
- Publish original research (3, 97)
**This year:**
- Build comprehensive content library (1-20)
- Establish partner ecosystem (79-88)
- Scale paid channels (41-52)
- Launch community (53)
- Build product-led growth loops (115-126)
skills/onboarding-cro/SKILL.md
+486
View File
@@ -0,0 +1,486 @@
---
name: onboarding-cro
description: >
Improve user onboarding flows to increase activation and retention. Use when
asked to design welcome screens, setup wizards, product tours, onboarding
checklists, or activation sequences. Trigger phrases: "onboarding flow",
"user activation", "welcome screen", "product tour", "onboarding checklist",
"first-run experience", "setup wizard", "aha moment", "time to value",
"user onboarding", "activation rate".
---
# Onboarding CRO
Design and optimize user onboarding flows that drive activation and long-term retention.
---
## 1. Onboarding Frameworks
### Jobs-To-Be-Done (JTBD) Onboarding
The best onboarding flows are organized around the user's job, not the product's features.
**Process:**
1. Identify the user's primary job-to-be-done
2. Map the minimum steps to complete that job in your product
3. Guide the user through those steps, removing all distractions
4. Celebrate completion (aha moment)
**Example (Notion):**
- Job: "I need to organize my team's projects"
- Steps: Create workspace > Invite team > Create first page > Use a template
- The onboarding flow guides exactly this path, nothing more
**Anti-pattern:** Feature tours that show every feature. Users do not care about features during onboarding; they care about solving their problem.
### Progressive Disclosure
Reveal functionality gradually as users demonstrate readiness.
**Levels:**
1. **First session:** Only show core functionality needed for primary job
2. **After first success:** Introduce secondary features that enhance the core workflow
3. **After repeated use:** Surface power features, integrations, customization
4. **After mastery:** Invite to advanced features, API, automation
**Implementation:**
- Use feature flags or user state to control what's visible
- Track user actions to determine when to advance disclosure level
- Never show everything at once
### Activation Metrics
Define your activation metric before designing onboarding. The activation metric is the action most correlated with long-term retention.
**Examples:**
| Product | Activation Metric | Timeframe |
|---------|------------------|-----------|
| Slack | Send 2,000 messages (team) | First 30 days |
| Dropbox | Upload 1 file from 2 devices | First 7 days |
| Facebook | Add 7 friends | First 10 days |
| Zoom | Host first meeting | First 7 days |
| Notion | Create 3 pages | First 7 days |
| Figma | Create first design | First 3 days |
| HubSpot | Import contacts + send first email | First 14 days |
**How to find your activation metric:**
1. Cohort analysis: Compare retained vs churned users
2. Identify actions that retained users took that churned users did not
3. Find the action with strongest correlation to 30-day retention
4. Validate by testing whether guiding users to that action improves retention
### Aha Moment Identification
The aha moment is when a user first experiences the core value of your product.
**Framework for identifying it:**
1. What do users say when they recommend your product? ("It's amazing because...")
2. When during their journey do users typically say "wow" or "this is cool"?
3. What single action separates users who stay from those who leave?
**The aha moment is NOT:**
- Signing up
- Completing onboarding
- Seeing a feature demo
**The aha moment IS:**
- Getting their first result
- Experiencing time saved
- Seeing their data visualized for the first time
- Completing their first task successfully
---
## 2. Onboarding Components
### Welcome Screens
The first screen after signup. Serves two purposes: make the user feel welcomed and collect information for personalization.
**Best Practices:**
- Use the user's name ("Welcome, Sarah!")
- Keep it to 1-3 questions maximum
- Use visual selectors (cards with icons) instead of dropdowns
- Every question should directly affect their experience
- Always allow skipping
**Template:**
```
Welcome to [Product], [Name]!
Let's personalize your experience.
What's your primary goal?
[ ] [Goal 1 -- with icon]
[ ] [Goal 2 -- with icon]
[ ] [Goal 3 -- with icon]
[ ] Something else
[Continue] [Skip for now]
```
**Example (Notion):**
```
What will you use Notion for?
[Personal] [Team] [School]
How big is your team?
[Just me] [2-10] [11-50] [50+]
```
### Setup Wizards
Guided multi-step flows that set up the product for use.
**When to use:** When the product requires configuration before it can deliver value (CRM, analytics, marketing automation).
**Best Practices:**
- Maximum 3-5 steps
- Show progress indicator
- Pre-fill defaults where possible
- Allow skipping non-essential steps
- Provide "try it with sample data" option
- End with a clear next action, not a blank screen
**Template:**
```
Step 1: Connect your [data source]
[Connect Google] [Connect manually] [Use sample data]
Step 2: Configure your [workspace/project]
[Pre-filled sensible defaults with edit option]
Step 3: Invite your team (optional)
[Email input] [Copy invite link] [Skip]
You're all set!
[Go to your dashboard]
```
### Product Tours
Interactive walkthroughs of the product interface.
**Types:**
1. **Tooltip tour:** Highlights UI elements with explanatory tooltips (Intercom, Appcues)
2. **Video walkthrough:** Short video showing key workflows
3. **Interactive tutorial:** User performs real actions with guidance
4. **Sandbox mode:** Pre-populated environment for safe exploration
**Best Practices:**
- Keep tours under 5 steps (3 is ideal)
- Focus on ONE workflow per tour
- Let users exit at any point
- Make the user DO something, not just read
- Trigger contextually (first time visiting a feature), not globally
- Never replay completed tours unless user requests it
**Anti-patterns:**
- 15-step tours that show every button
- Forced tours that cannot be dismissed
- Tours that explain obvious UI elements
- Tours that trigger repeatedly
**Template (per step):**
```
Step [X] of [Y]:
[Pointer to UI element]
"[Action verb] here to [achieve result]."
[Try it now] / [Next] / [Skip tour]
```
### Onboarding Checklists
Persistent task lists that guide users through activation.
**Why they work:**
- Zeigarnik effect: People feel compelled to complete unfinished tasks
- Clear progress visualization
- Users self-pace through the list
- Can be dismissed and revisited
**Template:**
```
Get started with [Product] [3/5 complete]
[x] Create your account
[x] Set up your profile
[x] [First key action]
[ ] [Second key action] <-- "Do this next"
[ ] [Third key action]
[Dismiss checklist]
```
**Best Practices:**
- 4-6 items maximum
- Pre-check easy items (account creation) for momentum
- Order by dependency and importance
- Highlight the next recommended step
- Celebrate completion (confetti, badge, reward)
- Include at least one "aha moment" action
- Show percentage complete or progress bar
**Example (Slack):**
```
Getting started [2/4]
[x] Set your profile photo
[x] Join a channel
[ ] Send your first message
[ ] Invite a teammate
```
**Example (Figma):**
```
Welcome to Figma [1/5]
[x] Create your account
[ ] Create a design file
[ ] Add a frame
[ ] Use a component
[ ] Share with your team
```
### Email Onboarding Sequences
Drip emails that complement the in-app experience.
**Sequence structure:**
| Day | Email | Purpose |
|-----|-------|---------|
| 0 | Welcome + quick start | Immediate value, link to first action |
| 1 | Tip: [Core feature] | Teach one key feature |
| 3 | Social proof | Show what others achieve with the product |
| 5 | "Need help?" | Address common obstacles, offer support |
| 7 | Feature highlight | Introduce a secondary feature |
| 10 | Activation reminder | If not activated, nudge toward key action |
| 14 | Upgrade prompt | If activated, pitch premium features |
**Day 0 Welcome Email Template:**
```
Subject: Welcome to [Product] -- here's your quick start
Hi [Name],
You're in! Here's how to get the most out of [Product] in the next 5 minutes:
1. [First action] -- [link directly to it]
2. [Second action] -- [link]
3. [Third action] -- [link]
[Primary CTA: "Go to your dashboard"]
Need help? Reply to this email or check our [getting started guide].
[Signature]
```
**Day 3 Social Proof Email Template:**
```
Subject: How [Customer] uses [Product] to [Result]
Hi [Name],
Did you know that [Customer/Company] uses [Product] to [specific result with metric]?
Here's what they did:
1. [Step they took]
2. [Step they took]
3. [Result they achieved]
You can do the same:
[CTA: "Try it now"]
```
---
## 3. Onboarding Examples from Top Products
### Notion
**What they do well:**
- Welcome screen asks role + use case (2 questions)
- Offers templates based on selection
- Pre-populates workspace with starter content
- Progressive disclosure: basic blocks first, databases later
- Checklist in sidebar tracks setup progress
- Empty states have clear CTAs
**Activation metric:** Create 3+ pages in first 7 days
### Slack
**What they do well:**
- Workspace setup wizard is 3 steps (name, invite, channel)
- Slackbot guides first interactions conversationally
- Pre-created #general and #random channels with welcome messages
- Teaches features by having users use them (send a message, react with emoji)
- Onboarding checklist in sidebar
**Activation metric:** Team sends 2,000 messages in first 30 days
### Figma
**What they do well:**
- Minimal signup (Google OAuth one-click)
- Immediately drops user into a canvas with interactive tutorial
- Tutorial teaches by doing (create shape, move it, style it)
- Sample files available to explore
- Team collaboration demonstrated early (cursor presence)
**Activation metric:** Create first design file in first 3 days
### Canva
**What they do well:**
- Asks "What will you design today?" with visual categories
- Immediately shows templates relevant to selection
- First design experience uses pre-made template (user edits, not creates from scratch)
- Celebrates first download with sharing prompt
### Linear
**What they do well:**
- Import from existing tools (Jira, Asana) as first step
- Pre-configured with sensible defaults (workflow states, labels)
- Keyboard shortcuts taught in context
- Empty states show exactly what to do next
---
## 4. Measuring Onboarding Success
### Key Metrics
| Metric | Formula | Target |
|--------|---------|--------|
| Onboarding completion rate | Users who complete onboarding / signups | 60-80% |
| Time to first key action | Time from signup to first meaningful action | Under 5 min |
| Activation rate | Users hitting activation metric / signups | 20-40% |
| Day 1 retention | Users returning day after signup / signups | 40-60% |
| Day 7 retention | Users returning 7 days after signup / signups | 20-35% |
| Day 30 retention | Users active 30 days after signup / signups | 10-25% |
| Onboarding step drop-off | Users completing step N / users starting step N | Track per step |
| Time to value (TTV) | Median time from signup to aha moment | As low as possible |
### Funnel Analysis
Build an onboarding funnel in your analytics tool:
```
Signup completed
-> Welcome screen completed
-> First key action
-> Second key action (aha moment)
-> Activation metric reached
-> Day 7 return
```
Track conversion rate between each step. The biggest drop-off is your biggest opportunity.
---
## 5. A/B Test Ideas for Onboarding
### Welcome Screen
1. 1 question vs 3 questions on welcome screen
2. Visual card selection vs dropdown
3. Personalized template suggestions vs generic
### Setup Flow
4. Guided setup vs "explore on your own"
5. Pre-populated sample data vs empty state
6. Setup wizard vs onboarding checklist
### Product Tour
7. Tooltip tour vs video walkthrough
8. 3-step tour vs 5-step tour
9. Auto-triggered tour vs user-initiated
### Activation
10. Email nudge on day 1 vs day 3 for inactive users
11. In-app prompt for next action vs no prompt
12. Celebrating milestones (confetti, badge) vs no celebration
13. Showing progress ("You're 60% set up") vs not showing
### Engagement
14. Daily tip emails vs weekly digest
15. Push notifications for incomplete onboarding vs email only
16. Peer comparison ("Teams like yours usually...") vs no comparison
---
## 6. Onboarding Audit Template
When auditing an existing onboarding flow:
```
## Onboarding Audit: [Product Name]
### Date: [Date]
### Current Flow Map
[Step-by-step flow with screenshots]
### Time to Complete
- Minimum path: [X] minutes
- Average path: [X] minutes
### Drop-off Analysis
| Step | Users Entering | Completion Rate | Drop-off |
|------|---------------|-----------------|----------|
| Signup | 100% | X% | X% |
| Welcome screen | X% | X% | X% |
| Setup step 1 | X% | X% | X% |
| Setup step 2 | X% | X% | X% |
| First key action | X% | X% | X% |
| Activation | X% | -- | -- |
### Scores (1-10)
| Dimension | Score | Notes |
|-----------|-------|-------|
| Time to value | X | |
| Clarity of next step | X | |
| Progressive disclosure | X | |
| Error recovery | X | |
| Mobile experience | X | |
| Personalization | X | |
| **Overall** | **X** | |
### Issues Found
1. **[Critical]** [Issue] -- Impact: [X]% activation loss
2. **[High]** [Issue]
3. **[Medium]** [Issue]
### Recommendations (Priority Order)
1. [Recommendation] -- Expected lift: X% on [metric]
2. [Recommendation] -- Expected lift: X%
3. [Recommendation] -- Expected lift: X%
### Quick Wins
- [ ] [Immediate fix]
- [ ] [Immediate fix]
### Long-term Improvements
- [ ] [Bigger initiative]
- [ ] [Bigger initiative]
```
---
## 7. Common Onboarding Mistakes
1. **Showing everything at once** -- Overwhelms users. Use progressive disclosure.
2. **Explaining features, not outcomes** -- "This is our dashboard" vs "See your results here."
3. **Forcing completion before value** -- Let users explore, then guide.
4. **No empty state strategy** -- Blank screens kill activation. Use templates, samples, or guided prompts.
5. **One-size-fits-all flow** -- Different user types need different onboarding paths.
6. **Ignoring mobile** -- Mobile onboarding needs its own design (not a shrunk desktop flow).
7. **No re-engagement for drop-offs** -- Users who abandon onboarding need targeted email nudges.
8. **Celebrating signup, not activation** -- "Welcome!" is not the goal. The first success moment is.
9. **Too many tooltips** -- If you need 10 tooltips, your UI is too complex.
10. **No measurement** -- If you are not tracking step-by-step drop-offs, you are guessing.
skills/page-cro/SKILL.md
+158
View File
@@ -0,0 +1,158 @@
---
name: page-cro
description: Audit and optimize landing pages for conversion rate. Use when the user asks about conversion rate optimization, CRO, landing page audits, improving sign-ups or sales, reducing bounce rate, A/B test ideas for pages, form optimization, or CTA optimization. Trigger phrases include "conversion rate", "CRO", "landing page audit", "why isn't my page converting", "improve conversions", "optimize my page", "reduce bounce rate", "CTA optimization", "form optimization", "above the fold".
---
# Landing Page Conversion Rate Optimization (CRO)
You are an expert CRO specialist. When the user asks you to audit a landing page, suggest improvements, or optimize for conversions, follow this framework.
## Step 1: Gather Page Context
Establish: Page URL, primary conversion action, traffic source (ads/SEO/social/email), current conversion rate, monthly traffic, target audience, industry, tech stack.
If the user provides a URL, read the page source or ask them to share the content.
## Step 2: Industry Benchmark Conversion Rates
| Industry | Landing Page CR | Good | Excellent |
|---|---|---|---|
| SaaS (Free Trial) | 3-5% | 7% | 10%+ |
| SaaS (Demo Request) | 2-4% | 5% | 8%+ |
| E-commerce | 2-3% | 4% | 6%+ |
| B2B Lead Gen | 2-5% | 6% | 10%+ |
| Financial Services | 2-4% | 5% | 8%+ |
| Education | 3-6% | 8% | 12%+ |
| Agency/Consulting | 3-5% | 7% | 10%+ |
Paid traffic converts 2-3x higher than organic. Mobile converts 30-50% lower than desktop.
## Step 3: Above-the-Fold Audit
The first screen determines whether 60-80% of visitors stay. Audit:
- [ ] **Headline clarity**: Understand the offer in under 5 seconds?
- [ ] **Value proposition**: Primary benefit (not feature) immediately clear?
- [ ] **Relevance match**: Headline matches the ad/link that brought them here?
- [ ] **Visual hierarchy**: Headline is the most prominent text?
- [ ] **Primary CTA visible**: Main action button visible without scrolling?
- [ ] **CTA contrast**: Button stands out from background?
- [ ] **CTA copy**: Describes the outcome (not "Submit")?
- [ ] **No competing CTAs**: Only one primary action above the fold?
### Headline Formulas That Convert
1. "[Achieve desired outcome] without [common pain point]"
2. "[Exact number] [audience] use [product] to [outcome]"
3. "What if you could [desired outcome] in [timeframe]?"
4. "Join [number] [audience] who [outcome]"
### CTA Button Copy Rules
Never: "Submit", "Click Here", "Learn More" on conversion pages.
Instead: "Start My Free Trial", "Get My [Deliverable]", "Book My Demo", "Create Free Account".
## Step 4: Full Page Audit Framework
### Social Proof (Place Within First 2 Scrolls)
- Customer logos (must-have for B2B), star ratings (must-have for e-commerce)
- Testimonials with photo + name + title addressing the #1 objection
- Case study metrics with specific numbers ("Increased revenue 340%")
- Trust badges, media mentions, user count
### Benefits and Features
- Lead with benefits, support with features. Use the "So what?" test.
- 3-5 benefit blocks maximum. Icons for scannability.
### How It Works
- 3-step process maximum. Number each step. End with the conversion action.
### Objection Handling
Address on every page: Price (show ROI), Time (show speed), Trust (show credentials), Risk (show guarantee), Effort (show ease), Relevance (show persona-matched testimonials).
### FAQ Section
5-8 questions from sales calls/support tickets. Expandable accordions. Lead with the #1 objection.
### Final CTA Block
Repeat primary CTA at bottom with different headline angle. Include micro-commitment option for hesitant visitors.
## Step 5: Form Optimization
| Fields | Impact on CR |
|---|---|
| 1 field (email only) | Baseline (highest) |
| 2-3 fields | -10 to -20% |
| 4-5 fields | -25 to -40% |
| 6+ fields | -40 to -80% |
**Rules**: Single-column layout. Labels above fields (not placeholder text). Inline validation. Pre-fill when possible. Replace dropdowns with buttons for <5 options. Remove CAPTCHA (use honeypot). Full-width submit button with outcome-focused copy.
**Multi-Step Forms** (5+ fields): Split into steps (low-friction start, qualifying info, specific needs). Show progress bar. Typical improvement: +20-40%.
## Step 6: Trust Signals and Guarantees
Place money-back guarantee near CTA, security badges near forms, customer count near hero, certifications in footer.
**Guarantee formula**: "[Type]: [Timeframe] [Promise]. [Supporting detail]. [What happens if not satisfied]."
## Step 7: Page Speed Impact
| Load Time | Conversion Impact |
|---|---|
| 0-2s | Baseline |
| 2-3s | -7% |
| 3-5s | -20% |
| 5-8s | -35% |
| 8s+ | -50%+ |
Target: LCP under 2.5s, CLS under 0.1. Optimize images (WebP, lazy loading). Mobile-responsive with 48x48px tap targets. No intrusive interstitials.
## Step 8: Heatmap Analysis Guidelines
| Pattern | Indicates | Action |
|---|---|---|
| Clicks on non-clickable elements | Expected interactivity | Make clickable or remove affordance |
| Rage clicks | Broken element | Fix the interaction |
| Scroll drop-off before CTA | CTA too far down | Move CTA higher |
| Ignoring a section | Irrelevant content | Remove or rewrite |
| Heavy FAQ engagement | Unanswered questions | Address earlier on page |
**Key Metrics**: CR (by source, device), Bounce rate (target <40%), Scroll depth (60%+ reaching CTA), Form start rate, Form completion rate (target 70%+).
## Step 9: A/B Test Hypotheses
**Template**: IF we [change], THEN [metric] will [increase/decrease] by [%], BECAUSE [reasoning]. PRIORITY: [High/Med/Low].
**Top tests by impact**: (1) Headline angle, (2) CTA copy, (3) Social proof placement, (4) Form length, (5) Hero image/video, (6) Page length, (7) Pricing display, (8) Guarantee addition, (9) Product demo video, (10) Nav bar removal.
## Output Format
```
CRO AUDIT REPORT
=================
Page: [URL] | Current CR: [X%] | Benchmark: [X%] | Traffic: [X/mo]
Estimated Improvement Potential: [X-X%]
CRITICAL ISSUES (Fix Immediately)
1. [Issue] -> [Fix] -> [Expected impact]
HIGH-IMPACT OPPORTUNITIES
1. [Opportunity] -> [Change] -> [Expected impact]
A/B TEST ROADMAP (Priority Order)
Test 1: [Hypothesis] -- Lift: X% -- Effort: Low/Med/High
QUICK WINS (Under 1 Hour)
1. [Change]
DETAILED RECOMMENDATIONS
[Section-by-section with specific copy/design suggestions]
```
Prioritize by impact/effort ratio. Lead with quick wins. Provide specific copy rewrites, not just general advice.
skills/pricing-strategy/SKILL.md
+149
View File
@@ -0,0 +1,149 @@
---
name: pricing-strategy
description: Optimize pricing pages, pricing models, and pricing strategy. Use when the user asks about pricing, pricing pages, how to price a product, tiered pricing, freemium vs. paid, price testing, pricing psychology, or pricing page design. Trigger phrases include "pricing", "pricing page", "how to price", "pricing strategy", "freemium", "tiered pricing", "per-seat pricing", "usage-based pricing", "pricing experiment", "price anchoring", "pricing psychology", "pricing optimization".
---
# Pricing Strategy and Page Optimization
You are an expert pricing strategist. When the user asks you to design pricing, optimize a pricing page, or advise on pricing decisions, follow this framework.
## Step 1: Gather Context
Establish: product/service, target market (B2B/B2C/SMB/enterprise), current pricing, cost structure (COGS, marginal cost), value delivered, competitive pricing, current conversion metrics, revenue model, stage (pre-launch/early/growth/scale).
## Step 2: Pricing Model Selection
| Model | Best For | Pros | Cons |
|---|---|---|---|
| **Freemium** | Viral/network effects, low marginal cost | Large funnel, PLG | Low conversion (2-5%) |
| **Free Trial** (time) | Products needing time to show value | Creates urgency, 10-25% conversion | Requires strong onboarding |
| **Flat Rate** | Simple products, single persona | Easy to understand | Leaves money on table |
| **Per-Seat** | Collaboration tools | Scales with adoption | Discourages spreading |
| **Usage-Based** | API, infrastructure | Aligns with value | Unpredictable revenue |
| **Tiered** | Most SaaS, distinct segments | Captures different WTP | Can overwhelm |
| **Hybrid** | Mature platforms | Predictable + upside | Complex |
**Decision tree**: Low marginal cost + viral -> Freemium. Needs demo time -> Free trial (14d simple, 30d complex). Scales with team -> Per-seat. Scales with consumption -> Usage-based. Distinct segments -> Tiered (3 tiers).
## Step 3: Pricing Psychology
### 1. Price Anchoring
Show highest tier first, compare to alternatives ("vs. hiring at $80K/year"), compare to outcome value ("Generates $10K savings. Costs $99/month").
### 2. Decoy Effect
Add a plan that makes the target plan look obviously better. Example: Basic $9 (5 users), Plus $25 (10 users, DECOY), Pro $29 (25 users, TARGET).
### 3. Charm Pricing
$99 feels cheaper than $100. Use .99 for consumer/SMB, round numbers for enterprise/premium.
### 4. Center-Stage Effect
People choose the middle of 3 options. Make your target plan the middle tier and highlight it.
### 5. Loss Aversion
Frame around what they lose without your product. Use "downgrade" language. Show features they would lose.
### 6. Endowment Effect
Full-featured trials, then keep. Show personalized data that makes leaving painful.
### 7. Price-Quality Signal
Premium products should not underprice. Own higher prices: "We cost more because we deliver more."
## Step 4: Tier Design
### 3-Tier Framework
```
TIER 1 (STARTER): Acquisition. Low/no cost. Enough value to demonstrate product.
Natural upgrade triggers (usage limits, feature gates).
TIER 2 (PRO - TARGET): Revenue engine. Everything most customers need.
Best value perception. Highlight "Most Popular." Price: 2-4x Tier 1.
TIER 3 (ENTERPRISE): Capture high WTP. SSO, audit logs, SLAs, dedicated support.
Custom pricing, sales-assisted. Price: 2-5x Tier 2.
```
### Feature Gating Rules
1. Core value in all tiers -- never gate the primary use case
2. Gate on scale (seats, storage, API calls), not core features
3. Gate on admin/governance (SSO, RBAC, audit logs) for enterprise
4. Gate on support level (email < chat < priority < dedicated)
5. Never gate basic security
6. Create natural upgrade triggers during normal usage
## Step 5: Pricing Page Design
### 3-Column Layout
```
+------------------+---------------------+------------------+
| STARTER | PROFESSIONAL | ENTERPRISE |
| $19/mo | $49/mo | Contact Sales |
| | * MOST POPULAR * | |
| [Start Free] | [Start Free Trial] | [Talk to Sales] |
| Feature list | Everything in | Everything in |
| | Starter, plus: | Pro, plus: |
+------------------+---------------------+------------------+
```
### Page Elements (Top to Bottom)
1. **Headline**: Value-focused ("Simple pricing that scales with you"), not just "Pricing"
2. **Billing toggle**: Monthly/Annual with savings shown as % and $
3. **Tier cards**: Highlighted middle tier, checkmarks/dashes for features
4. **Feature comparison table**: Expandable, grouped by category
5. **Social proof**: Logos, testimonials addressing pricing objections
6. **FAQ**: Can I switch plans? What happens after trial? Discounts? Refunds? Cancel anytime?
7. **Final CTA**: Repeat with value message
### Design Rules
Mobile: stack vertically, most popular first. Price font 2-3x larger. Show per-month price even for annual. CTA buttons same style, different weight for target tier.
## Step 6: Competitive Pricing Analysis
```
PREMIUM (10-30% above): Superior product, strong brand. Requires differentiation.
MARKET (within 10%): Feature parity. Requires non-price differentiators.
PENETRATION (20-40% below): New entrant. Risk of low quality perception.
VALUE-BASED (disconnected): Unique category, measurable ROI. Requires proof.
```
Map competitors: entry price, mid tier, enterprise, model type. Identify gaps and positioning implications.
## Step 7: Pricing A/B Tests
**Test 1: Price Point** -- Raise Pro from $49 to $59. Measure revenue per visitor.
**Test 2: Annual Default** -- Default to annual toggle. Measure 90-day LTV.
**Test 3: Tier Count** -- 4 tiers to 3. Measure conversion rate.
**Test 4: Feature Gating** -- Move feature from Enterprise to Pro. Measure plan distribution + revenue.
**Test 5: Social Proof** -- Add logos/testimonials to pricing page. Measure conversion.
### Safety Rules
Never show different prices to same user on repeat visits. Only test on new visitors. Run 30+ days. Track downstream (churn, LTV). Grandfather existing customers.
## Step 8: Pricing Page Audit Checklist
**Clarity**: Plans understood in 30s? Price prominent? Billing period clear? No jargon?
**Value**: Headline communicates value? "Most Popular" indicator? Target plan emphasized?
**Trust**: Logos/testimonials? Guarantee/trial? FAQ covers top objections?
**Conversion**: CTA specific? Low-commitment option? No credit card for trial? Clear upgrade path?
**Mobile**: Tiers stack well? Table usable? CTAs thumb-friendly?
## Output Format
```
PRICING STRATEGY RECOMMENDATION
================================
RECOMMENDED MODEL: [type] | RATIONALE: [why]
TIER STRUCTURE: [names, prices, features, CTAs]
PRICING PAGE WIREFRAME: [section-by-section layout]
PSYCHOLOGY TACTICS: [techniques and placement]
A/B TEST ROADMAP: [prioritized experiments]
COMPETITIVE CONTEXT: [positioning vs. alternatives]
RISKS AND MITIGATIONS: [downsides and how to address]
```
Show math behind price points when possible. Tie recommendations to specific business context.
skills/programmatic-seo/SKILL.md
+400
View File
@@ -0,0 +1,400 @@
---
name: programmatic-seo
description: Create SEO-optimized pages at scale using programmatic/template-based approaches. Use when the user says "programmatic SEO", "pSEO", "pages at scale", "template pages", "dynamic SEO pages", "auto-generate pages", "landing pages at scale", "city pages", "comparison pages", or wants to create many similar pages targeting different keywords.
---
# Programmatic SEO Skill
You are an expert in programmatic SEO (pSEO) -- the strategy of creating large numbers of targeted pages using templates and data. Help users identify page patterns, build templates, and deploy at scale while avoiding thin content penalties.
## What is Programmatic SEO?
Programmatic SEO creates pages at scale by combining:
- A **page template** (layout + structure)
- A **data source** (database, API, CSV)
- **Dynamic content** (unique per page, not just variable substitution)
- **SEO optimization** (meta tags, internal links, schema)
**Examples of successful pSEO:**
- Zapier: "How to connect {App A} to {App B}" (150K+ pages)
- Nomad List: "{City} for digital nomads" (1000+ city pages)
- Wise: "{Currency A} to {Currency B} exchange rate" (10K+ pages)
- G2: "{Software} reviews" (100K+ product pages)
- Tripadvisor: "Best {type} in {city}" (millions of pages)
## Process
### Step 1: Identify the Page Pattern
Help the user find their pSEO opportunity. Look for patterns where:
**Pattern formula:** `{Modifier} + {Head Term} + {Qualifier}`
| Pattern Type | Formula | Example | Volume Potential |
|-------------|---------|---------|-----------------|
| Location + Service | "{service} in {city}" | "plumber in Austin" | Cities x Services |
| Comparison | "{product A} vs {product B}" | "Notion vs Asana" | nC2 combinations |
| Integration | "{tool A} + {tool B} integration" | "Slack Salesforce integration" | Tools x Tools |
| Template/Example | "{type} template" | "invoice template" | Types count |
| Stats/Data | "{topic} statistics {year}" | "remote work statistics 2025" | Topics x Years |
| Glossary | "What is {term}" | "What is APR" | Terms count |
| Best/Top | "Best {product} for {use case}" | "Best CRM for startups" | Products x Uses |
| Review | "{product} review" | "Airtable review" | Products count |
| Alternative | "{product} alternatives" | "Slack alternatives" | Products count |
| Cost/Pricing | "How much does {service} cost" | "How much does a website cost" | Services count |
**Qualification criteria for a good pSEO opportunity:**
- [ ] Pattern has 100+ possible pages minimum
- [ ] Each combination has measurable search volume (even 10-50/mo is fine at scale)
- [ ] You can generate genuinely useful, unique content for each page
- [ ] The data is available (API, database, web scraping)
- [ ] Competitors aren't already dominating with better data
- [ ] Pages serve real user intent (not just keyword stuffing)
### Step 2: Build the Data Source
Define the data model that powers the pages:
```typescript
// Example: City + Service pages
interface PageData {
// URL parameters
slug: string; // "plumber-in-austin-tx"
city: string; // "Austin"
state: string; // "TX"
service: string; // "plumber"
// SEO fields
title: string; // "Best Plumber in Austin, TX | Top 10 for 2025"
metaDescription: string; // "Find the best plumber in Austin, TX..."
h1: string; // "Best Plumber in Austin, TX"
// Dynamic content
providers: Provider[]; // Local providers data
avgCost: number; // Average cost in this market
reviewCount: number; // Total reviews aggregated
faqs: FAQ[]; // Location-specific FAQs
// Related pages (internal linking)
nearbyPages: string[]; // Nearby cities
relatedServices: string[]; // Related services
}
```
**Data sources to consider:**
- Public APIs (government data, Wikipedia, industry databases)
- Web scraping (with permission/robots.txt compliance)
- User-generated content (reviews, contributions)
- AI-generated unique analysis per entity
- Licensed data (paid data providers)
- Internal product data (for SaaS/e-commerce)
### Step 3: Create the Page Template
Build a template that generates high-quality, unique pages. Critical principle: **each page must provide standalone value.**
#### Template Structure
```markdown
## Page Template: {Pattern Name}
### Above the Fold
- H1: {dynamic title}
- Key stat or hook: {dynamic data point}
- Quick summary: 2-3 sentences with unique data
- CTA (if commercial intent)
### Main Content Section 1: Overview
- {Entity}-specific introduction (NOT generic)
- Unique data point 1: {dynamic}
- Unique data point 2: {dynamic}
- Contextual explanation
### Main Content Section 2: Detailed Analysis
- Comparison table or detailed breakdown
- {Entity}-specific insights
- Data visualizations if applicable
### Main Content Section 3: Practical Information
- How-to or action steps
- Costs, timing, or specifications
- Location-specific or entity-specific details
### Related Content
- Internal links to related pages (same cluster)
- Links to parent/pillar page
- Links to sibling pages
### FAQ Section
- 3-5 questions specific to this entity
- Answers with unique data points
### Schema Markup
- Appropriate structured data for page type
```
#### Avoiding Thin Content
**The #1 risk in pSEO is thin content.** Every page must pass this checklist:
| Check | Requirement | How |
|-------|------------|-----|
| Unique content | > 60% of visible text is unique to this page | Dynamic data, unique analysis, UGC |
| Sufficient depth | > 500 words of substantive content per page | Template sections + dynamic content |
| Unique data | At least 2 data points unique to this entity | API data, calculations, aggregations |
| Useful to visitor | Page answers the searcher's query fully | Match search intent |
| Not auto-generated feel | Reads naturally, not like a template | Varied sentence structures, context |
| Internal value | Links to and from other relevant pages | Related pages section, breadcrumbs |
| Visual content | At least 1 unique or relevant image | Maps, charts, entity images |
### Step 4: Next.js Implementation
#### Dynamic Routes (App Router)
```typescript
// app/[service]/[city]/page.tsx
import { Metadata } from 'next';
import { notFound } from 'next/navigation';
import { getPageData, getAllPages } from '@/lib/pseo-data';
interface Props {
params: { service: string; city: string };
}
// Generate static paths at build time
export async function generateStaticParams() {
const pages = await getAllPages();
return pages.map((page) => ({
service: page.serviceSlug,
city: page.citySlug,
}));
}
// Dynamic meta tags
export async function generateMetadata({ params }: Props): Promise<Metadata> {
const data = await getPageData(params.service, params.city);
if (!data) return {};
return {
title: data.title,
description: data.metaDescription,
alternates: {
canonical: `https://example.com/${params.service}/${params.city}`,
},
openGraph: {
title: data.ogTitle,
description: data.ogDescription,
url: `https://example.com/${params.service}/${params.city}`,
type: 'website',
},
};
}
export default async function Page({ params }: Props) {
const data = await getPageData(params.service, params.city);
if (!data) notFound();
const jsonLd = {
'@context': 'https://schema.org',
'@type': 'WebPage',
name: data.title,
description: data.metaDescription,
// ... additional schema
};
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
{/* Page component tree */}
</>
);
}
```
#### Sitemap Generation
```typescript
// app/sitemap.ts
import { MetadataRoute } from 'next';
import { getAllPages } from '@/lib/pseo-data';
export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
const pages = await getAllPages();
return pages.map((page) => ({
url: `https://example.com/${page.serviceSlug}/${page.citySlug}`,
lastModified: page.updatedAt,
changeFrequency: 'monthly',
priority: 0.7,
}));
}
```
For large sitemaps (50,000+ URLs), use sitemap index:
```typescript
// app/sitemap.xml/route.ts
import { getAllPageCount } from '@/lib/pseo-data';
export async function GET() {
const totalPages = await getAllPageCount();
const sitemapCount = Math.ceil(totalPages / 50000);
const sitemaps = Array.from({ length: sitemapCount }, (_, i) =>
`<sitemap><loc>https://example.com/sitemap-${i}.xml</loc></sitemap>`
).join('');
return new Response(
`<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
${sitemaps}
</sitemapindex>`,
{ headers: { 'Content-Type': 'application/xml' } }
);
}
```
#### Robots.txt Management
```typescript
// app/robots.ts
import { MetadataRoute } from 'next';
export default function robots(): MetadataRoute.Robots {
return {
rules: [
{
userAgent: '*',
allow: '/',
disallow: ['/api/', '/admin/'],
},
],
sitemap: 'https://example.com/sitemap.xml',
};
}
```
### Step 5: Internal Linking Strategy
Internal linking is critical for pSEO. Implement these patterns:
**1. Hub-and-Spoke:**
```
Hub: /services/plumber/
|- /plumber/austin-tx
|- /plumber/dallas-tx
|- /plumber/houston-tx
```
**2. Sibling Links:**
Each city page links to 5-10 nearby city pages for the same service.
**3. Cross-Category Links:**
Each city page links to other services in the same city.
**4. Breadcrumb Navigation:**
```
Home > Services > Plumber > Austin, TX
```
**5. Footer/Sidebar Links:**
Popular pages and category indexes.
**Implementation pattern:**
```typescript
// Internal linking component
function RelatedPages({ currentSlug, relatedPages }) {
return (
<section>
<h2>Related Pages</h2>
<div className="grid grid-cols-2 md:grid-cols-3 gap-4">
{relatedPages.map((page) => (
<Link
key={page.slug}
href={`/${page.slug}`}
className="text-blue-600 hover:underline"
>
{page.title}
</Link>
))}
</div>
</section>
);
}
```
### Step 6: Indexation Management
When deploying thousands of pages, manage indexation carefully:
**Gradual rollout:**
1. Deploy 50-100 pages first
2. Monitor indexation in Google Search Console
3. Check for "Discovered - currently not indexed" and "Crawled - currently not indexed"
4. If indexation rate > 80%, continue deploying in batches of 500-1000
5. If indexation rate < 50%, improve page quality before deploying more
**Indexation signals:**
- Submit sitemap to Google Search Console
- Use IndexNow API (Bing, Yandex) for faster discovery
- Internal link from high-authority existing pages
- Share initial pages on social media for crawl signals
**Quality thresholds:**
- If Google indexes < 30% of pages, your template likely produces thin content
- If pages get indexed then dropped, content quality is borderline
- Monitor "Page experience" and "Core Web Vitals" in GSC for pSEO pages
### Step 7: Meta Tag Formulas
Use these formulas for generating meta tags at scale:
**Title tag formulas (50-60 chars):**
```
"{Primary Keyword} in {Location} | {Brand}"
"Best {Service} in {City}, {State} ({Year})"
"{Product A} vs {Product B}: {Differentiator}"
"{Number} Best {Category} for {Use Case} ({Year})"
"How Much Does {Service} Cost in {City}? ({Year} Pricing)"
```
**Meta description formulas (150-160 chars):**
```
"Find the best {service} in {city}. Compare {X} local providers, read {Y} reviews, and get free quotes. Average cost: ${Z}."
"Detailed comparison of {A} vs {B}. See features, pricing, pros/cons, and which is better for {use case}."
"{X} best {category} for {audience}. We analyzed {Y} options based on {criteria}. Updated for {year}."
```
**H1 formulas:**
```
"Best {Service} in {City}, {State}"
"{Product A} vs {Product B}: Complete Comparison"
"{Number} Best {Category} for {Use Case}"
```
## Output
When helping a user with programmatic SEO, deliver:
1. **Opportunity Analysis** - The pattern, estimated page count, volume potential
2. **Data Model** - TypeScript interface for the page data
3. **Page Template** - Complete template with all sections
4. **Sample Pages** - 2-3 fully rendered example pages
5. **Implementation Plan** - Next.js code for routes, sitemap, robots.txt
6. **Internal Linking Strategy** - How pages connect
7. **Indexation Plan** - Rollout schedule and monitoring metrics
8. **Quality Checklist** - Per-page quality criteria
## Common Pitfalls
- **Template stuffing:** Just swapping city names in identical text = thin content penalty
- **No unique data:** Pages without entity-specific data points add no value
- **Over-generation:** Creating pages for combinations with zero search volume wastes crawl budget
- **Ignoring cannibalization:** Overlapping pages compete with each other. Map one keyword per page.
- **No internal links:** Orphan pages won't get crawled or ranked
- **All at once:** Deploying 100K pages overnight looks unnatural. Batch them.
- **Ignoring noindex:** Some pages may not deserve indexing. Use `noindex` for low-quality or duplicate combinations.
skills/referral-program/SKILL.md
+383
View File
@@ -0,0 +1,383 @@
---
name: referral-program
description: >
Design referral programs and viral growth loops. Use when asked to create
referral systems, viral mechanics, word-of-mouth campaigns, or growth loops.
Trigger phrases: "referral program", "viral loop", "refer a friend",
"word of mouth", "viral coefficient", "referral incentive", "growth loop",
"invite system", "ambassador program".
---
# Referral Program Design
Design effective referral programs and viral loops that drive sustainable growth.
---
## 1. Referral Program Frameworks
### One-Sided Incentives
Only the referrer gets rewarded.
**Best for:**
- Products with strong organic word-of-mouth
- Low-friction signups where the referred user needs no extra motivation
- Cost-sensitive businesses
**Examples:**
- Uber: "$10 credit for every friend you refer"
- Amazon Associates: Commission on referred purchases
**Template:**
```
Refer a friend and get [reward].
Share your unique link: [referral_url]
```
### Two-Sided Incentives
Both referrer and referred user get rewarded.
**Best for:**
- Products requiring activation effort from new users
- Competitive markets where new users need a nudge
- Subscription businesses
**Examples:**
- Dropbox: Both get 500MB extra storage
- Airbnb: Referrer gets $25 credit, friend gets $40 off first stay
- PayPal: Both get $10 when friend makes first transaction
**Template:**
```
Give [friend_reward], get [referrer_reward].
Share your link and you both win: [referral_url]
```
### Tiered Incentives
Rewards increase with number of successful referrals.
**Example tier structure:**
| Referrals | Reward |
|-----------|--------|
| 1 | Free month |
| 3 | Exclusive feature unlock |
| 5 | Premium plan for 3 months |
| 10 | Lifetime premium access |
| 25 | Cash payout or swag box |
**Best for:**
- Creating power referrers / ambassadors
- Products with passionate user bases
- Building a referral leaderboard culture
---
## 2. Viral Coefficient Calculation
The viral coefficient (K-factor) determines whether your referral loop is self-sustaining.
### Formula
```
K = i * c
Where:
i = number of invites sent per user
c = conversion rate of each invite
If K > 1: viral growth (each user brings more than one new user)
If K < 1: referrals supplement but don't replace other acquisition
```
### Example Calculation
```
Users send an average of 5 invites (i = 5)
15% of invites convert to signups (c = 0.15)
K = 5 * 0.15 = 0.75
With 1,000 initial users:
- Cycle 1: 1,000 * 0.75 = 750 new users
- Cycle 2: 750 * 0.75 = 563 new users
- Cycle 3: 563 * 0.75 = 422 new users
- Total after 10 cycles: ~3,570 additional users from referrals
```
### Viral Cycle Time
The speed of the viral loop matters as much as K:
```
Effective growth = K / cycle_time
A K of 0.5 with a 1-day cycle > K of 0.8 with a 30-day cycle
```
### How to Improve K
| Lever | Action |
|-------|--------|
| Increase invites (i) | Make sharing frictionless, prompt at key moments |
| Increase conversion (c) | Better landing page, stronger incentive, social proof |
| Reduce cycle time | Instant reward delivery, real-time notifications |
---
## 3. Referral Channels
### Email Referral
**Pros:** High conversion, personal, trackable
**Cons:** Lower volume, requires email access
Template:
```
Subject: I thought you'd like [Product] -- here's [reward] to try it
Hey [Name],
I've been using [Product] for [time] and it's been great for [specific benefit].
I wanted to share my referral link so you can get [friend_reward]:
[referral_url]
[Your name]
```
### Social Media Sharing
**Pros:** High reach, low effort, viral potential
**Cons:** Lower conversion rate, less personal
Platform-specific templates:
**Twitter/X:**
```
I just [achievement/milestone] with @Product! If you want to try it,
use my link and we both get [reward]: [referral_url]
```
**LinkedIn:**
```
I've been using [Product] to [professional benefit] and the results
have been impressive: [specific metric].
If you're looking for [solution], here's my referral link
(we both get [reward]): [referral_url]
```
**WhatsApp/SMS:**
```
Hey! I've been using [Product] and really like it. They have a
referral deal -- we both get [reward] if you sign up through my link:
[referral_url]
```
### In-App Referral
**Pros:** Highest intent, contextual, frictionless
**Cons:** Only reaches existing users
Best practices:
- Show referral prompt after a success moment (completed task, achievement, positive outcome)
- Pre-populate sharing message
- Show referral progress and rewards earned
- Add referral widget to account/settings page
### Unique Link vs. Referral Code
| Method | Pros | Cons |
|--------|------|------|
| Unique link | Frictionless, works in any channel | Harder to share verbally |
| Referral code | Easy to remember, shareable verbally | Extra step at signup |
| Both | Maximum flexibility | More complex to implement |
---
## 4. Referral Landing Page Template
The page a referred user sees when they click the referral link.
### Structure
```
[Hero Section]
- Headline: "[Referrer's name] invited you to [Product]"
- Subheadline: "Sign up now and get [friend_reward]"
- CTA button: "Claim your [reward]"
[Social Proof]
- "[Referrer's name] and X others use [Product]"
- Logos of known customers
- Key metric: "Trusted by X users"
[Value Proposition]
- 3 key benefits with icons
- Brief product description
[How It Works]
- Step 1: Sign up (takes 30 seconds)
- Step 2: [Key activation action]
- Step 3: Enjoy [reward] + the product
[CTA Repeat]
- "Join [Referrer's name] on [Product]"
- Urgency: "This offer expires in [X days]"
[FAQ]
- When do I get my reward?
- What does [Product] do?
- Is there a catch?
```
---
## 5. Case Studies
### Dropbox (2008-2010)
- **Mechanic:** Two-sided -- both get 500MB extra storage
- **Result:** 3,900% growth in 15 months (100K to 4M users)
- **Key insight:** The reward (storage) was the product itself, making it self-reinforcing
- **Viral coefficient:** Estimated ~0.6-0.7 (supplemental, not purely viral)
### Airbnb (2014)
- **Mechanic:** Two-sided -- $25 travel credit for referrer, $40 off first booking for friend
- **Result:** 300% increase in bookings from referral program 2.0
- **Key insight:** Redesigned referral page to feel like a gift, not spam. Personalized with referrer's photo and travel history
- **Viral coefficient:** Low K but high LTV per referred user
### PayPal (1999-2000)
- **Mechanic:** Two-sided -- $20 per referral (later reduced to $10, then $5)
- **Result:** 7-10% daily growth, reaching 1M users in first year
- **Key insight:** Cash incentive drove massive initial growth, then reduced as network effects kicked in
- **Cost:** $60-70M in referral bonuses, but each user was worth much more in LTV
### Robinhood (2014-2015)
- **Mechanic:** Wait-list with move-up-the-line incentive + free stock for referrals
- **Result:** 1M waitlist signups before launch
- **Key insight:** Scarcity (waitlist) + social proof (your position) + tangible reward (free stock)
---
## 6. Implementation Checklist
### Technical Setup
- [ ] Generate unique referral links/codes per user
- [ ] Build referral tracking (link clicks, signups, activations, rewards)
- [ ] Set up attribution window (how long after click does signup count?)
- [ ] Implement fraud detection (self-referral, fake accounts, VPN abuse)
- [ ] Build reward fulfillment (automatic credit, manual approval, or hybrid)
- [ ] Create referral dashboard for users (invites sent, pending, completed, rewards earned)
### Fraud Prevention
- [ ] Block self-referrals (same IP, same device, same email domain)
- [ ] Require activation action before reward (not just signup)
- [ ] Set daily/weekly referral limits per user
- [ ] Flag suspicious patterns (bulk signups from same IP range)
- [ ] Implement clawback for fraudulent referrals
### Program Design Decisions
| Decision | Options |
|----------|---------|
| Reward type | Cash, credit, product features, swag, charity donation |
| Reward timing | On signup, on activation, on first purchase |
| Reward amount | Test multiple amounts; higher is not always better |
| Expiration | Referral links expire after X days? Rewards expire? |
| Limit | Max referrals per user per month? |
| Eligibility | All users or only paid/active users? |
---
## 7. Referral Email Sequences
### Invite Reminder (to existing users)
```
Subject: You have [X] invites waiting
Hey [Name],
Did you know you can give your friends [reward] and get [reward] for yourself?
You've invited [0/N] friends so far. Share your link:
[referral_url]
Here's what [Product] users are saying:
"[Testimonial]" -- [Customer name]
```
### Referred User Welcome
```
Subject: [Referrer] sent you a gift -- [reward] inside
Hey there!
[Referrer's name] thinks you'd love [Product], so they're giving you [reward] to try it.
[CTA: Claim your reward]
What is [Product]?
[1-sentence description]
What you'll get:
- [Benefit 1]
- [Benefit 2]
- [Benefit 3]
- Plus [friend_reward] from [Referrer's name]
This offer expires in [X] days.
```
### Referral Success Notification
```
Subject: [Friend's name] just signed up -- you earned [reward]!
Great news, [Name]!
[Friend's name] accepted your invitation and signed up for [Product].
Your [reward] has been added to your account.
Keep sharing: you've referred [X] friends so far.
[referral_url]
[Show progress toward next tier if using tiered rewards]
```
---
## 8. Measuring Success
### Key Metrics
| Metric | Formula | Good Benchmark |
|--------|---------|----------------|
| Participation rate | Users who share / total users | 15-25% |
| Shares per user | Total shares / participating users | 3-5 |
| Click-through rate | Link clicks / shares | 20-40% |
| Conversion rate | Signups / link clicks | 10-25% |
| Viral coefficient (K) | Invites * conversion rate | 0.3-0.7 typical |
| Viral cycle time | Avg days from invite to new user's first invite | 1-7 days |
| Referral revenue | Revenue from referred users | Track separately |
| CAC via referral | Reward cost / acquired users | Compare to paid CAC |
### A/B Tests to Run
1. Reward amount ($10 vs $20 vs $50)
2. Reward type (credit vs cash vs feature unlock)
3. One-sided vs two-sided incentive
4. Referral prompt timing (after signup vs after first success)
5. Landing page copy (gift framing vs deal framing)
6. Email subject lines for referral invites
7. Social sharing copy variations
skills/schema-markup/SKILL.md
+608
View File
@@ -0,0 +1,608 @@
---
name: schema-markup
description: Generate Schema.org structured data (JSON-LD) for any page type. Use when the user says "schema markup", "structured data", "JSON-LD", "rich snippets", "rich results", "FAQ schema", "product schema", "article schema", "breadcrumb schema", "organization schema", "how-to schema", "review schema", or asks about structured data for SEO.
---
# Schema Markup Generator Skill
You are an expert in Schema.org structured data and Google's rich results requirements. Generate valid, complete JSON-LD markup that maximizes eligibility for Google rich results.
## Supported Schema Types
This skill supports the following schema types. When the user asks for schema, determine which type(s) are appropriate based on the page content.
### 1. Article / BlogPosting / NewsArticle
**Use for:** Blog posts, news articles, editorial content
**Rich result:** Article carousel, headline in search
```json
{
"@context": "https://schema.org",
"@type": "Article",
"headline": "Your Article Title (max 110 characters)",
"description": "Brief description of the article (max 160 characters)",
"image": [
"https://example.com/image-16x9.jpg",
"https://example.com/image-4x3.jpg",
"https://example.com/image-1x1.jpg"
],
"datePublished": "2025-01-15T08:00:00+00:00",
"dateModified": "2025-01-20T10:30:00+00:00",
"author": [{
"@type": "Person",
"name": "Author Name",
"url": "https://example.com/author/name",
"jobTitle": "Senior Editor",
"sameAs": [
"https://twitter.com/authorhandle",
"https://linkedin.com/in/authorname"
]
}],
"publisher": {
"@type": "Organization",
"name": "Publisher Name",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png",
"width": 600,
"height": 60
}
},
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://example.com/article-url"
},
"wordCount": 2500,
"articleSection": "Technology",
"keywords": ["keyword1", "keyword2", "keyword3"],
"isAccessibleForFree": true
}
```
**Google requirements:**
- `headline` is required (max 110 characters)
- `image` is required (provide 3 aspect ratios: 16:9, 4:3, 1:1; each > 696px wide)
- `datePublished` is required (ISO 8601 format)
- `author.name` is required
- For `NewsArticle`, also add `dateline` if applicable
- For `BlogPosting`, `@type` changes to `"BlogPosting"`
---
### 2. Product
**Use for:** Product pages, e-commerce listings
**Rich result:** Product snippet with price, availability, reviews
```json
{
"@context": "https://schema.org",
"@type": "Product",
"name": "Product Name",
"description": "Product description",
"image": [
"https://example.com/product-1.jpg",
"https://example.com/product-2.jpg"
],
"sku": "SKU-12345",
"mpn": "MPN-67890",
"gtin13": "0123456789012",
"brand": {
"@type": "Brand",
"name": "Brand Name"
},
"offers": {
"@type": "Offer",
"url": "https://example.com/product",
"priceCurrency": "USD",
"price": "99.99",
"priceValidUntil": "2025-12-31",
"availability": "https://schema.org/InStock",
"itemCondition": "https://schema.org/NewCondition",
"seller": {
"@type": "Organization",
"name": "Seller Name"
},
"shippingDetails": {
"@type": "OfferShippingDetails",
"shippingRate": {
"@type": "MonetaryAmount",
"value": "0",
"currency": "USD"
},
"deliveryTime": {
"@type": "ShippingDeliveryTime",
"handlingTime": {
"@type": "QuantitativeValue",
"minValue": 0,
"maxValue": 1,
"unitCode": "DAY"
},
"transitTime": {
"@type": "QuantitativeValue",
"minValue": 1,
"maxValue": 5,
"unitCode": "DAY"
}
},
"shippingDestination": {
"@type": "DefinedRegion",
"addressCountry": "US"
}
},
"hasMerchantReturnPolicy": {
"@type": "MerchantReturnPolicy",
"applicableCountry": "US",
"returnPolicyCategory": "https://schema.org/MerchantReturnFiniteReturnWindow",
"merchantReturnDays": 30,
"returnMethod": "https://schema.org/ReturnByMail",
"returnFees": "https://schema.org/FreeReturn"
}
},
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.5",
"bestRating": "5",
"ratingCount": "142"
},
"review": [{
"@type": "Review",
"author": {
"@type": "Person",
"name": "Reviewer Name"
},
"datePublished": "2025-01-10",
"reviewBody": "Review text here",
"reviewRating": {
"@type": "Rating",
"ratingValue": "5",
"bestRating": "5"
}
}]
}
```
**Google requirements:**
- `name` is required
- `offers`, `review`, or `aggregateRating` - at least one required
- `offers.price` and `offers.priceCurrency` required if offers present
- `offers.availability` must use Schema.org enum values
- As of 2024, `shippingDetails` and `hasMerchantReturnPolicy` are recommended for merchant listings
---
### 3. FAQPage
**Use for:** FAQ sections, Q&A pages
**Rich result:** Expandable FAQ in search results
```json
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is the first question?",
"acceptedAnswer": {
"@type": "Answer",
"text": "<p>The answer with <strong>HTML formatting</strong> allowed. You can include <a href=\"https://example.com\">links</a>.</p>"
}
},
{
"@type": "Question",
"name": "What is the second question?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Plain text answers also work."
}
}
]
}
```
**Google requirements:**
- Each `Question` must have exactly one `acceptedAnswer`
- Answer `text` can include HTML: `<h2>` through `<h6>`, `<br>`, `<ol>`, `<ul>`, `<li>`, `<a>`, `<p>`, `<b>`, `<strong>`, `<i>`, `<em>`
- Must be visible on the page (not hidden behind tabs/accordions without proper implementation)
- Google may show up to 3 FAQ rich results per page
- Do not use for advertising purposes
---
### 4. HowTo
**Use for:** Tutorial pages, step-by-step guides, DIY instructions
**Rich result:** Step-by-step display in search results
```json
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "How to Do Something",
"description": "Brief description of the task",
"image": {
"@type": "ImageObject",
"url": "https://example.com/howto-main.jpg",
"height": "406",
"width": "305"
},
"totalTime": "PT30M",
"estimatedCost": {
"@type": "MonetaryAmount",
"currency": "USD",
"value": "20"
},
"supply": [
{
"@type": "HowToSupply",
"name": "Supply item 1"
},
{
"@type": "HowToSupply",
"name": "Supply item 2"
}
],
"tool": [
{
"@type": "HowToTool",
"name": "Tool 1"
}
],
"step": [
{
"@type": "HowToStep",
"name": "Step 1 Title",
"text": "Detailed instructions for step 1.",
"url": "https://example.com/howto#step1",
"image": "https://example.com/step1.jpg"
},
{
"@type": "HowToStep",
"name": "Step 2 Title",
"text": "Detailed instructions for step 2.",
"url": "https://example.com/howto#step2",
"image": "https://example.com/step2.jpg"
}
]
}
```
**Google requirements:**
- `name` is required
- `step` array is required with at least one step
- Each step needs either `text` or `itemListElement` with `HowToDirection`/`HowToTip`
- `totalTime` uses ISO 8601 duration format (PT1H30M = 1 hour 30 minutes)
- Do not use HowTo for recipes (use Recipe schema instead)
---
### 5. Organization
**Use for:** Homepage, about page, company information
**Rich result:** Knowledge panel, logo in search
```json
{
"@context": "https://schema.org",
"@type": "Organization",
"name": "Company Name",
"alternateName": "Company Abbreviation",
"url": "https://example.com",
"logo": {
"@type": "ImageObject",
"url": "https://example.com/logo.png",
"width": 512,
"height": 512
},
"description": "Company description",
"foundingDate": "2020-01-01",
"founder": {
"@type": "Person",
"name": "Founder Name"
},
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"contactPoint": [{
"@type": "ContactPoint",
"telephone": "+1-555-555-5555",
"contactType": "customer service",
"areaServed": "US",
"availableLanguage": "English"
}],
"sameAs": [
"https://twitter.com/company",
"https://linkedin.com/company/company",
"https://facebook.com/company",
"https://github.com/company"
],
"numberOfEmployees": {
"@type": "QuantitativeValue",
"minValue": 10,
"maxValue": 50
}
}
```
---
### 6. LocalBusiness
**Use for:** Local business pages, Google Business Profile support
**Rich result:** Local business panel, map results
```json
{
"@context": "https://schema.org",
"@type": "LocalBusiness",
"@id": "https://example.com/#business",
"name": "Business Name",
"description": "Business description",
"url": "https://example.com",
"telephone": "+1-555-555-5555",
"email": "info@example.com",
"image": "https://example.com/storefront.jpg",
"logo": "https://example.com/logo.png",
"priceRange": "$$",
"address": {
"@type": "PostalAddress",
"streetAddress": "123 Main St",
"addressLocality": "San Francisco",
"addressRegion": "CA",
"postalCode": "94102",
"addressCountry": "US"
},
"geo": {
"@type": "GeoCoordinates",
"latitude": "37.7749",
"longitude": "-122.4194"
},
"openingHoursSpecification": [
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
"opens": "09:00",
"closes": "17:00"
},
{
"@type": "OpeningHoursSpecification",
"dayOfWeek": "Saturday",
"opens": "10:00",
"closes": "14:00"
}
],
"aggregateRating": {
"@type": "AggregateRating",
"ratingValue": "4.7",
"bestRating": "5",
"ratingCount": "312"
},
"areaServed": {
"@type": "City",
"name": "San Francisco"
},
"hasMap": "https://maps.google.com/?cid=123456789"
}
```
**Google requirements:**
- `name`, `address` are required
- Use specific subtypes when possible: `Restaurant`, `Dentist`, `LegalService`, `RealEstateAgent`, etc.
- `geo` coordinates should be accurate to the business location
- `openingHoursSpecification` must reflect actual business hours
---
### 7. BreadcrumbList
**Use for:** Any page with breadcrumb navigation
**Rich result:** Breadcrumb trail in search results
```json
{
"@context": "https://schema.org",
"@type": "BreadcrumbList",
"itemListElement": [
{
"@type": "ListItem",
"position": 1,
"name": "Home",
"item": "https://example.com"
},
{
"@type": "ListItem",
"position": 2,
"name": "Category",
"item": "https://example.com/category"
},
{
"@type": "ListItem",
"position": 3,
"name": "Current Page Title"
}
]
}
```
**Google requirements:**
- `position` must be sequential starting at 1
- Last item should not have `item` (it's the current page)
- Must match the visible breadcrumb on the page
---
### 8. Review / AggregateRating
**Use for:** Review pages, product reviews, service reviews
**Rich result:** Star rating in search results
```json
{
"@context": "https://schema.org",
"@type": "Review",
"name": "Review Title",
"reviewBody": "Full review text...",
"datePublished": "2025-01-15",
"author": {
"@type": "Person",
"name": "Reviewer Name"
},
"itemReviewed": {
"@type": "Product",
"name": "Product Being Reviewed",
"image": "https://example.com/product.jpg"
},
"reviewRating": {
"@type": "Rating",
"ratingValue": "4",
"bestRating": "5",
"worstRating": "1"
},
"publisher": {
"@type": "Organization",
"name": "Review Site Name"
}
}
```
**Google requirements:**
- `author` is required (must be a valid `Person` or `Organization`)
- `itemReviewed` is required
- `reviewRating` is recommended
- Self-serving reviews (reviewing your own product) are against guidelines
## Multi-Schema Pages
Most pages need multiple schema types. Combine them using `@graph`:
```json
{
"@context": "https://schema.org",
"@graph": [
{
"@type": "Organization",
"@id": "https://example.com/#organization",
"name": "Company Name",
"url": "https://example.com",
"logo": "https://example.com/logo.png"
},
{
"@type": "WebSite",
"@id": "https://example.com/#website",
"url": "https://example.com",
"name": "Site Name",
"publisher": { "@id": "https://example.com/#organization" }
},
{
"@type": "WebPage",
"@id": "https://example.com/page/#webpage",
"url": "https://example.com/page/",
"name": "Page Title",
"isPartOf": { "@id": "https://example.com/#website" }
},
{
"@type": "Article",
"mainEntityOfPage": { "@id": "https://example.com/page/#webpage" },
"headline": "Article Title",
"author": { "@type": "Person", "name": "Author" },
"publisher": { "@id": "https://example.com/#organization" },
"datePublished": "2025-01-15"
},
{
"@type": "BreadcrumbList",
"itemListElement": [
{ "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com" },
{ "@type": "ListItem", "position": 2, "name": "Blog", "item": "https://example.com/blog" },
{ "@type": "ListItem", "position": 3, "name": "Article Title" }
]
}
]
}
```
## Generation Process
When the user asks for schema markup:
1. **Determine page type** - Ask what kind of page this is for (or infer from context)
2. **Gather information** - Ask for or collect the required fields. If the user provides a URL, fetch it to extract data.
3. **Select schema types** - Choose all applicable schemas (most pages need 2-4 types)
4. **Generate JSON-LD** - Create complete, valid markup
5. **Validate** - Check against Google's requirements for each type
6. **Provide implementation instructions** - Tell the user exactly where to place it
## Implementation Instructions
For **Next.js App Router**:
```tsx
// In your page component or layout
export default function Page() {
const jsonLd = {/* generated schema */};
return (
<>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
{/* page content */}
</>
);
}
```
For **Next.js with next/head (Pages Router)**:
```tsx
import Head from 'next/head';
export default function Page() {
const jsonLd = {/* generated schema */};
return (
<>
<Head>
<script
type="application/ld+json"
dangerouslySetInnerHTML={{ __html: JSON.stringify(jsonLd) }}
/>
</Head>
{/* page content */}
</>
);
}
```
For **plain HTML**:
```html
<head>
<script type="application/ld+json">
{/* generated schema */}
</script>
</head>
```
## Validation
After generating the markup, remind the user to validate using:
1. **Google Rich Results Test:** https://search.google.com/test/rich-results
2. **Schema.org Validator:** https://validator.schema.org/
## Common Mistakes to Avoid
- Do not add schema for content that is not visible on the page
- Do not use `Review` schema for self-serving reviews of your own business
- Do not markup content behind a paywall as `isAccessibleForFree: true`
- Do not use fake or placeholder data in production schema
- Do not add `AggregateRating` without actual user reviews
- Always use absolute URLs, never relative
- Always use ISO 8601 date format
- `priceValidUntil` must be a future date
- `availability` must use full Schema.org URL (e.g., `https://schema.org/InStock`)
- Image URLs must be crawlable and indexable
skills/search-console/SKILL.md
+403
View File
@@ -0,0 +1,403 @@
---
name: search-console
description: >
Pull Google Search Console data and perform search performance analysis.
Use when asked about search rankings, clicks, impressions, CTR, index coverage,
Core Web Vitals, or sitemap status. Trigger phrases: "search console", "GSC",
"search performance", "clicks and impressions", "CTR analysis", "index coverage",
"core web vitals", "URL inspection", "sitemap status", "ranking data",
"search queries", "keyword positions".
---
# Google Search Console
Pull search performance data, index coverage, and Core Web Vitals from Google Search Console API.
## Prerequisites
Requires Google OAuth credentials:
- `GOOGLE_CLIENT_ID`
- `GOOGLE_CLIENT_SECRET`
- A valid OAuth access token with `https://www.googleapis.com/auth/webmasters.readonly` scope
Set credentials in `.env`, `.env.local`, or `~/.claude/.env.global`.
### Getting an Access Token
```bash
# Step 1: Authorization URL (user visits in browser)
echo "https://accounts.google.com/o/oauth2/v2/auth?client_id=${GOOGLE_CLIENT_ID}&redirect_uri=urn:ietf:wg:oauth:2.0:oob&scope=https://www.googleapis.com/auth/webmasters.readonly&response_type=code&access_type=offline"
# Step 2: Exchange code for tokens
curl -s -X POST "https://oauth2.googleapis.com/token" \
-d "code={AUTH_CODE}" \
-d "client_id=${GOOGLE_CLIENT_ID}" \
-d "client_secret=${GOOGLE_CLIENT_SECRET}" \
-d "redirect_uri=urn:ietf:wg:oauth:2.0:oob" \
-d "grant_type=authorization_code"
# Step 3: Refresh expired token
curl -s -X POST "https://oauth2.googleapis.com/token" \
-d "refresh_token={REFRESH_TOKEN}" \
-d "client_id=${GOOGLE_CLIENT_ID}" \
-d "client_secret=${GOOGLE_CLIENT_SECRET}" \
-d "grant_type=refresh_token"
```
### Listing Available Sites
```bash
curl -s -H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
"https://www.googleapis.com/webmasters/v3/sites" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for site in data.get('siteEntry', []):
print(f\"{site['siteUrl']} | Permission: {site['permissionLevel']}\")
"
```
The site URL format is either `https://example.com/` (URL prefix) or `sc-domain:example.com` (domain property).
---
## 1. Search Performance Report
The core report: queries, pages, clicks, impressions, CTR, and average position.
### API Endpoint
```
POST https://www.googleapis.com/webmasters/v3/sites/{siteUrl}/searchAnalytics/query
```
Note: The `{siteUrl}` must be URL-encoded (e.g., `https%3A%2F%2Fexample.com%2F` or `sc-domain%3Aexample.com`).
### Top Queries
```bash
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["query"],
"rowLimit": 50,
"startRow": 0
}'
```
### Top Pages
```bash
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["page"],
"rowLimit": 50
}'
```
### Query + Page Combination
```bash
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["query", "page"],
"rowLimit": 100,
"dimensionFilterGroups": [{
"filters": [{
"dimension": "page",
"operator": "contains",
"expression": "/blog/"
}]
}]
}'
```
### Available Dimensions
| Dimension | Description |
|-----------|-------------|
| `query` | Search query |
| `page` | URL |
| `country` | Country code (ISO 3166-1 alpha-3) |
| `device` | `DESKTOP`, `MOBILE`, `TABLET` |
| `date` | Individual date |
| `searchAppearance` | Rich result type |
### Response Parsing
```bash
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f\"{'Query':<50} {'Clicks':>8} {'Impr':>8} {'CTR':>8} {'Pos':>6}\")
print('-' * 82)
for row in data.get('rows', []):
keys = ' + '.join(row.get('keys', []))
print(f\"{keys:<50} {row['clicks']:>8} {row['impressions']:>8} {row['ctr']*100:>7.1f}% {row['position']:>6.1f}\")
"
```
---
## 2. Search Performance by Date
Track daily trends for queries and pages.
```bash
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["date"],
"rowLimit": 1000
}'
```
To track a specific query over time:
```bash
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["date"],
"dimensionFilterGroups": [{
"filters": [{
"dimension": "query",
"operator": "equals",
"expression": "your target keyword"
}]
}]
}'
```
---
## 3. Index Coverage (URL Inspection API)
Check if a specific URL is indexed.
### Endpoint
```
POST https://searchconsole.googleapis.com/v1/urlInspection/index:inspect
```
### Example curl
```bash
curl -s -X POST \
"https://searchconsole.googleapis.com/v1/urlInspection/index:inspect" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"inspectionUrl": "https://example.com/page-to-check",
"siteUrl": "sc-domain:example.com"
}'
```
### Response Fields
| Field | Description |
|-------|-------------|
| `inspectionResult.indexStatusResult.coverageState` | `Submitted and indexed`, `Crawled - currently not indexed`, etc. |
| `inspectionResult.indexStatusResult.robotsTxtState` | `ALLOWED` or `DISALLOWED` |
| `inspectionResult.indexStatusResult.indexingState` | `INDEXING_ALLOWED` or `INDEXING_NOT_ALLOWED` |
| `inspectionResult.indexStatusResult.lastCrawlTime` | When Googlebot last crawled |
| `inspectionResult.indexStatusResult.crawledAs` | `DESKTOP` or `MOBILE` |
| `inspectionResult.mobileUsabilityResult.verdict` | `PASS`, `FAIL`, or `VERDICT_UNSPECIFIED` |
---
## 4. Sitemaps
List and check sitemap status.
### List Sitemaps
```bash
curl -s -H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/sitemaps" \
| python3 -c "
import json, sys
data = json.load(sys.stdin)
for sm in data.get('sitemap', []):
print(f\"URL: {sm['path']}\")
print(f\" Type: {sm.get('type','')} | Submitted: {sm.get('lastSubmitted','')}\")
print(f\" URLs discovered: {sm.get('contents',[{}])[0].get('submitted','?')} | Indexed: {sm.get('contents',[{}])[0].get('indexed','?')}\")
print()
"
```
### Submit a Sitemap
```bash
curl -s -X PUT -H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/sitemaps/https%3A%2F%2Fexample.com%2Fsitemap.xml"
```
---
## 5. Opportunity Identification
Use Search Console data to find SEO opportunities.
### Low-Hanging Fruit: High Impressions, Low CTR
Queries with many impressions but low CTR suggest the title/description needs optimization.
```bash
# Pull queries, then filter for: impressions > 100 AND ctr < 0.03 AND position < 20
curl -s -X POST \
"https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query" \
-H "Authorization: Bearer ${GSC_ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"startDate": "2024-01-01",
"endDate": "2024-03-31",
"dimensions": ["query", "page"],
"rowLimit": 1000
}' | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('== Low CTR Opportunities (High impressions, low CTR, good position) ==')
print(f\"{'Query':<40} {'Page':<40} {'Impr':>6} {'CTR':>7} {'Pos':>5}\")
for row in data.get('rows', []):
if row['impressions'] > 100 and row['ctr'] < 0.03 and row['position'] < 20:
print(f\"{row['keys'][0]:<40} {row['keys'][1][-40:]:<40} {row['impressions']:>6} {row['ctr']*100:>6.1f}% {row['position']:>5.1f}\")
"
```
### Striking Distance: Position 5-20
Queries ranking on page 1-2 that could be pushed to top 5 with content optimization.
```bash
# Filter for position between 5 and 20 with decent impressions
curl -s -X POST "..." | python3 -c "
import json, sys
data = json.load(sys.stdin)
print('== Striking Distance Keywords (Position 5-20) ==')
opps = [r for r in data.get('rows',[]) if 5 <= r['position'] <= 20 and r['impressions'] > 50]
opps.sort(key=lambda x: x['impressions'], reverse=True)
for row in opps[:30]:
print(f\"{row['keys'][0]:<50} Pos: {row['position']:>5.1f} Impr: {row['impressions']:>6} Clicks: {row['clicks']:>4}\")
"
```
### Cannibalization Detection
Find queries where multiple pages compete for the same keyword.
```bash
# Pull query+page data, then group by query to find duplicates
curl -s -X POST "..." | python3 -c "
import json, sys
from collections import defaultdict
data = json.load(sys.stdin)
query_pages = defaultdict(list)
for row in data.get('rows', []):
query_pages[row['keys'][0]].append({
'page': row['keys'][1],
'clicks': row['clicks'],
'impressions': row['impressions'],
'position': row['position']
})
print('== Keyword Cannibalization (multiple pages for same query) ==')
for query, pages in sorted(query_pages.items(), key=lambda x: -sum(p['impressions'] for p in x[1])):
if len(pages) > 1:
total_impr = sum(p['impressions'] for p in pages)
if total_impr > 100:
print(f\"\nQuery: {query} ({total_impr} total impressions)\")
for p in sorted(pages, key=lambda x: -x['impressions']):
print(f\" {p['page'][-60:]} Pos: {p['position']:.1f} Impr: {p['impressions']} Clicks: {p['clicks']}\")
"
```
---
## Workflow: Full Search Performance Audit
When asked for a complete GSC audit:
1. **Overall Metrics**: Total clicks, impressions, avg CTR, avg position for last 90 days vs previous 90 days
2. **Top 30 Queries**: By clicks, with CTR and position
3. **Top 20 Pages**: By clicks, with CTR and position
4. **Device Breakdown**: Desktop vs mobile performance
5. **Low-Hanging Fruit**: High impressions + low CTR opportunities
6. **Striking Distance**: Position 5-20 keywords with optimization potential
7. **Cannibalization**: Queries with multiple competing pages
8. **Index Coverage**: Spot-check important URLs
9. **Sitemap Health**: Verify sitemaps are submitted and indexed
### Report Format
```
## Search Console Audit: {domain}
### Period: {date range}
### Summary
| Metric | Current | Previous | Change |
|--------|---------|----------|--------|
| Clicks | X | Y | +Z% |
| Impressions | X | Y | +Z% |
| Avg CTR | X% | Y% | +Z pp |
| Avg Position | X | Y | +Z |
### Top Queries
| Query | Clicks | Impressions | CTR | Position |
|-------|--------|-------------|-----|----------|
| ... | ... | ... | ... | ... |
### Optimization Opportunities
#### Title/Description Optimization (High Impressions, Low CTR)
1. "{query}" - {impressions} impressions, {ctr}% CTR, position {pos}
- Page: {url}
- Recommendation: ...
#### Content Optimization (Striking Distance)
1. "{query}" - position {pos}, {impressions} impressions
- Action: Add {query} to H2, expand section on {topic}
#### Cannibalization Fixes
1. "{query}" appears on {n} pages
- Consolidate to: {best_url}
- Redirect/noindex: {other_urls}
```
---
## Rate Limits
- Search Analytics API: 1,200 queries per minute
- URL Inspection API: 2,000 inspections per day per property
- Data freshness: Search data is typically 2-3 days behind
## Common Errors
| Error | Cause | Fix |
|-------|-------|-----|
| 403 | No access to this property | Verify ownership in GSC |
| 400 | Invalid date range | Dates must be within last 16 months |
| Empty rows | No data matching filters | Broaden date range or remove filters |
skills/semrush-research/SKILL.md
+298
View File
@@ -0,0 +1,298 @@
---
name: semrush-research
description: >
SEO and competitive intelligence via the SemRush API. Use when asked to
research competitors, analyze domains, find keyword opportunities, check
backlinks, or estimate traffic. Trigger phrases: "competitor analysis",
"domain overview", "keyword research", "backlink check", "traffic estimate",
"SEO intelligence", "semrush", "competitive research".
---
# SemRush Research
Pull live SEO and competitive intelligence data from the SemRush API.
## Prerequisites
Requires `SEMRUSH_API_KEY` set in `.env`, `.env.local`, or `~/.claude/.env.global`.
```bash
# Verify the key is available
echo "SEMRUSH_API_KEY is ${SEMRUSH_API_KEY:+set}"
```
If the key is not set, instruct the user:
> You need a SemRush API key. Get one at https://www.semrush.com/api/
> Then add `SEMRUSH_API_KEY=your_key` to your `.env` file.
## API Base
All requests go to `https://api.semrush.com/` with the API key passed as `&key={SEMRUSH_API_KEY}`.
Responses are semicolon-delimited CSV. The first line is the header row. Parse accordingly.
---
## 1. Domain Overview
Get a high-level snapshot of any domain's organic and paid search performance.
### Endpoint
```
https://api.semrush.com/?type=domain_ranks&key={KEY}&export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain={domain}
```
### Export Columns
| Column | Meaning |
|--------|---------|
| `Dn` | Domain |
| `Rk` | SemRush Rank |
| `Or` | Organic keywords count |
| `Ot` | Organic traffic estimate |
| `Oc` | Organic traffic cost ($) |
| `Ad` | Paid keywords count |
| `At` | Paid traffic estimate |
| `Ac` | Paid traffic cost ($) |
### Example curl
```bash
curl -s "https://api.semrush.com/?type=domain_ranks&key=${SEMRUSH_API_KEY}&export_columns=Dn,Rk,Or,Ot,Oc,Ad,At,Ac&domain=example.com"
```
### Parsing the Response
```bash
# Response format (semicolon-delimited):
# Dn;Rk;Or;Ot;Oc;Ad;At;Ac
# example.com;12345;8234;145000;234500;120;3400;5600
# Parse with awk
curl -s "..." | awk -F';' 'NR==2 {
printf "Domain: %s\nSemRush Rank: %s\nOrganic Keywords: %s\nOrganic Traffic: %s\nOrganic Traffic Cost: $%s\nPaid Keywords: %s\nPaid Traffic: %s\nPaid Traffic Cost: $%s\n",
$1,$2,$3,$4,$5,$6,$7,$8
}'
```
---
## 2. Keyword Overview
Get search volume, CPC, competition, and SERP features for a keyword.
### Endpoint
```
https://api.semrush.com/?type=phrase_all&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td
```
### Export Columns
| Column | Meaning |
|--------|---------|
| `Ph` | Keyword phrase |
| `Nq` | Search volume (monthly) |
| `Cp` | CPC (USD) |
| `Co` | Competition (0-1) |
| `Nr` | Number of results |
| `Td` | Trend (12 months, comma-separated) |
### Example curl
```bash
curl -s "https://api.semrush.com/?type=phrase_all&key=${SEMRUSH_API_KEY}&phrase=content+marketing&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td"
```
### Supported Databases
Use `&database=XX` where XX is: `us`, `uk`, `ca`, `au`, `de`, `fr`, `es`, `it`, `br`, `in`, `jp`.
---
## 3. Related Keywords
Find semantically related keywords for content planning and gap analysis.
### Endpoint
```
https://api.semrush.com/?type=phrase_related&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=20
```
### Example curl
```bash
curl -s "https://api.semrush.com/?type=phrase_related&key=${SEMRUSH_API_KEY}&phrase=project+management&database=us&export_columns=Ph,Nq,Cp,Co,Nr,Td&display_limit=20"
```
### Parsing Multiple Rows
```bash
curl -s "..." | awk -F';' 'NR>1 { printf "%-40s Vol: %-8s CPC: $%-6s Comp: %s\n", $1, $2, $3, $4 }'
```
---
## 4. Keyword Difficulty
Estimate how hard it is to rank for a keyword.
### Endpoint
```
https://api.semrush.com/?type=phrase_kdi&key={KEY}&phrase={keyword}&database=us&export_columns=Ph,Kd
```
| Column | Meaning |
|--------|---------|
| `Ph` | Keyword |
| `Kd` | Keyword difficulty (0-100) |
Interpretation:
- 0-29: Easy - achievable with quality content
- 30-49: Moderate - needs solid content + some backlinks
- 50-69: Hard - needs strong domain authority + backlinks
- 70-84: Very hard - requires established authority
- 85-100: Extremely hard - dominated by top-tier domains
---
## 5. Domain Organic Keywords
See which keywords a domain ranks for organically.
### Endpoint
```
https://api.semrush.com/?type=domain_organic&key={KEY}&domain={domain}&database=us&export_columns=Ph,Po,Nq,Cp,Url,Tr,Tc&display_limit=50&display_sort=tr_desc
```
| Column | Meaning |
|--------|---------|
| `Ph` | Keyword |
| `Po` | Position |
| `Nq` | Search volume |
| `Cp` | CPC |
| `Url` | Ranking URL |
| `Tr` | Traffic (%) |
| `Tc` | Traffic cost |
### Example curl
```bash
curl -s "https://api.semrush.com/?type=domain_organic&key=${SEMRUSH_API_KEY}&domain=hubspot.com&database=us&export_columns=Ph,Po,Nq,Cp,Url,Tr,Tc&display_limit=20&display_sort=tr_desc"
```
---
## 6. Backlink Overview
Get a summary of a domain's backlink profile.
### Endpoint
```
https://api.semrush.com/analytics/v1/?key={KEY}&type=backlinks_overview&target={domain}&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,follows_num,nofollows_num,texts_num,images_num
```
### Example curl
```bash
curl -s "https://api.semrush.com/analytics/v1/?key=${SEMRUSH_API_KEY}&type=backlinks_overview&target=example.com&target_type=root_domain&export_columns=total,domains_num,urls_num,ips_num,follows_num,nofollows_num,texts_num,images_num"
```
---
## 7. Competitor Discovery
Find domains competing for the same organic keywords.
### Endpoint
```
https://api.semrush.com/?type=domain_organic_organic&key={KEY}&domain={domain}&database=us&export_columns=Dn,Cr,Np,Or,Ot,Oc,Ad&display_limit=10
```
| Column | Meaning |
|--------|---------|
| `Dn` | Competitor domain |
| `Cr` | Competition level |
| `Np` | Common keywords |
| `Or` | Organic keywords |
| `Ot` | Organic traffic |
| `Oc` | Organic traffic cost |
| `Ad` | Paid keywords |
### Example curl
```bash
curl -s "https://api.semrush.com/?type=domain_organic_organic&key=${SEMRUSH_API_KEY}&domain=notion.so&database=us&export_columns=Dn,Cr,Np,Or,Ot,Oc,Ad&display_limit=10"
```
---
## 8. Traffic Analytics (Estimates)
Estimate a domain's overall traffic sources and engagement.
### Endpoint
```
https://api.semrush.com/analytics/ta/api/v3/summary?key={KEY}&targets={domain}&display_date=2024-01-01&country=us&export_columns=target,visits,users,bounce_rate,pages_per_visit,avg_visit_duration
```
---
## Workflow: Full Competitive Analysis
When the user asks for a full competitive analysis, run these steps in order:
1. **Domain Overview** - Get the target domain's metrics
2. **Competitor Discovery** - Find top 5-10 competitors
3. **Domain Overview** for each competitor - Compare metrics
4. **Top Keywords** for each domain - Find keyword gaps
5. **Backlink Overview** for each domain - Compare link profiles
### Output Format
Present results as a comparison table:
```
| Metric | target.com | competitor1.com | competitor2.com |
|---------------------|-----------|-----------------|-----------------|
| SemRush Rank | ... | ... | ... |
| Organic Keywords | ... | ... | ... |
| Organic Traffic | ... | ... | ... |
| Traffic Cost | ... | ... | ... |
| Backlinks | ... | ... | ... |
| Referring Domains | ... | ... | ... |
```
Then highlight:
- **Keyword gaps**: Keywords competitors rank for but target does not
- **Quick wins**: Keywords where target ranks positions 5-20 (improvement opportunities)
- **Content gaps**: Topics competitors cover but target does not
- **Backlink opportunities**: Sites linking to competitors but not target
## Rate Limits and Costs
- Each API call costs API units (check your plan)
- Use `&display_limit=` to control result count (default varies by endpoint)
- Cache results locally when doing multi-step analysis to avoid redundant calls
- Domain overview calls are cheapest; backlink and traffic analytics cost more
## Error Handling
| Error | Meaning |
|-------|---------|
| `ERROR 50 :: NOTHING FOUND` | No data for this query |
| `ERROR 120 :: WRONG KEY` | Invalid API key |
| `ERROR 130 :: LIMIT EXCEEDED` | API unit limit reached |
| Empty response | Usually means no data available for the query parameters |
When you get "NOTHING FOUND", try:
- Different database (e.g., `uk` instead of `us`)
- Root domain instead of subdomain
- Broader keyword phrase
skills/seo-audit/SKILL.md
+234
View File
@@ -0,0 +1,234 @@
---
name: seo-audit
description: Run a full technical and on-page SEO audit on any website or page. Use when the user says "audit my site", "SEO check", "technical SEO review", "site health", "check my SEO", "what's wrong with my site", or provides a URL and asks for SEO feedback.
---
# SEO Audit Skill
You are an expert SEO auditor. When given a URL or domain, perform a comprehensive technical and on-page SEO audit. Produce a structured report with scores, issues, and prioritized fix recommendations.
## Audit Process
### Step 1: Gather Data
Use the available tools to collect information about the target site:
1. **Fetch the page** using WebFetch to get the HTML content
2. **Check robots.txt** at `{domain}/robots.txt`
3. **Check sitemap** at `{domain}/sitemap.xml` (also check robots.txt for sitemap location)
4. **Fetch key pages** - homepage, a few inner pages, blog post if available
5. **Check PageSpeed** via `https://www.googleapis.com/pagespeedonline/v5/runPagespeed?url={URL}&strategy=mobile` and `&strategy=desktop`
If the user provides a project codebase, also inspect:
- Next.js `next.config.js`, `app/layout.tsx`, `middleware.ts`
- Meta tag generation in page components
- `<head>` contents, Open Graph tags
- Sitemap generation logic
- Robots.txt file
### Step 2: Audit Categories
Evaluate each category below. Score each 0-100 and list specific issues found.
---
#### Category 1: Crawlability & Indexation (Weight: 20%)
Check these items:
| Check | What to look for | Severity |
|-------|-----------------|----------|
| robots.txt | Exists, not blocking important pages, allows search engines | Critical |
| XML Sitemap | Exists, valid XML, includes all important URLs, no 404s listed | Critical |
| Canonical tags | Present on all pages, self-referencing, no conflicting canonicals | High |
| Hreflang tags | Present if multi-language, valid language codes, reciprocal tags | Medium |
| Noindex tags | Not accidentally applied to important pages | Critical |
| URL structure | Clean slugs, no excessive parameters, logical hierarchy | Medium |
| Redirect chains | No chains longer than 2 hops, no redirect loops | High |
| 404 pages | Custom 404, no soft 404s, broken internal links | Medium |
| Pagination | rel=prev/next or proper infinite scroll handling | Low |
| Crawl depth | Important pages within 3 clicks of homepage | Medium |
**Scoring formula:**
- Start at 100
- Critical issue: -25 each
- High issue: -15 each
- Medium issue: -8 each
- Low issue: -3 each
- Minimum score: 0
---
#### Category 2: Technical Foundations (Weight: 25%)
| Check | What to look for | Severity |
|-------|-----------------|----------|
| HTTPS | Site uses HTTPS, no mixed content, proper redirects from HTTP | Critical |
| Mobile-friendliness | Responsive design, viewport meta tag, no horizontal scroll, tap targets 48px+ | Critical |
| Core Web Vitals - LCP | Largest Contentful Paint < 2.5s (good), < 4s (needs improvement) | High |
| Core Web Vitals - FID/INP | First Input Delay < 100ms / Interaction to Next Paint < 200ms | High |
| Core Web Vitals - CLS | Cumulative Layout Shift < 0.1 (good), < 0.25 (needs improvement) | High |
| Page speed - mobile | Performance score > 90 (good), > 50 (needs improvement) | High |
| Page speed - desktop | Performance score > 90 (good), > 50 (needs improvement) | Medium |
| Render blocking resources | Critical CSS inlined, JS deferred/async | Medium |
| Image optimization | WebP/AVIF format, proper sizing, lazy loading below fold | Medium |
| Server response time | TTFB < 200ms (good), < 500ms (acceptable) | High |
| Compression | Gzip or Brotli enabled | Medium |
| HTTP/2 or HTTP/3 | Modern protocol in use | Low |
| JavaScript rendering | Content visible without JS (for search engines) | High |
**Scoring:** Same formula as Category 1.
---
#### Category 3: On-Page Optimization (Weight: 25%)
For each page analyzed, check:
| Check | What to look for | Severity |
|-------|-----------------|----------|
| Title tag | Exists, 50-60 characters, includes primary keyword, unique per page | Critical |
| Meta description | Exists, 150-160 characters, includes keyword, compelling CTA | High |
| H1 tag | Exactly one per page, includes primary keyword | Critical |
| Heading hierarchy | Logical H1 > H2 > H3 nesting, no skipped levels | Medium |
| Keyword in first 100 words | Primary keyword appears naturally in opening paragraph | Medium |
| Content length | Adequate for topic (check against SERP competitors) | Medium |
| Internal links | 3-10 relevant internal links per page, descriptive anchor text | High |
| External links | Links to authoritative sources where appropriate | Low |
| Image alt text | All images have descriptive alt text with keywords where natural | Medium |
| URL slug | Includes primary keyword, short, hyphenated, lowercase | Medium |
| Open Graph tags | og:title, og:description, og:image present and correct | Medium |
| Twitter Card tags | twitter:card, twitter:title, twitter:description present | Low |
**Scoring:** Same formula as Category 1.
---
#### Category 4: Content Quality (Weight: 15%)
Evaluate these qualitative factors:
| Factor | What to assess | Score range |
|--------|---------------|-------------|
| E-E-A-T signals | Author bios, credentials, about page, contact info, bylines | 0-20 |
| Content freshness | Last updated dates, regular publishing cadence | 0-15 |
| Content depth | Comprehensive coverage vs. thin content, word count vs. competitors | 0-20 |
| Originality | Unique insights, not just rehashed competitor content | 0-15 |
| Readability | Short paragraphs, subheadings, lists, Flesch reading ease 60-70 | 0-15 |
| Media richness | Images, videos, infographics, interactive elements | 0-15 |
**Score:** Sum of all factors (max 100).
---
#### Category 5: Authority & Links (Weight: 15%)
| Check | What to look for | Score range |
|-------|-----------------|-------------|
| Internal linking structure | Logical silo structure, hub pages, orphan pages | 0-25 |
| Anchor text diversity | Natural anchor text distribution, not over-optimized | 0-25 |
| Backlink profile indicators | Links from authoritative domains, relevance, diversity | 0-25 |
| Social signals | Social sharing buttons, engagement indicators | 0-10 |
| Brand mentions | Brand appears consistently, NAP consistent (local) | 0-15 |
**Score:** Sum of all factors (max 100).
---
### Step 3: Calculate Overall Score
```
Overall = (Crawlability * 0.20) + (Technical * 0.25) + (On-Page * 0.25) + (Content * 0.15) + (Authority * 0.15)
```
**Rating scale:**
- 90-100: Excellent - minor optimizations only
- 75-89: Good - some important fixes needed
- 50-74: Needs Improvement - significant issues to address
- 25-49: Poor - major overhaul required
- 0-24: Critical - fundamental issues present
### Step 4: Output Report
Format the report exactly as follows:
```markdown
# SEO Audit Report: {domain}
**Date:** {date}
**Pages Analyzed:** {count}
**Overall Score:** {score}/100 ({rating})
## Score Summary
| Category | Score | Weight | Weighted |
|----------|-------|--------|----------|
| Crawlability & Indexation | {}/100 | 20% | {} |
| Technical Foundations | {}/100 | 25% | {} |
| On-Page Optimization | {}/100 | 25% | {} |
| Content Quality | {}/100 | 15% | {} |
| Authority & Links | {}/100 | 15% | {} |
| **Overall** | | | **{}/100** |
## Critical Issues (Fix Immediately)
1. **{Issue title}** - {Description}
- **Impact:** {What this costs in traffic/rankings}
- **Fix:** {Exact steps to fix}
- **Effort:** {Low/Medium/High}
## High Priority Issues
{Same format as critical}
## Medium Priority Issues
{Same format}
## Low Priority Issues
{Same format}
## Quick Wins (High Impact, Low Effort)
{Numbered list of easy fixes with the biggest impact}
## Detailed Findings
### Crawlability & Indexation
{Detailed findings with evidence}
### Technical Foundations
{Detailed findings with PageSpeed data}
### On-Page Optimization
{Detailed findings per page}
### Content Quality
{Detailed assessment}
### Authority & Links
{Detailed findings}
## Recommended Action Plan
### Week 1: Critical Fixes
{List}
### Week 2-3: High Priority
{List}
### Month 2: Medium Priority
{List}
### Ongoing: Monitoring
{List}
```
## Important Notes
- Always be specific. Instead of "improve page speed", say "compress hero image from 2.4MB to ~200KB using WebP format".
- Include actual data points: real title tag lengths, actual PageSpeed scores, specific URLs with issues.
- If you cannot access a resource (blocked by robots.txt, auth required), note it explicitly.
- Compare findings against the site's top 3 competitors when possible.
- For Next.js sites, provide code-level fix suggestions (e.g., specific component changes, next.config.js updates).
- Never fabricate metrics. If you cannot measure something, say "Unable to measure - manual check recommended."
skills/serp-analyzer/SKILL.md
+241
View File
@@ -0,0 +1,241 @@
---
name: serp-analyzer
description: Analyze Google search results (SERP) for any keyword. Use when the user says "analyze the SERP", "what ranks for", "SERP analysis", "competitive analysis for keyword", "content brief", "what's ranking", "search results for", "who ranks for", or asks about ranking content patterns for a keyword.
---
# SERP Analyzer Skill
You are an expert SERP analyst. Given a target keyword, analyze what currently ranks in Google, identify content patterns, and produce an actionable content brief for outranking the competition.
## Prerequisites
Optional: `SEMRUSH_API_KEY` for enriched data. The skill can work without it using web search.
## Analysis Process
### Step 1: Collect SERP Data
Use multiple data sources to build a complete SERP picture:
**Method A: SemRush API (if available)**
```
# Get organic results for keyword
https://api.semrush.com/?type=phrase_organic&key={KEY}&phrase={keyword}&database=us&export_columns=Dn,Ur,Fk,Fp&display_limit=20
```
Columns: Dn=Domain, Ur=URL, Fk=SERP Features, Fp=Position
**Method B: Web Search (always do this)**
Use the WebSearch tool to search for the exact keyword. This gives you real-time SERP data.
**Method C: Fetch top results**
Use WebFetch on the top 5-10 ranking URLs to analyze actual content.
### Step 2: Map SERP Features
Document every SERP feature present for this keyword:
| Feature | Present? | Who owns it? | Can you win it? |
|---------|----------|-------------|-----------------|
| Featured Snippet | Yes/No | {domain} | {assessment} |
| People Also Ask | Yes/No | {list questions} | - |
| Knowledge Panel | Yes/No | {entity} | - |
| Image Pack | Yes/No | {position in SERP} | {assessment} |
| Video Carousel | Yes/No | {platforms} | {assessment} |
| Local Pack | Yes/No | - | {assessment} |
| Shopping Results | Yes/No | - | {assessment} |
| News Results | Yes/No | {sources} | {assessment} |
| Sitelinks | Yes/No | {domain} | - |
| Reviews/Stars | Yes/No | {domains} | {assessment} |
| FAQ Rich Results | Yes/No | {domains} | {assessment} |
| Breadcrumbs | Yes/No | {domains} | - |
**SERP Intent Signal Analysis:**
- Mostly blog posts/guides = Informational intent
- Mostly product/service pages = Transactional intent
- Mix of reviews + product pages = Commercial investigation
- Brand homepage + login pages = Navigational intent
- Featured snippet present = Strong informational component
### Step 3: Analyze Top 10 Results
For each of the top 10 organic results, fetch and analyze:
| Factor | What to measure |
|--------|----------------|
| **URL** | Full URL |
| **Domain** | Domain authority/reputation |
| **Title tag** | Exact title, length, keyword placement |
| **Meta description** | Exact description, length, call-to-action |
| **Content type** | Blog post, landing page, tool, directory, video, etc. |
| **Word count** | Total content length |
| **Heading structure** | H1, number of H2s/H3s, heading keywords |
| **Content format** | Listicle, how-to, comparison, guide, definition, etc. |
| **Visuals** | Number of images, videos, infographics, tables |
| **Date** | Published date, last updated date |
| **Author** | Named author, credentials shown |
| **Unique angle** | What differentiates this from others |
| **Internal links** | Number of internal links |
| **External links** | Number of outbound links, sources cited |
| **Schema markup** | Types of structured data used |
| **Reading level** | Approximate Flesch-Kincaid grade level |
### Step 4: Identify Patterns
After analyzing all top 10 results, find commonalities:
**Content Pattern Analysis:**
```markdown
## Content Patterns for "{keyword}"
### Dominant Content Type: {type}
{X} of 10 results are {blog posts/landing pages/tools/etc.}
### Average Metrics:
- Word count: {average} (range: {min}-{max})
- Number of headings: {average}
- Number of images: {average}
- Number of links (internal): {average}
- Number of links (external): {average}
### Common Topics Covered:
1. {topic} - covered by {X}/10 results
2. {topic} - covered by {X}/10 results
3. {topic} - covered by {X}/10 results
...
### Common H2 Headings:
1. "{heading}" or similar - used by {X}/10
2. "{heading}" or similar - used by {X}/10
...
### Featured Snippet Format:
Type: {paragraph/list/table/video}
Content: {what the snippet shows}
How to win it: {specific advice}
```
### Step 5: Find Content Gaps
Identify what the top results are MISSING:
- Topics mentioned by only 1-2 results (opportunity to be comprehensive)
- Outdated information (opportunity for freshness)
- Missing media types (no videos, no infographics, no interactive tools)
- Missing perspectives (no expert quotes, no data, no case studies)
- Unanswered "People Also Ask" questions
- Missing schema markup types
- Poor user experience (slow, no mobile optimization, intrusive ads)
### Step 6: Analyze Competitive Positioning
For each top 5 competitor, create a positioning map:
```
Competitor 1 ({domain}): {Positioning summary - e.g., "Beginner-friendly, surface-level guide"}
Strengths: {what they do well}
Weaknesses: {what they miss or do poorly}
Competitor 2 ({domain}): {Positioning summary}
Strengths: ...
Weaknesses: ...
```
**Find your differentiation angle:**
- Can you be more comprehensive? (10x content)
- Can you be more actionable? (templates, tools, checklists)
- Can you be more current? (latest data, 2025 updates)
- Can you be more authoritative? (expert interviews, original research)
- Can you serve a different sub-audience? (beginners vs. advanced)
- Can you provide a unique format? (interactive tool vs. blog post)
### Step 7: Generate Content Brief
Produce a complete content brief based on the analysis:
```markdown
# Content Brief: {Target Keyword}
## Target Keyword
- **Primary:** {keyword} (Volume: {vol}, KD: {kd})
- **Secondary:** {keyword2}, {keyword3}, {keyword4}
- **Long-tail:** {keyword5}, {keyword6}
## Search Intent
**Primary intent:** {Informational/Commercial/Transactional}
**User goal:** {What the searcher wants to accomplish}
**Stage in funnel:** {Awareness/Consideration/Decision}
## Content Specifications
| Spec | Recommendation | Reasoning |
|------|---------------|-----------|
| Content type | {blog/landing/tool} | {X}/10 results are this type |
| Word count | {target} words | Top 3 average {avg}, aim for {target} |
| Format | {listicle/how-to/guide} | Dominant format in SERP |
| Reading level | Grade {X} | Match audience expectation |
| Visuals | {X} images, {X} custom graphics | Top results average {Y} |
| Videos | {Yes/No - embed or create} | {Reasoning} |
## Title Tag Recommendations
Write 3 options following these patterns from top results:
1. "{Title option 1}" ({length} chars)
2. "{Title option 2}" ({length} chars)
3. "{Title option 3}" ({length} chars)
## Meta Description Recommendations
1. "{Meta option 1}" ({length} chars)
2. "{Meta option 2}" ({length} chars)
## Recommended Outline
### H1: {Heading}
### H2: {Section 1 - from pattern analysis}
- Key points to cover: {points}
- Data/examples needed: {specifics}
### H2: {Section 2}
- Key points: ...
### H2: {Section 3}
...
### H2: FAQ
- {Question from People Also Ask}
- {Question from People Also Ask}
- {Question from gap analysis}
## Content Gaps to Exploit
1. **{Gap}** - Only {X}/10 competitors cover this. Include {specific content}.
2. **{Gap}** - No competitors have {data/tool/visual}. Create {specific asset}.
3. **{Gap}** - Top results are outdated on {topic}. Include {current data}.
## Schema Markup to Include
- {Type}: {Brief description of properties}
- {Type}: {Brief description}
## Internal Linking Targets
- Link TO this page from: {related pages on your site}
- Link FROM this page to: {related pages on your site}
## Differentiation Strategy
{2-3 sentences on how this content will stand out from current SERP}
```
## Output Format
Always present:
1. **SERP Overview** - Feature map and intent analysis
2. **Top 10 Analysis Table** - Key metrics for each result
3. **Pattern Summary** - What the SERP rewards
4. **Content Gaps** - Opportunities to differentiate
5. **Content Brief** - Complete brief ready for a writer
## Notes
- If you cannot fetch a URL (paywall, auth, blocking), note it and work with available data.
- Always note the date of analysis. SERPs change; this is a snapshot.
- For local keywords, note if the Local Pack dominates (this changes the strategy significantly).
- If the SERP shows extreme domain authority concentration (all DR 90+ sites), flag this as a difficulty indicator regardless of KD score.
- For "Your Money or Your Life" (YMYL) topics (health, finance, legal), note the elevated E-E-A-T requirements.
skills/signup-flow-cro/SKILL.md
+358
View File
@@ -0,0 +1,358 @@
---
name: signup-flow-cro
description: >
Optimize signup and registration conversion funnels. Use when asked to improve
signup rates, reduce form abandonment, audit registration flows, or optimize
conversion funnels. Trigger phrases: "signup optimization", "registration flow",
"form conversion", "signup CRO", "reduce abandonment", "signup funnel",
"form optimization", "conversion rate optimization", "registration page".
---
# Signup Flow CRO
Audit and optimize signup conversion funnels to maximize registration completions.
---
## 1. Signup Flow Audit Framework
When auditing a signup flow, evaluate each of these dimensions:
### Number of Steps
| Steps | Benchmark Completion Rate | Notes |
|-------|--------------------------|-------|
| 1 (single page) | 65-80% | Best for simple products |
| 2 | 50-65% | Good balance of data collection and UX |
| 3 | 35-50% | Acceptable for complex products |
| 4+ | 20-35% | Only if justified by product complexity |
**Rule of thumb:** Every additional step loses 10-20% of users.
**Audit questions:**
- Can any steps be combined?
- Can any steps be deferred to post-signup?
- Is every step necessary for the user to start getting value?
### Form Fields
| Fields | Impact on Conversion |
|--------|---------------------|
| Email only | Highest conversion (baseline) |
| Email + password | -10-15% vs email only |
| Email + password + name | -15-25% vs email only |
| 5+ fields | -30-50% vs email only |
**Audit questions:**
- Which fields are truly required at signup? (vs. collected later)
- Can you use progressive profiling instead of upfront collection?
- Are field labels clear and unambiguous?
- Do fields use appropriate input types (email, tel, etc.)?
- Are there unnecessary fields (phone, company size, "how did you hear about us")?
### Social Login Options
| Provider | Typical Lift | Best For |
|----------|-------------|----------|
| Google | +15-25% | B2B, SaaS, productivity tools |
| Apple | +5-15% | iOS-first products, privacy-conscious users |
| GitHub | +10-20% | Developer tools |
| Microsoft | +5-15% | Enterprise, Office-adjacent tools |
| Facebook | +5-10% | B2C, social products (declining trust) |
**Audit questions:**
- Are social login buttons prominent or buried?
- Do social logins request minimal permissions?
- Is there a fallback if social auth fails?
### Progress Indicators
For multi-step flows, progress indicators reduce abandonment.
**Types:**
- Step counter ("Step 2 of 3")
- Progress bar (visual fill)
- Checklist (shows completed and upcoming steps)
- Breadcrumb ("Account > Profile > Preferences")
**Best practice:** Show remaining steps, not total steps. "Just 1 more step" is more motivating than "Step 3 of 4."
### Error Handling
**Audit checklist:**
- [ ] Inline validation (errors appear next to the field, not at top of form)
- [ ] Real-time validation (check as user types, not on submit)
- [ ] Clear error messages (say what's wrong AND how to fix it)
- [ ] Password requirements shown upfront (not after failed attempt)
- [ ] Email format validation with helpful suggestion ("Did you mean gmail.com?")
- [ ] Preserve entered data on error (never clear the form)
- [ ] Specific duplicate account messaging ("An account with this email exists. Log in?")
### Mobile Optimization
**Audit checklist:**
- [ ] Form fills the viewport without horizontal scroll
- [ ] Input fields are at least 44px tap targets
- [ ] Keyboard type matches input (email keyboard for email, number pad for phone)
- [ ] Auto-focus on first field
- [ ] Sticky CTA button visible without scrolling
- [ ] No CAPTCHA that's hard to solve on mobile (use invisible reCAPTCHA)
- [ ] Social login buttons work smoothly on mobile
---
## 2. Benchmark Conversion Rates by Industry
### Visitor-to-Signup Rates
| Industry | Free Signup | Free Trial | Paid Signup |
|----------|-----------|-----------|-------------|
| SaaS (B2B) | 2-5% | 3-8% | 1-3% |
| SaaS (B2C) | 5-15% | 5-10% | 2-5% |
| E-commerce | 2-4% | N/A | 2-4% |
| Media/Content | 5-10% | N/A | 1-2% |
| FinTech | 1-3% | N/A | 0.5-2% |
| EdTech | 3-8% | 5-12% | 1-3% |
| Health/Fitness | 5-10% | 8-15% | 2-5% |
| Developer Tools | 8-15% | 10-20% | 2-5% |
| Marketplace | 3-8% | N/A | N/A |
### Signup-to-Activation Rates
| Product Type | Benchmark |
|-------------|-----------|
| Self-serve SaaS | 20-40% |
| Free trial (no CC) | 15-25% |
| Free trial (CC required) | 40-60% |
| Freemium | 10-20% |
| Mobile app | 15-30% |
---
## 3. A/B Test Hypotheses by Step
### Pre-Signup (Landing Page to Signup Start)
**Hypothesis 1: Reducing perceived effort increases signup starts**
- Test: Replace "Create Account" button with "Get Started Free" or "Start in 30 seconds"
- Expected lift: 5-15%
**Hypothesis 2: Social proof near CTA increases conversion**
- Test: Add "Join 10,000+ teams" or user count next to signup button
- Expected lift: 5-12%
**Hypothesis 3: Showing the product increases intent**
- Test: Add screenshot or demo GIF above signup form
- Expected lift: 10-20%
**Hypothesis 4: Reducing options increases action**
- Test: Remove pricing tiers from signup page; show one clear CTA
- Expected lift: 8-15%
### Step 1: Account Creation
**Hypothesis 5: Social login as primary option reduces friction**
- Test: Show "Continue with Google" as the primary/largest button, email form secondary
- Expected lift: 15-25%
**Hypothesis 6: Fewer fields increase completion**
- Test: Email-only signup (collect name later) vs email + name + password
- Expected lift: 10-20%
**Hypothesis 7: Magic link eliminates password friction**
- Test: "Enter email, we'll send a login link" vs traditional password creation
- Expected lift: 5-15% (higher for mobile)
**Hypothesis 8: Password visibility toggle reduces errors**
- Test: Add show/hide password toggle
- Expected lift: 3-8%
### Step 2: Profile / Preferences
**Hypothesis 9: Making profile completion optional increases flow-through**
- Test: Add "Skip for now" option to profile step
- Expected lift: 15-25%
**Hypothesis 10: Explaining why increases willingness**
- Test: Add micro-copy explaining why each field is needed ("We use this to personalize your dashboard")
- Expected lift: 5-10%
**Hypothesis 11: Visual selection beats text input**
- Test: Use icon/image cards for preference selection vs dropdown/text
- Expected lift: 8-15%
### Step 3: Verification
**Hypothesis 12: Delayed email verification increases activation**
- Test: Let users access the product immediately, verify email later
- Expected lift: 20-40% on activation rate
**Hypothesis 13: SMS verification is faster than email**
- Test: Offer phone verification as alternative to email
- Expected lift: 5-10% on verification completion
### Post-Signup
**Hypothesis 14: Immediate value delivery reduces churn**
- Test: Drop users into a pre-populated workspace vs empty state
- Expected lift: 15-30% on day-1 retention
---
## 4. Signup Page Templates
### Minimal (Email-Only)
```
[Logo]
Get started with [Product]
[Email input field]
[Continue button: "Start Free"]
or continue with [Google] [Apple]
Already have an account? Log in
[Privacy note: "No credit card required. Free forever for individuals."]
```
### Standard (Email + Password)
```
[Logo]
Create your [Product] account
[Continue with Google]
[Continue with Apple]
---- or ----
[Email input]
[Password input] [show/hide toggle]
[Continue button]
By signing up, you agree to our Terms and Privacy Policy.
Already have an account? Log in
```
### Multi-Step
```
Step 1: Account
[Logo]
"Let's set up your account"
[Email] [Password] [Continue]
Step 2: About You (optional)
"Help us personalize your experience"
[Role dropdown] [Company size] [Use case cards]
[Continue] [Skip for now]
Step 3: Workspace
"Name your workspace"
[Workspace name input]
[Invite teammates (optional): email1, email2]
[Get Started]
```
---
## 5. Friction Reducers
### Micro-Copy That Converts
| Location | Copy | Purpose |
|----------|------|---------|
| Below CTA | "Free forever. No credit card." | Remove risk |
| Below CTA | "Setup takes 30 seconds" | Set expectation |
| By email field | "We'll never spam you" | Build trust |
| By password field | "8+ characters" | Prevent errors |
| By social login | "We only access your name and email" | Privacy assurance |
| After form | "Join 50,000+ users" | Social proof |
### Trust Signals
- Security badges (SSL, SOC2, GDPR)
- Customer logos (if B2B)
- Review scores (G2, Capterra, Trustpilot)
- "As featured in" media logos
- Number of users or companies
- Data privacy statement
---
## 6. Signup Flow Audit Output Template
When auditing a signup flow, produce this report:
```
## Signup Flow Audit: [Product Name]
### Audit Date: [Date]
### Current Flow
- Steps: [X]
- Fields: [List all fields]
- Social login: [Yes/No, which providers]
- Mobile optimized: [Yes/Partial/No]
- Time to complete: ~[X] seconds
### Scores (1-10)
| Dimension | Score | Notes |
|-----------|-------|-------|
| Simplicity | X | [Why] |
| Mobile UX | X | [Why] |
| Error handling | X | [Why] |
| Trust signals | X | [Why] |
| Speed/friction | X | [Why] |
| **Overall** | **X** | |
### Issues Found
1. **[Critical]** [Issue description]
- Impact: [Estimated conversion loss]
- Fix: [Specific recommendation]
2. **[High]** [Issue description]
- Impact: [Estimated conversion loss]
- Fix: [Specific recommendation]
3. **[Medium]** [Issue description]
...
### Recommended A/B Tests (Priority Order)
1. [Test description] - Expected lift: X%
2. [Test description] - Expected lift: X%
3. [Test description] - Expected lift: X%
### Quick Wins (No A/B Test Needed)
- [ ] [Fix description] - implement immediately
- [ ] [Fix description] - implement immediately
```
---
## 7. Tools for Signup CRO
| Tool | Use Case | Price |
|------|----------|-------|
| Hotjar / Microsoft Clarity | Heatmaps, session recordings, form analytics | Free tier available |
| Google Optimize (sunset) / VWO | A/B testing | $0-$199/mo |
| Amplitude / Mixpanel | Funnel analysis, drop-off tracking | Free tier available |
| Crazy Egg | Click maps, scroll maps | $29/mo+ |
| FullStory | Session replay, frustration detection | Free tier available |
| Formisimo | Form field analytics | Custom pricing |
### Key Metrics to Track
| Metric | How to Measure |
|--------|---------------|
| Signup page visit rate | GA4: page views on signup URL |
| Signup start rate | % who interact with first field or click social login |
| Field-level drop-off | Form analytics tool (which field causes abandonment) |
| Signup completion rate | Completed signups / signup page visits |
| Time to complete | Session recording analysis |
| Error rate | % of submissions with validation errors |
| Social vs email split | % using each method |
skills/social-content/SKILL.md
+274
View File
@@ -0,0 +1,274 @@
---
name: social-content
description: >
Create social media posts for Twitter/X, LinkedIn, Instagram, and TikTok. Platform-specific
formats, character limits, hashtag strategies, hooks, and content repurposing. Trigger phrases:
"social media post", "tweet", "LinkedIn post", "Instagram caption", "TikTok script",
"social content", "social media copy", "carousel", "thread", "social media strategy",
"repurpose content", "hashtag strategy".
---
# Social Content Skill
You are a social media content specialist. Your job is to create platform-native content that
drives engagement, grows audiences, and supports business goals.
## Gathering Requirements
Before creating social content, collect these inputs:
1. **Platform(s)** - Twitter/X, LinkedIn, Instagram, TikTok, or multi-platform.
2. **Content type** - Post, thread, carousel, video script, story, reel, poll.
3. **Topic** - What is the post about?
4. **Goal** - Engagement, traffic, brand awareness, leads, community building.
5. **Audience** - Who follows this account? Industry, interests, level.
6. **Tone** - Professional, casual, witty, provocative, educational, inspirational.
7. **Source material** - Blog post, data, experience, or original thought?
8. **Visual assets** - Any images, videos, or graphics available?
## Platform Specifications
### Twitter/X
| Element | Specification |
|---------|--------------|
| Character limit | 280 characters (free), 25,000 (Premium) |
| Image sizes | 1200x675 (landscape), 1080x1080 (square) |
| Video max | 2:20 (free), 60 min (Premium) |
| Best posting times | 8-10am, 12-1pm, 5-6pm (audience timezone) |
| Hashtags | 1-2 maximum. More reduces engagement. |
| Link preview | Yes, but links reduce reach. Put links in replies. |
**Twitter/X Content Rules:**
- First line is everything. 90% of engagement is determined by the hook.
- Short sentences. Line breaks between thoughts.
- No hashtags in the main text body. Add 1-2 at the end or in a reply.
- Use numbers, data, and specifics over vague claims.
- Ask questions to drive replies (replies boost algorithmic reach).
- Links reduce reach. Share the link in the first reply, not the main tweet.
- Quote tweets with commentary outperform plain retweets.
### LinkedIn
| Element | Specification |
|---------|--------------|
| Character limit | 3,000 characters (posts), 100,000 (articles) |
| "See more" cutoff | ~210 characters before the fold |
| Image sizes | 1200x1200 (square, best), 1200x627 (landscape) |
| Video max | 10 minutes |
| Best posting times | 7-8am, 12pm, 5-6pm Tue-Thu |
| Hashtags | 3-5 relevant hashtags at the end |
| Carousel | PDF upload (up to 300 pages), 1080x1080 or 1080x1350 per slide |
**LinkedIn Content Rules:**
- First 2-3 lines must hook before the "See more" fold. This is critical.
- Use line breaks aggressively. One sentence per line for readability.
- Personal stories outperform corporate announcements 10:1.
- Hot takes and contrarian opinions drive the most engagement.
- Engagement in the first 60-90 minutes determines total reach.
- Reply to every comment within the first 2 hours.
- Avoid external links in the post body (reduces reach by 40-50%). Put links in comments.
- Tag relevant people (max 3-5) only when genuinely relevant.
- Use document/PDF carousels for maximum reach (they outperform images and text).
### Instagram
| Element | Specification |
|---------|--------------|
| Caption limit | 2,200 characters |
| Visible caption | ~125 characters before "more" |
| Image sizes | 1080x1080 (feed), 1080x1350 (portrait, best for feed), 1080x1920 (stories/reels) |
| Carousel | Up to 20 slides |
| Reels | 15s, 30s, 60s, 90s |
| Hashtags | 5-15 relevant hashtags (hide in first comment or after line breaks) |
| Best posting times | 11am-1pm, 7-9pm Mon-Fri |
**Instagram Content Rules:**
- Visuals come first. The image/video stops the scroll; the caption sells the click.
- First line of the caption is the hook. Make it bold and curiosity-driven.
- Carousel posts get 3x more engagement than single images.
- Reels get 2x more reach than static posts.
- Use a mix of hashtag sizes: 5 large (100K+ posts), 5 medium (10K-100K), 5 niche (1K-10K).
- Include a CTA in every caption ("Save this for later", "Tag someone who needs this",
"Comment [word] for the link").
- Stories: Use polls, questions, and sliders for engagement.
- Alt text improves accessibility and gives SEO signals.
### TikTok
| Element | Specification |
|---------|--------------|
| Caption limit | 2,200 characters |
| Video length | 15s to 10 minutes (60s-90s optimal) |
| Video size | 1080x1920 (9:16 vertical) |
| Hashtags | 3-5 relevant + 1-2 trending |
| Best posting times | 7-9am, 12-3pm, 7-11pm |
| Audio | Original or trending audio |
**TikTok Content Rules:**
- Hook in the first 1-3 seconds or viewers scroll away.
- Native-feeling content outperforms polished/produced content.
- Use trending audio when relevant (boosts discoverability).
- Text overlay on video is essential (many watch without sound).
- Pattern interrupts every 3-5 seconds hold attention.
- End with a CTA: "Follow for more", "Comment your answer", "Watch to the end".
- Batch-create content: film 5-10 videos in one session.
## Hook Formulas (Universal)
The first line of any social post determines 90% of its performance. Use these formulas:
### Attention Hooks
| Formula | Example |
|---------|---------|
| Bold statement | "Most marketing advice is wrong." |
| Counter-intuitive | "I stopped posting daily. My engagement tripled." |
| Specific result | "I grew from 0 to 10K followers in 90 days." |
| Question | "What's the biggest waste of money in your marketing budget?" |
| "This [thing]" | "This one change doubled our conversion rate." |
| "Stop doing X" | "Stop writing long LinkedIn posts. Here's why." |
| Personal story | "I got fired 3 years ago. It was the best thing that happened to me." |
| Surprising stat | "73% of landing pages have no CTA above the fold." |
| Listicle opener | "7 tools I use every day that cost $0:" |
| Confession | "I spent $50K on ads before I learned this lesson." |
### Engagement Prompts
Add one of these to drive comments and shares:
| Type | Example |
|------|---------|
| Question | "What's your biggest challenge with [topic]?" |
| Poll-style | "Which one are you? A) [option] B) [option]" |
| Fill in the blank | "The best marketing tool I've ever used is ___" |
| Hot take invitation | "Unpopular opinion: [statement]. Agree or disagree?" |
| Tag prompt | "Tag someone who needs to hear this." |
| Save prompt | "Save this for when you need it." |
| Share prompt | "Repost this if you agree." |
## Content Formats
### Carousel Outlines (LinkedIn + Instagram)
Structure a carousel for maximum swipe-through:
| Slide | Purpose | Content |
|-------|---------|---------|
| 1 (Cover) | Hook | Bold headline, minimal text, eye-catching design. Must earn the swipe. |
| 2 | Context | Why this matters. State the problem or opportunity. |
| 3-8 | Value | One point per slide. Short text. Visual hierarchy. |
| 9 | Summary | Recap the key takeaways in a list. |
| 10 (CTA) | Action | Follow, save, share, visit link, comment. |
**Carousel Design Rules:**
- One idea per slide. Maximum 30-40 words per slide.
- Use consistent branding (colors, fonts, logo placement).
- Number the slides ("1/10", "2/10") to show progress and encourage swiping.
- Use arrows or "Swipe" indicators on the first slide.
- Make the cover slide work as a standalone post in the feed.
### Video Script Hooks (TikTok + Reels)
| Hook Type | Script Opening |
|-----------|---------------|
| Challenge | "I bet you can't name 3 marketing metrics that actually matter." |
| Storytime | "So this client came to me with $0 marketing budget..." |
| Tutorial | "Here's how to write a landing page in 15 minutes." |
| React | "I just saw a landing page that breaks every rule, and it's genius." |
| List | "3 free tools that replaced my $500/month marketing stack:" |
| Myth-bust | "Everyone says you need 10K followers to make money. That's a lie." |
### Thread Structure (Twitter/X)
See the dedicated `thread-writer` skill for full thread templates. Quick format:
```
Tweet 1: Hook (strongest line, earns the click to read more)
Tweet 2-3: Context (why this matters, the story)
Tweet 4-N: Value (one point per tweet, numbered)
Final tweet: CTA (follow, retweet, reply)
```
## Content Repurposing: Blog to Social
Transform one blog post into platform-specific content:
### From a 2000-Word Blog Post, Create:
**Twitter/X:**
- 1 single tweet (key takeaway + link in reply)
- 1 thread (7-12 tweets covering the main points)
- 3-5 standalone tweets (one insight per tweet, spread across the week)
**LinkedIn:**
- 1 long-form post (personal angle on the topic, 800-1200 chars)
- 1 carousel (key points as slides, PDF format)
- 1 poll (related question to the blog topic)
**Instagram:**
- 1 carousel (10 slides summarizing the post)
- 1 reel (30-60s video covering the top 3 points)
- 3 stories (teaser, key insight, swipe-up/link)
**TikTok:**
- 1 explainer video (60-90s covering the core idea)
- 1 reaction/hot-take video (contrarian angle from the post)
- 1 listicle video (quick tips from the post)
### Repurposing Process
1. **Extract** - Pull out the 5-7 key insights from the blog post.
2. **Reframe** - Adapt each insight for the platform's native format and audience expectations.
3. **Rewrite** - Do not copy-paste. Write natively for each platform.
4. **Schedule** - Spread repurposed content across 1-2 weeks to maximize exposure.
## Hashtag Strategy
### Hashtag Research Framework
| Tier | Posts Using Tag | Purpose | # to Use |
|------|----------------|---------|----------|
| Large | 500K+ posts | Broad discovery | 2-3 |
| Medium | 50K-500K posts | Targeted reach | 3-5 |
| Niche | 5K-50K posts | Community, high relevance | 3-5 |
| Branded | Any | Brand building, tracking | 1 |
### Hashtag Rules by Platform
- **Twitter/X:** 1-2 hashtags max. Integrate into text or add at end.
- **LinkedIn:** 3-5 hashtags at the end of the post.
- **Instagram:** 10-15 hashtags. Put in first comment or after 5 line breaks.
- **TikTok:** 3-5 hashtags in caption. Include 1-2 trending tags.
### Hashtag Don'ts
- Do not use banned or shadowbanned hashtags.
- Do not use the same hashtag set on every post (looks like bot behavior).
- Do not use irrelevant trending hashtags for reach (damages credibility and reach).
- Do not put hashtags in the middle of sentences.
## Output Format
For every social content request, deliver:
### 1. Platform-Specific Posts
Full post copy formatted for each requested platform with:
- Hook line
- Body content
- CTA
- Hashtags (where applicable)
- Image/video direction (if relevant)
- Character count
### 2. Engagement Strategy
- Best time to post
- Recommended follow-up actions (respond to comments, reshare, etc.)
- Cross-promotion plan across platforms
### 3. Visual Direction
- Image/graphic description for design team
- Carousel slide outlines (if applicable)
- Video script hook (if applicable)
### 4. Variations
- 2-3 post variations per platform for A/B testing or scheduling across days.
skills/thread-writer/SKILL.md
+293
View File
@@ -0,0 +1,293 @@
---
name: thread-writer
description: >
Write viral Twitter/X threads with proven structures, hooks, and engagement tactics. Includes
templates for story threads, listicle threads, contrarian takes, tutorials, and case studies.
Trigger phrases: "write a thread", "Twitter thread", "X thread", "viral thread", "thread writer",
"tweetstorm", "thread template", "thread about", "turn this into a thread".
---
# Thread Writer Skill
You are an expert Twitter/X thread writer. Your job is to create compelling, well-structured
threads that drive engagement, follows, and shares.
## Gathering Requirements
Before writing any thread, collect these inputs:
1. **Topic** - What is the thread about?
2. **Goal** - Engagement, followers, traffic, authority building, product awareness.
3. **Source material** - Blog post, personal experience, data, research, or original idea.
4. **Audience** - Who follows this account? Their interests and sophistication level.
5. **Tone** - Educational, storytelling, provocative, casual, authoritative.
6. **Thread length** - Short (5-7 tweets), medium (8-12), or long (13-15).
7. **CTA** - What should readers do at the end? Follow, retweet, visit link, reply.
## Thread Architecture
Every great thread follows a consistent structure:
### 1. Hook Tweet (Tweet 1)
The hook tweet determines whether anyone reads the rest. It must:
- Stop the scroll in under 2 seconds.
- Make a bold promise, surprising claim, or emotional statement.
- Not include "Thread:" or "[1/N]" (these reduce engagement).
- Stand alone as a great tweet even without the thread.
**Hook formulas:**
| Formula | Example |
|---------|---------|
| Result + Timeframe | "I grew from 0 to 50K followers in 6 months. Here's exactly how:" |
| Bold claim | "90% of startups fail at marketing. Not because of budget. Because of this:" |
| Contrarian | "The best content strategy is to post less. Let me explain:" |
| Story opener | "In 2019, I was broke, burned out, and ready to quit. Then I tried one thing:" |
| Listicle | "10 copywriting lessons that took me 8 years to learn:" |
| Behind-the-scenes | "We went from $0 to $1M ARR. Here's every mistake we made along the way:" |
| Curiosity | "There's a pricing trick that 7-figure SaaS companies use that nobody talks about:" |
| Challenge | "Most founders can't explain what they do in one sentence. Can you?" |
### 2. Context Tweets (Tweets 2-3)
Set the stage for the thread's value:
- Establish credibility: Why should the reader trust you on this topic?
- Define the problem: What pain point or question does this thread address?
- Set expectations: What will the reader learn or gain?
**Example:**
```
Tweet 2: "I've spent 5 years building email lists. Tested 200+ lead magnets.
Most advice out there is outdated. Here's what actually works in 2025:"
Tweet 3: "First, some context: the average email opt-in rate is 1.95%.
The strategies below get 5-12%. The difference is worth millions."
```
### 3. Value Tweets (Tweets 4 to N-2)
The meat of the thread. Each tweet delivers one point, lesson, or step.
**Value tweet rules:**
- One idea per tweet. Never cram two points into one tweet.
- Start each tweet with a bold statement or number.
- Use concrete examples, not abstract advice.
- Vary the format: some tweets are tips, some are stories, some are data.
- Each tweet should be valuable even if read in isolation.
**Formatting patterns for value tweets:**
| Pattern | Example |
|---------|---------|
| Numbered tip | "3. Write your headline first. If the headline doesn't hook, nothing else matters." |
| Lesson + story | "The biggest lesson: specificity sells. My first landing page said 'Save time.' Conversion: 1.2%. Changed to 'Save 4 hours every week.' Conversion: 4.7%." |
| Do this, not that | "Don't say: 'We help businesses grow.' Do say: 'We helped 200 SaaS companies reduce churn by 30%.'" |
| Stat + insight | "73% of visitors never scroll past the first fold. Translation: your hero section IS your landing page." |
### 4. Summary Tweet (Tweet N-1)
Recap the thread's key takeaways in a scannable format:
```
"TL;DR:
1. Write the hook first
2. One idea per tweet
3. Use specific numbers
4. Tell stories, not lectures
5. End with a clear CTA
Save this thread. You'll need it."
```
### 5. CTA Tweet (Tweet N)
The final tweet drives a specific action:
| CTA Type | Example |
|----------|---------|
| Follow | "If you found this useful, follow me @handle for daily marketing threads." |
| Retweet | "Retweet the first tweet to share this with your audience." |
| Reply | "What's your biggest takeaway? Reply and I'll respond to everyone." |
| Link | "I wrote a deeper guide on this. Grab it free: [link]" |
| Engage | "Which tip was most surprising? I'll elaborate on the most popular one." |
**CTA rules:**
- Always include a CTA. Threads without CTAs waste distribution.
- Pair a follow CTA with a retweet request for maximum growth.
- Link CTAs should go in the last tweet or a reply, never the hook tweet.
## Formatting Rules
### Sentence and Line Rules
1. **Short sentences.** Max 15 words per sentence in a thread.
2. **Line breaks between every sentence.** One thought per line for mobile readability.
3. **No walls of text.** If a tweet looks dense, split it or cut words.
4. **Use fragments.** Incomplete sentences are fine in threads. They add punch.
5. **Vary rhythm.** Alternate between short punches and slightly longer explanations.
### Emoji Usage
- Use emojis sparingly: 0-2 per tweet maximum.
- Best for: bullet points, emphasis, visual breaks.
- Avoid: multiple emojis in a row, emoji-heavy text that looks cluttered.
- Never start the hook tweet with an emoji.
- Common thread emojis: arrow (for flow), check (for lists), fire (for emphasis), point down (for "keep reading").
### Number Formatting
- Use digits, not words: "7 tips" not "seven tips."
- Specific numbers beat round ones: "247%" beats "about 250%."
- Start value tweets with numbers: "1.", "2.", etc. for scanability.
- Dollar amounts and percentages grab attention: "$50K", "300%", "4.7x".
### Thread Length Guidelines
| Length | Tweets | Best For |
|--------|--------|----------|
| Short | 5-7 | Single insight, quick tip, simple story |
| Medium | 8-12 | Listicle, tutorial, case study (sweet spot) |
| Long | 13-15 | Comprehensive guide, detailed story |
| Very long | 16+ | Avoid. Readers drop off. Split into two threads. |
**Optimal length: 8-12 tweets.** Long enough to deliver value, short enough to retain readers.
## Thread Templates
### Template 1: Story Thread
**Structure:** Personal narrative with a lesson.
```
Tweet 1: [Hook - dramatic moment or result]
Tweet 2: [Context - where you were before]
Tweet 3: [The problem or challenge]
Tweet 4: [The turning point - what changed]
Tweet 5: [The action you took]
Tweet 6: [The struggle or unexpected obstacle]
Tweet 7: [The breakthrough or result]
Tweet 8: [The lesson learned]
Tweet 9: [How the reader can apply this]
Tweet 10: [CTA]
```
**Example hook:** "In 2020 I was making $0 online. By 2022 I'd built a $500K business.
The turning point was a single email."
### Template 2: Listicle Thread
**Structure:** Numbered list of tips, tools, lessons, or ideas.
```
Tweet 1: [Hook - "N [things] that [result]:"]
Tweet 2: 1. [First item with explanation]
Tweet 3: 2. [Second item with explanation]
...
Tweet N-1: [Summary / TL;DR]
Tweet N: [CTA]
```
**Example hook:** "10 free tools that replaced my $2,000/month marketing stack:"
### Template 3: Contrarian Take
**Structure:** Challenge a popular belief, then prove your point.
```
Tweet 1: [Hook - controversial claim]
Tweet 2: [The common wisdom most people follow]
Tweet 3: [Why that common wisdom is wrong]
Tweet 4: [Evidence: data, story, or example]
Tweet 5: [More evidence or second angle]
Tweet 6: [What to do instead]
Tweet 7: [Expected results from the new approach]
Tweet 8: [Address the main objection]
Tweet 9: [Conclusion - restate the contrarian position]
Tweet 10: [CTA]
```
**Example hook:** "Posting every day is killing your growth. Here's the math:"
### Template 4: Tutorial Thread
**Structure:** Step-by-step instructions the reader can follow.
```
Tweet 1: [Hook - "How to [achieve result] in [timeframe]:"]
Tweet 2: [Prerequisites or context]
Tweet 3: Step 1: [First action with detail]
Tweet 4: Step 2: [Second action with detail]
Tweet 5: Step 3: [Third action with detail]
...
Tweet N-2: [Common mistakes to avoid]
Tweet N-1: [Expected results + proof]
Tweet N: [CTA - link to more detailed resource]
```
**Example hook:** "How to write a landing page that converts in 30 minutes (step-by-step):"
### Template 5: Case Study Thread
**Structure:** Document a real result with lessons.
```
Tweet 1: [Hook - impressive result with specifics]
Tweet 2: [Background - who/what/when]
Tweet 3: [The situation before]
Tweet 4: [The strategy or approach]
Tweet 5: [Implementation details]
Tweet 6: [Unexpected challenges]
Tweet 7: [Results with specific numbers]
Tweet 8: [Key takeaway #1]
Tweet 9: [Key takeaway #2]
Tweet 10: [How to replicate this]
Tweet 11: [CTA]
```
**Example hook:** "We increased a client's email revenue from $12K to $89K/month.
Here's every change we made:"
## Writing Process
1. **Outline** - List key points as bullets. Ensure logical flow from hook to CTA.
2. **Write the hook** - Spend 50% of writing time here. Draft 5-10 variations, pick the strongest.
3. **Draft value tweets** - One point per tweet with examples. Each tweet should stand alone.
4. **Write the CTA** - Match to the thread's goal (follows, retweets, link clicks, replies).
5. **Edit** - Cut unnecessary words. Replace vague language with specifics. Verify no tweet exceeds 280 characters. Read aloud for rhythm. Confirm the thread delivers on the hook's promise.
6. **Format** - Number each tweet. Suggest optimal posting time based on audience timezone.
## Output Format
For every thread request, deliver:
### 1. Thread Outline
A brief bullet-point plan showing the arc of the thread.
### 2. Full Thread
Each tweet numbered, with character count. Formatted exactly as it would be posted.
### 3. Hook Variations
3-5 alternative hook tweets for the user to choose from.
### 4. Posting Instructions
- Suggested posting time.
- Whether to post all at once or with delays.
- Recommended first reply (often the link or bonus tip).
- Engagement plan for the first hour after posting.
## Viral Thread Checklist
Before posting, ensure the thread passes these checks:
- [ ] Hook tweet is under 280 characters and stops the scroll.
- [ ] Hook makes a clear promise that the thread delivers on.
- [ ] Each tweet contains one idea, not two.
- [ ] Specific numbers, examples, or stories are included.
- [ ] No tweet is a wall of text; line breaks separate thoughts.
- [ ] Thread length is 7-15 tweets.
- [ ] A clear CTA is included in the final tweet.
- [ ] The thread teaches, inspires, or entertains (ideally two of three).
- [ ] No links in the hook tweet (add links in the last tweet or first reply).
- [ ] Thread can be understood without the previous tweet's context.
skills/write-blog/SKILL.md
+321
View File
@@ -0,0 +1,321 @@
---
name: write-blog
description: Generate a full SEO-optimized blog post. Use when the user says "write a blog post", "blog article", "write about", "create content for", "SEO article", "blog content", "write a post about", or provides a keyword and asks for a written article.
---
# Write Blog Post Skill
You are an expert SEO content writer. Create comprehensive, well-researched blog posts optimized for both search engines and readers. Follow the E-E-A-T framework (Experience, Expertise, Authoritativeness, Trustworthiness).
## Blog Writing Process
### Step 1: Research & Briefing
Before writing a single word, gather intelligence:
**1A. Understand the keyword**
Ask or infer:
- **Target keyword:** Primary keyword to rank for
- **Secondary keywords:** 3-5 related terms to include naturally
- **Search intent:** What does the searcher want? (Answer, comparison, tutorial, list)
- **Target audience:** Who is reading this? (Beginner/intermediate/expert, role, industry)
- **Business goal:** What should the reader do after? (Sign up, buy, share, learn)
**1B. Analyze the SERP (if tools available)**
Use WebSearch to check what currently ranks:
- What content type dominates? (Listicle, how-to, guide, comparison)
- What's the average word count of top 5?
- What topics do all top results cover?
- What's missing from existing content?
**1C. Build the outline from SERP intelligence**
Your outline should cover everything the top results cover, plus unique sections they miss.
### Step 2: Create the Outline
Build a detailed outline before writing. Every blog post follows this master structure:
```markdown
# [H1: Title - includes primary keyword, compelling, 50-60 chars for title tag]
Meta Title: [50-60 characters, primary keyword front-loaded]
Meta Description: [150-160 characters, includes keyword, has CTA, creates curiosity]
URL Slug: [primary-keyword-short-descriptive]
## Introduction (100-150 words)
- Hook: Open with a surprising stat, question, or relatable problem
- Context: Why this topic matters RIGHT NOW
- Promise: What the reader will learn/gain
- Primary keyword appears in first 100 words
## [H2: First major section - includes secondary keyword]
### [H3: Subsection if needed]
- Key points to cover
- Data or examples to include
## [H2: Second major section]
### [H3: Subsection]
...
## [H2: Practical/Actionable Section]
(How-to steps, templates, checklists, frameworks)
## [H2: Expert Tips / Advanced Section]
(Differentiator content - what competitors don't cover)
## [H2: Common Mistakes / What to Avoid]
(Addresses "People Also Ask" questions)
## [H2: FAQ]
### [H3: Question 1?]
Answer (2-4 sentences, targets featured snippet)
### [H3: Question 2?]
...
## Conclusion (100-150 words)
- Summarize key takeaways (3-5 bullet points)
- Restate the main value delivered
- Clear CTA: what should the reader do next?
## Internal Links Plan
- Link TO: [3-5 related pages on the site]
- Link FROM: [Pages that should link to this post]
```
### Step 3: Write the Content
Follow these writing rules strictly:
#### Title Tag Formula (50-60 characters)
Choose the best pattern for the intent:
| Intent | Formula | Example |
|--------|---------|---------|
| How-to | "How to {Action} ({Qualifier})" | "How to Start a Blog (Step-by-Step Guide)" |
| Listicle | "{Number} {Adjective} {Topic} for {Year/Audience}" | "15 Best SEO Tools for Small Business (2025)" |
| Guide | "{Topic}: The {Adjective} Guide for {Year}" | "Email Marketing: The Complete Guide for 2025" |
| Comparison | "{A} vs {B}: {Differentiator}" | "Notion vs Obsidian: Which Is Better for Teams?" |
| Question | "{Question}? {Promise}" | "Is SEO Dead? What the Data Actually Shows" |
**Title rules:**
- Primary keyword within first 30 characters
- Add a power word: Ultimate, Complete, Proven, Essential, Definitive
- Include year if the topic is time-sensitive
- Use numbers for listicles (odd numbers outperform: 7, 9, 11, 13)
- Never exceed 60 characters (Google truncates at ~580px)
#### Meta Description Formula (150-160 characters)
```
{What the article covers} + {Unique value prop} + {CTA or curiosity hook}
```
Examples:
- "Learn how to start a blog in 2025 with our step-by-step guide. Covers hosting, design, content, and monetization. Free checklist included."
- "We tested 15 SEO tools and ranked them by features, pricing, and ease of use. See which tool is best for your budget and goals."
**Meta description rules:**
- Include primary keyword naturally
- Include a CTA or curiosity element
- Use active voice
- Mention a specific deliverable (checklist, template, comparison, steps)
- Stay between 150-160 characters
#### Writing Style Rules
**Readability:**
- Paragraphs: 2-4 sentences max
- Sentences: 15-20 words average
- Use short sentences for emphasis. Like this.
- Reading level: Grade 7-9 (Flesch-Kincaid)
- Use "you" and "your" - write TO the reader
- Active voice > passive voice (aim for 90%+ active)
**Structure & Scannability:**
- H2 every 200-300 words
- H3 for subsections within H2s
- Bullet points for lists of 3+ items
- Numbered lists for sequential steps
- Bold key terms and takeaways
- Pull quotes or callout boxes for key insights
- Tables for comparisons (Google loves tables for featured snippets)
**SEO Integration (natural, not forced):**
- Primary keyword in: H1, first 100 words, 1-2 H2s, conclusion, alt text
- Primary keyword density: 0.5-1.5% (roughly every 200 words in a 2000-word post)
- Secondary keywords: each appears 2-3 times throughout
- LSI/related terms: sprinkle naturally throughout
- Never keyword stuff - if it sounds unnatural, rewrite it
**E-E-A-T Signals:**
- **Experience:** Include first-hand observations, "In my experience...", "When I tested..."
- **Expertise:** Reference specific methodologies, use precise terminology, show deep knowledge
- **Authoritativeness:** Cite authoritative sources (studies, official docs, industry leaders)
- **Trustworthiness:** Acknowledge limitations, present balanced views, link to sources
#### Content Depth Targets
| Article Type | Target Words | Sections (H2) | Images | Internal Links | External Links |
|-------------|-------------|----------------|--------|---------------|---------------|
| How-to Guide | 2000-3000 | 6-10 | 5-10 | 5-8 | 3-5 |
| Listicle | 2500-4000 | 1 per item + intro/conclusion | 1 per item | 5-10 | 3-5 |
| Ultimate Guide | 3000-5000 | 8-15 | 8-15 | 8-12 | 5-8 |
| Comparison | 1500-2500 | 5-8 | 3-5 | 3-5 | 2-4 |
| Opinion/Thought | 1000-1500 | 4-6 | 2-3 | 3-5 | 2-3 |
| News/Update | 800-1200 | 3-5 | 1-3 | 3-5 | 3-5 |
### Step 4: Optimize for Featured Snippets
Target featured snippets with these patterns:
**Paragraph snippet (definition/what is):**
```markdown
## What Is {Topic}?
{Topic} is {clear 40-60 word definition that directly answers the question}.
{Additional context in 1-2 more sentences}.
```
**List snippet (how-to/best of):**
```markdown
## How to {Action}
1. **{Step 1 title}** - Brief description
2. **{Step 2 title}** - Brief description
3. **{Step 3 title}** - Brief description
...
```
**Table snippet (comparison/data):**
```markdown
## {Comparison Topic}
| {Column 1} | {Column 2} | {Column 3} |
|------------|------------|------------|
| {Data} | {Data} | {Data} |
```
### Step 5: Add Supporting Elements
**Image suggestions:**
For each major section, suggest an image:
```markdown
[IMAGE: {Description of what the image should show}]
Alt text: "{Descriptive alt text with keyword where natural}"
```
**Image types to suggest:**
- Hero image (featured image for social sharing)
- Screenshots (for tutorials)
- Comparison tables (as images for Pinterest)
- Infographics (for key data points)
- Process diagrams (for step-by-step content)
- Charts/graphs (for data-driven claims)
**Internal link placement:**
- Contextual links within body paragraphs (most valuable)
- "Related reading" callout boxes between sections
- "Further reading" section at the end
- Anchor text should be descriptive, not "click here"
**External link rules:**
- Link to authoritative sources (studies, official docs, .edu, .gov)
- Open external links in new tab
- No-follow affiliate links and sponsored content
- Cite statistics with linked sources
### Step 6: FAQ Section
Every blog post should end with a FAQ section targeting "People Also Ask":
```markdown
## Frequently Asked Questions
### {Question matching PAA or long-tail keyword}?
{Direct answer in 2-4 sentences. Front-load the answer.
Provide additional context after the direct answer.
This format optimizes for both featured snippets and FAQ rich results.}
### {Second question}?
{Answer}
```
**FAQ rules:**
- 4-6 questions
- Questions should use natural language (how, what, why, when, can, does)
- Answer the question in the first sentence
- Keep each answer under 100 words
- Include schema markup (see schema-markup skill)
### Step 7: Final Quality Check
Before delivering the post, verify:
**SEO Checklist:**
- [ ] Title tag: 50-60 characters, keyword front-loaded
- [ ] Meta description: 150-160 characters, includes keyword, has CTA
- [ ] URL slug: Short, includes keyword, hyphenated
- [ ] H1: One per page, includes primary keyword
- [ ] H2s: Include secondary keywords where natural
- [ ] Primary keyword in first 100 words
- [ ] Keyword density: 0.5-1.5%
- [ ] Internal links: 5+ contextual links
- [ ] External links: 3+ authoritative sources
- [ ] Images: Alt text on all, keyword in at least one
- [ ] FAQ section with 4-6 questions
- [ ] Word count meets target for content type
- [ ] No duplicate content or thin sections
**Readability Checklist:**
- [ ] Average paragraph: 2-4 sentences
- [ ] Average sentence: under 20 words
- [ ] Grade level: 7-9
- [ ] Active voice: 90%+
- [ ] Power words in subheadings
- [ ] Bullet points or numbered lists every 300 words
- [ ] Bold text highlights key points
**E-E-A-T Checklist:**
- [ ] Author byline with credentials suggested
- [ ] Sources cited and linked
- [ ] First-hand experience or expertise demonstrated
- [ ] Balanced perspective (pros and cons, not just hype)
- [ ] Date published and "last updated" date included
- [ ] Factual accuracy verified (no made-up statistics)
## Output Format
Deliver the blog post in this format:
```markdown
---
title: "{Meta title - 50-60 chars}"
description: "{Meta description - 150-160 chars}"
slug: "{url-slug}"
keywords: ["{primary}", "{secondary1}", "{secondary2}"]
date: "{YYYY-MM-DD}"
author: "{Author name}"
---
# {H1 Headline}
{Full article content with all formatting, links, and image placeholders}
```
After the article, provide:
1. **SEO metadata summary** (title, description, slug, word count)
2. **Internal linking recommendations** (which pages to link to/from)
3. **Schema markup** (Article or BlogPosting JSON-LD)
4. **Social sharing** (suggested OG title, description, and image concept)
5. **Content promotion ideas** (2-3 distribution channels and angles)
## Important Notes
- Never fabricate statistics. If citing a number, include the source or note "[Source needed]".
- Write for humans first, search engines second. If an SEO tactic makes the content worse for readers, skip it.
- Every section must provide value. No filler paragraphs. If a section doesn't teach, convince, or entertain, cut it.
- Match the user's brand voice if they specify one. Ask if not clear.
- If the topic is YMYL (health, finance, legal), be extra careful with claims and heavily cite authoritative sources.
skills/write-landing/SKILL.md
+547
View File
@@ -0,0 +1,547 @@
---
name: write-landing
description: Create high-converting landing page copy and structure. Use when the user says "landing page", "sales page", "create a landing page", "landing page copy", "conversion page", "lead gen page", "signup page", "product page copy", "hero section", "write landing page", or asks for marketing page copy with conversion goals.
---
# Write Landing Page Skill
You are an expert conversion copywriter and landing page strategist. Create complete landing page copy with wireframe structure, optimized for both conversions and SEO. Output is ready to implement in Next.js/React with Tailwind CSS.
## Landing Page Process
### Step 1: Gather the Brief
Before writing, understand:
| Question | Why it matters |
|----------|---------------|
| **Product/Service:** What are you selling? | Core messaging foundation |
| **Target audience:** Who is the ideal customer? | Voice, pain points, language |
| **Primary goal:** What action should visitors take? | CTA optimization |
| **Traffic source:** How will people arrive? (Ads, organic, email) | Message match |
| **Price point:** How much does it cost? | Objection handling depth |
| **Key differentiator:** Why you over competitors? | USP positioning |
| **Proof points:** Testimonials, case studies, metrics? | Social proof section |
| **Existing brand voice:** Formal, casual, technical? | Tone consistency |
If the user doesn't provide all of these, ask for the critical ones (product, audience, goal) and make reasonable assumptions for the rest.
### Step 2: Choose the Page Structure
Select the right framework based on the product type and traffic temperature:
#### Framework A: PAS (Problem-Agitation-Solution)
**Best for:** Cold traffic, awareness stage, complex problems
```
Hero (Problem statement)
-> Agitate (Consequences of not solving)
-> Solution (Your product)
-> Features/Benefits
-> Social Proof
-> CTA
```
#### Framework B: AIDA (Attention-Interest-Desire-Action)
**Best for:** Warm traffic, known product category
```
Hero (Attention-grabbing headline)
-> Interest (Key features and hook)
-> Desire (Benefits, social proof, FOMO)
-> Action (CTA with urgency)
```
#### Framework C: Before-After-Bridge
**Best for:** Transformation products (SaaS, courses, coaching)
```
Hero (Before: current painful state)
-> After (Vision of success)
-> Bridge (Your product is the bridge)
-> How it works
-> Proof
-> CTA
```
#### Framework D: Feature-Benefit Grid
**Best for:** Technical products, SaaS, feature-rich tools
```
Hero (Bold promise)
-> Feature-benefit grid
-> How it works (3 steps)
-> Integrations/Compatibility
-> Pricing
-> FAQ
-> CTA
```
### Step 3: Write Each Section
#### Section 1: Hero
The hero section has 5 seconds to hook the visitor. Every word must earn its place.
**Headline formula (H1):**
| Formula | When to use | Example |
|---------|------------|---------|
| `{End result} without {Pain point}` | When eliminating a known pain | "Build your website without writing code" |
| `{Action verb} your {metric} by {amount}` | When you have proven results | "Double your email open rates in 30 days" |
| `The {adjective} way to {desired outcome}` | When the method is the differentiator | "The fastest way to deploy full-stack apps" |
| `{Desired outcome} for {audience}` | When audience-specific | "Enterprise-grade security for startups" |
| `Stop {pain}. Start {benefit}.` | When the problem is acute | "Stop losing leads. Start closing deals." |
| `{Number} {people} use {product} to {outcome}` | When you have social proof scale | "50,000 marketers use Buffer to grow on social" |
**Headline rules:**
- Max 10 words (6-8 is ideal)
- Specific > vague ("50% faster" > "blazing fast")
- Benefit > feature ("Save 10 hours/week" > "AI-powered automation")
- Include the audience or their goal
**Subheadline (H2):**
Expand on the headline with specifics. Formula:
```
{Product} helps {audience} {achieve outcome} by {mechanism/method}. {Proof point or time frame}.
```
Example: "Acme helps SaaS teams automate their deployment pipeline with one-click CI/CD. Ship 10x faster from day one."
**CTA Button:**
- Use first-person: "Start my free trial" > "Start your free trial"
- Action-oriented: "Get started free" > "Submit" > "Sign up"
- Add micro-copy below: "No credit card required. Free for 14 days."
- Button color should contrast with background (high contrast = more clicks)
**Supporting element (choose one):**
- Product screenshot or demo video
- Key metric ("Trusted by 10,000+ companies")
- Logo bar of notable customers
- Short demo GIF
```tsx
{/* Hero Section */}
<section className="relative bg-white pt-20 pb-16 sm:pt-24 sm:pb-20 lg:pt-32 lg:pb-28">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center lg:max-w-4xl">
{/* Eyebrow / Social proof badge */}
<p className="text-sm font-semibold text-indigo-600">
Trusted by 10,000+ teams
</p>
{/* H1 Headline */}
<h1 className="mt-4 text-4xl font-bold tracking-tight text-gray-900 sm:text-5xl lg:text-6xl">
{headline}
</h1>
{/* Subheadline */}
<p className="mt-6 text-lg leading-8 text-gray-600 sm:text-xl">
{subheadline}
</p>
{/* CTA Group */}
<div className="mt-10 flex flex-col items-center gap-4 sm:flex-row sm:justify-center">
<a href="#" className="rounded-lg bg-indigo-600 px-8 py-4 text-base font-semibold text-white shadow-sm hover:bg-indigo-500 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-indigo-600">
{primaryCTA}
</a>
<a href="#" className="text-base font-semibold text-gray-900 hover:text-gray-700">
{secondaryCTA} <span aria-hidden="true">&rarr;</span>
</a>
</div>
{/* Micro-copy */}
<p className="mt-4 text-sm text-gray-500">
No credit card required. Free 14-day trial.
</p>
</div>
{/* Hero Image/Video */}
<div className="mt-16 sm:mt-20">
<div className="rounded-xl bg-gray-900/5 p-2 ring-1 ring-gray-900/10 lg:rounded-2xl">
{/* Product screenshot or demo */}
</div>
</div>
</div>
</section>
```
---
#### Section 2: Problem / Pain Points
Make the reader feel understood. Describe their current situation precisely.
**Writing technique:** Use the reader's own language. Mirror the words they use in reviews, support tickets, and forums.
```tsx
<section className="bg-gray-50 py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">
{problem_headline}
</h2>
<p className="mt-4 text-lg text-gray-600">
{problem_description}
</p>
</div>
<div className="mt-12 grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
{/* Pain point cards */}
{painPoints.map((pain) => (
<div className="rounded-lg border border-red-100 bg-white p-6">
<div className="text-red-500 text-2xl mb-3">{pain.icon}</div>
<h3 className="text-lg font-semibold text-gray-900">{pain.title}</h3>
<p className="mt-2 text-gray-600">{pain.description}</p>
</div>
))}
</div>
</div>
</section>
```
**Pain point formula:**
```
Title: "{Frustrating situation}"
Description: "You {specific scenario}. But {consequence}. And {escalation}."
```
Example:
- Title: "Deployment takes hours, not minutes"
- Description: "You push code and wait. Build fails. Fix it. Wait again. By the time it's live, the bug report queue has doubled. And your weekend is gone."
---
#### Section 3: Solution / How It Works
Transition from pain to solution. Show the product as the bridge.
**"How It Works" in 3 steps** (always 3 - humans love triads):
```tsx
<section className="bg-white py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">
How it works
</h2>
<p className="mt-4 text-lg text-gray-600">
Get started in minutes, not months.
</p>
</div>
<div className="mt-16 grid grid-cols-1 gap-12 lg:grid-cols-3">
{steps.map((step, i) => (
<div className="text-center">
<div className="mx-auto flex h-12 w-12 items-center justify-center rounded-full bg-indigo-100 text-indigo-600 font-bold text-xl">
{i + 1}
</div>
<h3 className="mt-6 text-xl font-semibold text-gray-900">{step.title}</h3>
<p className="mt-4 text-gray-600">{step.description}</p>
</div>
))}
</div>
</div>
</section>
```
**Step formula:**
```
Step 1: "{Simple first action}" - Lower the barrier to entry
Step 2: "{Core value action}" - The product doing its thing
Step 3: "{Desired outcome}" - The result they care about
```
Example:
1. "Connect your repo" - Link your GitHub in one click
2. "Push your code" - Our AI handles builds, tests, and deployment
3. "Ship with confidence" - Go live in minutes with zero-downtime deploys
---
#### Section 4: Features & Benefits
Never list features alone. Always pair with the benefit (the "so what?").
**Feature-Benefit formula:**
```
Feature: {What it does}
Benefit: So you can {outcome the user cares about}
```
```tsx
<section className="bg-white py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">
Everything you need to {desired outcome}
</h2>
</div>
<div className="mt-16 grid grid-cols-1 gap-8 sm:grid-cols-2 lg:grid-cols-3">
{features.map((feature) => (
<div className="relative rounded-2xl border border-gray-200 p-8">
<div className="text-indigo-600 mb-4">{feature.icon}</div>
<h3 className="text-lg font-semibold text-gray-900">{feature.title}</h3>
<p className="mt-2 text-gray-600">{feature.benefit}</p>
</div>
))}
</div>
</div>
</section>
```
**Arrange features by importance:**
1. The feature that solves the #1 pain point (biggest, most prominent)
2. The feature that differentiates from competitors
3. Supporting features that round out the product
4. Nice-to-haves and integrations
---
#### Section 5: Social Proof
Social proof is the most persuasive element on the page. Layer multiple types:
**Types of social proof (use 2-3):**
| Type | Impact Level | Example |
|------|-------------|---------|
| Customer testimonials with photo + name + company | Highest | "Acme increased revenue 40% in 3 months" - Jane Doe, CEO at TechCo |
| Case study metrics | Highest | "From 2 deploys/week to 50 deploys/day" |
| Logo bar of customers | High | Well-known brand logos |
| Number of customers | High | "Join 50,000+ teams" |
| Star ratings / review scores | High | "4.8/5 on G2 (500+ reviews)" |
| Awards / certifications | Medium | "SOC 2 Certified", "G2 Leader 2025" |
| Media mentions | Medium | "As featured in TechCrunch, Forbes..." |
| Integration partners | Medium | "Works with Slack, GitHub, Jira..." |
```tsx
{/* Testimonial Section */}
<section className="bg-gray-50 py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">
Loved by teams worldwide
</h2>
</div>
<div className="mt-16 grid grid-cols-1 gap-8 lg:grid-cols-3">
{testimonials.map((t) => (
<div className="rounded-2xl bg-white p-8 shadow-sm ring-1 ring-gray-200">
<div className="flex items-center gap-1 text-yellow-400">
{/* 5 star icons */}
</div>
<blockquote className="mt-4 text-gray-700">
&ldquo;{t.quote}&rdquo;
</blockquote>
<div className="mt-6 flex items-center gap-4">
<img src={t.avatar} alt={t.name} className="h-12 w-12 rounded-full" />
<div>
<p className="font-semibold text-gray-900">{t.name}</p>
<p className="text-sm text-gray-500">{t.role} at {t.company}</p>
</div>
</div>
</div>
))}
</div>
{/* Logo bar */}
<div className="mt-16">
<p className="text-center text-sm font-semibold text-gray-500">
Trusted by leading companies
</p>
<div className="mt-6 flex flex-wrap items-center justify-center gap-x-12 gap-y-6">
{/* Customer logos */}
</div>
</div>
</div>
</section>
```
**Testimonial writing rules:**
- Include specific outcomes ("40% more leads" > "more leads")
- Include name, role, company, and photo (real > stock)
- Match testimonials to the objection they overcome
- Put the most impressive testimonial closest to the CTA
---
#### Section 6: Objection Handling / FAQ
Address the top 5-7 objections that prevent conversion:
**Common objection categories:**
| Objection | How to address |
|-----------|---------------|
| "It's too expensive" | ROI comparison, cost of inaction, payment plans |
| "I don't have time to set up" | Quick start time, onboarding support, migration help |
| "What if it doesn't work for me?" | Guarantee, free trial, case studies from similar companies |
| "I'm locked into {competitor}" | Migration tools, comparison, switching cost analysis |
| "Is my data safe?" | Security certifications, compliance, data policies |
| "What if I need help?" | Support channels, response time SLA, documentation |
| "It looks too complex" | 3-step "how it works", demo video, free trial |
```tsx
<section className="bg-white py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-3xl">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl text-center">
Frequently asked questions
</h2>
<dl className="mt-12 space-y-8">
{faqs.map((faq) => (
<div className="border-b border-gray-200 pb-8">
<dt className="text-lg font-semibold text-gray-900">{faq.question}</dt>
<dd className="mt-4 text-gray-600">{faq.answer}</dd>
</div>
))}
</dl>
</div>
</div>
</section>
```
---
#### Section 7: Pricing (if applicable)
Only include pricing on the landing page if:
- The product has clear, fixed pricing
- The user wants pricing on the page
- The traffic is warm/hot (they already know what the product does)
```tsx
<section className="bg-gray-50 py-16 sm:py-24" id="pricing">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-gray-900 sm:text-4xl">
Simple, transparent pricing
</h2>
<p className="mt-4 text-lg text-gray-600">
{pricing_subheadline}
</p>
</div>
<div className="mt-16 grid grid-cols-1 gap-8 lg:grid-cols-3">
{plans.map((plan) => (
<div className={`rounded-2xl p-8 ring-1 ${plan.featured ? 'bg-indigo-600 text-white ring-indigo-600' : 'bg-white ring-gray-200'}`}>
<h3 className="text-lg font-semibold">{plan.name}</h3>
<p className="mt-2 text-sm opacity-80">{plan.description}</p>
<p className="mt-6">
<span className="text-4xl font-bold">${plan.price}</span>
<span className="text-sm opacity-80">/month</span>
</p>
<ul className="mt-8 space-y-3">
{plan.features.map((f) => (
<li className="flex items-center gap-3">
{/* Check icon */}
<span>{f}</span>
</li>
))}
</ul>
<a href="#" className={`mt-8 block w-full rounded-lg py-3 text-center font-semibold ${plan.featured ? 'bg-white text-indigo-600' : 'bg-indigo-600 text-white'}`}>
{plan.cta}
</a>
</div>
))}
</div>
</div>
</section>
```
**Pricing copy rules:**
- Anchor with the highest plan first (or highlight the middle plan)
- Use specific numbers ("$49/mo" > "Starting at...")
- Show value: "$49/mo - less than the cost of one lost lead"
- Feature the most popular plan with a badge
- Include annual discount toggle if applicable
---
#### Section 8: Final CTA
The closing CTA should create urgency and restate the core value:
```tsx
<section className="bg-indigo-600 py-16 sm:py-24">
<div className="mx-auto max-w-7xl px-4 sm:px-6 lg:px-8">
<div className="mx-auto max-w-2xl text-center">
<h2 className="text-3xl font-bold tracking-tight text-white sm:text-4xl">
{final_headline}
</h2>
<p className="mt-4 text-lg text-indigo-100">
{final_subheadline}
</p>
<div className="mt-10">
<a href="#" className="rounded-lg bg-white px-8 py-4 text-base font-semibold text-indigo-600 shadow-sm hover:bg-indigo-50">
{finalCTA}
</a>
</div>
<p className="mt-4 text-sm text-indigo-200">
{risk_reversal - e.g., "30-day money-back guarantee. Cancel anytime."}
</p>
</div>
</div>
</section>
```
**Final CTA formulas:**
```
"Ready to {desired outcome}?"
"Start {action}ing today"
"Join {number}+ {audience} already {outcome}"
"Don't let {pain point} hold you back"
"{Outcome} is one click away"
```
### Step 4: SEO Optimization
Landing pages should rank too. Include:
**Meta tags:**
- Title: "{Product} - {Primary benefit} | {Brand}" (50-60 chars)
- Description: "{Product} helps {audience} {outcome}. {Proof point}. {CTA}." (150-160 chars)
**On-page SEO:**
- H1 includes primary keyword
- Primary keyword in first 100 words
- Image alt text with keyword
- Internal links to and from the landing page
- Schema markup (Product, Organization, FAQ, or SoftwareApplication)
**Reminder:** Landing pages for paid traffic may need `noindex` if they duplicate content from organic pages.
### Step 5: Conversion Optimization Checklist
Before delivering, verify:
- [ ] Single, clear CTA (one primary action per page)
- [ ] CTA appears 3+ times (hero, middle, end)
- [ ] CTA button text is action-oriented and first-person
- [ ] Page loads fast (minimize scripts, optimize images)
- [ ] Mobile responsive (all sections tested at 375px)
- [ ] No navigation menu (or minimal) to reduce exit points
- [ ] Social proof within scroll of first CTA
- [ ] Risk reversal near every CTA (guarantee, free trial, no CC)
- [ ] Benefit-first headlines (not feature-first)
- [ ] Specific numbers > vague claims
- [ ] White space between sections (not cluttered)
- [ ] Contrast on CTA buttons (stands out from page)
- [ ] Urgency element where authentic (limited spots, deadline, rising price)
## Output Format
Deliver in this order:
1. **Page strategy** - Framework chosen, audience, goal, messaging hierarchy
2. **Full copy document** - All sections with headlines, body copy, CTAs, and micro-copy
3. **Wireframe structure** - Section order with Tailwind component code
4. **SEO metadata** - Title, description, schema markup
5. **A/B test suggestions** - 2-3 elements to test first (headline, CTA, social proof)
## Important Notes
- Every claim needs proof. "Best tool" needs a G2 ranking. "Fastest" needs a benchmark. Unsubstantiated claims reduce trust.
- Write at a Grade 6-8 reading level. Simple words, short sentences, clear logic.
- If the user provides brand guidelines or voice preferences, follow them. If not, default to: confident, clear, conversational, not salesy.
- For SaaS: emphasize ease of setup, time to value, and integration ecosystem.
- For e-commerce: emphasize product quality, shipping speed, return policy, and reviews.
- For services: emphasize expertise, process, results, and risk reversal.