Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
ba3c85c92a | ||
|
|
2b45f16275 | ||
|
|
3826a38f88 | ||
|
|
44eb148f67 | ||
|
|
d95efdf556 | ||
|
|
33218ff1ca | ||
|
|
2e3ab04a49 | ||
|
|
2247e86e21 | ||
|
|
407693f5cd | ||
|
|
48b4d80b83 | ||
|
|
6c6017451d | ||
|
|
055f1818fc | ||
|
|
7b34569732 | ||
|
|
b363ec75a7 | ||
|
|
717890b2be | ||
|
|
30dbd7f793 | ||
|
|
5f2b4c06af | ||
|
|
2815104d54 | ||
|
|
b41f80c50a | ||
|
|
7852e3fd44 | ||
|
|
4160507a92 | ||
|
|
8bfcdffb65 | ||
|
|
6577c4d3d8 | ||
|
|
c033eb579d | ||
|
|
8dc0fe1f8f | ||
|
|
e934f4c95a | ||
|
|
a99ce71d8e | ||
|
|
699d027c15 | ||
|
|
3bea48edea | ||
|
|
8d0b7adce2 | ||
|
|
f0c3fe8887 | ||
|
|
bee3f2f42c | ||
|
|
abf10cface | ||
|
|
ff3a37dbc8 | ||
|
|
4b377f289b | ||
|
|
4fae86c626 | ||
|
|
6d00fcf644 | ||
|
|
d0d00c12ff | ||
|
|
4c198ab496 | ||
|
|
f45cbdb6c4 | ||
|
|
eadc5484ce | ||
|
|
a064dd837f | ||
|
|
91a9b42aa8 | ||
|
|
6f27a99f0a | ||
|
|
74d5bcb462 | ||
|
|
1e3bdacfa8 | ||
|
|
dce9908745 | ||
|
|
085bb4c01b | ||
|
|
9a1001fac1 | ||
|
|
29d42c399e | ||
|
|
c2f7f6482e | ||
|
|
e3a294055c | ||
|
|
310d5997f4 | ||
|
|
7f4af1ea8e | ||
|
|
3c6b8928fc | ||
|
|
8dd104c6c1 | ||
|
|
88414ceeba | ||
|
|
27f06a2b7b | ||
|
|
4286bbdc23 | ||
|
|
ed63ccd0eb | ||
|
|
3f4b4ffeb5 | ||
|
|
d9987d25c3 | ||
|
|
0b83502e5e | ||
|
|
6441f8c067 | ||
|
|
a6811561b7 | ||
|
|
e57899f2d5 | ||
|
|
1300f2ad4d | ||
|
|
b02566d7b1 | ||
|
|
fb2fff94eb | ||
|
|
8ced1fc9ef | ||
|
|
54c29da8ab | ||
|
|
f8ac011df5 | ||
|
|
bc9522e750 | ||
|
|
0c166511c8 | ||
|
|
ec31133ad9 | ||
|
|
692b76118c | ||
|
|
b69b236246 | ||
|
|
a10be10a9f | ||
|
|
f86637eace | ||
|
|
13fa45674c | ||
|
|
aa3cef76f9 | ||
|
|
3fb8bb625d | ||
|
|
e40125a746 | ||
|
|
0f39e12b76 | ||
|
|
d36433703b | ||
|
|
114587831e | ||
|
|
908500123b | ||
|
|
0fd7bb5ad9 | ||
|
|
4b54b0dd6f | ||
|
|
8b0a54eef9 | ||
|
|
c08ae5ff3d | ||
|
|
dc7fea85bf | ||
|
|
4b37de5228 | ||
|
|
75e8221af8 | ||
|
|
148fe208ed | ||
|
|
bd8eb1a0e5 | ||
|
|
bf173b731b | ||
|
|
0e2ef1301b | ||
|
|
76f18f0156 | ||
|
|
30f9b9a729 | ||
|
|
f3990f7f99 | ||
|
|
906c2fb28e | ||
|
|
34a39b0eb1 | ||
|
|
0c933b277e | ||
|
|
1bcff9fc79 | ||
|
|
e0829df01d | ||
|
|
b70440fa5f | ||
|
|
fd99bb8085 | ||
|
|
b831842fb7 | ||
|
|
07db354ccc | ||
|
|
64136709b6 | ||
|
|
affc3aab49 | ||
|
|
0cdc990715 | ||
|
|
737c3c6ea2 | ||
|
|
6b068a2c92 | ||
|
|
17923c78a9 | ||
|
|
194afa2f09 | ||
|
|
4036e776e2 | ||
|
|
11e3b0ff69 | ||
|
|
e18a04403b | ||
|
|
34501dd36c | ||
|
|
20443e1361 | ||
|
|
9698318a30 | ||
|
|
c8e2d11556 | ||
|
|
a45a348b08 | ||
|
|
5d48b351be | ||
|
|
cafdd38e58 | ||
|
|
c38fd75ec5 | ||
|
|
dfe912224e | ||
|
|
2ea0f0c2c7 | ||
|
|
f23b665461 | ||
|
|
880386085e | ||
|
|
dffa2fd3cb | ||
|
|
db34fa2a21 | ||
|
|
0d586e4952 | ||
|
|
9125d8216e | ||
|
|
50e72e0a2d | ||
|
|
978051caf1 | ||
|
|
e8623ad57d | ||
|
|
e659c764dd | ||
|
|
58a9947df4 | ||
|
|
ea4704a905 | ||
|
|
883f9b6380 | ||
|
|
743f718a7c | ||
|
|
4eaf647eef | ||
|
|
5616e31192 | ||
|
|
138dc3a9be | ||
|
|
2b4cccbfcf | ||
|
|
a04b00d810 | ||
|
|
2570f6ad4e | ||
|
|
eb4256891a | ||
|
|
3448f557de | ||
|
|
9f9c2d6f59 | ||
|
|
7df49f2be8 | ||
|
|
2c7c108bd5 | ||
|
|
fe670959f7 | ||
|
|
4874fe8979 | ||
|
|
d88009d1a4 | ||
|
|
78da95de86 | ||
|
|
7c2e29c526 | ||
|
|
49f520f4eb | ||
|
|
ef8e08ffd2 | ||
|
|
e10c33406c | ||
|
|
c31adfe89e | ||
|
|
1f295fa5c8 | ||
|
|
af9fe5fb09 | ||
|
|
bb54a76215 | ||
|
|
884cf5e108 | ||
|
|
295f1eef37 | ||
|
|
5c90bb8075 | ||
|
|
2fe1310881 | ||
|
|
6020ef6943 | ||
|
|
42ac956cb7 | ||
|
|
d10c161c04 | ||
|
|
76d1f89df9 | ||
|
|
85b93be6d6 | ||
|
|
d97425f15b | ||
|
|
dba8570870 | ||
|
|
28e8684fdd | ||
|
|
07a893efd0 | ||
|
|
fdb1202f12 | ||
|
|
314230b6db | ||
|
|
330d220aca | ||
|
|
c4cb25cb6c | ||
|
|
4ceaf88e96 | ||
|
|
7d85256e19 | ||
|
|
7c13fccdd9 | ||
|
|
b902ed2d79 | ||
|
|
47db68aaba | ||
|
|
fcac7f27b0 | ||
|
|
fd98062849 | ||
|
|
40f20b2736 | ||
|
|
7c8c087486 | ||
|
|
fcf4b4e784 | ||
|
|
cc1a9c106b | ||
|
|
cb4451c9a1 | ||
|
|
9d4d29a795 | ||
|
|
b0fbcabc5f | ||
|
|
6d08784211 | ||
|
|
b5a9bb57a9 | ||
|
|
6e47b53faf | ||
|
|
b970e9d8e4 | ||
|
|
869321e949 | ||
|
|
1c32ad3dbf | ||
|
|
51146da746 | ||
|
|
8657fd4f78 | ||
|
|
2f5db8d95c | ||
|
|
3a8d01283d | ||
|
|
68f5eaf64e | ||
|
|
51e29954fb | ||
|
|
a3ab09378b | ||
|
|
926c624d07 | ||
|
|
8c8090ed92 | ||
|
|
b325e41c91 | ||
|
|
b0a3a23699 | ||
|
|
7e7e7a09d8 | ||
|
|
11e9ea811f | ||
|
|
831dbe9616 | ||
|
|
6b1da2158e | ||
|
|
e4283c6616 | ||
|
|
633f9c642d | ||
|
|
89fd57a8b0 | ||
|
|
a2e646c2e6 | ||
|
|
9a2bb97784 | ||
|
|
4ff486a702 | ||
|
|
a3516be13d | ||
|
|
edd613d33f | ||
|
|
90a7e84d0e | ||
|
|
cac82f3a40 | ||
|
|
3a13e58808 | ||
|
|
e47e3a3073 | ||
|
|
8ea7487545 | ||
|
|
1622c8e398 | ||
|
|
ee28bc4359 | ||
|
|
f5badfe416 | ||
|
|
bc3253d30d | ||
|
|
12c34eb714 | ||
|
|
c4bc2fcc49 | ||
|
|
0c24410a0b | ||
|
|
066c420416 | ||
|
|
08c100bc7b | ||
|
|
8618c5bad2 | ||
|
|
488d09cda5 |
@@ -5,47 +5,15 @@
|
||||
"url": "https://corey.co"
|
||||
},
|
||||
"metadata": {
|
||||
"description": "Marketing skills for Claude Code — conversion optimization, copywriting, SEO, paid ads, and growth",
|
||||
"version": "1.0.0",
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, and growth",
|
||||
"version": "2.8.5",
|
||||
"repository": "https://github.com/coreyhaines31/marketingskills"
|
||||
},
|
||||
"plugins": [
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"description": "29 marketing skills for technical marketers and founders: CRO, copywriting, cold email, SEO, AI SEO, paid ads, ad creative, churn prevention, pricing strategy, referral programs, and more",
|
||||
"source": "./",
|
||||
"strict": false,
|
||||
"skills": [
|
||||
"./skills/ab-test-setup",
|
||||
"./skills/ad-creative",
|
||||
"./skills/ai-seo",
|
||||
"./skills/analytics-tracking",
|
||||
"./skills/churn-prevention",
|
||||
"./skills/cold-email",
|
||||
"./skills/competitor-alternatives",
|
||||
"./skills/content-strategy",
|
||||
"./skills/copy-editing",
|
||||
"./skills/copywriting",
|
||||
"./skills/email-sequence",
|
||||
"./skills/form-cro",
|
||||
"./skills/free-tool-strategy",
|
||||
"./skills/launch-strategy",
|
||||
"./skills/marketing-ideas",
|
||||
"./skills/marketing-psychology",
|
||||
"./skills/onboarding-cro",
|
||||
"./skills/page-cro",
|
||||
"./skills/paid-ads",
|
||||
"./skills/paywall-upgrade-cro",
|
||||
"./skills/popup-cro",
|
||||
"./skills/pricing-strategy",
|
||||
"./skills/product-marketing-context",
|
||||
"./skills/programmatic-seo",
|
||||
"./skills/referral-program",
|
||||
"./skills/schema-markup",
|
||||
"./skills/seo-audit",
|
||||
"./skills/signup-flow-cro",
|
||||
"./skills/social-content"
|
||||
]
|
||||
"description": "47 marketing skills for technical marketers and founders: CRO, copywriting, cold email, prospecting, SEO, AI SEO, paid ads, SMS, ad creative, video production, image generation, co-marketing, churn prevention, pricing, referrals, revenue operations, sales enablement, customer research, site architecture, comprehensive AARRR-structured marketing plans, public relations and earned media, offer design, and more",
|
||||
"source": "./"
|
||||
}
|
||||
]
|
||||
}
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
{
|
||||
"name": "marketing-skills",
|
||||
"description": "Marketing skills for AI agents — conversion optimization, copywriting, SEO, paid ads, ad creative, and growth",
|
||||
"version": "2.8.5",
|
||||
"author": {
|
||||
"name": "Corey Haines"
|
||||
},
|
||||
"homepage": "https://github.com/coreyhaines31/marketingskills",
|
||||
"repository": "https://github.com/coreyhaines31/marketingskills",
|
||||
"license": "MIT",
|
||||
"skills": "./skills"
|
||||
}
|
||||
@@ -69,6 +69,6 @@ body:
|
||||
attributes:
|
||||
label: Related existing skills
|
||||
description: Are there existing skills this relates to or differs from?
|
||||
placeholder: "Similar to page-cro but focused on..."
|
||||
placeholder: "Similar to cro but focused on..."
|
||||
validations:
|
||||
required: false
|
||||
|
||||
@@ -11,6 +11,7 @@ const path = require("path");
|
||||
|
||||
const SKILLS_DIR = "skills";
|
||||
const MARKETPLACE_FILE = ".claude-plugin/marketplace.json";
|
||||
const PLUGIN_FILE = ".claude-plugin/plugin.json";
|
||||
const README_FILE = "README.md";
|
||||
|
||||
/**
|
||||
@@ -132,27 +133,51 @@ function updateReadme(skills) {
|
||||
}
|
||||
|
||||
/**
|
||||
* Update marketplace.json with skills list
|
||||
* Update marketplace.json — refresh the skill count in the plugin description
|
||||
* and strip any `skills` array if present. Claude Code's plugin schema discovers
|
||||
* skills via the `skills/` directory; the explicit array fails validation, so
|
||||
* this script must never (re-)introduce it.
|
||||
*/
|
||||
function updateMarketplace(skills) {
|
||||
const marketplace = JSON.parse(fs.readFileSync(MARKETPLACE_FILE, "utf8"));
|
||||
const plugin = marketplace.plugins[0];
|
||||
const existingSkills = plugin.skills || [];
|
||||
const currentSkills = skills.map((s) => s.path);
|
||||
|
||||
if (JSON.stringify(currentSkills) === JSON.stringify(existingSkills)) {
|
||||
const oldDescription = plugin.description;
|
||||
const newDescription = updateSkillCount(plugin.description, skills.length);
|
||||
const hadStaleSkillsArray = "skills" in plugin;
|
||||
|
||||
if (newDescription === oldDescription && !hadStaleSkillsArray) {
|
||||
return { updated: false };
|
||||
}
|
||||
|
||||
plugin.skills = currentSkills;
|
||||
plugin.description = updateSkillCount(plugin.description, currentSkills.length);
|
||||
plugin.description = newDescription;
|
||||
delete plugin.skills;
|
||||
|
||||
fs.writeFileSync(MARKETPLACE_FILE, JSON.stringify(marketplace, null, 2) + "\n");
|
||||
|
||||
const added = currentSkills.filter((s) => !existingSkills.includes(s));
|
||||
const removed = existingSkills.filter((s) => !currentSkills.includes(s));
|
||||
return { updated: true, removedSkillsArray: hadStaleSkillsArray };
|
||||
}
|
||||
|
||||
return { updated: true, added, removed };
|
||||
/**
|
||||
* Update plugin.json's `version` field to match marketplace.json's
|
||||
* `metadata.version`. Claude Code uses plugin.json's version for the update
|
||||
* check (`claude plugin update`); if it drifts from marketplace.json the
|
||||
* update path silently breaks.
|
||||
*/
|
||||
function updatePluginVersion() {
|
||||
if (!fs.existsSync(PLUGIN_FILE)) return { updated: false };
|
||||
|
||||
const marketplace = JSON.parse(fs.readFileSync(MARKETPLACE_FILE, "utf8"));
|
||||
const plugin = JSON.parse(fs.readFileSync(PLUGIN_FILE, "utf8"));
|
||||
const marketplaceVersion = marketplace.metadata && marketplace.metadata.version;
|
||||
|
||||
if (!marketplaceVersion) return { updated: false };
|
||||
if (plugin.version === marketplaceVersion) return { updated: false };
|
||||
|
||||
const oldVersion = plugin.version;
|
||||
plugin.version = marketplaceVersion;
|
||||
fs.writeFileSync(PLUGIN_FILE, JSON.stringify(plugin, null, 2) + "\n");
|
||||
return { updated: true, oldVersion, newVersion: marketplaceVersion };
|
||||
}
|
||||
|
||||
function main() {
|
||||
@@ -160,22 +185,24 @@ function main() {
|
||||
|
||||
const marketplaceResult = updateMarketplace(skills);
|
||||
const readmeUpdated = updateReadme(skills);
|
||||
const pluginResult = updatePluginVersion();
|
||||
|
||||
if (!marketplaceResult.updated && !readmeUpdated) {
|
||||
if (!marketplaceResult.updated && !readmeUpdated && !pluginResult.updated) {
|
||||
console.log("Everything is already in sync");
|
||||
return;
|
||||
}
|
||||
|
||||
if (marketplaceResult.updated) {
|
||||
if (marketplaceResult.added.length) {
|
||||
console.log(`Added: ${marketplaceResult.added.join(", ")}`);
|
||||
}
|
||||
if (marketplaceResult.removed.length) {
|
||||
console.log(`Removed: ${marketplaceResult.removed.join(", ")}`);
|
||||
if (marketplaceResult.removedSkillsArray) {
|
||||
console.log("Stripped stale `skills` array from marketplace.json");
|
||||
}
|
||||
console.log(`Updated marketplace.json (${skills.length} skills)`);
|
||||
}
|
||||
|
||||
if (pluginResult.updated) {
|
||||
console.log(`Bumped plugin.json version: ${pluginResult.oldVersion} → ${pluginResult.newVersion}`);
|
||||
}
|
||||
|
||||
if (readmeUpdated) {
|
||||
console.log("Updated README.md skills table");
|
||||
}
|
||||
|
||||
@@ -5,6 +5,7 @@ on:
|
||||
branches: [main]
|
||||
paths:
|
||||
- 'skills/**'
|
||||
- '.claude-plugin/marketplace.json'
|
||||
|
||||
jobs:
|
||||
sync:
|
||||
@@ -26,5 +27,5 @@ jobs:
|
||||
with:
|
||||
commit_user_name: Coreybot
|
||||
commit_user_email: coreybot+github-actions[bot]@users.noreply.github.com
|
||||
commit_message: "chore: sync skills with marketplace.json and README"
|
||||
file_pattern: ".claude-plugin/marketplace.json README.md"
|
||||
commit_message: "chore: sync skills with marketplace.json, plugin.json, and README"
|
||||
file_pattern: ".claude-plugin/marketplace.json .claude-plugin/plugin.json README.md"
|
||||
|
||||
+7
-2
@@ -1,6 +1,11 @@
|
||||
# Dependencies
|
||||
node_modules/
|
||||
|
||||
# Skill install artifacts (npx skills add)
|
||||
.agents/
|
||||
.claude/
|
||||
skills-lock.json
|
||||
|
||||
# Environment variables / secrets
|
||||
.env
|
||||
.env.*
|
||||
@@ -14,8 +19,8 @@ node_modules/
|
||||
* 2.*
|
||||
* 2/
|
||||
|
||||
# Remotion video project
|
||||
video/
|
||||
# Remotion video project (root only, not skills/video/)
|
||||
/video/
|
||||
|
||||
# Editor
|
||||
*.swp
|
||||
|
||||
@@ -4,7 +4,7 @@ Guidelines for AI agents working in this repository.
|
||||
|
||||
## Repository Overview
|
||||
|
||||
This repository contains **Agent Skills** for AI agents following the [Agent Skills specification](https://agentskills.io/specification.md). It also serves as a **Claude Code plugin marketplace** via `.claude-plugin/marketplace.json`.
|
||||
This repository contains **Agent Skills** for AI agents following the [Agent Skills specification](https://agentskills.io/specification.md). Skills install to `.agents/skills/` (the cross-agent standard). This repo also serves as a **Claude Code plugin marketplace** via `.claude-plugin/marketplace.json`.
|
||||
|
||||
- **Name**: Marketing Skills
|
||||
- **GitHub**: [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills)
|
||||
@@ -22,6 +22,7 @@ marketingskills/
|
||||
│ └── SKILL.md # Required skill file
|
||||
├── tools/
|
||||
│ ├── clis/ # Zero-dependency Node.js CLI tools (51 tools)
|
||||
│ ├── composio/ # Composio integration layer (quick start + toolkit mapping)
|
||||
│ ├── integrations/ # API integration guides per tool
|
||||
│ └── REGISTRY.md # Tool index with capabilities
|
||||
├── CONTRIBUTING.md
|
||||
@@ -44,6 +45,22 @@ node tools/clis/<name>.js # Show usage (no args = help)
|
||||
node tools/clis/<name>.js <cmd> --dry-run # Preview request without sending
|
||||
```
|
||||
|
||||
## Versioning
|
||||
|
||||
Two version layers, with different rules:
|
||||
|
||||
**Repo release version** — `.claude-plugin/plugin.json` `version`, `.claude-plugin/marketplace.json` `metadata.version`, and the `VERSIONS.md` changelog headings all share one x.y.z number:
|
||||
|
||||
- **x** — repo-wide changes (restructures, spec changes, breaking changes)
|
||||
- **y** — new skill(s) added
|
||||
- **z** — updates to existing skills
|
||||
|
||||
Do not bump y for content added to an existing skill, no matter how substantial — that's a z release (e.g. a new reference file in ad-creative is 2.8.0 → 2.8.1, not 2.9.0).
|
||||
|
||||
**Per-skill version** — `metadata.version` in each SKILL.md, mirrored in the `VERSIONS.md` table. Bump on ANY shipped change to that skill: the update check compares `VERSIONS.md` against users' local skill metadata, so an unbumped change is invisible to installed users. Minor for new capability or description triggers, patch for fixes and clarifications.
|
||||
|
||||
Bump the repo release version in the same PR that ships the change (2.7.0 and 2.8.0 shipped without touching plugin.json/marketplace.json and needed a catch-up later).
|
||||
|
||||
## Agent Skills Specification
|
||||
|
||||
Skills follow the [Agent Skills spec](https://agentskills.io/specification.md).
|
||||
@@ -73,7 +90,7 @@ description: What this skill does and when to use it. Include trigger phrases.
|
||||
- No consecutive hyphens (`--`)
|
||||
- Must match parent directory name exactly
|
||||
|
||||
**Valid**: `page-cro`, `email-sequence`, `ab-test-setup`
|
||||
**Valid**: `cro`, `emails`, `ab-testing`
|
||||
**Invalid**: `Page-CRO`, `-page`, `page--cro`
|
||||
|
||||
### Optional Skill Directories
|
||||
@@ -123,7 +140,7 @@ The `description` is critical for skill discovery. Include:
|
||||
3. Related skills for scope boundaries
|
||||
|
||||
```yaml
|
||||
description: When the user wants to optimize conversions on any marketing page. Use when the user says "CRO," "conversion rate optimization," "this page isn't converting." For signup flows, see signup-flow-cro.
|
||||
description: When the user wants to optimize conversions on any marketing page. Use when the user says "CRO," "conversion rate optimization," "this page isn't converting." For signup flows, see signup.
|
||||
```
|
||||
|
||||
## Claude Code Plugin
|
||||
@@ -150,7 +167,7 @@ See [Claude Code plugins documentation](https://code.claude.com/docs/en/plugins.
|
||||
Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
|
||||
|
||||
- `feat: add skill-name skill`
|
||||
- `fix: improve clarity in page-cro`
|
||||
- `fix: improve clarity in cro`
|
||||
- `docs: update README`
|
||||
|
||||
### Pull Request Checklist
|
||||
@@ -167,7 +184,8 @@ This repository includes a tools registry for agent-compatible marketing tools.
|
||||
|
||||
- **Tool discovery**: Read `tools/REGISTRY.md` to see available tools and their capabilities
|
||||
- **Integration details**: See `tools/integrations/{tool}.md` for API endpoints, auth, and common operations
|
||||
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier
|
||||
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam, introw, composio
|
||||
- **Composio** (integration layer): Adds MCP access to OAuth-heavy tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, etc.). See `tools/integrations/composio.md`
|
||||
|
||||
### Registry Structure
|
||||
|
||||
@@ -184,10 +202,12 @@ tools/
|
||||
### When to Use Tools
|
||||
|
||||
Skills reference relevant tools for implementation. For example:
|
||||
- `referral-program` skill → rewardful, tolt, dub-co, mention-me guides
|
||||
- `analytics-tracking` skill → ga4, mixpanel, segment guides
|
||||
- `email-sequence` skill → customer-io, mailchimp, resend guides
|
||||
- `paid-ads` skill → google-ads, meta-ads, linkedin-ads guides
|
||||
- `referrals` skill → rewardful, tolt, dub-co, mention-me guides
|
||||
- `analytics` skill → ga4, mixpanel, segment guides
|
||||
- `emails` skill → customer-io, mailchimp, resend guides
|
||||
- `ads` skill → google-ads, meta-ads, linkedin-ads guides
|
||||
|
||||
For tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion), Composio provides MCP access via a single server. See `tools/integrations/composio.md` for setup and `tools/composio/marketing-tools.md` for the full toolkit mapping.
|
||||
|
||||
## Checking for Updates
|
||||
|
||||
@@ -215,3 +235,36 @@ When using any skill from this repository:
|
||||
## Skill Categories
|
||||
|
||||
See `README.md` for the current list of skills organized by category. When adding new skills, follow the naming patterns of existing skills in that category.
|
||||
|
||||
## Claude Code-Specific Enhancements
|
||||
|
||||
These patterns are **Claude Code only** and must not be added to `SKILL.md` files directly, as skills are designed to be cross-agent compatible (Codex, Cursor, Windsurf, etc.). Apply them locally in your own project's `.claude/skills/` overrides instead.
|
||||
|
||||
### Dynamic content injection with `!`command``
|
||||
|
||||
Claude Code supports embedding shell commands in SKILL.md using `` !`command` `` syntax. When the skill is invoked, Claude Code runs the command and injects the output inline — the model sees the result, not the instruction.
|
||||
|
||||
**Most useful application: auto-inject the product marketing context file**
|
||||
|
||||
Instead of every skill telling the agent "go check if `.agents/product-marketing.md` exists and read it," you can inject it automatically:
|
||||
|
||||
```markdown
|
||||
Product context: !`cat .agents/product-marketing.md 2>/dev/null || echo "No product context file found — ask the user about their product before proceeding."`
|
||||
```
|
||||
|
||||
Place this at the top of a skill's body (after frontmatter) to make context available immediately without any file-reading step.
|
||||
|
||||
**Other useful injections:**
|
||||
|
||||
```markdown
|
||||
# Inject today's date for recency-sensitive skills
|
||||
Today's date: !`date +%Y-%m-%d`
|
||||
|
||||
# Inject current git branch (useful for workflow skills)
|
||||
Current branch: !`git branch --show-current 2>/dev/null`
|
||||
|
||||
# Inject recent commits for context
|
||||
Recent commits: !`git log --oneline -5 2>/dev/null`
|
||||
```
|
||||
|
||||
**Why this is Claude Code-only**: Other agents that load skills will see the literal `` !`command` `` string rather than executing it, which would appear as garbled instructions. Keep cross-agent skill files free of this syntax.
|
||||
|
||||
+1
-1
@@ -33,7 +33,7 @@ Optional frontmatter fields: `license` (default: MIT), `metadata` (author, versi
|
||||
|
||||
### 3. Follow the naming conventions
|
||||
|
||||
- **Directory name**: lowercase, hyphens only (e.g., `email-sequence`)
|
||||
- **Directory name**: lowercase, hyphens only (e.g., `emails`)
|
||||
- **Name field**: must match directory name exactly
|
||||
- **Description**: 1-1024 characters, include trigger phrases
|
||||
|
||||
|
||||
@@ -1,51 +1,108 @@
|
||||
# Marketing Skills for Claude Code
|
||||
# Marketing Skills for AI Agents
|
||||
|
||||
A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want Claude Code (or similar AI coding assistants) to help with conversion optimization, copywriting, SEO, analytics, and growth engineering.
|
||||
A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want AI coding agents to help with conversion optimization, copywriting, SEO, analytics, and growth engineering. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the [Agent Skills spec](https://agentskills.io).
|
||||
|
||||
Built by [Corey Haines](https://corey.co?ref=marketingskills). Need hands-on help? Check out [Conversion Factory](https://conversionfactory.co?ref=marketingskills) — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to [Swipe Files](https://swipefiles.com?ref=marketingskills).
|
||||
Built by [Corey Haines](https://corey.co?ref=marketingskills). Need hands-on help? Check out [Conversion Factory](https://conversionfactory.co?ref=marketingskills) — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to [Swipe Files](https://swipefiles.com?ref=marketingskills). Want to get dangerously good at using AI for marketing? Check out [AI Marketing Training](https://conversionfactory.co/offers/ai-marketing-training?ref=marketingskills). Want an autonomous AI agent that uses these skills to be your CMO? Try [Magister](https://magistermarketing.com?ref=marketingskills).
|
||||
|
||||
New to the terminal and coding agents? Check out the companion guide [Coding for Marketers](https://codingformarketers.com?ref=marketingskills).
|
||||
|
||||
**Contributions welcome!** Found a way to improve a skill or have a new one to add? [Open a PR](#contributing).
|
||||
|
||||
Run into a problem or have a question? [Open an issue](https://github.com/coreyhaines31/marketingskills/issues) — we're happy to help.
|
||||
|
||||
## What are Skills?
|
||||
|
||||
Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, Claude Code can recognize when you're working on a marketing task and apply the right frameworks and best practices.
|
||||
Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, your agent can recognize when you're working on a marketing task and apply the right frameworks and best practices.
|
||||
|
||||
## How Skills Work Together
|
||||
|
||||
Skills reference each other and build on shared context. The `product-marketing` skill is the foundation — every other skill checks it first to understand your product, audience, and positioning before doing anything.
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────┐
|
||||
│ product-marketing │
|
||||
│ (read by all other skills first) │
|
||||
└──────────────────┬───────────────────┘
|
||||
│
|
||||
┌──────────────┬─────────────┬─────────────┼─────────────┬──────────────┬──────────────┐
|
||||
▼ ▼ ▼ ▼ ▼ ▼ ▼
|
||||
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────┐
|
||||
│ SEO & │ │ CRO │ │Content & │ │ Paid & │ │ Growth & │ │ Sales & │ │ Strategy │
|
||||
│ Content │ │ │ │ Copy │ │Measurement │ │Retention │ │ GTM │ │ │
|
||||
├──────────┤ ├──────────┤ ├──────────┤ ├────────────┤ ├──────────┤ ├─────────────┤ ├───────────┤
|
||||
│seo-audit │ │cro │ │copywritng│ │ads │ │referrals │ │revops │ │mktg-ideas │
|
||||
│ai-seo │ │signup │ │copy-edit │ │ad-creative │ │free-tools│ │sales-enable │ │mktg-psych │
|
||||
│site-arch │ │onboarding│ │cold-email│ │ab-testing │ │churn- │ │launch │ │customer- │
|
||||
│programm │ │popups │ │emails │ │analytics │ │ prevent │ │pricing │ │ research │
|
||||
│schema │ │paywalls │ │social │ │ │ │community │ │competitors │ │ │
|
||||
│content │ │ │ │video │ │ │ │lead-magnt│ │comp-profile │ │ │
|
||||
│aso │ │ │ │image │ │ │ │co-mktg │ │directory │ │ │
|
||||
│ │ │ │ │sms │ │ │ │ │ │prospecting │ │ │
|
||||
└────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └──────┬──────┘ └─────┬─────┘
|
||||
│ │ │ │ │ │ │
|
||||
└────────────┴─────┬──────┴──────────────┴─────────────┴──────────────┴──────────────┘
|
||||
│
|
||||
Skills cross-reference each other:
|
||||
copywriting ↔ cro ↔ ab-testing
|
||||
revops ↔ sales-enablement ↔ cold-email
|
||||
seo-audit ↔ schema ↔ ai-seo
|
||||
customer-research → copywriting, cro, competitors
|
||||
```
|
||||
|
||||
See each skill's **Related Skills** section for the full dependency map.
|
||||
|
||||
## Available Skills
|
||||
|
||||
<!-- SKILLS:START -->
|
||||
| Skill | Description |
|
||||
|-------|-------------|
|
||||
| [ab-test-setup](skills/ab-test-setup/) | When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B... |
|
||||
| [ab-testing](skills/ab-testing/) | When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program.... |
|
||||
| [ad-creative](skills/ad-creative/) | When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad... |
|
||||
| [ads](skills/ads/) | When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X,... |
|
||||
| [ai-seo](skills/ai-seo/) | When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers.... |
|
||||
| [analytics-tracking](skills/analytics-tracking/) | When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions... |
|
||||
| [analytics](skills/analytics/) | When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions... |
|
||||
| [aso](skills/aso/) | When the user wants to audit or optimize an App Store or Google Play listing. Also use when the user mentions 'ASO... |
|
||||
| [churn-prevention](skills/churn-prevention/) | When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or... |
|
||||
| [co-marketing](skills/co-marketing/) | When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use... |
|
||||
| [cold-email](skills/cold-email/) | Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails,... |
|
||||
| [competitor-alternatives](skills/competitor-alternatives/) | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when... |
|
||||
| [community-marketing](skills/community-marketing/) | Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a... |
|
||||
| [competitor-profiling](skills/competitor-profiling/) | When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions... |
|
||||
| [competitors](skills/competitors/) | When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when... |
|
||||
| [content-strategy](skills/content-strategy/) | When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also... |
|
||||
| [copy-editing](skills/copy-editing/) | When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this... |
|
||||
| [copy-editing](skills/copy-editing/) | When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the... |
|
||||
| [copywriting](skills/copywriting/) | When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages,... |
|
||||
| [email-sequence](skills/email-sequence/) | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email... |
|
||||
| [form-cro](skills/form-cro/) | When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms,... |
|
||||
| [free-tool-strategy](skills/free-tool-strategy/) | When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or... |
|
||||
| [launch-strategy](skills/launch-strategy/) | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user... |
|
||||
| [cro](skills/cro/) | When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage,... |
|
||||
| [customer-research](skills/customer-research/) | When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer... |
|
||||
| [directory-submissions](skills/directory-submissions/) | When the user wants to submit their product to startup, SaaS, AI, agent, MCP, no-code, or review directories for... |
|
||||
| [emails](skills/emails/) | When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email... |
|
||||
| [free-tools](skills/free-tools/) | When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or... |
|
||||
| [image](skills/image/) | When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product... |
|
||||
| [launch](skills/launch/) | When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user... |
|
||||
| [lead-magnets](skills/lead-magnets/) | When the user wants to create, plan, or optimize a lead magnet for email capture or lead generation. Also use when the... |
|
||||
| [marketing-council](skills/marketing-council/) | When the user wants multiple expert perspectives on a marketing question — a simulated board of advisors staffed by... |
|
||||
| [marketing-ideas](skills/marketing-ideas/) | When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the... |
|
||||
| [marketing-loops](skills/marketing-loops/) | When the user wants to set up a recurring, self-running marketing workflow — a repeatable loop an AI agent runs on a... |
|
||||
| [marketing-plan](skills/marketing-plan/) | When the user needs a comprehensive marketing plan for a client, a company they advise, or their own product. Also use... |
|
||||
| [marketing-psychology](skills/marketing-psychology/) | When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when... |
|
||||
| [onboarding-cro](skills/onboarding-cro/) | When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also... |
|
||||
| [page-cro](skills/page-cro/) | When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing... |
|
||||
| [paid-ads](skills/paid-ads/) | When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X,... |
|
||||
| [paywall-upgrade-cro](skills/paywall-upgrade-cro/) | When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use... |
|
||||
| [popup-cro](skills/popup-cro/) | When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also... |
|
||||
| [pricing-strategy](skills/pricing-strategy/) | When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions... |
|
||||
| [product-marketing-context](skills/product-marketing-context/) | When the user wants to create or update their product marketing context document. Also use when the user mentions... |
|
||||
| [offers](skills/offers/) | When the user wants to design, construct, or improve an offer — the thing they actually sell — including value framing,... |
|
||||
| [onboarding](skills/onboarding/) | When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also... |
|
||||
| [paywalls](skills/paywalls/) | When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use... |
|
||||
| [popups](skills/popups/) | When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also... |
|
||||
| [pricing](skills/pricing/) | When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions... |
|
||||
| [product-marketing](skills/product-marketing/) | When the user wants to create or update their product marketing context document. Also use when the user mentions... |
|
||||
| [programmatic-seo](skills/programmatic-seo/) | When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions... |
|
||||
| [referral-program](skills/referral-program/) | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy.... |
|
||||
| [schema-markup](skills/schema-markup/) | When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user... |
|
||||
| [prospecting](skills/prospecting/) | When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or... |
|
||||
| [public-relations](skills/public-relations/) | When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy... |
|
||||
| [referrals](skills/referrals/) | When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy.... |
|
||||
| [revops](skills/revops/) | When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes.... |
|
||||
| [sales-enablement](skills/sales-enablement/) | When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also... |
|
||||
| [schema](skills/schema/) | When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user... |
|
||||
| [seo-audit](skills/seo-audit/) | When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO... |
|
||||
| [signup-flow-cro](skills/signup-flow-cro/) | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the... |
|
||||
| [social-content](skills/social-content/) | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram,... |
|
||||
| [signup](skills/signup/) | When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the... |
|
||||
| [site-architecture](skills/site-architecture/) | When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal... |
|
||||
| [sms](skills/sms/) | When the user wants to plan, build, or optimize SMS or MMS marketing — including welcome flows, abandoned cart texts,... |
|
||||
| [social](skills/social/) | When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram,... |
|
||||
| [video](skills/video/) | When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use... |
|
||||
<!-- SKILLS:END -->
|
||||
|
||||
## Installation
|
||||
@@ -59,13 +116,13 @@ Use [npx skills](https://github.com/vercel-labs/skills) to install skills direct
|
||||
npx skills add coreyhaines31/marketingskills
|
||||
|
||||
# Install specific skills
|
||||
npx skills add coreyhaines31/marketingskills --skill page-cro copywriting
|
||||
npx skills add coreyhaines31/marketingskills --skill cro copywriting
|
||||
|
||||
# List available skills
|
||||
npx skills add coreyhaines31/marketingskills --list
|
||||
```
|
||||
|
||||
This automatically installs to your `.claude/skills/` directory.
|
||||
This automatically installs to your `.agents/skills/` directory (and symlinks into `.claude/skills/` for Claude Code compatibility).
|
||||
|
||||
### Option 2: Claude Code Plugin
|
||||
|
||||
@@ -85,7 +142,7 @@ Clone the entire repo and copy the skills folder:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/coreyhaines31/marketingskills.git
|
||||
cp -r marketingskills/skills/* .claude/skills/
|
||||
cp -r marketingskills/skills/* .agents/skills/
|
||||
```
|
||||
|
||||
### Option 4: Git Submodule
|
||||
@@ -93,10 +150,10 @@ cp -r marketingskills/skills/* .claude/skills/
|
||||
Add as a submodule for easy updates:
|
||||
|
||||
```bash
|
||||
git submodule add https://github.com/coreyhaines31/marketingskills.git .claude/marketingskills
|
||||
git submodule add https://github.com/coreyhaines31/marketingskills.git .agents/marketingskills
|
||||
```
|
||||
|
||||
Then reference skills from `.claude/marketingskills/skills/`.
|
||||
Then reference skills from `.agents/marketingskills/skills/`.
|
||||
|
||||
### Option 5: Fork and Customize
|
||||
|
||||
@@ -113,83 +170,143 @@ Use [SkillKit](https://github.com/rohitg00/skillkit) to install skills across mu
|
||||
npx skillkit install coreyhaines31/marketingskills
|
||||
|
||||
# Install specific skills
|
||||
npx skillkit install coreyhaines31/marketingskills --skill page-cro copywriting
|
||||
npx skillkit install coreyhaines31/marketingskills --skill cro copywriting
|
||||
|
||||
# List available skills
|
||||
npx skillkit install coreyhaines31/marketingskills --list
|
||||
```
|
||||
|
||||
## Upgrading from v1.x to v2.0
|
||||
|
||||
v2.0 renames 17 skills and consolidates `page-cro` + `form-cro` into a single `cro` skill. If you installed the v1.x skills, you'll have **stale old-name folders** in your install directory after upgrading — the new skills install alongside the old ones, so you'll see both `skills/page-cro/` and `skills/cro/`, etc. Clean them up:
|
||||
|
||||
```bash
|
||||
# From the directory where you installed the skills (e.g., .agents/skills/ or .claude/skills/)
|
||||
rm -rf page-cro form-cro \
|
||||
ab-test-setup analytics-tracking aso-audit competitor-alternatives \
|
||||
email-sequence free-tool-strategy launch-strategy onboarding-cro \
|
||||
paid-ads paywall-upgrade-cro popup-cro pricing-strategy \
|
||||
product-marketing-context referral-program schema-markup \
|
||||
signup-flow-cro social-content
|
||||
```
|
||||
|
||||
Then reinstall the v2.0 skills via your usual method (e.g., `npx skills add coreyhaines31/marketingskills`).
|
||||
|
||||
### Migrate the product marketing context file
|
||||
|
||||
In v2.0 the context file moved from `.claude/` to `.agents/` and was renamed from `product-marketing-context.md` to `product-marketing.md`. Move your existing context file:
|
||||
|
||||
```bash
|
||||
mkdir -p .agents
|
||||
# v2.0 file (or pre-v2.0 file with new name)
|
||||
mv .claude/product-marketing.md .agents/product-marketing.md 2>/dev/null
|
||||
# pre-v2.0 file with legacy name
|
||||
mv .claude/product-marketing-context.md .agents/product-marketing.md 2>/dev/null
|
||||
```
|
||||
|
||||
Skills will still check `.claude/` and the legacy `product-marketing-context.md` filename as fallbacks, so nothing breaks if you don't migrate.
|
||||
|
||||
### Full rename map
|
||||
|
||||
| Old | New |
|
||||
|-----|-----|
|
||||
| `ab-test-setup` | `ab-testing` |
|
||||
| `analytics-tracking` | `analytics` |
|
||||
| `aso-audit` | `aso` |
|
||||
| `competitor-alternatives` | `competitors` |
|
||||
| `email-sequence` | `emails` |
|
||||
| `form-cro` | merged into `cro` |
|
||||
| `free-tool-strategy` | `free-tools` |
|
||||
| `launch-strategy` | `launch` |
|
||||
| `onboarding-cro` | `onboarding` |
|
||||
| `page-cro` | `cro` |
|
||||
| `paid-ads` | `ads` |
|
||||
| `paywall-upgrade-cro` | `paywalls` |
|
||||
| `popup-cro` | `popups` |
|
||||
| `pricing-strategy` | `pricing` |
|
||||
| `product-marketing-context` | `product-marketing` |
|
||||
| `referral-program` | `referrals` |
|
||||
| `schema-markup` | `schema` |
|
||||
| `signup-flow-cro` | `signup` |
|
||||
| `social-content` | `social` |
|
||||
|
||||
## Usage
|
||||
|
||||
Once installed, just ask Claude Code to help with marketing tasks:
|
||||
Once installed, just ask your agent to help with marketing tasks:
|
||||
|
||||
```
|
||||
"Help me optimize this landing page for conversions"
|
||||
→ Uses page-cro skill
|
||||
→ Uses cro skill
|
||||
|
||||
"Write homepage copy for my SaaS"
|
||||
→ Uses copywriting skill
|
||||
|
||||
"Set up GA4 tracking for signups"
|
||||
→ Uses analytics-tracking skill
|
||||
→ Uses analytics skill
|
||||
|
||||
"Create a 5-email welcome sequence"
|
||||
→ Uses email-sequence skill
|
||||
→ Uses emails skill
|
||||
```
|
||||
|
||||
You can also invoke skills directly:
|
||||
|
||||
```
|
||||
/page-cro
|
||||
/email-sequence
|
||||
/cro
|
||||
/emails
|
||||
/seo-audit
|
||||
```
|
||||
|
||||
## Skill Categories
|
||||
|
||||
### Conversion Optimization
|
||||
- `page-cro` - Any marketing page
|
||||
- `signup-flow-cro` - Registration flows
|
||||
- `onboarding-cro` - Post-signup activation
|
||||
- `form-cro` - Lead capture forms
|
||||
- `popup-cro` - Modals and overlays
|
||||
- `paywall-upgrade-cro` - In-app upgrade moments
|
||||
- `cro` - Pages and forms
|
||||
- `signup` - Registration flows
|
||||
- `onboarding` - Post-signup activation
|
||||
- `popups` - Modals and overlays
|
||||
- `paywalls` - In-app upgrade moments
|
||||
|
||||
### Content & Copy
|
||||
- `copywriting` - Marketing page copy
|
||||
- `copy-editing` - Edit and polish existing copy
|
||||
- `cold-email` - B2B cold outreach emails and sequences
|
||||
- `email-sequence` - Automated email flows
|
||||
- `social-content` - Social media content
|
||||
- `emails` - Automated email flows
|
||||
- `social` - Social media content
|
||||
- `image` - AI image generation, design tools, and optimization
|
||||
|
||||
### SEO & Discovery
|
||||
- `seo-audit` - Technical and on-page SEO
|
||||
- `ai-seo` - AI search optimization (AEO, GEO, LLMO)
|
||||
- `programmatic-seo` - Scaled page generation
|
||||
- `competitor-alternatives` - Comparison and alternative pages
|
||||
- `schema-markup` - Structured data
|
||||
- `site-architecture` - Page hierarchy, navigation, URL structure
|
||||
- `competitors` - Comparison and alternative pages
|
||||
- `schema` - Structured data
|
||||
|
||||
### Paid & Distribution
|
||||
- `paid-ads` - Google, Meta, LinkedIn ad campaigns
|
||||
- `ads` - Google, Meta, LinkedIn ad campaigns
|
||||
- `ad-creative` - Bulk ad creative generation and iteration
|
||||
- `social-content` - Social media scheduling and strategy
|
||||
- `social` - Social media scheduling and strategy
|
||||
|
||||
### Measurement & Testing
|
||||
- `analytics-tracking` - Event tracking setup
|
||||
- `ab-test-setup` - Experiment design
|
||||
- `analytics` - Event tracking setup
|
||||
- `ab-testing` - Experiment design
|
||||
|
||||
### Retention
|
||||
- `churn-prevention` - Cancel flows, save offers, dunning, payment recovery
|
||||
|
||||
### Growth Engineering
|
||||
- `free-tool-strategy` - Marketing tools and calculators
|
||||
- `referral-program` - Referral and affiliate programs
|
||||
- `co-marketing` - Partner identification and joint campaigns
|
||||
- `free-tools` - Marketing tools and calculators
|
||||
- `referrals` - Referral and affiliate programs
|
||||
|
||||
### Strategy & Monetization
|
||||
- `marketing-ideas` - 140 SaaS marketing ideas
|
||||
- `marketing-psychology` - Mental models and psychology
|
||||
- `launch-strategy` - Product launches and announcements
|
||||
- `pricing-strategy` - Pricing, packaging, and monetization
|
||||
- `launch` - Product launches and announcements
|
||||
- `pricing` - Pricing, packaging, and monetization
|
||||
|
||||
### Sales & RevOps
|
||||
- `revops` - Lead lifecycle, scoring, routing, pipeline management
|
||||
- `sales-enablement` - Sales decks, one-pagers, objection docs, demo scripts
|
||||
|
||||
## Contributing
|
||||
|
||||
@@ -200,3 +317,9 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on adding or improving ski
|
||||
## License
|
||||
|
||||
[MIT](LICENSE) - Use these however you want.
|
||||
|
||||
<br />
|
||||
<br />
|
||||
<a href="https://vercel.com/open-source-program">
|
||||
<img alt="Vercel OSS Program" src="https://vercel.com/oss/program-badge-2026.svg" />
|
||||
</a>
|
||||
|
||||
+222
-29
@@ -4,38 +4,231 @@ Current versions of all skills. Agents can compare against local versions to che
|
||||
|
||||
| Skill | Version | Last Updated |
|
||||
|-------|---------|--------------|
|
||||
| ab-test-setup | 1.0.0 | 2026-01-27 |
|
||||
| ad-creative | 1.0.0 | 2026-02-17 |
|
||||
| ai-seo | 1.0.0 | 2026-02-18 |
|
||||
| analytics-tracking | 1.0.0 | 2026-01-27 |
|
||||
| churn-prevention | 1.0.0 | 2026-02-18 |
|
||||
| cold-email | 1.0.0 | 2026-02-14 |
|
||||
| competitor-alternatives | 1.0.0 | 2026-01-27 |
|
||||
| content-strategy | 1.0.0 | 2026-01-27 |
|
||||
| copy-editing | 1.0.0 | 2026-01-27 |
|
||||
| copywriting | 1.0.0 | 2026-01-27 |
|
||||
| email-sequence | 1.0.0 | 2026-01-27 |
|
||||
| form-cro | 1.0.0 | 2026-01-27 |
|
||||
| free-tool-strategy | 1.0.0 | 2026-01-27 |
|
||||
| launch-strategy | 1.0.0 | 2026-01-27 |
|
||||
| marketing-ideas | 1.0.0 | 2026-01-27 |
|
||||
| marketing-psychology | 1.0.0 | 2026-01-27 |
|
||||
| onboarding-cro | 1.0.0 | 2026-01-27 |
|
||||
| page-cro | 1.0.0 | 2026-01-27 |
|
||||
| paid-ads | 1.0.0 | 2026-01-27 |
|
||||
| paywall-upgrade-cro | 1.0.0 | 2026-01-27 |
|
||||
| popup-cro | 1.0.0 | 2026-01-27 |
|
||||
| pricing-strategy | 1.0.0 | 2026-01-27 |
|
||||
| product-marketing-context | 1.0.0 | 2026-01-27 |
|
||||
| programmatic-seo | 1.0.0 | 2026-01-27 |
|
||||
| referral-program | 1.0.0 | 2026-01-27 |
|
||||
| schema-markup | 1.0.0 | 2026-01-27 |
|
||||
| seo-audit | 1.0.0 | 2026-01-27 |
|
||||
| signup-flow-cro | 1.0.0 | 2026-01-27 |
|
||||
| social-content | 1.0.0 | 2026-01-27 |
|
||||
| ab-testing | 2.0.0 | 2026-05-05 |
|
||||
| ad-creative | 2.5.0 | 2026-07-09 |
|
||||
| ai-seo | 2.1.0 | 2026-06-15 |
|
||||
| analytics | 2.0.0 | 2026-05-05 |
|
||||
| aso | 2.0.0 | 2026-05-05 |
|
||||
| churn-prevention | 2.0.0 | 2026-05-05 |
|
||||
| co-marketing | 2.0.0 | 2026-05-05 |
|
||||
| cold-email | 2.0.0 | 2026-05-05 |
|
||||
| community-marketing | 2.0.0 | 2026-05-05 |
|
||||
| competitor-profiling | 2.0.0 | 2026-05-05 |
|
||||
| competitors | 2.0.0 | 2026-05-05 |
|
||||
| content-strategy | 2.0.0 | 2026-05-05 |
|
||||
| copy-editing | 2.0.0 | 2026-05-05 |
|
||||
| copywriting | 2.0.1 | 2026-06-16 |
|
||||
| cro | 2.0.0 | 2026-05-05 |
|
||||
| customer-research | 2.0.0 | 2026-05-05 |
|
||||
| directory-submissions | 2.0.0 | 2026-05-05 |
|
||||
| emails | 2.0.0 | 2026-05-05 |
|
||||
| free-tools | 2.0.0 | 2026-05-05 |
|
||||
| image | 2.0.1 | 2026-05-18 |
|
||||
| launch | 2.0.1 | 2026-06-16 |
|
||||
| lead-magnets | 2.0.0 | 2026-05-05 |
|
||||
| marketing-council | 1.0.0 | 2026-07-06 |
|
||||
| marketing-ideas | 2.0.0 | 2026-05-05 |
|
||||
| marketing-loops | 1.1.0 | 2026-07-05 |
|
||||
| marketing-plan | 1.1.0 | 2026-05-29 |
|
||||
| marketing-psychology | 2.0.0 | 2026-05-05 |
|
||||
| offers | 1.0.0 | 2026-06-16 |
|
||||
| onboarding | 2.0.0 | 2026-05-05 |
|
||||
| ads | 2.2.0 | 2026-07-05 |
|
||||
| paywalls | 2.0.0 | 2026-05-05 |
|
||||
| popups | 2.0.0 | 2026-05-05 |
|
||||
| pricing | 2.0.1 | 2026-06-16 |
|
||||
| product-marketing | 2.0.0 | 2026-05-05 |
|
||||
| programmatic-seo | 2.0.0 | 2026-05-05 |
|
||||
| prospecting | 1.0.0 | 2026-05-26 |
|
||||
| public-relations | 1.0.0 | 2026-06-10 |
|
||||
| referrals | 2.0.0 | 2026-05-05 |
|
||||
| revops | 2.0.0 | 2026-05-05 |
|
||||
| sales-enablement | 2.0.1 | 2026-06-16 |
|
||||
| schema | 2.0.0 | 2026-05-05 |
|
||||
| seo-audit | 2.0.0 | 2026-05-05 |
|
||||
| signup | 2.0.0 | 2026-05-05 |
|
||||
| site-architecture | 2.0.0 | 2026-05-05 |
|
||||
| sms | 1.0.0 | 2026-05-21 |
|
||||
| social | 2.2.0 | 2026-07-09 |
|
||||
| video | 2.0.1 | 2026-05-18 |
|
||||
|
||||
## Recent Changes
|
||||
|
||||
### 2.8.5 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.4.0 → 2.5.0): extended the iMessage reveal reference into **iOS-native reveal video ads** — `references/imessage-video-ads.md` (filename unchanged; retitled) now covers three surfaces sharing one production architecture. New **Other iOS-Native Reveal Surfaces** section: a surface-selection table keyed to persuasion mechanic (iMessage = a friend's recommendation; ChatGPT = an authoritative answer to the viewer's own question; Apple Notes = a private confession made public), **ChatGPT reveals** (the typed question is the customer's verbatim question; stream the answer in word chunks — type like thumbs, stream like a model; ChatGPT-real formatting; OpenAI trade-dress legal note; and the strictest compliance rule in the family — the answer is ad copy wearing an authority costume, so health/medical/financial advice in a fabricated AI answer requires legal review and the exchange is never presented as a real unprompted ChatGPT endorsement), and **Apple Notes reveals** (confession-not-conversation: note title as the hook, first-person list typed live with keyboard-taps-only audio, one typo-and-correction, the product as the least enthusiastic line, realizations grounded in real reviews per Grounded Inputs). SKILL.md pointer updated to the three-surface framing and adds 'ChatGPT ad' and 'Apple Notes ad' triggers. New eval (id 8) covers the health-claims compliance flag, surface selection, and Notes craft rules. Format source credit unchanged (Gooseworks iOS Ads pack). Closes #424.
|
||||
|
||||
### 2.8.4 (2026-07-09)
|
||||
|
||||
- **social** (2.1.0 → 2.2.0): added a **carousel framework library**. New `references/carousel-frameworks.md` — five slide-by-slide narrative architectures for Instagram carousels and LinkedIn document posts, re-expressed and extended from a pattern circulating on marketing X (Vibe Marketers HQ's five-framework breakdown): **Value-Stack** (exact-count cover → one item per slide → action close; the count is a checkable promise), **Problem-Proof** (result-as-fact hook → reframed problem → named mechanism → literal detail → screenshot receipt that closes slide 1's loop), **Hack List** (contrarian stat hook → why the common approach fails → one *named* technique per slide → thesis + CTA), **Rant Callout** (provocative claim → specific escalation → the fairness pivot that keeps it conviction-not-bitterness → signed close), and **Demo Walkthrough** (outcome first → pain → numbered process overview *before* the detail to cut mid-swipe drop-off → one real screenshot per step → result + positioning). Includes a framework-selection table (match structure to content type), two cross-framework rules (slide 1 is the thumbnail; one visual template per carousel), per-framework SaaS examples and failure modes, platform notes (IG 4:5 specs, LinkedIn PDF document posts with the post text as a second hook, TikTok photo-mode pacing), a production checklist (real claims only, exact counts delivered, one CTA), and measurement guidance (judge on saves + completion, not likes). SKILL.md wires the reference next to post templates and adds 'carousel,' 'slide-by-slide,' and 'document post' triggers; post-templates.md's generic Carousel Hook now points to the full library. New eval (id 7) covers framework selection, named-technique slides, LinkedIn document-post guidance, and no-invented-stats. Closes #421.
|
||||
|
||||
### 2.8.3 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.3.0 → 2.4.0): added a **brand-flexible style tier** to `references/motion-video-ads.md` — four token-driven styles that absorb any company's brand system instead of imposing their own palette: **monoline editorial** (thin single-weight ink line-art on the brand neutral, one accent sweep — the most universally brandable), **Swiss typographic** (the label set enormous in the brand's type on a grid; works for any brand with a font and a color), **wireglow** (wireframe subject on near-black with one gradient accent beam — dev-tool/dark-mode brands), and **duotone screenprint** (photography reduced to ink + accent). All driven by a **brand slots contract** — FIELD (neutral ground), INK (drawing/type color), ACCENT (one element per frame, scarcity is the design), TYPE FEEL, plus per-brand constraints (e.g. "gradients only on edges") — resolvable from brand guidelines or `.agents/product-marketing.md`. Includes per-style motion notes (lines draw themselves, beams pulse, type settles) under the same composition-never-changes rules. All four verified to render with clean typography using a real brand's tokens.
|
||||
|
||||
### 2.8.2 (2026-07-09)
|
||||
|
||||
- **ad-creative** (2.2.0 → 2.3.0): added the **faceless motion-style video ad format**. New `references/motion-video-ads.md` (format popularized by @borjafat; original re-expression of the open Bomx `super-video-maker` motion-collage recipe, extended with production lessons from shipping it end-to-end): a fully generated 15–45s concept/explainer video — styled poster stills (one per beat, series-locked via reference images) → image-to-video "living" motion → TTS narration → whisper-word-timed captions — at roughly $3–6 and ~15 minutes per finished video. Covers the provider-agnostic pipeline with a one-key Gemini path (Nano Banana Pro + Veo 3.1 + Gemini TTS) and alternatives (GPT-Image/Flux, Seedance/Kling/Runway, ElevenLabs), a **five-style visual library** with fill-in prompt formulas (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation), a motion prompt formula, hard-earned QC gotchas (image-to-video models inject photoreal "maker hands" — and negative prompts make it worse; always QC each clip's final 2 seconds; caption/label collision; TTS/whisper sound-alike words in CTAs), ad-specific rules (brand in the poster for sound-off autoplay, beat 1 is the 3-second hook, regenerate stills per aspect rather than cropping), and AI-content disclosure notes. SKILL.md wires the reference into Generating Ad Visuals and adds 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' and 'motion collage ad' description triggers.
|
||||
|
||||
### 2.8.1 (2026-07-08)
|
||||
|
||||
- **ad-creative** (2.1.0 → 2.2.0): added the **iMessage chat-reveal video ad format**. New `references/imessage-video-ads.md` — an original distillation of the format popularized by Shiv Sakhuja / Gooseworks (their public `create-imessage-video-ad` skill; the repo carries no open-source license, so content was re-expressed with credit rather than copied): a 9:16 video where a scripted iMessage thread unfolds bubble-by-bubble — screenshot hook → friend reacts → "what app is that?" → brand + promo-code reveal → static end card. Covers when to use it and when not (considered B2B, nothing screenshot-able, regulated-industry compliance), a compliance/grounding section tying dramatized conversations to the skill's Grounded Inputs rules (facts in the thread must be real; never frame the thread as a real testimonial), the six concept angles (result-as-screenshot, setup flex, cancellation moment, feature-as-punchline, friend-asks-friend inverse, receipt-as-hook), ad anatomy with script + pacing rules (8–14 bubbles, texting voice, brand appears once and late, rhythm not metronome, link-underlined promo code), three production routes (off-the-shelf Gooseworks skill; code-based HTML mockup + one continuous Playwright recording + ffmpeg stitch; Remotion for templated scale), the craft rules that sell the illusion (the recognizable send/receive SFX — CC0 recordings on BigSoundBank, with a trade-dress legal-review note; silent typing indicators; composer-typed text must equal sent text; static end card with the real logo SVG; native 1080×1920 recording; HTML-mimic real app UIs for hook screenshots instead of AI-generating them), a ship checklist, and an iteration order (hook attachment first). SKILL.md wires the reference into Generating Ad Visuals and adds 'iMessage ad,' 'chat reveal ad,' 'text message ad,' and 'fake DM ad' description triggers. Closes #411.
|
||||
|
||||
### 2.8.0 (2026-07-06)
|
||||
|
||||
- Added `marketing-council` skill — a simulated board of advisors staffed by twelve legendary marketers, built so their lenses deliberately collide: Seth Godin, David Ogilvy, Eugene Schwartz, Claude Hopkins, Gary Halbert, Russell Brunson, Alex Hormozi, April Dunford, Rory Sutherland, Byron Sharp, Ann Handley, and Gary Vaynerchuk. Three session modes (quick take / 3-5 seat council session / full council), a seating table mapping question types to strong fits plus **designated dissenters** (an agreeing council is an anti-pattern — e.g., Sharp dissents on niche strategies, Godin on funnel pressure, Hopkins on unmeasurable brand plays), and a session protocol ending in a **disagreement map** (each conflict named as its underlying trade-off plus the evidence that would settle it) and a chair's synthesis with skill handoffs. Per-advisor dossiers in `references/advisors/` were research-grounded via parallel web-research passes: each carries lens, frameworks with verified attributions (incl. misattribution flags — Dream 100 is Chet Holmes's, "salesmanship in print" is John E. Kennedy's coinage, brand image originated with Gardner & Levy, AIDA predates Halbert), documented positions with named sources, signature questions, best-for/blind-spots (with documented criticisms so dissent is honest), voice notes, and key works. Hard grounding rules: output labeled as simulation; no fabricated quotes (verifiable quotes with source, else paraphrase attributed to the work); no implied endorsements of the user's specific company; extra care for the eight living advisors including explicit do-not-fabricate flags (e.g., Hormozi launch figures are self-reported; recency questions about living advisors route to the research pass). Optional live research pass integrates deep-research / watch-video / last30days-style skills when installed, degrading to web search. `references/advisor-template.md` supports custom advisors saved to `.agents/advisors/` with a two-tier grounding standard (public figures need sources; private advisors' positions must come from the user, never invented). Includes an `evals/evals.json` suite covering dissent enforcement, quote discipline, custom-advisor flow, and the do-not-fabricate rule. Closes #391. Total skills: 47.
|
||||
|
||||
### 2.7.0 (2026-07-05)
|
||||
|
||||
- **ad-creative** (2.0.0 → 2.1.0): added scaled static ad production with grounded inputs. New `references/static-ad-templates.md` — a 15-template structural library for static ads (Headline Statement, Us vs. Them, Stat Callout, Review Card, Testimonial Stack, Before/After, Problem/Solution, Founder Message, Feature Spotlight, Press Mention, Lifestyle Hero, Numbered List, FAQ Card, Competitor Callout, Origin Story), each with structure, copy slot, DTC + SaaS examples, sourcing guidance, and compliance notes where relevant (before/after claims, press logos, comparative advertising). SKILL.md adds **Mode 3: Scaled Static Batches (Grounded)** and a **Grounded Inputs** section: a durable inputs corpus (`inputs/winning-ads/`, `inputs/reviews/`, `inputs/comments/`, plus `brand/`), hard grounding rules (every concept cites its source — a real review, winning ad, or ad comment; no invented claims or testimonials; refuse to generate when required inputs are empty rather than falling back to ungrounded output), and input-decay guidance. Ad comments called out as the most-skipped, highest-value input (public objections → FAQ Card ads; unprompted praise → customer-written angles). New static batch output format: `outputs/YYYY-MM-DD/` with scannable `INDEX.md` (template + grounding per concept), per-concept files, and images — built for the pick-5-of-50 human review workflow. Two new Common Mistakes (generating without grounding, skipping the comments input) and cross-refs to `marketing-loops` and `customer-research`. Frontmatter description adds 'static ads,' 'static ad concepts,' and 'ad templates' triggers. Remixed from a DTC "morning ads" playbook pattern, adapted for cross-agent use and extended with B2B/SaaS examples.
|
||||
- **marketing-loops** (1.0.0 → 1.1.0): added **the daily-creative-drop loop** to the Paid section of `references/loop-catalog.md` (loop #44) — a daily batch of grounded static ad concepts via `ad-creative` Mode 3. Full nine-part anatomy: acts only when the grounded inputs corpus is populated (else asks for inputs instead of generating), one-batch-per-day idempotency via dated output folders plus near-duplicate tracking across recent batches, stages creative only (never publishes to the ad account), pauses itself if batches go unreviewed for a week (vanity-loop detection), and a companion input-freshness cadence (weekly `inputs/winning-ads/` refresh; monthly `inputs/reviews/` and `inputs/comments/` refresh).
|
||||
- **ads** (2.1.0 → 2.2.0): major B2B operations expansion — five new references plus a routing-table pattern, adapted (re-expressed, reconciled, and extended with our own framing) from practitioner playbooks, notably Ivan Falco's ads-skills (ColdIQ; MIT + Commons Clause, so all content was rewritten rather than copied). New **Reference Routing** table at the top of SKILL.md maps user intent → reference file, with a hard rule that live-account operational decisions load the relevant playbook first. New references: **b2b-paid-playbook.md** (5-stage demand lifecycle past the funnel — Create/Capture/Accelerate-Activate/Revive/Expand with bottom-up build order; budget-by-stage matrix with ROI timelines; leading vs. lagging signals for 2-24-month sales cycles; breakeven CPL/CPC derivation; hard kill rules — 2-3× target CPL at zero conversions for new ads, 1.5-2× over target for aging ads; the optimize-to-quality trap + offline conversion loop with "the CRM wins" reconciliation; Urgency/Budget/Fit 0-9 lead scoring ranked by ad; the scaling quadrant 2×2; measurement maturity gate; channel selection incl. paid-review listings and the $100 test). **meta-decision-system.md** (fully quantified kill/graduate/scale engine anchored on TCPL — target cost per *qualified* lead: ad-count ceiling formula, 80/20 Scaling/Testing dual-CBO structure, day-7 delivery check with fair-share math, weekly quality evaluation with a 3×TCPL data gate and QL-rate bands, five-condition graduation criteria, fatigue frequency bands by campaign type, swap rules, creative production math with win rates and minimum proven-ad inventory, +20%-per-5-days scaling protocol with rollback triggers, weekly cadence, lead-form friction / social-amnesia fixes, Advantage+ transition at ~50 conversions/week, benchmarks + Q1/Q4 seasonality). **linkedin-b2b-playbook.md** (auto-then-manual-at-−20% bidding progression, penetration-based scaling triggers, audience sizing rules and failure modes, job-functions-vs-titles tradeoffs incl. the seniority mutual-exclusivity and Business-Development-contains-C-suite gotchas, audience splitting rules and platform distribution bias, funnel-stage benchmarks with the CTRTLP-vs-CTR trap, thought-leader-ads playbook incl. the 72-hour organic-first edit trick and format-as-auction-tactic insight, campaign-group build order, document/conversation/CTV format notes, the non-retroactive retargeting warning, and an audit shortlist). **google-search-playbook.md** (the five-rung intent ladder with don't-skip-rungs gating, brand pause test on total-not-paid conversions, capture-before-create channel rule, separate-budgets-by-intent account structure with themed-ad-groups-not-SKAGs and default settings to flip, Phrase/Exact→Broad progression with 30-conversion gates, starter negative lists + negative match-type mechanics gotcha, the weekly search-terms ritual with don't-over-negative restraint, bidding-by-conversion-volume table with ±10-15% target moves, the 2× daily budget rule, offline conversion import via GCLID, QS fix-order and form-length-as-intent-gate, PMax-for-B2B guardrails and value ranking, benchmarks + the 8-metric weekly scorecard). **abm-playbook.md** (go/no-go thresholds, LinkedIn ABM 1:1/1:few/1:many with list-size mechanics and segmentation against enterprise over-serving, personalized-creative lift + the Germany legal exception, engagement-based frequency capping, ABM-on-Meta enrichment workflow for the sub-5% match-rate problem, acceleration campaigns against open pipeline on awareness objectives, 60/30/10 cross-channel split, the UTM cross-channel remarketing mechanic, sales orchestration with 48-hour engagement triggers, and account-movement KPIs + 80/20 incrementality holdouts). Also: the mandatory **Google RSA Output Spec** moved verbatim from SKILL.md to `references/rsa-output-spec.md` (SKILL.md keeps a mandatory load-and-follow pointer), bringing SKILL.md from 552 back under the 500-line limit. New description triggers: 'ABM,' 'account-based marketing,' 'B2B ads,' 'lead quality,' 'negative keywords,' 'Performance Max,' 'thought leader ads,' 'when should I kill an ad.' New Related Skills cross-refs to `revops` and `customer-research`.
|
||||
|
||||
### 2.6.0 (2026-07-01)
|
||||
|
||||
- Added `marketing-loops` skill — a library of 43 repeatable marketing loops (recurring agent workflows an agent runs on a cadence). Inspired by ForwardFuture's Loop Library pattern but scoped to marketing operations, and positioned as the operational cousin of `marketing-ideas` (ideas = what to try once; loops = what to keep doing on a schedule). SKILL.md defines a nine-part loop anatomy — check cadence, acts-when (action condition), purpose, skills used, loop body, self-check, **state/idempotency** (last-run marker, dedupe key, cooldown — so loops don't double-act or re-nag), stop/bail-out, and output — plus a cadence rule (match frequency to how fast the signal actually changes), when NOT to loop (strategy/creative work, unreviewed spend/publish, sparse signals, vanity loops), and scheduling guidance that defers the mechanics to `loopify` (Claude Code `/loop` / `ScheduleWakeup` / `CronCreate`) or plain cron. `references/loop-catalog.md` holds all 43 loops grouped by function: SEO & Content (keyword-gap, ranking-drop watch, content-decay, internal-linking, programmatic-SEO quality, content-repurposing, content-calendar refill), Paid (ad-fatigue, paid-search query-mining, retargeting hygiene, landing-page regression), Earned/Social/Partnerships (newsjacking, social-listening, community-engagement, competitor-watch, backlink-prospecting, directory-submission, partner-pipeline), Activation (onboarding drop-off, signup-funnel-leak, lead-capture asset, feature-adoption), Retention (churn-signal, lifecycle-email-refresh, re-engagement, email-deliverability, voice-of-customer), Revenue (trial-conversion, PQL/upgrade-intent, pricing-page-experiment, paywall-optimization, expansion/upsell, failed-payment/dunning), Referral & Advocacy (referral-nudge, review-and-UGC-harvest, review-site-management, case-study-sourcing), and Ongoing Ops (weekly-marketing-review, experiment-backlog, analytics-anomaly, brand-mention/reputation, tracking-QA, campaign-postmortem). Each entry orchestrates existing skills and carries concrete guardrails — e.g. newsjacking has a veto list (tragedy/politics/crisis/sensitive verticals) + mandatory human approval; ad-fatigue requires real significance (spend/impressions/conversions/attribution/learning-phase); lifecycle-email optimizes on clicks/replies/complaints/bounces not opens; pricing/paywall judge winners on revenue-per-visitor/refunds/churn not conversion alone; review-harvest enforces consent/FTC/platform ToS; the experiment-backlog loop is a thin wrapper that hands off to `ab-testing`. `references/loop-template.md` gives authors a copy-paste template (fill-in prompts + worked before/after example + ship checklist) for creating their own loops. Three further references round out the skill: `loop-orchestration.md` (how loops compose into a four-layer system — sensing → diagnostic → action → learning — plus a staged rollout path so you adopt tracking + a weekly review before acquisition, and never build all 43 at once), `loop-state.md` (where loop state lives — `.agents/loops/<loop>.json` — the watermark/dedupe/cooldown/in-flight idempotency patterns, and a run-log format that doubles as a vanity-loop detector), and `loop-guardrails.md` (a two-tier action model of autonomous-safe vs. gated actions, spend/send caps + allowlists, CAN-SPAM/GDPR/FTC/platform-ToS compliance mapped to the loops each governs, PII handling, an always-escalate list, a required kill switch, and a pre-launch checklist). Includes a banned-vocabulary list (no "set it and forget it" / "fully autonomous marketing" / "10x on autopilot") and an `evals/evals.json` suite. Total skills: 46.
|
||||
- **ads** (2.0.1 → 2.1.0): reframed the skill around the "audience knowledge → creative first, targeting filters second" shift, plus a new modern Meta playbook. Rewrote the **Audience Understanding & Targeting** section — audience research is still the highest-leverage work, but where you apply that knowledge has changed: as ad-platform algorithms have improved at matching, feeding audience identifiers into the *creative* (headlines, copy, hooks, examples) now outperforms jamming them into *targeting filters*. Added a platform-by-platform table splitting how much audience knowledge should go to creative vs. targeting (Meta post-Andromeda 80%+ creative; Google Search 60% targeting; PMax/Demand Gen 70% creative; LinkedIn 60% targeting; TikTok 70% creative; Twitter/X 50/50), guidance on applying each kind of audience identifier to creative, and a "trying to fix weak creative with hyper-precise targeting" failure-mode callout. Added a **Modern Meta playbook (Andromeda era — 2026+)** section covering Meta's 2025 Andromeda algorithm change: creative volume as the binding constraint (statics > polished video, ~1 hr/week of fresh creative for the winning offer), creative-as-targeting (broad audience + specific creative, with a duplicate-and-strip-targeting A/B test), and the 4-component retargeting framework (segment by funnel stage, retarget with different offers). Interest-stacking is now flagged as actively harmful on Meta. Skill body only; frontmatter description unchanged.
|
||||
|
||||
### 2.5.1 (2026-06-16)
|
||||
|
||||
- Bumped `copywriting`, `launch`, `pricing`, and `sales-enablement` from 2.0.0 → 2.0.1 to reflect the description changes that shipped in v2.5.0 (cross-references added pointing to the new `offers` skill). The skill bodies are unchanged; only the frontmatter description picked up a new "For ..., see offers" line. Without the version bump, the repo's update check (which compares VERSIONS.md against local skill metadata) would not surface the routing/discovery change to users with installed copies. Caught by codex review.
|
||||
|
||||
### 2.5.0 (2026-06-16)
|
||||
|
||||
- Added `offers` skill for offer design — the thing you actually sell, not the page that sells it. Built around two frameworks: (1) the Value Equation (Dream Outcome × Perceived Likelihood / Time Delay × Effort), originally Hormozi, now standard across direct-response and creator-economy training; and (2) the six-component anatomy of a complete offer (core deliverable, bonus stack, guarantee, scarcity, name, price + payment structure). Self-scoped explicitly: best for services, agency retainers, courses, coaching, info products, high-ticket B2B, and direct response. Less load-bearing for pure self-serve SaaS where `pricing` does more work. References include: `value-equation.md` (full breakdown of the four levers with diagnostic prompts and a worked example of a stuck $3K copywriting course), `offer-anatomy.md` (the six components with worked examples and a fractional-CMO before/after), `guarantee-design.md` (eight guarantee types with decision tree by business type, refund tolerance, and buyer sophistication; honest case for anti-guarantees on premium offers), `bonus-stacking.md` (bonuses-as-objection-handlers, the math of stated value, the 4-bonus pattern that works, common failure modes), `scarcity-urgency.md` (honest formats: capacity / cohort / founding-member / inventory / seasonal / bonus-expiry / price-increase; explicit rejection of fake countdown timers and manufactured FOMO; why fake scarcity is uniquely costly), `offer-formats.md` (default offer format by business type — service, course, coaching, info product, high-ticket B2B, agency retainer, self-serve SaaS, direct-response — with what to watch for each), and `examples.md` (six anonymized before/after worked examples spanning fractional CMO, copywriting course, Notion templates, B2B SaaS annual contract, group coaching mastermind, content agency retainer). Includes a banned-vocabulary list (game-changing, revolutionary, 10x, secret, hidden, "limited time" with no actual limit) and explicit anti-patterns (manipulative scarcity, over-promising guarantees, bonus inflation, course-bro aesthetic).
|
||||
- Cross-references added in `pricing`, `copywriting`, `launch`, and `sales-enablement` descriptions pointing to `offers` for offer construction.
|
||||
- Total skills: 45.
|
||||
|
||||
### 2.4.2 (2026-06-15)
|
||||
|
||||
- **ai-seo** (2.0.1 → 2.1.0): added coverage of Google's Open Knowledge Format (OKF), a v0.1 markdown spec for agent-readable site bundles introduced on the Google Cloud blog on 2026-06-12 and shipped inside Knowledge Catalog. New `references/okf.md` reference covers what OKF is (directory of cross-linked markdown files with YAML frontmatter — `type` required, plus `title`/`description`/`resource`/`tags`/`timestamp` recommended), honest framing (Google built it for data-team catalog metadata; site-readable repurposing popularized by Suganthan Mohanadasan is a clever secondary use), what it does for AI search today (nothing immediate; protocol-layer registration like early schema.org adoption), where OKF fits in the agent-readable stack alongside `sitemap.xml` / `robots.txt` / `llms.txt` / `/pricing.md` / schema, three ways to ship a bundle (Suganthan's free web generator, his pending WordPress plugin, or by hand), hosting guidance (`yoursite.com/okf/index.md` plus an `llms.txt` line pointing to it), when to skip (closed platforms like Wix/Squarespace, very small sites, sites without other machine-readable files), and what to watch (v1.0 spec, AI engine adoption signals). `SKILL.md` adds a brief OKF subsection under "Machine-Readable Files for AI Agents" pointing to the reference. Frontmatter description extended with new triggers: `llms.txt`, `OKF`, `Open Knowledge Format`, `knowledge bundle`, `agent-readable site`. `references/platform-ranking-factors.md` Google AI Overviews section gets an OKF callout framing it as a "register early" protocol bet rather than a confirmed ranking signal.
|
||||
|
||||
### 2.4.1 (2026-06-10)
|
||||
|
||||
- Renamed `pr` skill to `public-relations` to avoid collision with pull-request skills in other Claude Code plugins (common naming for code-review / GitHub PR automation). The skill description already disambiguated from pull requests, but the directory name `pr` was still ambiguous to skill resolvers and to users typing `/pr`. The rename happened within hours of the initial v2.4.0 publish, before meaningful install adoption. No content changes; skill version stays at 1.0.0. All cross-references in `social/SKILL.md`, `VERSIONS.md`, and `README.md` updated accordingly.
|
||||
|
||||
### 2.4.0 (2026-06-10)
|
||||
|
||||
- Added `public-relations` skill (originally shipped as `pr`, renamed in v2.4.1) for public relations / earned media work — pitching journalists, newsjacking trending stories, responding to press requests (HARO/Connectively, Qwoted, Featured, Help A B2B Writer), and building the owned-media foundation (press page + media kit). Four PR modes (reactive / proactive / inbound / owned), explicit when-to-skip framing, and a banned-vocabulary list. References include: `newsjacking.md` (detect → score → angle → pitch loop with newsworthiness scoring rubric, 7 angle templates, Google News / HN / Reddit curl recipes, failure modes); `journalist-pitching.md` (media list construction, journalist fit scoring, 6 pitch templates by angle — data story / exclusive launch / op-ed / customer story / trend connector / newsjack response — subject-line craft, embargo etiquette, follow-up cadence); `press-platforms.md` (daily triage workflow, response template, ROI reality check); `media-outlets.md` (tiered list of tech press, SaaS, AI, devtools, business outlets, newsletters, podcasts, vertical press, regional press — explicitly scoped to journalist-driven outlets, with startup directories deferred to `directory-submissions`). Scope is enforced via cross-references: the `public-relations` skill handles earned media; `directory-submissions` handles Product Hunt / BetaList / SaaS directories; `launch` handles the broader launch moment.
|
||||
- **social** (2.0.0 → 2.1.0): added `references/listening.md` for engagement triage — a daily loop for surfacing the top posts to comment on rather than scrolling feeds. Includes a 5-dimension scoring rubric (ICP fit, intent signal, reach potential, comment opportunity, recency), comment quality tiers, curl-based recipes for Reddit / HN Algolia / Bluesky (no auth required), and a browser-driven workflow for LinkedIn and X via `dev-browser` with persistent session. Added `references/listening-sources-template.md` — a copyable starter for `.agents/listening-sources.md` covering brand/category context, ICP definition, target accounts per platform, intent keywords, subreddits, saved-search URLs, and a do-not-engage list. SKILL.md Engagement Strategy section now links to the listening reference.
|
||||
- Total skills: 44.
|
||||
|
||||
### 2.3.0 (2026-05-27)
|
||||
|
||||
- Added `marketing-plan` skill — comprehensive AARRR-structured marketing plan generator. Produces a 13-section Notion-paste-ready plan document (executive summary, strategic frame, current state, AARRR breakdown, 90-day roadmap, 12-month outlook with funding-stage capability unlocks, marketing operations stack mapping skills + MCPs to AARRR stages, tactical idea bank cross-referencing all 139 `marketing-ideas` to AARRR + client-specific status, measurement framework, RACI, open decisions). Customized for current budget, team, stage, and tooling stack. Three-phase workflow: INIT (research + intake), REVIEW (section-by-section walkthrough), FINALIZE (compile + verify + optional publish to shared repo). References include methodology, plan-template, aarrr-framework, current-state-rubric (self-contained 17-section scoring rubric), ops-stack-mapping, idea-cross-reference (139-idea AARRR mapping), funding-stage-unlocks, measurement-framework, client-types (variations by B2B SaaS / D2C / hardware-hybrid / marketplace / dev tool / clinical / commerce), example-quietude (anonymized canonical reference plan, based on a real fCMO engagement with names/identifying details changed), budget-planning (two scientific methods for setting the marketing budget — Revenue-Based 5–40% of ARR, and Goal-Based formula reverse-engineered from the revenue target; plus blended CAC calculation, the 10–20% experimental buffer rule, the 3-3-2-2-2 VC growth path, and the forecasting reality check), growth-patterns (the real shape of SaaS growth — $0–10K / $10K–100K / $100K–1M phases with binding constraints, linear vs step-function vs S-curve patterns, and Channel × Product × Market layering), and team-and-agency-model (the strategy-in-house / execution-outsourced principle, three core functions Growth/Product/Content, π-shaped marketer framework, title progression Manager → Lead → Director → VP → Chief, agency selection framework, and the three-stage scaling model Early/Growth/Scale). Budget, growth-pattern, and team frameworks drawn from *Founding Marketing* by Corey Haines.
|
||||
- Total skills: 43.
|
||||
|
||||
### 2.2.0 (2026-05-26)
|
||||
|
||||
- Added `prospecting` skill for building qualified prospect lists across SaaS, B2B, and local SMB motions. Includes shared 5-phase framework (ICP → discovery → qualify → score → output) plus branch-specific references (saas-prospecting, b2b-prospecting, local-prospecting), data-sources guide covering Apollo / Clay / ZoomInfo / Clearbit / Hunter / Snov / Truelist / RB2B / Sales Nav / BuiltWith / Crunchbase / GitHub, and compliance reference (CAN-SPAM, GDPR, CASL, platform ToS).
|
||||
- Added `tools/clis/github-prospects.js` CLI for pulling GitHub stargazers, forkers, and watchers as a developer-intent signal — with pagination, enrichment, filter-based early termination, and CSV output.
|
||||
- Added new tool integration docs: `truelist` (email deliverability validation, OpenAPI-aligned), `github` (REST API for prospecting), `firecrawl` (single-target page scraping), `browserbase` (real Chromium for JS-heavy pages or interaction).
|
||||
- **ads** (2.0.0 → 2.0.1): added Google RSA Output Spec section enforcing 15 headlines × 30 chars, 4 descriptions × 90 chars, ad group structure labels, ≥8 negative keywords, ≥4 sitelinks/callouts, output ordering to avoid truncation, and a self-check before responding. Includes optional Brazilian medical (CFM) compliance rules when product context indicates that vertical.
|
||||
- Added `sequenzy` tool integration (email marketing platform with MCP support).
|
||||
- Fixed plugin.json version drift (was stuck at 1.9.0 across three releases) — `sync-skills.js` now auto-syncs `plugin.json` version to `marketplace.json` on every change. Closes #323.
|
||||
- Added skill install artifacts (`.agents/`, `.claude/`, `skills-lock.json`) to `.gitignore`.
|
||||
- Total skills: 42.
|
||||
|
||||
### 2.1.0 (2026-05-21)
|
||||
- Added `sms` skill for SMS/MMS marketing — welcome flows, abandoned cart, post-purchase, win-back, promotional sends, and transactional/auth. Includes compliance reference (TCPA, A2P 10DLC, GDPR, CASL), sequence templates with character counts, and platform comparison (Klaviyo, Postscript, Attentive, Twilio, Brevo, SimpleTexting, Customer.io).
|
||||
- Total skills: 41
|
||||
|
||||
### 2.0.1 (2026-05-18)
|
||||
|
||||
Content patch — no breaking changes, no new skills.
|
||||
|
||||
- **ai-seo** (2.0.0 → 2.0.1): aligned with Google's official AI features optimization guide. Added sections for Google's stance on AI optimization, query fan-out, agentic experiences (including UCP), explicit "what NOT to do" (scaled content abuse, etc.), and Search Console expectations. Reframed llms.txt / pricing.md / schema markup recommendations as "Google says not required, helpful for non-Google AI engines." Moved content-type tactics to `references/content-types.md` (added local/ecom Merchant Center + Business Profile guidance per Google).
|
||||
- **image** (2.0.0 → 2.0.1): refreshed model lineup to current May 2026 releases — Nano Banana / Nano Banana Pro family naming, Flux Pro 1.1 + Kontext + Dev + Schnell variants, Ideogram 3.0, ChatGPT Images 2.0 / GPT Image, Midjourney v7, Recraft V3, SD 3.5 / SDXL. Updated decision tree and trigger phrases.
|
||||
- **video** (2.0.0 → 2.0.1): refreshed model lineup — Sora 2 promoted from limited-availability caveat, Kling 2.5/3.0, added Seedance (ByteDance), Hailuo / MiniMax (character consistency), Hunyuan Video / Wan 2 (open-weight self-hosted), Pika 2.x. New "Quick picks" guide.
|
||||
|
||||
Total skills: 40 (unchanged).
|
||||
|
||||
### 2.0.0 (2026-05-05)
|
||||
|
||||
**Breaking changes** — Users must reinstall skills after this update.
|
||||
|
||||
#### Skill Renames (17)
|
||||
| Old Name | New Name |
|
||||
|----------|----------|
|
||||
| ab-test-setup | ab-testing |
|
||||
| analytics-tracking | analytics |
|
||||
| aso-audit | aso |
|
||||
| competitor-alternatives | competitors |
|
||||
| email-sequence | emails |
|
||||
| free-tool-strategy | free-tools |
|
||||
| launch-strategy | launch |
|
||||
| onboarding-cro | onboarding |
|
||||
| paid-ads | ads |
|
||||
| paywall-upgrade-cro | paywalls |
|
||||
| popup-cro | popups |
|
||||
| pricing-strategy | pricing |
|
||||
| product-marketing-context | product-marketing |
|
||||
| referral-program | referrals |
|
||||
| schema-markup | schema |
|
||||
| signup-flow-cro | signup |
|
||||
| social-content | social |
|
||||
|
||||
#### Consolidations (1)
|
||||
- `page-cro` + `form-cro` → `cro` (form content moved to `references/form.md`)
|
||||
|
||||
#### Why 2.0?
|
||||
- Shorter, cleaner skill names
|
||||
- Consistent naming conventions (no more `-strategy`, `-setup`, `-cro` suffixes)
|
||||
- Consolidated CRO into single skill with references
|
||||
- All cross-references updated across 100+ files
|
||||
|
||||
**Total skills: 40**
|
||||
|
||||
### 1.10.0 (2026-05-04)
|
||||
- Added `co-marketing` skill for partner identification, joint campaigns, and co-marketing strategy
|
||||
- Total skills: 41
|
||||
|
||||
### 2026-04-24
|
||||
- Added `image` skill for AI image generation, design tools, profile/listing banners, and optimization
|
||||
- Added `video` skill for AI video production (Hyperframes, HeyGen, Veo, Runway, Kling)
|
||||
- Added short-form video section to `social` (1.3.0) — TikTok, Reels, Shorts frameworks
|
||||
- Added HeyGen and Hyperframes tool integration guides
|
||||
- Fixed plugin marketplace: `source` field now passes Claude Code schema validation (#270)
|
||||
- Added proper `plugin.json` manifest with `"skills": "./skills"`
|
||||
- Total skills: 40
|
||||
|
||||
### 2026-04-21
|
||||
- Added `directory-submissions` skill for Product Hunt, G2, AI directories, and backlink strategy
|
||||
- Added `competitor-profiling` skill for competitive intelligence research
|
||||
- Added international SEO & localization section to `seo-audit` (1.2.0)
|
||||
- Added conversion tracking reference to `ads` (cross-platform pixel setup)
|
||||
- Added Zapier SDK integration for 8,000+ app access
|
||||
- Fixed plugin loading: removed `./` prefix from marketplace.json skill paths (#243)
|
||||
- Hardened CLI tools: Supermetrics API key moved to header, ZoomInfo JWT masked by default
|
||||
- Fixed community-marketing YAML frontmatter (#240)
|
||||
- Fixed Zapier webhook URL validation (#247)
|
||||
- Added missing skills to VERSIONS.md (aso, community-marketing, customer-research — shipped in prior releases)
|
||||
- Total skills: 38
|
||||
|
||||
### 2026-03-14
|
||||
- Added `lead-magnets` skill for lead magnet strategy, format selection, and conversion optimization
|
||||
- Added Composio integration layer for MCP access to OAuth-heavy tools (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion, etc.)
|
||||
- Added headless CMS integration guides (Sanity, Contentful, Strapi) with headless-cms reference
|
||||
- Added 197 evals across all 33 skills for automated quality testing
|
||||
- Optimized all 32 skill descriptions for better trigger phrase matching
|
||||
- Replaced rigid imperatives with reasoning-based guidance across all skills
|
||||
- Added 10 new CLI tools (airops, clay, close, coupler, crossbeam, outreach, pendo, similarweb, supermetrics, zoominfo)
|
||||
- Added 13 new integration guides
|
||||
- Bumped all 32 existing skills from 1.1.0 → 1.2.0
|
||||
|
||||
### 2026-02-27
|
||||
- Migrated context path from `.claude/` to `.agents/` for agent-agnostic compatibility
|
||||
- All skills now check `.agents/product-marketing.md` first, with `.claude/` fallback for older setups
|
||||
- Updated install paths in README to reference `.agents/skills/`
|
||||
- Bumped all 32 skills from 1.0.0 → 1.1.0
|
||||
|
||||
### 2026-02-22
|
||||
- Added `revops` skill for revenue operations, lead lifecycle, scoring, routing, pipeline management, and CRM automation
|
||||
- Added `sales-enablement` skill for sales decks, one-pagers, objection handling, demo scripts, and sales playbooks
|
||||
|
||||
### 2026-02-21
|
||||
- Added `site-architecture` skill for website structure planning, page hierarchy, navigation design, URL structure, and internal linking strategy
|
||||
|
||||
### 2026-02-18
|
||||
- Added `ai-seo` skill for AI search optimization (AEO, GEO, LLMO, AI Overviews)
|
||||
- Moved AEO/GEO content patterns from `seo-audit` references to `ai-seo` skill
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: ab-test-setup
|
||||
description: When the user wants to plan, design, or implement an A/B test or experiment. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," or "hypothesis." For tracking implementation, see analytics-tracking.
|
||||
name: ab-testing
|
||||
description: When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program. Also use when the user mentions "A/B test," "split test," "experiment," "test this change," "variant copy," "multivariate test," "hypothesis," "should I test this," "which version is better," "test two versions," "statistical significance," "how long should I run this test," "growth experiments," "experiment velocity," "experiment backlog," "ICE score," "experimentation program," or "experiment playbook." Use this whenever someone is comparing two approaches and wants to measure which performs better, or when they want to build a systematic experimentation practice. For tracking implementation, see analytics. For page-level conversion optimization, see cro.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# A/B Test Setup
|
||||
@@ -12,7 +12,7 @@ You are an expert in experimentation and A/B testing. Your goal is to help desig
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before designing a test, understand:
|
||||
|
||||
@@ -180,7 +180,7 @@ We'll know this is true when [metrics].
|
||||
- Check segment quality
|
||||
- Document external factors
|
||||
|
||||
**DON'T:**
|
||||
**Avoid:**
|
||||
- Peek at results and stop early
|
||||
- Make changes to variants
|
||||
- Add traffic from new sources
|
||||
@@ -229,6 +229,93 @@ Document every test with:
|
||||
|
||||
---
|
||||
|
||||
## Growth Experimentation Program
|
||||
|
||||
Individual tests are valuable. A continuous experimentation program is a compounding asset. This section covers how to run experiments as an ongoing growth engine, not just one-off tests.
|
||||
|
||||
### The Experiment Loop
|
||||
|
||||
```
|
||||
1. Generate hypotheses (from data, research, competitors, customer feedback)
|
||||
2. Prioritize with ICE scoring
|
||||
3. Design and run the test
|
||||
4. Analyze results with statistical rigor
|
||||
5. Promote winners to a playbook
|
||||
6. Generate new hypotheses from learnings
|
||||
→ Repeat
|
||||
```
|
||||
|
||||
### Hypothesis Generation
|
||||
|
||||
Feed your experiment backlog from multiple sources:
|
||||
|
||||
| Source | What to Look For |
|
||||
|--------|-----------------|
|
||||
| Analytics | Drop-off points, low-converting pages, underperforming segments |
|
||||
| Customer research | Pain points, confusion, unmet expectations |
|
||||
| Competitor analysis | Features, messaging, or UX patterns they use that you don't |
|
||||
| Support tickets | Recurring questions or complaints about conversion flows |
|
||||
| Heatmaps/recordings | Where users hesitate, rage-click, or abandon |
|
||||
| Past experiments | "Significant loser" tests often reveal new angles to try |
|
||||
|
||||
### ICE Prioritization
|
||||
|
||||
Score each hypothesis 1-10 on three dimensions:
|
||||
|
||||
| Dimension | Question |
|
||||
|-----------|----------|
|
||||
| **Impact** | If this works, how much will it move the primary metric? |
|
||||
| **Confidence** | How sure are we this will work? (Based on data, not gut.) |
|
||||
| **Ease** | How fast and cheap can we ship and measure this? |
|
||||
|
||||
**ICE Score** = (Impact + Confidence + Ease) / 3
|
||||
|
||||
Run highest-scoring experiments first. Re-score monthly as context changes.
|
||||
|
||||
### Experiment Velocity
|
||||
|
||||
Track your experimentation rate as a leading indicator of growth:
|
||||
|
||||
| Metric | Target |
|
||||
|--------|--------|
|
||||
| Experiments launched per month | 4-8 for most teams |
|
||||
| Win rate | 20-30% is common for mature programs (sustained higher rates may indicate conservative hypotheses) |
|
||||
| Average test duration | 2-4 weeks |
|
||||
| Backlog depth | 20+ hypotheses queued |
|
||||
| Cumulative lift | Compound gains from all winners |
|
||||
|
||||
### The Experiment Playbook
|
||||
|
||||
When a test wins, don't just implement it — document the pattern:
|
||||
|
||||
```
|
||||
## [Experiment Name]
|
||||
**Date**: [date]
|
||||
**Hypothesis**: [the hypothesis]
|
||||
**Sample size**: [n per variant]
|
||||
**Result**: [winner/loser/inconclusive] — [primary metric] changed by [X%] (95% CI: [range], p=[value])
|
||||
**Guardrails**: [any guardrail metrics and their outcomes]
|
||||
**Segment deltas**: [notable differences by device, segment, or cohort]
|
||||
**Why it worked/failed**: [analysis]
|
||||
**Pattern**: [the reusable insight — e.g., "social proof near pricing CTAs increases plan selection"]
|
||||
**Apply to**: [other pages/flows where this pattern might work]
|
||||
**Status**: [implemented / parked / needs follow-up test]
|
||||
```
|
||||
|
||||
Over time, your playbook becomes a library of proven growth patterns specific to your product and audience.
|
||||
|
||||
### Experiment Cadence
|
||||
|
||||
**Weekly (30 min)**: Review running experiments for technical issues and guardrail metrics. Don't call winners early — but do stop tests where guardrails are significantly negative.
|
||||
|
||||
**Bi-weekly**: Conclude completed experiments. Analyze results, update playbook, launch next experiment from backlog.
|
||||
|
||||
**Monthly (1 hour)**: Review experiment velocity, win rate, cumulative lift. Replenish hypothesis backlog. Re-prioritize with ICE.
|
||||
|
||||
**Quarterly**: Audit the playbook. Which patterns have been applied broadly? Which winning patterns haven't been scaled yet? What areas of the funnel are under-tested?
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
### Test Design
|
||||
@@ -261,6 +348,6 @@ Document every test with:
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For generating test ideas based on CRO principles
|
||||
- **analytics-tracking**: For setting up test measurement
|
||||
- **cro**: For generating test ideas based on CRO principles
|
||||
- **analytics**: For setting up test measurement
|
||||
- **copywriting**: For creating variant copy
|
||||
@@ -0,0 +1,105 @@
|
||||
{
|
||||
"skill_name": "ab-testing",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "I want to A/B test our homepage headline. We currently say 'The All-in-One Project Management Tool' and want to test something benefit-focused. We get about 15,000 visitors/month and our current signup rate is 3.2%.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should build a proper hypothesis using the framework: 'Because [observation], we believe [change] will cause [outcome], which we'll measure by [metric].' Should identify this as an A/B test (two variants). Should calculate or reference sample size needs based on 15,000 monthly visitors and 3.2% baseline. Should define primary metric (signup rate), secondary metrics, and guardrail metrics. Should warn about the peeking problem and recommend a fixed test duration. Should provide the test plan in the structured output format.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Uses the hypothesis framework with observation, belief, outcome, and metric",
|
||||
"Identifies as A/B test type",
|
||||
"Addresses sample size calculation based on traffic and baseline rate",
|
||||
"Defines primary metric (signup rate)",
|
||||
"Defines secondary and guardrail metrics",
|
||||
"Warns about the peeking problem",
|
||||
"Provides structured test plan output"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "we want to test like 4 different CTA button colors on our pricing page. is that a good idea?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should identify this as an A/B/n test (multiple variants). Should caution that testing 4 variants requires significantly more traffic than a simple A/B test. Should reference the sample size quick reference showing traffic multipliers for multiple variants. Should question whether button color alone is likely to produce meaningful lift vs testing CTA copy, placement, or surrounding context. Should recommend either reducing to 2 variants or ensuring sufficient traffic. Should still provide hypothesis framework and test setup if proceeding.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Identifies as A/B/n test (multiple variants)",
|
||||
"Cautions about increased traffic needs for 4 variants",
|
||||
"References sample size requirements",
|
||||
"Questions whether button color alone is high-impact",
|
||||
"Suggests alternative higher-impact elements to test",
|
||||
"Provides hypothesis framework"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Our test has been running for 3 days and Variant B is winning with 95% confidence. Should we call it?",
|
||||
"expected_output": "Should immediately address the peeking problem. Should explain that checking results early inflates false positive rates. Should recommend running for the full pre-calculated duration regardless of early results. Should explain why early significance can be misleading (regression to the mean, day-of-week effects, audience mix shifts). Should provide guidance on when it IS appropriate to stop early (sequential testing methods). Should recommend the pre-test commitment to duration.",
|
||||
"assertions": [
|
||||
"Addresses the peeking problem directly",
|
||||
"Explains why early significance is misleading",
|
||||
"Recommends running for full pre-calculated duration",
|
||||
"Mentions day-of-week effects or audience mix shifts",
|
||||
"Explains false positive rate inflation from peeking",
|
||||
"Mentions sequential testing as alternative approach"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Help me set up a multivariate test on our landing page. I want to test the headline, hero image, and CTA button simultaneously.",
|
||||
"expected_output": "Should identify this as a Multivariate Test (MVT). Should explain that MVT tests combinations of elements and requires much more traffic than A/B tests. Should calculate or reference traffic needs (combinations multiply: e.g., 2 headlines × 2 images × 2 CTAs = 8 combinations). Should recommend MVT only if traffic supports it, otherwise suggest sequential A/B tests. Should build hypotheses for each element being tested. Should define interaction effects to watch for. Should provide structured test plan.",
|
||||
"assertions": [
|
||||
"Identifies as multivariate test (MVT)",
|
||||
"Explains MVT tests combinations of elements",
|
||||
"Addresses dramatically higher traffic requirements",
|
||||
"Calculates number of combinations",
|
||||
"Suggests sequential A/B tests as alternative if traffic insufficient",
|
||||
"Builds hypotheses for each element",
|
||||
"Provides structured test plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "What metrics should I track for an A/B test on our trial signup page? We're testing a longer form (adds company size and role fields) against the current short form.",
|
||||
"expected_output": "Should apply the metrics selection framework with three tiers: primary, secondary, and guardrail metrics. Primary: form completion rate (the direct conversion metric). Secondary: lead quality metrics (SQL conversion rate, activation rate post-signup). Guardrail: overall signup volume (ensure longer form doesn't tank total signups below acceptable threshold). Should explain the tradeoff between conversion quantity and lead quality. Should note that this test needs longer observation window to measure downstream metrics.",
|
||||
"assertions": [
|
||||
"Applies three-tier metric framework (primary, secondary, guardrail)",
|
||||
"Identifies form completion rate as primary metric",
|
||||
"Identifies lead quality as secondary metric",
|
||||
"Defines guardrail metrics to protect against negative outcomes",
|
||||
"Explains quantity vs quality tradeoff",
|
||||
"Notes need for longer observation window for downstream metrics"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Can you help me write copy for our new landing page? We want to test it against the current version.",
|
||||
"expected_output": "Should recognize this is primarily a copywriting task, not a test setup task. Should defer to or cross-reference the copywriting skill for writing the actual copy. May help frame the test hypothesis and setup, but should make clear that copywriting is the right skill for creating the page copy itself.",
|
||||
"assertions": [
|
||||
"Recognizes this as primarily a copywriting task",
|
||||
"References or defers to copywriting skill",
|
||||
"Does not attempt to write full page copy using test setup patterns",
|
||||
"May offer to help with test hypothesis and setup"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "We ran an A/B test on our pricing page for 4 weeks. Control: 2.1% conversion. Variant: 2.4% conversion. 12,000 visitors per variant. Is this statistically significant? Should we ship it?",
|
||||
"expected_output": "Should evaluate the results against statistical significance criteria. Should calculate or estimate whether the sample size is sufficient to detect a 0.3 percentage point lift from a 2.1% baseline (this is a ~14% relative lift). Should reference the 95% confidence threshold. Should discuss practical significance vs statistical significance. Should recommend whether to ship, continue testing, or iterate. Should consider segment analysis if results are borderline.",
|
||||
"assertions": [
|
||||
"Evaluates against statistical significance criteria",
|
||||
"Addresses whether sample size is sufficient for this effect size",
|
||||
"References 95% confidence threshold",
|
||||
"Distinguishes statistical significance from practical significance",
|
||||
"Provides clear recommendation on shipping",
|
||||
"Suggests segment analysis or follow-up if borderline"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: ad-creative
|
||||
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' or 'ad performance optimization.' This skill covers generating ad creative at scale, iterating based on performance data, and enforcing platform character limits. For campaign strategy and targeting, see paid-ads. For landing page copy, see copywriting."
|
||||
description: "When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad variations — for any paid advertising platform. Also use when the user mentions 'ad copy variations,' 'ad creative,' 'generate headlines,' 'RSA headlines,' 'bulk ad copy,' 'ad iterations,' 'creative testing,' 'ad performance optimization,' 'write me some ads,' 'Facebook ad copy,' 'Google ad headlines,' 'LinkedIn ad text,' 'static ads,' 'static ad concepts,' 'ad templates,' 'iMessage ad,' 'chat reveal ad,' 'text message ad,' 'fake DM ad,' 'ChatGPT ad,' 'Apple Notes ad,' 'motion video ad,' 'faceless video ad,' 'animated explainer ad,' 'motion collage ad,' or 'I need more ad variations.' Use this whenever someone needs to produce ad copy at scale or iterate on existing ads. For campaign strategy and targeting, see ads. For landing page copy, see copywriting."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.5.0
|
||||
---
|
||||
|
||||
# Ad Creative
|
||||
@@ -12,7 +12,7 @@ You are an expert performance creative strategist. Your goal is to generate high
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
@@ -46,7 +46,7 @@ Gather this context (ask if not provided):
|
||||
|
||||
## How This Skill Works
|
||||
|
||||
This skill supports two modes:
|
||||
This skill supports three modes:
|
||||
|
||||
### Mode 1: Generate from Scratch
|
||||
When starting fresh, you generate a full set of ad creative based on product context, audience insights, and platform best practices.
|
||||
@@ -60,11 +60,40 @@ The core loop:
|
||||
Pull performance data → Identify winning patterns → Generate new variations → Validate specs → Deliver
|
||||
```
|
||||
|
||||
### Mode 3: Scaled Static Batches (Grounded)
|
||||
For recurring static ad production at volume (e.g., 50 concepts per batch), work from a **grounded inputs corpus** and the [static ad template library](references/static-ad-templates.md). Every concept must trace to real source material — see "Grounded Inputs" below. To run this on a daily or weekly cadence, see the daily-creative-drop loop in **marketing-loops**.
|
||||
|
||||
---
|
||||
|
||||
## Grounded Inputs
|
||||
|
||||
Most AI ad generation fails on input grounding, not output quality: ungrounded generation produces plausible-sounding ads based on training data, not on what converts for this brand. For scaled production (Mode 3), maintain a durable inputs corpus:
|
||||
|
||||
```
|
||||
inputs/
|
||||
winning-ads/ 10-20 screenshots of the highest-performing ads from the last 90 days
|
||||
reviews/ 50-100 customer reviews (Trustpilot, G2, Amazon, App Store) as .md/.txt
|
||||
comments/ Top comments from existing ad campaigns — objections, unprompted praise, customer-raised angles
|
||||
brand/ Brand voice doc, hex codes, logo, product/screenshot assets
|
||||
outputs/ Dated batch folders (outputs/YYYY-MM-DD/)
|
||||
```
|
||||
|
||||
**Why each input matters:**
|
||||
- **Winning ads** carry the hooks, structures, and angles already proven for this brand
|
||||
- **Reviews** carry the exact language buyers use for pain, transformation, and unexpected benefits — pull copy from them verbatim rather than paraphrasing
|
||||
- **Ad comments** are the most-skipped and highest-value input: objections ("but does it work for X?") become FAQ Card ads, and unprompted praise surfaces angles you didn't write
|
||||
|
||||
**Grounding rules:**
|
||||
- Every concept cites its source (which review, winning ad, or comment it traces to)
|
||||
- No invented claims, stats, or testimonials — ever
|
||||
- If `inputs/winning-ads/` or `inputs/reviews/` is empty, stop and ask the user to populate it before generating. Do not generate ungrounded concepts as a fallback.
|
||||
- Inputs decay: refresh `inputs/winning-ads/` as new ads scale; refresh `inputs/reviews/` and `inputs/comments/` monthly
|
||||
|
||||
---
|
||||
|
||||
## Platform Specs
|
||||
|
||||
**Always enforce these limits.** Never deliver creative that exceeds platform character limits.
|
||||
Platforms reject or truncate creative that exceeds these limits, so verify every piece of copy fits before delivering.
|
||||
|
||||
### Google Ads (Responsive Search Ads)
|
||||
|
||||
@@ -119,7 +148,13 @@ For detailed specs and format variations, see [references/platform-specs.md](ref
|
||||
|
||||
## Generating Ad Visuals
|
||||
|
||||
For image and video ad creative, use generative AI tools and code-based video rendering. See [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
|
||||
**For static ad structure**, use the 15-template library in [references/static-ad-templates.md](references/static-ad-templates.md) — layout frameworks (Us vs. Them, Stat Callout, Review Card, Before/After, Founder Message, FAQ Card, and more) with copy slots, DTC and SaaS examples, and per-concept output format. Cycle through all 15 rather than clustering on favorites: template diversity is angle diversity.
|
||||
|
||||
**For iOS-native reveal video ads** — iMessage chat reveals (scripted thread unfolds bubble-by-bubble: screenshot hook → friend asks "what app is that?" → brand + promo code reveal → end card), ChatGPT reveals (typed question → streaming answer), and Apple Notes reveals (a confessional note typed live) — see [references/imessage-video-ads.md](references/imessage-video-ads.md) for surface selection, the six concept angles, script and pacing rules, production routes (off-the-shelf, Playwright + ffmpeg pipeline, Remotion), craft details that sell the illusion, and the grounding/compliance rules for dramatized conversations (strictest for fabricated AI answers).
|
||||
|
||||
**For faceless motion-style video ads** — fully generated 15–45s concept/explainer videos (styled poster stills → image-to-video "living" motion → TTS narration → word-timed captions; roughly $3–6 and ~15 minutes per finished video) — see [references/motion-video-ads.md](references/motion-video-ads.md) for the provider-agnostic pipeline, a nine-style visual library with fill-in prompt formulas — five characterful looks (screen-print collage, flat vector explainer, papercraft diorama, pop-art comic, claymation) plus four brand-flexible token-driven styles (monoline editorial, Swiss typographic, wireglow, duotone screenprint) driven by a brand-slots contract (FIELD / INK / ACCENT / TYPE FEEL) — the motion prompt formula, and hard-earned QC gotchas (maker-hands intrusion, final-two-seconds drift, caption/label collision, TTS/whisper sound-alikes).
|
||||
|
||||
For image and video generation tools, see [references/generative-tools.md](references/generative-tools.md) for the complete guide covering:
|
||||
|
||||
- **Image generation** — Nano Banana Pro (Gemini), Flux, Ideogram for static ad images
|
||||
- **Video generation** — Veo, Kling, Runway, Sora, Seedance, Higgsfield for video ads
|
||||
@@ -273,6 +308,19 @@ headline_1,headline_2,headline_3,description_1,description_2,platform
|
||||
"Stop Manual Reporting","Automate in 5 Minutes","Join 10K+ Teams","Save 10+ hrs/week on reports. Start free.","Connect data sources once. Reports forever.","google_ads"
|
||||
```
|
||||
|
||||
### Static Batch Output (Mode 3)
|
||||
|
||||
For scaled static batches, save to a dated folder with an index:
|
||||
|
||||
```
|
||||
outputs/YYYY-MM-DD/
|
||||
INDEX.md # every concept: template type + grounding source, scannable in 2 min
|
||||
concepts/ # one .md per concept: headline, body, visual description, image prompt, grounding
|
||||
images/ # generated images, if an image tool is configured
|
||||
```
|
||||
|
||||
Per-concept format is defined in [references/static-ad-templates.md](references/static-ad-templates.md). The human workflow this supports: open the folder, scan INDEX.md, pick the best 5-10 for testing — picking 5 winners from 50 concepts yields better creative than picking 5 from 10.
|
||||
|
||||
### Iteration Report
|
||||
|
||||
When iterating, include a summary:
|
||||
@@ -320,9 +368,11 @@ For large-scale creative production (Anthropic's growth team generates 100+ vari
|
||||
- **Writing headlines that only work together** — RSA headlines get combined randomly
|
||||
- **Ignoring character limits** — Platforms truncate without warning
|
||||
- **All variations sound the same** — Vary angles, not just word choice
|
||||
- **No CTA headlines** — Always include action-oriented headlines
|
||||
- **No CTA headlines** — RSAs need action-oriented headlines to drive clicks; include at least 2-3
|
||||
- **Generic descriptions** — "Learn more about our solution" wastes the slot
|
||||
- **Iterating without data** — Gut feelings are less reliable than metrics
|
||||
- **Generating without grounding** — Ungrounded concepts read like every other ad in the feed; feed the skill winning ads, reviews, and comments first
|
||||
- **Skipping the comments input** — Ad comments hold the objections and angles customers raise themselves; those usually convert best
|
||||
- **Testing too many things at once** — Change one variable per test cycle
|
||||
- **Retiring creative too early** — Allow 1,000+ impressions before judging
|
||||
|
||||
@@ -355,8 +405,10 @@ node tools/clis/google-ads.js reports get --type ad_performance --date-range las
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **paid-ads**: For campaign strategy, targeting, budgets, and optimization
|
||||
- **ads**: For campaign strategy, targeting, budgets, and optimization
|
||||
- **marketing-loops**: For running static batch generation on a recurring cadence (the daily-creative-drop loop)
|
||||
- **customer-research**: For mining reviews and comments when building the grounded inputs corpus
|
||||
- **copywriting**: For landing page copy (where ad traffic lands)
|
||||
- **ab-test-setup**: For structuring creative tests with statistical rigor
|
||||
- **ab-testing**: For structuring creative tests with statistical rigor
|
||||
- **marketing-psychology**: For psychological principles behind high-performing creative
|
||||
- **copy-editing**: For polishing ad copy before launch
|
||||
|
||||
@@ -0,0 +1,120 @@
|
||||
{
|
||||
"skill_name": "ad-creative",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Generate ad creative for our Meta (Facebook/Instagram) campaign. We sell an AI writing assistant for content marketers. Main value prop: write blog posts 5x faster. Target audience: content marketing managers at B2B SaaS companies. Budget: $5k/month.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should generate creative following the angle-based approach: identify 3-5 angles (speed, quality, ROI, pain of blank page, competitive edge). For each angle, should generate primary text (≤125 chars), headline (≤40 chars), and description (≤30 chars) respecting Meta character limits. Should provide multiple variations per angle. Should suggest image/visual direction for each. Should organize output with angle name, hook, body, CTA for each variation. Should recommend which angles to test first.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Uses angle-based generation approach",
|
||||
"Identifies multiple angles (3-5)",
|
||||
"Respects Meta character limits (125/40/30)",
|
||||
"Generates multiple variations per angle",
|
||||
"Suggests image or visual direction",
|
||||
"Includes hook, body, and CTA for each",
|
||||
"Recommends which angles to test first"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "I need Google Ads copy for our CRM product. We're targeting the keyword 'best CRM for small business'. Need responsive search ads.",
|
||||
"expected_output": "Should generate Google RSA creative respecting character limits: headlines (≤30 chars each, need 10-15 variations) and descriptions (≤90 chars each, need 4+ variations). Should note that pinning should be used sparingly as it reduces optimization. Should include the target keyword in headlines. Should provide multiple angle-based variations. Should suggest ad extensions (sitelinks, callouts, structured snippets). Should follow Google Ads best practices for RSA.",
|
||||
"assertions": [
|
||||
"Respects Google RSA character limits (30 char headlines, 90 char descriptions)",
|
||||
"Generates 10-15 headline variations",
|
||||
"Generates 4+ description variations",
|
||||
"Includes target keyword in headlines",
|
||||
"Notes pinning should be used sparingly per skill guidance",
|
||||
"Suggests ad extensions",
|
||||
"Uses angle-based variation approach"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Here's our ad performance data: Ad A (pain point angle) - CTR 2.1%, CPC $3.20, Conv rate 4.5%. Ad B (social proof angle) - CTR 1.4%, CPC $4.10, Conv rate 6.2%. Ad C (feature angle) - CTR 0.8%, CPC $5.50, Conv rate 2.1%. Help me iterate on these.",
|
||||
"expected_output": "Should activate the iteration-from-performance mode (not generate-from-scratch). Should analyze the data: Ad A has best CTR, Ad B has best conversion rate (highest efficiency despite lower CTR), Ad C is underperforming on all metrics. Should recommend doubling down on the pain point angle (high CTR) and social proof angle (high conversion), while pausing or reworking the feature angle. Should generate new variations that combine winning elements (pain point hook + social proof). Should suggest specific iterations on Ad A and Ad B.",
|
||||
"assertions": [
|
||||
"Activates iteration mode based on performance data",
|
||||
"Analyzes CTR, CPC, and conversion rate for each ad",
|
||||
"Identifies winning angles from the data",
|
||||
"Recommends pausing or reworking underperforming creative",
|
||||
"Generates new variations combining winning elements",
|
||||
"Provides specific iterations on top performers"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "we need linkedin ads for our enterprise security product. audience is CISOs and IT directors.",
|
||||
"expected_output": "Should trigger on casual phrasing. Should generate LinkedIn ad creative respecting character limits: introductory text (≤150 chars), headline (≤70 chars), description (≤100 chars). Should adapt tone and messaging for enterprise security audience (CISOs, IT directors) — more formal, compliance-focused, risk-reduction language. Should provide multiple angles relevant to security buyers (risk reduction, compliance, incident response time, cost of breaches). Should suggest ad format recommendations for LinkedIn (sponsored content, message ads, etc.).",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Respects LinkedIn character limits (150/70/100)",
|
||||
"Adapts tone for enterprise security audience",
|
||||
"Uses risk-reduction and compliance language",
|
||||
"Provides multiple angles relevant to security buyers",
|
||||
"Suggests LinkedIn ad format recommendations"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "I need to generate a big batch of ad variations for a multi-platform campaign launching next week. We're a meal delivery service targeting busy professionals. Need ads for Google, Meta, and TikTok.",
|
||||
"expected_output": "Should activate the batch generation workflow. Should generate creative for all three platforms respecting each platform's character limits: Google RSA (30/90), Meta (125/40/30), TikTok (80 chars recommended, 100 max). Should identify 3-5 angles that work across platforms (convenience, health, time savings, variety, cost vs eating out). Should generate variations per angle per platform. Should note platform-specific creative considerations (TikTok needs video concepts, not just text). Should organize output clearly by platform.",
|
||||
"assertions": [
|
||||
"Activates batch generation workflow",
|
||||
"Generates for all three platforms",
|
||||
"Respects each platform's character limits",
|
||||
"Identifies angles that work across platforms",
|
||||
"Notes TikTok needs video concepts",
|
||||
"Organizes output by platform",
|
||||
"Generates multiple variations per angle per platform"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Help me plan our overall paid advertising strategy. We have a $20k monthly budget and want to figure out which platforms to use and how to allocate spend.",
|
||||
"expected_output": "Should recognize this is a paid advertising strategy task, not ad creative generation. Should defer to or cross-reference the ads skill, which handles campaign strategy, platform selection, and budget allocation. May briefly mention creative considerations but should make clear that ads is the right skill for strategy.",
|
||||
"assertions": [
|
||||
"Recognizes this as paid ads strategy, not creative generation",
|
||||
"References or defers to ads skill",
|
||||
"Does not attempt full campaign strategy using creative generation patterns"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "I want to make one of those iMessage-style video ads for Meta — the ones where a fake text conversation reveals the product and a promo code. We sell a sleep tracking ring. Our promo code is RESTED.",
|
||||
"expected_output": "Should load references/imessage-video-ads.md. Should start by picking a concept angle from the six-angle catalog (result-as-screenshot, setup flex, cancellation moment, feature-as-punchline, friend-asks-friend inverse, receipt-as-hook) before writing bubbles — likely result-as-screenshot (a sleep score) for this product. Should draft an 8-14 bubble script in real texting voice where the brand appears only after the peer asks, with the RESTED code delivered conversationally inside a bubble and repeated on a static end card. Should apply grounding rules: any sleep-improvement claim in the thread must trace to a real customer result or product fact, and the thread must not be framed as a real testimonial. Should present production route options (off-the-shelf skill, Playwright+ffmpeg pipeline, or Remotion) rather than assuming one, and mention key craft rules (the recognizable send/receive SFX, silent typing indicators, 9:16 1080x1920).",
|
||||
"assertions": [
|
||||
"Loads or applies the imessage-video-ads reference",
|
||||
"Selects a concept angle before writing the script",
|
||||
"Script is 8-14 bubbles in authentic texting voice",
|
||||
"Brand name appears only after the peer asks about it",
|
||||
"Promo code RESTED appears in a bubble and on the end card",
|
||||
"Applies grounding rules — no fabricated claims, not framed as a real testimonial",
|
||||
"Mentions at least one production route and key craft rules (SFX, silent typing indicator, 9:16)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 8,
|
||||
"prompt": "We sell a menopause supplement. I saw those ads where someone asks ChatGPT a health question and the answer recommends the product — make one of those for us. Also curious about the Apple Notes version.",
|
||||
"expected_output": "Should load references/imessage-video-ads.md and apply the Other iOS-Native Reveal Surfaces section. Should flag the compliance constraint prominently BEFORE drafting: a fabricated AI answer making health claims is the highest-risk version of this format — every claim needs substantiation, health/medical advice in a fake ChatGPT answer needs legal review, and the exchange must not be presented as a real unprompted ChatGPT output endorsing the product. May propose a compliant angle (mechanism education grounded in documented facts) or steer to the Apple Notes confession format as the lower-risk fit for a transformation story. For the Notes version: title-as-hook, first-person list with the product as the least enthusiastic line, keyboard-taps-only audio, grounding realizations in real reviews. Should apply surface-selection guidance rather than treating the three formats as interchangeable.",
|
||||
"assertions": [
|
||||
"Applies the iOS-native reveal surfaces section of the imessage-video-ads reference",
|
||||
"Flags health-claim/substantiation risk for the fabricated ChatGPT answer before or while drafting",
|
||||
"Does not present the ChatGPT exchange as a real unprompted output endorsing the product",
|
||||
"Recommends legal review or a compliant reframe for health advice in the AI answer",
|
||||
"Apple Notes guidance: title-as-hook, first-person confession, product as an understated list item, keyboard-taps-only audio",
|
||||
"Grounds claims and realizations in documented facts/reviews (Grounded Inputs)",
|
||||
"Gives surface-selection reasoning (ChatGPT vs Notes) instead of treating formats as interchangeable"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -8,7 +8,7 @@ Reference for using AI image generators, video generators, and code-based video
|
||||
|
||||
| Need | Tool Category | Best Fit |
|
||||
|------|---------------|----------|
|
||||
| Static ad images (banners, social) | Image generation | Nano Banana Pro, Flux, Ideogram |
|
||||
| Static ad images (banners, social) | Image generation | ChatGPT Images 2.0, Nano Banana Pro, Flux, Ideogram |
|
||||
| Ad images with text overlays | Image generation (text-capable) | Ideogram, Nano Banana Pro |
|
||||
| Short video ads (6-30 sec) | Video generation | Veo, Kling, Runway, Sora, Seedance |
|
||||
| Video ads with voiceover | Video gen + voice | Veo/Sora (native), or Runway + ElevenLabs |
|
||||
|
||||
@@ -0,0 +1,186 @@
|
||||
# iOS-Native Reveal Video Ads (iMessage, ChatGPT, Apple Notes)
|
||||
|
||||
A family of 9:16 social-native video formats that recreate a familiar iOS surface in real time and let the brand emerge inside it. The flagship is the **iMessage chat reveal** — someone sends a screenshot of a result or product, a friend reacts and asks what it is, and the conversation reveals the brand, usually with a promo code. Message bubbles pop in over ~15–22 seconds with authentic send/receive sounds, then a static brand end card lands the CTA. The same architecture powers **ChatGPT reveals** and **Apple Notes reveals** — covered in [Other iOS-Native Reveal Surfaces](#other-ios-native-reveal-surfaces) below.
|
||||
|
||||
The format works because it borrows the most-read UI on earth. A chat thread is a familiar, high-attention dramatization — it mirrors how real recommendations happen, so the viewer leans in instead of scrolling past. The CTA arrives conversationally ("use code FREEPACK") instead of as a hard sell, which keeps the ad-skip reflex from firing until the pitch has already landed. Run it only as a clearly labeled paid placement (Meta's "Sponsored" tag does the disclosure work); never seed it organically as if it were a real leaked conversation.
|
||||
|
||||
Credit: this reference distills the format popularized by Shiv Sakhuja and the Gooseworks team ([@shivsakhuja](https://x.com/shivsakhuja), [gooseworks-ai/gooseworks-ads-skills](https://github.com/gooseworks-ai/gooseworks-ads-skills)), who report the format performing strongly on Meta.
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Format
|
||||
|
||||
**Good fit:**
|
||||
- Reaction/discovery ads where the punchline is the recipient's curiosity ("wait, what app is that?")
|
||||
- Promo-code offers — the conversational delivery feels far less ad-like than a code on a slate
|
||||
- Products with a screenshot-able result: a number, a dashboard, a receipt, a before/after
|
||||
- UGC-style angles when you don't have UGC creators on tap
|
||||
|
||||
**Poor fit:**
|
||||
- Considered B2B purchases where a casual text exchange undercuts credibility
|
||||
- Products with nothing visual or numeric to screenshot (fix the hook first, not the format)
|
||||
- Brands whose compliance review can't approve dramatized conversations (regulated industries — check first)
|
||||
|
||||
**Platform fit:** Built for Meta Reels/Stories placements (9:16, 1080×1920) with a 1:1 center-crop variant for feed. Works on TikTok and YouTube Shorts with the same master file.
|
||||
|
||||
---
|
||||
|
||||
## Compliance and Grounding
|
||||
|
||||
This is a **dramatization** — a scripted conversation, not a real one. That's a standard, legitimate ad device, but two rules keep it honest and on the right side of FTC guidance:
|
||||
|
||||
1. **Every claim in the thread must be true of the product.** The race time, the savings math, the "5 minutes a day" — ground each one in a real customer result, review, or verifiable product fact, exactly as the Grounded Inputs rules in SKILL.md require. The conversation is fictional; the facts inside it can't be.
|
||||
2. **Don't present the thread as a real testimonial.** No real customer names, no "this is an actual text from a customer" framing, no fabricated endorsements. The format persuades through recognizability, not through pretending to be found footage.
|
||||
|
||||
If a claim needs a disclaimer on your landing page, it needs one on this ad too.
|
||||
|
||||
---
|
||||
|
||||
## Concept Angles
|
||||
|
||||
Most iMessage ads fit one of six angles. Pick the angle before writing any copy — the most common failure mode ("script is fine but the ad feels off") is an angle mismatch, not bad lines. The strongest hooks share one of three traits: a specific number, a small act of self-trust, or a physically novel product mechanic.
|
||||
|
||||
| Angle | The hook attachment | The reveal |
|
||||
|---|---|---|
|
||||
| **Result-as-screenshot** | A number that brags by itself — race time, app summary, dashboard stat | "X minutes a day. that's it." |
|
||||
| **Setup flex** | A photo of your space — tiny apartment gym, race-kit corner, desk setup | "this is the whole setup" |
|
||||
| **Cancellation moment** | A confirmation receipt — gym cancellation email, "subscription cancelled" page | "$X/mo → $Y/mo. do the math" |
|
||||
| **Feature-as-punchline** | A short clip of the product mechanic in motion | The mechanic *is* the brand |
|
||||
| **Friend-asks-friend (inverse)** | The *peer* opens with the wow — "how are you doing this 😭" | *You* reply with the brand |
|
||||
| **Receipt-as-hook** | A mundane financial document — statement, App Store receipt | A small act of self-trust |
|
||||
|
||||
---
|
||||
|
||||
## Anatomy of the Ad
|
||||
|
||||
```
|
||||
0:00 Hook attachment lands (the screenshot the whole chat is about)
|
||||
↓ short reactions, 250–450ms apart ("bro no way" / "wait is that real")
|
||||
0:06 The question — "what app is that??"
|
||||
↓ typing indicator … then the brand-name reply
|
||||
0:12 The pitch, in texting voice — one or two bubbles max
|
||||
0:15 The code — "use FREEPACK, first pack's free" (code renders link-underlined)
|
||||
0:17 Beat of silence, then the closer — "bet" / "ok downloading"
|
||||
0:18 300ms crossfade → static brand end card: logo, code, tagline (~3s)
|
||||
```
|
||||
|
||||
**Script rules:**
|
||||
|
||||
- **8–14 bubbles total.** Shorter reads thin; longer loses the scroll-past viewer.
|
||||
- **Write in real texting voice.** Lowercase, fragments, one emoji max per message, no marketing adjectives. Read it aloud as two friends — any bubble that sounds like ad copy gets cut.
|
||||
- **The brand appears once, late.** The thread is about the *result* until someone asks. Naming the brand in bubble two kills the reveal.
|
||||
- **Pacing has rhythm, not a metronome.** One-word reactions fire 250–450ms apart; sentence replies get 600–900ms of air after them; leave ~600ms of silence before the final reaction so it lands.
|
||||
- **Typing indicators go before sentence-length peer replies**, optional before short reactions. The indicator appearing is silent (see SFX rules below).
|
||||
- **The promo code goes inside a bubble**, styled with iOS's link-detection underline, *and* on the end card. Conversational delivery first, reinforcement second.
|
||||
|
||||
---
|
||||
|
||||
## Production Routes
|
||||
|
||||
Three ways to produce it, in order of control:
|
||||
|
||||
### Route 1: Off-the-shelf skill (fastest)
|
||||
|
||||
Gooseworks distributes their pipeline as an installable agent skill — `npx gooseworks install --all`, then invoke the goose-ads skill from your agent. It handles rendering, recording, SFX, and stitching end to end. Use this to validate the format before building anything custom. (Their ads-skills source repo is public but carries no open-source license — treat it as reference reading, not code to vendor.)
|
||||
|
||||
### Route 2: Code-based pipeline (full control)
|
||||
|
||||
The architecture that produces a convincing result: render the chat as HTML/CSS mimicking the iMessage UI, drive the animation with a timeline script, record it headlessly with Playwright, and assemble audio + end card with ffmpeg.
|
||||
|
||||
1. **Script as data.** Store the thread as JSON: participants (peer name, initials, avatar color), ordered messages (`from`, `text`, attachment paths, typing-indicator flags), theme, header. The script is reviewable and re-renderable without touching code.
|
||||
2. **Render the chat UI in HTML/CSS.** Dark theme reads most native. Two variants: full-bleed chat, or the chat inside an iPhone frame (status bar + Dynamic Island) over a brand-relevant background photo — the framed variant reads more native in-feed and is the better default.
|
||||
3. **Animate with a timeline, record in ONE continuous session.** All bubbles exist in the DOM but hidden (`display: none` — not `opacity: 0`, or the thread pre-allocates space and never "grows"). A driver script walks a timeline array revealing each bubble, driving the composer, and auto-scrolling. Never record scene-by-scene and concat — every page reload causes a visible micro-flicker.
|
||||
4. **Type the composer for every sent bubble.** The typed text must exactly equal the sent text (a mismatch reads fake on second watch). Pace ~12–15 chars/sec with ±30% per-character jitter so it feels like thumbs, not a script.
|
||||
5. **Record at native output resolution.** Set both the Playwright `viewport` *and* `recordVideo.size` to 1080×1920 — if you omit `recordVideo.size`, Playwright records a scaled-down video by default. Recording small and upscaling ships soft, blurry bubble text.
|
||||
6. **Layer audio with ffmpeg.** SFX cues computed deterministically from the same timeline that drove the recording, so sounds land exactly on bubble pops.
|
||||
7. **Stitch: chat → 300ms crossfade → static end card.** ffmpeg's `xfade` requires both inputs to match in resolution, pixel format, and frame rate — render the end card to a fixed-frame MP4 at the same specs as the chat recording before fading. Export the 9:16 master plus a 1:1 center crop.
|
||||
|
||||
### Route 3: Remotion (templated scale)
|
||||
|
||||
Once a winning script structure emerges, rebuild it as a Remotion composition (see [generative-tools.md](generative-tools.md)) with the thread JSON as props. Then variations — new hooks, new codes, new personas — are data changes, not re-productions. Right move at the "we're testing 10 script variants a week" stage, not for the first ad.
|
||||
|
||||
---
|
||||
|
||||
## Craft Rules (the details that sell the illusion)
|
||||
|
||||
These are the difference between "feels like a real chat" and "feels like a mockup":
|
||||
|
||||
- **The real send/receive sounds, never generic notification sounds.** The iMessage feel is mostly the audio. BigSoundBank hosts recordings of Apple's message sounds under CC0: send whoosh (`bigsoundbank.com/UPLOAD/mp3/1313.mp3`, ~0.5s) and receive tritone (`bigsoundbank.com/UPLOAD/mp3/1111.mp3` — trim to ~1.4s with a 400ms fade). Normalize loud (≈ -9 LUFS) so they cut through the music. Note the recordings being CC0 doesn't mean Apple has licensed its sound marks or UI trade dress — this is standard practice in the format, but regulated brands and risk-averse legal teams should review the iMessage mimicry as a whole; a generic chat-app skin (neutral bubbles, non-Apple sounds) is the fallback that keeps the mechanic.
|
||||
- **No sound on the typing indicator.** iOS is silent when someone starts typing. Play the receive sound only when the actual bubble replaces the dots. This is the single most common tell.
|
||||
- **Music bed: quiet lofi/hip-hop instrumental.** ~30% volume, highpass around 60Hz to clear room for the SFX, fade out ~1.5s before the code reveal so the CTA lands in relative silence.
|
||||
- **Static end card — no zoom, no Ken Burns drift.** The brand slate must land hard; a drifting end card reads as filler.
|
||||
- **Real brand logo SVG on the end card, never CSS-styled text.** Font-approximated wordmarks look amateur even when close. Pull the official SVG from the brand's press kit, Wikimedia, or brandfetch.com.
|
||||
- **Hook screenshots: mimic the real app's UI, don't AI-generate it.** AI-generated app UIs ship garbled chrome that reads as slop. Build a small HTML page copying the actual app's brand colors, typography, and layout conventions (the Strava-orange strip, the "Public · 2h ago" timestamp) and screenshot it. Reserve AI image generation for *photographic* hooks — a beach photo, a lifestyle shot, the framed variant's background.
|
||||
- **Audio mixing gotcha:** ffmpeg's `amix` divides volume by input count by default — pass `normalize=0` or the whole mix comes out mysteriously quiet. Then run the mix through a limiter with the ceiling just under full scale (e.g. `alimiter=limit=0.95`, ≈ -0.4 dB) so it's loud without clipping.
|
||||
|
||||
---
|
||||
|
||||
## Quality Checklist
|
||||
|
||||
Before shipping:
|
||||
|
||||
- [ ] Every factual claim in the thread traces to a real review, result, or product fact (Grounded Inputs)
|
||||
- [ ] Script reads as real texting voice when read aloud — no marketing adjectives in bubbles
|
||||
- [ ] Brand name appears only after the peer asks
|
||||
- [ ] No sound on any typing indicator; receive SFX fires when the text bubble lands
|
||||
- [ ] SFX land exactly on bubble pops (spot-check first and last)
|
||||
- [ ] Every sent bubble had a full composer drive; typed text equals sent text
|
||||
- [ ] No micro-flicker anywhere in the chat — the only cut is chat → end card (300ms crossfade)
|
||||
- [ ] Promo code is link-underlined in its bubble and repeated on the end card
|
||||
- [ ] End card is static with the real logo SVG
|
||||
- [ ] Master is native 1080×1920; 1:1 variant is a crop, not a squeeze
|
||||
- [ ] Final bubble gets ~600–800ms of air before the crossfade
|
||||
- [ ] Audio is limited just under full scale (no clipping); music never fights the SFX
|
||||
|
||||
---
|
||||
|
||||
## Iterating the Format
|
||||
|
||||
Treat the thread as the variable and the pipeline as fixed. Test in this order — hook first, everything else after:
|
||||
|
||||
1. **Hook attachment** — the screenshot is the thumbnail and the first 2 seconds; it decides the scroll-stop
|
||||
2. **Angle** — result-flex vs. cancellation vs. inverse changes who the viewer identifies with
|
||||
3. **Code reveal phrasing** — "first pack's free with FREEPACK" vs. "FREEPACK gets you one free"
|
||||
4. **Peer persona** — name, avatar, and texting style shift the perceived audience
|
||||
5. **Length** — try a 12-bubble and an 8-bubble cut of the same script
|
||||
|
||||
The same architecture extends to further surfaces too — WhatsApp, Slack, a search box — same timeline-driven recording, different UI shell.
|
||||
|
||||
---
|
||||
|
||||
## Other iOS-Native Reveal Surfaces
|
||||
|
||||
Everything above about production (UI mockup → timeline-driven continuous recording → deterministic SFX cues → static end card), grounding, and disclosure carries over unchanged. What changes per surface is the *persuasion mechanic* and a handful of craft details.
|
||||
|
||||
| Surface | Persuasion mechanic | Reach for it when |
|
||||
|---|---|---|
|
||||
| **iMessage** | A friend's recommendation — social proof through dialogue | The product is discovered through results people share ("what app is that?") |
|
||||
| **ChatGPT** | An authoritative answer to the viewer's own question | The problem is question-shaped — something people would literally type into ChatGPT |
|
||||
| **Apple Notes** | A private confession made public — first-person, no dialogue | The angle is transformation or realization ("things nobody told me about 45") |
|
||||
|
||||
The strongest signal for choosing: which of these three surfaces already fills your audience's day. Recommendation products want iMessage; advice-seeking problems want ChatGPT; identity/transformation stories want Notes.
|
||||
|
||||
### ChatGPT Reveal
|
||||
|
||||
The viewer identifies with the *asker*. The typed question is the hook and must be the target customer's verbatim question — awkward phrasing and all ("why is my stomach so bloated all of a sudden at 47?"). The streaming answer names the problem's real mechanism, then the solution category; the brand lands in the answer's recommendation or in a typed follow-up ("what's the best one?").
|
||||
|
||||
**Craft details:**
|
||||
- **Stream the answer in word chunks**, not character-by-character (that's typing, not generation) and not whole paragraphs at once. A subtle tick underneath the stream and a clean stop when the response completes; no iMessage tritones anywhere.
|
||||
- **Type the question like thumbs, stream the answer like a model.** Two distinct rhythms — the contrast is what reads as "real ChatGPT."
|
||||
- **Keep the answer scannable:** short paragraphs, a bolded phrase or a short list, exactly the way ChatGPT actually formats. A wall of text breaks the illusion and loses the viewer.
|
||||
- OpenAI's interface is their trade dress — same legal-review posture as the Apple UI mimicry note above, with a generic "AI assistant" skin as the fallback.
|
||||
|
||||
**Compliance — stricter here than anywhere else in this family.** The "answer" is your ad copy wearing a lab coat: an authority costume. Every claim in it needs the same substantiation as a claim in your own voice, and the format's borrowed authority raises the bar, not lowers it. Do not put health, medical, or financial advice in a fabricated AI answer without legal review — that's the highest-risk version of this format. And never present the exchange as a real, unprompted ChatGPT output endorsing your product; it's a dramatization, same as the iMessage thread.
|
||||
|
||||
### Apple Notes Reveal
|
||||
|
||||
A different genre from the chat formats: **confession, not conversation.** The viewer watches someone type a private note — a list of realizations, a "things I wish I knew" entry — with the keyboard visible. The note's title is the hook and does the job slide 1 does in a carousel ("Things nobody told me about 45."). The product appears as one item in the list, named the way a person would actually write it to themselves — not the way a brand would.
|
||||
|
||||
**Craft details:**
|
||||
- **Audio is keyboard taps only.** No chat SFX, no receive tones — a note has no other party. A quiet music bed still works underneath.
|
||||
- **Type at real thumb pace with jitter**, same as the iMessage composer rule. One typo-and-correction reads as human; several read as staged.
|
||||
- **Get the Notes chrome right:** title styled larger than body, the formatting bar above the keyboard, iOS-yellow accents. Same HTML-mimicry approach — and the same Apple trade-dress review note and generic-notes-app fallback — as everything else here.
|
||||
- **Fit the note to the frame.** Write short enough that the whole note fits without scrolling, or scroll once, deliberately, late.
|
||||
- **First person or it doesn't work.** The moment the note reads like ad copy ("[Brand] changed everything!"), the intimacy that makes the format convert is gone. The product mention should be the *least* enthusiastic line in the note.
|
||||
|
||||
The grounding rule hits differently here: the confession is a dramatization of a *composite, true* customer story — pull the realizations from real reviews and interviews (the Grounded Inputs corpus), and keep any numbers or outcomes to documented ones.
|
||||
@@ -0,0 +1,126 @@
|
||||
# Motion-Style Video Ads (Faceless, Fully Generated)
|
||||
|
||||
> Format popularized by Borja ([@borjafat](https://x.com/borjafat)) and the open `super-video-maker` motion-collage recipe by [Bomx](https://github.com/Bomx/super-video-maker-skill); this guide is an original re-expression of the method, extended with a multi-style library and production lessons from building and shipping it end-to-end.
|
||||
|
||||
Produce a 15–45s faceless video ad or explainer from nothing but a concept: a styled
|
||||
poster still (image model) → brought to life with subtle motion (image-to-video model)
|
||||
→ narrated (TTS) → word-timed captions. No footage, no presenter, no editor. Cost per
|
||||
finished video is roughly $3–6 in API calls; wall-clock ~15 minutes.
|
||||
|
||||
The format works because the *still* carries the idea (one literal, slightly surreal
|
||||
visual per beat) and the *motion* only makes it breathe. Resist the urge to make the
|
||||
video do the storytelling — this is animated poster design, not filmmaking.
|
||||
|
||||
## When to use
|
||||
|
||||
- Concept/explainer ads: one idea made concrete ("your CRM is a junk drawer")
|
||||
- Top-of-funnel social video (9:16 Reels/Shorts/TikTok, 4:5 and 1:1 feed)
|
||||
- Brand-response hybrids where a distinctive owned style beats stock UGC
|
||||
- NOT for: demo/proof ads (screen recordings win), testimonial/UGC formats,
|
||||
anything requiring a real product shot as evidence
|
||||
|
||||
## Pipeline (provider-agnostic)
|
||||
|
||||
1. **Script** 3–6 beats, 20–45s of VO. One idea per beat. Calm and specific beats
|
||||
hype. End on a single CTA line.
|
||||
2. **Poster stills** — one per beat, using a *style formula* (below). Generate beat 1,
|
||||
approve it, then pass it as a reference image for every later beat so the set reads
|
||||
as one series. Fix garbled label text by regenerating with a shorter phrase.
|
||||
3. **Animate** each approved still with an image-to-video model (5–8s per beat).
|
||||
Motion belongs to the objects in the frame; the composition must not change.
|
||||
4. **VO + captions**: one continuous TTS take, transcribe with word timestamps
|
||||
(whisper), cut beats at sentence boundaries, burn 2–3-word caption groups.
|
||||
5. **Assemble**: concat beats trimmed to their VO spans (hold the last frame to pad),
|
||||
loudness-normalize to `I=-16:TP=-1.5:LRA=11`, export per-placement aspect.
|
||||
|
||||
**Provider options** (any combination works; the recipe is model-agnostic):
|
||||
|
||||
| Stage | One-key Gemini path | Alternatives |
|
||||
|---|---|---|
|
||||
| Stills | Nano Banana Pro (`gemini-3-pro-image-preview`) — excellent label typography | GPT-Image, Flux, Ideogram |
|
||||
| Motion | Veo 3.1 fast image-to-video (note: 1080p requires 8s clips) | Seedance 2.0 via fal.ai, Kling, Runway |
|
||||
| VO | Gemini TTS (calm voices: Charon/Kore) | ElevenLabs, OpenAI TTS |
|
||||
| Captions | whisper word timings + PIL/ASS burn-in | CapCut, platform auto-captions |
|
||||
|
||||
## The style library
|
||||
|
||||
Five proven looks. Each is a fill-in-the-slots prompt formula; keep ONE style per
|
||||
campaign so the account builds a recognizable visual identity. All five animate well.
|
||||
|
||||
### A. Screen-print collage (editorial, "In a Nutshell" docu energy)
|
||||
> Flat screen-print collage poster, single saturated `<COLOR>` background, subtle newsprint grain. Centerpiece: a black-and-white halftone cutout of `<SUBJECT DOING THE LITERAL CONCEPT>`, treated as a paper sticker with a thin white die-cut outline, slightly torn edges, and a soft drop shadow. Visible halftone dot texture, vintage editorial photo feel, grayscale subject. Accent cutouts: 2–4 flat shapes (cream circle sun, black zigzag, scattered dots). A torn-paper label near the bottom with the words "`<LABEL>`" in bold condensed uppercase newspaper type. Matte printed risograph aesthetic, limited palette. No gradients, no glow, no 3D, no photorealism, no extra text.
|
||||
|
||||
### B. Flat vector explainer (clean, techy, infinitely brandable)
|
||||
> Flat vector explainer illustration in the style of a premium animated science channel: a friendly simplified `<SUBJECT>`, bold flat shapes with clean rounded edges, solid `<BRAND COLOR>` background, limited palette of `<2-3 ACCENTS>`, flat geometric accents, soft long shadows, completely flat 2D design. A clean rectangular banner near the bottom reads "`<LABEL>`" in bold geometric sans-serif uppercase. No outlines, no 3D, no photorealism, no texture, no extra text.
|
||||
|
||||
### C. Papercraft diorama (warm, tactile, premium-crafty)
|
||||
> Layered papercraft diorama: `<SUBJECT>`, every element hand-cut from colored construction paper with visible paper thickness and real drop shadows between layers, `<COLOR>` paper background with cut-paper accents, tactile handmade craft feel with slightly imperfect scissor cuts. A cut-paper banner near the bottom reads "`<LABEL>`" in chunky cut-out paper letters. Soft studio lighting on the paper layers. No digital gradients, no photorealistic humans, no extra text.
|
||||
|
||||
### D. Pop-art comic (loud, scroll-stopping, promo-friendly)
|
||||
> Vintage pop-art comic panel: `<SUBJECT>`, bold black ink outlines, Ben-Day halftone dots shading, flat process colors (`<PALETTE>`), comic starburst accents, thick panel border, aged newsprint paper texture. A comic caption box near the bottom reads "`<LABEL>`" in bold comic lettering. 1960s printed comic aesthetic, slight ink misregistration. No 3D, no photorealism, no gradients, no extra text.
|
||||
|
||||
### E. Claymation (charming, high pattern-interrupt)
|
||||
> Stop-motion claymation scene: a charming handmade plasticine `<SUBJECT>`, visible fingerprints and clay texture, `<COLOR>` clay backdrop and floor, chunky clay props, warm soft studio lighting like a stop-motion film set, shallow depth of field. A small clay sign near the bottom reads "`<LABEL>`" in hand-molded clay letters. Handcrafted miniature feel. No 2D illustration, no photorealistic humans, no extra text.
|
||||
|
||||
## Brand-flexible styles (token-driven)
|
||||
|
||||
The five looks above are *characterful* — they impose their own palette. This second
|
||||
tier is *brand-first*: each style is defined by *slots*, so any company's tokens drop
|
||||
in and the output reads as that brand's own design system.
|
||||
|
||||
**The brand slots contract.** Before generating, resolve these from the brand's
|
||||
guidelines (or `.agents/product-marketing.md`):
|
||||
|
||||
- `FIELD` — the neutral ground (brand white/off-white, or brand dark)
|
||||
- `INK` — the drawing/type color (brand gray/charcoal, near-black)
|
||||
- `ACCENT` — ONE brand color or gradient, used sparingly (a rule, a beam, a square)
|
||||
- `TYPE FEEL` — the brand's typographic voice ("clean modern grotesque sans", "geometric sans", "mono captions")
|
||||
- Any per-brand constraints (e.g. "gradients only on borders/edges, never fills")
|
||||
|
||||
Keep the accent genuinely scarce — one element per frame. Scarcity is what makes
|
||||
these read as designed rather than generated.
|
||||
|
||||
### F. Monoline editorial (the most universally brandable)
|
||||
> Minimal editorial monoline illustration poster: `<SUBJECT>`, drawn entirely in elegant thin single-weight `<INK>` lines on a clean `<FIELD>` background, the style of a premium tech company blog illustration. Sparse composition with generous whitespace, a few small monoline accent details, and ONE restrained `<ACCENT>` element: `<a thin accent underline sweep / a small accent arc>`. A small caption near the bottom reads "`<LABEL>`" in `<TYPE FEEL>`, `<INK>`, letterspaced uppercase, with a thin `<ACCENT>` underline. Precise, technical, refined. No fills except the single accent, no gradients, no 3D, no photorealism, no texture, no extra text.
|
||||
|
||||
### G. Swiss typographic (type IS the visual — any brand with a font and a color)
|
||||
> Swiss International Typographic Style poster: the words "`<LABEL>`" set enormous in a bold `<TYPE FEEL>`, `<INK>` on a `<FIELD>` background, filling the upper two thirds with tight leading and cropped edges. A small black-and-white photographic cutout of `<SUBJECT>` sits on a thin baseline grid in the lower third, aligned to an asymmetric grid with one thin `<ACCENT>` rule line and a small `<ACCENT>` square as the only color. Visible faint grid lines, precise margins, mathematical composition. Flat, printed, matte. No gradients, no 3D, no decoration, no extra text beyond the label and one small letterspaced caption line.
|
||||
|
||||
### H. Wireglow (dark keynote — dev-tool / dark-mode brands)
|
||||
> Dark minimal tech-keynote poster: `<SUBJECT>` rendered as an elegant thin light-gray wireframe line drawing on a near-black `<FIELD>` background with subtle film grain. From `<the focal object>` emanates a soft narrow beam of glowing `<ACCENT>` gradient light, the only color, feathered and atmospheric. Faint thin concentric geometric guide circles. A caption near the bottom reads "`<LABEL>`" in `<TYPE FEEL>`, light gray, letterspaced uppercase, with a hairline gradient rule beneath it. Restrained, premium, technical. No photorealism, no 3D render look, no busy elements, no extra text.
|
||||
|
||||
### I. Duotone screenprint (photo brands — editorial punch from two tokens)
|
||||
> Bold duotone screenprint photo poster: a dramatic photograph of `<SUBJECT>`, reproduced as a two-color screenprint — `<INK>` for the shadows and `<ACCENT>` for the highlights — on an off-white `<FIELD>` paper background with visible coarse halftone grain and slight ink misregistration. Strong diagonal composition, the figure large and cropped. A wide solid `<INK>` bar near the bottom carries the words "`<LABEL>`" reversed out in bold condensed `<TYPE FEEL>` uppercase, with a small `<ACCENT>` square bullet. Editorial poster energy, matte printed feel. No gradients beyond the duotone, no 3D, no extra text.
|
||||
|
||||
**Motion notes for this tier**: F/G animate as drawing motions (lines extend, the accent
|
||||
sweep draws itself, type settles by a few pixels); H animates as beam pulse + slow
|
||||
wireframe rotation feel; I as grain shimmer + slow push. Same hard rules apply — motion
|
||||
belongs to existing elements, composition never changes.
|
||||
|
||||
## Motion prompt formula
|
||||
|
||||
> Subtle living-`<style>` motion of the existing elements only. `<ONE literal motion tied to the concept: the pile inflates / the arrow creeps higher / the megaphone trembles with each shout>`. `<Secondary ambient motion: accents drift, gentle push-in>`. Every element that is visible now is the only thing that ever appears; the composition stays exactly as it is. Everything stays `<style descriptor: a flat printed collage / flat 2D vector / cut paper / printed comic / handmade clay>`. No camera whip, no scene change, no morphing, no added text.
|
||||
|
||||
## Hard-earned gotchas
|
||||
|
||||
- **Video models love adding photoreal "maker hands"** reaching into frame, especially
|
||||
on pressing/handling motions — and *negative prompts make it worse* ("no hands" is an
|
||||
attention trap). Never mention hands; describe motion as belonging to the objects,
|
||||
and include "the composition stays exactly as it is."
|
||||
- **Always QC each clip's final 2 seconds** — that's where intruding objects and style
|
||||
drift appear. Trim before them or regenerate; never ship a "realified" frame.
|
||||
- **One dominant motion per beat.** Two motions read as chaos at feed speed.
|
||||
- **TTS + whisper disagree on sound-alikes** ("laws" → "loss"). Read the transcript
|
||||
against the script before burning captions; prefer phoneme-unambiguous CTA wording.
|
||||
- **Keep captions clear of the label band** (captions ~60% height, label ~80%).
|
||||
Clamp caption groups so two never overlap; shrink-to-fit long groups.
|
||||
- **Ad-specific**: put the brand/label in the poster itself (it survives sound-off
|
||||
autoplay), front-load the concept in beat 1 (the 3-second hook is the poster), and
|
||||
export 9:16 + 4:5 + 1:1 from the same beats by regenerating stills per aspect
|
||||
rather than cropping.
|
||||
|
||||
## Compliance
|
||||
|
||||
Fully synthetic characters — no likeness/UGC disclosure issues, but check platform
|
||||
AI-content disclosure requirements (Meta and TikTok label AI-generated media).
|
||||
Don't fabricate statistics or testimonials in the VO; ground every claim.
|
||||
@@ -0,0 +1,200 @@
|
||||
# Static Ad Template Library
|
||||
|
||||
Fifteen structural templates for static (image) ad creative. Each is a layout framework with slots for brand-specific copy — the structure is proven; the inputs make it yours.
|
||||
|
||||
Use these when generating static ad concepts at volume (Meta, Instagram, LinkedIn, display). Cycle through **all** templates rather than clustering on 2-3 favorites: template diversity is angle diversity, and the winner is usually not the one you'd have picked by hand.
|
||||
|
||||
## How to Use This Library
|
||||
|
||||
1. **Ground first.** Read the inputs corpus (winning ads, reviews, ad comments, brand voice) before generating anything. See "Grounded Inputs" in SKILL.md.
|
||||
2. **Cycle templates.** For a batch of N concepts, spread across all 15 templates (3-4 variations each for a 50-concept batch).
|
||||
3. **Fill slots from source material.** Every variation pulls its copy from a real review, a winning ad pattern, or an ad comment — and cites which one.
|
||||
4. **Write the visual description.** Each concept includes enough visual direction that a designer or image-generation tool can produce it without guessing.
|
||||
|
||||
## Generation Rules
|
||||
|
||||
- Every variation must include: **template name, headline copy, body copy, visual description, source grounding**
|
||||
- Source grounding = which review, winning ad, or comment this concept is based on
|
||||
- Never produce a variation without source grounding — no invented claims, stats, or testimonials
|
||||
- Pull copy directly from customer language whenever possible; don't paraphrase reviews into marketing-speak
|
||||
- Match the brand voice doc on tone, not generic direct-response voice
|
||||
- Real names, real stats, real quotes only — fabricated social proof is a compliance and trust violation
|
||||
|
||||
---
|
||||
|
||||
## The 15 Templates
|
||||
|
||||
### 1. Headline Statement
|
||||
|
||||
Bold one-line claim. Single product hero shot. Minimal background. The headline does all the work.
|
||||
|
||||
- **Structure**: One dominant text line (60%+ of visual weight), product image, logo small
|
||||
- **Copy slot**: One claim specific enough to stop the scroll
|
||||
- **DTC example**: "The last greens powder you'll ever buy."
|
||||
- **SaaS example**: "Close your books in 3 days, not 3 weeks."
|
||||
- **Source it from**: Your strongest winning-ad hook or the most repeated benefit in reviews
|
||||
|
||||
### 2. Us vs. Them
|
||||
|
||||
Side-by-side comparison. Competitor or "old way" on the left (grayed out), your product on the right (full color). 4-6 comparison rows.
|
||||
|
||||
- **Structure**: Two columns, check/cross marks per row, your side visually alive
|
||||
- **Copy slot**: Comparison rows — each row a real differentiator, not filler
|
||||
- **DTC example**: "Their multivitamin: 13 ingredients. Ours: 60."
|
||||
- **SaaS example**: "Spreadsheets: 6 hours a week. Us: 6 minutes."
|
||||
- **Source it from**: Reviews that mention switching, or comments comparing you to a competitor
|
||||
|
||||
### 3. Stat Callout
|
||||
|
||||
One dominant number takes up 60% of the visual. Supporting context below.
|
||||
|
||||
- **Structure**: Giant stat, one line of context, product or logo anchor
|
||||
- **Copy slot**: A real, defensible number — measurement beats superlative
|
||||
- **DTC example**: "97% of users feel a difference in 14 days."
|
||||
- **SaaS example**: "11 hours saved per rep, per week."
|
||||
- **Source it from**: Case studies, product analytics, or survey data — never invent the number
|
||||
|
||||
### 4. Review Card
|
||||
|
||||
A five-star testimonial styled as a screenshotted product review. Reviewer name, star rating, date.
|
||||
|
||||
- **Structure**: Looks like a native review UI (G2, Trustpilot, Amazon, App Store — match where your buyers read reviews)
|
||||
- **Copy slot**: A real review, verbatim — the artifact's credibility is its realism
|
||||
- **DTC example**: A Trustpilot card: "I've tried 6 of these. This is the only one I reordered."
|
||||
- **SaaS example**: A G2-styled card: "Killed 4 tools and replaced them with this."
|
||||
- **Source it from**: `inputs/reviews/` verbatim — with permission where the platform requires it
|
||||
|
||||
### 5. Testimonial Stack
|
||||
|
||||
Three customer quotes arranged vertically, photo + name + one-line quote each.
|
||||
|
||||
- **Structure**: Three short rows; quotes must be scannable in 2 seconds each
|
||||
- **Copy slot**: Three quotes covering *different* objections or benefits — not the same praise three times
|
||||
- **DTC example**: Three customers on results, taste, and convenience
|
||||
- **SaaS example**: Three roles (IC, manager, exec) each praising their own outcome
|
||||
- **Source it from**: Reviews — pick for coverage, not just enthusiasm
|
||||
|
||||
### 6. Before / After
|
||||
|
||||
Split image with arrow between. Transformation framing — product results, workflow, or visual proof.
|
||||
|
||||
- **Structure**: Two panels, arrow or divider, minimal copy labeling each state
|
||||
- **Copy slot**: Label the states in the customer's words ("Sunday-night spreadsheet dread" → "Reports send themselves")
|
||||
- **DTC example**: Skin, energy, space — the classic visual transformation
|
||||
- **SaaS example**: Cluttered 6-tab workflow → one clean dashboard
|
||||
- **Compliance note**: Before/after claims are regulated in health, finance, and beauty — verify platform policy before using
|
||||
- **Source it from**: Transformation language in reviews ("I used to X, now I Y")
|
||||
|
||||
### 7. Problem / Solution
|
||||
|
||||
Pain point on top (text or image), product as the answer below.
|
||||
|
||||
- **Structure**: Two zones — tension above, relief below
|
||||
- **Copy slot**: The pain in the customer's exact words, then the product's one-line answer
|
||||
- **DTC example**: "Tired of 6 supplements every morning?" → one scoop visual
|
||||
- **SaaS example**: "Your CRM knows nothing about product usage." → integration screenshot
|
||||
- **Source it from**: The most common pain phrasing in `inputs/reviews/` — verbatim beats paraphrase
|
||||
|
||||
### 8. Founder Message
|
||||
|
||||
Handwritten-style or plain-text note from the founder. Conversational, personal tone.
|
||||
|
||||
- **Structure**: Note-style layout, founder name/photo, no product glamour shot
|
||||
- **Copy slot**: "I built this because..." — one honest paragraph, no marketing polish
|
||||
- **DTC example**: "Hey — I made this because every 'healthy' snack was secretly candy."
|
||||
- **SaaS example**: "I ran RevOps for 6 years. This is the tool I kept wishing existed."
|
||||
- **Source it from**: The actual founding story — this template collapses if fabricated
|
||||
|
||||
### 9. Feature Spotlight (Ingredient Spotlight)
|
||||
|
||||
Product hero in the center, 4-6 callout boxes around the edges highlighting key components.
|
||||
|
||||
- **Structure**: Center image, radiating callouts, each callout 3-6 words
|
||||
- **Copy slot**: The components buyers actually ask about — not your full feature list
|
||||
- **DTC example**: Product bottle with callouts per key ingredient and what it does
|
||||
- **SaaS example**: Dashboard screenshot with callouts on the 4 features reviews mention most
|
||||
- **Source it from**: Which features/ingredients appear most in reviews and comments
|
||||
|
||||
### 10. Press Mention
|
||||
|
||||
"As seen in" with publication logos and a pull quote.
|
||||
|
||||
- **Structure**: Logo row + one strong quote + product anchor
|
||||
- **Copy slot**: A real quote from real coverage
|
||||
- **DTC example**: "The category's first genuinely new idea in years." — [publication]
|
||||
- **SaaS example**: Analyst or industry-newsletter quote with the outlet's logo
|
||||
- **Compliance note**: Only use logos of outlets that actually covered you; check their logo-usage terms
|
||||
- **Source it from**: Actual press, podcasts, newsletters, or analyst mentions
|
||||
|
||||
### 11. Lifestyle Hero
|
||||
|
||||
Product in use in a real environment. Minimal copy. Aspirational, not salesy.
|
||||
|
||||
- **Structure**: One photograph does the work; a short line and logo at most
|
||||
- **Copy slot**: 5-8 words, identity-flavored ("Mornings, handled.")
|
||||
- **DTC example**: Product on a kitchen counter mid-routine
|
||||
- **SaaS example**: The tool on-screen in a real work moment (standup, close call, ship day)
|
||||
- **Source it from**: Winning ads' visual patterns; identity language in reviews
|
||||
|
||||
### 12. Numbered List
|
||||
|
||||
"5 reasons [audience] are switching to [brand]." Icons next to each point.
|
||||
|
||||
- **Structure**: Numbered rows, icon + short line each, product anchor at bottom
|
||||
- **Copy slot**: Each reason a distinct angle — pain, outcome, proof, differentiator, price
|
||||
- **DTC example**: "5 reasons runners switched to [brand] this year"
|
||||
- **SaaS example**: "4 reasons finance teams are leaving [legacy tool]"
|
||||
- **Source it from**: Aggregate the most common switching reasons across reviews
|
||||
|
||||
### 13. FAQ Card
|
||||
|
||||
A common objection as the question, answered directly.
|
||||
|
||||
- **Structure**: Question prominent, answer concise, product anchor
|
||||
- **Copy slot**: The objection *as customers phrase it* — the recognition is the hook
|
||||
- **DTC example**: "But does it work for sensitive skin? Yes — and here's why."
|
||||
- **SaaS example**: "Will this survive our security review? SOC 2 Type II, SSO, EU hosting."
|
||||
- **Source it from**: `inputs/comments/` — the objections people post publicly under your ads
|
||||
|
||||
### 14. Competitor Callout
|
||||
|
||||
Name a specific competitor (or the category default) and explain the difference. Bold but factual.
|
||||
|
||||
- **Structure**: Their name vs. yours, one clear axis of difference
|
||||
- **Copy slot**: A difference you can defend with facts — comparative claims invite scrutiny
|
||||
- **DTC example**: "Like [competitor], minus the 14g of sugar."
|
||||
- **SaaS example**: "[Competitor] charges per seat. We don't."
|
||||
- **Compliance note**: Comparative advertising must be truthful and substantiatable; some platforms restrict naming competitors
|
||||
- **Source it from**: Competitor mentions in reviews and comments — customers name the alternative for you
|
||||
|
||||
### 15. Origin Story
|
||||
|
||||
Founder photo with the why-we-built-this narrative. Longer copy than other formats.
|
||||
|
||||
- **Structure**: Portrait or team photo, 2-3 short paragraphs, product secondary
|
||||
- **Copy slot**: The specific moment or frustration that started it — specificity is the credibility
|
||||
- **DTC example**: "We spent 2 years and 47 batches getting this right. Here's why."
|
||||
- **SaaS example**: "We were the customer. The tool we needed didn't exist, so we built it."
|
||||
- **Source it from**: The real story — pairs with warm/retargeting audiences better than cold
|
||||
|
||||
---
|
||||
|
||||
## Per-Concept Output Format
|
||||
|
||||
Each generated concept follows this structure:
|
||||
|
||||
```markdown
|
||||
## Concept [N]: [Template Name]
|
||||
|
||||
**Headline**: [the headline copy]
|
||||
**Body**: [supporting copy, if the template uses it]
|
||||
**Visual**: [layout description specific enough to design or generate from]
|
||||
**Image prompt**: [prompt for the image tool, if generating — see generative-tools.md]
|
||||
**Grounded in**: [which review / winning ad / comment this traces to, quoted or named]
|
||||
```
|
||||
|
||||
For a batch, add an `INDEX.md` listing every concept with its template type and grounding source, so the reviewer can scan 50 concepts in two minutes.
|
||||
|
||||
## Batch Distribution
|
||||
|
||||
For a standard 50-concept batch: 3-4 variations per template across all 15. If performance data shows certain templates consistently winning for this brand, shift to 60% proven templates / 40% full-cycle coverage — but never drop coverage to zero. Fatigue is why you're generating daily; the template that's tired next month is the one you're scaling today.
|
||||
@@ -0,0 +1,487 @@
|
||||
---
|
||||
name: ads
|
||||
description: "When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X, or other ad platforms. Also use when the user mentions 'PPC,' 'paid media,' 'ROAS,' 'CPA,' 'ad campaign,' 'retargeting,' 'audience targeting,' 'Google Ads,' 'Facebook ads,' 'LinkedIn ads,' 'ad budget,' 'cost per click,' 'ad spend,' 'should I run ads,' 'ABM,' 'account-based marketing,' 'B2B ads,' 'lead quality,' 'negative keywords,' 'Performance Max,' 'thought leader ads,' or 'when should I kill an ad.' Use this for campaign strategy, audience targeting, bidding, and optimization. For bulk ad creative generation and iteration, see ad-creative. For landing page optimization, see cro."
|
||||
metadata:
|
||||
version: 2.2.0
|
||||
---
|
||||
|
||||
# Paid Ads
|
||||
|
||||
You are an expert performance marketer with direct access to ad platform accounts. Your goal is to help create, optimize, and scale paid advertising campaigns that drive efficient customer acquisition.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Campaign Goals
|
||||
- What's the primary objective? (Awareness, traffic, leads, sales, app installs)
|
||||
- What's the target CPA or ROAS?
|
||||
- What's the monthly/weekly budget?
|
||||
- Any constraints? (Brand guidelines, compliance, geographic)
|
||||
|
||||
### 2. Product & Offer
|
||||
- What are you promoting? (Product, free trial, lead magnet, demo)
|
||||
- What's the landing page URL?
|
||||
- What makes this offer compelling?
|
||||
|
||||
### 3. Audience
|
||||
- Who is the ideal customer?
|
||||
- What problem does your product solve for them?
|
||||
- What are they searching for or interested in?
|
||||
- Do you have existing customer data for lookalikes?
|
||||
|
||||
### 4. Current State
|
||||
- Have you run ads before? What worked/didn't?
|
||||
- Do you have existing pixel/conversion data?
|
||||
- What's your current funnel conversion rate?
|
||||
|
||||
---
|
||||
|
||||
## Reference Routing
|
||||
|
||||
This skill's depth lives in references — load by intent. For **any operational decision on a live account** (kill/keep/scale/budget), load the relevant playbook before answering; the thresholds live there, not here.
|
||||
|
||||
| User intent | Load | Covers |
|
||||
|---|---|---|
|
||||
| B2B strategy, funnel stages, budget splits, kill rules, lead quality, breakeven math | [b2b-paid-playbook.md](references/b2b-paid-playbook.md) | Demand lifecycle, leading/lagging signals, kill rules, offline conversion loop, U/B/F lead scoring, scaling quadrant |
|
||||
| Meta operations: when to kill/graduate/scale an ad, fatigue, testing structure | [meta-decision-system.md](references/meta-decision-system.md) | TCPL-anchored decision tree, ad-count ceiling, 80/20 CBO structure, fatigue bands, lead forms, Advantage+ transition |
|
||||
| LinkedIn operations: bidding, audience sizing, scaling, benchmarks, TLAs, formats | [linkedin-b2b-playbook.md](references/linkedin-b2b-playbook.md) | Bidding progression, penetration scaling, sizing rules, funnel benchmarks, document/conversation ads, audit shortlist |
|
||||
| Google Search: what to spend on first, structure, match types, negatives, PMax | [google-search-playbook.md](references/google-search-playbook.md) | Intent ladder, account structure, match-type gates, negatives, bidding by volume, offline conversions, PMax guardrails |
|
||||
| Named-account targeting, pipeline acceleration, cross-channel retargeting | [abm-playbook.md](references/abm-playbook.md) | LinkedIn/Meta ABM, list mechanics, acceleration campaigns, UTM cross-channel remarketing, ABM measurement |
|
||||
| Generating Google RSAs | [rsa-output-spec.md](references/rsa-output-spec.md) | Mandatory output spec — limits, sidecars, template, self-check |
|
||||
| Audience setup, tracking setup, launch checklists, copy formulas | [audience-targeting.md](references/audience-targeting.md) · [conversion-tracking.md](references/conversion-tracking.md) · [platform-setup-checklists.md](references/platform-setup-checklists.md) · [ad-copy-templates.md](references/ad-copy-templates.md) | Existing foundations |
|
||||
|
||||
---
|
||||
|
||||
## Platform Selection Guide
|
||||
|
||||
| Platform | Best For | Use When |
|
||||
|----------|----------|----------|
|
||||
| **Google Ads** | High-intent search traffic | People actively search for your solution |
|
||||
| **Meta** | Demand generation, visual products | Creating demand, strong creative assets |
|
||||
| **LinkedIn** | B2B, decision-makers | Job title/company targeting matters, higher price points |
|
||||
| **Twitter/X** | Tech audiences, thought leadership | Audience is active on X, timely content |
|
||||
| **TikTok** | Younger demographics, viral creative | Audience skews 18-34, video capacity |
|
||||
|
||||
---
|
||||
|
||||
## Campaign Structure Best Practices
|
||||
|
||||
### Account Organization
|
||||
|
||||
```
|
||||
Account
|
||||
├── Campaign 1: [Objective] - [Audience/Product]
|
||||
│ ├── Ad Set 1: [Targeting variation]
|
||||
│ │ ├── Ad 1: [Creative variation A]
|
||||
│ │ ├── Ad 2: [Creative variation B]
|
||||
│ │ └── Ad 3: [Creative variation C]
|
||||
│ └── Ad Set 2: [Targeting variation]
|
||||
└── Campaign 2...
|
||||
```
|
||||
|
||||
### Naming Conventions
|
||||
|
||||
```
|
||||
[Platform]_[Objective]_[Audience]_[Offer]_[Date]
|
||||
|
||||
Examples:
|
||||
META_Conv_Lookalike-Customers_FreeTrial_2024Q1
|
||||
GOOG_Search_Brand_Demo_Ongoing
|
||||
LI_LeadGen_CMOs-SaaS_Whitepaper_Mar24
|
||||
```
|
||||
|
||||
### Budget Allocation
|
||||
|
||||
**Testing phase (first 2-4 weeks):**
|
||||
- 70% to proven/safe campaigns
|
||||
- 30% to testing new audiences/creative
|
||||
|
||||
**Scaling phase:**
|
||||
- Consolidate budget into winning combinations
|
||||
- Increase budgets ~20% at a time — never 30%+ in one move (resets platform learning)
|
||||
- Wait 3-5 days between increases for algorithm learning
|
||||
|
||||
---
|
||||
|
||||
## Ad Copy Frameworks
|
||||
|
||||
### Key Formulas
|
||||
|
||||
**Problem-Agitate-Solve (PAS):**
|
||||
> [Problem] → [Agitate the pain] → [Introduce solution] → [CTA]
|
||||
|
||||
**Before-After-Bridge (BAB):**
|
||||
> [Current painful state] → [Desired future state] → [Your product as bridge]
|
||||
|
||||
**Social Proof Lead:**
|
||||
> [Impressive stat or testimonial] → [What you do] → [CTA]
|
||||
|
||||
**For detailed templates and headline formulas**: See [references/ad-copy-templates.md](references/ad-copy-templates.md)
|
||||
|
||||
---
|
||||
|
||||
## Audience Understanding & Targeting
|
||||
|
||||
Knowing your audience deeply is still the highest-leverage work in paid ads — demographics, job titles, pain points, fears, hopes, the exact language they use, who they follow, what they've tried, why they failed, what they buy. **Gather every identifier you can.**
|
||||
|
||||
What's changed in 2026 is **where you apply that knowledge.** As ad-platform algorithms have gotten dramatically better at finding the right person, jamming all your audience identifiers into the platform's *targeting filters* underperforms feeding those same identifiers into the *creative* (headlines, copy, visuals, hooks, examples).
|
||||
|
||||
The discipline now: **audience knowledge → creative first, targeting filters second.** How much that ratio tips toward "creative" varies meaningfully by platform.
|
||||
|
||||
### Platform-by-platform: where to apply audience knowledge
|
||||
|
||||
| Platform | Audience knowledge → creative | Audience knowledge → targeting filters | Notes |
|
||||
|----------|------------------------------|-------------------------------------|-------|
|
||||
| **Meta** (post-Andromeda) | **80%+** | 20% | Algorithm rewards broad + specific creative. See [[#Modern Meta playbook (Andromeda era — 2026+)]] below for the full reframe. Interest-stacking now actively hurts. |
|
||||
| **Google Search** | 40% | **60%** | Keywords are still the dominant signal — match-types, search-intent layering, and negative keywords still drive performance. Creative (RSA headlines) matters but is downstream of the keyword. |
|
||||
| **Google Performance Max / Demand Gen** | **70%** | 30% | Audience signals are advisory, not deterministic. Creative + product feed quality dominate. |
|
||||
| **LinkedIn** | 40% | **60%** | Job-title / company / industry filters still produce real precision because LinkedIn's identity data is high-quality. Creative makes the click; firmographics make the *right person* see it. |
|
||||
| **TikTok** | **70%** | 30% | Algorithm is closer to Meta's model — broad targeting + native-feeling creative wins. Some audience interests help but creative dominates. |
|
||||
| **Twitter/X** | 50% | 50% | Interest + follower targeting still meaningful, but creative differentiation is high-leverage given lower competition. |
|
||||
|
||||
These ratios are directional, not precise. Test in your actual account.
|
||||
|
||||
### Applying audience knowledge to creative
|
||||
|
||||
Once you've gathered audience identifiers, here's how to put each kind into the creative:
|
||||
|
||||
- **Demographic identifiers** (age, location, occupation) → embed as identity-trigger keywords in headlines (see [[#The one-keyword hack (identity-trigger keywords)]])
|
||||
- **Pain points + fears** → headline + first line of body copy (Sabri Suby's framing: "the verbatim words your customers use about the problem")
|
||||
- **Hopes / desired outcomes** → transformation copy + CTAs
|
||||
- **Objections + "why they didn't buy last time"** → objection-handling retargeting ads (see [[#The 4-component retargeting framework]])
|
||||
- **Their language / vocabulary** → the entire copy voice — never use industry jargon they don't
|
||||
- **Existing customer base** → still feed it for lookalike audiences (see Key Concepts below)
|
||||
- **Niche / segment they identify with** → identity-trigger keywords in headline ("for dentists" / "for B2B founders" / "for parents of toddlers")
|
||||
|
||||
### Key Concepts (still apply)
|
||||
|
||||
- **Lookalikes**: Base on best customers (by LTV), not all customers. Still high-value across platforms.
|
||||
- **Retargeting**: Segment by funnel stage (visitors vs. cart abandoners). See [[#Retarget with DIFFERENT offers (not the same one)]] and [[#The 4-component retargeting framework]] for the modern playbook.
|
||||
- **Exclusions**: Exclude existing customers and recent converters — showing ads to people who already bought wastes spend.
|
||||
|
||||
### Common failure mode
|
||||
|
||||
Trying to make up for weak creative with hyper-precise targeting. If your creative is generic but you stack 12 interests + 3 demographic filters + a custom audience, what you've built is a small audience that all see a bad ad. Better: gather the same audience identifiers, write 5 creative variants that each speak to a different segment, target broadly, let the algorithm match each creative to the right segment.
|
||||
|
||||
**For detailed targeting strategies by platform**: See [references/audience-targeting.md](references/audience-targeting.md)
|
||||
|
||||
---
|
||||
|
||||
## Modern Meta playbook (Andromeda era — 2026+)
|
||||
|
||||
Meta launched the **Andromeda** algorithm in 2025, which fundamentally changed Meta ads. The old playbook (interest stacking, polished video creative, single-winner scaling) underperforms. The new playbook:
|
||||
|
||||
### Creative volume is the constraint (statics > polished video)
|
||||
- Andromeda is "a hungry panda" — it needs constant fresh creative or it fatigues
|
||||
- **Statics often outperform video in 2026** because:
|
||||
- Meta's algorithm has a bias toward statics — it can show more statics per session per user, so they're cheaper to deliver
|
||||
- Static creative is 10x cheaper and faster to produce than video, enabling the volume Andromeda needs
|
||||
- Even top advertisers running 17+ VSLs report that down-and-dirty native statics often beat 2.5-month-production VSLs
|
||||
- **Dedicate 1 hour per week** to producing fresh creatives for your winning offer. Volume > polish.
|
||||
|
||||
### Creative IS the targeting (broad audience + specific creative)
|
||||
- The old playbook: stack interests, narrow the audience, hope to find the right buyer
|
||||
- The new playbook: target broadly (just the country) and let the creative do the targeting
|
||||
- **Long-form ad copy works better than short-form** in 2026 — gives Meta a wider context window to understand who to show the ad to
|
||||
- Test it: take your best winning ad with interest-stacked targeting, duplicate it, remove all targeting (just pick the country), run side-by-side for 7 days. Check CPAs. Broad typically wins.
|
||||
|
||||
### The one-keyword hack (identity-trigger keywords)
|
||||
- Take your winning ad
|
||||
- Duplicate it with a niche/identity keyword inserted in the headline or body copy
|
||||
- *"Here's how to get 462 leads per week on autopilot"* → *"Here's how to get 462 **dental** leads per week on autopilot"* / *"...**lawyer** leads..."* / *"...**property investment** leads..."*
|
||||
- The keyword is an **identity trigger** for the viewer AND a targeting signal for Andromeda
|
||||
- Dramatically drops CPL and opens audience pockets you couldn't reach with a generic ad
|
||||
|
||||
### AI variant farming (the 100-people test)
|
||||
- Take your winning ad
|
||||
- Feed to Claude/ChatGPT/Kong with the prompt:
|
||||
> *"I want you to read this ad and be the author. If I show the next ad I'm going to ask you to write to 100 people, not 1 in 100 would be able to tell you it's written by a different person. Now write this for [demographic/niche]."*
|
||||
- The output should read essentially the same with subtle relevance shifts for the target
|
||||
- Apply in sequence: body copy → headlines → creative
|
||||
- Drop all variants in a CBO, let Meta's AI allocate spend
|
||||
|
||||
### Zombie campaigns
|
||||
- After running a CBO, Meta will give 80% of variants no spend
|
||||
- Take the dead variants you have **high conviction** about
|
||||
- Launch them in a separate ad set ("zombie campaign")
|
||||
- Typically resurrects 20% as winners that Meta's first allocation passed over
|
||||
|
||||
### Don't make ads look like ads
|
||||
- Hundreds of millions of people have ad blockers — the polished-ad aesthetic kills performance
|
||||
- Study what content **natively performs** in your niche on TikTok/Instagram/YouTube → produce ads that match that aesthetic
|
||||
- **Burner account technique:** create a clean Instagram/TikTok account, follow all influencers and pages in your niche, like their content. Your feed becomes a curated view of what's natively winning. Produce ads that match.
|
||||
- If you have an organic video with millions of views, **run that exact video as a paid ad** — proven content + paid distribution = the highest-leverage move
|
||||
|
||||
## Creative Best Practices
|
||||
|
||||
### Image Ads
|
||||
- Clear product screenshots showing UI
|
||||
- Before/after comparisons
|
||||
- Stats and numbers as focal point
|
||||
- Human faces (real, not stock)
|
||||
- Bold, readable text overlay (keep under 20%)
|
||||
|
||||
### Video Ads Structure (15-30 sec)
|
||||
1. Hook (0-3 sec): Pattern interrupt, question, or bold statement
|
||||
2. Problem (3-8 sec): Relatable pain point
|
||||
3. Solution (8-20 sec): Show product/benefit
|
||||
4. CTA (20-30 sec): Clear next step
|
||||
|
||||
**Production tips:**
|
||||
- Captions always (85% watch without sound)
|
||||
- Vertical for Stories/Reels, square for feed
|
||||
- Native feel outperforms polished
|
||||
- First 3 seconds determine if they watch
|
||||
|
||||
### Creative Testing Hierarchy
|
||||
1. Concept/angle (biggest impact)
|
||||
2. Hook/headline
|
||||
3. Visual style
|
||||
4. Body copy
|
||||
5. CTA
|
||||
|
||||
---
|
||||
|
||||
## Campaign Optimization
|
||||
|
||||
For hard kill/keep/scale thresholds, use the platform playbooks (see Reference Routing): the kill rules and breakeven CPL/CPC math live in [b2b-paid-playbook.md](references/b2b-paid-playbook.md), and Meta's full decision tree lives in [meta-decision-system.md](references/meta-decision-system.md).
|
||||
|
||||
### Key Metrics by Objective
|
||||
|
||||
| Objective | Primary Metrics |
|
||||
|-----------|-----------------|
|
||||
| Awareness | CPM, Reach, Video view rate |
|
||||
| Consideration | CTR, CPC, Time on site |
|
||||
| Conversion | CPA, ROAS, Conversion rate |
|
||||
|
||||
### Optimization Levers
|
||||
|
||||
**If CPA is too high:**
|
||||
1. Check landing page (is the problem post-click?)
|
||||
2. Tighten audience targeting
|
||||
3. Test new creative angles
|
||||
4. Improve ad relevance/quality score
|
||||
5. Adjust bid strategy
|
||||
|
||||
**If CTR is low:**
|
||||
- Creative isn't resonating → test new hooks/angles
|
||||
- Audience mismatch → refine targeting
|
||||
- Ad fatigue → refresh creative
|
||||
|
||||
**If CPM is high:**
|
||||
- Audience too narrow → expand targeting
|
||||
- High competition → try different placements
|
||||
- Low relevance score → improve creative fit
|
||||
|
||||
### Bid Strategy Progression
|
||||
1. Start with manual or cost caps
|
||||
2. Gather conversion data (50+ conversions)
|
||||
3. Switch to automated with targets based on historical data
|
||||
4. Monitor and adjust targets based on results
|
||||
|
||||
---
|
||||
|
||||
## Retargeting Strategies
|
||||
|
||||
### Funnel-Based Approach
|
||||
|
||||
| Funnel Stage | Audience | Message | Goal |
|
||||
|--------------|----------|---------|------|
|
||||
| Top | Blog readers, video viewers | Educational, social proof | Move to consideration |
|
||||
| Middle | Pricing/feature page visitors | Case studies, demos | Move to decision |
|
||||
| Bottom | Cart abandoners, trial users | Urgency, objection handling | Convert |
|
||||
|
||||
### Retargeting Windows
|
||||
|
||||
| Stage | Window | Frequency Cap |
|
||||
|-------|--------|---------------|
|
||||
| Hot (cart/trial) | 1-7 days | Higher OK |
|
||||
| Warm (key pages) | 7-30 days | 3-5x/week |
|
||||
| Cold (any visit) | 30-90 days | 1-2x/week |
|
||||
|
||||
### Exclusions to Set Up
|
||||
- Existing customers (unless upsell)
|
||||
- Recent converters (7-14 day window)
|
||||
- Bounced visitors (<10 sec)
|
||||
- Irrelevant pages (careers, support)
|
||||
|
||||
### Retarget with DIFFERENT offers (not the same one)
|
||||
|
||||
The conventional retargeting playbook re-shows the same product/offer to people who didn't buy. The Sabri Suby principle: **the #1 reason someone didn't buy is the offer wasn't right for them.** Re-showing the same thing harder doesn't help.
|
||||
|
||||
Instead, retarget with **different** products, services, or offers from your catalog:
|
||||
- Visitor clicked on protein powder, didn't buy → retarget with creatine (totally different category)
|
||||
- Visitor downloaded a lead magnet, didn't book a call → retarget with a different lead magnet on a related topic
|
||||
- Visitor viewed pricing, didn't sign up → retarget with a free audit or assessment instead
|
||||
|
||||
The lift from this is often dramatic — a 2-3 ROAS audience on the original offer can hit 6+ ROAS on a different offer.
|
||||
|
||||
### The 4-component retargeting framework
|
||||
|
||||
Build out your retargeting layer with these 4 ad types running simultaneously:
|
||||
|
||||
1. **Objection-handling ad** — directly addresses the most common reasons people didn't buy. To find these, **outbound call every lead** who didn't convert and ask why. The verbatim objections become the headline of this ad.
|
||||
2. **Proof testimonial carousel** — multi-image/multi-slide carousel of testimonials and proof that supports the claims of your original ad
|
||||
3. **Other-offers CBO** — your other best-performing ads for other products/services in one CBO, retargeted to the same audience
|
||||
4. **Value-first audit/assessment ad** — wraps your call in a free piece of value. Whether they buy or not, they leave with something useful. Lowers the friction to engage.
|
||||
|
||||
These four together, retargeting the same audience that didn't convert from the top-of-funnel ad, dramatically lift the ROAS of the entire funnel.
|
||||
|
||||
---
|
||||
|
||||
## Landing Page Alignment (the headline-mirror trick)
|
||||
|
||||
Ad-to-landing-page congruence is the single most underrated lever in paid ads. Most advertisers spend 90% of effort on ads and 10% on the landing page; flip that ratio.
|
||||
|
||||
### Headline mirroring
|
||||
|
||||
Meta is the best split-testing tool that exists — your ad headlines are exposed to ~1000x the audience that actually clicks through to your landing page. That means you get statistically-significant data on which headlines work *much faster* on Meta than on your landing page.
|
||||
|
||||
The play:
|
||||
|
||||
1. Run **20-40 different headlines** as ad variations
|
||||
2. Identify the best-performing headline (by CTR + downstream conversion)
|
||||
3. **Mirror that winning headline on your landing page** — exact wording in the H1, sub-headline, and lead-in copy of the body
|
||||
4. Expect a **15-20% minimum lift** in landing-page conversion rate from this single change
|
||||
|
||||
This works because the viewer who clicked is expecting *that specific promise*. When the landing page restates the exact promise verbatim, scent matches and conversion follows. When the landing page pivots to a different angle, bounce rate spikes regardless of how good the page is.
|
||||
|
||||
### Three split tests minimum at all times
|
||||
|
||||
A standing discipline: **at any given moment, you should have at least 3 split tests running** somewhere in your funnel — ad creative, landing page, offer, or post-conversion flow. If you don't, you've capped your improvement curve.
|
||||
|
||||
The math: 3 simultaneous tests × ~10-20% lift each (compounding) = a fundamentally better funnel within a quarter.
|
||||
|
||||
## Reporting & Analysis
|
||||
|
||||
### Weekly Review
|
||||
- Spend vs. budget pacing
|
||||
- CPA/ROAS vs. targets
|
||||
- Top and bottom performing ads
|
||||
- Audience performance breakdown
|
||||
- Frequency check (fatigue risk)
|
||||
- Landing page conversion rate
|
||||
|
||||
### Attribution Considerations
|
||||
- Platform attribution is inflated
|
||||
- Use UTM parameters consistently
|
||||
- Compare platform data to GA4
|
||||
- Look at blended CAC, not just platform CPA
|
||||
|
||||
### Scaling discipline (net cash > ROAS percentage)
|
||||
|
||||
The most common scaling failure: a business at a 40 ROAS spending $5k/month, refusing to scale because "if I spend more, my ROAS will drop." This is the wrong frame.
|
||||
|
||||
**Net cash flow > ROAS percentage at the business level:**
|
||||
- ROAS dropping from 10 → 5 sounds bad
|
||||
- But if spend goes from $10k → $100k, you net dramatically more total profit
|
||||
- The number to optimize is **blended ROAS at the business level**, not per-ad-set ROAS
|
||||
- Even better: optimize **net free cash flow**, not ROAS at all
|
||||
|
||||
**Find your break-even ROAS:**
|
||||
1. Calculate the absolute maximum you can pay to acquire a customer and still be profitable (factoring LTV)
|
||||
2. That's your break-even ROAS / CPA ceiling
|
||||
3. **Scale until you approach that ceiling**, not until your ad-account ROAS drops below an arbitrary preference
|
||||
|
||||
**The 3-hour founder review:**
|
||||
- Block out **3 hours per month** in the calendar to physically review the numbers yourself
|
||||
- Not what your data analyst says. Not what your media buyer says. You, going through the actual data
|
||||
- The confidence this generates is irreplaceable — and confidence is what lets you scale with conviction
|
||||
- "Data gives you confidence. Confidence gives you speed."
|
||||
|
||||
**Outbound-call your leads who didn't convert:**
|
||||
- Every lead that downloaded a lead magnet or hit your funnel but didn't buy gets a call
|
||||
- Ask why they didn't book, what was confusing, what the actual blocker was
|
||||
- These verbatim answers become objection-handling ads (see Retargeting section)
|
||||
- Massive insight-to-creative loop that most advertisers skip
|
||||
|
||||
---
|
||||
|
||||
## Platform Setup
|
||||
|
||||
Before launching campaigns, ensure proper tracking and account setup.
|
||||
|
||||
**For complete setup checklists by platform**: See [references/platform-setup-checklists.md](references/platform-setup-checklists.md)
|
||||
|
||||
**For conversion pixel installation and event setup**: See [references/conversion-tracking.md](references/conversion-tracking.md)
|
||||
|
||||
### Universal Pre-Launch Checklist
|
||||
- [ ] Conversion tracking tested with real conversion
|
||||
- [ ] Landing page loads fast (<3 sec)
|
||||
- [ ] Landing page mobile-friendly
|
||||
- [ ] UTM parameters working
|
||||
- [ ] Budget set correctly
|
||||
- [ ] Targeting matches intended audience
|
||||
|
||||
---
|
||||
|
||||
## Google RSA Output Spec (mandatory when generating RSAs)
|
||||
|
||||
When the user requests Google Ads RSAs, load [references/rsa-output-spec.md](references/rsa-output-spec.md) and follow it exactly — hard character limits, required sidecar artifacts (ad groups, negatives, sitelinks, callouts), output order, template shape, CFM medical compliance, and the pre-send self-check. Do not output any RSA that violates it.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Strategy
|
||||
- Launching without conversion tracking
|
||||
- Too many campaigns (fragmenting budget)
|
||||
- Not giving algorithms enough learning time
|
||||
- Optimizing for wrong metric
|
||||
|
||||
### Targeting
|
||||
- Audiences too narrow or too broad
|
||||
- Not excluding existing customers
|
||||
- Overlapping audiences competing
|
||||
|
||||
### Creative
|
||||
- Only one ad per ad set
|
||||
- Not refreshing creative (fatigue)
|
||||
- Mismatch between ad and landing page
|
||||
|
||||
### Budget
|
||||
- Spreading too thin across campaigns
|
||||
- Making big budget changes (disrupts learning)
|
||||
- Stopping campaigns during learning phase
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What platform(s) are you currently running or want to start with?
|
||||
2. What's your monthly ad budget?
|
||||
3. What does a successful conversion look like (and what's it worth)?
|
||||
4. Do you have existing creative assets or need to create them?
|
||||
5. What landing page will ads point to?
|
||||
6. Do you have pixel/conversion tracking set up?
|
||||
|
||||
---
|
||||
|
||||
## Tool Integrations
|
||||
|
||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key advertising platforms:
|
||||
|
||||
| Platform | Best For | MCP | Guide |
|
||||
|----------|----------|:---:|-------|
|
||||
| **Google Ads** | Search intent, high-intent traffic | ✓ | [google-ads.md](../../tools/integrations/google-ads.md) |
|
||||
| **Meta Ads** | Demand gen, visual products, B2C | - | [meta-ads.md](../../tools/integrations/meta-ads.md) |
|
||||
| **LinkedIn Ads** | B2B, job title targeting | - | [linkedin-ads.md](../../tools/integrations/linkedin-ads.md) |
|
||||
| **TikTok Ads** | Younger demographics, video | - | [tiktok-ads.md](../../tools/integrations/tiktok-ads.md) |
|
||||
|
||||
For tracking setup, see [references/conversion-tracking.md](references/conversion-tracking.md), [ga4.md](../../tools/integrations/ga4.md), [segment.md](../../tools/integrations/segment.md)
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **ad-creative**: For generating and iterating ad headlines, descriptions, and creative at scale
|
||||
- **revops**: For the CRM side of ABM — lead scoring, routing, and the offline conversion loop
|
||||
- **customer-research**: For the voice-of-customer inputs that feed ad copy and creative angles
|
||||
- **copywriting**: For landing page copy that converts ad traffic
|
||||
- **analytics**: For proper conversion tracking setup
|
||||
- **ab-testing**: For landing page testing to improve ROAS
|
||||
- **cro**: For optimizing post-click conversion rates
|
||||
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"skill_name": "ads",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Help me plan a paid advertising strategy. We're a B2B SaaS tool for HR teams, selling at $99/month per seat. We have $15k/month to spend on ads and want to generate demo requests. Where should we advertise?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide based on B2B, HR audience, $99/month price point. Should recommend LinkedIn (B2B targeting by job title/industry), Google Ads (search intent for HR software keywords), and potentially Meta (retargeting). Should recommend campaign structure with naming conventions. Should define audience targeting strategy for each platform. Should set budget allocation across platforms. Should define success metrics and attribution approach. Should recommend starting structure and scaling plan.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies platform selection guide",
|
||||
"Recommends platforms appropriate for B2B HR audience",
|
||||
"Recommends campaign structure with naming conventions",
|
||||
"Defines audience targeting per platform",
|
||||
"Sets budget allocation across platforms",
|
||||
"Defines success metrics",
|
||||
"Recommends starting structure and scaling plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Our Google Ads CPC is $12 and our cost per lead is $180. Is that good? We're getting about 80 leads/month from a $15k budget.",
|
||||
"expected_output": "Should evaluate the metrics in context. Should assess: $12 CPC for B2B (reasonable depending on industry), $180 CPL (depends on LTV — need to compare against customer lifetime value), 80 leads/month from $15k (math checks out). Should apply the campaign optimization framework: check quality score, search term relevance, landing page conversion rate, negative keywords. Should recommend specific optimization levers to reduce CPC and CPL. Should frame performance against industry benchmarks if applicable. Should ask about downstream conversion rates (lead → demo → customer).",
|
||||
"assertions": [
|
||||
"Evaluates metrics in context",
|
||||
"Compares CPL against LTV considerations",
|
||||
"Applies campaign optimization framework",
|
||||
"Recommends specific optimization levers",
|
||||
"Asks about downstream conversion rates",
|
||||
"Provides industry context for benchmarking"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "we want to run retargeting ads for people who visited our site but didn't convert. how should we set this up?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the retargeting strategies section, specifically the funnel-based approach. Should recommend audience segments: all visitors (broad), pricing page visitors (high intent), blog readers (lower intent), and cart/signup abandoners (highest intent). Should recommend different messaging and offers for each segment. Should address frequency capping to avoid ad fatigue. Should recommend retargeting platforms (Meta, Google Display, LinkedIn). Should include duration windows for each audience.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Applies funnel-based retargeting approach",
|
||||
"Recommends audience segments by intent level",
|
||||
"Recommends different messaging per segment",
|
||||
"Addresses frequency capping",
|
||||
"Recommends retargeting platforms",
|
||||
"Includes audience duration windows"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Should we advertise on TikTok? We sell accounting software to small businesses. Our current ads are on Google and Meta.",
|
||||
"expected_output": "Should apply the platform selection guide for TikTok specifically. Should evaluate TikTok fit for accounting software + small business audience: likely a weaker fit than Google/Meta for this category (lower purchase intent, younger skewing audience, less B2B targeting). Should discuss when TikTok CAN work for B2B (brand awareness, creative content, younger business owners). Should provide an honest recommendation with caveats. Should suggest a small test budget approach if they want to try.",
|
||||
"assertions": [
|
||||
"Applies platform selection guide for TikTok",
|
||||
"Evaluates fit for accounting + small business audience",
|
||||
"Provides honest assessment of likely weaker fit",
|
||||
"Discusses when TikTok can work for B2B",
|
||||
"Suggests small test budget if proceeding",
|
||||
"Compares to their existing Google/Meta performance"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "How do we structure our Google Ads campaigns? We have 50+ keywords we want to target for our CRM product.",
|
||||
"expected_output": "Should apply the campaign structure and naming conventions framework. Should recommend organizing campaigns by theme/intent (brand, competitor, product features, pain points). Should recommend ad group structure (tightly themed, 5-15 keywords per group). Should define naming conventions for campaigns and ad groups. Should recommend match types strategy. Should include negative keyword lists. Should provide a sample campaign structure.",
|
||||
"assertions": [
|
||||
"Applies campaign structure framework",
|
||||
"Organizes campaigns by theme/intent",
|
||||
"Recommends tight ad group structure",
|
||||
"Defines naming conventions",
|
||||
"Recommends match types strategy",
|
||||
"Includes negative keyword lists",
|
||||
"Provides sample campaign structure"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Can you write some ad copy for our Facebook ads? We need headlines and descriptions for 5 different angles.",
|
||||
"expected_output": "Should recognize this is an ad creative generation task, not campaign strategy. Should defer to or cross-reference the ad-creative skill, which handles platform-specific ad copy generation with character limits, angle-based variation, and batch generation. May provide brief ad copy framework guidance but should make clear that ad-creative is the right skill for generating ad copy at scale.",
|
||||
"assertions": [
|
||||
"Recognizes this as ad creative generation",
|
||||
"References or defers to ad-creative skill",
|
||||
"Does not attempt bulk ad copy generation using campaign strategy patterns"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,93 @@
|
||||
# ABM Playbook (Paid)
|
||||
|
||||
Account-based marketing with ads: targeting named accounts on LinkedIn and Meta, accelerating open pipeline, and stitching channels together. ABM ads are a *pipeline influence* motion, not a lead-gen motion — measure accordingly.
|
||||
|
||||
## Contents
|
||||
|
||||
- When ABM (go/no-go)
|
||||
- LinkedIn ABM
|
||||
- ABM on Meta
|
||||
- Acceleration campaigns (ads against open pipeline)
|
||||
- Cross-channel orchestration
|
||||
- Cross-channel UTM remarketing
|
||||
- Sales orchestration
|
||||
- Measuring ABM
|
||||
|
||||
## When ABM (go/no-go)
|
||||
|
||||
Run paid ABM when: target account list ≥ ~1,000 companies (or you accept 1:1/1:few economics), deal size ~$25K+, sales cycle 60+ days, sales and marketing actually aligned on the list, and (for Meta) contact enrichment available.
|
||||
|
||||
Skip it when: TAL under ~500 with no enrichment, no first-party data, budget under ~$3K/month, or a short transactional cycle — standard ICP targeting will outperform.
|
||||
|
||||
## LinkedIn ABM
|
||||
|
||||
Three motions, by list size:
|
||||
|
||||
- **1:1** — add the company by name; fully personalized creative for one account.
|
||||
- **1:few** — up to ~10–20 accounts per campaign, shared pain/industry angle.
|
||||
- **1:many** — uploaded list (or native targeting), scaled creative.
|
||||
|
||||
**List mechanics:**
|
||||
- LinkedIn needs **300 matched members minimum** to serve; aim for 1,000+ rows (duplicating company names to pad the upload is fine — it dedupes on match). Contact lists match best at scale (LinkedIn suggests ~10K emails); **company lists beat contact lists** for most teams — easier to source, better match rates, less maintenance.
|
||||
- Cold ABM audiences need ~15K members to deliver reliably.
|
||||
- **Segment mixed lists.** Left as one audience, LinkedIn over-serves the largest enterprises in the list — accounts have sat at 15% list coverage because the algorithm parked on a few big companies. Split into homogeneous bands (e.g., enterprise / mid-market / SMB) with separate campaigns and budgets.
|
||||
- List-based targeting typically buys reach materially cheaper than native firmographic targeting, with stronger decision-maker engagement.
|
||||
- Use the per-company engagement report (Audiences → click into the list) to find under-served priority accounts, then break them into a dedicated campaign.
|
||||
|
||||
**Personalized 1:1 creative:** putting the target account's name/logo in the creative can lift CTR ~5–10× over generic ads. **Legal exception: do not run company-name/logo-personalized ads into Germany** — privacy law, not platform policy.
|
||||
|
||||
**Frequency capping:** target ~3 impressions/person/week in priority accounts. Mechanic: build a company-engagement audience of accounts that crossed ~500 impressions in the last 7 days and add it as an *exclusion* — it self-rotates accounts out as they cool down. Tune the threshold (300 if fatigue shows, 750 for more pressure).
|
||||
|
||||
## ABM on Meta
|
||||
|
||||
Meta has no native company targeting — the play is **bring your own matched audience**:
|
||||
|
||||
- **The match-rate problem:** raw CRM exports of work emails match under ~5% on Meta. Enrichment providers (identity-graph tools that resolve work identities to personal profiles — e.g., Primer, Metadata, ZoomInfo, Clearbit) raise matches to ~40–85%. Workflow: firmographic criteria → identity-graph match → upload as Custom Audience → target directly or seed a 1% lookalike.
|
||||
- **Minimum sizes:** account-list audiences ~1,000 companies (5–10K optimal); retargeting slices work down to ~100 accounts; lookalike seeds want 500+.
|
||||
- Advantage+ **conflicts with strict ABM** — it won't stay locked to your list. Run ABM campaigns manual (or hybrid: manual for the list, Advantage+ for the broad layer).
|
||||
- Meta's ABM role is cheap **air cover and multi-threading** (reaching the buying committee beyond your champion) while LinkedIn does precision — see the split below.
|
||||
|
||||
## Acceleration campaigns (ads against open pipeline)
|
||||
|
||||
Ads aimed at accounts already in your pipeline, to speed deals rather than source them:
|
||||
|
||||
- Segment the CRM by stage (evaluation / proposal / negotiation), filter to deals worth the spend, upload as an audience, refresh weekly.
|
||||
- **Use an awareness/reach objective, not conversions** — you're keeping the vendor top-of-mind for the buying committee, not asking in-pipeline accounts to "book a demo" they already booked.
|
||||
- Creative: case studies, proof, objection-handlers — matched to stage. Budget scales with deal value (larger open deals justify $100–200/day of air cover; stalled deals get a maintenance dose).
|
||||
|
||||
## Cross-channel orchestration
|
||||
|
||||
Default split for B2B ABM: **~60% LinkedIn / ~30% Meta / ~10% other**. LinkedIn buys precision (right person, right company) at $40–70 CPMs; Meta buys presence and committee reach at $10–25. Sequence LinkedIn first to validate the audience, then extend to Meta. Multi-channel ABM consistently and materially outperforms single-channel on engagement and conversion — the channels compound, they don't compete.
|
||||
|
||||
## Cross-channel UTM remarketing
|
||||
|
||||
The cheapest high-quality audience you can build: retarget one platform's validated clickers on another platform.
|
||||
|
||||
1. Tag all paid traffic with consistent UTMs (`utm_source=linkedin`, `utm_source=google&utm_medium=cpc`).
|
||||
2. On Meta, build a website Custom Audience with the rule **"URL contains `utm_source=linkedin`"** (or `utm_source=google`).
|
||||
3. Retarget that audience on Meta — LinkedIn-grade audience quality at Meta-grade CPMs (typically 50–70% cheaper reach).
|
||||
|
||||
Works in both directions (search clickers → LinkedIn remarketing needs meaningful search volume — worth it above roughly $30K/month search spend). Requires enough source-channel traffic to clear minimum audience sizes. Use a consistent account/campaign token in UTMs so attribution survives the hop.
|
||||
|
||||
## Sales orchestration
|
||||
|
||||
ABM ads without sales follow-up is billboard spend:
|
||||
|
||||
- Pipe ad-engagement signals to the CRM (LinkedIn company-engagement exports, or connectors that sync engagement per account) and treat an engagement spike as a sales trigger — **outreach within ~48 hours** of the spike.
|
||||
- Route new leads to a shared channel (Slack webhook) with a per-campaign quality reaction (👍/👎) — the cheapest lead-quality feedback loop that exists.
|
||||
- Hold a monthly sales-marketing session on the list itself: who's engaging, who's dark, who closed — and re-cut the list.
|
||||
- Expect ~7–10 cross-channel touches before a sales conversation is normal at ABM deal sizes.
|
||||
|
||||
## Measuring ABM
|
||||
|
||||
Judge ABM on account movement, not CPL:
|
||||
|
||||
- **Account penetration** (% of list reached): target ~40–60%.
|
||||
- **Cost per engaged account** (not per click): ~$100–300 is a workable band.
|
||||
- **Account → opportunity rate:** ~10–20%.
|
||||
- **Pipeline influenced:** aim for 3–5× spend; expect win-rate and velocity improvements on engaged vs. non-engaged accounts.
|
||||
- **Incrementality:** hold out ~20% of the list from ads and compare pipeline formation after 21+ days — the only honest answer to "did the ads do anything?"
|
||||
|
||||
---
|
||||
|
||||
*Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Thresholds are practitioner-reported starting points — recalibrate against your own accounts.*
|
||||
@@ -0,0 +1,115 @@
|
||||
# B2B Paid Playbook
|
||||
|
||||
Cross-platform operating rules for B2B paid acquisition — where sales cycles run 2–24 months, in-platform conversions mislead, and lead *quality* matters more than lead cost. Use this alongside the platform playbooks ([Meta decision system](meta-decision-system.md), [LinkedIn](linkedin-b2b-playbook.md), [Google Search](google-search-playbook.md), [ABM](abm-playbook.md)).
|
||||
|
||||
## Contents
|
||||
|
||||
- The Demand Lifecycle (5 stages, past the funnel)
|
||||
- Budget by stage
|
||||
- Leading vs. lagging signals
|
||||
- Unit economics: breakeven CPL and CPC
|
||||
- Kill rules
|
||||
- The optimize-to-quality trap (and the offline conversion loop)
|
||||
- Lead quality scoring (Urgency / Budget / Fit)
|
||||
- The scaling quadrant
|
||||
- Measurement maturity check
|
||||
- Channel selection
|
||||
|
||||
## The Demand Lifecycle (5 stages, past the funnel)
|
||||
|
||||
TOFU/MOFU/BOFU stops at conversion. B2B revenue doesn't — closed-lost deals, open pipeline, and existing customers are all addressable with ads. Plan across five stages:
|
||||
|
||||
| Stage | Outcome | Buyer awareness | Typical offers | KPIs |
|
||||
|-------|---------|-----------------|----------------|------|
|
||||
| **Create** | Build affinity & trust | Unaware / Problem-aware | Educational content, POV | Cost per consumption, blended cost/opp |
|
||||
| **Capture** | Convert in-market buyers | Solution / Product-aware | Demos, trials | Pipe-to-spend, direct cost/opp |
|
||||
| **Accelerate** (sales-led) / **Activate** (product-led) | Close open deals faster / convert free users | Product / Offer-aware | Case studies, webinars, events | Pipeline velocity, paid signups |
|
||||
| **Revive** | Restart closed-lost | Offer-aware | Incentivized demos, guided trials | SQOs created, cost/SQO |
|
||||
| **Expand** | Grow existing accounts | Most aware | Referral programs, new-feature content | Expansion revenue, influenced SQOs |
|
||||
|
||||
**Build bottom-up for fastest ROI**: Expand → Revive → Accelerate/Activate → Capture → Create. The bottom stages are cheap, small-audience, and quick to pay back; Create is the biggest and slowest investment. Most teams build top-down and burn months waiting for ROI.
|
||||
|
||||
## Budget by stage
|
||||
|
||||
| Stage | Budget size | Time to ROI | Difficulty |
|
||||
|-------|------------|-------------|------------|
|
||||
| Create | High | 90+ days | High (needs strong content + POV) |
|
||||
| Capture | Moderate | <45 days | High (expensive, competitive) |
|
||||
| Accelerate/Activate | Low | Tracks sales cycle | Low |
|
||||
| Revive | Low | <45 days | Low |
|
||||
| Expand | Low | <60 days | Medium (small audiences) |
|
||||
|
||||
Weight by motion: product-led skews budget to Create + Capture; sales-led with a small TAM skews to Create + Accelerate. The stage with the most *pipeline* isn't automatically the stage that deserves the most *budget* — fund where pipeline share exceeds budget share and the audience is under-penetrated.
|
||||
|
||||
## Leading vs. lagging signals
|
||||
|
||||
You can't optimize on closed-won when deals close in 6 months. Split every stage's metrics:
|
||||
|
||||
- **Leading** (moves in <1 month — optimize on these): CTR, engagement, CPL, cost per qualified lead, accounts reached
|
||||
- **Lagging** (moves in >1 month — the truth, reviewed monthly/quarterly): pipe-to-spend, influenced revenue, time-to-close, expansion revenue
|
||||
|
||||
The leading metric must demonstrably correlate with the lagging one — a proxy metric worth optimizing is measurable, moveable, not an average, and hard to game. If CPL falls while pipeline doesn't move, the proxy broke; fix the proxy, not the ads.
|
||||
|
||||
## Unit economics: breakeven CPL and CPC
|
||||
|
||||
Derive targets from deal math, not platform benchmarks:
|
||||
|
||||
- **Breakeven CPL** = average deal size × lead-to-close rate. ($3,000 ACV × 10% close = $300 CPL.)
|
||||
- **Breakeven CPC** = target CPL × landing page conversion rate. ($300 CPL × 5% LP conversion = $15 CPC.)
|
||||
|
||||
Set the actual target below breakeven by your required margin. Every kill rule and scaling decision keys off this number.
|
||||
|
||||
## Kill rules
|
||||
|
||||
Two hard rules that remove emotion from pausing decisions:
|
||||
|
||||
- **Non-performer rule** (new ads, any time): pause once an ad has spent **2–3× target CPL with zero conversions**. Target CPL $300 → kill at $600–900 spent, no conversions.
|
||||
- **Maintenance rule** (ads past ~7–14 days): pause when an ad's CPL runs **1.5–2× over target**. Target $300 → kill at $450–600 CPL.
|
||||
|
||||
These aren't statistically rigorous — they're repeatable, cheap to apply, and better than deciding by mood. Never pause a producer without a replacement staged (see the swap rules in the [Meta decision system](meta-decision-system.md)).
|
||||
|
||||
## The optimize-to-quality trap (and the offline conversion loop)
|
||||
|
||||
Smart bidding optimizes toward whatever you call a "conversion." Feed it raw form-fills and it will buy you cheap junk form-fills — CPL improves while pipeline dies. The fix, in order:
|
||||
|
||||
1. **Close the offline conversion loop.** Push CRM stage changes (MQL → SQL → opportunity → closed-won) back to the ad platforms — GCLID + offline import on Google, CAPI lifecycle events on Meta, conversion API on LinkedIn. This is the single highest-impact move in a B2B ad account: the algorithm starts buying pipeline instead of form-fills.
|
||||
2. **Value conversions differently.** A demo request is not an ebook download.
|
||||
3. **Until offline data flows, keep a human reading lead quality weekly** — job titles and companies, not just CPL.
|
||||
|
||||
Reconcile platform-reported conversions against the CRM monthly. When they disagree, **the CRM wins**.
|
||||
|
||||
## Lead quality scoring (Urgency / Budget / Fit)
|
||||
|
||||
The platform can't see lead quality — score it yourself and rank ads by it:
|
||||
|
||||
- **Urgency** (0–3): 0 browsing → 3 burning need with timeline
|
||||
- **Budget** (0–3): 0 none/no authority → 3 approved and ready
|
||||
- **Fit** (0–3): 0 not ICP → 3 perfect ICP
|
||||
|
||||
Whoever runs the sales calls scores each lead (max 9) and logs it against the originating ad. After ~20 scored calls, **rank ads by average quality score, not CPL or CTR** — the ad with the best CPL is regularly the one producing 3/9 leads. Scale the high-score ads; kill variations whose average drops below ~5.
|
||||
|
||||
## The scaling quadrant
|
||||
|
||||
Route scaling tactics by your actual constraint:
|
||||
|
||||
| | Low effort | High effort |
|
||||
|---|---|---|
|
||||
| **High budget** | **Audiences** — bigger audiences, more segments, more frequency | **Geography** — new countries/regions (localization work) |
|
||||
| **Low budget** | **Ads** — new creative, angles, formats | **Objectives & bids** — change objective or bid strategy to buy cheaper |
|
||||
|
||||
- Have budget but no time → work the top row (audiences, then geo).
|
||||
- Need scale but capped on budget → work the bottom row (better creative and cheaper bidding free up money).
|
||||
|
||||
## Measurement maturity check
|
||||
|
||||
Before scaling spend, score yourself 1–3 on each: blended pipeline dashboard; per-channel dashboard; conversion tracking (1 = none, 2 = pixel only, 3 = offline conversions flowing); web analytics; a documented, agreed attribution process. Under ~6/15, fix visibility before adding budget — you're flying blind and every optimization is a guess. Fix the lowest score first.
|
||||
|
||||
## Channel selection
|
||||
|
||||
Five channel families: paid social, paid search, **paid review listings** (G2, Capterra, Software Advice — often skipped, high intent), programmatic (display, audio, CTV, native), and sponsorships (newsletters, podcasts, events, creators). Evaluate on four axes: can you actually target your ICP; media cost (CPC/CPM); reach at your targeting; platform policy for your industry.
|
||||
|
||||
Before committing to a new channel, **run a ~$100 test campaign** to learn its real CPC/CPM for your targeting — platform estimates and published benchmarks are consistently wrong for specific ICPs.
|
||||
|
||||
---
|
||||
|
||||
*Framework lineage: several operating rules in this file are adapted (re-expressed, restructured, and extended) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks and thresholds are practitioner-reported starting points — always recalibrate against your own account's first 30 days.*
|
||||
@@ -0,0 +1,361 @@
|
||||
# Conversion Tracking Setup
|
||||
|
||||
How to set up conversion tracking pixels across ad platforms. This guide covers installation, event configuration, and validation — everything a marketer needs to ensure ad spend is properly attributed.
|
||||
|
||||
---
|
||||
|
||||
## Why This Matters
|
||||
|
||||
Without conversion tracking:
|
||||
- Ad platforms can't optimize for your actual goals
|
||||
- You're flying blind on ROAS and CPA
|
||||
- Retargeting audiences can't be built
|
||||
- You'll waste budget on impressions that don't convert
|
||||
|
||||
Get tracking right before spending a dollar on ads.
|
||||
|
||||
---
|
||||
|
||||
## Platform Pixels Overview
|
||||
|
||||
| Platform | Pixel/Tag Name | Events API | Key Events |
|
||||
|----------|---------------|:----------:|------------|
|
||||
| **Google Ads** | Google tag (gtag.js) | Enhanced Conversions | purchase, sign_up, generate_lead |
|
||||
| **Meta** | Meta Pixel + CAPI | Conversions API | Purchase, Lead, ViewContent, AddToCart |
|
||||
| **LinkedIn** | Insight Tag | Conversions API | conversion (URL or event-based) |
|
||||
| **TikTok** | TikTok Pixel | Events API | Purchase, ViewContent, AddToCart, CompleteRegistration |
|
||||
| **Twitter/X** | Twitter Pixel | - | Purchase, SignUp, Download |
|
||||
|
||||
---
|
||||
|
||||
## Google Ads
|
||||
|
||||
### Install the Google tag
|
||||
|
||||
Add to every page, in `<head>`:
|
||||
|
||||
```html
|
||||
<script async src="https://www.googletagmanager.com/gtag/js?id=AW-XXXXXXXXX"></script>
|
||||
<script>
|
||||
window.dataLayer = window.dataLayer || [];
|
||||
function gtag(){dataLayer.push(arguments);}
|
||||
gtag('js', new Date());
|
||||
gtag('config', 'AW-XXXXXXXXX');
|
||||
</script>
|
||||
```
|
||||
|
||||
Replace `AW-XXXXXXXXX` with your Conversion ID from Google Ads > Tools > Conversions.
|
||||
|
||||
### Set up conversion actions
|
||||
|
||||
In Google Ads > Goals > Conversions > New conversion action:
|
||||
|
||||
| Conversion | Category | Value | Count |
|
||||
|-----------|----------|-------|-------|
|
||||
| Purchase | Purchase | Dynamic (order value) | Every |
|
||||
| Sign up / Lead | Sign-up | Fixed ($X estimated value) | One |
|
||||
| Demo request | Lead | Fixed ($X estimated value) | One |
|
||||
| Free trial start | Sign-up | Fixed ($X estimated value) | One |
|
||||
|
||||
### Fire conversion events
|
||||
|
||||
```javascript
|
||||
// Purchase
|
||||
gtag('event', 'conversion', {
|
||||
'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL',
|
||||
'value': 99.00,
|
||||
'currency': 'USD',
|
||||
'transaction_id': 'ORDER-123'
|
||||
});
|
||||
|
||||
// Lead / Sign up
|
||||
gtag('event', 'conversion', {
|
||||
'send_to': 'AW-XXXXXXXXX/CONVERSION_LABEL',
|
||||
'value': 50.00,
|
||||
'currency': 'USD'
|
||||
});
|
||||
```
|
||||
|
||||
### Enhanced Conversions
|
||||
|
||||
Sends hashed first-party data (email, phone) to improve attribution after cookie restrictions. Enable in Google Ads > Goals > Settings > Enhanced conversions.
|
||||
|
||||
```javascript
|
||||
gtag('set', 'user_data', {
|
||||
'email': 'user@example.com', // auto-hashed by gtag
|
||||
'phone_number': '+11234567890'
|
||||
});
|
||||
```
|
||||
|
||||
### Google Tag Manager alternative
|
||||
|
||||
If using GTM instead of inline gtag.js:
|
||||
1. Install GTM container on all pages
|
||||
2. Create Google Ads conversion tags in GTM
|
||||
3. Set triggers for conversion events (form submissions, purchases)
|
||||
4. Use the Data Layer to pass dynamic values (order amount, transaction ID)
|
||||
5. Test with GTM Preview mode before publishing
|
||||
|
||||
---
|
||||
|
||||
## Meta (Facebook/Instagram)
|
||||
|
||||
### Install the Meta Pixel
|
||||
|
||||
Add to every page, in `<head>`:
|
||||
|
||||
```html
|
||||
<script>
|
||||
!function(f,b,e,v,n,t,s)
|
||||
{if(f.fbq)return;n=f.fbq=function(){n.callMethod?
|
||||
n.callMethod.apply(n,arguments):n.queue.push(arguments)};
|
||||
if(!f._fbq)f._fbq=n;n.push=n;n.loaded=!0;n.version='2.0';
|
||||
n.queue=[];t=b.createElement(e);t.async=!0;
|
||||
t.src=v;s=b.getElementsByTagName(e)[0];
|
||||
s.parentNode.insertBefore(t,s)}(window, document,'script',
|
||||
'https://connect.facebook.net/en_US/fbevents.js');
|
||||
fbq('init', 'YOUR_PIXEL_ID');
|
||||
fbq('track', 'PageView');
|
||||
</script>
|
||||
```
|
||||
|
||||
Replace `YOUR_PIXEL_ID` from Meta Events Manager.
|
||||
|
||||
### Standard events
|
||||
|
||||
```javascript
|
||||
// View a product or key page
|
||||
fbq('track', 'ViewContent', {
|
||||
content_name: 'Pro Plan',
|
||||
content_category: 'Pricing',
|
||||
value: 29.00,
|
||||
currency: 'USD'
|
||||
});
|
||||
|
||||
// Lead capture (form submit, demo request)
|
||||
fbq('track', 'Lead', {
|
||||
content_name: 'Demo Request',
|
||||
value: 50.00,
|
||||
currency: 'USD'
|
||||
});
|
||||
|
||||
// Purchase
|
||||
fbq('track', 'Purchase', {
|
||||
value: 99.00,
|
||||
currency: 'USD',
|
||||
content_type: 'product',
|
||||
contents: [{ id: 'pro-plan', quantity: 1 }]
|
||||
});
|
||||
|
||||
// Add to cart (e-commerce)
|
||||
fbq('track', 'AddToCart', {
|
||||
content_ids: ['SKU-123'],
|
||||
content_type: 'product',
|
||||
value: 49.00,
|
||||
currency: 'USD'
|
||||
});
|
||||
```
|
||||
|
||||
### Conversions API (CAPI)
|
||||
|
||||
Server-side tracking that works alongside the pixel. Required for accurate tracking after iOS 14+ and cookie restrictions.
|
||||
|
||||
Set up via:
|
||||
- **Direct integration** — send events from your server to Meta's API
|
||||
- **Partner integrations** — Shopify, WooCommerce, Segment, etc. have built-in CAPI support
|
||||
- **Conversions API Gateway** — Meta's managed solution via AWS
|
||||
|
||||
Key: send the same events from both pixel (browser) AND CAPI (server), with a shared `event_id` for deduplication.
|
||||
|
||||
### Aggregated Event Measurement
|
||||
|
||||
Required for iOS 14+ tracking. In Events Manager > Aggregated Event Measurement:
|
||||
1. Verify your domain
|
||||
2. Configure and prioritize your top 8 events in order of business importance
|
||||
3. Purchase should typically be #1, Lead #2
|
||||
|
||||
---
|
||||
|
||||
## LinkedIn
|
||||
|
||||
### Install the Insight Tag
|
||||
|
||||
Add to every page, before `</body>`:
|
||||
|
||||
```html
|
||||
<script type="text/javascript">
|
||||
_linkedin_partner_id = "YOUR_PARTNER_ID";
|
||||
window._linkedin_data_partner_ids = window._linkedin_data_partner_ids || [];
|
||||
window._linkedin_data_partner_ids.push(_linkedin_partner_id);
|
||||
(function(l) {
|
||||
if (!l){window.lintrk = function(a,b){window.lintrk.q.push([a,b])};
|
||||
window.lintrk.q=[]}
|
||||
var s = document.getElementsByTagName("script")[0];
|
||||
var b = document.createElement("script");
|
||||
b.type = "text/javascript";b.async = true;
|
||||
b.src = "https://snap.licdn.com/li.lms-analytics/insight.min.js";
|
||||
s.parentNode.insertBefore(b, s);})(window.lintrk);
|
||||
</script>
|
||||
```
|
||||
|
||||
### Conversion tracking
|
||||
|
||||
LinkedIn supports two methods:
|
||||
|
||||
**URL-based**: Fires when someone visits a specific URL (e.g., `/thank-you`).
|
||||
Set up in Campaign Manager > Analyze > Conversion Tracking > Create Conversion.
|
||||
|
||||
**Event-based**: Fire manually on specific actions:
|
||||
|
||||
```javascript
|
||||
window.lintrk('track', { conversion_id: YOUR_CONVERSION_ID });
|
||||
```
|
||||
|
||||
### LinkedIn CAPI
|
||||
|
||||
For server-side tracking, LinkedIn offers a Conversions API. Set up via partner integrations (Segment, Tealium) or direct API calls. Deduplicates with the Insight Tag automatically when configured correctly.
|
||||
|
||||
---
|
||||
|
||||
## TikTok
|
||||
|
||||
### Install the TikTok Pixel
|
||||
|
||||
Add to every page, in `<head>`:
|
||||
|
||||
```html
|
||||
<script>
|
||||
!function (w, d, t) {
|
||||
w.TiktokAnalyticsObject=t;var ttq=w[t]=w[t]||[];
|
||||
ttq.methods=["page","track","identify","instances","debug","on","off",
|
||||
"once","ready","alias","group","enableCookie","disableCookie","holdConsent",
|
||||
"revokeConsent","grantConsent"],ttq.setAndDefer=function(t,e)
|
||||
{t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
|
||||
for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
|
||||
ttq.instance=function(t){for(var e=ttq._i[t]||[],n=0;
|
||||
n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
|
||||
ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js",
|
||||
o=n&&n.partner;ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,
|
||||
ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},
|
||||
ttq._o[e]=n||{};var s=document.createElement("script");
|
||||
s.type="text/javascript",s.async=!0,s.src=r+"?sdkid="+e+"&lib="+t;
|
||||
var a=document.getElementsByTagName("script")[0];
|
||||
a.parentNode.insertBefore(s,a)};
|
||||
ttq.load('YOUR_PIXEL_ID');
|
||||
ttq.page();
|
||||
}(window, document, 'ttq');
|
||||
</script>
|
||||
```
|
||||
|
||||
### Standard events
|
||||
|
||||
```javascript
|
||||
// View content
|
||||
ttq.track('ViewContent', {
|
||||
content_id: 'pro-plan',
|
||||
content_type: 'product',
|
||||
content_name: 'Pro Plan',
|
||||
value: 29.00,
|
||||
currency: 'USD'
|
||||
});
|
||||
|
||||
// Complete registration / sign up
|
||||
ttq.track('CompleteRegistration', {
|
||||
content_name: 'Free Trial'
|
||||
});
|
||||
|
||||
// Purchase
|
||||
ttq.track('Purchase', {
|
||||
content_id: 'pro-plan',
|
||||
content_type: 'product',
|
||||
value: 99.00,
|
||||
currency: 'USD',
|
||||
quantity: 1
|
||||
});
|
||||
|
||||
// Add to cart
|
||||
ttq.track('AddToCart', {
|
||||
content_id: 'SKU-123',
|
||||
content_type: 'product',
|
||||
value: 49.00,
|
||||
currency: 'USD'
|
||||
});
|
||||
```
|
||||
|
||||
### Events API (server-side)
|
||||
|
||||
TikTok's Events API works like Meta's CAPI — send the same events from your server for better attribution. Use `event_id` for deduplication with browser pixel events.
|
||||
|
||||
### Advanced Matching
|
||||
|
||||
Pass hashed user data for better attribution:
|
||||
|
||||
```javascript
|
||||
ttq.identify({
|
||||
email: 'user@example.com', // auto-hashed
|
||||
phone_number: '+11234567890'
|
||||
});
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Checklist
|
||||
|
||||
After installing any pixel, verify before going live:
|
||||
|
||||
### Browser-side checks
|
||||
|
||||
- [ ] Pixel fires on every page (check via browser extension)
|
||||
- [ ] Conversion events fire at the right moment (after confirmed action, not on button click)
|
||||
- [ ] Event parameters contain correct values (currency, amount, content IDs)
|
||||
- [ ] No duplicate events firing on the same action
|
||||
- [ ] Events fire on both desktop and mobile
|
||||
|
||||
### Platform-side checks
|
||||
|
||||
- [ ] Events appear in the platform's event manager/diagnostics
|
||||
- [ ] Test conversions show correct values
|
||||
- [ ] Event match quality is acceptable (Meta: score > 6)
|
||||
- [ ] Server-side events are deduplicating with browser events (not double-counting)
|
||||
|
||||
### Debugging tools
|
||||
|
||||
| Platform | Tool |
|
||||
|----------|------|
|
||||
| Google | Google Tag Assistant, Chrome DevTools Network tab |
|
||||
| Meta | Meta Pixel Helper (Chrome extension), Events Manager Test Events |
|
||||
| LinkedIn | Insight Tag Validator in Campaign Manager |
|
||||
| TikTok | TikTok Pixel Helper (Chrome extension), Events Manager |
|
||||
| All | GTM Preview Mode (if using Google Tag Manager) |
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
- **Firing purchase events on button click instead of confirmed payment** — always fire on the success/thank-you page or after server confirmation
|
||||
- **Missing deduplication between pixel and server events** — without a shared `event_id`, you'll double-count conversions
|
||||
- **Not testing on mobile** — many pixels break on mobile browsers or in-app webviews
|
||||
- **Hardcoded test values** — remove test transaction amounts before going live
|
||||
- **Forgetting to exclude internal traffic** — your team's visits inflate conversion data
|
||||
- **Installing pixels without consent management** — GDPR/CCPA require user consent before firing tracking pixels in applicable regions
|
||||
- **Pixel installed but no conversion actions created** — the pixel collects data, but the ad platform won't optimize without defined conversion actions
|
||||
|
||||
---
|
||||
|
||||
## When to Use Server-Side Tracking
|
||||
|
||||
Browser-only tracking is increasingly unreliable due to:
|
||||
- iOS 14+ App Tracking Transparency
|
||||
- Third-party cookie deprecation
|
||||
- Ad blockers (30%+ of tech audiences)
|
||||
|
||||
**Use server-side (CAPI/Events API) when:**
|
||||
- Running Meta or TikTok ads (strongly recommended)
|
||||
- Your audience is tech-savvy (higher ad blocker usage)
|
||||
- You need accurate purchase/revenue attribution
|
||||
- You're spending >$5K/month on any platform
|
||||
|
||||
**Server-side is optional when:**
|
||||
- Running Google Ads only (Enhanced Conversions covers most gaps)
|
||||
- Low ad spend / testing phase
|
||||
- B2B with LinkedIn only (Insight Tag is still reliable)
|
||||
@@ -0,0 +1,120 @@
|
||||
# Google Search Playbook (B2B)
|
||||
|
||||
Intent-first operating rules for Google Ads: where to spend first, how to structure the account, when to loosen match types, and how to keep smart bidding pointed at revenue instead of junk form-fills. For RSA generation mechanics, see [rsa-output-spec.md](rsa-output-spec.md).
|
||||
|
||||
## Contents
|
||||
|
||||
- The intent ladder
|
||||
- Brand bidding (and the pause test)
|
||||
- Capture before you create
|
||||
- Account structure
|
||||
- Keywords and match types
|
||||
- Negative keywords
|
||||
- The weekly search-terms ritual
|
||||
- Bidding by conversion volume
|
||||
- Offline conversions
|
||||
- Quality Score and landing pages
|
||||
- PMax for B2B
|
||||
- Benchmarks and the weekly scorecard
|
||||
|
||||
## The intent ladder
|
||||
|
||||
Spend opens rung by rung — each tier unlocks only after the one below proves it converts to *pipeline*:
|
||||
|
||||
1. **Brand** — "they want you" (brand name, brand + pricing/login). Cheapest clicks, highest conversion. Always on.
|
||||
2. **High-intent non-brand** — ready to buy ("cold email software," "best CRM for agencies"). The profit center; most budget lives here.
|
||||
3. **Competitor** — evaluating alternatives ("[competitor] alternative/vs"). Higher CPC, lower CVR; run selectively with dedicated comparison pages.
|
||||
4. **Problem-aware** — has the problem, isn't shopping ("how to scale outbound"). Longer payback; only after tiers 1–2 work.
|
||||
5. **Demand-gen/awareness** — broad, Display, YouTube. Last, with spare budget only.
|
||||
|
||||
**Don't skip rungs.** Broad spend before high-intent proof is how B2B accounts burn budgets with nothing in the CRM.
|
||||
|
||||
## Brand bidding (and the pause test)
|
||||
|
||||
Bid on brand by default — if you don't, competitors will, and you pay in lost deals rather than clicks. The exception: if you're the only bidder and organic owns the whole SERP, test pausing brand and watch **total brand conversions (paid + organic)**, not just paid. If total holds, you were cannibalizing yourself; if it drops, turn it back on. Cap brand budget — it rarely needs much, and shared budgets let brand eat everything (see below).
|
||||
|
||||
## Capture before you create
|
||||
|
||||
Search **harvests existing demand**; it cannot create demand. If your category has near-zero search volume, say so and put the budget upstream (LinkedIn/Meta/YouTube) instead of forcing keywords nobody types. Demand creation happens on social; Search is where you catch it landing.
|
||||
|
||||
## Account structure
|
||||
|
||||
Minimum viable split — each with an **independent budget**:
|
||||
|
||||
- **Brand** (own budget — never shared)
|
||||
- **Non-brand high-intent** (one campaign, themed ad groups by solution)
|
||||
- **Competitor** (own budget and messaging — its CPC/CVR economics are different)
|
||||
- **Remarketing** (separate from Search)
|
||||
|
||||
Why independent budgets: in a shared budget the cheapest, highest-converting campaign (always brand) starves the ones you actually need data from. The account looks profitable on paper and is blind everywhere that matters.
|
||||
|
||||
- **Themed ad groups, not SKAGs:** 5–15 closely related keywords sharing one intent, answerable by one promise. If two keywords need different landing pages or value props, split the group. 2–3 RSAs per ad group.
|
||||
- **Consolidation rule:** a campaign that can't reach ~15–30 conversions/month can't feed smart bidding — merge it. Fewer, better-fed campaigns beat elaborate structures in low-volume B2B.
|
||||
- **Default settings to flip on every new Search campaign:** turn OFF Search Partners and Display Network until proven; set location targeting to **"Presence"** (people physically in the target geo — the default "presence or interest" serves people merely interested in it); remember language targeting keys off the user's Google interface language, not the query language.
|
||||
- **Don't compete with yourself:** the same keyword at the same match type in multiple ad groups splits your data and bids against your own account. Use negatives to route each query to exactly one home.
|
||||
|
||||
## Keywords and match types
|
||||
|
||||
Source keywords from how **buyers describe the problem** (sales-call language, your own search-terms report, competitor ad copy) — not how you describe the product. A keyword with 50 searches/month and clear intent beats one with 5,000 and mixed intent. Tag every keyword by intent tier.
|
||||
|
||||
**Match-type progression — in this order:**
|
||||
|
||||
1. Start high-intent terms on **Phrase + Exact** (Exact still matches close variants; Phrase is the B2B workhorse), manual CPC or Max Conversions while volume is low.
|
||||
2. Mine the search-terms report weekly (ritual below).
|
||||
3. Introduce **Broad only after**: 30+ conversions/month in the campaign, AND smart bidding live, AND a tight negative list. Broad without all three is a donation to Google.
|
||||
|
||||
## Negative keywords
|
||||
|
||||
Starter lists to apply at build time:
|
||||
|
||||
- **Universal junk:** free, cheap, jobs, salary, hiring, career, intern, student, course, tutorial, training, certification, pdf, template, reddit, wiki, login (except in brand campaigns)
|
||||
- **Research intent:** "what is," "how to," "examples," "meaning," "definition"
|
||||
- **Category collisions:** terms your category shares with an unrelated one (selling sales-engagement? negative "employee engagement")
|
||||
- **Your brand as a negative in non-brand campaigns** — routes brand traffic to the brand campaign where it belongs
|
||||
|
||||
**Match-type mechanics gotcha:** negative broad requires ALL its words present (any order) — negative broad "free trial" does **not** block "free" alone. Negative phrase blocks in-order phrases; negative exact blocks only that exact query. Most accidental over-blocking and under-blocking traces to this.
|
||||
|
||||
**Don't over-negative:** every negative narrows reach, and it compounds fast at B2B volumes. Negative the clearly wrong, not the merely uncertain — an ambiguous term deserves more data before it's cut.
|
||||
|
||||
## The weekly search-terms ritual
|
||||
|
||||
Once a week per campaign, three passes:
|
||||
|
||||
1. **Waste:** terms with spend (3+ clicks) and zero conversions → negative the irrelevant ones.
|
||||
2. **Winners:** converting search terms that aren't keywords yet → add as Exact/Phrase in the right ad group.
|
||||
3. **Drift:** broad/phrase matches pulling adjacent-but-wrong meanings → tighten the match type or negative the drift.
|
||||
|
||||
## Bidding by conversion volume
|
||||
|
||||
| Conversions/month (campaign) | Strategy |
|
||||
|---|---|
|
||||
| 0–15 | Manual CPC or Maximize Conversions (no target) |
|
||||
| 15–30 | Maximize Conversions |
|
||||
| 30+ stable | Target CPA — set at or slightly above your trailing 30-day actual |
|
||||
| Real revenue values flowing back | Target ROAS |
|
||||
|
||||
Rules of thumb: smart bidding needs ~30 conversions in 30 days per campaign to learn. Set tCPA near actuals — an aggressively low target chokes delivery (Google just stops bidding). Move targets in **±10–15% steps and wait 1–2 weeks**; every change restarts learning, so don't panic-edit inside the learning window. Budget mechanics: campaigns can spend up to **2× daily budget** in a day (Google balances monthly — single-day overspend is normal); a budget-capped campaign that's converting often *lowers* its CPA when you raise the budget, because constrained smart bidding underperforms.
|
||||
|
||||
## Offline conversions
|
||||
|
||||
The single highest-impact move in a B2B Google account: **import CRM outcomes** (SQL, opportunity, closed-won) back into Google via GCLID + offline conversion import or a native CRM integration, with real deal values. Until then, smart bidding optimizes to form-fills and buys you junk (see the optimize-to-quality trap in [b2b-paid-playbook.md](b2b-paid-playbook.md)). B2B clicks close in 60–180 days — in-platform conversion counts will never tell the truth on their own. Reconcile against the CRM monthly; the CRM wins.
|
||||
|
||||
## Quality Score and landing pages
|
||||
|
||||
QS (1–10, per keyword) = expected CTR + ad relevance + landing page experience. Low QS means paying more for the same position — **fix the weak component before raising the bid.** Landing page rules that move it: message match (page headline echoes the ad's promise and the query — not a generic homepage); one job and one CTA per page; speed; proof above the fold. **Form length is an intent gate:** short forms buy volume at lower quality, longer qualified forms buy fewer/better — match it to what you're feeding back as the conversion event.
|
||||
|
||||
## PMax for B2B
|
||||
|
||||
Value ranking: **brand Search > high-intent non-brand Search > remarketing > PMax > broad demand-gen.** PMax earns budget only after the cheaper, clearer wins are maxed. Never run it as the first campaign, on weak tracking, or on tiny budgets.
|
||||
|
||||
Guardrails when you do run it: account-level **brand exclusions** (or it cannibalizes brand Search and claims the credit); audience signals from first-party data; negative keywords from day one; offline conversions imported *before* scaling it; check the CRM quality of PMax leads by campaign — if they convert to pipeline at half the rate of Search leads, PMax is cheap-looking and expensive-in-reality. Google auto-generates a bad video if you don't supply one.
|
||||
|
||||
## Benchmarks and the weekly scorecard
|
||||
|
||||
B2B SaaS Search ranges (wide on purpose — anchor to your own first 30 days): brand CTR 8–20%, CVR 15–40%; non-brand high-intent CTR 2–6%, CVR 3–10%, CPC $8–40+, CPL $80–400+; competitor terms run higher CPC and lower CVR than non-brand.
|
||||
|
||||
Weekly scorecard — exactly eight numbers: spend · leads · CPL · lead→SQL rate (from CRM) · SQLs · cost per SQL · Search impression share · top wasted search terms. Diagnostic: **Search Lost IS (budget)** vs **Lost IS (rank)** tells you whether you're capped by money or by Ad Rank — different problems, different fixes. If the eight are healthy and trending right, the account is healthy.
|
||||
|
||||
---
|
||||
|
||||
*Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks are practitioner-reported starting points — recalibrate against your own account.*
|
||||
@@ -0,0 +1,107 @@
|
||||
# LinkedIn B2B Playbook
|
||||
|
||||
Operational rules for LinkedIn Ads: bidding, audience sizing, scaling triggers, benchmarks, and format-specific tactics. LinkedIn is the precision channel — highest-quality B2B targeting at the highest cost, so the operating discipline is about not wasting that precision.
|
||||
|
||||
## Contents
|
||||
|
||||
- Bidding progression
|
||||
- Audience sizing rules
|
||||
- Job functions vs. job titles
|
||||
- Audience splitting rules
|
||||
- Penetration-based scaling
|
||||
- Benchmarks by funnel stage
|
||||
- Thought leader ads (TLAs)
|
||||
- Campaign group build order
|
||||
- Format notes (document, conversation, CTV)
|
||||
- Retargeting setup (non-retroactive!)
|
||||
- Account audit shortlist
|
||||
|
||||
## Bidding progression
|
||||
|
||||
1. **Week 1:** launch on automated bidding / maximum delivery. Don't touch it — you're buying CPC data.
|
||||
2. **Week 2+:** switch to manual CPC set **~20% below the average CPC** the automated phase produced. This reliably cuts CPC without killing delivery.
|
||||
3. **Exceptions:** small retargeting/ABM audiences stay on automated (manual underdelivers on small pools); reset to automated for a week whenever you change objective; audiences under ~10K may never spend their full budget at any bid.
|
||||
|
||||
Scheduling note: LinkedIn's ad day resets at UTC midnight. Professional activity peaks weekday mornings–early afternoon in the audience's timezone; dayparting there stretches limited budgets.
|
||||
|
||||
## Audience sizing rules
|
||||
|
||||
- **Cold prospecting:** 50K–300K members. Minimum ~15K per cold campaign.
|
||||
- **Too-narrow failure mode:** hyper-narrow audiences spike CPMs several-fold and stall delivery entirely — budget won't spend at any bid. If it's not spending, the audience is usually too small, not the bid too low.
|
||||
- **Tiny TAM (<~30K addressable):** skip the TOF/BOF split — run one campaign that saturates the whole audience with all funnel layers.
|
||||
- **Retargeting:** audiences of roughly 1K–5K per segment (site visitors, 50%+ video viewers) are workable; below ~300 won't deliver.
|
||||
|
||||
## Job functions vs. job titles
|
||||
|
||||
Title targeting is precise but small and expensive. **Job function + seniority** targeting typically triples the addressable audience with materially cheaper reach at similar engagement — at the cost of a weekly "negative title" exclusion pass for the first ~2 months (like negative keywords: exclude irrelevant titles as they show up in demographics).
|
||||
|
||||
Platform gotchas:
|
||||
- **Job-title targeting and seniority targeting are mutually exclusive** — you can't stack them. Entry-level exclusions only work under function/seniority targeting.
|
||||
- The **Business Development function includes many CEOs, CMOs, and managing directors.** Don't blanket-exclude BD if you sell to the C-suite — filter with seniority exclusions instead.
|
||||
- Leave **Audience Expansion OFF** (it quietly spends a meaningful share of budget on out-of-ICP members) and **Audience Network OFF** for B2B lead gen.
|
||||
|
||||
## Audience splitting rules
|
||||
|
||||
Split priority: **intent > persona > region/company size > seniority.**
|
||||
|
||||
- **Region:** keep the US separate (most expensive market — grouped with cheaper regions, it eats the budget). DACH needs localized ads; UK/Canada/Australia group fine; Nordics/Netherlands run fine in English. Never group an expensive market with small ones.
|
||||
- **Company size:** segment by employee count (not revenue — LinkedIn's revenue data is estimated). Start with two bands, not three. Left unsegmented, LinkedIn over-serves the extremes (small companies and very large ones) and underserves mid-market — splitting forces fair distribution.
|
||||
|
||||
## Penetration-based scaling
|
||||
|
||||
Audience penetration (reached ÷ audience size) is the scaling trigger, not spend:
|
||||
|
||||
- 30-day penetration **<25%** → room to raise budget on this audience.
|
||||
- **25–35%** → hold; let penetration accumulate before adding spend.
|
||||
- **~35%+** = healthy saturation → scale horizontally (new audiences), not vertically.
|
||||
- Expect diminishing returns: doubling budget grows penetration ~50–70%, not 100%.
|
||||
- One campaign at 35%+ penetration beats three campaigns at 12% each — consolidate before multiplying.
|
||||
- **Spend rising but reach flat (frequency climbing)?** Either competitors outbid you or ad quality is dragging your auction price. Strong ads → raise budget/bids; weak ads → fix creative first, more money just buys the same people again.
|
||||
|
||||
## Benchmarks by funnel stage
|
||||
|
||||
Practitioner-reported B2B SaaS ranges — recalibrate on your own account. **Careful:** for engagement-objective and thought-leader campaigns, LinkedIn's reported "CTR" includes social actions; judge traffic on **click-through to landing page (CTRTLP)** specifically.
|
||||
|
||||
| Metric | Cold / TOF | MOF | BOF/retargeting |
|
||||
|---|---|---|---|
|
||||
| CTRTLP | 0.30–0.55% | 0.55–0.80% | 0.80–1.30% |
|
||||
| CPM | $33–65 typical | — | — |
|
||||
| CPC | $8–22+ | — | lower |
|
||||
| Cost per lead (Lead Gen Form) | — | $50–200 | — |
|
||||
| Cost per website form fill | — | — | $200–500 |
|
||||
|
||||
Other useful bars: lead-gen form fill rate >8% (below = form too long, offer weak, or audience too cold); cost per SQL should stay under ~$500 (enterprise ACVs tolerate $300–500+ CPLs; SMB needs $50–150); video view rate >40%, completion 8–15% for horizontal; expect return data to lag 3–6 months.
|
||||
|
||||
## Thought leader ads (TLAs)
|
||||
|
||||
Ads promoted from a person's profile rather than the company page — currently the platform's biggest efficiency arbitrage:
|
||||
|
||||
- TLAs typically deliver **~3–6× the CTR of company-page ads** at a fraction of the CPC.
|
||||
- **Non-employee/creator TLAs often outperform employee TLAs** — partnerships with niche creators are worth 30–50% of TLA budget if available.
|
||||
- **Organic-first pipeline:** posts that hit ~2–3% organic CTR are your TLA candidates — the audience already voted.
|
||||
- **The 72-hour edit:** organic reach concentrates in a post's first ~3 days. Let it run organic, then edit the post to add the CTA/product mention and promote it as a TLA — you capture organic credibility first, then convert it to demand gen.
|
||||
- Auction insight: single-image ads face the most auction competition. Document, conversation, and TLA formats often buy cheaper reach purely because fewer advertisers use them — format diversification is a *bidding* tactic, not just creative variety.
|
||||
|
||||
## Campaign group build order
|
||||
|
||||
Add groups in ROI order, funding each before the next: **1. Product value** (direct response on your core offer) → **2. Remarketing** → **3. Content** (only content that can't be consumed in-feed — it must earn the click) → **4. Social proof** (case studies, testimonials) → **5. Thought leadership** (slowest payback, add last). Group-budget optimization tends to favor cheap audiences and video — don't mix enterprise with SMB or static with video in one group.
|
||||
|
||||
## Format notes
|
||||
|
||||
- **Document ads:** always 1080×1350 portrait (4:5). 5–7 slides: hook → pain → shift → solution → differentiators → CTA. The classic mistake is making the "solution" slide generic category requirements and the "differentiator" slide a rehash — slide N must add what slide N-1 couldn't. Big standalone stat slides (one number, source small) carry these.
|
||||
- **Conversation ads:** subject 2–4 words; 3–5 short lines per message; specific numbers beat vague benefit claims; lead with a soft CTA ("see how it works") over "book a demo"; route the primary CTA to a Lead Gen Form, not a scheduling link. Benchmarks: 35–50%+ open rate, 2–5% CTR.
|
||||
- **CTV:** Brand Awareness objective only, auto-bid only, ~$50/day minimum, limited geos. Completion metrics are meaningless (forced view). Only worth it above roughly $15K/month total spend — below that it cannibalizes measurable-signal budget.
|
||||
|
||||
## Retargeting setup (non-retroactive!)
|
||||
|
||||
**LinkedIn retargeting audiences only start collecting from the moment you create them.** Create every retargeting audience you might ever want (site visitors, video viewers, ad engagers, lead-form openers, company page visitors) **before launch** — data you didn't capture is gone permanently.
|
||||
|
||||
Cross-channel: tag paid-search traffic with UTMs and build LinkedIn (and Meta) retargeting audiences from it — see the [ABM playbook](abm-playbook.md) for the mechanic.
|
||||
|
||||
## Account audit shortlist
|
||||
|
||||
The highest-frequency findings when auditing LinkedIn accounts, in order: Audience Expansion left on · Audience Network left on · audiences too small to deliver · fewer than 4 active ads per campaign · campaigns under ~10 results/week (starved — consolidate) · stale creative (3+ months old) · no retargeting audiences created · lead quality never reconciled against CRM · brand/geo budget mixing · everything on automated bidding forever.
|
||||
|
||||
---
|
||||
|
||||
*Framework lineage: adapted (re-expressed and restructured) from practitioner playbooks, notably Ivan Falco's ads-skills. Benchmarks are practitioner-reported starting points — recalibrate against your own account.*
|
||||
@@ -0,0 +1,143 @@
|
||||
# Meta Decision System (B2B)
|
||||
|
||||
A quantified kill/keep/scale engine for Meta ads. Every threshold derives from one anchor number, so decisions become arithmetic instead of vibes. Pairs with the strategy-level Meta playbook in SKILL.md (creative-as-targeting, creative volume) — this file is the *operating* layer.
|
||||
|
||||
## Contents
|
||||
|
||||
- TCPL: the anchor variable
|
||||
- The ad-count ceiling
|
||||
- Two-campaign structure (Scaling / Testing)
|
||||
- Stage 1: delivery check (day 7)
|
||||
- Stage 2: quality evaluation (weekly)
|
||||
- Graduation criteria
|
||||
- Fatigue detection
|
||||
- Swap rules
|
||||
- Creative production math
|
||||
- Scaling protocol
|
||||
- Weekly cadence
|
||||
- Lead forms and social amnesia
|
||||
- Advantage+ transition
|
||||
- Benchmarks and seasonality
|
||||
|
||||
## TCPL: the anchor variable
|
||||
|
||||
TCPL = **Target Cost Per Qualified Lead** (qualified = meets your ICP bar, not just a form-fill). Set it one of three ways:
|
||||
|
||||
1. **From deal math (best):** TCPL = target cost per demo × qualified-lead-to-demo rate. ($2,000/demo × 0.28 = $560.)
|
||||
2. **From history:** TCPL = trailing 30-day CPL(qualified) × 0.80 — a 20% improvement is achievable through operational cleanup alone (killing zero-QL ads, graduating winners). Once you have both, use whichever is tighter.
|
||||
3. **New account:** target CAC × qualified-lead-to-customer rate, or a placeholder from your ACV tier; replace with method 2 after 30 days.
|
||||
|
||||
Every rule below is expressed in multiples of TCPL. Review TCPL monthly.
|
||||
|
||||
## The ad-count ceiling
|
||||
|
||||
More active ads than your budget can feed = every ad starves and nothing gets a fair read.
|
||||
|
||||
**Ceiling = (daily budget × 14) / (2 × TCPL)** — i.e., over a 14-day evaluation window, each ad needs at least 2× TCPL of spend to be judged.
|
||||
|
||||
$1,000/day at $500 TCPL → ceiling of 14 ads; run **6–10** (winners + 2–3 test slots). At the ceiling, launching a new test requires killing something first.
|
||||
|
||||
## Two-campaign structure (Scaling / Testing)
|
||||
|
||||
Run two CBO campaigns over the **same audience**:
|
||||
|
||||
- **Scaling campaign (~80% of budget)** — holds only graduated, proven ads.
|
||||
- **Testing campaign (~20%)** — holds new concepts and iterations, with its own protected budget.
|
||||
|
||||
Why: inside a single CBO, proven ads always starve new ads — tests never get enough spend to be judged. Why not ABO for testing: equal forced distribution keeps spending on ads Meta has already deprioritized. The separation is *budget protection*, not audience segmentation.
|
||||
|
||||
**Image-first validation:** launch new concepts as statics first; only produce the video/carousel/UGC version after the image passes the checks below. Exception: concepts that are inherently video (testimonial, demo, UGC).
|
||||
|
||||
## Stage 1: delivery check (day 7)
|
||||
|
||||
CBO's spend allocation is itself a signal — Meta pre-screens your ads. At day 7 for each test ad:
|
||||
|
||||
- **Fair share test:** minimum expected spend = (campaign daily budget ÷ active ads) × 7 × 0.5. Below that → **kill** (Meta actively deprioritized it). Zero spend → kill immediately.
|
||||
- **Ongoing:** if an ad has spent ≥ 1× TCPL lifetime AND averaged under ~$10/day over the last 7 days → kill. (The lifetime-spend gate stops you from killing ads CBO simply hasn't explored yet.)
|
||||
|
||||
When iterating on a delivery-killed ad, change the **hook/visual/format only** — the audience never got far enough for copy or CTA to matter.
|
||||
|
||||
## Stage 2: quality evaluation (weekly, rolling 14-day data)
|
||||
|
||||
Run in order; stop at the first triggered action:
|
||||
|
||||
1. **Data gate:** spend < 3× TCPL → **wait** (not enough signal). At true cost-per-QL = target, 3× TCPL of spend should produce ~3 qualified leads; zero QLs at that spend is ~5% probability — so judging at 3× gives ~95% confidence without wasting budget (2× has a 13% false-negative rate; 5× overpays for certainty).
|
||||
2. **Zero pixel leads** at ≥3× TCPL → **swap and abandon the concept** (don't iterate a dead concept).
|
||||
3. **Quality check** (the layer Meta can't see — requires your CRM):
|
||||
- Pixel leads but zero qualified → swap; keep the format, change the angle.
|
||||
- Qualified rate <40% → swap; the ad attracts the wrong people. Add ICP-filtering language. (At 40% QL rate, true cost per QL is 2.5× the pixel CPL you see in Ads Manager — two ads identical in-platform can differ 60%+ in real cost.)
|
||||
- 40–60% → monitor one more week. ≥60% → proceed.
|
||||
4. **Cost check:** cost per QL ≤ TCPL → candidate winner. 1–1.5× TCPL → monitor (normal variance). >1.5× TCPL → swap (structural underperformance, not noise).
|
||||
|
||||
## Graduation criteria (Testing → Scaling)
|
||||
|
||||
Graduate only when **all** are true: ≥5 qualified leads · qualified rate ≥60% · cost per QL ≤ TCPL · running ≥14 days · ≥1 QL in the last 7 days.
|
||||
|
||||
## Fatigue detection
|
||||
|
||||
Frequency bands by campaign type (safe / warning / critical):
|
||||
|
||||
| Campaign type | Safe | Warning | Critical |
|
||||
|---|---|---|---|
|
||||
| Cold prospecting | 1.0–2.5 | 2.5–4.0 | >4.0 |
|
||||
| Retargeting | 2.0–4.0 | 4.0–6.0 | >6.0 |
|
||||
| ABM (small audiences) | 2.0–5.0 | 5.0–8.0 | >8.0 |
|
||||
|
||||
Other signals, in urgency order: CTR down 20%+ from baseline over 7 days; CPM up 30%+ over 2 weeks (leading indicator — moves before CTR); ad relevance rankings "below average"; CPA up with stable targeting.
|
||||
|
||||
For **scaling-campaign ads**, apply a deliberately stricter bar than the general bands — these ads carry ~80% of spend, so fatigue there costs the most: warning at frequency 3.0–3.5 or cost +20% → start 2 iterations now (they take ~14 days to be ready); swap at >3.5, cost +40%, or >1.5× TCPL for 2 weeks.
|
||||
|
||||
**Lifespan expectations (B2B):** statics 14–28 days; short video and carousels 21–35; UGC/testimonial 28–42. Small B2B audiences build frequency fast — plan refresh every 14–21 days.
|
||||
|
||||
**Retire (don't iterate)** when CTR drops 30%+ from peak or frequency crosses the campaign type's critical band above — the concept is exhausted, not the execution.
|
||||
|
||||
**Rotation without resetting learning:** never edit creative inside a performing ad — that resets the learning phase. Launch new ads alongside existing ones, or spin up a new ad set with the same targeting. Pausing doesn't reset; editing does.
|
||||
|
||||
## Swap rules
|
||||
|
||||
**Never pause without a replacement.** Keep 2–3 iterations staged; replacement live within 7 days, immediately for critical fatigue. If the pipeline is empty, redirect the budget to proven ads rather than leaving a zombie running. What to change depends on why it died: delivery kill → hook/visual; quality kill → angle and ICP language; cost kill → offer and audience; fatigue → fresh execution of the same proven concept.
|
||||
|
||||
## Creative production math
|
||||
|
||||
- **Test throughput** ≈ (monthly budget × 0.20) ÷ (3 × TCPL), per month. Delivery kills free budget early, so actual throughput runs ~1.5–2× the base rate.
|
||||
- **Win rates:** iterations on winners ~25%; brand-new concepts ~10%; blended ~1 in 6. To get N winners, plan ~6× N tests.
|
||||
- **Minimum proven-ad inventory** ≈ monthly budget ÷ $5,000 — each proven B2B ad absorbs roughly $5K/month before fatiguing. **You cannot scale budget ahead of creative supply**; if proven ads < minimum, fix the creative deficit before raising budget.
|
||||
- **Iteration priority** when refreshing a winner (ranked by impact): 1. hook (changes who stops) → 2. visual treatment → 3. format → 4. body copy/CTA.
|
||||
|
||||
## Scaling protocol
|
||||
|
||||
Scale only when all: proven-ad count meets the next budget level's minimum; account frequency <3.0; cost per QL ≤ TCPL for 2+ consecutive weeks; 3+ replacements staged.
|
||||
|
||||
- **Rate:** +20% every 5 days. Never +30% or more in one move — that resets learning.
|
||||
- **Rollback trigger:** cost per QL >1.5× TCPL after a scale step → cut budget 20–30% immediately, stabilize 2 weeks, resume at +10% per week.
|
||||
- **Hitting the wall** (account-wide average frequency >3.5 — an account-level *scale* guardrail, distinct from the per-ad fatigue bands above): expand lookalikes 1% → 2–3%, add new seed audiences, test broad, activate cross-channel UTM audiences (see [ABM playbook](abm-playbook.md)), re-open remarketing.
|
||||
|
||||
## Weekly cadence
|
||||
|
||||
- **Monday — decision day:** pull rolling 14-day data; run Stage 2 on every test ad; run the fatigue check on every scaling ad.
|
||||
- **Wednesday — launch day:** launch new tests into freed slots; run Stage 1 on ads that hit day 7.
|
||||
- **Friday — scaling day:** apply scale steps or rollbacks.
|
||||
- **Monthly:** creative library audit + TCPL review.
|
||||
|
||||
## Lead forms and social amnesia
|
||||
|
||||
The #1 B2B Meta lead-quality problem: frictionless auto-filled forms produce leads who don't remember converting ("social amnesia"). **Intentional friction = awareness = quality:**
|
||||
|
||||
- Use **Higher Intent** form type (adds a review step), not More Volume.
|
||||
- **Require work email** — it can't auto-fill from the Facebook profile, forcing a conscious act. This is the single biggest quality lever.
|
||||
- Add 1–3 multiple-choice qualification questions (4+ spikes abandonment), ordered easiest → hardest.
|
||||
- Confirmation message sets expectations for what happens next (combats amnesia at the follow-up stage).
|
||||
|
||||
Lead form vs. landing page: LP converting ≥5% → use the LP; LP under ~2% → lead form; demo/trial offers → LP; content/webinar → form.
|
||||
|
||||
## Advantage+ transition
|
||||
|
||||
Manual is where you learn; Advantage+ is where you earn. Transition a campaign to Advantage+ only after: a proven offer, a validated audience, and **~50 conversions/week** on the optimization event (the learning-phase exit bar — budget needed ≈ target CPA × 50 ÷ 7 per day). If you can't hit 50/week on the target event, optimize a higher-volume event up-funnel and retarget converters. Advantage+ conflicts with strict ABM (you can't lock it to a list) — see the [ABM playbook](abm-playbook.md). Watch Campaign Score directionally (70+ healthy, <50 = fighting the algorithm) but never trade lead quality for score.
|
||||
|
||||
## Benchmarks and seasonality
|
||||
|
||||
B2B SaaS Meta ranges (practitioner-reported; recalibrate on your own first 30 days): CTR 1.0–1.5% (red flag <0.8%); CPM $10–20 (red flag >$25); CPL (form) $20–50 (red flag >$75); landing page CVR 8–12%. Seasonality: Q1 CPMs are the year's lowest (scale aggressively); Q4 runs +60–80% (consider reducing B2B spend and banking budget for January).
|
||||
|
||||
---
|
||||
|
||||
*Framework lineage: this decision system is adapted (re-expressed, reconciled, and restructured) from practitioner operating systems, notably Ivan Falco's ads-skills. All thresholds are starting points — recalibrate against your own account.*
|
||||
@@ -0,0 +1,88 @@
|
||||
# Google RSA Output Spec
|
||||
|
||||
When the user requests Google Ads RSAs (Responsive Search Ads), output MUST comply with these platform limits and structural requirements. Do not output any RSA that violates them.
|
||||
|
||||
## Hard limits per RSA (enforce before responding)
|
||||
|
||||
- **Headlines:** exactly **15** per RSA, each **≤ 30 characters** (count characters, including spaces). Render as `1. ... (NN chars)` so the reader can verify.
|
||||
- **Descriptions:** exactly **4** per RSA, each **≤ 90 characters**.
|
||||
- **Paths:** up to 2 path fields, each **≤ 15 characters**.
|
||||
- **Final URL:** present, https.
|
||||
- **Pinning:** state any pinned positions explicitly. Default = unpinned unless user asks.
|
||||
- **Per-account guardrail:** Google enforces **3 RSAs max per ad group**. When the user asks for >3, group them by ad group.
|
||||
|
||||
## Required sidecar artifacts (always include with RSA request)
|
||||
|
||||
1. **Ad group structure**, labeled `Ad group structure:` — list each ad group with its theme, target keywords (match types), and which RSAs map to it.
|
||||
2. **Negative keyword list**, labeled `Negative keywords:` — minimum **8** entries, group-level vs campaign-level called out.
|
||||
3. **Sitelinks** (≥ 4), **Callouts** (≥ 4 ≤25 chars), **Structured snippets** if relevant.
|
||||
|
||||
## Medical / CFM compliance (when product context indicates pt-BR medical practice)
|
||||
|
||||
If `.agents/product-marketing.md` indicates a Brazilian medical practice (CFM-regulated), the following terms are **forbidden** in headlines, descriptions, sitelinks, and callouts:
|
||||
|
||||
- Superlatives: `#1`, `melhor`, `o melhor`, `melhor do brasil`, `top`, `referência`
|
||||
- Outcome promises: `garantido`, `garantia`, `cura`, `cura definitiva`, `100%`, `resultado garantido`, `livre da dor`
|
||||
- Comparative claims vs other doctors/clinics
|
||||
|
||||
Use neutral framing: `atendimento`, `consulta`, `avaliação`, `segunda opinião`, `agende sua consulta`, `tire suas dúvidas`. Geo modifier (`Porto Alegre`, `POA`, `Zona Sul POA`) required where the prompt specifies a region.
|
||||
|
||||
## Output ORDER (mandatory — emit in this order to avoid truncation)
|
||||
|
||||
1. **Ad group structure** (short)
|
||||
2. **Negative keywords** (≥8, MANDATORY — emit BEFORE RSAs so it isn't dropped if output runs long)
|
||||
3. **Sitelinks** (≥4)
|
||||
4. **Callouts** (≥4)
|
||||
5. **RSA1, RSA2, RSA3** (largest section, last — safe to truncate gracefully)
|
||||
|
||||
## Output template (mandatory shape)
|
||||
|
||||
```
|
||||
Ad group structure:
|
||||
- AG1 [theme]: keywords (match types) → RSA1, RSA2
|
||||
- AG2 [theme]: ...
|
||||
|
||||
Negative keywords:
|
||||
Campaign-level:
|
||||
- <kw>
|
||||
- <kw>
|
||||
(≥4 here)
|
||||
Ad-group level:
|
||||
- AG1: <kw>, <kw>
|
||||
- AG2: <kw>, <kw>
|
||||
(≥4 more here — TOTAL ≥8 entries)
|
||||
|
||||
Sitelinks (≥4):
|
||||
- <title (≤25)> | <desc1 (≤35)> | <desc2 (≤35)> | URL
|
||||
|
||||
Callouts (≥4, each ≤25 chars):
|
||||
- <callout>
|
||||
|
||||
RSA1 — [ad group name]
|
||||
Final URL: https://...
|
||||
Path1: ... Path2: ...
|
||||
Headlines (15, each ≤30 chars):
|
||||
1. <headline> (NN chars)
|
||||
...
|
||||
15. <headline> (NN chars)
|
||||
Descriptions (4, each ≤90 chars):
|
||||
1. <description> (NN chars)
|
||||
...
|
||||
4. <description> (NN chars)
|
||||
Pinning: H1=none; H2=none; ... (or explicit pins)
|
||||
|
||||
RSA2 — ...
|
||||
RSA3 — ...
|
||||
```
|
||||
|
||||
## Self-check before responding
|
||||
|
||||
Before sending the output, run this checklist mentally:
|
||||
|
||||
- [ ] Each RSA has exactly 15 headlines, exactly 4 descriptions.
|
||||
- [ ] Every headline is ≤30 chars; every description is ≤90 chars. Character counts printed.
|
||||
- [ ] Negative keyword list labeled and ≥8 entries.
|
||||
- [ ] Ad group structure labeled.
|
||||
- [ ] If medical (CFM): no forbidden superlative/outcome words; geo modifier present where required; language is pt-BR.
|
||||
|
||||
If any check fails, rewrite before responding. Do not ship partial RSAs.
|
||||
+140
-49
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: ai-seo
|
||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' or 'zero-click search.' This skill covers content optimization for AI answer engines, monitoring AI visibility, and getting cited as a source. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema-markup."
|
||||
description: "When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers. Also use when the user mentions 'AI SEO,' 'AEO,' 'GEO,' 'LLMO,' 'answer engine optimization,' 'generative engine optimization,' 'LLM optimization,' 'AI Overviews,' 'optimize for ChatGPT,' 'optimize for Perplexity,' 'AI citations,' 'AI visibility,' 'zero-click search,' 'how do I show up in AI answers,' 'LLM mentions,' 'optimize for Claude/Gemini,' 'llms.txt,' 'OKF,' 'Open Knowledge Format,' 'knowledge bundle,' or 'agent-readable site.' Use this whenever someone wants their content to be cited or surfaced by AI assistants and AI search engines. For traditional technical and on-page SEO audits, see seo-audit. For structured data implementation, see schema."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.1.0
|
||||
---
|
||||
|
||||
# AI SEO
|
||||
@@ -12,7 +12,7 @@ You are an expert in AI search optimization — the practice of making content d
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
@@ -66,6 +66,45 @@ In traditional search, you need to rank on page 1. In AI search, a well-structur
|
||||
- Optimized content gets cited 3x more often than non-optimized
|
||||
- Statistics and citations boost visibility by 40%+ across queries
|
||||
|
||||
### Google's Official Stance vs. Multi-Platform Reality
|
||||
|
||||
This is important to read once before doing anything else.
|
||||
|
||||
**Google's position** ([AI features optimization guide](https://developers.google.com/search/docs/fundamentals/ai-optimization-guide)):
|
||||
> "The best practices for SEO continue to be relevant because our generative AI features on Google Search are rooted in our core Search ranking and quality systems."
|
||||
|
||||
Google explicitly says:
|
||||
- **No special markup or files are required** for AI Overviews or AI Mode
|
||||
- **Don't chunk content for AI** — write for people, organize with normal headings and paragraphs
|
||||
- **Don't write separate content for AI** — that risks "scaled content abuse" spam policy
|
||||
- **Helpful, reliable, people-first content** wins — same E-E-A-T standards as regular Search
|
||||
- **No AI-specific Search Console reporting** — use standard SEO metrics
|
||||
|
||||
**Other AI engines (ChatGPT, Claude, Perplexity, Copilot) behave differently:**
|
||||
- They actively reward extractable structure — passages, FAQs, comparison tables, definition blocks
|
||||
- They parse `llms.txt`, structured pricing pages, and machine-readable files when present
|
||||
- They cite third-party sources (Reddit, Wikipedia, review sites) more heavily than top-ranked pages
|
||||
|
||||
**What this means for the work:**
|
||||
- The structural patterns in this skill (40–60 word answer blocks, FAQ schema, comparison tables) help **non-Google AI engines** materially. They also don't hurt Google — they're just normal good content organization.
|
||||
- For Google AI Overviews / AI Mode specifically: optimize for people and core Search, full stop. Strong E-E-A-T, original information, semantic HTML, clean indexability.
|
||||
- For ChatGPT/Claude/Perplexity: layer on the extractable structure + llms.txt + machine-readable files.
|
||||
|
||||
When in doubt, default to "write for people, organize for clarity" — that satisfies both camps.
|
||||
|
||||
### Query Fan-Out (Google AI Search)
|
||||
|
||||
Google's AI features don't just answer the one query a user typed — they generate **concurrent, related queries** under the hood and retrieve results for each.
|
||||
|
||||
Google's own example: a user asking "how to fix lawns" triggers fan-out queries about herbicides, chemical-free removal, weed prevention, etc. The AI synthesizes across all of them.
|
||||
|
||||
**Implications:**
|
||||
- Single-page-per-keyword targeting is less effective. Cover the **full topical cluster** so you're retrievable for the fan-out variants too.
|
||||
- Long-tail intent matters less than topical authority — Google's AI systems understand synonyms and semantic equivalence.
|
||||
- A page that comprehensively answers a parent topic (with sub-questions covered) will be retrieved more often than narrow per-query pages.
|
||||
|
||||
**Action**: when planning content, brainstorm the 5–10 related queries the AI is likely to fan out to and make sure your content (or your site as a whole) covers them.
|
||||
|
||||
---
|
||||
|
||||
## AI Visibility Audit
|
||||
@@ -226,6 +265,58 @@ AI systems don't just cite your website — they cite where you appear.
|
||||
- Create YouTube content for key how-to queries
|
||||
- Answer relevant Quora questions with depth
|
||||
|
||||
### Machine-Readable Files for AI Agents
|
||||
|
||||
> **Google's stance**: not required for AI Overviews or AI Mode. Their guide explicitly says you don't need new markup, AI files, or markdown to appear in generative AI search.
|
||||
>
|
||||
> **Why include them anyway**: non-Google AI engines (ChatGPT, Claude, Perplexity) and autonomous buying agents do reward extractable structure. The files below help with those engines without harming Google.
|
||||
|
||||
AI agents aren't just answering questions — they're becoming buyers. When an AI agent evaluates tools on behalf of a user, it needs structured, parseable information. If your pricing is locked in a JavaScript-rendered page or a "contact sales" wall, agents will skip you and recommend competitors whose information they can actually read.
|
||||
|
||||
Add these machine-readable files to your site root:
|
||||
|
||||
**`/pricing.md` or `/pricing.txt`** — Structured pricing data for AI agents
|
||||
|
||||
```markdown
|
||||
# Pricing — [Your Product Name]
|
||||
|
||||
## Free
|
||||
- Price: $0/month
|
||||
- Limits: 100 emails/month, 1 user
|
||||
- Features: Basic templates, API access
|
||||
|
||||
## Pro
|
||||
- Price: $29/month (billed annually) | $35/month (billed monthly)
|
||||
- Limits: 10,000 emails/month, 5 users
|
||||
- Features: Custom domains, analytics, priority support
|
||||
|
||||
## Enterprise
|
||||
- Price: Custom — contact sales@example.com
|
||||
- Limits: Unlimited emails, unlimited users
|
||||
- Features: SSO, SLA, dedicated account manager
|
||||
```
|
||||
|
||||
**Why this matters now:**
|
||||
- AI agents increasingly compare products programmatically before a human ever visits your site
|
||||
- Opaque pricing gets filtered out of AI-mediated buying journeys
|
||||
- A simple markdown file is trivially parseable by any LLM — no rendering, no JavaScript, no login walls
|
||||
- Same principle as `robots.txt` (for crawlers), `llms.txt` (for AI context), and `AGENTS.md` (for agent capabilities)
|
||||
|
||||
**Best practices:**
|
||||
- Use consistent units (monthly vs. annual, per-seat vs. flat)
|
||||
- Include specific limits and thresholds, not just feature names
|
||||
- List what's included at each tier, not just what's different
|
||||
- Keep it updated — stale pricing is worse than no file
|
||||
- Link to it from your sitemap and main pricing page
|
||||
|
||||
**`/llms.txt`** — Context file for AI systems (see [llmstxt.org](https://llmstxt.org))
|
||||
|
||||
If you don't have one yet, add an `llms.txt` that gives AI systems a quick overview of what your product does, who it's for, and links to key pages (including your pricing).
|
||||
|
||||
**`/okf/` — Open Knowledge Format bundle (Google-backed, v0.1)**
|
||||
|
||||
Google [introduced OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) in June 2026 — a markdown spec for representing site content as a directory of cross-linked files with YAML frontmatter, agent-readable without scraping. Built primarily for data-team catalog metadata; the site-readable-by-agents repurposing was popularized by Suganthan Mohanadasan. No confirmed AI-search ranking signal today — treat it as protocol-layer registration like early schema.org. **For the full breakdown, implementation paths (free generator, WordPress plugin, by-hand), hosting guidance, and when to skip, see [references/okf.md](references/okf.md).**
|
||||
|
||||
### Schema Markup for AI
|
||||
|
||||
Structured data helps AI systems understand your content. Key schemas:
|
||||
@@ -240,7 +331,32 @@ Structured data helps AI systems understand your content. Key schemas:
|
||||
| Reviews | `Review`, `AggregateRating` | Trust signals |
|
||||
| Organization | `Organization` | Entity recognition |
|
||||
|
||||
Content with proper schema shows 30-40% higher AI visibility. For implementation, use the **schema-markup** skill.
|
||||
Content with proper schema shows 30-40% higher AI visibility on non-Google AI engines. **Google's note**: structured data is "not required for generative AI search" but is recommended for overall SEO strategy. For implementation, use the **schema** skill.
|
||||
|
||||
---
|
||||
|
||||
## Agentic Experiences
|
||||
|
||||
Beyond AI search engines summarizing content, autonomous agents are starting to access sites directly — clicking, reading, comparing, even buying on behalf of users. Google's guide flags this as an emerging category to plan for.
|
||||
|
||||
**How agents access your site:**
|
||||
- **Visual rendering** — they screenshot/read the page like a user would
|
||||
- **DOM inspection** — they parse the page's HTML structure
|
||||
- **Accessibility tree** — they rely on the same semantic information assistive tech uses (labels, roles, landmarks, headings)
|
||||
|
||||
**What to do:**
|
||||
- **Render meaningful content without heavy JS gymnastics** — if the page is blank until 4 frameworks finish loading, agents see blank
|
||||
- **Semantic HTML** — use `<main>`, `<nav>`, `<article>`, `<button>`, proper heading hierarchy, `alt` text on images
|
||||
- **Clean accessibility tree** — every interactive element labelled; ARIA used correctly (or not at all when native HTML suffices)
|
||||
- **Stable selectors / predictable layouts** — agents struggle with sites that re-render every interaction
|
||||
- **Visible pricing, specs, contact info** — anything an agent would need to make a buying recommendation should be on a public, indexable page (this is where `/pricing.md` and similar files help)
|
||||
|
||||
**Emerging — Universal Commerce Protocol (UCP):**
|
||||
Google references UCP as a forthcoming protocol that will give agents standardized hooks for commerce interactions (catalog discovery, pricing, checkout). Watch for adoption; for now, the structural recommendations above are the precursor.
|
||||
|
||||
For ecom and local business specifically, Google highlights:
|
||||
- **Merchant Center feeds** + **Google Business Profile** for product/service visibility in AI Search
|
||||
- **Business Agent** for conversational customer engagement (where applicable)
|
||||
|
||||
---
|
||||
|
||||
@@ -296,55 +412,29 @@ Monthly manual check:
|
||||
3. Record: Are you cited? Who is? What page?
|
||||
4. Log in a spreadsheet, track month-over-month
|
||||
|
||||
### Search Console expectations
|
||||
|
||||
Google's guide is explicit: **there is no AI-specific Search Console reporting**. AI Overviews and AI Mode use core Search ranking, so the standard Search Console reports (Performance, Coverage, Core Web Vitals) are still what you measure with for Google. The third-party tools above are the only way to see cross-platform AI citation behavior.
|
||||
|
||||
---
|
||||
|
||||
## AI SEO for Different Content Types
|
||||
## What NOT to Do
|
||||
|
||||
### SaaS Product Pages
|
||||
Google's guide calls these out explicitly — they hurt across both traditional Search and AI features.
|
||||
|
||||
**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.
|
||||
1. **Write separate content "for AI"**. Same content should serve people and AI. Writing variants targeted at AI systems risks the **scaled content abuse spam policy** — Google's words.
|
||||
2. **Chunk pages into AI-bait fragments**. Google's guide is direct: *"Don't break your content into tiny pieces for AI to better understand it."* Use normal paragraph + heading structure.
|
||||
3. **Generate at scale for ranking manipulation**. AI-generated content is fine *if* it meets Search Essentials and spam policies. Mass-producing thin variations does not.
|
||||
4. **Pursue inauthentic mentions**. Don't fabricate citations or bulk-spam Reddit/Wikipedia for AI visibility. Real participation only.
|
||||
5. **Block AI crawlers if you want citation**. Blocking GPTBot, PerplexityBot, ClaudeBot, Google-Extended means those engines literally cannot cite you. Block training-only crawlers (CCBot) if you must, not the search-and-cite ones.
|
||||
6. **Hide your main content behind JS that doesn't render**. Both core Search and AI agents need to see your content; JS-only rendering loses both audiences.
|
||||
7. **Skip E-E-A-T fundamentals**. Author identity, first-hand experience, expertise signals, transparent sourcing — Google's guide leans heavily on these for AI features.
|
||||
|
||||
**Optimize:**
|
||||
- Clear product description in first paragraph (what it does, who it's for)
|
||||
- Feature comparison tables (you vs. category, not just competitors)
|
||||
- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast")
|
||||
- Customer count or social proof with numbers
|
||||
- Pricing transparency (AI cites pages with visible pricing)
|
||||
- FAQ section addressing common buyer questions
|
||||
---
|
||||
|
||||
### Blog Content
|
||||
## AI SEO by Content Type
|
||||
|
||||
**Goal:** Get cited as an authoritative source on topics in your space.
|
||||
|
||||
**Optimize:**
|
||||
- One clear target query per post (match heading to query)
|
||||
- Definition in first paragraph for "What is" queries
|
||||
- Original data, research, or expert quotes
|
||||
- "Last updated" date visible
|
||||
- Author bio with relevant credentials
|
||||
- Internal links to related product/feature pages
|
||||
|
||||
### Comparison/Alternative Pages
|
||||
|
||||
**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries.
|
||||
|
||||
**Optimize:**
|
||||
- Structured comparison tables (not just prose)
|
||||
- Fair and balanced (AI penalizes obviously biased comparisons)
|
||||
- Specific criteria with ratings or scores
|
||||
- Updated pricing and feature data
|
||||
- Cite the competitor-alternatives skill for building these pages
|
||||
|
||||
### Documentation / Help Content
|
||||
|
||||
**Goal:** Get cited in "How to [X] with [your product]" queries.
|
||||
|
||||
**Optimize:**
|
||||
- Step-by-step format with numbered lists
|
||||
- Code examples where relevant
|
||||
- HowTo schema markup
|
||||
- Screenshots with descriptive alt text
|
||||
- Clear prerequisites and expected outcomes
|
||||
For tactical guidance on SaaS product pages, blog content, comparison/alternative pages, documentation, and local/ecom (Google's emphasis on Merchant Center + Business Profile), see [references/content-types.md](references/content-types.md).
|
||||
|
||||
---
|
||||
|
||||
@@ -353,11 +443,12 @@ Monthly manual check:
|
||||
- **Ignoring AI search entirely** — ~45% of Google searches now show AI Overviews, and ChatGPT/Perplexity are growing fast
|
||||
- **Treating AI SEO as separate from SEO** — Good traditional SEO is the foundation; AI SEO adds structure and authority on top
|
||||
- **Writing for AI, not humans** — If content reads like it was written to game an algorithm, it won't get cited or convert
|
||||
- **No freshness signals** — Undated content loses to dated content. Always show when content was last updated
|
||||
- **No freshness signals** — Undated content loses to dated content because AI systems weight recency heavily. Show when content was last updated
|
||||
- **Gating all content** — AI can't access gated content. Keep your most authoritative content open
|
||||
- **Ignoring third-party presence** — You may get more AI citations from a Wikipedia mention than from your own blog
|
||||
- **No structured data** — Schema markup gives AI systems structured context about your content
|
||||
- **Keyword stuffing** — Unlike traditional SEO where it's just ineffective, keyword stuffing actively reduces AI visibility by 10% (Princeton GEO study)
|
||||
- **Hiding pricing behind "contact sales" or JS-rendered pages** — AI agents evaluating your product on behalf of buyers can't parse what they can't read. Add a `/pricing.md` file
|
||||
- **Blocking AI bots** — If GPTBot, PerplexityBot, or ClaudeBot are blocked in robots.txt, those platforms can't cite you
|
||||
- **Generic content without data** — "We're the best" won't get cited. "Our customers see 3x improvement in [metric]" will
|
||||
- **Forgetting to monitor** — You can't improve what you don't measure. Check AI visibility monthly at minimum
|
||||
@@ -391,8 +482,8 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md).
|
||||
## Related Skills
|
||||
|
||||
- **seo-audit**: For traditional technical and on-page SEO audits
|
||||
- **schema-markup**: For implementing structured data that helps AI understand your content
|
||||
- **schema**: For implementing structured data that helps AI understand your content
|
||||
- **content-strategy**: For planning what content to create
|
||||
- **competitor-alternatives**: For building comparison pages that get cited
|
||||
- **competitors**: For building comparison pages that get cited
|
||||
- **programmatic-seo**: For building SEO pages at scale
|
||||
- **copywriting**: For writing content that's both human-readable and AI-extractable
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"skill_name": "ai-seo",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "How do I make sure our SaaS product shows up in AI search results? We're a project management tool and we keep getting left out of ChatGPT and Perplexity recommendations when people ask about project management software.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the three pillars framework: Structure (make content extractable), Authority (make content citable), Presence (be where AI looks). Should run through the AI Visibility Audit checklist across platforms (Google AI Overviews, ChatGPT, Perplexity, etc.). Should check content extractability (clear definitions, structured comparisons, statistics). Should reference Princeton GEO research findings (citations improve visibility +40%, statistics +37%). Should check AI bot access in robots.txt. Should provide a prioritized action plan.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies three pillars framework (Structure, Authority, Presence)",
|
||||
"Runs AI Visibility Audit across platforms",
|
||||
"Checks content extractability",
|
||||
"References Princeton GEO research findings",
|
||||
"Checks AI bot access in robots.txt",
|
||||
"Provides prioritized action plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Should we block AI crawlers like GPTBot and PerplexityBot in our robots.txt? We're worried about content theft.",
|
||||
"expected_output": "Should address the AI bot access question directly. Should explain the tradeoff: blocking AI bots prevents training on your content but also prevents AI platforms from citing and recommending you. Should reference the specific bots and their purposes (GPTBot, Google-Extended, PerplexityBot, ClaudeBot, etc.). Should provide the recommended robots.txt configuration. Should explain that blocking may hurt AI visibility more than it protects content. Should provide a nuanced recommendation based on business goals.",
|
||||
"assertions": [
|
||||
"Addresses the blocking tradeoff directly",
|
||||
"Explains impact on AI visibility vs content protection",
|
||||
"Lists specific AI bot user agents",
|
||||
"Provides recommended robots.txt configuration",
|
||||
"Gives nuanced recommendation based on business goals",
|
||||
"Explains what each bot does"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "What kind of content gets cited most by AI systems? We want to create content specifically optimized for AI search.",
|
||||
"expected_output": "Should reference the content types that get cited most, including comparisons (~33% of AI citations), definitive guides (~15%), and other high-citation content types. Should explain why these formats work (they provide the structured, extractable, authoritative information AI systems need). Should provide specific recommendations for creating AI-optimized content: clear definitions, structured data, original statistics, comparison tables, expert quotes. Should reference the Princeton GEO research on what increases citation probability.",
|
||||
"assertions": [
|
||||
"References specific content types with citation rates",
|
||||
"Mentions comparisons as highest-cited format",
|
||||
"Explains why these formats work for AI",
|
||||
"Provides specific content creation recommendations",
|
||||
"References Princeton GEO research",
|
||||
"Mentions structured data, statistics, and clear definitions"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "we noticed our competitors are showing up in google AI overviews but we're not. what do we need to change?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should focus specifically on Google AI Overviews visibility. Should explain how AI Overviews selects sources (authoritative, well-structured, directly answers queries). Should run through the Structure pillar checklist: content extractability, heading hierarchy, answer-first format, structured data. Should check Authority signals: domain authority, citations, E-E-A-T. Should recommend specific content structure changes. Should suggest monitoring approach.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Focuses on Google AI Overviews specifically",
|
||||
"Explains how AI Overviews selects sources",
|
||||
"Checks Structure pillar (extractability, headings, answer-first)",
|
||||
"Checks Authority signals",
|
||||
"Recommends specific content structure changes",
|
||||
"Suggests monitoring approach"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Can you audit our website for AI search readiness? We want to know how visible we are across ChatGPT, Perplexity, Google AI Overviews, and other AI platforms.",
|
||||
"expected_output": "Should run the full AI Visibility Audit. Should check each platform in the landscape (Google AI Overviews, ChatGPT, Perplexity, Claude, Gemini, Copilot). Should evaluate all three pillars: Structure (content extractability, JSON-LD, clear definitions), Authority (citations, backlinks, E-E-A-T signals), Presence (AI bot access, platform-specific factors). Should provide findings organized by pillar. Should provide a prioritized action plan with specific fixes.",
|
||||
"assertions": [
|
||||
"Runs full AI Visibility Audit",
|
||||
"Checks multiple AI platforms",
|
||||
"Evaluates all three pillars (Structure, Authority, Presence)",
|
||||
"Checks content extractability",
|
||||
"Checks AI bot access",
|
||||
"Provides findings organized by pillar",
|
||||
"Provides prioritized action plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Our organic search traffic has dropped 30% this quarter. Can you do a full SEO audit to figure out what's going on?",
|
||||
"expected_output": "Should recognize this is a traditional SEO audit request, not specifically an AI SEO task. Should defer to or cross-reference the seo-audit skill, which handles comprehensive traditional SEO audits including crawlability, technical foundations, on-page optimization, and content quality. May mention AI search as one factor to investigate but should make clear that seo-audit is the primary skill for this task.",
|
||||
"assertions": [
|
||||
"Recognizes this as a traditional SEO audit request",
|
||||
"References or defers to seo-audit skill",
|
||||
"Does not attempt a full traditional SEO audit using AI SEO patterns",
|
||||
"May mention AI search as one factor to consider"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,71 @@
|
||||
# AI SEO by Content Type
|
||||
|
||||
Tactical guidance for optimizing specific content types for AI search citation. These tactics work for non-Google AI engines (ChatGPT, Claude, Perplexity, Copilot) and don't hurt Google AI Overviews / AI Mode.
|
||||
|
||||
For the cross-cutting strategy, see [SKILL.md](../SKILL.md).
|
||||
|
||||
---
|
||||
|
||||
## SaaS Product Pages
|
||||
|
||||
**Goal:** Get cited in "What is [category]?" and "Best [category]" queries.
|
||||
|
||||
**Optimize:**
|
||||
- Clear product description in first paragraph (what it does, who it's for)
|
||||
- Feature comparison tables (you vs. category, not just competitors)
|
||||
- Specific metrics ("processes 10,000 transactions/sec" not "blazing fast")
|
||||
- Customer count or social proof with numbers
|
||||
- Pricing transparency (AI cites pages with visible pricing) — add a `/pricing.md` file so AI agents can parse your plans without rendering your page (see "Machine-Readable Files" in the main skill)
|
||||
- FAQ section addressing common buyer questions
|
||||
|
||||
---
|
||||
|
||||
## Blog Content
|
||||
|
||||
**Goal:** Get cited as an authoritative source on topics in your space.
|
||||
|
||||
**Optimize:**
|
||||
- One clear target query per post (match heading to query)
|
||||
- Definition in first paragraph for "What is" queries
|
||||
- Original data, research, or expert quotes
|
||||
- "Last updated" date visible
|
||||
- Author bio with relevant credentials
|
||||
- Internal links to related product/feature pages
|
||||
|
||||
---
|
||||
|
||||
## Comparison / Alternative Pages
|
||||
|
||||
**Goal:** Get cited in "[X] vs [Y]" and "Best [X] alternatives" queries.
|
||||
|
||||
**Optimize:**
|
||||
- Structured comparison tables (not just prose)
|
||||
- Fair and balanced (AI penalizes obviously biased comparisons)
|
||||
- Specific criteria with ratings or scores
|
||||
- Updated pricing and feature data
|
||||
- Cite the `competitors` skill for building these pages
|
||||
|
||||
---
|
||||
|
||||
## Documentation / Help Content
|
||||
|
||||
**Goal:** Get cited in "How to [X] with [your product]" queries.
|
||||
|
||||
**Optimize:**
|
||||
- Step-by-step format with numbered lists
|
||||
- Code examples where relevant
|
||||
- HowTo schema markup
|
||||
- Screenshots with descriptive alt text
|
||||
- Clear prerequisites and expected outcomes
|
||||
|
||||
---
|
||||
|
||||
## Local Business / Ecom (Google emphasis)
|
||||
|
||||
Google's AI features pull from product feeds and business profiles for local + ecom queries. Optimize:
|
||||
|
||||
- **Merchant Center feeds** kept current with accurate inventory, pricing, attributes
|
||||
- **Google Business Profile** complete with hours, services, photos, posts, Q&A answered
|
||||
- **Reviews** — recent + sufficient volume; respond to reviews to signal active management
|
||||
- **Service area schema** for local services
|
||||
- **Business Agent** (where available) for conversational customer engagement
|
||||
@@ -0,0 +1,104 @@
|
||||
# Open Knowledge Format (OKF)
|
||||
|
||||
Google's v0.1 markdown spec for representing site content as an agent-readable bundle. Introduced on the [Google Cloud blog](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) on 2026-06-12 and shipped inside Knowledge Catalog.
|
||||
|
||||
## What it is
|
||||
|
||||
OKF is a directory of cross-linked markdown files. Each file has:
|
||||
|
||||
- A YAML frontmatter block (`type` required; `title`, `description`, `resource`, `tags`, `timestamp` recommended)
|
||||
- A standard markdown body
|
||||
- Standard markdown links to other files in the bundle (which the spec treats as concept relationships)
|
||||
|
||||
An optional `index.md` lists the files for progressive disclosure. The bundle can be distributed as a git repo (recommended), a tarball/zip, or a subdirectory of a larger repo.
|
||||
|
||||
The [full spec](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/HEAD/okf/SPEC.md) fits on one page. The repo lives under `GoogleCloudPlatform` (the "not an official Google product" disclaimer is Google's standard open-source boilerplate, not a denial — it appears on most of Google's open-source repos including their main AI samples repo).
|
||||
|
||||
### A minimal concept file
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: Article
|
||||
title: How to Connect the Ahrefs MCP Server to Manus
|
||||
description: The official MCP servers, why they did not connect, and the fix.
|
||||
resource: https://yoursite.com/blog/ahrefs-mcp-manus/
|
||||
tags: [mcp, ahrefs]
|
||||
---
|
||||
|
||||
# How to Connect the Ahrefs MCP Server to Manus
|
||||
|
||||
The body of the post, as clean markdown.
|
||||
```
|
||||
|
||||
Add an `index.md` that lists all files so an agent can see the bundle's shape before opening each file, and that is the entire format.
|
||||
|
||||
## Honest framing
|
||||
|
||||
**Google built OKF for data teams sharing catalog metadata** — BigQuery tables, API endpoints, metrics, playbooks. Most of the spec's examples are data-team artifacts, not blog posts. Google's blog post framing: "improve data sharing" and "standardized documentation" for collaboration across teams.
|
||||
|
||||
Pointing OKF at a marketing site is a **clever repurposing** popularized by [Suganthan Mohanadasan](https://suganthan.com/blog/open-knowledge-format/). It's a legitimate use case for the format but not Google's primary one. Frame it accurately when explaining it to founders or marketing teams.
|
||||
|
||||
## What it does for AI search today
|
||||
|
||||
Nothing immediate. Nothing crawls the web for OKF bundles yet — the spec is weeks old, no AI engine has announced integration, and Knowledge Catalog ingests bundles only for paying enterprise customers' data teams.
|
||||
|
||||
Treat OKF as **protocol-layer registration** — the same shape of bet as early `schema.org` adoption was a decade ago. Schema took the better part of ten years to pay off; people who shipped it early are still glad they did.
|
||||
|
||||
A secondary benefit that pays off today regardless: **generating the bundle is itself an internal-linking audit**. Suganthan's tool draws every page as a node and every internal link as an edge, so islands and orphans become obvious at a glance.
|
||||
|
||||
## Where OKF fits in the agent-readable stack
|
||||
|
||||
| Layer | Purpose |
|
||||
|---|---|
|
||||
| `sitemap.xml` | Tells a crawler which URLs exist |
|
||||
| `robots.txt` (with AI bot rules) | Permits or blocks AI crawlers |
|
||||
| `llms.txt` | Points an agent at the handful of pages you most want read |
|
||||
| `/pricing.md` | Structured pricing for agent-buyer comparisons |
|
||||
| **`/okf/` bundle** | Hands over the content itself as cross-linked concepts |
|
||||
| Schema markup | Per-page structured data (Article, FAQPage, Product, etc.) |
|
||||
|
||||
These stack rather than compete. `llms.txt` is a signpost, OKF is the library.
|
||||
|
||||
## How to ship one
|
||||
|
||||
Three options, ordered by how much effort they take:
|
||||
|
||||
### 1. Suganthan's free web tool (recommended for most sites)
|
||||
|
||||
[suganthan.com/okf-generator](https://suganthan.com/okf-generator/) — paste a URL or sitemap, crawls up to 100 pages, returns a downloadable bundle. Also draws the resulting page graph so you can spot disconnected pages before publishing.
|
||||
|
||||
### 2. WordPress plugin (pending wp.org approval)
|
||||
|
||||
Suganthan's plugin (free, GPL, awaiting wp.org approval at time of writing) installs in a minute, serves the bundle at `/okf/`, and rebuilds on every publish or edit so it stays in sync. Direct download link is in [his blog post](https://suganthan.com/blog/open-knowledge-format/). Requires WordPress 6.0+ and PHP 7.4+. Read-only — never edits posts or settings.
|
||||
|
||||
### 3. By hand
|
||||
|
||||
Only practical for a handful of pages. Each post becomes a markdown file with frontmatter that you cross-link manually. Miserable for a whole site.
|
||||
|
||||
## Hosting & discovery
|
||||
|
||||
Serve the bundle at `yoursite.com/okf/`, starting with `yoursite.com/okf/index.md`:
|
||||
|
||||
- **Static hosts / Cloudflare**: drag and drop
|
||||
- **WordPress**: Suganthan's plugin handles the serving
|
||||
- **Static sites with custom paths**: upload the directory to `/okf/`
|
||||
- **Closed platforms (Wix, Squarespace, most page-builders)**: you usually can't serve files at custom paths — skip OKF entirely
|
||||
|
||||
After it's serving, add a line to `llms.txt` pointing to the bundle so agents that read `llms.txt` (today) can discover the bundle (later).
|
||||
|
||||
## When to skip
|
||||
|
||||
- Site is <10 pages — overhead exceeds payoff
|
||||
- Site is on a closed platform that won't allow custom paths
|
||||
- You're not maintaining `llms.txt`, schema markup, or other machine-readable files (OKF compounds with those; alone it does nothing)
|
||||
- You can't budget the 30 minutes a quarter to refresh the bundle as content changes
|
||||
|
||||
## What to watch
|
||||
|
||||
OKF is v0.1, weeks old. Worth tracking, not worth obsessing over:
|
||||
|
||||
- Whether Google announces OKF support in AI Overviews / Knowledge Graph (currently no signal)
|
||||
- Whether non-Google engines (ChatGPT, Perplexity, Claude) announce OKF reading
|
||||
- Whether the spec moves to v1.0 (breaking changes are possible at <1.0)
|
||||
- Whether Knowledge Catalog adds public ingestion endpoints
|
||||
- Adoption signals — search GitHub for `okf/index.md` to see who's shipping bundles
|
||||
@@ -34,6 +34,8 @@ Google AI Overviews pull from Google's own index and lean heavily on E-E-A-T sig
|
||||
- Get into Google's Knowledge Graph where possible (an accurate Wikipedia entry helps)
|
||||
- Target "how to" and "what is" query patterns — these trigger AI Overviews most often
|
||||
|
||||
**Watch for OKF.** In June 2026 Google introduced the [Open Knowledge Format](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) — a markdown spec for agent-readable site bundles. There is no confirmed signal that AI Overviews factor it in today, but the spec is published, the GitHub repo lives under `GoogleCloudPlatform`, and it ships inside Knowledge Catalog. For protocol-layer "register early" plays, it has the same shape as early schema.org adoption did a decade ago. See **Machine-Readable Files for AI Agents** in the main `SKILL.md` for how to generate and serve a bundle.
|
||||
|
||||
---
|
||||
|
||||
## ChatGPT
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: analytics-tracking
|
||||
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," or "tracking plan." For A/B test measurement, see ab-test-setup.
|
||||
name: analytics
|
||||
description: When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions "set up tracking," "GA4," "Google Analytics," "conversion tracking," "event tracking," "UTM parameters," "tag manager," "GTM," "analytics implementation," "tracking plan," "how do I measure this," "track conversions," "attribution," "Mixpanel," "Segment," "are my events firing," or "analytics isn't working." Use this whenever someone asks how to know if something is working or wants to measure marketing results. For A/B test measurement, see ab-testing.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Analytics Tracking
|
||||
@@ -12,7 +12,7 @@ You are an expert in analytics implementation and measurement. Your goal is to h
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before implementing tracking, understand:
|
||||
|
||||
@@ -303,6 +303,7 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analy
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **ab-test-setup**: For experiment tracking
|
||||
- **ab-testing**: For experiment tracking
|
||||
- **seo-audit**: For organic traffic analysis
|
||||
- **page-cro**: For conversion optimization (uses this data)
|
||||
- **cro**: For conversion optimization (uses this data)
|
||||
- **revops**: For pipeline metrics, CRM tracking, and revenue attribution
|
||||
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"skill_name": "analytics",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Help me set up analytics tracking for our B2B SaaS product. We use GA4 and GTM. We need to track signups, feature usage, and upgrade events.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the 'track for decisions' principle — ask what decisions the tracking will inform. Should use the event naming convention (object_action, lowercase with underscores). Should define essential events for SaaS: signup_completed, trial_started, feature_used, plan_upgraded, etc. Should provide GA4 implementation details with proper event parameters. Should include GTM data layer push examples. Should organize output as a tracking plan with event name, trigger, parameters, and purpose for each event.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies 'track for decisions' principle",
|
||||
"Uses object_action naming convention",
|
||||
"Defines essential SaaS events (signup, feature usage, upgrade)",
|
||||
"Provides GA4 implementation details",
|
||||
"Includes GTM data layer examples",
|
||||
"Output follows tracking plan format"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "What UTM parameters should we use? We run ads on Google, Meta, and LinkedIn, plus send a weekly newsletter and post on LinkedIn organically.",
|
||||
"expected_output": "Should apply the UTM parameter strategy framework. Should define consistent UTM conventions: source (google, meta, linkedin, newsletter), medium (cpc, paid-social, email, organic-social), campaign (naming convention with date or identifier). Should provide specific UTM examples for each channel mentioned. Should warn about common UTM mistakes (inconsistent casing, redundant parameters, missing medium). Should recommend a UTM tracking spreadsheet or naming convention document.",
|
||||
"assertions": [
|
||||
"Applies UTM parameter strategy",
|
||||
"Defines source, medium, and campaign conventions",
|
||||
"Provides specific UTM examples for each channel",
|
||||
"Uses consistent naming conventions (lowercase)",
|
||||
"Warns about common UTM mistakes",
|
||||
"Recommends tracking documentation"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "our tracking seems broken — we're seeing duplicate events and our conversion numbers in GA4 don't match what our database shows. help?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the debugging and validation framework. Should systematically check for common issues: duplicate GTM tags firing, missing event deduplication, incorrect trigger conditions, cross-domain tracking issues, consent mode filtering. Should provide specific debugging steps: use GA4 DebugView, GTM Preview mode, browser developer tools. Should address the GA4 vs database discrepancy (common causes: consent mode, ad blockers, client-side vs server-side tracking, session timeout differences).",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Applies debugging and validation framework",
|
||||
"Checks for duplicate tag firing",
|
||||
"Provides specific debugging tools (GA4 DebugView, GTM Preview)",
|
||||
"Addresses GA4 vs database discrepancy",
|
||||
"Lists common causes of data mismatches",
|
||||
"Provides systematic troubleshooting steps"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "We're launching an e-commerce store and need to set up tracking from scratch. What events do we absolutely need?",
|
||||
"expected_output": "Should reference the essential events by site type, specifically e-commerce. Should define the e-commerce event taxonomy: product_viewed, product_added_to_cart, cart_viewed, checkout_started, checkout_step_completed, purchase_completed, product_removed_from_cart. Should include enhanced e-commerce parameters (item_id, item_name, price, quantity, etc.). Should follow object_action naming convention. Should organize as a tracking plan with priorities (must-have vs nice-to-have).",
|
||||
"assertions": [
|
||||
"References essential events for e-commerce site type",
|
||||
"Defines full e-commerce event taxonomy",
|
||||
"Includes enhanced e-commerce parameters",
|
||||
"Follows object_action naming convention",
|
||||
"Organizes by priority (must-have vs nice-to-have)",
|
||||
"Provides tracking plan format output"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We need to make sure our tracking is GDPR compliant. We have European users and we're using GA4, Hotjar, and Facebook Pixel.",
|
||||
"expected_output": "Should apply the privacy and compliance framework. Should address GDPR requirements for each tool: consent before tracking, consent management platform (CMP) setup, GA4 consent mode configuration, conditional loading of Hotjar and Facebook Pixel. Should recommend a consent hierarchy (necessary, analytics, marketing). Should provide GTM implementation for consent-based tag firing. Should mention data retention settings in GA4. Should address cookie banner requirements.",
|
||||
"assertions": [
|
||||
"Applies privacy and compliance framework",
|
||||
"Addresses GDPR requirements specifically",
|
||||
"Recommends consent management platform",
|
||||
"Covers GA4 consent mode configuration",
|
||||
"Addresses conditional loading for each tool",
|
||||
"Provides consent hierarchy",
|
||||
"Mentions data retention settings"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Help me set up tracking for our A/B test. We want to measure which version of our pricing page converts better.",
|
||||
"expected_output": "Should recognize this overlaps with A/B test setup, not just analytics tracking. Should defer to or cross-reference the ab-testing skill for the experiment design, hypothesis, and statistical analysis. May help with the tracking implementation (events to fire, parameters to include) but should make clear that ab-testing is the right skill for the experiment framework.",
|
||||
"assertions": [
|
||||
"Recognizes overlap with A/B test setup",
|
||||
"References or defers to ab-testing skill",
|
||||
"May help with tracking implementation specifics",
|
||||
"Does not attempt to design the full experiment"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: aso
|
||||
description: "When the user wants to audit or optimize an App Store or Google Play listing. Also use when the user mentions 'ASO audit,' 'app store optimization,' 'optimize my app listing,' 'improve app visibility,' 'app store ranking,' 'audit my listing,' 'why aren't people downloading my app,' 'improve my app conversion,' 'keyword optimization for app,' or 'compare my app to competitors.' Use when the user shares an App Store or Google Play URL and wants to improve it."
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# ASO Audit
|
||||
|
||||
Analyze App Store and Google Play listings against ASO best practices. Fetches
|
||||
live listing data, scores metadata, visuals, and ratings, then produces a
|
||||
prioritized action plan.
|
||||
|
||||
## When to Use
|
||||
|
||||
- User shares an App Store or Google Play URL
|
||||
- User asks to audit or optimize an app listing
|
||||
- User wants to compare their app against competitors
|
||||
- User asks about app store ranking, visibility, or download conversion
|
||||
|
||||
## Before Auditing
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
## Phase 1 — Identify Store & Fetch
|
||||
|
||||
### Detect store type from URL
|
||||
|
||||
```
|
||||
Apple: apps.apple.com/{country}/app/{name}/id{digits}
|
||||
Google: play.google.com/store/apps/details?id={package}
|
||||
```
|
||||
|
||||
If the user gives an app name instead of a URL, search the web for:
|
||||
`site:apps.apple.com "{app name}"` or `site:play.google.com "{app name}"`
|
||||
|
||||
### Fetch the listing
|
||||
|
||||
Use WebFetch to retrieve the listing page. Extract every available field:
|
||||
|
||||
**Apple App Store fields:**
|
||||
|
||||
- App name (title) — 30 char limit
|
||||
- Subtitle — 30 char limit
|
||||
- Description (long) — not indexed for search, but matters for conversion
|
||||
- Promotional text — 170 chars, updatable without new release
|
||||
- Category (primary + secondary)
|
||||
- Screenshots (count, order, caption text)
|
||||
- Preview video (presence, duration)
|
||||
- Rating (average + count)
|
||||
- Recent reviews (visible ones)
|
||||
- Price / in-app purchases
|
||||
- Developer name
|
||||
- Last updated date
|
||||
- Version history notes
|
||||
- Age rating
|
||||
- Size
|
||||
- Languages / localizations listed
|
||||
- In-app events (if any visible)
|
||||
|
||||
**Google Play fields:**
|
||||
|
||||
- App name (title) — 30 char limit
|
||||
- Short description — 80 char limit
|
||||
- Full description — 4,000 char limit, IS indexed for search
|
||||
- Category + tags
|
||||
- Feature graphic (presence)
|
||||
- Screenshots (count, order)
|
||||
- Preview video (presence)
|
||||
- Rating (average + count)
|
||||
- Recent reviews (visible ones)
|
||||
- Price / in-app purchases
|
||||
- Developer name
|
||||
- Last updated date
|
||||
- What's new text
|
||||
- Downloads range
|
||||
- Content rating
|
||||
- Data safety section
|
||||
- Languages listed
|
||||
|
||||
If WebFetch returns incomplete data (stores render client-side), note gaps and
|
||||
work with what's available. Ask the user to paste missing fields if critical.
|
||||
|
||||
### Visual asset assessment
|
||||
|
||||
WebFetch cannot extract screenshot images or caption text. **Take a screenshot
|
||||
of the listing page** to get visual data:
|
||||
|
||||
1. Navigate to the listing URL and capture a full-page screenshot
|
||||
2. Assess the screenshot for: icon quality, screenshot count, caption text,
|
||||
messaging quality, preview video presence, feature graphic (Google Play)
|
||||
3. If browser tools are unavailable, ask the user to share a screenshot of the
|
||||
listing page
|
||||
|
||||
**Promotional text (Apple):** This 170-char field appears above the description
|
||||
but is often indistinguishable from it in scraped HTML. If you cannot confirm
|
||||
its presence, note this and recommend the user check App Store Connect.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1.5 — Assess Brand Maturity
|
||||
|
||||
Before scoring, classify the app into one of three tiers. This determines how
|
||||
you interpret "textbook ASO" deviations — a deliberate brand choice by a
|
||||
household name is not the same as a missed opportunity by an unknown app.
|
||||
|
||||
### Tier definitions
|
||||
|
||||
| Tier | Signals | Examples |
|
||||
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------- |
|
||||
| **Dominant** | Household name, 1M+ ratings, top-10 in category, near-universal brand recognition. Users search by brand name, not generic keywords. | Instagram, Uber, Spotify, WhatsApp, Netflix |
|
||||
| **Established** | Well-known in their category, 100K+ ratings, strong organic installs, recognized brand but not universally known. | Strava, Notion, Duolingo, Cash App, Calm |
|
||||
| **Challenger** | Building awareness, <100K ratings, needs discovery through keywords and ASO tactics. Most apps fall here. | Your app, most indie/startup apps |
|
||||
|
||||
### How tier affects scoring
|
||||
|
||||
**Dominant apps** get adjusted scoring in these areas:
|
||||
|
||||
- **Title:** Brand-only or brand-first titles are valid (score 8+ if brand is the keyword). These apps don't need generic keyword discovery.
|
||||
- **Description:** Score purely on conversion quality, not keyword presence. If the app is a household name, a well-crafted brand description beats a keyword-stuffed one.
|
||||
- **Visual Assets:** Lifestyle/brand photography instead of UI demos is a legitimate conversion strategy. No video is acceptable if the product is hard to demo in 30s or brand awareness is near-universal.
|
||||
- **What's New:** Generic release notes at weekly+ cadence are acceptable (score 8+). At scale, detailed changelogs have minimal ROI and risk backlash.
|
||||
- **In-app events:** Missing events for utility apps with massive install bases (Uber, WhatsApp) is not a penalty. These apps don't need discovery help.
|
||||
- **Localization:** Score relative to actual market, not absolute count. A US-only fintech with 2 languages (English + Spanish) is appropriately localized.
|
||||
|
||||
**Established apps** get partial adjustment:
|
||||
|
||||
- Brand-first titles are fine but should still include 1-2 keywords
|
||||
- Strategic description choices get benefit of the doubt
|
||||
- Other dimensions scored normally
|
||||
|
||||
**Challenger apps** are scored strictly against textbook ASO best practices — every character, screenshot, and keyword matters.
|
||||
|
||||
**Key principle:** Before docking points, ask: "Is this a mistake or a deliberate
|
||||
choice by a team that has data I don't?" If the app has 1M+ ratings and a
|
||||
dedicated ASO team, assume their choices are data-informed unless clearly wrong.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — Score Each Dimension
|
||||
|
||||
Score each dimension 0-10 using the criteria in `references/scoring-criteria.md`.
|
||||
Apply the brand maturity tier adjustments from Phase 1.5.
|
||||
|
||||
Reference files for platform specs and benchmarks:
|
||||
|
||||
- `references/apple-specs.md` — Official Apple character limits, screenshot/video specs, CPP/PPO rules, rejection triggers
|
||||
- `references/google-play-specs.md` — Official Google Play limits, screenshot specs, Android Vitals thresholds, policies
|
||||
- `references/benchmarks.md` — Conversion data, rating impact, video lift, screenshot behavior, CPP/event benchmarks
|
||||
|
||||
### Dimensions and Weights
|
||||
|
||||
| # | Dimension | Weight | What It Covers |
|
||||
| --- | -------------------- | ------ | ------------------------------------------------------------------------- |
|
||||
| 1 | Title & Subtitle | 20% | Character usage, keyword presence, clarity, brand + keyword balance |
|
||||
| 2 | Description | 15% | First 3 lines, keyword density (Google), CTA, structure, promotional text |
|
||||
| 3 | Visual Assets | 25% | Screenshot count/quality/messaging, video, icon, feature graphic |
|
||||
| 4 | Ratings & Reviews | 20% | Average rating, volume, recency, developer responses |
|
||||
| 5 | Metadata & Freshness | 10% | Category choice, update recency, localization count, data safety |
|
||||
| 6 | Conversion Signals | 10% | Price positioning, IAP transparency, social proof, download range |
|
||||
|
||||
**Final score** = weighted sum, out of 100.
|
||||
|
||||
### Score interpretation
|
||||
|
||||
| Score | Grade | Meaning |
|
||||
| ------ | ----- | --------------------------------------------------------- |
|
||||
| 85-100 | A | Well-optimized; focus on A/B testing and iteration |
|
||||
| 70-84 | B | Good foundation; clear opportunities to improve |
|
||||
| 50-69 | C | Significant gaps; prioritized fixes will have high impact |
|
||||
| 30-49 | D | Major optimization needed across multiple dimensions |
|
||||
| 0-29 | F | Listing needs a complete overhaul |
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — Competitor Comparison (Optional)
|
||||
|
||||
If the user provides competitor URLs or asks for comparison:
|
||||
|
||||
1. Fetch 2-3 top competitors in the same category
|
||||
2. Run the same scoring on each
|
||||
3. Build a comparison table highlighting where the user's app is weaker/stronger
|
||||
4. Identify keyword gaps — terms competitors rank for that the user's app doesn't target
|
||||
|
||||
If no competitors are specified, suggest the user provide 2-3 or offer to search
|
||||
for top apps in their category.
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 — Generate Report
|
||||
|
||||
Use the template in `references/report-template.md` to structure the output.
|
||||
|
||||
The report must include:
|
||||
|
||||
1. **Score card** — table with all 6 dimensions, scores, and grade
|
||||
2. **Top 3 quick wins** — changes that take <1 hour and have highest impact
|
||||
3. **Detailed findings** — per-dimension breakdown with specific issues and fixes
|
||||
4. **Keyword suggestions** — based on title/description analysis and competitor gaps
|
||||
5. **Visual asset recommendations** — specific screenshot/video improvements
|
||||
6. **Priority action plan** — ordered list of changes by impact vs effort
|
||||
|
||||
### Report rules
|
||||
|
||||
- Every recommendation must be **specific and actionable** ("Change subtitle from X to Y" not "Improve subtitle")
|
||||
- Include character counts for all text recommendations
|
||||
- Flag platform-specific differences (Apple vs Google) when relevant
|
||||
- Note what CANNOT be assessed without paid tools (search volume, exact rankings)
|
||||
- When suggesting keyword changes, explain WHY each keyword matters
|
||||
|
||||
---
|
||||
|
||||
## Platform-Specific Rules
|
||||
|
||||
### Apple App Store — Key Facts
|
||||
|
||||
- Title (30 chars) + Subtitle (30 chars) + Keyword field (100 **bytes**, hidden) = indexed text
|
||||
- Keywords field is bytes not chars — Arabic/CJK use 2-3 bytes per char
|
||||
- Long description is NOT indexed for search — optimize for conversion only
|
||||
- Promotional text (170 chars) does NOT affect search (Apple confirmed)
|
||||
- Never repeat words across title/subtitle/keyword field (Apple indexes each word once)
|
||||
- Keyword field: commas, no spaces ("photo,editor,filter" not "photo, editor, filter")
|
||||
- Screenshots: up to 10 per device. First 3 visible in search — 90% never scroll past 3rd
|
||||
- Screenshot captions indexed since June 2025 (AI extraction)
|
||||
- In-app events: max 10 published at once, max 31 days each. Indexed and appear in search
|
||||
- Custom Product Pages (up to 70) in organic search since July 2025. +5.9% avg conversion lift
|
||||
- App preview video: up to 3, 15-30s each. Autoplays muted — +20-40% conversion lift
|
||||
- SKStoreReviewController: max 3 prompts per 365 days
|
||||
- Apple has human editorial curation — quality and design matter more
|
||||
- See `references/apple-specs.md` for full specs, dimensions, and rejection triggers
|
||||
|
||||
### Google Play — Key Facts
|
||||
|
||||
- Title (30 chars) + Short description (80 chars) + Full description (4,000 chars) = indexed text
|
||||
- Full description IS indexed — target 2-3% keyword density naturally
|
||||
- No hidden keyword field — all keywords must be in visible text
|
||||
- Google NLP/semantic understanding — keyword stuffing detected and penalized
|
||||
- Prohibited in title: emojis, ALL CAPS, "best"/"#1"/"free", CTAs (enforced since 2021)
|
||||
- Screenshots: min 2, **max 8** per device (not 10 like Apple)
|
||||
- Feature graphic (1024x500, exact) required for featured placements
|
||||
- Video does NOT autoplay — only ~6% of users tap play (low ROI vs iOS)
|
||||
- Android Vitals directly affect ranking: crash >1.09% or ANR >0.47% = reduced visibility
|
||||
- Promotional Content: submit 14 days early for featuring. Apps see 2x explore acquisitions
|
||||
- Custom Store Listings: up to 50 (can target churned users, specific countries, ad campaigns)
|
||||
- Store Listing Experiments: test up to 3 variants, run 7+ days, 1 experiment at a time
|
||||
- See `references/google-play-specs.md` for full specs and policy details
|
||||
|
||||
### What Apple Indexes vs What Google Indexes
|
||||
|
||||
| Field | Apple Indexed? | Google Indexed? |
|
||||
| --------------------- | ---------------- | ---------------------- |
|
||||
| Title | Yes | Yes (strongest signal) |
|
||||
| Subtitle / Short desc | Yes | Yes |
|
||||
| Keyword field | Yes (hidden) | Does not exist |
|
||||
| Long description | No | Yes (heavily) |
|
||||
| Screenshot captions | Yes (since 2025) | No |
|
||||
| In-app events | Yes | N/A (LiveOps instead) |
|
||||
| Developer name | No | Partial |
|
||||
| IAP names | Yes | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Common Issues Checklist
|
||||
|
||||
Flag these if found. Items marked _(tier-dependent)_ should be evaluated against
|
||||
the app's brand maturity tier — they may be deliberate choices for Dominant apps.
|
||||
|
||||
**Always flag (all tiers):**
|
||||
|
||||
- [ ] Rating below 4.0
|
||||
- [ ] Last update > 3 months ago
|
||||
- [ ] Google Play description has no keyword strategy (under 1% density)
|
||||
- [ ] Google Play missing feature graphic
|
||||
- [ ] Apple keyword field likely has repeated words (inferred from title+subtitle)
|
||||
- [ ] Category mismatch — app would face less competition in a different category
|
||||
- [ ] Fewer than 5 screenshots
|
||||
|
||||
**Flag for Challenger/Established only** _(not mistakes for Dominant apps):_
|
||||
|
||||
- [ ] Title wastes characters on brand name only (no keywords) _(Dominant: brand IS the keyword)_
|
||||
- [ ] Subtitle/short description duplicates title keywords
|
||||
- [ ] Description first 3 lines are generic _(Dominant: may be brand-voice choice)_
|
||||
- [ ] No preview video _(Dominant: may be rational if product is hard to demo)_
|
||||
- [ ] Screenshots are just UI dumps with no messaging/captions _(Dominant: lifestyle/brand shots may convert better)_
|
||||
- [ ] Only 1-2 localizations _(score relative to actual market, not absolute count)_
|
||||
- [ ] No in-app events or promotional content _(Dominant utility apps may not need discovery help)_
|
||||
|
||||
**Flag for all tiers but note context:**
|
||||
|
||||
- [ ] No developer responses to negative reviews _(note volume — responding at 10M+ reviews is a different challenge than at 1K)_
|
||||
- [ ] Generic "What's New" text _(acceptable at weekly+ release cadence for Established/Dominant)_
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What is the App Store or Google Play URL?
|
||||
2. Is this your app or a competitor's?
|
||||
3. What category does the app compete in?
|
||||
4. Do you have competitor URLs to compare against?
|
||||
5. Are you focused on search visibility, conversion rate, or both?
|
||||
6. Do you have access to App Store Connect or Google Play Console data?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **cro**: For optimizing the conversion of web-based landing pages that drive app installs
|
||||
- **ad-creative**: For creating App Store and Google Play ad creatives
|
||||
- **analytics**: For setting up install attribution and in-app event tracking
|
||||
- **customer-research**: For understanding user needs and language to inform listing copy
|
||||
@@ -0,0 +1,91 @@
|
||||
{
|
||||
"skill_name": "aso",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Here's our app on the App Store: https://apps.apple.com/us/app/example/id123456789. Can you audit our listing and tell me what to fix?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should detect this is an Apple App Store URL and run the full ASO audit workflow. Should fetch the listing and extract Apple-specific fields (title 30 chars, subtitle 30 chars, description, promotional text 170 chars, category, screenshots, video, ratings). Should classify the app's brand maturity tier (Dominant/Established/Challenger) before scoring. Should score all 6 dimensions (Title & Subtitle 20%, Description 15%, Visual Assets 25%, Ratings & Reviews 20%, Metadata & Freshness 10%, Conversion Signals 10%) with weighted total out of 100 and a grade. Should output a scorecard, top 3 quick wins, detailed findings, keyword suggestions, visual recommendations, and prioritized action plan with specific 'change X from Y to Z' recommendations including character counts.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Identifies as Apple App Store URL",
|
||||
"Classifies brand maturity tier",
|
||||
"Scores all 6 dimensions with weights",
|
||||
"Provides scorecard with grade",
|
||||
"Lists top 3 quick wins",
|
||||
"Recommendations include character counts",
|
||||
"Recommendations are specific (X to Y format)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We're a small fintech startup with about 5,000 downloads. Our Play Store listing has a 2.8 rating and we haven't updated the description in 8 months. Help us figure out what to fix first.",
|
||||
"expected_output": "Should recognize this as a Challenger-tier Google Play app. Should immediately flag the always-flag issues: rating below 4.0 (critical), last update >3 months ago. Should apply strict Challenger scoring against textbook best practices. Should focus on Google Play-specific guidance: full description is indexed for search (target 2-3% keyword density), no hidden keyword field, feature graphic required (1024x500), max 8 screenshots, Android Vitals affect ranking. Should prioritize fixing the rating issue (response strategy, in-app review prompts) and refreshing the description with keyword strategy. Should recommend updating the listing soon to break the >3 month stale signal.",
|
||||
"assertions": [
|
||||
"Identifies as Google Play app",
|
||||
"Classifies as Challenger tier",
|
||||
"Flags rating below 4.0",
|
||||
"Flags stale update (>3 months)",
|
||||
"Notes Google Play indexes full description",
|
||||
"Mentions feature graphic requirement",
|
||||
"Recommends keyword strategy in description",
|
||||
"Prioritizes rating improvement"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Instagram's App Store listing has just 'Instagram' as the title and barely any keywords. Should they fix that?",
|
||||
"expected_output": "Should classify Instagram as a Dominant-tier app and apply tier-adjusted scoring. Should explain that brand-only titles are valid for Dominant apps (score 8+ if brand IS the keyword) because users search by brand name, not generic keywords. Should NOT flag this as a missed opportunity. Should explain the key principle: 'Is this a mistake or a deliberate choice by a team that has data I don't?' Should note that other dimensions (screenshots, description, what's new) are also evaluated against tier — lifestyle/brand photography and brief release notes are acceptable for Dominant apps. Should contrast with what would be a problem for a Challenger app.",
|
||||
"assertions": [
|
||||
"Classifies Instagram as Dominant tier",
|
||||
"Explains brand-only titles are valid for Dominant",
|
||||
"Does NOT flag the title as a problem",
|
||||
"Contrasts Dominant vs Challenger treatment",
|
||||
"Cites the 'mistake vs deliberate choice' principle"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Compare our app https://apps.apple.com/us/app/ourapp/id111 against these two competitors: https://apps.apple.com/us/app/competitor1/id222 and https://apps.apple.com/us/app/competitor2/id333",
|
||||
"expected_output": "Should run Phase 3 competitor comparison. Should fetch and score all three apps with the same 6-dimension framework. Should build a side-by-side comparison table highlighting where the user's app is weaker or stronger across each dimension. Should identify keyword gaps — terms competitors target that the user's app doesn't. Should produce a prioritized list of competitor-informed changes. Should call out platform-specific considerations consistently across all three apps.",
|
||||
"assertions": [
|
||||
"Scores all 3 apps with same framework",
|
||||
"Builds comparison table",
|
||||
"Identifies where user's app is weaker",
|
||||
"Identifies keyword gaps vs competitors",
|
||||
"Produces competitor-informed action list"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We only have 3 screenshots and no preview video. Does this really matter that much?",
|
||||
"expected_output": "Should explain that screenshot count and video presence are heavily weighted in the Visual Assets dimension (25% of total score). Should cite specific data: Apple allows up to 10 screenshots per device with the first 3 visible in search, and 90% of users never scroll past the 3rd. Should note Apple screenshot captions are indexed for search since June 2025. Should cite the conversion benchmark: app preview video delivers +20-40% conversion lift on iOS (note Google Play video has lower ROI — only ~6% tap play). Should recommend adding 5-8 screenshots minimum with caption text, and a 15-30s preview video. Should flag fewer than 5 screenshots as an always-flag issue across all tiers.",
|
||||
"assertions": [
|
||||
"Notes Visual Assets is 25% of score",
|
||||
"Cites first 3 screenshots are most important",
|
||||
"Mentions screenshot caption indexing (Apple, 2025)",
|
||||
"Cites video conversion lift benchmark",
|
||||
"Notes Google Play video has lower ROI",
|
||||
"Recommends specific screenshot count and video specs",
|
||||
"Flags <5 screenshots as always-flag issue"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Should I run a Custom Product Page experiment on iOS for our paid search campaigns?",
|
||||
"expected_output": "Should reference Apple-specific facts: Custom Product Pages (CPP) — up to 70 — appear in organic search since July 2025 with +5.9% average conversion lift. Should explain CPPs let you test variants of screenshots, video, and promotional text against specific traffic sources (e.g., paid search keywords). Should recommend matching CPP variants to the keyword intent for the campaign. Should cross-reference the ab-testing skill for proper experiment design and the ads skill for the campaign side. Should note this is an iOS-only feature (Google Play has Store Listing Experiments and Custom Store Listings as equivalents).",
|
||||
"assertions": [
|
||||
"Identifies Custom Product Pages as iOS-specific",
|
||||
"Cites +5.9% conversion lift benchmark",
|
||||
"Explains CPP can match traffic source intent",
|
||||
"Cross-references ab-testing or ads skill",
|
||||
"Notes Google Play equivalents"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,107 @@
|
||||
# Apple App Store — Official Specs & Guidelines
|
||||
|
||||
All data from developer.apple.com as of March 2026.
|
||||
|
||||
## Character Limits
|
||||
|
||||
| Field | Limit | Indexed for Search? | Notes |
|
||||
| ----------------------- | ---------------- | ------------------------ | -------------------------------------------------------- |
|
||||
| App Name | 30 chars (min 2) | Yes | Must be unique; no trademarks, competitor names, pricing |
|
||||
| Subtitle | 30 chars | Yes | No unverifiable claims |
|
||||
| Keywords | 100 bytes | Yes (hidden) | Commas, no spaces between terms |
|
||||
| Description | 4,000 chars | **No** | Plain text only, no HTML |
|
||||
| Promotional Text | 170 chars | **No** (Apple confirmed) | Updatable without new version |
|
||||
| What's New | 4,000 chars | No | Required for all versions after first |
|
||||
| IAP Name | 35 chars | Yes | Appears in search |
|
||||
| IAP Description | 55 chars | No | |
|
||||
| In-App Event Name | 30 chars | Yes | Title case required |
|
||||
| In-App Event Short Desc | 50 chars | Yes | Sentence case |
|
||||
| In-App Event Long Desc | 120 chars | No | Sentence case |
|
||||
|
||||
**Keywords field is 100 bytes, not 100 characters.** Non-Latin scripts (Arabic,
|
||||
Chinese, Japanese, Korean) use 2-3 bytes per character, reducing effective
|
||||
keyword count significantly.
|
||||
|
||||
## Screenshot Specs
|
||||
|
||||
| Device | Required? | Count | Dimensions (portrait) |
|
||||
| ---------------- | ------------- | ----- | -------------------------- |
|
||||
| 6.9" iPhone | **Required** | 1-10 | 1260 x 2736 |
|
||||
| 13" iPad | **Required** | 1-10 | 2064 x 2752 |
|
||||
| Mac | If applicable | 1-10 | Up to 2880 x 1800 (16:10) |
|
||||
| Apple Watch | If applicable | 1-10 | Varies by model |
|
||||
| Apple TV | If applicable | 1-10 | 1920 x 1080 or 3840 x 2160 |
|
||||
| Apple Vision Pro | If applicable | 1-10 | 3840 x 2160 |
|
||||
|
||||
- Formats: JPEG, PNG
|
||||
- Apple auto-scales from required base sizes to smaller devices
|
||||
|
||||
## App Preview Video Specs
|
||||
|
||||
- **Count:** Up to 3 per app
|
||||
- **Duration:** 15-30 seconds
|
||||
- **Max file size:** 500 MB
|
||||
- **Codecs:** H.264 (10-12 Mbps, up to 30fps) or ProRes 422 HQ
|
||||
- **Audio:** Stereo, 256 kbps AAC or PCM, 44.1/48 kHz
|
||||
- **Formats:** .mov, .m4v, .mp4
|
||||
- **Behavior:** Autoplays muted on product page (iOS 11+)
|
||||
|
||||
## Custom Product Pages (CPPs)
|
||||
|
||||
- **Max:** 70 additional pages (plus 1 default)
|
||||
- **Customizable:** Screenshots, promotional text, app previews, deep links (iOS 18+)
|
||||
- **Keywords:** Each keyword combo must be unique to a single CPP
|
||||
- **Review:** Submitted to App Review independently of app updates
|
||||
- **Organic search:** CPPs appear in organic search results since July 2025
|
||||
- **Performance:** +2.5 percentage points higher conversion on average vs default
|
||||
|
||||
## Product Page Optimization (A/B Testing)
|
||||
|
||||
- **Treatments:** Up to 3 vs original
|
||||
- **Testable:** App icons, screenshots, app preview videos
|
||||
- **NOT testable:** Title, subtitle, description, keywords
|
||||
- **Concurrent tests:** 1 per app
|
||||
- **Max duration:** 90 days
|
||||
- **Icon constraint:** All icon variants must be in the published app binary
|
||||
- **Confidence:** Apple recommends 90% threshold (Bayesian method)
|
||||
- **Cannot modify** a test once started
|
||||
|
||||
## In-App Events
|
||||
|
||||
- **Max approved:** 15 in App Store Connect at once
|
||||
- **Max published:** 10 on App Store simultaneously
|
||||
- **Max duration:** 31 days per event
|
||||
- **Pre-event promotion:** Up to 14 days before start
|
||||
- **Badge types:** Challenge, Competition, Live Event, Major Update, New Season, Premiere, Special Event
|
||||
|
||||
**Event card image:** 16:9, min 1920x1080, max 3840x2160
|
||||
**Event details image:** 9:16, min 1080x1920, max 2160x3840
|
||||
|
||||
**Not suitable:** Repetitive daily tasks, price promotions without new content, general awareness campaigns.
|
||||
|
||||
## Ratings & Reviews
|
||||
|
||||
- **SKStoreReviewController:** Max 3 prompts per 365-day period
|
||||
- System controls display frequency (may show fewer than 3)
|
||||
- Do not use custom buttons to request reviews
|
||||
- Developers can respond to all reviews in App Store Connect
|
||||
- Summary rating is territory-specific
|
||||
|
||||
## Metadata Rejection Triggers (App Review Guidelines)
|
||||
|
||||
| Guideline | Rejection Trigger |
|
||||
| --------- | ------------------------------------------------------------------------- |
|
||||
| 2.3.1 | Hidden features, misleading marketing, false pricing |
|
||||
| 2.3.2 | Not disclosing IAPs in description/screenshots |
|
||||
| 2.3.3 | Screenshots that don't show app in use (only splash/login) |
|
||||
| 2.3.4 | Preview videos using non-app content |
|
||||
| 2.3.5 | Wrong category selected |
|
||||
| 2.3.7 | Keyword stuffing: trademarks, competitor names, pricing, irrelevant terms |
|
||||
| 2.3.8 | Metadata not appropriate for all audiences (must be 4+ rated) |
|
||||
| 2.3.10 | Other platform names/imagery (Android, etc.) in metadata |
|
||||
| 2.3.12 | Generic What's New for significant changes |
|
||||
| 2.3.13 | Inaccurate in-app event metadata |
|
||||
|
||||
Sources: developer.apple.com/app-store/product-page/,
|
||||
developer.apple.com/app-store/search/,
|
||||
developer.apple.com/app-store/review/guidelines/
|
||||
@@ -0,0 +1,129 @@
|
||||
# ASO Benchmarks & Conversion Data
|
||||
|
||||
Industry data from AppTweak, SplitMetrics, Sensor Tower, and others. Updated March 2026.
|
||||
|
||||
## Conversion Rate Benchmarks by Category
|
||||
|
||||
**Average CVR (page view to install):**
|
||||
|
||||
- iOS overall: **25.0%**
|
||||
- Google Play overall: **27.3%**
|
||||
|
||||
| Category | iOS CVR | Google Play CVR |
|
||||
| ----------------- | -------------- | --------------- |
|
||||
| Navigation | 115%\* | -- |
|
||||
| Auto & Vehicles | -- | 70.5% |
|
||||
| Business | 66.7% | -- |
|
||||
| Music (Games) | -- | 45.0% |
|
||||
| Utilities & Tools | -- | 36.8% |
|
||||
| Shopping | -- | 27.7% |
|
||||
| Health & Fitness | -- | 23.2% |
|
||||
| Finance | -- | 19.7% |
|
||||
| Food & Drink | -- | 13.1% |
|
||||
| Games (Board) | 1.2% | 7.3% |
|
||||
| Games (overall) | 3-5% realistic | -- |
|
||||
|
||||
\*Above 100% = some users install from search without visiting product page.
|
||||
|
||||
Source: AppTweak 2025 Benchmarks Report (H1 2024 data, US market)
|
||||
|
||||
## Rating Impact on Conversion
|
||||
|
||||
| Rating Change | Conversion Impact |
|
||||
| -------------------------- | --------------------------------------- |
|
||||
| 3.0 to 4.0 stars | **+89%** |
|
||||
| 4.0 to 4.5 stars | **+20-30%** |
|
||||
| 4.3 to 4.6 stars | **+22-28%** (Finance, Health) |
|
||||
| 0.4-star gap vs competitor | **~25% lost installs** from same search |
|
||||
| 3-star vs 5-star app | **50% fewer conversions** for 3-star |
|
||||
|
||||
**Critical thresholds:**
|
||||
|
||||
- **4.0 stars** = minimum for Apple featuring, user trust, conversion viability
|
||||
- **4.5+ stars** = optimal zone. Sweet spot: 4.1-4.9
|
||||
- **5.0 stars** can look suspicious to users
|
||||
- **Below 3.5** = sharp visibility drop on both stores
|
||||
- **79% of users** check ratings before downloading
|
||||
- **50% reject** apps below 3 stars
|
||||
|
||||
Sources: AppFollow, MobileAction, Sensor Tower, Troof.ai
|
||||
|
||||
## Preview Video Impact
|
||||
|
||||
**iOS:** +20-40% conversion lift (video autoplays on product page)
|
||||
**Google Play:** Minimal lift (only ~6% of visitors tap to play)
|
||||
|
||||
- Autoplay introduced in iOS 11 caused **+47% conversion jump**
|
||||
- Users who watch video are **2x more likely to install**
|
||||
- Average watch time: **4-6.5 seconds** (first 5 seconds are critical)
|
||||
- 50%+ of viewers watch to the end
|
||||
|
||||
**Takeaway:** Video is high-ROI on iOS, low-ROI on Google Play.
|
||||
|
||||
Sources: StoreMaven, SplitMetrics, Leanplum
|
||||
|
||||
## Screenshot Impact
|
||||
|
||||
- **90% of users** do not scroll past the 3rd screenshot
|
||||
- Average scroll rate: only **17%**
|
||||
- Users spend **6-10 seconds** scanning before deciding
|
||||
- **First screenshot decides everything**
|
||||
- Well-designed screenshots lift conversion **20-35%**
|
||||
- A/B test winners see **10-25% improvement**
|
||||
- **Optimal count:** 4-5 for utility apps, 5-6 for complex apps
|
||||
- More than 6: diminishing returns, can cause decision paralysis
|
||||
- Top 200 apps update screenshots **2-4 times/year**
|
||||
- Top Google Play games update visuals **up to 8x/year**
|
||||
- **57% of top games** A/B tested screenshots at least 2x in 2024
|
||||
|
||||
Sources: AppTweak, ASOMobile, Sensor Tower
|
||||
|
||||
## Custom Product Pages (Apple CPPs)
|
||||
|
||||
- Average conversion lift: **+5.9% for apps**, **+3.5% for games**
|
||||
- Best cases: up to **+8.6%**
|
||||
- Organic referral: **+2.5 percentage points** (156% lift vs 1.6% baseline)
|
||||
- Apple Ads CPP CVR: **55.8% in 2024** (up from 42.1% in 2023)
|
||||
- **Only 31% of apps** and **26% of games** use CPPs (low adoption = opportunity)
|
||||
- Screenshot reordering alone produced **+16.6% installs** in one case
|
||||
|
||||
Sources: AppTweak, SplitMetrics, MobileAction
|
||||
|
||||
## Custom Store Listings (Google Play CSLs)
|
||||
|
||||
- Up to **50 custom versions** per app
|
||||
- Case study (Lockwood/Avakin Life): **+57% CVR** over 2 months
|
||||
- Can target inactive/churned users (28+ days no activity)
|
||||
|
||||
Source: Phiture, MobileAction
|
||||
|
||||
## In-App Events (Apple)
|
||||
|
||||
- **55% of top 200 apps** use them regularly
|
||||
- +**15-20% more impressions** from editorial/browse placements
|
||||
- One case: **+124% surge** in total impressions
|
||||
- One case: **+50% impressions AND first-time downloads**
|
||||
- Search CVR uptick: **+10.3%**
|
||||
- Re-downloads increase: **+15.5%**
|
||||
- **Boost is short-lived** -- KPIs drop to baseline when event ends
|
||||
- Optimal: **2-4 active events per month**
|
||||
|
||||
Sources: Phiture, AppTweak, Appalize
|
||||
|
||||
## Promotional Content (Google Play)
|
||||
|
||||
- Apps with featuring see **2x explore acquisitions** (official Google)
|
||||
- +2% 28-day active users and +4% revenue on average
|
||||
|
||||
Source: Google Play Console documentation
|
||||
|
||||
## A/B Test Impact Thresholds
|
||||
|
||||
| Improvement | Classification |
|
||||
| ----------- | ---------------------------------- |
|
||||
| >10% | Strong winner -- apply immediately |
|
||||
| 5-10% | Meaningful winner |
|
||||
| 2-5% | Marginal winner |
|
||||
| <2% | Noise -- not significant |
|
||||
|
||||
Source: SplitMetrics, MobileAction
|
||||
@@ -0,0 +1,131 @@
|
||||
# Google Play Store — Official Specs & Guidelines
|
||||
|
||||
All data from support.google.com and developer.android.com as of March 2026.
|
||||
|
||||
## Character Limits
|
||||
|
||||
| Field | Limit | Indexed? | Notes |
|
||||
| ----------------- | ----------- | ---------------------- | ------------------------------------- |
|
||||
| App Title | 30 chars | Yes (strongest signal) | Reduced from 50 in Sept 2021 |
|
||||
| Short Description | 80 chars | Yes | Visible without expanding |
|
||||
| Full Description | 4,000 chars | **Yes (heavily)** | Google NLP indexes entire text |
|
||||
| Developer Name | 64 chars | Partial | Same emoji/caps restrictions as title |
|
||||
|
||||
## Prohibited in Metadata (enforced since Sept 2021)
|
||||
|
||||
**Title, Icon, Developer Name:**
|
||||
|
||||
- Emojis, emoticons, repeated special characters
|
||||
- ALL CAPS (unless registered brand)
|
||||
- Performance claims: "top," "best," "#1," "free," "no ads"
|
||||
- Misleading store performance or endorsement
|
||||
- Calls-to-action: "update now," "download now"
|
||||
|
||||
**Short Description:**
|
||||
|
||||
- Same performance claims as title
|
||||
- Calls-to-action
|
||||
- Unattributed testimonials
|
||||
|
||||
**Screenshots, Feature Graphic, Video:**
|
||||
|
||||
- Time-sensitive taglines
|
||||
- Calls-to-action ("Download now," "Play now")
|
||||
- Must authentically showcase app functionality
|
||||
|
||||
## Screenshot Specs
|
||||
|
||||
| Device | Min | Max | Aspect Ratio | Min Resolution | Max Long Edge |
|
||||
| ---------- | ----- | ----- | ------------ | -------------- | ------------- |
|
||||
| Phone | **2** | **8** | 9:16 or 16:9 | 320px any side | 3,840px |
|
||||
| 7" Tablet | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
|
||||
| 10" Tablet | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
|
||||
| Chromebook | 4 | 8 | 9:16 or 16:9 | 1,080px short | 7,680px |
|
||||
| Wear OS | 1 | 8 | **1:1** | 384x384 | 3,840px |
|
||||
| Android TV | 1 | 8 | **16:9** | 1,920x1,080 | 3,840px |
|
||||
|
||||
- **Recommended phone size:** 1080x1920 (portrait)
|
||||
- **Format:** JPEG or 24-bit PNG (no alpha)
|
||||
- **Max file size:** 8 MB each
|
||||
|
||||
**Note:** Google Play max is 8 screenshots per device, not 10 like Apple.
|
||||
|
||||
## Feature Graphic
|
||||
|
||||
- **Dimensions:** 1024 x 500 px (exact, required)
|
||||
- **Format:** JPEG or 24-bit PNG (no alpha)
|
||||
- Displayed at top of listing and in featured placements
|
||||
|
||||
## App Icon
|
||||
|
||||
- **Dimensions:** 512 x 512 px
|
||||
- **Format:** 32-bit PNG (with alpha)
|
||||
- **Max file size:** 1,024 KB
|
||||
- **Shape:** Full square (Google applies 30% corner radius automatically)
|
||||
- **Prohibited:** Ranking claims, download counts, deal text, emoji
|
||||
|
||||
## Preview Video
|
||||
|
||||
- **Format:** YouTube URL (public or unlisted)
|
||||
- **Duration:** 30 seconds to 2 minutes recommended
|
||||
- No ads, no monetization, must be embeddable, not age-restricted
|
||||
- **Does NOT autoplay** (only ~6% of visitors tap to play)
|
||||
|
||||
## Store Listing Experiments (A/B Testing)
|
||||
|
||||
- **Variants:** Up to 3 per experiment (plus control)
|
||||
- **Testable:** Icon, feature graphic, screenshots, video, short description, full description
|
||||
- **Concurrent:** Cannot run more than 1 default graphics experiment simultaneously
|
||||
- **Audience:** Signed-in Google Play users only
|
||||
- **Metrics:** First-time installers + retained first-time installers (1-day retention)
|
||||
- **Duration:** Run at least 7 days (weekday/weekend variance)
|
||||
- **Localized:** Test across up to 5 languages simultaneously
|
||||
|
||||
## Custom Store Listings
|
||||
|
||||
- **Max:** 50 per app (100 for Play partners)
|
||||
- **Customizable:** Title, short/full description, icon, screenshots, feature graphic, video
|
||||
- **Targeting:** Country/region, pre-registration, install state, Google Ads campaigns, inactive/churned users (28+ days)
|
||||
- **2025 addition:** Gemini AI auto-generates text for CSLs in Play Console
|
||||
|
||||
## Promotional Content (LiveOps)
|
||||
|
||||
| Type | Description | Duration |
|
||||
| ----------------- | ------------------------------ | -------------------- |
|
||||
| Offers | Discounts, free items, bundles | Up to 28 days |
|
||||
| Events | Time-limited in-app events | Must have time limit |
|
||||
| Major Update | Significant new features | Max 1 week |
|
||||
| Crossover (games) | Cross-game/IP collaboration | Varies |
|
||||
|
||||
- Submit **4+ days** before start (standard review)
|
||||
- Submit **14+ days** before for featuring requests
|
||||
- **Impact:** "Over twice as many explore acquisitions during featuring" (official Google)
|
||||
|
||||
## Android Vitals — Ranking Thresholds
|
||||
|
||||
Apps exceeding these thresholds get **reduced visibility** in search and recommendations.
|
||||
|
||||
| Metric | Overall Threshold | Per-Device Threshold |
|
||||
| ---------------------------- | ----------------- | -------------------- |
|
||||
| User-Perceived Crash Rate | **1.09%** | 8% |
|
||||
| User-Perceived ANR Rate | **0.47%** | 8% |
|
||||
| Excessive Partial Wake Locks | 5% | N/A |
|
||||
|
||||
**Consequences:** Reduced search visibility, warning labels on listing, quality alerts to users before install.
|
||||
**Recovery:** Google checks daily using 28-day rolling average.
|
||||
|
||||
## Search Ranking — Official Factors
|
||||
|
||||
Google confirms these affect ranking:
|
||||
|
||||
1. **Metadata relevance** — Title carries most weight. NLP scans title + short desc + full desc.
|
||||
2. **App quality** — Android Vitals (crash/ANR rates)
|
||||
3. **Ratings and reviews** — Star rating + review text. 85% of featured apps have 4.0+
|
||||
4. **Install volume and velocity** — Total installs + daily/weekly frequency
|
||||
5. **Engagement and retention** — Session frequency, duration, retention rates
|
||||
6. **Update frequency** — Regular updates signal active maintenance
|
||||
7. **Localization** — Regional keyword/visual adaptation. 59% of US apps localize titles.
|
||||
|
||||
Sources: support.google.com/googleplay/android-developer/answer/4448378,
|
||||
support.google.com/googleplay/android-developer/answer/9898842,
|
||||
developer.android.com/topic/performance/vitals
|
||||
@@ -0,0 +1,213 @@
|
||||
# ASO Audit Report Template
|
||||
|
||||
Use this structure for all ASO audit reports.
|
||||
|
||||
---
|
||||
|
||||
## Header
|
||||
|
||||
```
|
||||
# ASO Audit: {App Name}
|
||||
**Store:** {Apple App Store / Google Play}
|
||||
**URL:** {listing URL}
|
||||
**Audit date:** {date}
|
||||
**Brand tier:** {Dominant / Established / Challenger} — {one-line justification}
|
||||
**Overall Score:** {score}/100 (Grade: {A/B/C/D/F})
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Score Card
|
||||
|
||||
```
|
||||
| Dimension | Score | Grade | Key Issue |
|
||||
|-----------|-------|-------|-----------|
|
||||
| Title & Subtitle | X/10 | {grade} | {one-line summary} |
|
||||
| Description | X/10 | {grade} | {one-line summary} |
|
||||
| Visual Assets | X/10 | {grade} | {one-line summary} |
|
||||
| Ratings & Reviews | X/10 | {grade} | {one-line summary} |
|
||||
| Metadata & Freshness | X/10 | {grade} | {one-line summary} |
|
||||
| Conversion Signals | X/10 | {grade} | {one-line summary} |
|
||||
| **OVERALL** | **{weighted}/100** | **{grade}** | |
|
||||
```
|
||||
|
||||
Grade scale per dimension: 9-10 = A, 7-8 = B, 5-6 = C, 3-4 = D, 1-2 = F
|
||||
|
||||
---
|
||||
|
||||
## Top 3 Quick Wins
|
||||
|
||||
Highest-impact changes that take under 1 hour:
|
||||
|
||||
```
|
||||
### 1. {Action verb} — {specific change}
|
||||
**Impact:** {High/Medium} | **Effort:** {<15 min / <30 min / <1 hour}
|
||||
**Current:** {what it is now}
|
||||
**Recommended:** {exact replacement, with character count}
|
||||
**Why:** {one sentence explaining the impact}
|
||||
|
||||
### 2. ...
|
||||
### 3. ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Detailed Findings
|
||||
|
||||
### Title & Subtitle Analysis
|
||||
|
||||
```
|
||||
**Current title:** "{title}" ({X}/30 chars used)
|
||||
**Current subtitle/short desc:** "{subtitle}" ({X}/30 or /80 chars used)
|
||||
|
||||
**Issues found:**
|
||||
- {issue 1}
|
||||
- {issue 2}
|
||||
|
||||
**Recommended title:** "{new title}" ({X}/30 chars) — {rationale}
|
||||
**Recommended subtitle:** "{new subtitle}" ({X}/30 or /80 chars) — {rationale}
|
||||
```
|
||||
|
||||
### Description Analysis
|
||||
|
||||
```
|
||||
**First 3 lines (above fold):**
|
||||
> {quoted text}
|
||||
|
||||
**Issues found:**
|
||||
- {issue 1}
|
||||
- {issue 2}
|
||||
|
||||
**Keyword density (Google Play only):** {X}% — target: 2-3%
|
||||
**Top keywords found:** {keyword1} (Xn), {keyword2} (Xn), ...
|
||||
**Missing high-value keywords:** {keyword1}, {keyword2}, ...
|
||||
|
||||
**Recommended first 3 lines:**
|
||||
> {rewritten text}
|
||||
```
|
||||
|
||||
### Visual Assets Analysis
|
||||
|
||||
```
|
||||
**Screenshots:** {count} ({store} shows first {3/all} in search)
|
||||
**Preview video:** {Yes/No}
|
||||
**Icon assessment:** {description}
|
||||
**Feature graphic (Google Play):** {Yes/No}
|
||||
|
||||
**Screenshot audit:**
|
||||
1. {screenshot 1 description} — {pass/issue}
|
||||
2. {screenshot 2 description} — {pass/issue}
|
||||
...
|
||||
|
||||
**Recommendations:**
|
||||
- {specific visual change 1}
|
||||
- {specific visual change 2}
|
||||
```
|
||||
|
||||
### Ratings & Reviews Analysis
|
||||
|
||||
```
|
||||
**Average rating:** {X.X} stars ({count} ratings)
|
||||
**Recent review sentiment:** {Positive/Mixed/Negative}
|
||||
**Common complaints:** {theme1}, {theme2}
|
||||
**Developer responses:** {Yes, active / Sporadic / None}
|
||||
|
||||
**Recommendations:**
|
||||
- {specific action 1}
|
||||
- {specific action 2}
|
||||
```
|
||||
|
||||
### Metadata & Freshness
|
||||
|
||||
```
|
||||
**Last updated:** {date} ({X days/months ago})
|
||||
**Localizations:** {count} languages
|
||||
**Category:** {current category}
|
||||
**In-app events/LiveOps:** {Yes/No}
|
||||
|
||||
**Recommendations:**
|
||||
- {specific action 1}
|
||||
- {specific action 2}
|
||||
```
|
||||
|
||||
### Conversion Signals
|
||||
|
||||
```
|
||||
**Price model:** {Free / Freemium / Paid}
|
||||
**IAP count:** {count}
|
||||
**Downloads (Google Play):** {range}
|
||||
**Social proof visible:** {awards, press, badges — or "none"}
|
||||
|
||||
**Recommendations:**
|
||||
- {specific action 1}
|
||||
- {specific action 2}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Keyword Suggestions
|
||||
|
||||
```
|
||||
| Keyword | Rationale | Where to Place | Priority |
|
||||
|---------|-----------|----------------|----------|
|
||||
| {keyword} | {why this keyword} | {title/subtitle/description/keyword field} | {High/Med/Low} |
|
||||
| ... | ... | ... | ... |
|
||||
```
|
||||
|
||||
Note: Without paid ASO tools, exact search volume is unavailable. These
|
||||
suggestions are based on category analysis, competitor metadata, and semantic
|
||||
relevance. Validate with AppTweak, Sensor Tower, or MobileAction for volume data.
|
||||
|
||||
---
|
||||
|
||||
## Competitor Comparison (if applicable)
|
||||
|
||||
```
|
||||
| Metric | {Your App} | {Competitor 1} | {Competitor 2} |
|
||||
|--------|-----------|----------------|----------------|
|
||||
| Title keywords | ... | ... | ... |
|
||||
| Rating | ... | ... | ... |
|
||||
| Screenshots | ... | ... | ... |
|
||||
| Video | ... | ... | ... |
|
||||
| Description keywords | ... | ... | ... |
|
||||
| Last updated | ... | ... | ... |
|
||||
| Overall ASO score | ... | ... | ... |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Priority Action Plan
|
||||
|
||||
Ordered by impact (high to low), grouped by effort:
|
||||
|
||||
```
|
||||
### Do This Week (Quick Wins)
|
||||
1. {action} — {expected impact}
|
||||
2. {action} — {expected impact}
|
||||
|
||||
### Do This Month (Medium Effort)
|
||||
3. {action} — {expected impact}
|
||||
4. {action} — {expected impact}
|
||||
|
||||
### Plan for Next Quarter (High Effort)
|
||||
5. {action} — {expected impact}
|
||||
6. {action} — {expected impact}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitations
|
||||
|
||||
Always include this section:
|
||||
|
||||
> **What this audit cannot measure without paid ASO tools:**
|
||||
>
|
||||
> - Exact keyword search volume and difficulty scores
|
||||
> - Historical keyword ranking positions
|
||||
> - Download and revenue estimates
|
||||
> - Apple keyword field contents (hidden from public view)
|
||||
> - Install conversion rate data (only available to app owner in console)
|
||||
> - A/B test results from previous experiments
|
||||
>
|
||||
> For these data points, consider using AppTweak ($69/mo), Sensor Tower, or
|
||||
> MobileAction ($69/mo).
|
||||
@@ -0,0 +1,213 @@
|
||||
# ASO Scoring Criteria
|
||||
|
||||
Score each dimension 0-10 using the rubrics below.
|
||||
**Apply brand maturity tier adjustments** from Phase 1.5 of the main skill.
|
||||
|
||||
---
|
||||
|
||||
## Brand Maturity Adjustments (apply to all dimensions)
|
||||
|
||||
Before scoring, determine the app's tier: **Dominant**, **Established**, or **Challenger**.
|
||||
|
||||
**Dominant apps (Instagram, Uber, Spotify, WhatsApp, Netflix):**
|
||||
|
||||
- Brand-only titles score 8+ (the brand IS the keyword)
|
||||
- Lifestyle/brand screenshots score same as captioned UI screenshots
|
||||
- Generic What's New at weekly+ cadence scores 8+
|
||||
- Missing in-app events for utility apps is not a penalty
|
||||
- Description scored on conversion quality only, not keyword presence
|
||||
- Localization scored relative to actual market footprint
|
||||
- Missing preview video is acceptable if brand awareness is near-universal
|
||||
|
||||
**Established apps (Duolingo, Strava, Notion, Calm, Cash App):**
|
||||
|
||||
- Brand-first titles with 1-2 keywords score normally
|
||||
- Strategic description/visual choices get benefit of the doubt
|
||||
- All other dimensions scored normally
|
||||
|
||||
**Challenger apps (most apps):**
|
||||
|
||||
- Scored strictly against textbook ASO — every character and feature matters
|
||||
|
||||
**Key principle:** Before docking points, ask: "Is this a mistake or a data-informed
|
||||
choice by a team with more information than I have?"
|
||||
|
||||
---
|
||||
|
||||
## 1. Title & Subtitle (Weight: 20%)
|
||||
|
||||
**Challenger rubric:**
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9-10 | Brand + high-value keyword in title, complementary keywords in subtitle, no word repetition across fields, near max character usage, instantly communicates app purpose |
|
||||
| 7-8 | Good keyword presence, minor character waste (5+ unused chars), clear purpose |
|
||||
| 5-6 | Has keywords but poor placement, some repetition between fields, purpose somewhat clear |
|
||||
| 3-4 | Title is brand-only or generic, subtitle missing or weak, poor character usage |
|
||||
| 1-2 | No keyword strategy, title doesn't communicate purpose, major character waste |
|
||||
| 0 | Cannot assess (data unavailable) |
|
||||
|
||||
**Dominant/Established adjustment:** Brand-only titles (e.g., "Instagram") are
|
||||
valid if the brand has high search volume. Score 8+ for Dominant apps where
|
||||
brand recognition eliminates the need for generic keywords. Evaluate whether
|
||||
unused characters represent waste or intentional simplicity.
|
||||
|
||||
**Check for:**
|
||||
|
||||
- Characters used vs limit (title: 30, subtitle/short desc: 30/80). "Near max" = within 3 chars of the limit (27+/30, 77+/80)
|
||||
- Primary keyword in title
|
||||
- Keyword duplication between title and subtitle
|
||||
- Whether app purpose is immediately clear
|
||||
- Unnecessary words (articles, prepositions) consuming space
|
||||
- Special characters or claims ("#1", "best") that risk rejection (Apple)
|
||||
|
||||
---
|
||||
|
||||
## 2. Description (Weight: 15%)
|
||||
|
||||
### Apple App Store
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| 9-10 | First 3 lines hook with clear value prop, structured with features/benefits/social proof/CTA, promotional text actively used, compelling and scannable |
|
||||
| 7-8 | Good opening, decent structure, could improve scannability or CTA |
|
||||
| 5-6 | Generic opening ("Welcome to..."), some structure, missing CTA or social proof |
|
||||
| 3-4 | Wall of text, no clear value prop above fold, no promotional text |
|
||||
| 1-2 | Minimal or boilerplate description, no effort |
|
||||
| 0 | Cannot assess |
|
||||
|
||||
### Google Play
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9-10 | Keywords in first 3 sentences, 2-3% natural density throughout, HTML formatting used, structured sections, strong CTA, keywords feel natural |
|
||||
| 7-8 | Good keyword presence, some structure, density slightly off (1-2% or 3-4%) |
|
||||
| 5-6 | Keywords present but sparse (<1%) or stuffed (>5%), weak structure |
|
||||
| 3-4 | No keyword strategy visible, poor formatting, wall of text |
|
||||
| 1-2 | Minimal description, no keywords, no structure |
|
||||
| 0 | Cannot assess |
|
||||
|
||||
**Check for:**
|
||||
|
||||
- First 3 lines quality (visible before "Read More")
|
||||
- Feature-benefit framing (not just feature lists)
|
||||
- Social proof (downloads, awards, press mentions)
|
||||
- Call to action
|
||||
- Keyword density (Google Play only - count target keywords / total words)
|
||||
- HTML formatting usage (Google Play)
|
||||
- Promotional text presence and quality (Apple)
|
||||
|
||||
---
|
||||
|
||||
## 3. Visual Assets (Weight: 25%)
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9-10 | 8-10 screenshots with clear messaging/captions, preview video present, screenshots tell a story in sequence, each communicates one benefit, icon is distinctive and memorable |
|
||||
| 7-8 | 6-7 screenshots with captions, good icon, no video OR good video but some screenshot messaging unclear |
|
||||
| 5-6 | 5+ screenshots but weak/no captions, basic icon, no video, screenshots are UI dumps |
|
||||
| 3-4 | 3-4 screenshots, no captions, generic icon, no storytelling |
|
||||
| 1-2 | Fewer than 3 screenshots, or screenshots are raw unedited UI, poor icon |
|
||||
| 0 | Cannot assess |
|
||||
|
||||
**Check for:**
|
||||
|
||||
- Screenshot count (minimum 5, ideal 8-10)
|
||||
- Caption/overlay text on screenshots (one message per screen, 5-7 words max)
|
||||
- First 3 screenshots (highest conversion impact on Apple)
|
||||
- Preview video presence and quality
|
||||
- Icon distinctiveness (no text in icon, bold shapes, stands out)
|
||||
- Feature graphic presence (Google Play - mandatory for featured placements)
|
||||
- Screenshot storytelling flow (do they tell a coherent story?)
|
||||
- Localized visual assets (for non-English markets)
|
||||
- Caption keywords (Apple - indexed since June 2025)
|
||||
|
||||
---
|
||||
|
||||
## 4. Ratings & Reviews (Weight: 20%)
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ------------------------------------------------------------------------------------------------------ |
|
||||
| 9-10 | 4.5+ stars, 10K+ ratings, recent reviews positive, developer responds to negatives, steady review flow |
|
||||
| 7-8 | 4.0-4.4 stars, 1K+ ratings, mostly positive recent reviews, some developer responses |
|
||||
| 5-6 | 3.5-3.9 stars, 500+ ratings, mixed recent reviews, no developer responses |
|
||||
| 3-4 | 3.0-3.4 stars, <500 ratings, negative themes in recent reviews |
|
||||
| 1-2 | Below 3.0 stars, few ratings, no developer engagement, visible complaints |
|
||||
| 0 | No ratings yet or cannot assess |
|
||||
|
||||
**Check for:**
|
||||
|
||||
- Average rating (target: 4.0+ minimum, 4.5+ ideal)
|
||||
- Total rating count
|
||||
- Recent review sentiment (last 5-10 visible reviews)
|
||||
- Common complaint themes (bugs, crashes, pricing, UX)
|
||||
- Developer response presence and quality
|
||||
- Rating trend (improving or declining, if visible)
|
||||
- Review recency (fresh reviews signal active user base)
|
||||
|
||||
---
|
||||
|
||||
## 5. Metadata & Freshness (Weight: 10%)
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9-10 | Updated within last month, 10+ localizations, optimal category choice, in-app events/LiveOps active, data safety complete |
|
||||
| 7-8 | Updated within 2 months, 5+ localizations, good category, data safety present |
|
||||
| 5-6 | Updated within 3 months, 2-4 localizations, acceptable category |
|
||||
| 3-4 | Updated 3-6 months ago, 1-2 localizations, possibly wrong category |
|
||||
| 1-2 | Not updated in 6+ months, single language, poor category choice |
|
||||
| 0 | Cannot assess |
|
||||
|
||||
**Check for:**
|
||||
|
||||
- Last update date and recency
|
||||
- Number of supported languages/localizations
|
||||
- Category selection (is it the best fit? less competitive alternative?)
|
||||
- In-app events (Apple) or promotional content (Google) presence
|
||||
- Data safety / privacy nutrition label completeness
|
||||
- Age rating appropriateness
|
||||
- Version history quality (do release notes communicate value?)
|
||||
- What's New text quality
|
||||
|
||||
---
|
||||
|
||||
## 6. Conversion Signals (Weight: 10%)
|
||||
|
||||
| Score | Criteria |
|
||||
| ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 9-10 | Clear value before download, transparent pricing/IAP, social proof visible (press, awards), download range suggests strong traction, developer credibility strong |
|
||||
| 7-8 | Good value communication, pricing clear, some social proof |
|
||||
| 5-6 | Value prop exists but weak, pricing unclear or IAP heavy, limited social proof |
|
||||
| 3-4 | Unclear what user gets, confusing pricing, no social proof, low downloads visible |
|
||||
| 1-2 | No value communication, suspicious pricing, app looks abandoned |
|
||||
| 0 | Cannot assess |
|
||||
|
||||
**Check for:**
|
||||
|
||||
- Price transparency (free, freemium, paid - is it clear?)
|
||||
- In-app purchase list quality (do IAP names communicate value?)
|
||||
- Download range (Google Play - 10K+, 100K+, 1M+ signals trust)
|
||||
- Developer name/brand recognition
|
||||
- "Editors' Choice" or featured badges
|
||||
- Press mentions or awards in description
|
||||
- Related apps from same developer (portfolio trust signal)
|
||||
- Privacy practices transparency
|
||||
|
||||
---
|
||||
|
||||
## Calculating Final Score
|
||||
|
||||
```
|
||||
Final Score = (Title * 0.20) + (Description * 0.15) + (Visuals * 0.25)
|
||||
+ (Ratings * 0.20) + (Metadata * 0.10) + (Conversion * 0.10)
|
||||
|
||||
Scale to 100: Final Score * 10
|
||||
```
|
||||
|
||||
**Example:** Title: 7, Description: 6, Visuals: 8, Ratings: 9, Metadata: 5, Conversion: 7
|
||||
|
||||
```
|
||||
(7 * 0.20) + (6 * 0.15) + (8 * 0.25) + (9 * 0.20) + (5 * 0.10) + (7 * 0.10)
|
||||
= 1.4 + 0.9 + 2.0 + 1.8 + 0.5 + 0.7
|
||||
= 7.3 → 73/100 → Grade: B
|
||||
```
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: churn-prevention
|
||||
description: "When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or implement retention strategies. Also use when the user mentions 'churn,' 'cancel flow,' 'offboarding,' 'save offer,' 'dunning,' 'failed payment recovery,' 'win-back,' 'retention,' 'exit survey,' 'pause subscription,' or 'involuntary churn.' This skill covers voluntary churn (cancel flows, save offers, exit surveys) and involuntary churn (dunning, payment recovery). For post-cancel win-back email sequences, see email-sequence. For in-app upgrade paywalls, see paywall-upgrade-cro."
|
||||
description: "When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or implement retention strategies. Also use when the user mentions 'churn,' 'cancel flow,' 'offboarding,' 'save offer,' 'dunning,' 'failed payment recovery,' 'win-back,' 'retention,' 'exit survey,' 'pause subscription,' 'involuntary churn,' 'people keep canceling,' 'churn rate is too high,' 'how do I keep users,' or 'customers are leaving.' Use this whenever someone is losing subscribers or wants to build systems to prevent it. For post-cancel win-back email sequences, see emails. For in-app upgrade paywalls, see paywalls."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Churn Prevention
|
||||
@@ -12,7 +12,7 @@ You are an expert in SaaS retention and churn prevention. Your goal is to help r
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
@@ -252,7 +252,7 @@ Health Score = (
|
||||
| Trigger | Intervention |
|
||||
|---------|-------------|
|
||||
| Usage drop >50% for 2 weeks | "We noticed you haven't used [feature]. Need help?" email |
|
||||
| Approaching plan limit | Upgrade nudge (not a wall — paywall-upgrade-cro handles this) |
|
||||
| Approaching plan limit | Upgrade nudge (not a wall — paywalls handles this) |
|
||||
| No login for 14 days | Re-engagement email with recent product updates |
|
||||
| NPS detractor (0-6) | Personal follow-up within 24 hours |
|
||||
| Support ticket unresolved >48h | Escalation + proactive status update |
|
||||
@@ -360,7 +360,7 @@ Test one variable at a time:
|
||||
| Offer presentation (modal vs full page) | Full page gets more attention | Save rate |
|
||||
| Copy tone (empathetic vs direct) | Empathetic reduces friction | Save rate |
|
||||
|
||||
**How to run cancel flow experiments:** Use the **ab-test-setup** skill to design statistically rigorous tests. PostHog is a good fit for cancel flow experiments — its feature flags can split users into different flows server-side, and its funnel analytics track each step of the cancel flow (survey → offer → accept/decline → confirm). See the [PostHog integration guide](../../tools/integrations/posthog.md) for setup.
|
||||
**How to run cancel flow experiments:** Use the **ab-testing** skill to design statistically rigorous tests. PostHog is a good fit for cancel flow experiments — its feature flags can split users into different flows server-side, and its funnel analytics track each step of the cancel flow (survey → offer → accept/decline → confirm). See the [PostHog integration guide](../../tools/integrations/posthog.md) for setup.
|
||||
|
||||
---
|
||||
|
||||
@@ -375,7 +375,7 @@ Test one variable at a time:
|
||||
- **Guilt-trip copy** — "Are you sure you want to abandon us?" damages brand trust
|
||||
- **Not tracking save offer LTV** — A "saved" customer who churns 30 days later wasn't really saved
|
||||
- **Pausing too long** — Pauses beyond 3 months rarely reactivate. Set limits.
|
||||
- **No post-cancel path** — Always make reactivation easy and trigger win-back emails
|
||||
- **No post-cancel path** — Make reactivation easy and trigger win-back emails, because some churned users will want to come back
|
||||
|
||||
---
|
||||
|
||||
@@ -416,9 +416,9 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md).
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **email-sequence**: For win-back email sequences after cancellation
|
||||
- **paywall-upgrade-cro**: For in-app upgrade moments and trial expiration
|
||||
- **pricing-strategy**: For plan structure and annual discount strategy
|
||||
- **onboarding-cro**: For activation to prevent early churn
|
||||
- **analytics-tracking**: For setting up churn signal events
|
||||
- **ab-test-setup**: For testing cancel flow variations with statistical rigor
|
||||
- **emails**: For win-back email sequences after cancellation
|
||||
- **paywalls**: For in-app upgrade moments and trial expiration
|
||||
- **pricing**: For plan structure and annual discount strategy
|
||||
- **onboarding**: For activation to prevent early churn
|
||||
- **analytics**: For setting up churn signal events
|
||||
- **ab-testing**: For testing cancel flow variations with statistical rigor
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
{
|
||||
"skill_name": "churn-prevention",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Our SaaS product has a 7% monthly churn rate and we need to bring it down. We're a $49/month project management tool with about 2,000 paying customers. Can you help us design a churn prevention strategy?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should address both voluntary and involuntary churn. Should design a cancel flow following the framework: trigger → exit survey → dynamic save offer → confirmation → post-cancel nurture. Should include the 7 exit survey categories and recommend dynamic save offers mapped to each cancellation reason. Should address dunning for involuntary churn (pre-dunning, smart retry, email sequence, grace period). Should recommend a health score model. Should provide prioritized implementation plan.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Addresses both voluntary and involuntary churn",
|
||||
"Designs cancel flow with proper stages",
|
||||
"Includes exit survey with multiple categories",
|
||||
"Maps save offers to cancellation reasons",
|
||||
"Addresses dunning stack for payment recovery",
|
||||
"Recommends health score model",
|
||||
"Provides prioritized implementation plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We keep losing customers because their credit cards expire. About 15% of our churn is from failed payments. How do we fix this?",
|
||||
"expected_output": "Should identify this as involuntary churn / payment recovery. Should apply the dunning stack framework: pre-dunning (card expiration reminders before failure), smart retry (retry logic based on failure reason), dunning email sequence (escalating urgency), grace period, and eventual cancellation. Should provide specific timing for each stage. Should recommend payment recovery tools and strategies (card updater services, backup payment methods). Should include recovery rate benchmarks.",
|
||||
"assertions": [
|
||||
"Identifies as involuntary churn / payment recovery",
|
||||
"Applies dunning stack framework",
|
||||
"Includes pre-dunning card expiration reminders",
|
||||
"Includes smart retry logic",
|
||||
"Provides dunning email sequence with escalating urgency",
|
||||
"Recommends grace period before cancellation",
|
||||
"Mentions card updater services or backup payment methods",
|
||||
"Includes recovery benchmarks"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "what should we show users when they click the cancel button? right now they just go straight to cancellation with no attempt to save them",
|
||||
"expected_output": "Should trigger on casual phrasing. Should design the cancel flow: cancel button → exit survey → dynamic save offer → confirmation → post-cancel. Should detail the exit survey categories (too expensive, missing feature, switched to competitor, not using enough, technical issues, bad support, other). Should provide dynamic save offers matched to each reason (e.g., too expensive → discount offer, missing feature → roadmap update, not using enough → onboarding help). Should include copy recommendations for each screen. Should warn against dark patterns (making it impossible to cancel).",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Designs multi-step cancel flow",
|
||||
"Includes exit survey with 7 categories",
|
||||
"Provides dynamic save offers mapped to reasons",
|
||||
"Includes copy recommendations",
|
||||
"Warns against dark patterns",
|
||||
"Includes confirmation and post-cancel steps"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "How do we identify which customers are at risk of churning before they actually cancel? We want to be proactive.",
|
||||
"expected_output": "Should apply the health score model framework. Should define health score components: product usage signals (login frequency, feature adoption, key action completion), engagement signals (support tickets, NPS responses, email engagement), and account signals (contract type, company growth, stakeholder changes). Should recommend scoring methodology (0-100 scale). Should define risk tiers and recommended interventions for each tier. Should suggest data sources and implementation approach.",
|
||||
"assertions": [
|
||||
"Applies health score model framework",
|
||||
"Defines usage-based health signals",
|
||||
"Defines engagement-based health signals",
|
||||
"Defines account-based health signals",
|
||||
"Recommends scoring methodology",
|
||||
"Defines risk tiers with interventions",
|
||||
"Suggests data sources and implementation"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Our exit survey shows that 40% of cancellations say 'too expensive' as the reason. What save offers should we try?",
|
||||
"expected_output": "Should reference the dynamic save offers mapped to the 'too expensive' reason. Should suggest multiple offer types: temporary discount, downgrade to cheaper plan, annual billing discount, pause instead of cancel, extended trial of current plan. Should recommend testing different offers to find what works best. Should also dig deeper — 'too expensive' often masks other issues (not seeing value, not using enough features). Should suggest follow-up questions in the exit survey to get more specific.",
|
||||
"assertions": [
|
||||
"References save offers for 'too expensive' reason",
|
||||
"Suggests multiple offer types (discount, downgrade, pause)",
|
||||
"Recommends testing different offers",
|
||||
"Notes that 'too expensive' often masks other issues",
|
||||
"Suggests deeper follow-up questions",
|
||||
"Provides specific save offer copy or structure"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "We want to set up a win-back email sequence for customers who already cancelled. Can you help write those emails?",
|
||||
"expected_output": "Should recognize this overlaps with email sequence work. Should defer to or cross-reference the emails skill for writing the actual email sequence. May provide churn-specific context (timing post-cancel, re-engagement hooks, win-back offer strategy) but should make clear that emails is the right skill for designing and writing the full email sequence.",
|
||||
"assertions": [
|
||||
"Recognizes overlap with email sequence work",
|
||||
"References or defers to emails skill",
|
||||
"May provide churn-specific context for the sequence",
|
||||
"Does not attempt to write a full email sequence"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -184,7 +184,7 @@ For multi-plan products, downgrade is the strongest save:
|
||||
When the cancel reason is "switching to competitor":
|
||||
|
||||
1. **Ask which competitor** (optional, don't force it)
|
||||
2. **Show a comparison** if you have one (see competitor-alternatives skill)
|
||||
2. **Show a comparison** if you have one (see competitors skill)
|
||||
3. **Offer a migration credit** ("We'll match their price for 3 months")
|
||||
4. **Request a feedback call** ("15 minutes to understand what we're missing")
|
||||
|
||||
@@ -226,7 +226,7 @@ from customers like you.
|
||||
| Day 60 | Address their specific cancel reason if resolved |
|
||||
| Day 90 | Final win-back with special offer |
|
||||
|
||||
**For detailed win-back email sequences**: See the email-sequence skill.
|
||||
**For detailed win-back email sequences**: See the emails skill.
|
||||
|
||||
---
|
||||
|
||||
@@ -290,7 +290,7 @@ The most effective cancel flows use segmentation to show different offers to dif
|
||||
- [ ] Set up proactive intervention triggers
|
||||
- [ ] A/B test discount amounts and offer types
|
||||
- [ ] Segment flows by plan, tenure, and usage
|
||||
- [ ] Post-cancel win-back sequence (coordinate with email-sequence skill)
|
||||
- [ ] Post-cancel win-back sequence (coordinate with emails skill)
|
||||
- [ ] Cohort analysis: churn by channel, plan, tenure
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,290 @@
|
||||
---
|
||||
name: co-marketing
|
||||
description: "When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use when the user says 'co-marketing,' 'partner marketing,' 'joint campaign,' 'who should we partner with,' 'integration marketing,' 'cross-promotion,' 'collaborate with another company,' 'partnership ideas,' or 'co-brand.' For customer referral programs, see referrals. For launch-specific partnerships, see launch."
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
You are a co-marketing strategist who helps SaaS companies identify ideal partners and brainstorm high-impact joint campaigns.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Finding potential co-marketing partners
|
||||
- Brainstorming campaign ideas with a specific partner
|
||||
- Planning joint launches or promotions
|
||||
- Evaluating partnership fit
|
||||
- Structuring co-marketing agreements
|
||||
|
||||
---
|
||||
|
||||
## Partner Identification Framework
|
||||
|
||||
### 1. Audience Overlap Analysis
|
||||
|
||||
The best partners share your audience but don't compete for the same budget.
|
||||
|
||||
**Ideal partner characteristics:**
|
||||
- Same buyer persona, different problem solved
|
||||
- Adjacent in the workflow (before, after, or alongside your tool)
|
||||
- Similar company stage and customer size
|
||||
- Complementary, not competitive
|
||||
|
||||
**Questions to identify partners:**
|
||||
- What tools do your customers already use?
|
||||
- What do they use before/after your product?
|
||||
- Who else is selling to your ICP?
|
||||
- Which integrations do customers request most?
|
||||
|
||||
### 2. Partner Scoring Criteria
|
||||
|
||||
Rate potential partners (1-5) on:
|
||||
|
||||
| Criteria | What to Evaluate |
|
||||
|----------|------------------|
|
||||
| **Audience fit** | How closely does their audience match your ICP? |
|
||||
| **Audience size** | Do they have reach worth partnering for? |
|
||||
| **Brand alignment** | Would you be proud to be associated? |
|
||||
| **Engagement quality** | Do they have an active, engaged audience? |
|
||||
| **Reciprocity potential** | Can you offer them equal value? |
|
||||
| **Ease of execution** | Do they have a partnerships team? History of co-marketing? |
|
||||
|
||||
### 3. Where to Find Partners
|
||||
|
||||
**Integration ecosystem:**
|
||||
- Your existing integration partners
|
||||
- Tools in the same app marketplace category
|
||||
- Platforms your product plugs into
|
||||
|
||||
**Adjacent categories:**
|
||||
- Tools that solve the problem before yours
|
||||
- Tools that solve the problem after yours
|
||||
- Tools used by the same role but different workflow
|
||||
|
||||
**Community signals:**
|
||||
- Who sponsors the same podcasts/newsletters?
|
||||
- Who exhibits at the same conferences?
|
||||
- Who's active in the same communities?
|
||||
- Whose content does your audience share?
|
||||
|
||||
**Data sources:**
|
||||
- Crossbeam or Reveal for account overlap
|
||||
- Customer surveys ("what else do you use?")
|
||||
- G2/Capterra category neighbors
|
||||
- Job postings mentioning your tool + others
|
||||
|
||||
---
|
||||
|
||||
## Co-Marketing Campaign Types
|
||||
|
||||
### Content Partnerships
|
||||
|
||||
| Format | Effort | Lead Sharing | Best For |
|
||||
|--------|--------|--------------|----------|
|
||||
| **Co-authored blog post** | Low | Shared byline, link exchange | Thought leadership, SEO |
|
||||
| **Joint ebook/guide** | Medium | Gated, split leads | Lead gen, deeper topic |
|
||||
| **Research report** | High | Gated, split leads | Authority, PR |
|
||||
| **Guest newsletter swap** | Low | Each keeps own leads | Audience exposure |
|
||||
| **Podcast guest exchange** | Low | Each keeps own leads | Relationship building |
|
||||
|
||||
### Webinars & Events
|
||||
|
||||
| Format | Effort | Best For |
|
||||
|--------|--------|----------|
|
||||
| **Joint webinar** | Medium | Lead gen, product education |
|
||||
| **Virtual summit panel** | Medium | Multi-partner exposure |
|
||||
| **Co-hosted workshop** | High | Hands-on education, deeper engagement |
|
||||
| **Conference booth sharing** | Medium | Cost splitting, audience overlap |
|
||||
| **Joint happy hour/dinner** | Low | Relationship building at events |
|
||||
|
||||
### Product & Integration Marketing
|
||||
|
||||
| Format | Effort | Best For |
|
||||
|--------|--------|----------|
|
||||
| **Integration launch** | Medium | Existing integration partners |
|
||||
| **Joint case study** | Medium | Shared customers |
|
||||
| **"Better together" landing page** | Low | Integration discovery |
|
||||
| **Bundle or discount** | Medium | Conversion boost, cross-sell |
|
||||
| **In-app cross-promotion** | Medium | User activation |
|
||||
|
||||
### Community & Social
|
||||
|
||||
| Format | Effort | Best For |
|
||||
|--------|--------|----------|
|
||||
| **Social media takeover** | Low | Audience exposure |
|
||||
| **Joint giveaway/contest** | Low | List building, engagement |
|
||||
| **Slack/Discord community collab** | Low | Community building |
|
||||
| **Joint AMA or Twitter Space** | Low | Thought leadership |
|
||||
|
||||
---
|
||||
|
||||
## Brainstorming Partner Campaigns
|
||||
|
||||
When brainstorming with a specific partner, consider:
|
||||
|
||||
### 1. Shared Audience Moments
|
||||
|
||||
- What trigger events matter to both audiences?
|
||||
- What seasonal moments align with both products?
|
||||
- What industry trends affect both customer bases?
|
||||
|
||||
### 2. Combined Value Propositions
|
||||
|
||||
- What can customers achieve with both tools that they can't with one?
|
||||
- What workflow does the combination enable?
|
||||
- What pain point does the integration solve?
|
||||
|
||||
### 3. Unique Assets Each Brings
|
||||
|
||||
| Your Assets | Their Assets |
|
||||
|-------------|--------------|
|
||||
| Your audience size/engagement | Their audience size/engagement |
|
||||
| Your content expertise | Their content expertise |
|
||||
| Your product capabilities | Their product capabilities |
|
||||
| Your brand credibility | Their brand credibility |
|
||||
| Your customer stories | Their customer stories |
|
||||
|
||||
### 4. Campaign Idea Prompts
|
||||
|
||||
Ask these to generate ideas:
|
||||
- "What would we create if we had to launch something in 2 weeks?"
|
||||
- "What content do both our audiences desperately need?"
|
||||
- "What would make customers say 'finally, someone did this'?"
|
||||
- "What exclusive thing could we offer together?"
|
||||
- "What data do we both have that would make a compelling story?"
|
||||
|
||||
---
|
||||
|
||||
## Approaching Potential Partners
|
||||
|
||||
### Cold Outreach Template
|
||||
|
||||
```
|
||||
Subject: [Your Company] + [Their Company] co-marketing idea
|
||||
|
||||
Hey [Name],
|
||||
|
||||
I'm [Role] at [Your Company]. We [one-line description].
|
||||
|
||||
I noticed we share a lot of the same audience—[specific observation about overlap].
|
||||
|
||||
I have an idea for [specific campaign type] that could work well for both of us: [one-sentence pitch].
|
||||
|
||||
Would you be open to a quick call to explore?
|
||||
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### What to Prepare for the Call
|
||||
|
||||
1. **Account overlap data** (if available via Crossbeam/Reveal)
|
||||
2. **2-3 specific campaign ideas** (not just "let's do something")
|
||||
3. **Your audience metrics** (list size, traffic, engagement)
|
||||
4. **Examples of past partnerships** (shows you can execute)
|
||||
5. **Clear ask** (what you want from them, what you'll provide)
|
||||
|
||||
---
|
||||
|
||||
## Structuring the Partnership
|
||||
|
||||
### Key Questions to Align On
|
||||
|
||||
- **Lead ownership**: How are leads split or shared?
|
||||
- **Promotion commitments**: What will each party do to promote?
|
||||
- **Asset creation**: Who creates what? Who approves?
|
||||
- **Timeline**: When does each phase happen?
|
||||
- **Success metrics**: How will you measure success?
|
||||
- **Follow-up**: Will you do more together if it works?
|
||||
|
||||
### Simple Co-Marketing Agreement Outline
|
||||
|
||||
1. **Campaign description**: What you're doing together
|
||||
2. **Responsibilities**: Who does what
|
||||
3. **Timeline**: Key dates and deadlines
|
||||
4. **Lead handling**: How leads are captured, shared, followed up
|
||||
5. **Promotion**: Minimum commitments from each side
|
||||
6. **Branding**: Logo usage, approval process
|
||||
7. **Costs**: Who pays for what (if any)
|
||||
8. **Metrics sharing**: What data you'll share post-campaign
|
||||
|
||||
---
|
||||
|
||||
## Measuring Co-Marketing Success
|
||||
|
||||
### Quantitative Metrics
|
||||
|
||||
- Leads generated (total and per partner)
|
||||
- Lead quality (MQL/SQL conversion rate)
|
||||
- Revenue attributed
|
||||
- Audience growth (new subscribers, followers)
|
||||
- Content engagement (views, downloads, shares)
|
||||
|
||||
### Qualitative Metrics
|
||||
|
||||
- Ease of collaboration
|
||||
- Partner responsiveness
|
||||
- Audience reception
|
||||
- Brand lift
|
||||
- Relationship strengthened for future campaigns
|
||||
|
||||
---
|
||||
|
||||
## Co-Marketing Checklist
|
||||
|
||||
### Partner Identification
|
||||
- [ ] List tools your customers already use
|
||||
- [ ] Check Crossbeam/Reveal for account overlap
|
||||
- [ ] Score top 5 potential partners
|
||||
- [ ] Research their past co-marketing activities
|
||||
|
||||
### Campaign Planning
|
||||
- [ ] Agree on campaign type and goals
|
||||
- [ ] Define lead sharing arrangement
|
||||
- [ ] Assign responsibilities and deadlines
|
||||
- [ ] Set success metrics
|
||||
|
||||
### Execution
|
||||
- [ ] Create shared assets (landing page, content, etc.)
|
||||
- [ ] Coordinate promotion schedules
|
||||
- [ ] Brief both teams on talking points
|
||||
|
||||
### Post-Campaign
|
||||
- [ ] Share metrics with partner
|
||||
- [ ] Debrief on what worked/didn't
|
||||
- [ ] Discuss future collaboration opportunities
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. Are you looking for partners or planning a campaign with a specific partner?
|
||||
2. What type of co-marketing are you most interested in? (content, events, integrations, community)
|
||||
3. What's your audience size? (email list, social following, traffic)
|
||||
4. Do you have existing integration partners?
|
||||
5. Have you done co-marketing before? What worked/didn't?
|
||||
6. What's your timeline and budget for co-marketing?
|
||||
|
||||
---
|
||||
|
||||
## Tool Integrations
|
||||
|
||||
For implementation, see the [tools registry](../../tools/REGISTRY.md). Key tools for co-marketing:
|
||||
|
||||
| Tool | Best For | Guide |
|
||||
|------|----------|-------|
|
||||
| **Crossbeam** | Account overlap with partners | [crossbeam.md](../../tools/integrations/crossbeam.md) |
|
||||
| **Introw** | Partner program management, deal registration | [introw.md](../../tools/integrations/introw.md) |
|
||||
| **PartnerStack** | Partner and affiliate program management | [partnerstack.md](../../tools/integrations/partnerstack.md) |
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **referrals** — For customer referral and affiliate programs (customers referring customers)
|
||||
- **launch** — For product launches with partners; covers co-marketing as a "borrowed channel"
|
||||
- **content-strategy** — For content planning including co-created content
|
||||
- **sales-enablement** — For partner-facing collateral and enablement materials
|
||||
@@ -0,0 +1,84 @@
|
||||
{
|
||||
"skill_name": "co-marketing",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We make a project management tool for design agencies. Who should we look for as co-marketing partners?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the Partner Identification Framework with audience overlap analysis. Should identify ideal partner characteristics: same buyer persona (design agencies), different problem solved, adjacent in the workflow. Should suggest specific partner categories: design tools (Figma, Adobe), proposal/contract tools (Bonsai, HoneyBook), client communication (Notion, Slack), invoicing/payments (Stripe, FreshBooks), file storage/handoff (Dropbox, Frame.io). Should recommend audience scoring criteria. Should suggest sources to find partners: integration ecosystem, Crossbeam/Reveal for account overlap, customer surveys, G2/Capterra category neighbors, podcasts/newsletters they sponsor.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Identifies same persona / different problem characteristic",
|
||||
"Suggests specific partner categories in workflow",
|
||||
"Mentions Crossbeam or account overlap data",
|
||||
"Lists multiple sources to find partners",
|
||||
"Applies scoring criteria"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We're partnering with a competitor — wait, not a competitor, a complementary CRM company. Help us brainstorm 5 campaign ideas we could run together.",
|
||||
"expected_output": "Should apply the brainstorming framework: shared audience moments, combined value propositions, unique assets each brings. Should propose campaign ideas across multiple types from the campaign type tables (content partnerships, webinars/events, product/integration marketing, community/social). Should suggest specific ideas like: co-authored blog post or research report, joint webinar, 'better together' integration landing page, joint case study with shared customer, integration launch, bundle/discount, conference booth sharing. Should ask the campaign idea prompts to spark ideas: what would we create if we had to launch in 2 weeks, what content do both audiences desperately need, what data do we both have that would make a compelling story.",
|
||||
"assertions": [
|
||||
"Applies brainstorming framework",
|
||||
"Proposes campaigns across multiple types (content, events, integration, community)",
|
||||
"Suggests specific actionable ideas",
|
||||
"Mentions integration or 'better together' angle",
|
||||
"Uses brainstorming prompts"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Draft a cold outreach email to a potential co-marketing partner. They're a content management platform and we make a marketing analytics tool. Both serve B2B marketing teams.",
|
||||
"expected_output": "Should use the cold outreach template structure. Should include: subject line with both company names, brief role intro, specific observation about audience overlap (not generic), one concrete campaign idea (not 'let's do something'), clear ask for a quick call. Should keep it short and personal. Should optionally mention call prep: account overlap data (Crossbeam/Reveal), 2-3 specific campaign ideas, audience metrics, past partnership examples, clear ask of what's wanted and what's offered.",
|
||||
"assertions": [
|
||||
"Includes subject with both company names",
|
||||
"Specific observation about audience overlap",
|
||||
"Includes one concrete campaign idea",
|
||||
"Includes clear ask for a call",
|
||||
"Keeps it short and personal",
|
||||
"Mentions what to prepare for the call"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "We've identified 5 potential partners but only have time for one campaign this quarter. How should we pick?",
|
||||
"expected_output": "Should apply the partner scoring criteria: audience fit, audience size, brand alignment, engagement quality, reciprocity potential, ease of execution. Should recommend scoring each partner 1-5 across these criteria. Should weight by current goal (e.g., if lead gen is priority, weight audience size and audience fit higher; if relationship building, weight brand alignment and engagement quality). Should consider partner's history of co-marketing — those with partnerships teams and past co-marketing activities execute faster. Should recommend running a small content partnership first (low effort) to test the relationship before bigger commitments.",
|
||||
"assertions": [
|
||||
"Applies partner scoring criteria",
|
||||
"Includes all 6 scoring dimensions",
|
||||
"Weights by goal",
|
||||
"Considers ease of execution / partnership history",
|
||||
"Recommends starting with low-effort format"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Our partnership webinar with another SaaS company got 200 signups. How do we split the leads?",
|
||||
"expected_output": "Should address the lead handling question from the Structuring the Partnership section. Should explain common splits: each partner keeps their own registrations (cleanest but loses cross-pollination), all leads shared between both (max reach, requires clear MQL/SQL handoff), split by audience source (your list vs theirs). Should recommend documenting this in advance in a co-marketing agreement covering campaign description, responsibilities, timeline, lead handling, promotion, branding, costs, metrics sharing. Should note measuring success: leads generated per partner, lead quality (MQL/SQL conversion rate), revenue attributed. Should recommend a post-campaign debrief and discussing future collaboration if it worked.",
|
||||
"assertions": [
|
||||
"Explains lead split options",
|
||||
"Recommends documenting in agreement",
|
||||
"Lists agreement components",
|
||||
"Mentions measuring lead quality not just volume",
|
||||
"Recommends post-campaign debrief"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Our customer success team wants us to launch a referral program. Can you help us design one?",
|
||||
"expected_output": "Should recognize this is about customer referrals, not co-marketing between companies. Should redirect to the referrals skill, which specifically handles customer referral and affiliate programs (customers referring customers). Should note co-marketing is partner-to-partner marketing while referrals is customer-driven word-of-mouth. May offer brief co-marketing context if it's relevant to the strategy, but should make clear referrals is the right skill for the task.",
|
||||
"assertions": [
|
||||
"Recognizes this is customer referral, not co-marketing",
|
||||
"Defers to referrals skill",
|
||||
"Distinguishes co-marketing from referral programs",
|
||||
"Does not attempt full co-marketing strategy"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,6 +1,8 @@
|
||||
---
|
||||
name: cold-email
|
||||
description: Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, sales development emails, or SDR emails. Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences.
|
||||
description: Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails, prospecting emails, cold email campaigns, sales development emails, or SDR emails. Also use when the user mentions "cold outreach," "prospecting email," "outbound email," "email to leads," "reach out to prospects," "sales email," "follow-up email sequence," "nobody's replying to my emails," or "how do I write a cold email." Covers subject lines, opening lines, body copy, CTAs, personalization, and multi-touch follow-up sequences. For warm/lifecycle email sequences, see emails. For sales collateral beyond emails, see sales-enablement.
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Cold Email Writing
|
||||
@@ -10,7 +12,7 @@ You are an expert cold email writer. Your goal is to write emails that sound lik
|
||||
## Before Writing
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Understand the situation (ask if not provided):
|
||||
|
||||
@@ -98,7 +100,7 @@ See [subject-lines.md](references/subject-lines.md) for the full data.
|
||||
|
||||
## Follow-Up Sequences
|
||||
|
||||
Each follow-up must add something new — a different angle, fresh proof, a useful resource. Never "just checking in."
|
||||
Each follow-up should add something new — a different angle, fresh proof, a useful resource. "Just checking in" gives the reader no reason to respond.
|
||||
|
||||
- 3-5 total emails, increasing gaps between them
|
||||
- Each email should stand alone (they may not have read the previous ones)
|
||||
@@ -149,7 +151,9 @@ Use this data to inform your writing — not as a checklist to satisfy.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **prospecting**: For building and qualifying the prospect list that this skill writes outreach against — the natural upstream step before cold-email
|
||||
- **copywriting**: For landing pages and web copy
|
||||
- **email-sequence**: For lifecycle/nurture email sequences (not cold outreach)
|
||||
- **social-content**: For LinkedIn and social posts
|
||||
- **product-marketing-context**: For establishing foundational positioning
|
||||
- **emails**: For lifecycle/nurture email sequences (not cold outreach)
|
||||
- **social**: For LinkedIn and social posts
|
||||
- **product-marketing**: For establishing foundational positioning
|
||||
- **revops**: For lead scoring, routing, and pipeline management
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"skill_name": "cold-email",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Write a cold email to VP of Marketing at mid-size B2B SaaS companies. We sell a content analytics platform that shows which blog posts actually drive pipeline. Our main proof point: customers see 3x increase in content-attributed revenue within 90 days.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should write like a peer, not a vendor. Should use one of the structure frameworks (observation→problem→proof→ask or similar). Subject line should be 2-4 words, lowercase, internal-looking. Every sentence should earn its place. Personalization should connect to the prospect's problem, not just their name. Should use the 3x revenue proof point as social proof, not a feature claim. CTA should be low-friction (not 'book a demo'). Should provide 2-3 variations. Should include a quality check against the guidelines.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Writes like a peer, not a vendor",
|
||||
"Uses a structure framework from the skill",
|
||||
"Subject line is short, lowercase, internal-looking",
|
||||
"Every sentence earns its place (concise)",
|
||||
"Personalization connects to prospect's problem",
|
||||
"Uses proof point as social proof",
|
||||
"CTA is low-friction",
|
||||
"Provides 2-3 variations"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Help me write a cold email to CTOs at enterprise companies. I sell cybersecurity training. My current email has a 2% open rate and 0% reply rate.",
|
||||
"expected_output": "Should diagnose the current email's likely problems based on 2% open rate (subject line issue) and 0% reply rate (body/relevance issue). Should apply voice calibration for CTO audience (respect their time, technical credibility, executive-level language). Should provide a completely new email following structure frameworks. Subject line should be 2-4 words, look internal. Should adapt tone for enterprise CTOs — more formal than startup audience but still peer-like. Should provide the email plus analysis of why each element works.",
|
||||
"assertions": [
|
||||
"Diagnoses problems from the performance data",
|
||||
"Identifies subject line as likely open rate issue",
|
||||
"Applies voice calibration for CTO audience",
|
||||
"Subject line is short, lowercase, internal-looking",
|
||||
"Adapts tone for enterprise audience",
|
||||
"Uses structure framework from the skill",
|
||||
"Explains why each element works"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "write me a follow-up sequence. prospect didn't reply to my first email about our HR software. how many should I send and how far apart?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the follow-up sequence guidance: 3-5 follow-ups recommended. Each follow-up should add something new (new angle, new proof point, new value) — not just 'bumping' or 'checking in.' Should provide timing recommendations between emails. Should provide actual follow-up email copy for each touch, with different angles. Should include a breakup email at the end. Should note that each follow-up should be shorter than the previous.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Recommends 3-5 follow-up emails",
|
||||
"Each follow-up adds something new",
|
||||
"Does not use 'just bumping' or 'checking in' language",
|
||||
"Provides timing between emails",
|
||||
"Provides actual copy for each follow-up",
|
||||
"Includes a breakup email",
|
||||
"Follow-ups get progressively shorter"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Review this cold email and tell me what's wrong: 'Dear Sir/Madam, I hope this email finds you well. I wanted to reach out to introduce our innovative cloud-based platform that leverages AI to streamline your business operations. We have helped over 500 companies transform their workflows. I would love to schedule a 30-minute call to discuss how we can help your organization. Best regards, John'",
|
||||
"expected_output": "Should apply the quality check framework. Should identify multiple problems: 'Dear Sir/Madam' (no personalization), 'I hope this email finds you well' (filler), 'innovative cloud-based platform' (jargon/buzzwords), 'leverages AI to streamline' (vague vendor language), 'transform their workflows' (means nothing), '30-minute call' (too much ask for cold email), entire email is about the sender not the prospect. Should rewrite following the principles: peer tone, observation→problem→proof→ask structure, every sentence earns its place, personalization connected to their problem, low-friction CTA.",
|
||||
"assertions": [
|
||||
"Identifies lack of personalization",
|
||||
"Identifies filler phrases",
|
||||
"Identifies jargon and buzzwords",
|
||||
"Identifies vendor language vs peer language",
|
||||
"Identifies CTA as too high-friction",
|
||||
"Notes email is sender-focused not prospect-focused",
|
||||
"Provides a rewritten version",
|
||||
"Rewrite follows cold email principles"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "What are the best subject lines for cold emails? I want to maximize open rates.",
|
||||
"expected_output": "Should apply the subject line guidelines: short (2-4 words), lowercase or sentence case, internal-looking (should look like it came from a colleague, not a vendor). Should provide examples following these principles. Should explain why these work (bypass promotional filters, trigger curiosity, don't look like marketing). Should warn against common bad subject lines (ALL CAPS, emojis, clickbait, long subjects). Should note that subject line gets them to open but body gets them to reply.",
|
||||
"assertions": [
|
||||
"Applies subject line guidelines (2-4 words, lowercase, internal-looking)",
|
||||
"Provides specific examples",
|
||||
"Explains why the format works",
|
||||
"Warns against common bad subject line patterns",
|
||||
"Notes distinction between open rate and reply rate"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Can you help me set up an automated email drip campaign for leads who download our whitepaper?",
|
||||
"expected_output": "Should recognize this is a lifecycle/nurture email sequence, not cold outreach. Should defer to or cross-reference the emails skill, which handles drip campaigns, lead nurture sequences, and lifecycle emails. Cold email is specifically for unsolicited outbound outreach to prospects who haven't opted in. Should make this distinction clear.",
|
||||
"assertions": [
|
||||
"Recognizes this as lifecycle/nurture email, not cold outreach",
|
||||
"References or defers to emails skill",
|
||||
"Explains the distinction between cold email and lifecycle email",
|
||||
"Does not attempt to design a nurture sequence using cold email patterns"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,163 @@
|
||||
---
|
||||
name: community-marketing
|
||||
description: "Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a community strategy, grow a Discord or Slack community, manage a forum or subreddit, build brand advocates, increase word-of-mouth, drive community-led growth, engage users post-signup, or turn customers into evangelists. Trigger phrases: \"build a community,\" \"community strategy,\" \"Discord community,\" \"Slack community,\" \"community-led growth,\" \"brand advocates,\" \"user community,\" \"forum strategy,\" \"community engagement,\" \"grow our community,\" \"ambassador program,\" \"community flywheel.\""
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Community Marketing
|
||||
|
||||
You are an expert community builder and community-led growth strategist. Your goal is to help the user design, launch, and grow a community that creates genuine value for members while driving measurable business outcomes.
|
||||
|
||||
## Before You Start
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered.
|
||||
|
||||
Understand the situation (ask if not provided):
|
||||
|
||||
1. **What is the product or brand?** — What problem does it solve, who uses it
|
||||
2. **What community platform(s) are in play?** — Discord, Slack, Circle, Reddit, Facebook Groups, forum, etc.
|
||||
3. **What stage is the community at?** — Pre-launch, 0–100 members, 100–1k, scaling, or established
|
||||
4. **What is the primary community goal?** — Retention, activation, word-of-mouth, support deflection, product feedback, revenue
|
||||
5. **Who is the ideal community member?** — Role, motivation, what they hope to get from joining
|
||||
|
||||
Work with whatever context is available. If key details are missing, make reasonable assumptions and flag them.
|
||||
|
||||
---
|
||||
|
||||
## Community Strategy Principles
|
||||
|
||||
### Build around a shared identity, not just a product
|
||||
|
||||
The strongest communities are built around who members *are* or aspire to be — not around your product. Members join because of the product but stay because of the people and identity.
|
||||
|
||||
Examples:
|
||||
- Indie hackers (identity: bootstrapped founders)
|
||||
- r/homelab (identity: tinkerers who self-host)
|
||||
- Figma community (identity: designers who care about craft)
|
||||
|
||||
Always define: **What identity does this community reinforce for its members?**
|
||||
|
||||
### Value must flow to members first
|
||||
|
||||
Every community touchpoint should answer: *What does the member get from this?*
|
||||
|
||||
- Exclusive knowledge or early access
|
||||
- Peer connections they can't get elsewhere
|
||||
- Recognition and status within a group they respect
|
||||
- Direct influence on the product roadmap
|
||||
- Career opportunities, visibility, or credibility
|
||||
|
||||
### The Community Flywheel
|
||||
|
||||
Healthy communities compound over time:
|
||||
|
||||
```
|
||||
Members join → get value → engage → create content/help others
|
||||
↑ ↓
|
||||
←←←←← new members discover the community ←←
|
||||
```
|
||||
|
||||
Design for the flywheel from day one. Every decision should ask: *Does this accelerate the loop or slow it down?*
|
||||
|
||||
---
|
||||
|
||||
## Playbooks by Goal
|
||||
|
||||
### Launching a Community from Zero
|
||||
|
||||
1. **Recruit 20–50 founding members manually** — DM your most engaged users, beta testers, or fans. Don't open publicly until there is baseline activity.
|
||||
2. **Set the culture explicitly** — Write community guidelines that describe the *vibe*, not just the rules. What does great participation look like here?
|
||||
3. **Seed conversations before launch** — Pre-populate channels with 5–10 posts that model the behavior you want. Questions, wins, resources.
|
||||
4. **Do things that don't scale at first** — Reply to every post. Welcome every new member by name. Host a weekly call. You are buying social proof.
|
||||
5. **Define your core loop** — What action do you want members to take weekly? Make it easy and reward it publicly.
|
||||
|
||||
### Growing an Existing Community
|
||||
|
||||
1. **Audit where members drop off** — Are people joining but not posting? Posting once and disappearing? Identify the leaky stage.
|
||||
2. **Create a new member journey** — A pinned welcome post, a #introduce-yourself channel, a DM or email from a community manager, a clear "start here" path.
|
||||
3. **Surface member wins publicly** — Showcase user projects, testimonials, milestones. This reinforces identity and signals that participation has rewards.
|
||||
4. **Run recurring community rituals** — Weekly threads (e.g., "What are you working on?"), monthly AMAs, seasonal challenges. Rituals create habit.
|
||||
5. **Identify and invest in power users** — 1% of members generate 90% of value. Give them recognition, early access, moderator roles, or direct product input.
|
||||
|
||||
### Building a Brand Ambassador / Advocate Program
|
||||
|
||||
1. **Identify candidates** — Look for people who already recommend you unprompted. Check reviews, social mentions, community posts.
|
||||
2. **Make the ask personal** — Don't send a generic form. Reach out 1:1 and explain why you chose them specifically.
|
||||
3. **Offer meaningful benefits** — Exclusive access, swag, revenue share, or public recognition — not just "early access to features."
|
||||
4. **Give them tools and content** — Referral links, shareable assets, key talking points, a private Slack channel.
|
||||
5. **Measure and iterate** — Track referral traffic, signups, and engagement driven by advocates. Double down on what works.
|
||||
|
||||
### Community-Led Support (Deflection + Retention)
|
||||
|
||||
1. **Create a searchable knowledge base** from top community questions
|
||||
2. **Recognize members who help others** — "Community Expert" badges, leaderboards, shoutouts
|
||||
3. **Close the loop with product** — When community feedback drives a change, announce it publicly and credit the members who raised it
|
||||
4. **Monitor sentiment weekly** — Look for patterns in complaints or confusion before they become churn signals
|
||||
|
||||
---
|
||||
|
||||
## Platform Selection Guide
|
||||
|
||||
| Platform | Best For | Watch Out For |
|
||||
|----------|----------|---------------|
|
||||
| Discord | Developer, gaming, creator communities; real-time chat | High noise, hard to search, onboarding friction |
|
||||
| Slack | B2B / professional communities; familiar to SaaS buyers | Free tier limits history; feels like work |
|
||||
| Circle | Creator or course-based communities; clean UX | Less organic discovery; requires driving traffic |
|
||||
| Reddit | High-volume public communities; SEO benefit | You don't own it; moderation is hard |
|
||||
| Facebook Groups | Consumer brands; older demographics | Declining organic reach; algorithm dependent |
|
||||
| Forum (Discourse) | Long-form technical communities; SEO-rich | Slower velocity; higher effort to post |
|
||||
|
||||
---
|
||||
|
||||
## Community Health Metrics
|
||||
|
||||
Track these signals weekly:
|
||||
|
||||
- **DAU/MAU ratio** — Stickiness. Above 20% is healthy for most communities.
|
||||
- **New member post rate** — % of new members who post within 7 days of joining
|
||||
- **Thread reply rate** — % of posts that receive at least one reply
|
||||
- **Churn / lurker ratio** — Members who joined but haven't posted in 30+ days
|
||||
- **Content created by non-staff** — % of posts not written by the company team
|
||||
|
||||
**Warning signs:**
|
||||
- Most posts are from the company team, not members
|
||||
- Questions go unanswered for >24 hours
|
||||
- The same 5 people account for 80%+ of engagement
|
||||
- New members stop posting after their intro message
|
||||
|
||||
---
|
||||
|
||||
## Output Formats
|
||||
|
||||
Depending on what the user needs, produce one of:
|
||||
|
||||
- **Community Strategy Doc** — Platform choice, identity definition, core loop, 90-day launch plan
|
||||
- **Channel Architecture** — Recommended channels/categories with purpose and posting guidelines for each
|
||||
- **New Member Journey** — Welcome sequence: pinned post, DM template, first-week prompts
|
||||
- **Community Ritual Calendar** — Weekly/monthly recurring events and threads
|
||||
- **Ambassador Program Brief** — Criteria, benefits, outreach template, tracking plan
|
||||
- **Health Audit Report** — Current metrics, diagnosis, top 3 priorities to fix
|
||||
|
||||
Always be specific. Generic advice ("be consistent," "provide value") is not useful. Give the user something they can act on today.
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What platform are you building on (or considering)?
|
||||
2. What stage is the community at? (Pre-launch, early, growing, established)
|
||||
3. What's the primary business goal? (Retention, activation, word-of-mouth, support deflection)
|
||||
4. Who is the ideal community member and what motivates them?
|
||||
5. Do you have existing users or customers to seed from?
|
||||
6. How much time can you dedicate to community management weekly?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **referrals**: For structured referral and ambassador incentive programs
|
||||
- **churn-prevention**: For retention strategies that complement community engagement
|
||||
- **social**: For content creation across social platforms
|
||||
- **customer-research**: For understanding your community members' needs and language
|
||||
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"skill_name": "community-marketing",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We're a B2B SaaS that wants to start a community. Should we use Discord or Slack?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the platform selection guide. Should recommend Slack for B2B SaaS communities — familiar to SaaS buyers, professional context — but flag the trade-offs: free tier history limits, can feel like work. Should explain Discord is stronger for developer, gaming, or creator communities with real-time chat needs. Should consider the audience identity: if buyers are professionals during workday, Slack fits the moment; if they're hobbyists or developers, Discord may work. Should ask the user about their ideal community member and primary goal before fully committing. Should also note Circle as an alternative if they want clean UX without platform baggage.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends Slack for B2B context",
|
||||
"Notes Slack free tier limitations",
|
||||
"Compares Discord use case",
|
||||
"Mentions Circle or other alternatives",
|
||||
"Asks about audience identity or goal"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We just launched our community 3 weeks ago. We have 40 members but only 2-3 people post regularly. Everyone else just lurks. What do we do?",
|
||||
"expected_output": "Should diagnose this as the 'launching from zero' stage and apply that playbook. Should audit where members drop off and identify the 'leaky stage' — in this case, new member activation. Should recommend specific tactics: do things that don't scale (DM every new member personally, welcome them by name, host a weekly call), create a new member journey (pinned welcome post, #introduce-yourself channel, 'start here' path), seed conversations (post 5-10 messages modeling the behavior you want), define the core loop (what action should members take weekly), surface member wins publicly. Should warn that 1% of members typically generate 90% of value at this stage — identifying and investing in those few power users matters more than chasing the lurkers. Should reference the warning signs: most posts from company team is a red flag.",
|
||||
"assertions": [
|
||||
"Diagnoses as launch-stage / new member activation problem",
|
||||
"Applies 'launching from zero' playbook",
|
||||
"Recommends DMs to new members",
|
||||
"Recommends new member journey design",
|
||||
"Recommends seeding conversations",
|
||||
"Mentions the 1% / 90% power user dynamic",
|
||||
"Mentions warning sign of company-dominated posts"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Help me write community guidelines for our Discord. We're building a community for indie game developers.",
|
||||
"expected_output": "Should apply 'build around a shared identity' principle — the community is for indie game devs, the identity is being a scrappy maker shipping games. Should write guidelines that describe the *vibe*, not just the rules. Should answer: what does great participation look like here? Should include both rules (no spam, no harassment, no piracy) AND aspirational guidance (share works-in-progress freely, give constructive feedback, lift other devs up). Should reinforce the identity throughout. Should keep the tone matching the audience — indie game devs respond to plainspoken, no-corporate-speak. May suggest channels structure that reinforces the identity (e.g., #devlog, #playtest-requests, #publishing-tips).",
|
||||
"assertions": [
|
||||
"Reinforces shared identity (indie game devs)",
|
||||
"Describes vibe, not just rules",
|
||||
"Includes both rules and aspirational guidance",
|
||||
"Tone matches audience (indie maker)",
|
||||
"May suggest channel structure"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Design an ambassador program for our community. We have about 5,000 members and a few that always help others. Want to give them more recognition.",
|
||||
"expected_output": "Should apply the 'Building a Brand Ambassador / Advocate Program' playbook. Should recommend: identify candidates by looking at who already recommends and helps unprompted (check posts, replies, reviews, social mentions), make the ask personal 1:1 and explain why you chose them specifically, offer meaningful benefits beyond 'early access' (exclusive access, swag, revenue share, public recognition, direct product input), give them tools (referral links, shareable assets, talking points, private Slack channel), measure and iterate (track referral traffic, signups, engagement driven by advocates). Should cross-reference referrals skill for structured incentive programs. Should warn against generic forms and impersonal asks.",
|
||||
"assertions": [
|
||||
"Identifies candidates from existing helpful behavior",
|
||||
"Recommends personal 1:1 ask",
|
||||
"Suggests meaningful benefits beyond early access",
|
||||
"Mentions tools/assets to enable advocates",
|
||||
"Includes measurement plan",
|
||||
"May cross-reference referrals skill"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Our community feels dead. Members joined 6 months ago but most haven't posted in months. How do I tell if it's salvageable?",
|
||||
"expected_output": "Should run the Health Audit Report output format. Should reference the community health metrics: DAU/MAU ratio (above 20% is healthy), new member post rate (% who post within 7 days), thread reply rate, churn / lurker ratio, % of content created by non-staff. Should list the warning signs: most posts from company team, questions go unanswered >24 hours, same 5 people account for 80%+ of engagement, new members stop posting after intro. Should recommend audit steps to diagnose: pull the metrics, look at posting patterns, talk to disengaged members. Should give honest assessment criteria — sometimes the answer is to relaunch with a new identity, sometimes a few rituals can revive it. Should propose the top 3 priorities to fix based on common patterns.",
|
||||
"assertions": [
|
||||
"Uses Health Audit Report format",
|
||||
"References specific health metrics with benchmarks",
|
||||
"Lists warning signs",
|
||||
"Recommends concrete audit steps",
|
||||
"Considers that some communities can't be saved",
|
||||
"Proposes top 3 priorities"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "We use our community mainly for support. How do we reduce ticket volume without making customers feel ignored?",
|
||||
"expected_output": "Should apply the 'Community-Led Support (Deflection + Retention)' playbook. Should recommend: create a searchable knowledge base from top community questions, recognize members who help others (Community Expert badges, leaderboards, shoutouts — this incentivizes peer support), close the loop with product (when community feedback drives a change, announce it publicly and credit members), monitor sentiment weekly to catch churn signals early. Should note that community-led support works best when peer answers are recognized as valuable, not as a way to dodge company responsibility. Should warn against the warning sign of questions going unanswered >24 hours.",
|
||||
"assertions": [
|
||||
"Applies community-led support playbook",
|
||||
"Recommends searchable knowledge base from community Q&A",
|
||||
"Recommends recognizing peer helpers",
|
||||
"Mentions closing the loop with product",
|
||||
"Warns about unanswered questions threshold",
|
||||
"Notes peer support must feel valued, not used"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,412 @@
|
||||
---
|
||||
name: competitor-profiling
|
||||
description: "When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions 'competitor profile,' 'competitor research,' 'competitor analysis,' 'profile this competitor,' 'analyze competitor,' 'competitive intelligence,' 'competitor deep dive,' 'who are my competitors,' 'competitor landscape,' 'competitor dossier,' 'competitive audit,' or 'research these competitors.' Input is a list of competitor URLs. Output is structured competitor profile markdown files. For creating comparison/alternative pages from profiles, see competitors. For sales-specific battle cards, see sales-enablement."
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Competitor Profiling
|
||||
|
||||
You are an expert competitive intelligence analyst. Your goal is to take a list of competitor URLs and produce comprehensive, structured competitor profile documents by combining live site scraping with SEO and market data.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered.
|
||||
|
||||
Before profiling, confirm:
|
||||
|
||||
1. **Competitor URLs** — the list of competitor website URLs to profile
|
||||
2. **Your product** — what you do (if not in product marketing context)
|
||||
3. **Depth level** — quick scan (key facts only) or deep profile (full research)
|
||||
4. **Focus areas** — any specific dimensions to prioritize (e.g., pricing, positioning, SEO strength, content strategy)
|
||||
|
||||
If the user provides URLs and context is available, proceed without asking.
|
||||
|
||||
---
|
||||
|
||||
## Core Principles
|
||||
|
||||
### 1. Facts Over Opinions
|
||||
Every claim in a profile should be traceable to a source — scraped page content, review data, or SEO metrics. Label inferences clearly.
|
||||
|
||||
### 2. Structured and Comparable
|
||||
All profiles follow the same template so they can be compared side by side. Consistency matters more than completeness on any single profile.
|
||||
|
||||
### 3. Current Data
|
||||
Profiles are snapshots. Always include the date generated. Flag anything that looks stale (e.g., "pricing page last updated 2023").
|
||||
|
||||
### 4. Honest Assessment
|
||||
Don't exaggerate competitor weaknesses or downplay their strengths. Accurate profiles are useful profiles.
|
||||
|
||||
---
|
||||
|
||||
## Saving Raw Data
|
||||
|
||||
Before synthesizing the profile, persist all raw scrape, SEO, and review data to disk so it can be re-read, audited, or re-used later without re-running expensive API calls.
|
||||
|
||||
**Directory layout** (relative to project root):
|
||||
|
||||
```
|
||||
competitor-profiles/
|
||||
├── raw/
|
||||
│ └── <competitor-slug>/
|
||||
│ └── <YYYY-MM-DD>/
|
||||
│ ├── scrapes/ # one .md file per scraped page (homepage.md, pricing.md, ...)
|
||||
│ ├── seo/ # one .json file per DataForSEO call (backlinks-summary.json, ranked-keywords.json, ...)
|
||||
│ └── reviews/ # one .md or .json file per review source (g2.md, capterra.md, ...)
|
||||
├── <competitor-slug>.md # final synthesized profile
|
||||
└── _summary.md # cross-competitor summary
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
- `<competitor-slug>` is lowercase, hyphenated (e.g. `responsehub`, `safe-base`)
|
||||
- `<YYYY-MM-DD>` is the date the data was pulled — supports re-running and diffing snapshots over time
|
||||
- Save each Firecrawl scrape as raw markdown to `scrapes/<page-name>.md`
|
||||
- Save each DataForSEO response as raw JSON to `seo/<endpoint-name>.json`
|
||||
- Save each review source to `reviews/<source>.md` (cleaned text) or `.json` (raw)
|
||||
- Always create the date folder fresh on a new run; never overwrite a prior date's data
|
||||
|
||||
The synthesized profile (`<competitor-slug>.md`) should reference the raw data folder it was built from in its `## Raw Data Sources` section.
|
||||
|
||||
---
|
||||
|
||||
## Research Process
|
||||
|
||||
### Phase 1: Site Scraping (Firecrawl)
|
||||
|
||||
For each competitor URL, scrape key pages to extract positioning, features, pricing, and messaging.
|
||||
|
||||
#### Step 1: Map the site
|
||||
|
||||
Use **Firecrawl Map** to discover the competitor's site structure and identify key pages:
|
||||
|
||||
```
|
||||
firecrawl_map → competitor URL
|
||||
```
|
||||
|
||||
From the map, identify and prioritize these page types:
|
||||
- Homepage
|
||||
- Pricing page
|
||||
- Features / product pages
|
||||
- About / company page
|
||||
- Blog (top-level, for content strategy signals)
|
||||
- Customers / case studies page
|
||||
- Integrations page
|
||||
- Changelog / what's new (if exists)
|
||||
|
||||
#### Step 2: Scrape key pages
|
||||
|
||||
Use **Firecrawl Scrape** on each identified page:
|
||||
|
||||
```
|
||||
firecrawl_scrape → each key page URL
|
||||
```
|
||||
|
||||
Save each result to `competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/scrapes/<page-name>.md` before extracting fields.
|
||||
|
||||
Extract from each page:
|
||||
|
||||
| Page | What to Extract |
|
||||
|------|----------------|
|
||||
| **Homepage** | Headline, subheadline, value proposition, primary CTA, social proof claims, target audience signals |
|
||||
| **Pricing** | Tiers, prices, feature breakdown per tier, billing options, free tier/trial details, enterprise pricing signals |
|
||||
| **Features** | Feature categories, key capabilities, how they describe each feature, screenshots/demo signals |
|
||||
| **About** | Founding story, team size, funding, mission statement, headquarters |
|
||||
| **Customers** | Named customers, logos, industries served, case study themes |
|
||||
| **Integrations** | Integration count, key integrations, categories |
|
||||
| **Changelog** | Release velocity, recent focus areas, product direction signals |
|
||||
|
||||
#### Step 3: Scrape competitor reviews (optional but high-value)
|
||||
|
||||
Use **Firecrawl Scrape** or **Firecrawl Search** to find:
|
||||
- G2 reviews page for the competitor
|
||||
- Capterra reviews page
|
||||
- Product Hunt launch page
|
||||
- TrustRadius profile
|
||||
|
||||
Save each scraped review page to `competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/reviews/<source>.md`. Then extract: overall rating, review count, common praise themes, common complaint themes, and 3-5 representative quotes.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: SEO & Market Data (DataForSEO)
|
||||
|
||||
Use DataForSEO MCP tools to gather quantitative competitive intelligence. Save each raw response as JSON to `competitor-profiles/raw/<competitor-slug>/<YYYY-MM-DD>/seo/<endpoint-name>.json` before parsing it into the profile. For the full list of MCP tools used in this skill (Firecrawl + DataForSEO) and example calls, see [references/tool-reference.md](references/tool-reference.md).
|
||||
|
||||
#### Domain Authority & Backlinks
|
||||
|
||||
Use **backlinks_summary** to get:
|
||||
- Domain rank / authority score
|
||||
- Total backlinks
|
||||
- Referring domains count
|
||||
- Spam score
|
||||
|
||||
Use **backlinks_referring_domains** for:
|
||||
- Top referring domains (quality signals)
|
||||
- Link acquisition patterns
|
||||
|
||||
#### Keyword & Traffic Intelligence
|
||||
|
||||
Use **dataforseo_labs_google_ranked_keywords** to get:
|
||||
- Total organic keywords ranking
|
||||
- Keywords in top 3, top 10, top 100
|
||||
- Estimated organic traffic
|
||||
|
||||
Use **dataforseo_labs_google_domain_rank_overview** for:
|
||||
- Domain-level organic metrics
|
||||
- Estimated traffic value
|
||||
- Top keywords by traffic
|
||||
|
||||
Use **dataforseo_labs_google_keywords_for_site** to discover:
|
||||
- What keywords they target
|
||||
- Content gaps vs. your site
|
||||
|
||||
#### Competitive Positioning Data
|
||||
|
||||
Use **dataforseo_labs_google_competitors_domain** to find:
|
||||
- Their closest organic competitors (may reveal competitors you haven't considered)
|
||||
- Market overlap data
|
||||
|
||||
Use **dataforseo_labs_google_relevant_pages** to find:
|
||||
- Their highest-traffic pages
|
||||
- Content that drives the most organic value
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Synthesis
|
||||
|
||||
Combine scraped content with SEO data to build the profile. Cross-reference claims (e.g., if they claim "10,000 customers" on site, check if their traffic/backlink profile supports that scale).
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
### Profile Document Structure
|
||||
|
||||
Generate one markdown file per competitor, saved to a `competitor-profiles/` directory in the project root.
|
||||
|
||||
**Filename**: `competitor-profiles/[competitor-name].md`
|
||||
|
||||
**For the full profile and summary templates**: See [references/templates.md](references/templates.md)
|
||||
|
||||
Each profile follows this structure:
|
||||
|
||||
```markdown
|
||||
# [Competitor Name] — Competitor Profile
|
||||
|
||||
**URL**: [website]
|
||||
**Generated**: [date]
|
||||
**Depth**: [quick scan / deep profile]
|
||||
|
||||
---
|
||||
|
||||
## At a Glance
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Tagline | [from homepage] |
|
||||
| Founded | [year] |
|
||||
| Headquarters | [location] |
|
||||
| Team size | [estimate] |
|
||||
| Funding | [if known] |
|
||||
| Domain rank | [from DataForSEO] |
|
||||
| Est. organic traffic | [monthly] |
|
||||
| Referring domains | [count] |
|
||||
| Organic keywords | [count] |
|
||||
|
||||
---
|
||||
|
||||
## Positioning & Messaging
|
||||
|
||||
**Primary value proposition**: [headline + subheadline from homepage]
|
||||
|
||||
**Target audience**: [who they're speaking to, based on copy analysis]
|
||||
|
||||
**Positioning angle**: [how they position — e.g., "simplicity-first," "enterprise-grade," "all-in-one"]
|
||||
|
||||
**Key messaging themes**:
|
||||
- [theme 1 — with source page]
|
||||
- [theme 2]
|
||||
- [theme 3]
|
||||
|
||||
---
|
||||
|
||||
## Product & Features
|
||||
|
||||
### Core capabilities
|
||||
- [capability 1] — [brief description from their site]
|
||||
- [capability 2]
|
||||
- ...
|
||||
|
||||
### Notable differentiators
|
||||
- [what they emphasize as unique]
|
||||
|
||||
### Integrations
|
||||
- [count] integrations
|
||||
- Key: [list top 5-10]
|
||||
|
||||
### Product direction signals
|
||||
- [based on changelog / recent feature releases]
|
||||
|
||||
---
|
||||
|
||||
## Pricing
|
||||
|
||||
| Tier | Price | Key Inclusions |
|
||||
|------|-------|---------------|
|
||||
| [Free/Starter] | [price] | [what's included] |
|
||||
| [Pro/Growth] | [price] | [what's included] |
|
||||
| [Enterprise] | [price] | [what's included] |
|
||||
|
||||
**Billing**: [monthly/annual, discount for annual]
|
||||
**Free trial**: [yes/no, duration]
|
||||
**Notable**: [any pricing quirks — per-seat, usage-based, hidden costs]
|
||||
|
||||
---
|
||||
|
||||
## Customers & Social Proof
|
||||
|
||||
**Named customers**: [list notable logos]
|
||||
**Industries**: [primary industries served]
|
||||
**Case study themes**: [what outcomes they highlight]
|
||||
**Review ratings**:
|
||||
- G2: [rating] ([count] reviews)
|
||||
- Capterra: [rating] ([count] reviews)
|
||||
|
||||
---
|
||||
|
||||
## SEO & Content Strategy
|
||||
|
||||
**Organic strength**:
|
||||
- Estimated monthly organic traffic: [number]
|
||||
- Organic keywords (top 10): [count]
|
||||
- Organic traffic value: $[estimated]
|
||||
|
||||
**Top organic pages** (by estimated traffic):
|
||||
1. [page URL] — [keyword] — [est. traffic]
|
||||
2. [page URL] — [keyword] — [est. traffic]
|
||||
3. [page URL] — [keyword] — [est. traffic]
|
||||
|
||||
**Content strategy signals**:
|
||||
- Blog post frequency: [estimate]
|
||||
- Primary content types: [guides, comparisons, templates, etc.]
|
||||
- Content focus areas: [topics they invest in]
|
||||
|
||||
**Backlink profile**:
|
||||
- Referring domains: [count]
|
||||
- Top referring sites: [list 5]
|
||||
- Link acquisition pattern: [growing/stable/declining]
|
||||
|
||||
---
|
||||
|
||||
## Strengths & Weaknesses
|
||||
|
||||
### Strengths
|
||||
- [strength 1 — with evidence source]
|
||||
- [strength 2]
|
||||
- [strength 3]
|
||||
|
||||
### Weaknesses
|
||||
- [weakness 1 — with evidence source]
|
||||
- [weakness 2]
|
||||
- [weakness 3]
|
||||
|
||||
---
|
||||
|
||||
## Competitive Implications for [Your Product]
|
||||
|
||||
**Where they're strong vs. us**: [areas where this competitor has an advantage]
|
||||
|
||||
**Where we're strong vs. them**: [areas where you have an advantage]
|
||||
|
||||
**Opportunities**: [gaps in their offering or positioning we can exploit]
|
||||
|
||||
**Threats**: [areas where they're improving or gaining ground]
|
||||
|
||||
---
|
||||
|
||||
## Raw Data Sources
|
||||
|
||||
- Homepage scraped: [date]
|
||||
- Pricing page scraped: [date]
|
||||
- SEO data pulled: [date]
|
||||
- Review data pulled: [date, sources]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Summary Document
|
||||
|
||||
After profiling all competitors, generate a `competitor-profiles/_summary.md` that includes:
|
||||
|
||||
1. **Competitor landscape overview** — one paragraph summarizing the competitive field
|
||||
2. **Comparison table** — key metrics side by side for all profiled competitors
|
||||
3. **Positioning map** — where each competitor sits (e.g., simple↔complex, cheap↔premium)
|
||||
4. **Key takeaways** — 3-5 strategic observations from the research
|
||||
5. **Gaps and opportunities** — where the market is underserved
|
||||
|
||||
---
|
||||
|
||||
## Quick Scan vs. Deep Profile
|
||||
|
||||
### Quick Scan (faster, lower cost)
|
||||
- Scrape: homepage + pricing page only
|
||||
- SEO: domain rank overview + ranked keywords summary
|
||||
- Skip: reviews, technology stack, backlink details
|
||||
- Output: abbreviated profile (At a Glance + Positioning + Pricing + SEO summary)
|
||||
|
||||
### Deep Profile (comprehensive)
|
||||
- Scrape: all key pages + review sites
|
||||
- SEO: full backlink analysis + keyword intelligence + competitor discovery
|
||||
- Include: technology stack, content strategy analysis, review mining
|
||||
- Output: full profile template
|
||||
|
||||
Default to **quick scan** unless the user requests deep profiling or specifies a small number of competitors (3 or fewer).
|
||||
|
||||
---
|
||||
|
||||
## Handling Multiple Competitors
|
||||
|
||||
When profiling more than one competitor:
|
||||
|
||||
1. **Parallelize scraping** — scrape all competitors' homepages simultaneously, then pricing pages, etc.
|
||||
2. **Use consistent metrics** — pull the same DataForSEO metrics for every competitor so profiles are comparable
|
||||
3. **Build the summary last** — after all individual profiles are complete
|
||||
4. **Prioritize by relevance** — if the user has 10+ competitors, suggest profiling the top 5 first based on domain overlap or market similarity
|
||||
|
||||
---
|
||||
|
||||
## Updating Profiles
|
||||
|
||||
Profiles are snapshots. When updating:
|
||||
|
||||
- Check pricing pages first (most volatile)
|
||||
- Re-pull SEO metrics (traffic and rankings shift monthly)
|
||||
- Scan changelog for product changes
|
||||
- Update the "Generated" date
|
||||
- Note what changed since last profile in a `## Change Log` section at the bottom
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
Only ask if not answered by context or input:
|
||||
|
||||
1. What competitor URLs should I profile?
|
||||
2. Quick scan or deep profile?
|
||||
3. Any specific dimensions to focus on (pricing, SEO, positioning)?
|
||||
4. Should I compare findings against your product?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **competitors**: For creating comparison/alternative pages from these profiles
|
||||
- **prospecting**: For broader list-building qualification (this skill does deep research on specific accounts; prospecting builds the initial list)
|
||||
- **customer-research**: For mining reviews and community sentiment in depth
|
||||
- **content-strategy**: For using competitor content gaps to plan your own content
|
||||
- **seo-audit**: For auditing your own site relative to competitors
|
||||
- **sales-enablement**: For turning profiles into battle cards and sales collateral
|
||||
- **ads**: For analyzing competitor ad strategies
|
||||
- **pricing**: For deeper pricing analysis informed by competitor profiles
|
||||
@@ -0,0 +1,85 @@
|
||||
{
|
||||
"skill_name": "competitor-profiling",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Profile these three competitors for us: https://competitor1.com, https://competitor2.com, https://competitor3.com. We need this for sales enablement and to find positioning gaps.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should run the full research process: Phase 1 site scraping (Firecrawl map + scrape of homepage, pricing, features, about, customers, integrations, changelog), Phase 2 SEO and market data (DataForSEO for backlinks, ranked keywords, traffic, competitors), Phase 3 synthesis. Should save raw data to competitor-profiles/raw/<slug>/<YYYY-MM-DD>/ with scrapes/, seo/, reviews/ subfolders before synthesizing. Should produce one markdown file per competitor following the profile template (At a Glance, Positioning & Messaging, Product & Features, Pricing, Customers & Social Proof, SEO & Content Strategy, Strengths & Weaknesses, Competitive Implications). Should produce a _summary.md after individual profiles with comparison table, positioning map, key takeaways, gaps and opportunities. Should parallelize scraping when handling multiple competitors and use consistent metrics across all three for comparability.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Runs all three phases (scraping, SEO data, synthesis)",
|
||||
"Saves raw data to competitor-profiles/raw/ with date subfolder",
|
||||
"Produces individual profile per competitor",
|
||||
"Produces _summary.md after individual profiles",
|
||||
"Uses consistent metrics across competitors",
|
||||
"Parallelizes scraping when possible"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We have 12 competitors. Profile all of them.",
|
||||
"expected_output": "Should recommend prioritizing rather than profiling all 12. Should suggest profiling the top 5 first based on domain overlap or market similarity (handling-multiple-competitors guidance). Should default to quick scan mode for a list this size, not deep profile. Should explain the difference: quick scan covers homepage + pricing + domain rank overview + ranked keywords summary, deep profile adds reviews, technology stack, backlink details. Should offer deep profile only if user requests or for 3 or fewer competitors. Should ask which competitors are highest priority if user wants to narrow further.",
|
||||
"assertions": [
|
||||
"Recommends prioritization over profiling all 12",
|
||||
"Suggests top 5 based on relevance",
|
||||
"Defaults to quick scan for large list",
|
||||
"Explains quick scan vs deep profile difference",
|
||||
"Asks user to prioritize"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "I have an existing profile of Notion from 4 months ago. Should I update it or start fresh?",
|
||||
"expected_output": "Should explain profile updating process from the Updating Profiles section. Should recommend updating rather than starting fresh — preserves history and enables diffing. Should explain what to re-pull: pricing page first (most volatile), SEO metrics (traffic and rankings shift monthly), changelog scan for product changes. Should update the Generated date. Should add a Change Log section at the bottom noting what changed since last profile. Should also save the new raw data to a new <YYYY-MM-DD> folder rather than overwriting prior data — supports diffing over time.",
|
||||
"assertions": [
|
||||
"Recommends updating over starting fresh",
|
||||
"Lists what to re-pull (pricing, SEO, changelog)",
|
||||
"Mentions adding Change Log section",
|
||||
"Says to save raw data to new date folder",
|
||||
"Says never overwrite prior date's data"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "What pages should I scrape for a competitor profile?",
|
||||
"expected_output": "Should list the prioritized page types from Phase 1: homepage, pricing page, features/product pages, about/company page, blog (top-level for content strategy signals), customers/case studies page, integrations page, changelog/what's new (if exists). Should explain what to extract from each: homepage (headline, value prop, primary CTA, social proof, target audience signals), pricing (tiers, prices, feature breakdown, billing options, free tier/trial details), features (categories, key capabilities, how they describe each feature), about (founding story, team size, funding, mission, HQ), customers (named customers, logos, industries, case study themes), integrations (count, key integrations, categories), changelog (release velocity, recent focus areas, product direction signals). Should mention optional review scraping (G2, Capterra, Product Hunt, TrustRadius).",
|
||||
"assertions": [
|
||||
"Lists all key page types in priority order",
|
||||
"Specifies what to extract from each page type",
|
||||
"Includes changelog as product direction signal",
|
||||
"Mentions optional review scraping",
|
||||
"References Firecrawl Map then Scrape workflow"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "I want a profile but I don't care about SEO data — just pricing, positioning, and customer logos. Can you skip the DataForSEO calls?",
|
||||
"expected_output": "Should accept the scoped request and skip Phase 2. Should run Phase 1 (Firecrawl scraping of homepage, pricing, customers pages) and Phase 3 synthesis only. Should explain that without SEO data, the profile won't include Domain Rank, organic traffic estimates, ranked keywords, referring domains, or top organic pages — but the positioning, pricing, and customer sections will be complete. Should produce an abbreviated profile flagging the SEO section as 'not collected per user request' rather than leaving placeholders. Should still save raw scrapes to disk for reuse.",
|
||||
"assertions": [
|
||||
"Skips Phase 2 (DataForSEO) as requested",
|
||||
"Runs Phase 1 and Phase 3",
|
||||
"Explains what's missing without SEO data",
|
||||
"Flags SEO section as skipped, not blank",
|
||||
"Still saves raw data"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Should I trust the customer logo wall on the competitor's homepage as evidence of who their customers are?",
|
||||
"expected_output": "Should apply the 'Facts Over Opinions' and 'Honest Assessment' principles. Should explain that customer logos are a positioning claim, not necessarily an accurate customer breakdown — companies often show their best-known logos regardless of share of revenue. Should recommend cross-referencing: check case studies for actual usage details, search for press releases naming customers, look at customer reviews on G2/Capterra/TrustRadius for company name signals, check their LinkedIn for posts about customers. Should note: if they claim '10,000 customers' but have weak traffic/backlink profile, the claim should be flagged in the profile. Should distinguish between named customers (verifiable claims) and 'industries served' (positioning statement). Always include the date the data was pulled.",
|
||||
"assertions": [
|
||||
"Treats logos as positioning claim, not customer breakdown",
|
||||
"Recommends cross-referencing case studies and reviews",
|
||||
"Mentions checking traffic/backlink profile against claim scale",
|
||||
"Distinguishes verifiable named customers from claims",
|
||||
"Notes including date pulled"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,167 @@
|
||||
# Profile Templates
|
||||
|
||||
Ready-to-use templates for competitor profile sections and the summary document.
|
||||
|
||||
## Contents
|
||||
- Quick Scan Template
|
||||
- Summary Comparison Table
|
||||
- Positioning Map
|
||||
- Competitive SWOT
|
||||
- Profile Update Changelog
|
||||
|
||||
---
|
||||
|
||||
## Quick Scan Template
|
||||
|
||||
Abbreviated profile for when speed matters more than depth.
|
||||
|
||||
```markdown
|
||||
# [Competitor Name] — Quick Profile
|
||||
|
||||
**URL**: [website]
|
||||
**Generated**: [date]
|
||||
|
||||
## At a Glance
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| Tagline | [from homepage] |
|
||||
| Target audience | [inferred from copy] |
|
||||
| Pricing starts at | [lowest paid tier] |
|
||||
| Free tier/trial | [yes/no + details] |
|
||||
| Domain rank | [from DataForSEO] |
|
||||
| Est. organic traffic | [monthly] |
|
||||
| Organic keywords (top 10) | [count] |
|
||||
| Referring domains | [count] |
|
||||
|
||||
## Positioning
|
||||
|
||||
**Headline**: "[exact homepage headline]"
|
||||
**Subheadline**: "[exact subheadline]"
|
||||
**Positioning angle**: [1-2 sentence summary of how they position]
|
||||
|
||||
## Pricing Summary
|
||||
|
||||
| Tier | Price | Notable Inclusions |
|
||||
|------|-------|-------------------|
|
||||
| [tier] | [price] | [key items] |
|
||||
| [tier] | [price] | [key items] |
|
||||
|
||||
## Key Takeaway
|
||||
|
||||
[2-3 sentences: what makes this competitor notable, where they're strong, where they're weak]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Summary Comparison Table
|
||||
|
||||
Use after profiling all competitors to create a side-by-side view.
|
||||
|
||||
```markdown
|
||||
# Competitive Landscape Summary
|
||||
|
||||
**Generated**: [date]
|
||||
**Your product**: [name]
|
||||
**Competitors profiled**: [count]
|
||||
|
||||
## Side-by-Side Comparison
|
||||
|
||||
| Dimension | [Your Product] | [Competitor 1] | [Competitor 2] | [Competitor 3] |
|
||||
|-----------|---------------|----------------|----------------|----------------|
|
||||
| **Tagline** | [yours] | [theirs] | [theirs] | [theirs] |
|
||||
| **Target audience** | [yours] | [theirs] | [theirs] | [theirs] |
|
||||
| **Positioning** | [angle] | [angle] | [angle] | [angle] |
|
||||
| **Starting price** | $[X]/mo | $[X]/mo | $[X]/mo | $[X]/mo |
|
||||
| **Free tier** | [yes/no] | [yes/no] | [yes/no] | [yes/no] |
|
||||
| **Domain rank** | [score] | [score] | [score] | [score] |
|
||||
| **Est. organic traffic** | [number] | [number] | [number] | [number] |
|
||||
| **Referring domains** | [count] | [count] | [count] | [count] |
|
||||
| **G2 rating** | [score] | [score] | [score] | [score] |
|
||||
| **Key strength** | [one-liner] | [one-liner] | [one-liner] | [one-liner] |
|
||||
| **Key weakness** | [one-liner] | [one-liner] | [one-liner] | [one-liner] |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Positioning Map
|
||||
|
||||
Visual representation of where competitors sit along two key dimensions. Choose the two axes most relevant to your market.
|
||||
|
||||
### Common Axis Pairs
|
||||
|
||||
| Market Type | X-Axis | Y-Axis |
|
||||
|-------------|--------|--------|
|
||||
| SaaS tools | Simple → Complex | Cheap → Expensive |
|
||||
| Developer tools | Low-code → Code-first | Individual → Team |
|
||||
| B2B platforms | SMB-focused → Enterprise-focused | Point solution → Platform |
|
||||
| Content tools | Template-driven → Custom | Self-serve → Managed |
|
||||
|
||||
### Format
|
||||
|
||||
```markdown
|
||||
## Positioning Map
|
||||
|
||||
**Axes**: [X-axis label] vs. [Y-axis label]
|
||||
|
||||
[Y-axis high label]
|
||||
│
|
||||
│
|
||||
[Competitor A] │ [Competitor B]
|
||||
│
|
||||
───────────────────────┼───────────────────────
|
||||
[X-axis low] │ [X-axis high]
|
||||
│
|
||||
[Your Product] │ [Competitor C]
|
||||
│
|
||||
[Y-axis low label]
|
||||
|
||||
### Interpretation
|
||||
- [1-2 sentences about what the map reveals]
|
||||
- [where the whitespace / opportunity is]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Competitive SWOT
|
||||
|
||||
Per-competitor SWOT relative to your product.
|
||||
|
||||
```markdown
|
||||
## SWOT: [Competitor] vs. [Your Product]
|
||||
|
||||
### Strengths (theirs vs. ours)
|
||||
- [Where they genuinely outperform us — be honest]
|
||||
|
||||
### Weaknesses (theirs vs. ours)
|
||||
- [Where they fall short compared to us — with evidence]
|
||||
|
||||
### Opportunities (for us)
|
||||
- [Gaps in their offering we can exploit]
|
||||
- [Segments they're ignoring]
|
||||
- [Messaging angles they're missing]
|
||||
|
||||
### Threats (from them)
|
||||
- [Areas where they're improving fast]
|
||||
- [Features they're building that overlap with us]
|
||||
- [Market moves that could shift perception]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Profile Update Changelog
|
||||
|
||||
Append to the bottom of any profile when updating it.
|
||||
|
||||
```markdown
|
||||
---
|
||||
|
||||
## Change Log
|
||||
|
||||
| Date | What Changed | Source |
|
||||
|------|-------------|--------|
|
||||
| [date] | Pricing increased from $X to $Y | Pricing page re-scrape |
|
||||
| [date] | Launched [feature] | Changelog scrape |
|
||||
| [date] | Domain rank changed from X to Y | DataForSEO re-pull |
|
||||
| [date] | Added [integration] | Integrations page re-scrape |
|
||||
```
|
||||
@@ -0,0 +1,179 @@
|
||||
# MCP Tool Reference for Competitor Profiling
|
||||
|
||||
Quick reference for the Firecrawl and DataForSEO MCP tools used in competitor profiling.
|
||||
|
||||
## Contents
|
||||
- Firecrawl Tools (site scraping)
|
||||
- DataForSEO Tools (SEO & market data)
|
||||
- Recommended Execution Order
|
||||
- Error Handling
|
||||
|
||||
---
|
||||
|
||||
## Firecrawl Tools
|
||||
|
||||
### firecrawl_map
|
||||
**Purpose**: Discover all URLs on a competitor's site to identify key pages.
|
||||
**When to use**: First step for every competitor — before scraping individual pages.
|
||||
**Key output**: List of URLs with their page types/paths.
|
||||
**Tip**: Look for paths containing `/pricing`, `/features`, `/about`, `/customers`, `/integrations`, `/blog`, `/changelog`.
|
||||
|
||||
### firecrawl_scrape
|
||||
**Purpose**: Extract content from a single page as clean markdown.
|
||||
**When to use**: After mapping, scrape each key page individually.
|
||||
**Key output**: Page content in markdown format — headlines, body text, structured data.
|
||||
**Tip**: Scrape homepage first — it reveals positioning, audience, and social proof in one shot.
|
||||
|
||||
### firecrawl_search
|
||||
**Purpose**: Search the web for specific content about a competitor.
|
||||
**When to use**: Finding review pages, press coverage, or competitor mentions not on their own site.
|
||||
**Example queries**:
|
||||
- `"[Competitor Name]" site:g2.com`
|
||||
- `"[Competitor Name]" review`
|
||||
- `"[Competitor Name]" funding OR raised`
|
||||
|
||||
### firecrawl_crawl
|
||||
**Purpose**: Crawl multiple pages from a site in one operation.
|
||||
**When to use**: Deep profiles where you want to analyze many pages (e.g., all feature pages, all blog posts). More expensive — use selectively.
|
||||
**Tip**: Set page limits to avoid crawling entire sites. Target specific URL patterns.
|
||||
|
||||
### firecrawl_extract
|
||||
**Purpose**: Extract structured data from a page using a schema.
|
||||
**When to use**: When you need specific data points in a consistent format (e.g., pricing tier details, feature lists).
|
||||
**Tip**: Define a clear schema for what you want extracted — more reliable than parsing raw markdown.
|
||||
|
||||
---
|
||||
|
||||
## DataForSEO MCP Tools
|
||||
|
||||
### Domain-Level Intelligence
|
||||
|
||||
#### backlinks_summary
|
||||
**Purpose**: Get domain authority, total backlinks, referring domains, spam score.
|
||||
**Input**: Target domain (e.g., `competitor.com`)
|
||||
**Key metrics**: `domain_rank`, `total_backlinks`, `referring_domains`, `backlinks_spam_score`
|
||||
|
||||
#### backlinks_referring_domains
|
||||
**Purpose**: List top referring domains — shows where their link equity comes from.
|
||||
**Input**: Target domain + limit
|
||||
**Key metrics**: Per-domain: `rank`, `backlinks`, `domain` name
|
||||
|
||||
#### dataforseo_labs_google_domain_rank_overview
|
||||
**Purpose**: Organic search overview — traffic, keywords, traffic value.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: `organic_count` (keywords), `organic_traffic` (estimated monthly), `organic_cost` (traffic value in $)
|
||||
|
||||
#### dataforseo_labs_google_ranked_keywords
|
||||
**Purpose**: What keywords a domain ranks for, with positions.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: Per-keyword: `keyword`, `position`, `search_volume`, `url` (ranking page)
|
||||
**Tip**: Sort by traffic to find their highest-value keywords.
|
||||
|
||||
#### dataforseo_labs_google_keywords_for_site
|
||||
**Purpose**: Keywords relevant to a domain — broader than ranked keywords, includes opportunities.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: `keyword`, `search_volume`, `competition`, `cpc`
|
||||
|
||||
### Competitive Analysis
|
||||
|
||||
#### dataforseo_labs_google_competitors_domain
|
||||
**Purpose**: Find a domain's closest organic competitors by keyword overlap.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: `domain`, `avg_position`, `intersections` (shared keywords), `full_domain_rank`
|
||||
**Tip**: May reveal competitors the user hasn't considered.
|
||||
|
||||
#### dataforseo_labs_google_domain_intersection
|
||||
**Purpose**: Find keywords where two domains both rank — shows direct competition.
|
||||
**Input**: Two target domains
|
||||
**Key metrics**: `keyword`, position for each domain, `search_volume`
|
||||
**Tip**: Use this to compare the user's domain vs. each competitor.
|
||||
|
||||
#### dataforseo_labs_google_relevant_pages
|
||||
**Purpose**: Find a domain's most important pages by organic traffic.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: `page`, `metrics` (traffic, keywords per page)
|
||||
**Tip**: Reveals their content strategy — which pages drive the most value.
|
||||
|
||||
### Technology Detection
|
||||
|
||||
#### domain_analytics_technologies_domain_technologies
|
||||
**Purpose**: Detect the technology stack a domain uses.
|
||||
**Input**: Target domain
|
||||
**Key metrics**: Technologies grouped by category (CMS, analytics, marketing, payments, etc.)
|
||||
|
||||
### Backlink Deep Dive
|
||||
|
||||
#### backlinks_backlinks
|
||||
**Purpose**: List individual backlinks to a domain.
|
||||
**Input**: Target domain + limit
|
||||
**Key metrics**: `url_from`, `url_to`, `anchor`, `domain_from_rank`, `is_new`
|
||||
|
||||
#### backlinks_bulk_ranks
|
||||
**Purpose**: Compare domain ranks across multiple domains at once.
|
||||
**Input**: Array of target domains
|
||||
**Key metrics**: `domain_rank` per domain
|
||||
**Tip**: Use this for the summary comparison table.
|
||||
|
||||
---
|
||||
|
||||
## Recommended Execution Order
|
||||
|
||||
### Quick Scan (per competitor)
|
||||
|
||||
```
|
||||
1. firecrawl_map → get site URLs
|
||||
2. In parallel:
|
||||
a. firecrawl_scrape → homepage
|
||||
b. firecrawl_scrape → pricing page
|
||||
c. dataforseo_labs_google_domain_rank_overview → organic metrics
|
||||
d. backlinks_summary → domain authority
|
||||
3. Synthesize into abbreviated profile
|
||||
```
|
||||
|
||||
### Deep Profile (per competitor)
|
||||
|
||||
```
|
||||
1. firecrawl_map → get site URLs
|
||||
2. In parallel (batch 1 — scraping):
|
||||
a. firecrawl_scrape → homepage
|
||||
b. firecrawl_scrape → pricing page
|
||||
c. firecrawl_scrape → features page(s)
|
||||
d. firecrawl_scrape → about page
|
||||
e. firecrawl_scrape → customers/case studies page
|
||||
f. firecrawl_scrape → integrations page
|
||||
3. In parallel (batch 2 — SEO data):
|
||||
a. dataforseo_labs_google_domain_rank_overview
|
||||
b. dataforseo_labs_google_ranked_keywords
|
||||
c. backlinks_summary
|
||||
d. backlinks_referring_domains
|
||||
e. dataforseo_labs_google_relevant_pages
|
||||
f. dataforseo_labs_google_competitors_domain
|
||||
4. In parallel (batch 3 — optional extras):
|
||||
a. domain_analytics_technologies_domain_technologies
|
||||
b. firecrawl_search → G2/Capterra reviews
|
||||
c. dataforseo_labs_google_domain_intersection (vs. user's domain)
|
||||
5. Synthesize into full profile
|
||||
```
|
||||
|
||||
### Multi-Competitor (3+ competitors)
|
||||
|
||||
```
|
||||
1. Map all competitor sites in parallel
|
||||
2. Scrape all homepages in parallel, then pricing pages in parallel
|
||||
3. Pull domain_rank_overview for all in parallel
|
||||
4. Pull backlinks_bulk_ranks for all at once
|
||||
5. Build profiles in sequence (synthesis requires focus)
|
||||
6. Build summary comparison last
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
| Issue | Action |
|
||||
|-------|--------|
|
||||
| Firecrawl scrape returns empty/blocked | Try with `firecrawl_browser_create` for JS-heavy sites |
|
||||
| Pricing page not found in map | Search for `/pricing`, `/plans`, `/packages` — some sites use different paths |
|
||||
| DataForSEO returns no data for domain | Domain may be too new or too small — note "insufficient data" in profile |
|
||||
| Rate limits hit | Space out requests; prioritize highest-value data first |
|
||||
| Review page scraping blocked | Use `firecrawl_search` to find cached or alternative review sources |
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: competitor-alternatives
|
||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' or 'competitive landing pages.' Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. Emphasizes deep research, modular content architecture, and varied section types beyond feature tables."
|
||||
name: competitors
|
||||
description: "When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when the user mentions 'alternative page,' 'vs page,' 'competitor comparison,' 'comparison page,' '[Product] vs [Product],' '[Product] alternative,' 'competitive landing pages,' 'how do we compare to X,' 'battle card,' or 'competitor teardown.' Use this for any content that positions your product against competitors. Covers four formats: singular alternative, plural alternatives, you vs competitor, and competitor vs competitor. For sales-specific competitor docs, see sales-enablement."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Competitor & Alternative Pages
|
||||
@@ -12,7 +12,7 @@ You are an expert in creating competitor comparison and alternative pages. Your
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before creating competitor pages, understand:
|
||||
|
||||
@@ -252,4 +252,5 @@ Recommended pages to create with priority order based on search volume.
|
||||
- **programmatic-seo**: For building competitor pages at scale
|
||||
- **copywriting**: For writing compelling comparison copy
|
||||
- **seo-audit**: For optimizing competitor pages
|
||||
- **schema-markup**: For FAQ and comparison schema
|
||||
- **schema**: For FAQ and comparison schema
|
||||
- **sales-enablement**: For internal sales collateral, decks, and objection docs
|
||||
@@ -0,0 +1,93 @@
|
||||
{
|
||||
"skill_name": "competitors",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Create a 'Best Asana Alternatives' page for our project management tool. We compete mainly on price (we're $8/user vs their $24/user) and simplicity (they've become bloated). Target audience is small teams (5-20 people).",
|
||||
"expected_output": "Should check for product-marketing.md first. Should identify this as the plural alternatives format ([Competitor] Alternatives). Should include the essential sections: TL;DR comparison, brief paragraphs on each alternative (including the user's product positioned first or prominently), feature comparison table, pricing comparison, who each alternative is best for. Should use the modular content architecture approach. Should address SEO considerations for the target keyword 'Asana alternatives.' Should position the user's product with the stated differentiators (price, simplicity).",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Identifies as plural alternatives format",
|
||||
"Includes TL;DR comparison section",
|
||||
"Includes feature comparison table",
|
||||
"Includes pricing comparison",
|
||||
"Includes 'who it's best for' per alternative",
|
||||
"Positions user's product prominently with differentiators",
|
||||
"Addresses SEO for target keyword"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Write a 'HubSpot vs Salesforce' comparison page. We're HubSpot and want to show why we're the better choice for SMBs.",
|
||||
"expected_output": "Should identify this as the 'you vs competitor' format. Should include structured comparison sections: overview of both, feature-by-feature comparison, pricing comparison, pros/cons of each, who each is best for, and migration path. Should be factually accurate about the competitor while strategically positioning the user's product. Should include a TL;DR at the top. Should address the SMB angle throughout. Should use the centralized competitor data architecture pattern.",
|
||||
"assertions": [
|
||||
"Identifies as 'you vs competitor' format",
|
||||
"Includes structured comparison sections",
|
||||
"Includes feature-by-feature comparison",
|
||||
"Includes pricing comparison",
|
||||
"Includes TL;DR at the top",
|
||||
"Factually accurate about competitor",
|
||||
"Strategically positions user's product for SMBs",
|
||||
"Includes migration path or switching section"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "we need a page targeting 'mailchimp alternative' (singular). we're an email marketing platform focused on e-commerce brands.",
|
||||
"expected_output": "Should trigger on casual phrasing. Should identify this as the singular alternative format ([Competitor] Alternative — positioning your product as THE alternative). Should focus the entire page on why the user's product is the best Mailchimp alternative for e-commerce. Should include: why people switch from Mailchimp, what the user's product does better (e-commerce specific features), feature comparison, pricing comparison, migration guide, customer testimonials. Should optimize for the singular keyword 'Mailchimp alternative.'",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Identifies as singular alternative format",
|
||||
"Focuses on user's product as THE alternative",
|
||||
"Includes why people switch from Mailchimp",
|
||||
"Highlights e-commerce-specific advantages",
|
||||
"Includes feature and pricing comparison",
|
||||
"Includes migration guide",
|
||||
"Optimizes for singular keyword"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Can you create a comparison page for 'Notion vs Coda'? We're a third-party review site, not affiliated with either product.",
|
||||
"expected_output": "Should identify this as the 'competitor vs competitor' format (third-party perspective). Should maintain objectivity since the user isn't either product. Should include balanced comparison: overview of both, feature comparison, pricing, pros/cons, use case recommendations. Should use the essential page sections from the skill. Should suggest how to monetize the page (affiliate links, CTA to the user's own product if relevant). Should address SEO for the 'Notion vs Coda' keyword.",
|
||||
"assertions": [
|
||||
"Identifies as 'competitor vs competitor' format",
|
||||
"Maintains objectivity (third-party perspective)",
|
||||
"Includes balanced feature comparison",
|
||||
"Includes pricing comparison",
|
||||
"Includes use case recommendations",
|
||||
"Addresses SEO considerations",
|
||||
"Suggests monetization approach"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We want to build a whole competitor comparison hub. We have 5 main competitors and want to create alternative pages for each, plus head-to-head comparisons. How should we structure this?",
|
||||
"expected_output": "Should apply the centralized competitor data architecture. Should recommend a hub structure with: individual alternative pages for each competitor (5 singular pages), a 'best alternatives' roundup page, head-to-head comparison pages for key matchups. Should address internal linking strategy between these pages. Should recommend the research process for gathering competitive data. Should address URL structure and site architecture for the hub.",
|
||||
"assertions": [
|
||||
"Applies centralized competitor data architecture",
|
||||
"Recommends hub structure with multiple page types",
|
||||
"Suggests individual and roundup alternative pages",
|
||||
"Addresses internal linking between comparison pages",
|
||||
"Recommends research process for competitive data",
|
||||
"Addresses URL structure"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "I need to create a battle card for our sales team comparing us to Zendesk. It should help reps handle competitive objections during sales calls.",
|
||||
"expected_output": "Should recognize this as internal sales enablement material, not a public comparison page. Should defer to or cross-reference the sales-enablement skill, which handles battle cards, objection handling docs, and internal competitive collateral. May provide some competitive positioning advice but should make clear that sales-enablement is the right skill for internal sales materials.",
|
||||
"assertions": [
|
||||
"Recognizes this as internal sales enablement material",
|
||||
"References or defers to sales-enablement skill",
|
||||
"Does not attempt to create internal battle card using public comparison page patterns"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: content-strategy
|
||||
description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," or "content planning." For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit.
|
||||
description: When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also use when the user mentions "content strategy," "what should I write about," "content ideas," "blog strategy," "topic clusters," "content planning," "editorial calendar," "content marketing," "content roadmap," "what content should I create," "blog topics," "content pillars," or "I don't know what to write." Use this whenever someone needs help deciding what content to produce, not just writing it. For writing individual pieces, see copywriting. For SEO-specific audits, see seo-audit. For social media content specifically, see social.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Content Strategy
|
||||
@@ -12,7 +12,7 @@ You are a content strategist. Your goal is to help plan content that drives traf
|
||||
## Before Planning
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
@@ -348,11 +348,18 @@ Visual or structured representation of how content interconnects.
|
||||
|
||||
---
|
||||
|
||||
## References
|
||||
|
||||
- **[Headless CMS Guide](references/headless-cms.md)**: CMS selection, content modeling for marketing, editorial workflows, platform comparison (Sanity, Contentful, Strapi)
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For writing individual content pieces
|
||||
- **seo-audit**: For technical SEO and on-page optimization
|
||||
- **ai-seo**: For optimizing content for AI search engines and getting cited by LLMs
|
||||
- **programmatic-seo**: For scaled content generation
|
||||
- **email-sequence**: For email-based content
|
||||
- **social-content**: For social media content
|
||||
- **site-architecture**: For page hierarchy, navigation design, and URL structure
|
||||
- **emails**: For email-based content
|
||||
- **social**: For social media content
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"skill_name": "content-strategy",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Help me build a content strategy for our B2B SaaS product. We sell expense management software to finance teams at companies with 50-500 employees. We currently have no blog and want to start from scratch.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should establish content pillars (3-5 core topic areas). Should map content types by buyer stage (awareness → consideration → decision → implementation). Should identify keyword research opportunities by buyer stage. Should recommend a mix of searchable (SEO-driven) and shareable (thought leadership, data) content. Should use the prioritization scoring framework (customer impact 40%, content-market fit 30%, search potential 20%, resources 10%). Should provide an initial content calendar or publishing cadence. Should recommend content types appropriate for starting from scratch.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Establishes 3-5 content pillars",
|
||||
"Maps content by buyer stage (awareness through implementation)",
|
||||
"Includes keyword research by buyer stage",
|
||||
"Recommends mix of searchable and shareable content",
|
||||
"Uses prioritization scoring framework",
|
||||
"Provides publishing cadence or calendar",
|
||||
"Recommends appropriate starting content types"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We have 200+ blog posts but traffic has been flat for a year. Our content feels random — no clear strategy. How do we fix this?",
|
||||
"expected_output": "Should diagnose the 'random content' problem. Should recommend a content audit process to evaluate existing posts. Should introduce content pillars and topical clustering to organize the existing library. Should identify hub-and-spoke opportunities from existing content. Should recommend which posts to update, consolidate, or retire. Should use the prioritization framework to plan next steps. Should address topical authority building through clusters.",
|
||||
"assertions": [
|
||||
"Diagnoses the 'random content' problem",
|
||||
"Recommends content audit for existing posts",
|
||||
"Introduces content pillars and topical clustering",
|
||||
"Identifies hub-and-spoke opportunities",
|
||||
"Recommends update, consolidate, or retire decisions",
|
||||
"Uses prioritization framework",
|
||||
"Addresses topical authority building"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "what kind of content should we be creating? we're a developer tool (API testing platform) and our audience is backend developers and QA engineers",
|
||||
"expected_output": "Should trigger on casual phrasing. Should recommend content types appropriate for a developer audience: technical tutorials, documentation-style guides, use-case content, template/example libraries, data-driven benchmarks. Should note that developer audiences prefer depth, accuracy, and practical value over marketing fluff. Should suggest content pillars aligned with developer interests. Should use the ideation sources framework (keyword data, community forums like Stack Overflow/Reddit, competitor gaps).",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Recommends content types for developer audience",
|
||||
"Emphasizes technical depth and practical value",
|
||||
"Notes developers prefer substance over marketing",
|
||||
"Suggests content pillars for developer tool",
|
||||
"Uses ideation sources framework",
|
||||
"Mentions developer community channels"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "How should we prioritize which content to create first? We have a list of 50 blog post ideas but limited resources — one content marketer writing 2 posts per week.",
|
||||
"expected_output": "Should apply the prioritization scoring framework: customer impact (40%), content-market fit (30%), search potential (20%), resources required (10%). Should help score or rank the content ideas using this framework. Should recommend focusing on high-impact, lower-effort content first. Should consider the buyer stage distribution (don't write only top-of-funnel). Should provide a practical workflow for the single content marketer to use going forward.",
|
||||
"assertions": [
|
||||
"Applies prioritization scoring framework with weights",
|
||||
"Explains each scoring dimension",
|
||||
"Recommends focusing on high-impact, lower-effort first",
|
||||
"Considers buyer stage distribution",
|
||||
"Provides practical workflow for limited resources"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We want to build topical authority in 'employee engagement.' What does a content cluster look like for this topic?",
|
||||
"expected_output": "Should apply the hub-and-spoke content cluster model. Should design a pillar page for 'employee engagement' (comprehensive, 3000+ word guide). Should identify 8-15 supporting spoke articles targeting long-tail keywords related to employee engagement. Should map the internal linking structure between hub and spokes. Should address keyword research for the cluster. Should recommend content types for each piece (guide, how-to, template, data-driven, etc.).",
|
||||
"assertions": [
|
||||
"Applies hub-and-spoke content cluster model",
|
||||
"Designs a pillar page for the core topic",
|
||||
"Identifies 8-15 supporting spoke articles",
|
||||
"Maps internal linking between hub and spokes",
|
||||
"Addresses keyword research for the cluster",
|
||||
"Recommends content types for each piece"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Can you write a blog post about remote work best practices for our HR software blog?",
|
||||
"expected_output": "Should recognize this is a copywriting/content creation task, not a content strategy task. Should defer to or cross-reference the copywriting skill for writing individual pieces of content. May provide strategic context (where this fits in the content strategy, keyword targeting, audience) but should make clear that copywriting is the right skill for writing the actual content.",
|
||||
"assertions": [
|
||||
"Recognizes this as content creation, not strategy",
|
||||
"References or defers to copywriting skill",
|
||||
"Does not attempt to write the full blog post",
|
||||
"May provide strategic context for the piece"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,194 @@
|
||||
# Headless CMS Guide
|
||||
|
||||
Reference for choosing, modeling, and implementing a headless CMS for marketing content.
|
||||
|
||||
## When to Use This Reference
|
||||
|
||||
Use this when selecting a CMS for a new project, designing content models for marketing sites, setting up editorial workflows, or connecting CMS content to programmatic pages.
|
||||
|
||||
---
|
||||
|
||||
## Headless vs Traditional CMS
|
||||
|
||||
A headless CMS separates content management from presentation. Content is stored in a structured backend and delivered via API to any frontend.
|
||||
|
||||
### When Headless Makes Sense
|
||||
|
||||
- Multiple frontends consume the same content (web, mobile, email)
|
||||
- Developers want full control over the frontend stack
|
||||
- Content needs to be reused across channels
|
||||
- You're building with a modern framework (Next.js, Remix, Astro)
|
||||
- Marketing needs structured, reusable content blocks
|
||||
|
||||
### When Traditional Works Better
|
||||
|
||||
- Small team with no dedicated developers
|
||||
- Simple blog or brochure site
|
||||
- WYSIWYG editing is a hard requirement
|
||||
- Budget is tight and WordPress/Webflow does the job
|
||||
|
||||
### Decision Checklist
|
||||
|
||||
| Factor | Headless | Traditional |
|
||||
|--------|----------|-------------|
|
||||
| Multi-channel delivery | Yes | Limited |
|
||||
| Developer control | Full | Constrained |
|
||||
| Non-technical editing | Requires setup | Built-in |
|
||||
| Time to launch | Longer | Faster |
|
||||
| Content reuse | Native | Manual |
|
||||
| Hosting flexibility | Any frontend | Platform-dependent |
|
||||
|
||||
---
|
||||
|
||||
## Content Modeling for Marketing
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Think in types, not pages.** A "Landing Page" is a content type with fields — not an HTML file. This lets you reuse components across pages.
|
||||
2. **Separate content from presentation.** Store the headline text, not the styled headline. Presentation belongs in the frontend.
|
||||
3. **Design for reuse.** If testimonials appear on 5 pages, create a Testimonial type and reference it — don't duplicate.
|
||||
4. **Keep models flat.** Deeply nested structures are hard to query and maintain. Prefer references over nesting.
|
||||
|
||||
### Common Marketing Content Types
|
||||
|
||||
| Type | Key Fields | Notes |
|
||||
|------|-----------|-------|
|
||||
| **Landing Page** | title, slug, hero, sections[], seo | Modular sections for flexibility |
|
||||
| **Blog Post** | title, slug, body, author, category, tags, publishedAt, seo | Rich text or Portable Text body |
|
||||
| **Case Study** | title, customer, challenge, solution, results, metrics[], logo | Link to related products/features |
|
||||
| **Testimonial** | quote, author, role, company, avatar, rating | Reference from landing pages |
|
||||
| **FAQ** | question, answer, category | Group by category for programmatic pages |
|
||||
| **Author** | name, bio, avatar, social links | Reference from blog posts |
|
||||
| **CTA Block** | heading, body, buttonText, buttonUrl, variant | Reusable across pages |
|
||||
|
||||
### SEO Fields Checklist
|
||||
|
||||
Every page-level content type needs:
|
||||
|
||||
- `metaTitle` — 50-60 characters
|
||||
- `metaDescription` — 150-160 characters
|
||||
- `ogImage` — 1200x630px social preview
|
||||
- `slug` — URL path segment
|
||||
- `canonicalUrl` — optional override
|
||||
- `noIndex` — boolean for excluding from search
|
||||
- `structuredData` — optional JSON-LD override
|
||||
|
||||
---
|
||||
|
||||
## Editorial Workflows
|
||||
|
||||
### Draft → Review → Publish Cycle
|
||||
|
||||
1. **Draft** — Author creates or edits content
|
||||
2. **Review** — Editor reviews for accuracy, brand voice, SEO
|
||||
3. **Approve** — Stakeholder signs off
|
||||
4. **Schedule** — Set publish date/time
|
||||
5. **Publish** — Content goes live via API
|
||||
|
||||
### Preview APIs
|
||||
|
||||
All major headless CMS platforms support draft previews:
|
||||
|
||||
- **Sanity**: Real-time preview with `useLiveQuery` or Presentation tool
|
||||
- **Contentful**: Preview API (`preview.contentful.com`) with separate access token
|
||||
- **Strapi**: Draft & Publish system with `status=draft` query parameter (v5; replaces v4's `publicationState`)
|
||||
|
||||
Set up a preview route in your frontend (e.g., `/api/preview`) that authenticates and renders draft content.
|
||||
|
||||
### Roles and Permissions
|
||||
|
||||
| Role | Can Create | Can Edit | Can Publish | Can Delete |
|
||||
|------|:----------:|:--------:|:-----------:|:----------:|
|
||||
| Author | Yes | Own | No | Own drafts |
|
||||
| Editor | Yes | All | Yes | Drafts |
|
||||
| Admin | Yes | All | Yes | All |
|
||||
|
||||
Exact permission models vary by platform. Sanity uses role-based access. Contentful has space-level roles. Strapi has granular RBAC.
|
||||
|
||||
---
|
||||
|
||||
## Platform Comparison
|
||||
|
||||
| Feature | Sanity | Contentful | Strapi |
|
||||
|---------|--------|------------|--------|
|
||||
| Hosting | Cloud (managed) | Cloud (managed) | Self-hosted or Cloud |
|
||||
| Query Language | GROQ | REST / GraphQL | REST / GraphQL |
|
||||
| Free Tier | Generous | Limited | Open source (free) |
|
||||
| Real-time Collab | Yes (built-in) | Limited | No |
|
||||
| Best For | Developer flexibility | Enterprise multi-locale | Budget / self-hosted |
|
||||
| Content Modeling | Schema-as-code | Web UI | Web UI or code |
|
||||
| Media Handling | Built-in DAM | Built-in | Plugin-based |
|
||||
|
||||
### Sanity
|
||||
|
||||
**Strengths**: GROQ query language is powerful and flexible. Schema defined in code (version-controlled). Real-time collaborative editing. Portable Text for rich content. Generous free tier.
|
||||
|
||||
**Considerations**: Steeper learning curve for non-developers. Studio customization requires React knowledge. Vendor lock-in on GROQ queries.
|
||||
|
||||
**Marketing fit**: Best when developers and marketers collaborate closely. Strong for content-heavy sites with complex models.
|
||||
|
||||
### Contentful
|
||||
|
||||
**Strengths**: Mature enterprise platform. Excellent multi-locale support. Strong ecosystem of integrations. Composable content with Studio. Well-documented APIs.
|
||||
|
||||
**Considerations**: Pricing scales with content types and locales. Two separate APIs (Delivery and Management). Rate limits can be tight on lower plans.
|
||||
|
||||
**Marketing fit**: Best for enterprises with multi-market content needs. Good when you need established vendor reliability.
|
||||
|
||||
### Strapi
|
||||
|
||||
**Strengths**: Open source, self-hosted option. Full control over data. No per-seat pricing. Customizable admin panel. Plugin ecosystem. REST by default, GraphQL via plugin.
|
||||
|
||||
**Considerations**: Self-hosting means you handle infrastructure. Smaller ecosystem than Sanity/Contentful. V5 migration can be significant from V4.
|
||||
|
||||
**Marketing fit**: Best for teams with DevOps capability who want full control and no vendor lock-in. Good for budget-conscious projects.
|
||||
|
||||
### Others Worth Knowing
|
||||
|
||||
- **Hygraph** — GraphQL-native, strong for federation and multi-source content
|
||||
- **Keystatic** — Git-based, good for developer-content hybrid workflows
|
||||
- **Payload** — TypeScript-first, self-hosted, code-configured like Sanity
|
||||
- **Builder.io** — Visual editor with headless backend, good for non-technical marketers
|
||||
- **Prismic** — Slice-based content modeling, strong Next.js integration
|
||||
|
||||
---
|
||||
|
||||
## Integration with Marketing Skills
|
||||
|
||||
### Programmatic SEO
|
||||
|
||||
Use CMS as the data source for programmatic pages. Store structured data (FAQs, comparisons, city pages) as content types and generate pages from queries. See **programmatic-seo** skill.
|
||||
|
||||
### Copywriting
|
||||
|
||||
CMS content models enforce consistent structure. Define fields that match your copy frameworks (headline, subheadline, social proof, CTA). See **copywriting** skill.
|
||||
|
||||
### Site Architecture
|
||||
|
||||
URL structure, navigation hierarchy, and internal linking all depend on how content is organized in the CMS. Plan your content model and site architecture together. See **site-architecture** skill.
|
||||
|
||||
### Email Sequences
|
||||
|
||||
Pull CMS content into email templates for consistent messaging across web and email. Case studies, testimonials, and blog posts can feed email nurture sequences. See **emails** skill.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
- [ ] Define content types based on page types and reusable blocks
|
||||
- [ ] Add SEO fields to every page-level content type
|
||||
- [ ] Set up preview/draft mode in your frontend
|
||||
- [ ] Configure roles and permissions for your team
|
||||
- [ ] Create sample content for each type before building frontend
|
||||
- [ ] Set up webhook notifications for content changes (rebuild triggers)
|
||||
- [ ] Document content guidelines for editors (field descriptions, character limits)
|
||||
- [ ] Test content delivery performance (CDN, caching, ISR)
|
||||
- [ ] Plan migration strategy if moving from existing CMS
|
||||
|
||||
---
|
||||
|
||||
## Relevant Integration Guides
|
||||
|
||||
- [Sanity](../../../tools/integrations/sanity.md) — GROQ queries, mutations, CLI
|
||||
- [Contentful](../../../tools/integrations/contentful.md) — Delivery/Management APIs, publishing
|
||||
- [Strapi](../../../tools/integrations/strapi.md) — REST CRUD, filters, document API
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: copy-editing
|
||||
description: "When the user wants to edit, review, or improve existing marketing copy. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' or 'copy sweep.' This skill provides a systematic approach to editing marketing copy through multiple focused passes."
|
||||
description: "When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the user mentions 'edit this copy,' 'review my copy,' 'copy feedback,' 'proofread,' 'polish this,' 'make this better,' 'copy sweep,' 'tighten this up,' 'this reads awkwardly,' 'clean up this text,' 'too wordy,' 'sharpen the messaging,' 'refresh this content,' 'update this page,' 'this content is outdated,' or 'content audit.' Use this when the user already has copy and wants it improved or refreshed rather than rewritten from scratch. For writing new copy, see copywriting."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Copy Editing
|
||||
@@ -12,7 +12,7 @@ You are an expert copy editor specializing in marketing and conversion copy. You
|
||||
## Core Philosophy
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before editing. Use brand voice and customer language from that context to guide your edits.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before editing. Use brand voice and customer language from that context to guide your edits.
|
||||
|
||||
Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.
|
||||
|
||||
@@ -256,6 +256,57 @@ For every statement, ask "Okay, so what?" If the copy doesn't answer that questi
|
||||
|
||||
---
|
||||
|
||||
## Expert Panel Scoring
|
||||
|
||||
Use this after completing the Seven Sweeps for an additional quality gate. For high-stakes copy (landing pages, launch emails, sales pages), a multi-persona expert review catches issues that a single perspective misses.
|
||||
|
||||
### How It Works
|
||||
|
||||
1. **Assemble 3-5 expert personas** relevant to the copy type
|
||||
2. **Each persona scores the copy 1-10** on their area of expertise
|
||||
3. **Collect specific critiques** — not just scores, but what to fix
|
||||
4. **Revise based on feedback** — address the lowest-scoring areas first
|
||||
5. **Re-score after revisions** — iterate until all personas score 7+, with an average of 8+ across the panel
|
||||
|
||||
### Recommended Expert Panels
|
||||
|
||||
**Landing page copy:**
|
||||
- Conversion copywriter (clarity, CTA strength, benefit hierarchy)
|
||||
- UX writer (scannability, cognitive load, user flow)
|
||||
- Target customer persona (does this speak to me? do I trust it?)
|
||||
- Brand strategist (voice consistency, positioning accuracy)
|
||||
|
||||
**Email sequence:**
|
||||
- Email marketing specialist (subject lines, open/click optimization)
|
||||
- Copywriter (hooks, storytelling, persuasion)
|
||||
- Spam filter analyst (deliverability red flags, trigger words)
|
||||
- Target customer persona (relevance, value, unsubscribe risk)
|
||||
|
||||
**Sales page / long-form:**
|
||||
- Direct response copywriter (offer structure, objection handling, urgency)
|
||||
- Skeptical buyer persona (proof gaps, trust issues, red flags)
|
||||
- Editor (flow, readability, conciseness)
|
||||
- SEO specialist (keyword coverage, search intent alignment)
|
||||
|
||||
### Scoring Rubric
|
||||
|
||||
| Score | Meaning |
|
||||
|-------|---------|
|
||||
| 9-10 | Publish-ready. No meaningful improvements. |
|
||||
| 7-8 | Strong. Minor tweaks only. |
|
||||
| 5-6 | Functional but has clear gaps. Needs another pass. |
|
||||
| 3-4 | Significant issues. Major revision needed. |
|
||||
| 1-2 | Fundamentally broken. Rethink approach. |
|
||||
|
||||
### When to Use
|
||||
|
||||
- **Always** for launch copy, pricing pages, and high-traffic landing pages
|
||||
- **Recommended** for email sequences, sales pages, and ad copy
|
||||
- **Optional** for blog posts, social content, and internal docs
|
||||
- **Skip** for quick updates, minor edits, and low-stakes content
|
||||
|
||||
---
|
||||
|
||||
## Quick-Pass Editing Checks
|
||||
|
||||
Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||
@@ -307,59 +358,7 @@ Use these for faster reviews when a full seven-sweep process isn't needed.
|
||||
|
||||
## Copy Editing Checklist
|
||||
|
||||
### Before You Start
|
||||
- [ ] Understand the goal of this copy
|
||||
- [ ] Know the target audience
|
||||
- [ ] Identify the desired action
|
||||
- [ ] Read through once without editing
|
||||
|
||||
### Clarity (Sweep 1)
|
||||
- [ ] Every sentence is immediately understandable
|
||||
- [ ] No jargon without explanation
|
||||
- [ ] Pronouns have clear references
|
||||
- [ ] No sentences trying to do too much
|
||||
|
||||
### Voice & Tone (Sweep 2)
|
||||
- [ ] Consistent formality level throughout
|
||||
- [ ] Brand personality maintained
|
||||
- [ ] No jarring shifts in mood
|
||||
- [ ] Reads well aloud
|
||||
|
||||
### So What (Sweep 3)
|
||||
- [ ] Every feature connects to a benefit
|
||||
- [ ] Claims answer "why should I care?"
|
||||
- [ ] Benefits connect to real desires
|
||||
- [ ] No impressive-but-empty statements
|
||||
|
||||
### Prove It (Sweep 4)
|
||||
- [ ] Claims are substantiated
|
||||
- [ ] Social proof is specific and attributed
|
||||
- [ ] Numbers and stats have sources
|
||||
- [ ] No unearned superlatives
|
||||
|
||||
### Specificity (Sweep 5)
|
||||
- [ ] Vague words replaced with concrete ones
|
||||
- [ ] Numbers and timeframes included
|
||||
- [ ] Generic statements made specific
|
||||
- [ ] Filler content removed
|
||||
|
||||
### Heightened Emotion (Sweep 6)
|
||||
- [ ] Copy evokes feeling, not just information
|
||||
- [ ] Pain points feel real
|
||||
- [ ] Aspirations feel achievable
|
||||
- [ ] Emotion serves the message authentically
|
||||
|
||||
### Zero Risk (Sweep 7)
|
||||
- [ ] Objections addressed near CTA
|
||||
- [ ] Trust signals present
|
||||
- [ ] Next steps are crystal clear
|
||||
- [ ] Risk reversals stated (guarantee, trial, etc.)
|
||||
|
||||
### Final Checks
|
||||
- [ ] No typos or grammatical errors
|
||||
- [ ] Consistent formatting
|
||||
- [ ] Links work (if applicable)
|
||||
- [ ] Core message preserved through all edits
|
||||
For a final QA pass before delivering edits, work through the full checklist in [references/checklist.md](references/checklist.md) — covering all seven sweeps plus pre-start and final-check items.
|
||||
|
||||
---
|
||||
|
||||
@@ -416,6 +415,16 @@ This iterative process ensures each edit doesn't create new problems while respe
|
||||
## References
|
||||
|
||||
- [Plain English Alternatives](references/plain-english-alternatives.md): Replace complex words with simpler alternatives
|
||||
- [Content Refresh](references/content-refresh.md): Full checklist, refresh vs. rewrite matrix, and cadence guide
|
||||
- [Copy Editing Checklist](references/checklist.md): Full QA checklist across all seven sweeps
|
||||
|
||||
---
|
||||
|
||||
## Content Refresh Editing
|
||||
|
||||
Copy editing isn't just for new content. Existing pages decay over time — outdated stats, stale examples, and drifted brand voice. Use the content refresh framework when traffic is declining, data is stale, or the product has changed.
|
||||
|
||||
**For the full refresh checklist, refresh vs. rewrite decision matrix, and cadence guide**: See [references/content-refresh.md](references/content-refresh.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -425,15 +434,16 @@ This iterative process ensures each edit doesn't create new problems while respe
|
||||
2. What action should readers take?
|
||||
3. Are there specific concerns or known issues?
|
||||
4. What proof/evidence do you have available?
|
||||
5. Is this new copy or a refresh of existing content?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **copywriting**: For writing new copy from scratch (use this skill to edit after your first draft is complete)
|
||||
- **page-cro**: For broader page optimization beyond copy
|
||||
- **cro**: For broader page optimization beyond copy
|
||||
- **marketing-psychology**: For understanding why certain edits improve conversion
|
||||
- **ab-test-setup**: For testing copy variations
|
||||
- **ab-testing**: For testing copy variations
|
||||
|
||||
---
|
||||
|
||||
@@ -444,4 +454,4 @@ This iterative process ensures each edit doesn't create new problems while respe
|
||||
| Writing new page copy from scratch | copywriting |
|
||||
| Reviewing and improving existing copy | copy-editing (this skill) |
|
||||
| Editing copy you just wrote | copy-editing (this skill) |
|
||||
| Structural or strategic page changes | page-cro |
|
||||
| Structural or strategic page changes | cro |
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"skill_name": "copy-editing",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Edit this homepage copy for us: 'Welcome to CloudSync! We are very excited to offer you an innovative, cutting-edge platform that seamlessly integrates with your existing tools. Our powerful solution helps businesses of all sizes optimize their workflows and drive meaningful results. Get started today and experience the difference!'",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the Seven Sweeps Framework systematically. Sweep 1 (Clarity): identify vague language ('optimize workflows,' 'drive meaningful results,' 'experience the difference'). Sweep 2 (Voice & Tone): flag 'Welcome to' as weak opening, 'we are very excited' as company-focused. Sweep 3 (So What): question what specific value is being offered. Sweep 4 (Prove It): note no proof points, stats, or evidence. Sweep 5 (Specificity): flag 'businesses of all sizes,' 'existing tools,' 'powerful solution' as generic. Sweep 6 (Heightened Emotion): assess emotional impact. Sweep 7 (Zero Risk): check for trust signals. Should provide a rewritten version addressing all issues.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies Seven Sweeps Framework",
|
||||
"Identifies vague language (Clarity sweep)",
|
||||
"Flags weak opening and company-focused language (Voice & Tone sweep)",
|
||||
"Questions missing value proposition (So What sweep)",
|
||||
"Notes missing proof points (Prove It sweep)",
|
||||
"Flags generic terms (Specificity sweep)",
|
||||
"Provides a rewritten version"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Quick edit on this CTA section: 'Ready to take your business to the next level? Our team of dedicated professionals is standing by to help you achieve your goals. Click here to learn more about how we can help you succeed.'",
|
||||
"expected_output": "Should apply the quick-pass editing checks. Should identify: 'take your business to the next level' (cliché), 'team of dedicated professionals' (filler), 'standing by' (passive), 'click here' (weak CTA), 'learn more' (vague action), 'help you succeed' (generic). Should apply word-level, sentence-level, and paragraph-level checks. Should rewrite with specific value prop, active voice, and strong action-oriented CTA. Should be concise since this was requested as a 'quick edit.'",
|
||||
"assertions": [
|
||||
"Identifies clichés and filler phrases",
|
||||
"Flags 'click here' and 'learn more' as weak",
|
||||
"Applies word-level and sentence-level checks",
|
||||
"Rewrites with specific value and strong CTA",
|
||||
"Uses active voice in rewrite",
|
||||
"Keeps response concise for a quick edit"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "edit this product description, it feels too long and wordy: 'Our comprehensive project management solution provides teams with a robust set of tools that enable them to efficiently plan, execute, and monitor their projects from start to finish. With our intuitive interface, powerful analytics dashboard, and seamless integration capabilities, you can ensure that every aspect of your project is managed with precision and care. Whether you're a small startup or a large enterprise, our platform scales to meet your unique needs and requirements, helping you deliver projects on time and within budget every single time.'",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the Clarity and Specificity sweeps primarily. Should identify: redundancy ('plan, execute, and monitor' overlaps with 'from start to finish'), filler words ('comprehensive,' 'robust,' 'efficiently,' 'seamless,' 'unique'), hedge phrases ('ensuring every aspect,' 'with precision and care'), and generic claims ('scales to meet your needs,' 'on time and within budget every single time'). Should cut the copy significantly (probably by 50%+). Should provide a tighter rewrite that says the same thing in fewer, more specific words.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Identifies redundancy in the copy",
|
||||
"Identifies filler words and hedge phrases",
|
||||
"Identifies generic claims",
|
||||
"Cuts copy significantly (50%+ reduction)",
|
||||
"Provides tighter rewrite with specific language"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Review this testimonial section and improve it: 'CloudSync is great! It really helped our company. The team was very responsive and the product works well. We would recommend it to anyone looking for a solution. - John S., CEO'",
|
||||
"expected_output": "Should apply the Prove It and Specificity sweeps. Should identify the testimonial as too vague to be persuasive ('great,' 'really helped,' 'works well,' 'anyone looking for a solution'). Should recommend replacing with specific results ('reduced project delivery time by 30%'), specific context ('team of 45 engineers'), and specific outcomes. Should suggest questions to ask the customer for a better testimonial. Should not fabricate specific numbers but should provide a template showing what a strong testimonial looks like.",
|
||||
"assertions": [
|
||||
"Applies Prove It and Specificity sweeps",
|
||||
"Identifies testimonial as too vague",
|
||||
"Recommends specific results and context",
|
||||
"Suggests questions to get better testimonial",
|
||||
"Does not fabricate specific numbers",
|
||||
"Provides template for strong testimonial"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "I need you to apply the 'So What' and 'Zero Risk' sweeps to this pricing page copy: 'Our Pro plan includes unlimited projects, advanced reporting, priority support, and custom integrations. Starting at $99/month.'",
|
||||
"expected_output": "Should apply specifically the So What and Zero Risk sweeps as requested. So What: for each feature, ask 'so what does this mean for the customer?' — unlimited projects (what does that enable?), advanced reporting (what decisions can they make?), priority support (what does that mean in practice? response time?), custom integrations (which ones? what workflow does it enable?). Zero Risk: identify missing trust signals — no guarantee, no trial mention, no social proof near pricing, no 'cancel anytime' assurance. Should provide rewritten copy addressing both sweeps.",
|
||||
"assertions": [
|
||||
"Applies So What sweep to each feature",
|
||||
"Translates features to customer benefits",
|
||||
"Applies Zero Risk sweep",
|
||||
"Identifies missing trust signals",
|
||||
"Suggests guarantee, trial, or cancel-anytime language",
|
||||
"Provides rewritten copy addressing both sweeps"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Write fresh homepage copy for our new product. We're launching a CRM for real estate agents.",
|
||||
"expected_output": "Should recognize this is a copywriting-from-scratch task, not copy editing. Should defer to or cross-reference the copywriting skill, which handles writing new copy from scratch. Copy-editing is specifically for improving existing copy. Should make this distinction clear.",
|
||||
"assertions": [
|
||||
"Recognizes this as writing new copy, not editing existing copy",
|
||||
"References or defers to copywriting skill",
|
||||
"Explains that copy-editing is for improving existing copy",
|
||||
"Does not attempt to write full page copy from scratch"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,66 @@
|
||||
# Copy Editing Checklist
|
||||
|
||||
Use this checklist alongside the Seven Sweeps Framework (see SKILL.md) as a final QA pass before delivering edited copy.
|
||||
|
||||
## Before You Start
|
||||
|
||||
- [ ] Understand the goal of this copy
|
||||
- [ ] Know the target audience
|
||||
- [ ] Identify the desired action
|
||||
- [ ] Read through once without editing
|
||||
|
||||
## Clarity (Sweep 1)
|
||||
|
||||
- [ ] Every sentence is immediately understandable
|
||||
- [ ] No jargon without explanation
|
||||
- [ ] Pronouns have clear references
|
||||
- [ ] No sentences trying to do too much
|
||||
|
||||
## Voice & Tone (Sweep 2)
|
||||
|
||||
- [ ] Consistent formality level throughout
|
||||
- [ ] Brand personality maintained
|
||||
- [ ] No jarring shifts in mood
|
||||
- [ ] Reads well aloud
|
||||
|
||||
## So What (Sweep 3)
|
||||
|
||||
- [ ] Every feature connects to a benefit
|
||||
- [ ] Claims answer "why should I care?"
|
||||
- [ ] Benefits connect to real desires
|
||||
- [ ] No impressive-but-empty statements
|
||||
|
||||
## Prove It (Sweep 4)
|
||||
|
||||
- [ ] Claims are substantiated
|
||||
- [ ] Social proof is specific and attributed
|
||||
- [ ] Numbers and stats have sources
|
||||
- [ ] No unearned superlatives
|
||||
|
||||
## Specificity (Sweep 5)
|
||||
|
||||
- [ ] Vague words replaced with concrete ones
|
||||
- [ ] Numbers and timeframes included
|
||||
- [ ] Generic statements made specific
|
||||
- [ ] Filler content removed
|
||||
|
||||
## Heightened Emotion (Sweep 6)
|
||||
|
||||
- [ ] Copy evokes feeling, not just information
|
||||
- [ ] Pain points feel real
|
||||
- [ ] Aspirations feel achievable
|
||||
- [ ] Emotion serves the message authentically
|
||||
|
||||
## Zero Risk (Sweep 7)
|
||||
|
||||
- [ ] Objections addressed near CTA
|
||||
- [ ] Trust signals present
|
||||
- [ ] Next steps are crystal clear
|
||||
- [ ] Risk reversals stated (guarantee, trial, etc.)
|
||||
|
||||
## Final Checks
|
||||
|
||||
- [ ] No typos or grammatical errors
|
||||
- [ ] Consistent formatting
|
||||
- [ ] Links work (if applicable)
|
||||
- [ ] Core message preserved through all edits
|
||||
@@ -0,0 +1,38 @@
|
||||
# Content Refresh Editing
|
||||
|
||||
Copy editing isn't just for new content. Existing pages and posts decay over time — outdated stats, stale examples, drifted brand voice, and missed SEO opportunities. A content refresh applies the same editing rigor to content that's already published.
|
||||
|
||||
## When to Refresh
|
||||
|
||||
- **Traffic declining** on a page that used to perform well
|
||||
- **Stats or data** are more than 12 months old
|
||||
- **Product has changed** — features, pricing, or positioning no longer match
|
||||
- **Competitors updated** their version of the same content
|
||||
- **AI search visibility** matters — outdated content gets cited less (see ai-seo skill)
|
||||
|
||||
## Content Refresh Checklist
|
||||
|
||||
1. **Freshness pass** — Update all dates, stats, and examples. Replace "in 2024" with current data. Remove references to deprecated features or tools.
|
||||
2. **Accuracy pass** — Verify all claims are still true. Check that linked resources still exist. Confirm pricing and feature descriptions match current state.
|
||||
3. **Voice pass** — Does the tone match your current brand voice? Older content often reflects an earlier stage of the company.
|
||||
4. **SEO pass** — Has search intent shifted for this topic? Are there new keywords or questions to address? Add "Last updated: [date]" prominently.
|
||||
5. **Proof pass** — Can you add newer testimonials, case studies, or data points that didn't exist when this was first published?
|
||||
6. **Structure pass** — Add comparison tables, FAQ sections, or other scannable formats that make the content easier to consume.
|
||||
|
||||
## Refresh vs. Rewrite
|
||||
|
||||
| Signal | Action |
|
||||
|--------|--------|
|
||||
| Core message still valid, details outdated | Refresh (update facts, stats, examples) |
|
||||
| Brand voice has evolved significantly | Refresh + voice rewrite |
|
||||
| Topic angle or audience has shifted | Full rewrite |
|
||||
| Page structure doesn't match current search intent | Full rewrite |
|
||||
| Just needs updated stats and links | Light refresh |
|
||||
|
||||
## Refresh Cadence
|
||||
|
||||
- **Pricing and product pages**: Every quarter, or when pricing/features change
|
||||
- **High-traffic blog posts**: Every 6 months
|
||||
- **Comparison and alternatives pages**: Every 3-6 months (competitors change fast)
|
||||
- **Evergreen guides**: Annually, unless traffic drops sooner
|
||||
- **Low-traffic pages**: Only when traffic data suggests an opportunity
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: copywriting
|
||||
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," or "CTA copy." For email copy, see email-sequence. For popup copy, see popup-cro.
|
||||
description: When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages, pricing pages, feature pages, about pages, or product pages. Also use when the user says "write copy for," "improve this copy," "rewrite this page," "marketing copy," "headline help," "CTA copy," "value proposition," "tagline," "subheadline," "hero section copy," "above the fold," "this copy is weak," "make this more compelling," or "help me describe my product." Use this whenever someone is working on website text that needs to persuade or convert. For email copy, see emails. For popup copy, see popups. For editing existing copy, see copy-editing. For the offer underneath the copy (bonuses, guarantees, value framing), see offers.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.1
|
||||
---
|
||||
|
||||
# Copywriting
|
||||
@@ -12,7 +12,7 @@ You are an expert conversion copywriter. Your goal is to write marketing copy th
|
||||
## Before Writing
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
@@ -67,7 +67,7 @@ Each section should advance one argument. Build a logical flow down the page.
|
||||
3. **Active over passive** — "We generate reports" not "Reports are generated"
|
||||
4. **Confident over qualified** — Remove "almost," "very," "really"
|
||||
5. **Show over tell** — Describe the outcome instead of using adverbs
|
||||
6. **Honest over sensational** — Never fabricate statistics or testimonials
|
||||
6. **Honest over sensational** — Fabricated statistics or testimonials erode trust and create legal liability
|
||||
|
||||
### Quick Quality Check
|
||||
|
||||
@@ -246,7 +246,7 @@ For headlines and CTAs, provide 2-3 options:
|
||||
## Related Skills
|
||||
|
||||
- **copy-editing**: For polishing existing copy (use after your draft)
|
||||
- **page-cro**: If page structure/strategy needs work, not just copy
|
||||
- **email-sequence**: For email copywriting
|
||||
- **popup-cro**: For popup and modal copy
|
||||
- **ab-test-setup**: To test copy variations
|
||||
- **cro**: If page structure/strategy needs work, not just copy
|
||||
- **emails**: For email copywriting
|
||||
- **popups**: For popup and modal copy
|
||||
- **ab-testing**: To test copy variations
|
||||
|
||||
@@ -0,0 +1,111 @@
|
||||
{
|
||||
"skill_name": "copywriting",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Write homepage copy for a SaaS tool that automates employee onboarding. Target audience is HR directors at mid-size companies (200-2000 employees). Main differentiator is that it integrates with all major HRIS systems and cuts onboarding time from 2 weeks to 2 days.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should write full page copy organized by section: Headline, Subheadline, CTA (above the fold), then Social Proof, Problem/Pain, Solution/Benefits, How It Works, Objection Handling, and Final CTA. Should follow copywriting principles: clarity over cleverness, benefits over features, specificity (use the '2 weeks to 2 days' stat), customer language. Headline should communicate core value proposition. CTAs should be action-oriented ('Start Free Trial' not 'Submit'). Should provide 2-3 headline alternatives with rationale. Should include annotations explaining key copy choices. Should include meta content (SEO page title and meta description).",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Writes full page copy organized by section",
|
||||
"Includes Headline, Subheadline, and CTA above the fold",
|
||||
"Includes Social Proof, Problem/Pain, Solution/Benefits, How It Works sections",
|
||||
"Uses the '2 weeks to 2 days' specificity in copy",
|
||||
"CTAs are action-oriented, not generic",
|
||||
"Provides 2-3 headline alternatives with rationale",
|
||||
"Includes annotations explaining copy choices",
|
||||
"Includes meta content (SEO title and meta description)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Rewrite this headline: 'An Innovative AI-Powered Platform for Streamlined Business Operations' — it's for a B2B SaaS tool that helps small businesses manage invoicing and payments.",
|
||||
"expected_output": "Should identify problems: jargon ('innovative,' 'AI-powered,' 'streamlined,' 'business operations'), too vague, company language not customer language. Should apply copywriting principles — specificity over vagueness, benefits over features, customer language over company language. Should provide 2-3 alternative headlines using formulas like '{Achieve outcome} without {pain point}' or 'The {category} for {audience}'. Each alternative should include rationale. Should also suggest a subheadline that adds specificity.",
|
||||
"assertions": [
|
||||
"Identifies jargon in original headline",
|
||||
"Identifies vagueness as a problem",
|
||||
"Identifies company language vs customer language issue",
|
||||
"Provides 2-3 alternative headlines",
|
||||
"Alternatives use headline formulas from the skill",
|
||||
"Each alternative includes rationale",
|
||||
"Suggests a subheadline"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "i need copy for my pricing page. we have three plans: starter ($29/mo), pro ($79/mo), business ($199/mo). it's a social media scheduling tool for marketers",
|
||||
"expected_output": "Should trigger on the casual phrasing. Should ask or infer audience context. Should apply Pricing Page guidance: help visitors choose the right plan, address 'which is right for me?' anxiety, make recommended plan obvious. Should write plan names, descriptions, feature lists with benefit-oriented copy (not just feature names). Should include a page headline that addresses the pricing decision. CTAs should be specific per plan. Should handle objection handling (FAQ copy). Should provide alternatives for key elements.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Applies Pricing Page guidance",
|
||||
"Addresses 'which plan is right for me' anxiety",
|
||||
"Makes recommended plan obvious",
|
||||
"Writes benefit-oriented feature copy, not just feature names",
|
||||
"Includes page headline",
|
||||
"CTAs are specific per plan",
|
||||
"Includes FAQ or objection handling copy",
|
||||
"Provides alternatives for key elements"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Write copy for our About page. We're a 3-person startup that built a developer tool for database migrations. Founded because we kept losing data during migrations at our last jobs. Tone should be professional but human.",
|
||||
"expected_output": "Should apply About Page guidance: tell the story of why you exist, connect mission to customer benefit, still include a CTA. Should adapt voice and tone to 'professional but human' as specified. Should tell the founder origin story authentically. Should connect the personal pain to the customer's pain. Should include a CTA even on the About page. Copy should follow style rules: active voice, confident, specific. Should NOT be overly corporate or generic.",
|
||||
"assertions": [
|
||||
"Applies About Page guidance",
|
||||
"Tells the story of why the company exists",
|
||||
"Connects mission to customer benefit",
|
||||
"Includes a CTA",
|
||||
"Adapts tone to professional but human",
|
||||
"Uses the founder origin story",
|
||||
"Connects personal pain to customer pain",
|
||||
"Uses active voice",
|
||||
"Avoids corporate jargon"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Can you improve this CTA? We currently have 'Learn More' on our feature page for our analytics dashboard product.",
|
||||
"expected_output": "Should immediately identify 'Learn More' as a weak CTA per the guidelines. Should apply the CTA formula: [Action Verb] + [What They Get] + [Qualifier]. Should provide 2-3 strong alternatives like 'See the Dashboard in Action,' 'Start Your Free Trial,' or 'Explore Analytics Features.' Each alternative should include rationale and context for when it works best. Should also consider CTA hierarchy — whether this is a primary or secondary CTA, and suggest complementary CTAs if relevant.",
|
||||
"assertions": [
|
||||
"Identifies 'Learn More' as a weak CTA",
|
||||
"Applies the CTA formula from the skill",
|
||||
"Provides 2-3 strong alternatives",
|
||||
"Each alternative includes rationale",
|
||||
"Considers CTA hierarchy (primary vs secondary)",
|
||||
"Suggests complementary CTAs"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Write me a 5-email welcome sequence for new trial users of our project management tool.",
|
||||
"expected_output": "Should recognize this is an email copywriting task, not page copywriting. Should defer to or cross-reference the emails skill, which specifically handles email sequences, drip campaigns, and lifecycle emails. May provide brief general guidance but should make clear that emails is the right skill for this task.",
|
||||
"assertions": [
|
||||
"Recognizes this as email sequence work",
|
||||
"References or defers to emails skill",
|
||||
"Does not attempt to write a full email sequence using page copywriting patterns"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "Review this copy and tell me what's wrong: 'We are extremely excited to announce our revolutionary, cutting-edge platform that will totally transform how businesses optimize their workflows! Sign up now!!'",
|
||||
"expected_output": "Should apply the Quick Quality Check. Should identify: exclamation points (remove them), marketing buzzwords without substance ('revolutionary,' 'cutting-edge,' 'totally transform,' 'optimize'), passive/weak constructions ('we are excited to announce'), vague language ('workflows'). Should apply writing style rules: simple over complex, specific over vague, confident over qualified, show over tell. Should rewrite the copy following these principles. Should provide 2-3 alternatives.",
|
||||
"assertions": [
|
||||
"Identifies exclamation point overuse",
|
||||
"Identifies marketing buzzwords without substance",
|
||||
"Identifies vague language",
|
||||
"Applies writing style rules",
|
||||
"Rewrites the copy following principles",
|
||||
"Provides alternatives",
|
||||
"Result is specific, clear, and jargon-free"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,18 +1,18 @@
|
||||
---
|
||||
name: page-cro
|
||||
description: When the user wants to optimize, improve, or increase conversions on any marketing page — including homepage, landing pages, pricing pages, feature pages, or blog posts. Also use when the user says "CRO," "conversion rate optimization," "this page isn't converting," "improve conversions," or "why isn't this page working." For signup/registration flows, see signup-flow-cro. For post-signup activation, see onboarding-cro. For forms outside of signup, see form-cro. For popups/modals, see popup-cro.
|
||||
name: cro
|
||||
description: "When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage, landing pages, pricing pages, feature pages, lead capture forms, or contact forms. Also use when the user says 'CRO,' 'conversion rate optimization,' 'this page isn't converting,' 'improve conversions,' 'why isn't this page working,' 'my landing page sucks,' 'form abandonment,' 'nobody's converting,' 'low conversion rate,' or 'this page needs work.' Use this even if the user just shares a URL and asks for feedback. For signup/registration flows, see signup. For post-signup activation, see onboarding. For popups/modals, see popups."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Page Conversion Rate Optimization (CRO)
|
||||
# Conversion Rate Optimization (CRO)
|
||||
|
||||
You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.
|
||||
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before providing recommendations, identify:
|
||||
|
||||
@@ -175,8 +175,13 @@ When recommending experiments, consider tests for:
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **signup-flow-cro**: If the issue is in the signup process itself
|
||||
- **form-cro**: If forms on the page need optimization
|
||||
- **popup-cro**: If considering popups as part of the strategy
|
||||
- **signup**: If the issue is in the signup process itself
|
||||
- **popups**: If considering popups as part of the strategy
|
||||
- **copywriting**: If the page needs a complete copy rewrite
|
||||
- **ab-test-setup**: To properly test recommended changes
|
||||
- **ab-testing**: To properly test recommended changes
|
||||
|
||||
---
|
||||
|
||||
## Form Optimization
|
||||
|
||||
For detailed form CRO guidance — including field optimization, multi-step forms, error handling, and form-specific experiments — see [references/form.md](references/form.md).
|
||||
@@ -0,0 +1,111 @@
|
||||
{
|
||||
"skill_name": "cro",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Here's my SaaS landing page: https://example.com/product. We get about 5,000 visitors/month from Google Ads but only 1.2% convert to free trial signups. Can you help me figure out what's wrong?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should identify page type (landing page) and conversion goal (free trial signup). Should analyze across the CRO framework dimensions: value proposition clarity, headline effectiveness, CTA placement/copy/hierarchy, visual hierarchy, trust signals, objection handling, and friction points. Should provide recommendations organized as Quick Wins, High-Impact Changes, and Test Ideas. Should note the message match issue between Google Ads and landing page. Should provide 2-3 headline and CTA copy alternatives with rationale.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Identifies page type as landing page",
|
||||
"Identifies conversion goal as free trial signup",
|
||||
"Analyzes value proposition clarity",
|
||||
"Analyzes CTA placement and copy",
|
||||
"Notes message match between ads and landing page",
|
||||
"Output has Quick Wins section",
|
||||
"Output has High-Impact Changes section",
|
||||
"Output has Test Ideas section",
|
||||
"Provides 2-3 headline or CTA alternatives"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Our pricing page has three tiers but nobody picks the middle one. 60% choose the cheapest plan and 30% bounce entirely. What should we change?",
|
||||
"expected_output": "Should apply the Pricing Page CRO framework. Should address plan comparison clarity, recommended plan indication, and 'which plan is right for me?' anxiety. Should analyze whether the middle tier's value proposition is differentiated enough. Should recommend trust signals and social proof near pricing. Should suggest specific experiments like changing plan names, adjusting feature differentiation, adding an annual toggle, or highlighting the recommended plan visually. Output should include Quick Wins, High-Impact Changes, and Test Ideas sections.",
|
||||
"assertions": [
|
||||
"Applies Pricing Page CRO framework",
|
||||
"Addresses recommended plan indication",
|
||||
"Addresses 'which plan is right for me' anxiety",
|
||||
"Analyzes middle tier differentiation",
|
||||
"Suggests specific experiments",
|
||||
"Output has Quick Wins section",
|
||||
"Output has High-Impact Changes section",
|
||||
"Output has Test Ideas section"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "this page isn't converting. can you take a look? it's our homepage for a B2B project management tool",
|
||||
"expected_output": "Should trigger on the casual 'this page isn't converting' phrasing. Should identify this as a Homepage CRO analysis. Should ask clarifying questions about current conversion rate, traffic sources, and conversion goal. Should apply the full CRO Analysis Framework starting with value proposition clarity. Should address the homepage-specific guidance: serving multiple audiences, leading with broadest value prop, and providing clear paths for different visitor intents. Should provide structured output with Quick Wins, High-Impact Changes, Test Ideas, and Copy Alternatives.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Identifies as Homepage CRO",
|
||||
"Asks about current conversion rate",
|
||||
"Asks about traffic sources",
|
||||
"Applies CRO Analysis Framework",
|
||||
"Addresses serving multiple audiences",
|
||||
"Addresses clear paths for different visitor intents",
|
||||
"Output has structured sections"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "We have a blog that gets 20k organic visits/month but almost nobody clicks through to our product. How do we get more conversions from blog readers?",
|
||||
"expected_output": "Should apply the Blog Post CRO framework. Should recommend contextual CTAs matching content topics and inline CTAs at natural stopping points. Should analyze whether CTAs are relevant to the content topic or generic. Should suggest specific CTA placements: within content, end of post, sidebar, sticky bar. Should recommend testing different CTA formats (inline text links, banner cards, exit-intent). Should cross-reference copywriting skill for CTA copy improvement.",
|
||||
"assertions": [
|
||||
"Applies Blog Post CRO framework",
|
||||
"Recommends contextual CTAs matching content",
|
||||
"Recommends inline CTAs at natural stopping points",
|
||||
"Suggests specific CTA placements",
|
||||
"Suggests testing different CTA formats",
|
||||
"Cross-references copywriting or related skill"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We redesigned our landing page and conversions dropped from 4.2% to 2.8%. Here's the new page. What went wrong?",
|
||||
"expected_output": "Should approach this as a diagnostic CRO audit focused on what changed. Should systematically compare against the CRO framework dimensions to identify likely regression causes. Should check for common redesign mistakes: losing trust signals, weaker value proposition clarity, CTA hierarchy changes, added friction, broken message match with traffic sources. Should provide specific fixes organized by likely impact. Should recommend reverting high-risk changes while testing others.",
|
||||
"assertions": [
|
||||
"Approaches as diagnostic audit",
|
||||
"Checks for lost trust signals",
|
||||
"Checks for weakened value proposition",
|
||||
"Checks for CTA hierarchy changes",
|
||||
"Checks for added friction",
|
||||
"Checks for broken message match with traffic sources",
|
||||
"Provides fixes organized by impact",
|
||||
"Recommends reverting high-risk changes"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Our signup form has too many fields and people keep abandoning it halfway through. Can you help optimize it?",
|
||||
"expected_output": "Should recognize this is about signup form optimization, not general page CRO. Should defer to or cross-reference the signup skill, which specifically handles signup, registration, and account creation flows. May provide some general friction reduction advice but should make clear that signup is the right skill for this task.",
|
||||
"assertions": [
|
||||
"Recognizes this as signup flow optimization",
|
||||
"References or defers to signup skill",
|
||||
"Does not attempt full cro analysis on a form"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "Review this feature page for our API monitoring tool. Most traffic comes from organic search for 'API monitoring tools'. We want them to start a free trial.",
|
||||
"expected_output": "Should apply the Feature Page CRO framework: connect feature to benefit, show use cases and examples, clear path to try/buy. Should reference the experiments section and suggest prioritized test ideas for hero section, trust signals, and CTA variations. Should note the organic search traffic source and check for message match with search intent. Should cross-reference ab-testing skill for proper test implementation.",
|
||||
"assertions": [
|
||||
"Applies Feature Page CRO framework",
|
||||
"Connects features to benefits",
|
||||
"Suggests use cases and examples",
|
||||
"Provides clear path to try/buy",
|
||||
"Notes organic traffic source and search intent match",
|
||||
"Suggests specific experiment hypotheses",
|
||||
"Cross-references ab-testing skill"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,10 +1,3 @@
|
||||
---
|
||||
name: form-cro
|
||||
description: When the user wants to optimize any form that is NOT signup/registration — including lead capture forms, contact forms, demo request forms, application forms, survey forms, or checkout forms. Also use when the user mentions "form optimization," "lead form conversions," "form friction," "form fields," "form completion rate," or "contact form." For signup/registration forms, see signup-flow-cro. For popups containing forms, see popup-cro.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Form CRO
|
||||
|
||||
You are an expert in form optimization. Your goal is to maximize form completion rates while capturing the data that matters.
|
||||
@@ -12,7 +5,7 @@ You are an expert in form optimization. Your goal is to maximize form completion
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before providing recommendations, identify:
|
||||
|
||||
@@ -120,7 +113,7 @@ For each field, ask:
|
||||
4. Logical grouping if many fields
|
||||
|
||||
### Labels and Placeholders
|
||||
- Labels: Always visible (not just placeholder)
|
||||
- Labels: Keep visible (not just placeholder) — placeholders disappear when typing, leaving users unsure what they're filling in
|
||||
- Placeholders: Examples, not labels
|
||||
- Help text: Only when genuinely helpful
|
||||
|
||||
@@ -423,7 +416,7 @@ Ideas to A/B test with expected outcomes
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **signup-flow-cro**: For account creation forms
|
||||
- **popup-cro**: For forms inside popups/modals
|
||||
- **page-cro**: For the page containing the form
|
||||
- **ab-test-setup**: For testing form changes
|
||||
- **signup**: For account creation forms
|
||||
- **popups**: For forms inside popups/modals
|
||||
- **cro**: For the page containing the form
|
||||
- **ab-testing**: For testing form changes
|
||||
@@ -0,0 +1,272 @@
|
||||
---
|
||||
name: customer-research
|
||||
description: When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer research," "ICP research," "talk to customers," "analyze transcripts," "customer interviews," "survey analysis," "support ticket analysis," "voice of customer," "VOC," "build personas," "customer personas," "jobs to be done," "JTBD," "what do customers say," "what are customers struggling with," "Reddit mining," "G2 reviews," "review mining," "digital watering holes," "community research," "forum research," "competitor reviews," "customer sentiment," or "find out why customers churn/convert/buy." Use for both analyzing existing research assets AND gathering new research from online sources. For writing copy informed by research, see copywriting. For acting on research to improve pages, see cro.
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Customer Research
|
||||
|
||||
You are an expert customer researcher. Your goal is to help uncover what customers actually think, feel, say, and struggle with — so that everything from positioning to product to copy is grounded in reality rather than assumption.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context to skip questions already answered.
|
||||
|
||||
---
|
||||
|
||||
## Two Modes of Research
|
||||
|
||||
### Mode 1: Analyze Existing Assets
|
||||
You have raw research material (transcripts, surveys, reviews, tickets). Your job is to extract signal.
|
||||
|
||||
### Mode 2: Go Find Research
|
||||
You need to gather intel from online sources (Reddit, G2, forums, communities, review sites). Your job is to know where to look and what to extract.
|
||||
|
||||
Most engagements combine both. Establish which mode applies before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Mode 1: Analyzing Existing Research Assets
|
||||
|
||||
### Asset Types
|
||||
|
||||
**Customer interview / sales call transcripts**
|
||||
- Extract: pains, triggers, desired outcomes, language used, objections, alternatives considered
|
||||
- Look for: the moment they decided to look for a solution, what they tried before, what success looks like to them
|
||||
|
||||
**Survey results**
|
||||
- Segment responses by customer tier, use case, or tenure before drawing conclusions
|
||||
- Flag: what open-ended answers say vs. what multiple-choice answers say (they often conflict)
|
||||
- Identify: the 20% of responses that contain the most useful signal
|
||||
|
||||
**Customer support conversations**
|
||||
- Mine for: recurring complaints, confusion points, feature requests, and "I wish it could…" language
|
||||
- Categorize tickets before analyzing — don't treat all tickets as equal signal
|
||||
- Separate bugs from confusion from missing features from expectation mismatches
|
||||
|
||||
**Win/loss interviews and churned customer notes**
|
||||
- Wins: what tipped the decision? What almost made them choose a competitor?
|
||||
- Losses and churn: was it price, features, fit, timing, or something else?
|
||||
- Segment by reason — don't average across different churn causes
|
||||
|
||||
**NPS responses**
|
||||
- Passives and detractors are higher signal than promoters for improvement work
|
||||
- Pair scores with verbatims — a 9 with a specific complaint beats a 10 with no comment
|
||||
|
||||
### Extraction Framework
|
||||
|
||||
For each asset, extract:
|
||||
|
||||
1. **Jobs to Be Done** — what outcome is the customer trying to achieve?
|
||||
- Functional job: the task itself
|
||||
- Emotional job: how they want to feel
|
||||
- Social job: how they want to be perceived
|
||||
|
||||
2. **Pain Points** — what's frustrating, broken, or inadequate about their current situation?
|
||||
- Prioritize pains mentioned unprompted and with emotional language
|
||||
|
||||
3. **Trigger Events** — what changed that made them seek a solution?
|
||||
- Common triggers: team growth, new hire, missed target, embarrassing incident, competitor doing something
|
||||
|
||||
4. **Desired Outcomes** — what does success look like in their words?
|
||||
- Capture exact quotes, not paraphrases
|
||||
|
||||
5. **Language and Vocabulary** — exact words and phrases customers use
|
||||
- This is gold for copy. "We were drowning in spreadsheets" > "manual process inefficiency"
|
||||
|
||||
6. **Alternatives Considered** — what else did they look at or try?
|
||||
- Includes doing nothing, hiring someone, or building internally
|
||||
|
||||
### Synthesis Steps
|
||||
|
||||
After extracting from individual assets:
|
||||
|
||||
1. **Cluster by theme** — group similar pains, outcomes, and triggers across assets
|
||||
2. **Frequency + intensity scoring** — how often does a theme appear, and how strongly is it felt?
|
||||
3. **Segment by customer profile** — do patterns differ by company size, role, use case, or tenure?
|
||||
4. **Identify the "money quotes"** — 5-10 verbatim quotes that best represent each theme
|
||||
5. **Flag contradictions** — where do customers say one thing but do another?
|
||||
|
||||
### Research Quality Guardrails
|
||||
|
||||
Label every insight with a confidence level before presenting it:
|
||||
|
||||
| Confidence | Criteria |
|
||||
|------------|----------|
|
||||
| **High** | Theme appears in 3+ independent sources; mentioned unprompted; consistent across segments |
|
||||
| **Medium** | Theme appears in 2 sources, or only prompted, or limited to one segment |
|
||||
| **Low** | Single source; could be an outlier; needs validation |
|
||||
|
||||
**Recency window**: Weight sources from the last 12 months more heavily. Markets shift — a 3-year-old transcript may reflect a different product and buyer.
|
||||
|
||||
**Sample bias checks**:
|
||||
- Online reviewers skew toward power users and people with strong opinions
|
||||
- Support tickets skew toward problems, not value
|
||||
- Reddit skews technical and skeptical vs. mainstream buyers
|
||||
- Factor this in when drawing conclusions about "all customers"
|
||||
|
||||
**Minimum viable sample**: Don't build personas or draw messaging conclusions from fewer than 5 independent data points per segment.
|
||||
|
||||
---
|
||||
|
||||
## Mode 2: Digital Watering Hole Research
|
||||
|
||||
Online communities are where customers speak without a filter. The goal is to find authentic, unmoderated language about the problem space.
|
||||
|
||||
### Where to Look
|
||||
|
||||
Choose sources based on your ICP type — then read `references/source-guides.md` for detailed playbooks, search operators, and per-platform extraction tips.
|
||||
|
||||
| ICP Type | Primary Sources |
|
||||
|----------|----------------|
|
||||
| B2B SaaS / technical buyers | Reddit (role-specific subs), G2/Capterra, Hacker News, LinkedIn, Indie Hackers, SparkToro |
|
||||
| SMB / founders | Reddit (r/entrepreneur, r/smallbusiness), Indie Hackers, Product Hunt, Facebook Groups, SparkToro |
|
||||
| Developer / DevOps | r/devops, r/programming, Hacker News, Stack Overflow, Discord servers |
|
||||
| B2C / consumer | App store reviews (1-3 star), Reddit hobby/lifestyle subs, YouTube comments, TikTok/Instagram comments |
|
||||
| Enterprise | LinkedIn, industry analyst reports, G2 Enterprise filter, job postings, SparkToro |
|
||||
|
||||
**Quick decision guide:**
|
||||
- Have a product category? → Start with G2/Capterra reviews (yours + competitors)
|
||||
- Need to know where your audience spends time? → SparkToro (reveals podcasts, YouTube, subreddits, websites, social accounts)
|
||||
- Need raw language? → Reddit and YouTube comments
|
||||
- Need trigger events? → LinkedIn posts, job postings, Hacker News "Ask HN" threads
|
||||
- Need competitive intel? → Competitor 4-star reviews on G2; Product Hunt discussions; SparkToro competitor audience analysis
|
||||
|
||||
### What to Extract from Each Source
|
||||
|
||||
For every piece of content you find:
|
||||
|
||||
| Field | What to Capture |
|
||||
|-------|----------------|
|
||||
| Source | Platform, thread URL, date |
|
||||
| Verbatim quote | Exact words — don't paraphrase |
|
||||
| Context | What prompted the comment? |
|
||||
| Sentiment | Positive / negative / neutral / frustrated |
|
||||
| Theme tag | Pain / trigger / outcome / alternative / language |
|
||||
| Customer profile signals | Role, company size, industry hints from the post |
|
||||
|
||||
### Research Synthesis Template
|
||||
|
||||
After gathering from multiple sources, synthesize into:
|
||||
|
||||
```
|
||||
## Top Themes (ranked by frequency × intensity)
|
||||
|
||||
### Theme 1: [Name]
|
||||
**Summary**: [1-2 sentences]
|
||||
**Frequency**: Appeared in X of Y sources
|
||||
**Intensity**: High / Medium / Low (based on emotional language used)
|
||||
**Representative quotes**:
|
||||
- "[exact quote]" — [source, date]
|
||||
- "[exact quote]" — [source, date]
|
||||
**Implications**: What this means for messaging / product / positioning
|
||||
|
||||
### Theme 2: ...
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Persona Generation
|
||||
|
||||
Personas should be built from research, not invented. Don't create a persona until you have at least 5-10 data points (interviews, reviews, or community posts) from a consistent segment.
|
||||
|
||||
### Persona Structure
|
||||
|
||||
```
|
||||
## [Persona Name] — [Role/Title]
|
||||
|
||||
**Profile**
|
||||
- Title range: [e.g., "Marketing Manager to VP of Marketing"]
|
||||
- Company size: [e.g., "50–500 employees, Series A–C SaaS"]
|
||||
- Industry: [if narrow]
|
||||
- Reports to: [who]
|
||||
- Team size managed: [if relevant]
|
||||
|
||||
**Primary Job to Be Done**
|
||||
[One sentence: what outcome are they trying to achieve in their role?]
|
||||
|
||||
**Trigger Events**
|
||||
What causes them to start looking for a solution like yours?
|
||||
- [trigger 1]
|
||||
- [trigger 2]
|
||||
|
||||
**Top Pains**
|
||||
1. [Pain — in their words if possible]
|
||||
2. [Pain]
|
||||
3. [Pain]
|
||||
|
||||
**Desired Outcomes**
|
||||
- [What success looks like to them]
|
||||
- [How they measure it]
|
||||
- [How it makes them look to their boss/team]
|
||||
|
||||
**Objections and Fears**
|
||||
- [What makes them hesitate to buy or switch]
|
||||
|
||||
**Alternatives They Consider**
|
||||
- [Competitor, DIY, do nothing, hire someone]
|
||||
|
||||
**Key Vocabulary**
|
||||
Words and phrases they actually use (sourced from research):
|
||||
- "[phrase]"
|
||||
- "[phrase]"
|
||||
|
||||
**How to Reach Them**
|
||||
- Channels: [where they spend time]
|
||||
- Content they consume: [formats, topics]
|
||||
- Influencers/communities they trust: [specific names if known]
|
||||
```
|
||||
|
||||
### Persona Anti-Patterns
|
||||
|
||||
- **Don't name them cutely** ("Marketing Mary") unless your team finds it helpful — it's often a distraction
|
||||
- **Don't average across segments** — a persona that represents everyone represents no one
|
||||
- **Don't invent details** — if you don't have data on something, leave it blank rather than filling it in
|
||||
- **Revisit quarterly** — personas decay as your market and product evolve
|
||||
|
||||
---
|
||||
|
||||
## Deliverable Formats
|
||||
|
||||
Depending on what the user needs, offer:
|
||||
|
||||
1. **Research synthesis report** — themes, quotes, patterns, and implications
|
||||
2. **VOC quote bank** — organized verbatim quotes by theme, for use in copy
|
||||
3. **Persona document** — 1-3 personas built from the research
|
||||
4. **Jobs-to-be-done map** — functional, emotional, and social jobs by segment
|
||||
5. **Competitive intelligence summary** — what customers say about competitors vs. you
|
||||
6. **Research gap analysis** — what you still don't know and how to find it
|
||||
|
||||
Ask the user which deliverable(s) they need before generating output.
|
||||
|
||||
---
|
||||
|
||||
## Questions to Ask Before Proceeding
|
||||
|
||||
If context is unclear:
|
||||
|
||||
1. **What's the goal?** Improve messaging? Build personas? Find product gaps? Understand churn?
|
||||
2. **What do you already have?** (transcripts, surveys, tickets, G2 reviews, nothing)
|
||||
3. **Who is the target segment?** (all customers, a specific tier, churned users, prospects who didn't buy)
|
||||
4. **What's your product?** (if not in the product marketing context file)
|
||||
5. **What do you want delivered?** (synthesis report, persona, quote bank, competitive intel)
|
||||
|
||||
Don't ask all five at once — lead with #1 and #2, then follow up as needed.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
| When to hand off | Skill |
|
||||
|-----------------|-------|
|
||||
| Writing copy informed by the research | `copywriting` |
|
||||
| Optimizing a page using VOC insights | `cro` |
|
||||
| Building a competitor comparison page | `competitors` |
|
||||
| Creating a churn prevention strategy from churn research | `churn-prevention` |
|
||||
| Planning paid ads informed by research | `ads` |
|
||||
| Writing cold email using research on pain/trigger | `cold-email` |
|
||||
| Translating customer research into an ICP for outbound | `prospecting` |
|
||||
| Planning content based on discovered topics | `content-strategy` |
|
||||
| Rolling research into a comprehensive marketing plan | `marketing-plan` |
|
||||
@@ -0,0 +1,162 @@
|
||||
{
|
||||
"skill_name": "customer-research",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "I have 20 customer interview transcripts. Help me analyze them.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should ask about the goal before analyzing (improve messaging, build personas, find product gaps, etc.). Should apply the extraction framework: jobs to be done, pain points, trigger events, desired outcomes, language/vocabulary, alternatives considered. Should recommend clustering by theme, frequency + intensity scoring, and identifying money quotes. Should ask which deliverable is needed.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Asks about the goal before diving in (improve messaging, build personas, find gaps, etc.)",
|
||||
"Mentions extracting jobs to be done, pain points, and desired outcomes",
|
||||
"Suggests organizing quotes by theme",
|
||||
"References frequency and intensity scoring",
|
||||
"Asks which deliverable is needed"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "I want to do ICP research but I don't have any customer interviews yet.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should recommend digital watering hole research as a starting point. Should mention Reddit, G2, Capterra, forums, or niche communities as sources. Should offer to plan a research approach and explain what to extract from online sources. Should note this is Mode 2 and ask what product/category to research.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends digital watering hole research as an alternative",
|
||||
"Mentions Reddit, G2, or review sites as starting points",
|
||||
"Asks what product or category to research",
|
||||
"Offers to help extract insights from online sources"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Mine Reddit and G2 to understand what people hate about project management software.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should identify relevant subreddits (r/projectmanagement, r/productivity, r/agile) and search strategies. Should recommend reading 3-star and 1-star G2 reviews and competitor 4-star reviews. Should plan to extract verbatim quotes, pain themes, and switching triggers. Should apply the extraction table (source, quote, context, sentiment, theme tag, profile signals).",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Identifies relevant subreddits or search strategies for project management",
|
||||
"Suggests reading 3-star and 1-star G2 reviews",
|
||||
"Recommends competitor 4-star reviews for buried complaints",
|
||||
"Plans to extract verbatim quotes and pain themes",
|
||||
"Mentions what to look for: complaints, workarounds, switching triggers"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Build me a customer persona for a marketing manager at a B2B SaaS company.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should ask if there is existing research to build from before generating a persona. Should warn against inventing details without data. Should use the persona structure: profile, primary JTBD, trigger events, top pains, desired outcomes, objections, alternatives, key vocabulary, how to reach them. Should note that personas should be built from at least 5-10 data points.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Asks if there is existing research to build from before inventing details",
|
||||
"Warns against creating personas without data",
|
||||
"Includes jobs to be done, pains, triggers, and desired outcomes in persona structure",
|
||||
"Mentions the need to capture actual customer vocabulary",
|
||||
"Notes minimum data threshold (5-10 data points)"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "I have 6 months of customer support tickets. What insights can I pull from them?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should recommend categorizing tickets before analyzing (bugs vs. confusion vs. feature requests vs. expectation mismatches). Should warn against treating all tickets as equal signal. Should suggest extracting recurring language, patterns, and 'I wish it could…' phrases. Should ask about the goal — product improvement, messaging, reducing support load, or something else.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends categorizing tickets before analyzing (bugs vs confusion vs feature requests)",
|
||||
"Warns against treating all tickets as equal signal",
|
||||
"Mentions extracting recurring language and patterns",
|
||||
"Asks about the goal — product improvement, messaging, or something else"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "What are customers saying about my competitors on review sites?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should ask which competitors to research. Should recommend G2 and Capterra as primary sources. Should specifically call out reading competitor 4-star reviews for buried complaints. Should describe what to extract: what they love (battlecard intel), what frustrates them (opportunities), unmet needs. Should use the review mining template.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends reading competitor 4-star reviews specifically for buried complaints",
|
||||
"Mentions G2 or Capterra as sources",
|
||||
"Describes what to extract: what they love, what frustrates them, unmet needs",
|
||||
"Frames as competitive intelligence input"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 7,
|
||||
"prompt": "Help me do voice of customer research for a new SaaS in the HR space.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should ask about the specific ICP segment within HR (recruiter, HR generalist, CHRO, etc.). Should suggest relevant digital watering holes: r/humanresources, r/recruiting, HR Slack communities, G2 HR category, LinkedIn. Should plan to extract verbatim language for copy use. Should offer to produce a VOC quote bank as a deliverable.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Asks about target ICP segment within HR",
|
||||
"Suggests relevant digital watering holes (subreddits, G2 categories, communities)",
|
||||
"Plans to extract verbatim language for copy use",
|
||||
"Mentions organizing findings into a VOC quote bank"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 8,
|
||||
"prompt": "I want to understand why customers churn. I have exit survey results.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should recommend segmenting churn reasons before analyzing — do not average across different causes. Should suggest pairing open-ended responses with quantitative data. Should ask if win/loss interview data or support tickets are also available. Should apply confidence labels (high/med/low) based on sample size and source consistency.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends segmenting churn reasons before analyzing",
|
||||
"Warns against averaging across different churn causes",
|
||||
"Suggests pairing open-ended responses with quantitative data",
|
||||
"Asks if win/loss interview data is also available"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 9,
|
||||
"prompt": "Find the digital watering holes where DevOps engineers talk shop.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should identify specific relevant communities: r/devops, r/sysadmin, Hacker News, DevOps-focused Discord/Slack groups, LinkedIn, Stack Overflow. Should suggest what to search for in those communities. Should describe what signal to extract from each source type and reference source-guides.md for detailed playbooks.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Mentions specific relevant communities (r/devops, Hacker News, LinkedIn, Discord)",
|
||||
"Suggests what to search for in those communities",
|
||||
"Describes what signal to extract from each source type"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 10,
|
||||
"prompt": "Turn my customer research into messaging I can use on my homepage.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should extract VOC language and top themes before moving to copy. Should identify the highest-signal quotes and language patterns. Should produce a VOC summary or quote bank, then hand off to the copywriting skill for the actual copy writing step rather than writing homepage copy directly.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Extracts the VOC language and themes first before jumping to copy",
|
||||
"Identifies the highest-signal quotes for messaging",
|
||||
"References the copywriting skill for the actual copy writing step"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 11,
|
||||
"prompt": "I run a mobile fitness app and want to understand why users drop off after week 2.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should recognize this as a B2C research scenario. Should suggest B2C-appropriate sources: app store reviews (1-3 star), Reddit fitness communities, YouTube comment sections on fitness apps, TikTok/Instagram comments. Should also recommend in-app surveys and analyzing support tickets/reviews. Should frame around activation and habit formation research.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recognizes this as a B2C research scenario",
|
||||
"Suggests app store reviews as a primary source",
|
||||
"Mentions Reddit or community sources relevant to fitness/consumer apps",
|
||||
"Frames around understanding drop-off triggers and desired outcomes"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 12,
|
||||
"prompt": "I have no existing research and don't know who my best customers are yet.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should treat this as a bootstrap research scenario. Should recommend starting with hypothesis formation before gathering data. Should suggest a minimum viable research plan: 5-10 customer interviews + digital watering hole scan. Should provide interview recruiting tips and what questions to ask. Should warn against building personas before collecting any data.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recognizes this as a zero-research bootstrap scenario",
|
||||
"Recommends forming hypotheses before gathering data",
|
||||
"Suggests a minimum viable research plan (interviews + online sources)",
|
||||
"Warns against building personas without any data"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,401 @@
|
||||
# Customer Research — Source Guides
|
||||
|
||||
Detailed, source-by-source playbooks for gathering customer intelligence from online watering holes.
|
||||
|
||||
---
|
||||
|
||||
## Reddit Research
|
||||
|
||||
### Finding the Right Subreddits
|
||||
|
||||
Start by identifying where your ICP spends time, not where your product is discussed.
|
||||
|
||||
**Discovery methods:**
|
||||
- Search `site:reddit.com "[job title] tools"` or `site:reddit.com "[problem category] software"`
|
||||
- Use [subreddit search tools](https://www.reddit.com/subreddits/search) with problem-space keywords
|
||||
- Look at what subreddits show up in Google results when you search ICP problems
|
||||
- Check what subreddits competitors' customers mention in reviews
|
||||
|
||||
**Common high-value subreddits by category:**
|
||||
- B2B SaaS: r/sales, r/marketing, r/entrepreneur, r/startups, r/smallbusiness
|
||||
- Dev tools: r/programming, r/devops, r/webdev, r/cscareerquestions
|
||||
- Analytics/data: r/analytics, r/dataengineering, r/BusinessIntelligence
|
||||
- Marketing: r/PPC, r/SEO, r/emailmarketing, r/content_marketing
|
||||
- HR/recruiting: r/recruiting, r/humanresources, r/jobs
|
||||
- Finance/ops: r/accounting, r/financialplanning, r/projectmanagement
|
||||
|
||||
### Search Operators
|
||||
|
||||
```
|
||||
site:reddit.com/r/[subreddit] "[keyword]"
|
||||
site:reddit.com "[problem]" "recommend" OR "suggestion" OR "alternative"
|
||||
site:reddit.com "[competitor name]" "vs" OR "alternative" OR "switched"
|
||||
```
|
||||
|
||||
### What to Look For
|
||||
|
||||
**High-signal post types:**
|
||||
- "What tools do you use for X?" → reveals alternatives and vocab
|
||||
- "Frustrated with [competitor], looking for alternatives" → reveals pain and switching triggers
|
||||
- "How do you handle X?" → reveals workflow and workarounds
|
||||
- "Is [your category] worth it?" → reveals objections and evaluation criteria
|
||||
- Complaint threads about competitors → reveals gaps you might fill
|
||||
|
||||
**What to extract:**
|
||||
- The exact problem described in the post
|
||||
- Top-voted solutions (what do practitioners actually recommend?)
|
||||
- Complaints about existing solutions in comments
|
||||
- The language used — note specific words and phrases
|
||||
- Upvote patterns — consensus vs. controversy
|
||||
|
||||
### Tools
|
||||
- Reddit's native search (limited but fast)
|
||||
- Google: `site:reddit.com [query]` (better results)
|
||||
- Pullpush.io — search archived Reddit posts (good for older threads)
|
||||
|
||||
---
|
||||
|
||||
## G2 and Review Site Mining
|
||||
|
||||
### Your Own Product Reviews
|
||||
|
||||
Read in this order for maximum signal:
|
||||
|
||||
1. **3-star reviews** — these are the most honest. Customer liked it enough to stay but felt something was missing.
|
||||
2. **1-star reviews** — understand the failure modes. Separate product issues from support/onboarding issues.
|
||||
3. **5-star reviews** — extract the "what they love" language. These are your proof points.
|
||||
4. **4-star reviews** — often contain "the only thing I wish…" buried in praise.
|
||||
|
||||
**What to extract:**
|
||||
- What they say they use it *for* (the job to be done)
|
||||
- What they say is hardest or most frustrating
|
||||
- What they compare it to ("coming from [X]", "better than [Y]")
|
||||
- Industry and role signals in reviewer profiles
|
||||
|
||||
### Competitor Reviews on G2
|
||||
|
||||
The 4-star competitor reviews are gold — customers who like the product but still have complaints.
|
||||
|
||||
**G2 structure to exploit:**
|
||||
- "What do you like best?" → their strengths (your battlecard intel)
|
||||
- "What do you dislike?" → their weaknesses (your opportunities)
|
||||
- "What problems are you solving?" → the job to be done
|
||||
|
||||
**Capterra** has similar structure. **Trustpilot** skews B2C. **AppSumo** reviews are useful for SMB/prosumer SaaS.
|
||||
|
||||
### Review Mining Template
|
||||
|
||||
For each competitor's 4-star reviews, extract:
|
||||
|
||||
| Category | Notes |
|
||||
|----------|-------|
|
||||
| Job to be done | Why do they use the product? |
|
||||
| Top praise | What do they love (and might be hard for you to match)? |
|
||||
| Top complaint | What frustrates them? |
|
||||
| Switching context | Did they mention switching from something else? |
|
||||
| Unmet need | "I wish it could…" or "It would be better if…" |
|
||||
|
||||
---
|
||||
|
||||
## Indie Hackers and Product Hunt
|
||||
|
||||
### Indie Hackers
|
||||
|
||||
Strong signal for founder/builder/SMB ICP.
|
||||
|
||||
**Where to look:**
|
||||
- "Ask IH" posts: questions about problems your product solves
|
||||
- Milestone posts: when founders describe their stack, they reveal tool preferences and pain
|
||||
- Comment threads on product launches in your category
|
||||
|
||||
**Search:** `site:indiehackers.com "[problem]"` or use IH's native search.
|
||||
|
||||
### Product Hunt
|
||||
|
||||
**Discussion tabs** on competing products are a research goldmine:
|
||||
- Questions asked = pre-sales concerns = objections
|
||||
- Comments = early adopter reactions = leading indicators of reception
|
||||
- "Alternatives to X" collections reveal the competitive landscape as users see it
|
||||
|
||||
---
|
||||
|
||||
## Hacker News
|
||||
|
||||
Strong signal for technical/developer ICP. Skews toward builders and skeptics.
|
||||
|
||||
**High-value searches:**
|
||||
- `site:news.ycombinator.com "[competitor or category]"`
|
||||
- HN "Ask HN: best tools for X" threads
|
||||
- "Show HN" posts for competitors — read the skeptical comments
|
||||
|
||||
**What's different about HN:**
|
||||
- Users are more likely to critique underlying architecture and business model
|
||||
- Strong opinions about pricing models (especially anything subscription-based)
|
||||
- First principles objections you might not hear elsewhere
|
||||
|
||||
---
|
||||
|
||||
## LinkedIn Research
|
||||
|
||||
### Posts and Comments
|
||||
|
||||
Search for posts by practitioners describing their workflows:
|
||||
- "[Role] at [company size]" + problem keyword
|
||||
- "We used to [old way] but now we [new way]" stories
|
||||
- Posts asking for tool recommendations get comments from active buyers
|
||||
|
||||
### Job Postings
|
||||
|
||||
A job posting is a company's admission of a pain point.
|
||||
|
||||
**What to look for:**
|
||||
- What tools are listed as "nice to have" vs. "required"? (reveals stack and adjacent tools)
|
||||
- What metrics and outcomes are mentioned in the role description?
|
||||
- What does the role spend most of its time doing? (reveals the job to be done)
|
||||
|
||||
**Search:** `site:linkedin.com/jobs "[role title]" "[relevant tool or category]"`
|
||||
|
||||
---
|
||||
|
||||
## YouTube Comments
|
||||
|
||||
### Finding High-Signal Videos
|
||||
|
||||
- Tutorial videos for problems your product solves
|
||||
- "Best tools for X in [year]" roundup videos
|
||||
- Competitor product demos and walkthroughs
|
||||
|
||||
**What to look for in comments:**
|
||||
- "Does this work for [specific use case]?" → edge cases and unmet needs
|
||||
- "I tried this but…" → failure points
|
||||
- "What about [competitor]?" → active evaluation
|
||||
- Timestamps with questions → confusion points in the workflow
|
||||
|
||||
---
|
||||
|
||||
## Twitter / X Research
|
||||
|
||||
### Search Operators
|
||||
|
||||
```
|
||||
"[competitor]" -filter:replies min_faves:10
|
||||
"[problem keyword]" "anyone know" OR "recommend" OR "alternative"
|
||||
"[category] is broken" OR "frustrated with [category]"
|
||||
```
|
||||
|
||||
### What to Find
|
||||
|
||||
- Real-time complaints about competitors
|
||||
- Practitioners discussing their stack
|
||||
- Influencers/thought leaders your ICP follows (useful for distribution)
|
||||
|
||||
---
|
||||
|
||||
## Blog Post and Forum Research
|
||||
|
||||
### Comparison Content
|
||||
|
||||
Google: `"[competitor 1] vs [competitor 2]"` or `"best [category] software [year]"`
|
||||
|
||||
Read the comments on these posts — people who find comparison content are actively evaluating. Their comments are questions your sales process should answer.
|
||||
|
||||
### Niche Communities
|
||||
|
||||
- **Slack communities**: Many industries have public or semi-public Slack groups. Search "[industry] Slack community".
|
||||
- **Discord servers**: Growing for developer and creator communities.
|
||||
- **Facebook Groups**: Still strong for SMB, e-commerce, agency, and coach/consultant ICP.
|
||||
- **Circle/Mighty Networks communities**: Check if there are paid communities in your ICP's space.
|
||||
|
||||
---
|
||||
|
||||
## B2C and Consumer App Research
|
||||
|
||||
B2C research requires different sources than B2B SaaS. Consumer buyers don't congregate on LinkedIn or G2 — they leave traces in app stores, social media, and communities built around the activity your product serves.
|
||||
|
||||
### App Store Reviews (iOS App Store / Google Play)
|
||||
|
||||
One of the richest unfiltered sources for mobile/consumer products.
|
||||
|
||||
**Read in this order:**
|
||||
1. **1-2 star reviews** — failure modes, unmet expectations, frustration peaks
|
||||
2. **3-star reviews** — honest tradeoffs and "it's good but…" feedback
|
||||
3. **5-star reviews** — what they love in their own words (proof points and positioning)
|
||||
|
||||
**What to extract:**
|
||||
- What job they hired the app to do ("I use this to…")
|
||||
- The moment it stopped working for them
|
||||
- What they compared it to or switched from
|
||||
- Emotional language — "I love how…", "I'm so frustrated that…"
|
||||
|
||||
**Search tip:** Sort by "Most Recent" to get fresh signal, then "Most Critical" for pain themes.
|
||||
|
||||
### Amazon Reviews (for physical products or software with Amazon presence)
|
||||
|
||||
Same priority order as app stores: 3-star reviews first.
|
||||
|
||||
**G2 analog for consumer SaaS**: Trustpilot, Sitejabber, and product-specific review aggregators.
|
||||
|
||||
### Reddit Consumer Communities
|
||||
|
||||
B2C Reddit is highly vertical — go to the hobby/lifestyle subreddit, not the general ones.
|
||||
|
||||
**Examples by product type:**
|
||||
- Fitness apps: r/running, r/loseit, r/fitness, r/MyFitnessPal
|
||||
- Personal finance: r/personalfinance, r/financialindependence, r/ynab
|
||||
- Productivity/notes: r/productivity, r/Notion, r/ObsidianMD
|
||||
- Travel: r/travel, r/solotravel, r/digitalnomad
|
||||
- Parenting: r/Parenting, r/beyondthebump, r/daddit
|
||||
|
||||
**Search pattern:** `site:reddit.com/r/[community] "[app name OR problem]"`
|
||||
|
||||
### TikTok and Instagram Comments
|
||||
|
||||
High-signal for consumer products with visual/lifestyle appeal.
|
||||
|
||||
**How to find signal:**
|
||||
- Search TikTok for "[product name] review" or "is [product] worth it"
|
||||
- Watch the top 5-10 videos; read ALL comments — not just likes
|
||||
- On Instagram, check tagged posts from real users (not brand posts)
|
||||
|
||||
**What to extract:**
|
||||
- Questions in comments = unmet needs or unclear positioning
|
||||
- "Does this work for…?" = jobs they want to hire it for
|
||||
- "I switched from X" comments = switching triggers
|
||||
- Complaints about price, missing features, or broken promises
|
||||
|
||||
### YouTube Comments (Consumer)
|
||||
|
||||
Same approach as B2B but different video types:
|
||||
|
||||
- "X app honest review" or "X app after 6 months"
|
||||
- "Best [category] apps [year]" comparison videos
|
||||
- Unboxing or "setup" videos for hardware/physical products
|
||||
|
||||
Comments on review videos are especially valuable — these are people actively in the consideration phase.
|
||||
|
||||
### Consumer Community Platforms
|
||||
|
||||
- **Facebook Groups**: Still dominant for many consumer verticals (parenting, fitness, local services, hobbies)
|
||||
- **Discord servers**: Growing for gaming, creator tools, productivity, crypto, lifestyle communities
|
||||
- **Nextdoor**: Useful for local service businesses
|
||||
- **Quora**: Long-form questions reveal decision anxiety and evaluation criteria
|
||||
|
||||
---
|
||||
|
||||
## SparkToro (Audience Intelligence)
|
||||
|
||||
SparkToro is a behavioral audience research tool. Instead of mining individual posts and comments, it aggregates clickstream, search, and social data to show what your audience does at scale — what they read, watch, listen to, follow, and search for.
|
||||
|
||||
### When to Use SparkToro vs. Manual Research
|
||||
|
||||
- **SparkToro first** when you need to understand where your ICP spends time, what content they consume, and which influencers they follow — it answers these questions in seconds with aggregated data
|
||||
- **Manual research first** (Reddit, G2, communities) when you need raw language, exact quotes, emotional context, and the "why" behind behavior
|
||||
- **Best together**: Use SparkToro to identify which podcasts, subreddits, and websites matter, then go mine those sources manually for voice-of-customer language
|
||||
|
||||
### Key Queries to Run
|
||||
|
||||
**By competitor:**
|
||||
- "People who follow @competitor" — reveals shared audience affinities
|
||||
- "People who visit competitor.com" — shows what else they consume
|
||||
|
||||
**By audience description:**
|
||||
- "People who frequently talk about [topic]" — finds audience behaviors
|
||||
- "People whose bio contains [job title]" — profiles a role-based segment
|
||||
|
||||
**By your own audience:**
|
||||
- "People who visit yourdomain.com" — understand your actual audience
|
||||
- Compare against competitor audience profiles to find gaps
|
||||
|
||||
### What to Extract
|
||||
|
||||
| Data Type | What It Tells You | Use It For |
|
||||
|-----------|------------------|------------|
|
||||
| Top websites visited | Where your audience reads | Content partnerships, guest posting targets |
|
||||
| Top podcasts | What they listen to | Podcast guesting, sponsorship decisions |
|
||||
| Top YouTube channels | What they watch | Video content strategy, ad placements |
|
||||
| Top subreddits | Where they discuss | Community participation, Reddit ad targeting |
|
||||
| Search keywords | What they Google | SEO and content topic planning |
|
||||
| AI prompt topics | What they ask AI tools | Emerging content opportunities |
|
||||
| Social accounts followed | Who influences them | Influencer partnerships, co-marketing |
|
||||
| Demographics | Who they are | Persona building, ad targeting |
|
||||
|
||||
### Source Weighting
|
||||
|
||||
SparkToro data is aggregated and anonymized — it shows patterns, not individual opinions. Treat it as:
|
||||
- **High confidence** for behavioral data (what they visit, follow, search for)
|
||||
- **Medium confidence** for demographic data (self-reported, may be incomplete)
|
||||
- **Not a substitute** for qualitative research (doesn't capture language, emotions, or the "why")
|
||||
|
||||
### Limitations
|
||||
|
||||
- Free tier: 5 reports/month, shallow results (top 5–10)
|
||||
- No public API — all research done through web interface
|
||||
- Skews English-language, US-centric
|
||||
- Shows what audiences do, not why — pair with qualitative sources
|
||||
|
||||
See [tools/integrations/sparktoro.md](../../../tools/integrations/sparktoro.md) for full tool details and pricing.
|
||||
|
||||
---
|
||||
|
||||
## Organizing Your Research
|
||||
|
||||
Use a simple tagging system across all sources:
|
||||
|
||||
| Tag | Meaning |
|
||||
|-----|---------|
|
||||
| `#pain` | A problem or frustration |
|
||||
| `#trigger` | An event that prompted the search |
|
||||
| `#outcome` | What success looks like |
|
||||
| `#language` | Exact phrases worth using in copy |
|
||||
| `#alternative` | Another solution they considered or use |
|
||||
| `#objection` | Reason to hesitate or not buy |
|
||||
| `#competitor` | Anything about a competing product |
|
||||
|
||||
Keep a running doc with columns: Source | Date | Quote | Tags | Notes
|
||||
|
||||
After 20-30 entries, patterns will emerge. Look for quotes that appear in multiple unrelated sources — those are your highest-confidence insights.
|
||||
|
||||
---
|
||||
|
||||
## Source Reliability and Confidence Scoring
|
||||
|
||||
Not all sources carry equal weight. Use this guide when assigning confidence labels.
|
||||
|
||||
### Source Weighting
|
||||
|
||||
| Source | Signal Strength | Bias to Note |
|
||||
|--------|----------------|--------------|
|
||||
| Customer interviews (unprompted) | Very high | Small sample; selection bias toward engaged customers |
|
||||
| Win/loss interviews | High | Recent memory only; rationalization common |
|
||||
| App store / G2 reviews | High | Skews toward strong opinions (love or hate) |
|
||||
| Reddit / community posts | Medium-high | Skews technical, skeptical, vocal minorities |
|
||||
| Support tickets | Medium | Skews toward problems; silent majority not represented |
|
||||
| Survey (open-ended) | Medium | Primed by question framing |
|
||||
| Survey (multiple choice) | Low-medium | Artifacts of the options you provided |
|
||||
| NPS verbatims | Medium | Correlates with score; prompted by the survey moment |
|
||||
| YouTube/TikTok comments | Medium | Skews toward engaged viewers; social performance |
|
||||
| SparkToro audience data | Medium-high | Aggregated behavioral data; strong for "what" but not "why" |
|
||||
| Job postings | Low-medium | Aspirational, not necessarily reflective of current pain |
|
||||
|
||||
### Confidence Labels in Practice
|
||||
|
||||
When presenting insights, lead with confidence:
|
||||
|
||||
```
|
||||
[HIGH CONFIDENCE] Customers feel overwhelmed by manual reporting — appears in 12 of 20 interviews,
|
||||
4 Reddit threads, and is the #1 complaint in 3-star G2 reviews. Consistent across SMB and mid-market.
|
||||
|
||||
[MEDIUM CONFIDENCE] Customers compare us to spreadsheets more than to direct competitors —
|
||||
mentioned in 6 interviews and 3 Reddit threads, but not yet seen in review data.
|
||||
|
||||
[LOW CONFIDENCE] Enterprise buyers may have procurement concerns — mentioned by 2 interviewees
|
||||
from companies 500+. Needs more signal before acting on it.
|
||||
```
|
||||
|
||||
### Recency Window
|
||||
|
||||
- **Use as primary source**: Data from the last 12 months
|
||||
- **Use with caution**: 12-24 months (product and market may have shifted)
|
||||
- **Use only for baseline context**: 2+ years old
|
||||
|
||||
When a theme appears consistently across old and new data, that's a durable signal worth acting on.
|
||||
@@ -0,0 +1,381 @@
|
||||
---
|
||||
name: directory-submissions
|
||||
description: When the user wants to submit their product to startup, SaaS, AI, agent, MCP, no-code, or review directories for backlinks, domain rating, and discovery. Also use when the user mentions "directory submissions," "submit to directories," "backlinks from directories," "list my product," "submit to Product Hunt," "BetaList," "TAAFT," "Futurepedia," "G2 listing," "Capterra listing," "AlternativeTo," "SaaSHub," "AI directories," "MCP registry," "agent directory," "dofollow backlinks," "launch directories," or "directory tracker." Use this whenever someone is planning the directory layer of a product launch or an ongoing backlink campaign. For the broader launch moment, see launch. For programmatic SEO pages that should live behind these backlinks, see programmatic-seo. For AI citation optimization, see ai-seo.
|
||||
metadata:
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Directory Submissions
|
||||
|
||||
You are an expert in directory-driven distribution for software products. Your goal is to help the user build a compounding backlink + discovery foundation by submitting to the right directories, in the right order, with the right positioning — and to make sure that foundation actually produces leads instead of vanity backlinks.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
Directory submissions are the **foundation layer** of distribution — never the whole strategy. They do three things well:
|
||||
|
||||
1. **Pass dofollow backlinks** from high domain-rating sites into your marketing pages. This raises your DR, which makes your entire site easier to rank for competitive keywords.
|
||||
2. **Create discovery surface area** — people browsing AI/SaaS directories are in-market buyers, not random traffic.
|
||||
3. **Get cited by AI engines** — ChatGPT, Claude, Perplexity, and Google AI Overviews all pull heavily from high-DR directories when answering "what's the best [category]?" queries. AI-referred traffic converts **6–27× higher** than traditional search traffic.
|
||||
|
||||
But directories alone will not generate meaningful leads. They exist to pass link equity into the pages that DO generate leads — template galleries, comparison pages, alternative pages, blog posts. **Build the destination pages first, then submit to directories so the link equity has somewhere useful to land.**
|
||||
|
||||
The full directory catalog lives in `references/directory-list.md`. The positioning variant library lives in `references/positioning-variations.md`. The submission tracker template lives in `references/submission-tracker-template.csv`.
|
||||
|
||||
---
|
||||
|
||||
## The Three Hard Rules
|
||||
|
||||
### Rule 1: Foundation before submission
|
||||
Never submit to a directory until the landing page it will link to is live, indexed, and has:
|
||||
- A single `<h1>` and sequential heading hierarchy — pages with clean hierarchy have **2.8× higher AI citation rates**, and 87% of ChatGPT-cited pages use a single H1.
|
||||
- A real pricing page (even "free while in beta" counts — most Tier 1 directories require one).
|
||||
- Privacy policy + terms.
|
||||
- Logo assets in PNG + SVG + square 1024×1024 + favicon.
|
||||
- 5–8 real product screenshots at 1920×1080 (not marketing mockups).
|
||||
- A 60–90 second demo video — products with video on Product Hunt get **2.7× more upvotes**.
|
||||
- FAQ schema markup (AI engines heavily weight `FAQPage` JSON-LD for answer extraction).
|
||||
- Structured data: `Organization`, `Product`, `SoftwareApplication`.
|
||||
|
||||
### Rule 2: Destination pages before directories
|
||||
Directories are the *source* of link equity. You need *destinations* that can convert the resulting traffic. Minimum destinations before submitting to anything:
|
||||
- 3–5 competitor alternative pages (`/alternatives/[competitor]`) targeting "[competitor] alternative" keywords. Comparison/alternative pages convert at **5–15%** vs 0.5–2% for generic content.
|
||||
- 3–5 use-case pages (`/for/[audience]` or `/use-cases/[use-case]`).
|
||||
- Template gallery with 20+ entries (if applicable — this was Typeform's largest SEO growth driver, generating 30K non-branded signups and $3M/year LTV).
|
||||
- 1 "best of" blog post you wrote yourself about your own category, including honest coverage of competitors.
|
||||
|
||||
### Rule 3: Positioning varies by directory type
|
||||
Never copy-paste the same description everywhere. AI engines penalize duplicate content, and each directory audience responds to different framing. See `references/positioning-variations.md` for the full variant library. Short version:
|
||||
|
||||
| Surface | Lead with | Why |
|
||||
|---|---|---|
|
||||
| Startup directories | **Outcome** | Audience is other founders. They care what it does. |
|
||||
| SaaS directories | **Alternative framing** | People search "[competitor] alternative" — meet them there. |
|
||||
| AI directories | **AI-first architecture** | TAAFT/Futurepedia audiences explicitly want AI tools. |
|
||||
| Agent/MCP directories | **Agent/MCP angle** | Niche but high-intent. A real moat. |
|
||||
| No-code directories | **Ease + power** | Audience values speed-to-build over depth. |
|
||||
| Dev directories | **Technical depth** | Dev audiences reward technical substance. |
|
||||
| B2B review sites | **ROI + use case** | Buyers want outcomes and case studies. |
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Readiness assessment (Phase 0)
|
||||
|
||||
Ask the user these 9 questions. If any are "no", they're not ready — help them build the missing piece first.
|
||||
|
||||
1. Is the product publicly accessible (no password wall)?
|
||||
2. Is there a pricing page (even "free while in beta")?
|
||||
3. Are privacy policy + terms live?
|
||||
4. Logo assets in PNG + SVG + square + favicon?
|
||||
5. 5–8 real screenshots + 60–90s demo video?
|
||||
6. Landing pages GEO-ready (single H1, sequential hierarchy, FAQ schema, structured data)?
|
||||
7. At least 3 alternative pages and 3 use-case pages live and indexed?
|
||||
8. Template gallery or lead magnet asset (if applicable to category)?
|
||||
9. At least 20 beta/early users who could leave a review on G2?
|
||||
|
||||
A "no" on any of 1–7 is a hard block. A "no" on 8–9 is a soft block: you can launch but will lose Tier 2 review value and Typeform-style compounding.
|
||||
|
||||
### Step 2: Choose the tiers
|
||||
|
||||
Full catalog in `references/directory-list.md`. Summary:
|
||||
|
||||
| Tier | When | Examples | Typical count |
|
||||
|---|---|---|---|
|
||||
| **Tier 1 — Flagship launch** | Launch week only | Product Hunt (anchor), BetaList, HN Show HN, Fazier, DevHunt | ~15 |
|
||||
| **Tier 2 — Startup/SaaS** | Week 1 + rolling | AlternativeTo, SaaSHub, G2, Capterra, F6S, SourceForge, Slashdot | ~50 |
|
||||
| **Tier 3 — AI directories** | Week 1–3 | TAAFT, Futurepedia, Toolify, Future Tools, aitools.inc, AIStage | ~40 |
|
||||
| **Tier 4 — Agent/MCP registries** | Week 1–3 (if MCP) | Glama, APITracker, LF MCP Registry, AI Agents List | ~10 |
|
||||
| **Tier 5 — No-code directories** | Week 1–3 (if no-code) | NoCodeFinder, No Code MBA, We Are No Code, MakerPad | ~8 |
|
||||
| **Tier 6 — "Best of" listicles** | Rolling outreach | Cold outreach to DR 40+ blog posts | ~10 inclusions |
|
||||
| **Tier 7 — Integration marketplaces** | When integrations ship | Zapier, HubSpot, Slack, Airtable, Notion | ~5 |
|
||||
| **Tier 8 — Profile & content platforms** | Rolling | GitHub, WordPress.com, Substack, Dev.to, SlideShare, Behance | ~50 |
|
||||
| **Tier 9 — Local business directories** | Rolling (if applicable) | Manta, Hotfrog, Locanto, MerchantCircle | ~20 |
|
||||
| **Tier 10 — Forums & communities** | Rolling (participate first) | SitePoint, GrowthHackers, Warrior Forum, Designer News | ~13 |
|
||||
| **Tier 11 — Press release & article sites** | Launch + milestones | PRLog, PR.com, EzineArticles, Feedspot | ~25 |
|
||||
| **Tier 12 — Social bookmarking** | Rolling | Scoop.it, Diigo, Pearltrees | ~5 |
|
||||
| **Tier 13 — Niche vertical directories** | When vertical fits | Justia (legal), Porch (home), LandBook (design), etc. | ~20 |
|
||||
|
||||
**Triage rule:** Only submit where the product is a genuine fit. Forcing a listing into the wrong category burns the first-submission advantage and gets rejected by moderators.
|
||||
|
||||
### Step 3: Prepare asset variations
|
||||
|
||||
For each tier, prep a distinct description variant (pulled from `references/positioning-variations.md`):
|
||||
- **Tagline** under 10 words
|
||||
- **Short description** at 60 chars
|
||||
- **Long description** at 150 words
|
||||
- **5–8 category tags**
|
||||
- **Logo** assets
|
||||
- **Screenshots** + demo video URL
|
||||
- **Founder story** (2–3 sentences)
|
||||
|
||||
**Critical:** Don't copy-paste the same long description into every directory. Vary the opening sentence, the feature emphasis, and the audience framing per tier. AI engines cross-reference and down-weight duplicate content.
|
||||
|
||||
### Step 4: Batch submit
|
||||
|
||||
Set up the tracker spreadsheet (`references/submission-tracker-template.csv`). Work left-to-right through it. 2–3 hours per batch is realistic.
|
||||
|
||||
Per submission:
|
||||
1. Copy the tier-appropriate positioning variant.
|
||||
2. Fill in the form.
|
||||
3. Upload assets.
|
||||
4. Submit.
|
||||
5. Log: date, URL, status, moderator notes.
|
||||
6. Once live, verify the backlink exists and is dofollow: `curl -sIL https://directory.com/your-listing | grep -i rel=`. If absent, the link is dofollow.
|
||||
|
||||
---
|
||||
|
||||
## Product Hunt Deep Dive (The Anchor Event)
|
||||
|
||||
Product Hunt is the single highest-leverage submission but also the most easily wasted. The 2026 PH algorithm weights **comment quality** more than upvote count — a post with 50 upvotes + 30 genuine comments ranks above one with 200 upvotes + 5 comments. **80% of failed launches** fail because they launched without a warm audience OR asked for upvotes instead of feedback.
|
||||
|
||||
### 3-week prep timeline
|
||||
|
||||
- **Day -21 to -14:** Warm up hunter account. Upvote + thoughtfully comment on 3 launches/day. Follow 100+ active makers. Build history so your account looks real to the algorithm.
|
||||
- **Day -14:** Create "Upcoming" page on PH. Drive traffic to it to collect "notify on launch" subscribers.
|
||||
- **Day -10:** (Optional) book a hunter. Don't pay cash — trade a feature, shoutout, or intro. A known hunter adds ~15% to day-one momentum but isn't required.
|
||||
- **Day -7:** Draft launch-day assets: gallery images (1270×760), tagline, 260-char description, first comment from you, first comment from a customer.
|
||||
- **Day -3:** Email list warm-up. "We're launching Tuesday. Here's what to expect. Reply if you want a heads up."
|
||||
- **Day -1:** Final check — product works in incognito, video autoplays, CTA goes to signup, PH listing preview looks right.
|
||||
|
||||
### Launch day execution
|
||||
|
||||
- **Launch at 12:01 AM Pacific Time.** Tuesday, Wednesday, or Thursday only — weekend launches get 60–70% less traffic. The 12:01 AM PT start maximizes your 24-hour window.
|
||||
- **First 2 hours are everything.** Need 50+ supporters in the first 2 hours to trigger algorithmic distribution.
|
||||
- **Post the first comment yourself** with the story: why you built it, what's different, what to try first.
|
||||
- **Reply to every comment** in under 30 minutes. PH measures maker responsiveness.
|
||||
- **Share the link to:** Twitter/X thread, LinkedIn long-form post, personal Slack/Discord communities, your email list, Indie Hackers, every power user via DM.
|
||||
- **Never ask for upvotes.** Ask for **feedback**. "Would love your honest take on the positioning" converts 3× better than "support us!" and doesn't trigger the algorithm's anti-manipulation filters.
|
||||
- **Don't message strangers.** The community flags this and moderators will hide your post.
|
||||
|
||||
### Post-launch
|
||||
|
||||
- Write a launch recap blog post with numbers + lessons. Honest, not bragging. Publish on day 2.
|
||||
- Cross-post the recap to Indie Hackers and r/SaaS (where promotion is allowed).
|
||||
- Only submit to Show HN if you have a *technical* angle to share (architecture, DSL, novel approach). A generic "we launched a SaaS" post will get flagged to death.
|
||||
|
||||
---
|
||||
|
||||
## Reviews Playbook (G2 / Capterra / TrustRadius)
|
||||
|
||||
G2 and Capterra (now owned by G2 as of Feb 2026) listings are **worthless without reviews**. 10 reviews is the magic threshold for Grid appearance. Run the 10-in-30 protocol during launch month.
|
||||
|
||||
### The 10-in-30 protocol
|
||||
|
||||
1. **Day 1 post-launch:** Identify 20 users who have completed a meaningful action with the product.
|
||||
2. **Send each a personal email** with a direct review URL (reduces friction by ~70%). No forms, no landing pages — direct link.
|
||||
3. **Offer a modest thank-you.** G2 and TrustRadius explicitly allow small incentives like a $25 Amazon gift card.
|
||||
4. **Follow up once** after 5 days. Don't follow up twice — it becomes annoying and damages the relationship.
|
||||
5. **Target:** 50% conversion → 10 reviews from 20 asks.
|
||||
|
||||
### Critical deadlines
|
||||
|
||||
- **G2 Summer reports:** cut off ~April 28. Plan review drives to land before this.
|
||||
- **G2 Fall reports:** cut off ~July 28.
|
||||
- Missing a cutoff means waiting 3 months for the next grid update.
|
||||
|
||||
### Badges and paid plans
|
||||
|
||||
- **"Users Love Us" badge** is still free: requires 20 reviews at 4.0+ average.
|
||||
- **Grid, Momentum, Index, and Award badges** require a paid G2 plan ($2,999+/year starting Summer 2025).
|
||||
- **Do not spend on paid G2 in year one.** The free listing + Users Love Us badge is sufficient.
|
||||
|
||||
### Cross-platform
|
||||
|
||||
- TrustRadius follows similar mechanics but smaller volume.
|
||||
- Capterra auto-syncs from Gartner Digital Markets in some categories — may populate without direct action.
|
||||
|
||||
---
|
||||
|
||||
## Destination Pages Strategy (What the Backlinks Point At)
|
||||
|
||||
Directories are useless if the backlinks land on a generic homepage. Build these destination pages *before* submitting:
|
||||
|
||||
### 1. Alternative pages (highest ROI)
|
||||
|
||||
Competitor alternative pages convert at **5–15%**, often hitting 15–30% for bottom-of-funnel queries. One page per top competitor:
|
||||
|
||||
- `/alternatives/[competitor-1]`
|
||||
- `/alternatives/[competitor-2]`
|
||||
- `/alternatives/[competitor-3]`
|
||||
- `/alternatives/[competitor-4]`
|
||||
|
||||
Each page needs: honest feature comparison table, "when to choose X over us," "when to choose us over X," pricing comparison, 3–5 use-case examples, strong FAQ with schema.
|
||||
|
||||
**Critical:** Be honest. AI engines cross-reference competitor feature claims and de-rank pages that lie.
|
||||
|
||||
### 2. Use-case / ICP pages
|
||||
|
||||
Every ICP gets a dedicated landing page:
|
||||
- `/for/[audience]` — coaches, agencies, ecommerce, SaaS, consultants, etc.
|
||||
- `/use-cases/[use-case]` — lead qualification, onboarding, product recommendations, etc.
|
||||
|
||||
### 3. Template / asset gallery (if applicable)
|
||||
|
||||
Typeform's template library generated **30,000 non-branded organic signups and $3M/year LTV**. The pattern:
|
||||
- One indexable page per template at `/templates/[slug]`.
|
||||
- H1 with the keyword, 150+ word description, screenshot, "when to use this," "use this template" CTA.
|
||||
- Related templates at the bottom of each page (internal linking = SEO compounding).
|
||||
- 100 templates by day 30, 300 by day 90 is the realistic target.
|
||||
|
||||
### 4. "Best of" listicles you wrote yourself
|
||||
|
||||
Write honest roundups of your own category: `/blog/best-[category]-tools-2026`. Include yourself + 10 competitors with real reviews. These rank for category queries AND serve as canonical references AI engines cite.
|
||||
|
||||
### 5. Integration pages (when integrations ship)
|
||||
|
||||
Every integration = one landing page at `/integrations/[partner]`. Follows the Zapier playbook: Zapier gets **~2.6M monthly organic visits** from programmatic integration pages (~15% of their total organic traffic).
|
||||
|
||||
---
|
||||
|
||||
## GEO (Generative Engine Optimization)
|
||||
|
||||
In 2026, 30–50% of "research a tool" queries happen inside ChatGPT, Claude, Perplexity, or Google AI Overviews without ever touching a traditional search page. Directories matter here too — AI engines pull heavily from high-DR directories when generating answers. But the *destination pages* also need to be GEO-optimized.
|
||||
|
||||
### Tactics that get pages cited
|
||||
|
||||
1. **One H1 per page, sequential heading hierarchy.** 2.8× higher citation rate. 87% of cited pages use a single H1.
|
||||
2. **Dense, factual content with citable stats.** AI engines prefer specific numbers ("3× faster than X") over vague claims.
|
||||
3. **FAQ schema on every landing page.** AI engines heavily weight `FAQPage` JSON-LD for answer extraction.
|
||||
4. **Comparison tables.** Extractable, structured — exactly what an AI answer needs.
|
||||
5. **Explicit "what it is" paragraph in the first 100 words.**
|
||||
6. **Get cited on Reddit and Hacker News.** Claude and Perplexity index these heavily. Genuine mentions on r/SaaS and HN count as training fuel.
|
||||
7. **Publish original research.** "We analyzed 10,000 [things] and found X" becomes the primary citation for anyone writing about that topic.
|
||||
8. **Claim Crunchbase, LinkedIn company page, and Wikidata entries.** All three feed AI training corpora.
|
||||
9. **If applicable, list on MCP registries with A/B grades** (Glama in particular). LLMs pull from these when answering MCP questions.
|
||||
|
||||
### Measurement
|
||||
|
||||
Manually check monthly: ask ChatGPT, Claude, and Perplexity "what are the best [category] tools?" and log where the product appears. Free GEO tracking tools (GeoTracker, llmrefs) automate this.
|
||||
|
||||
---
|
||||
|
||||
## Community & Ongoing Distribution
|
||||
|
||||
Directories are one-shot. Community is ongoing. Both feed the same funnel.
|
||||
|
||||
### Reddit (90/10 rule)
|
||||
|
||||
90% of activity must be genuinely helpful; only 10% promotional. Violating this gets shadowbanned.
|
||||
|
||||
**High-value subs (ranked):**
|
||||
- **r/SideProject** (200K+) — friendly to promo, launch announcements welcome.
|
||||
- **r/SaaS** (300K+) — "Share Your SaaS" threads are explicit promo windows.
|
||||
- **r/startups** (1.7M) — Feedback Friday thread.
|
||||
- **r/Entrepreneur** (3.5M) — weekly promo thread.
|
||||
- **r/nocode**, **r/IndieHackers**, **r/alphaandbetausers** — friendly.
|
||||
- **r/webdev**, **r/artificial**, **r/LocalLLaMA** — strict, technical only.
|
||||
|
||||
**What wins:** real numbers (MRR, signups, churn), screenshots, "what I tried / what happened / what I'd do differently" structure, mini case studies with a clear lesson. **What fails:** hype, vague claims, "check out my new tool" posts, asking for upvotes.
|
||||
|
||||
### LinkedIn (B2B primary channel)
|
||||
|
||||
80% of B2B social leads come from LinkedIn. Cadence: **3–5 posts/week** — fewer loses momentum, more causes fatigue.
|
||||
|
||||
Content types ranked by 2026 engagement:
|
||||
1. Personal stories with business lessons (1.5–2× avg engagement)
|
||||
2. Original data / research (1.3–1.5×)
|
||||
3. Contrarian industry takes (1.2–1.5×)
|
||||
4. Document carousels with 8–12 slides (1.3–1.8×)
|
||||
|
||||
### Twitter/X (indie hacker + dev channel)
|
||||
|
||||
Build-in-public threads on architecture, revenue, decisions. Technical deep-dives get indexed by Google + Claude + Perplexity → indirect GEO.
|
||||
|
||||
### Indie Hackers
|
||||
|
||||
- Launch a build-in-public thread on PH launch day.
|
||||
- Post weekly updates: revenue, ships, lessons. Zero-revenue posts work if the lesson is honest.
|
||||
- Comment 10× more than you post to build karma before your own links.
|
||||
|
||||
### Dev.to + Hashnode
|
||||
|
||||
Every substantial technical post = dofollow backlink + dev audience reach. Cross-post with canonical URL back to main blog.
|
||||
|
||||
---
|
||||
|
||||
## KPIs & Tracking
|
||||
|
||||
Track weekly. If a number isn't moving, investigate — don't just submit more directories.
|
||||
|
||||
| Metric | Day 0 | Day 30 target | Day 90 target |
|
||||
|---|---|---|---|
|
||||
| Domain Rating (DR) | 0 | 20 | 30+ |
|
||||
| Referring domains | 0 | 30 | 80+ |
|
||||
| Indexed pages | — | 50 | 200+ |
|
||||
| Organic clicks/day | 0 | 30 | 200+ |
|
||||
| Directory listings live | 0 | 50 | 70+ |
|
||||
| G2 reviews | 0 | 10 | 25 |
|
||||
| Capterra reviews | 0 | 5 | 15 |
|
||||
| AI citations (manual check) | 0 | 3 | 15+ |
|
||||
| Signups from directory referrals | 0 | 50 | 300 |
|
||||
| Signups from alt/use-case pages | 0 | 20 | 300 |
|
||||
|
||||
---
|
||||
|
||||
## What NOT to Do
|
||||
|
||||
1. **Don't pay for directory submission services** ($60–$200 packages). The whole point is these are free. It's an afternoon of copy-paste.
|
||||
2. **Don't submit to spam directories** (DR under 10, no traffic, no editorial quality). They dilute your backlink profile and Google's spam detection can penalize you.
|
||||
3. **Don't submit with the wrong positioning.** Re-read the positioning table per tier. Generic descriptions waste the listing.
|
||||
4. **Don't treat directories as your entire GTM.** They're the foundation. Content + community + reviews are what actually convert.
|
||||
5. **Don't skip reviews on G2/Capterra.** Zero-review listings are dead. Run the 10-in-30 protocol or don't submit.
|
||||
6. **Don't ask for upvotes on Product Hunt.** The 2026 algorithm penalizes it. Ask for **feedback**.
|
||||
7. **Don't amend old directory listings every week.** Submit once, check quarterly.
|
||||
8. **Don't submit before the destination page exists.** Link equity needs a destination.
|
||||
9. **Don't duplicate descriptions across directories.** AI engines penalize duplicate content.
|
||||
10. **Don't lie on comparison pages.** AI engines cross-reference and de-rank lies.
|
||||
11. **Don't over-index on launch-day spike.** The flywheel is templates + alternatives + reviews + ongoing content — not one day of PH.
|
||||
12. **Don't forget Crunchbase, LinkedIn company page, and Wikidata.** These feed AI training corpora and matter for GEO.
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. **What are you launching?** (Category changes tier mix — AI vs traditional SaaS vs no-code vs dev tool.)
|
||||
2. **When is launch day?** (Phase 0 assets need 7 days of prep.)
|
||||
3. **Do you have destination pages built?** (Alternatives, use cases, templates — if not, build first.)
|
||||
4. **Product Hunt hunter lined up?** (Optional but adds ~15% day-one lift. 3-week warm-up required regardless.)
|
||||
5. **How many beta users can you ask for reviews?** (Need 20 to hit 10.)
|
||||
6. **Do you have an MCP or agent angle?** (If yes, Tier 4 registries are a real moat.)
|
||||
7. **Existing integrations?** (If yes, Tier 7 marketplaces are the highest-DR backlinks available.)
|
||||
8. **Email list size?** (Needed for PH launch day warm traffic — 100+ is the minimum.)
|
||||
9. **Current DR and referring domain count?** (Baseline for measuring the compounding effect.)
|
||||
|
||||
---
|
||||
|
||||
## Output Format
|
||||
|
||||
When the user asks for a directory plan, return:
|
||||
|
||||
1. **Readiness assessment** — which Phase 0 items are missing, which block submission
|
||||
2. **Tier selection** — which tiers apply, which to skip, why
|
||||
3. **Submission order** — week 1 / week 2 / week 3 batches
|
||||
4. **Destination page list** — what to build first if missing
|
||||
5. **Positioning variants** — the actual copy per tier (from `references/positioning-variations.md`)
|
||||
6. **PH 3-week prep timeline** — mapped to calendar dates if launch day known
|
||||
7. **Reviews 10-in-30 plan** — who to ask, when, how
|
||||
8. **Weekly targets** — directories submitted, reviews, DR movement
|
||||
9. **Tracker** — link to or include the CSV from `references/submission-tracker-template.csv`
|
||||
|
||||
Keep the plan actionable. Every item should be something the user can do today.
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **launch** — broader launch moment, ORB framework, five-phase approach
|
||||
- **programmatic-seo** — destination pages (alternatives, integrations, templates) that backlinks should flow into
|
||||
- **competitors** — `/alternatives/[tool]` page pattern
|
||||
- **ai-seo** — GEO optimization for AI citation
|
||||
- **content-strategy** — editorial content that attracts "best of" listicle inclusions
|
||||
- **free-tools** — lead magnets for destination pages
|
||||
- **community-marketing** — Reddit, Indie Hackers, Slack community mechanics
|
||||
- **schema** — FAQ + Product + Organization JSON-LD for GEO
|
||||
@@ -0,0 +1,94 @@
|
||||
{
|
||||
"skill_name": "directory-submissions",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We're launching our AI SaaS in 3 weeks. Help me plan all the directories we should submit to.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should run Phase 0 readiness assessment with the 9 questions before recommending submissions. Should reject submission if any of items 1-7 are 'no' (hard block) and explain why. Should recommend tier mix: Tier 1 flagship launch (~15 — Product Hunt as anchor, BetaList, HN Show HN, Fazier, DevHunt), Tier 2 startup/SaaS (~50), Tier 3 AI directories (~40 — TAAFT, Futurepedia, Toolify), Tier 4 MCP/agent if applicable. Should map the 3-week Product Hunt prep timeline to calendar dates. Should warn against submitting before destination pages exist. Should reference references/directory-list.md and references/positioning-variations.md. Should recommend the 10-in-30 reviews protocol for G2/Capterra. Should set day-30 and day-90 targets from the KPI table.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Runs Phase 0 readiness assessment",
|
||||
"Recommends tier mix appropriate to AI SaaS",
|
||||
"Maps 3-week PH timeline to calendar dates",
|
||||
"Names Product Hunt as anchor",
|
||||
"Recommends 10-in-30 reviews protocol",
|
||||
"Sets day-30 and day-90 KPI targets",
|
||||
"References directory-list.md or positioning-variations.md"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Can I just copy-paste the same description into every directory?",
|
||||
"expected_output": "Should refuse and explain Rule 3: positioning varies by directory type. Should explain AI engines penalize duplicate content — directories cross-referenced by Claude, ChatGPT, Perplexity will de-rank repetitive copy. Should explain different framing per surface: startup directories lead with outcome (audience is founders), SaaS directories lead with alternative framing (people search '[competitor] alternative'), AI directories lead with AI-first architecture, agent/MCP directories lead with the agent/MCP angle, B2B review sites lead with ROI + use case. Should recommend preparing distinct variants per tier: tagline under 10 words, 60-char short description, 150-word long description, 5-8 category tags. Should reference references/positioning-variations.md.",
|
||||
"assertions": [
|
||||
"Refuses the request",
|
||||
"Cites Rule 3 (positioning varies by directory type)",
|
||||
"Notes AI engines penalize duplicate content",
|
||||
"Lists different framing per surface type",
|
||||
"Specifies variant lengths (tagline, short, long)",
|
||||
"References positioning-variations.md"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Should we pay for one of those directory submission services that submits to 200 directories for $99?",
|
||||
"expected_output": "Should say no, citing 'What NOT to Do' rule 1: don't pay for directory submission services. Should explain the whole point is these are free — it's an afternoon of copy-paste. Should warn that mass-submission services typically submit to low-quality spam directories (DR under 10, no traffic, no editorial quality) which dilute the backlink profile and can trigger Google spam detection. Should recommend the alternative: manually submit to Tier 1-4 directories with appropriate positioning variants and tracker. Should reinforce that the value comes from quality directories with editorial standards, not raw volume.",
|
||||
"assertions": [
|
||||
"Refuses the service",
|
||||
"Cites 'don't pay for submission services' rule",
|
||||
"Warns about low-DR spam directories",
|
||||
"Warns about Google spam penalty risk",
|
||||
"Recommends manual submission to quality directories"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Walk me through how to launch on Product Hunt next month. We've never done it before.",
|
||||
"expected_output": "Should apply the Product Hunt Deep Dive playbook. Should map the 3-week prep timeline: Day -21 to -14 (warm up hunter account, upvote and comment on 3 launches/day), Day -14 (create Upcoming page), Day -10 (optional book a hunter — trade not cash), Day -7 (draft launch-day assets: 1270x760 gallery images, tagline, 260-char description, first comment), Day -3 (email list warm-up), Day -1 (final check). Should explain launch day: launch at 12:01 AM Pacific Time on Tuesday/Wednesday/Thursday only, first 2 hours are everything (need 50+ supporters), post the first comment yourself, reply to every comment in under 30 minutes, share to multiple channels. Should warn never ask for upvotes — ask for feedback. Should warn don't DM strangers — community flags this. Should explain post-launch: write a launch recap blog post with numbers + lessons, cross-post to Indie Hackers, only submit to Show HN if there's a technical angle. Should note 80% of failed launches fail from no warm audience or asking for upvotes.",
|
||||
"assertions": [
|
||||
"Maps 3-week timeline with specific day markers",
|
||||
"Notes 12:01 AM Pacific Time launch",
|
||||
"Restricts to Tue/Wed/Thu",
|
||||
"Emphasizes first 2 hours / 50+ supporters",
|
||||
"Warns never ask for upvotes",
|
||||
"Recommends asking for feedback",
|
||||
"Warns against DMing strangers",
|
||||
"Includes post-launch recap and cross-posting"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "We want to list on G2 but we only have 4 customers right now. Worth doing?",
|
||||
"expected_output": "Should explain G2 and Capterra listings are worthless without reviews — 10 reviews is the magic threshold for Grid appearance. Should recommend NOT submitting yet, or claim the listing but plan a review drive in parallel. Should explain the 10-in-30 protocol: identify 20 users who completed a meaningful action, send each a personal email with direct review URL (reduces friction ~70%), offer a modest thank-you ($25 Amazon gift card is allowed by G2/TrustRadius), follow up once after 5 days, target 50% conversion. Should note the Users Love Us badge is free (20 reviews at 4.0+) but Grid/Momentum/Index/Award badges require a paid G2 plan ($2,999+/year as of Summer 2025) — and recommend NOT spending on paid G2 in year one. Should mention G2 Summer report cutoff ~April 28 and Fall ~July 28. Should suggest waiting until ~10 users are realistic before submitting.",
|
||||
"assertions": [
|
||||
"Explains 10-review threshold for Grid",
|
||||
"Recommends NOT submitting yet OR claim + plan review drive",
|
||||
"Lays out 10-in-30 protocol",
|
||||
"Notes incentive ($25 gift card) is allowed",
|
||||
"Mentions Users Love Us badge requirements",
|
||||
"Warns against paying for G2 plan in year one",
|
||||
"Mentions Summer/Fall report cutoffs"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "We submitted to 50 directories last week. Now what?",
|
||||
"expected_output": "Should warn against treating submissions as the strategy. Should reference 'What NOT to Do' rule 11: don't over-index on launch spike. Flywheel is templates + alternatives + reviews + ongoing content. Should recommend verifying the dofollow status of acquired backlinks (curl -sIL | grep -i rel=). Should pivot to ongoing distribution: destination pages strategy (alternative pages converting 5-15%, use-case/ICP pages, template gallery if applicable, 'best of' listicles you write yourself, integration pages), GEO tactics for AI citation (single H1, FAQ schema, comparison tables, get cited on Reddit/HN, claim Crunchbase/LinkedIn/Wikidata), community presence (Reddit 90/10 rule, LinkedIn 3-5 posts/week, Twitter build-in-public, Indie Hackers, Dev.to/Hashnode). Should remind to track weekly KPIs (DR, referring domains, indexed pages, organic clicks, signups from directory referrals) and investigate if numbers aren't moving rather than submitting more.",
|
||||
"assertions": [
|
||||
"Warns against over-indexing on launch spike",
|
||||
"Recommends verifying dofollow status of backlinks",
|
||||
"Pivots to destination pages strategy",
|
||||
"Mentions GEO tactics",
|
||||
"Includes ongoing community distribution",
|
||||
"Recommends tracking weekly KPIs",
|
||||
"Says investigate before submitting more"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,477 @@
|
||||
# Directory List — Full Reference
|
||||
|
||||
Canonical list of directories organized by tier. DR values are approximate and drift over time — verify via Ahrefs or Moz before building a plan around them.
|
||||
|
||||
**Column legend:**
|
||||
- **DR** — Domain Rating (Ahrefs). Higher = more link equity passed.
|
||||
- **Dofollow** — Whether the backlink passes SEO value. Nofollow listings still matter for referral traffic and brand signals.
|
||||
- **Cost** — Free unless noted.
|
||||
|
||||
---
|
||||
|
||||
## Tier 1 — Flagship Launch Platforms
|
||||
|
||||
Submit only during launch week. These are time-sensitive with limited re-submission windows.
|
||||
|
||||
| Directory | DR | Dofollow | Cost | Notes |
|
||||
|---|---|---|---|---|
|
||||
| **Product Hunt** | 91 | Yes | Free | The anchor event. Requires 3-week warm-up. 2026 algorithm weights comment quality over upvotes. Launch Tue/Wed/Thu at 12:01 AM PT. |
|
||||
| **Hacker News (Show HN)** | 91 | Nofollow | Free | Only if you have a genuine technical angle. Post title format: "Show HN: [Product] — [hook]". Moderator death penalty for hype. |
|
||||
| **BetaList** | 64 | Yes | Free (paid expedite ~$99) | Best for pre-launch waitlist building. Submission → 2–4 week queue unless expedited. |
|
||||
| **Launching Next** | ~30 | Yes | Free | Editorial curation — needs a compelling story. |
|
||||
| **Fazier** | ~30 | Yes | Free | Daily ranking with much lower competition than PH. Achievable #1. |
|
||||
| **Uneed** | ~40 | Yes | Free | Curated, smaller audience, quality backlink. |
|
||||
| **Microlaunch** | ~30 | Yes | Free | Month-long visibility vs one-day spike. |
|
||||
| **OpenHunts** | ~25 | Yes | Free | Indie-maker friendly, reports 14%+ conversion rates. |
|
||||
| **DevHunt** | ~35 | Yes | Free | Dev-focused. Best fit for developer tools and technical products. |
|
||||
| **PeerPush** | ~25 | Yes | Free | Similar to Fazier. Low competition. |
|
||||
| **LaunchVault** | ~20 | Yes | Free | Anti-VC positioning. Good for bootstrapped narrative. |
|
||||
| **What Launched Today** | ~20 | Yes | Free | Guaranteed visibility on launch day regardless of votes. |
|
||||
| **Firsto** | ~25 | Yes | Free tier | Sustained discovery, not one-day spike. |
|
||||
| **GetByte** | ~20 | Yes | Free | Lightweight listing + promotional support. |
|
||||
| **Best of Web** | ~30 | Yes | Free | Easy fast submission, free dofollow. |
|
||||
| **Tiny Launch** | ~20 | Yes | Free | Lightweight, fast approval. |
|
||||
| **PitchWall** | ~25 | Yes | Free | Indie-hacker friendly. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 2 — Startup / SaaS / Software Directories
|
||||
|
||||
Submit during launch week and continue rolling submissions thereafter.
|
||||
|
||||
| Directory | DR | Dofollow | Cost | Notes |
|
||||
|---|---|---|---|---|
|
||||
| **AlternativeTo** | 79 | Nofollow | Free | Massive SEO value despite nofollow. Submit as alternative to your top 4 competitors. |
|
||||
| **SaaSHub** | 77 | Yes | Free | Ranks well for "[tool] alternatives" queries. High intent. |
|
||||
| **G2** | 92 | Yes | Free listing | 10 reviews required for Grid appearance. Paid badges start at $2,999/yr. |
|
||||
| **Capterra** | 93 | Yes | Free listing | Owned by G2 (acquired Feb 2026). Reviews drive everything. |
|
||||
| **GetApp** | 78 | Yes | Free | Auto-syncs from Capterra in some cases. Owned by G2. |
|
||||
| **SourceForge** | 92 | Yes | Free | Legacy but still high DR. Trivial to list. |
|
||||
| **Slashdot** | ~88 | Yes | Free | Legacy but high DR. Company profile submission. |
|
||||
| **Startup Stash** | ~50 | Yes | Free | Curated, organized by startup need. |
|
||||
| **SideProjectors** | ~35 | Yes | Free | Discovery + marketplace. Community-driven. |
|
||||
| **F6S** | 65 | Yes | Free | Startup platform used by accelerators. |
|
||||
| **Stackshare** | ~60 | Yes | Free | Dev-centric. Show your tech stack. |
|
||||
| **Resource.fyi** | ~40 | Yes | Free | Curated for designers/devs/marketers. |
|
||||
| **Shipybara** | ~30 | Yes | Free | Shows which companies use your tool. |
|
||||
| **TrustRadius** | 72 | Yes | Free | Smaller but respected B2B review platform. |
|
||||
| **Crozdesk** | ~55 | Yes | Free | Feeds into Gartner ecosystem. |
|
||||
| **Software Advice** | 88 | Yes | Free | Gartner property. Auto-syncs with Capterra in some categories. |
|
||||
| **TheSaaSDirectory** | 88 | Yes | Free | SaaS-specific directory. Good categorization. |
|
||||
| **Tech.co** | 80 | Yes | Free | Startup/SaaS directory + media. |
|
||||
| **Taalk** | 80 | Yes | Free | Startup directory. |
|
||||
| **Startup Fame** | 77 | Yes | Free | Startup showcase directory. |
|
||||
| **Indie Hackers** | 76 | Yes | Free | Build-in-public community + product directory. |
|
||||
| **Slant** | 75 | Yes | Free | "What is the best..." recommendation platform. |
|
||||
| **Gust** | 75 | Yes | Free | Startup/investor platform. Profile with links. |
|
||||
| **Inc42** | 75 | Yes | Free | Indian startup media + directory. |
|
||||
| **Wefunder** | 76 | Yes | Free | Equity crowdfunding. Product profile with links. |
|
||||
| **Startups.com** | 68 | Yes | Free | Startup community + resources. |
|
||||
| **IndieHustles** | 66 | Yes | Free | Indie SaaS directory. |
|
||||
| **SaaSWorthy** | 65 | Yes | Free | SaaS review/comparison site. |
|
||||
| **ToolsFine** | 65 | Yes | Free | SaaS tool directory. |
|
||||
| **Bizcommunity** | 65 | Yes | Free | Business news + directory. |
|
||||
| **StartUs** | 62 | Yes | Free | Startup directory + insights. |
|
||||
| **Today Launches** | 60 | Yes | Free | Daily launch directory. |
|
||||
| **StartupBuffer** | 57 | Yes | Free | Startup promotion platform. |
|
||||
| **Feedough** | 55 | Yes | Free | Startup resources + directory. |
|
||||
| **Indie Hacker Tools** | 55 | Yes | Free | Tools for indie hackers. |
|
||||
| **Open Launch** | 55 | Yes | Free | Product launch directory. |
|
||||
| **New SaaSly** | 52 | Yes | Free | New SaaS product directory. |
|
||||
| **Business Software** | 49 | Yes | Free | Business software directory. |
|
||||
| **Promote Project** | 47 | Yes | Free | Project promotion directory. |
|
||||
| **FiveTaco** | 47 | Yes | Free | SaaS tool directory. |
|
||||
| **Cuspera** | 45 | Yes | Free | SaaS comparison platform. |
|
||||
| **BetaBound** | 45 | Yes | Free | Beta testing community + directory. |
|
||||
| **Makerthrive** | 45 | Yes | Free | Maker community + tools. |
|
||||
| **StartupTracker** | 44 | Yes | Free | Startup tracking directory. |
|
||||
| **BusinessHunt** | 43 | Yes | Free | Business product directory. |
|
||||
| **Launched.io** | 40 | Yes | Free | Launch directory. |
|
||||
| **ProfitHunt** | 40 | Yes | Free | Profitable startup directory. |
|
||||
| **10words** | 40 | Yes | Free | SaaS directory (10-word descriptions). |
|
||||
| **TrustMRR** | 40 | Yes | Free | MRR-verified startup directory. |
|
||||
| **OpenClawDir** | 35 | Yes | Free | Open directory. |
|
||||
| **Build Voyage** | 33 | Yes | Free | Startup builder directory. |
|
||||
| **AlphaDigits** | 32 | Yes | Free | SaaS directory. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 3 — AI Tool Directories
|
||||
|
||||
Relevant only for AI-native products. Submit during weeks 1–3.
|
||||
|
||||
### Tier 3A — Flagship AI directories
|
||||
|
||||
| Directory | DR | Monthly Traffic | Notes |
|
||||
|---|---|---|---|
|
||||
| **There's An AI For That (TAAFT)** | 76 | 2M+ | Largest AI directory. Task-based search. Worth the effort to list well. |
|
||||
| **Futurepedia** | 70 | 1M+ | 5,000+ tools, 54 categories. Matt Wolfe YouTube (2M+ subs) drives traffic. |
|
||||
| **Toolify.ai** | 71 | 500K+ | 26K+ tools, 450+ categories. Tracks traffic trends. |
|
||||
| **Future Tools (futuretools.io)** | 69 | 400K+ | Curated by Matt Wolfe. Smaller but influential. |
|
||||
| **AI Tools Neilpatel** | 91 | n/a | Highest DR free AI directory. |
|
||||
| **Good AI Tools** | 66 | n/a | Curated, quality over quantity. |
|
||||
| **NewTools.site** | 51 | n/a | Dofollow backlink for every approved submission. |
|
||||
|
||||
### Tier 3B — Mid-tier AI directories
|
||||
|
||||
| Directory | Est. DR | Notes |
|
||||
|---|---|---|
|
||||
| **aitools.inc** | ~66 | "10x your output" positioning. |
|
||||
| **AIStage** | ~66 | Includes open source + news. |
|
||||
| **AItrendytools** | ~69 | Comprehensive listing. |
|
||||
| **Grabon AI Directory** | ~70 | High DR, broad audience. |
|
||||
| **TopAI.tools** | ~60 | Task-based search similar to TAAFT. |
|
||||
| **Supertools** | ~61 | Clean interface, good categorization. |
|
||||
| **AI Tools Directory** (aitoolsdirectory.com) | ~55 | Curated; featured placement available. |
|
||||
| **AI Tools Love** | ~25 | Comparison-focused. |
|
||||
| **AIChief** | ~35 | Business-focused. |
|
||||
| **LogicBalls** | ~40 | 3,500+ verified tools. |
|
||||
| **SaasAITools** | ~30 | SaaS + AI crossover. |
|
||||
| **PoweredByAI** | ~35 | Growing directory with newsletter reach. |
|
||||
| **TheAISurf** | ~30 | Newer, actively promoting submissions. |
|
||||
| **Aixyz** | ~30 | 1,500+ tools, smart filters. |
|
||||
| **AI Pedia Hub** | ~40 | "Largest directory, updated daily." |
|
||||
| **Dofollow.Tools** | ~30 | Explicitly free dofollow backlinks. |
|
||||
| **AIBacklinkList** | ~25 | Aggregated list of 2500+ AI backlink opportunities. |
|
||||
| **AI Scout** | ~25 | Emerging, less competition. |
|
||||
| **AiMatchPro** | ~20 | Use-case search. |
|
||||
| **GPTForge** | ~30 | Domain created 2025 — DR 88 from source list is implausible. Verify via Ahrefs. |
|
||||
| **AI Tools Guide** | 77 | Curated AI tools directory. |
|
||||
| **AIToolly** | 69 | AI tool discovery. |
|
||||
| **All The AI Tools** | 66 | Comprehensive AI tool listing. |
|
||||
| **Aiforme.wiki** | 66 | AI tool wiki/directory. |
|
||||
| **Noxilo** | 66 | AI tools directory. |
|
||||
| **AI Generation** | 55 | AI tools directory. |
|
||||
| **Every AI** | 55 | AI tool aggregator. |
|
||||
| **BAI.tools** | 53 | AI tools directory. |
|
||||
| **The Rundown Tools** | 40 | AI newsletter's tool directory. |
|
||||
| **AI NavHub** | 38 | AI navigation directory. |
|
||||
| **WhatTheAI** | 35 | AI tools directory. |
|
||||
| **ToolAI** | 31 | AI tools directory. |
|
||||
| **LLM Relevance** | 30 | LLM-focused directory. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 4 — AI Agent & MCP Server Registries
|
||||
|
||||
Relevant only if the product exposes agent capabilities or MCP servers. These are a real moat for AI-native tools — traditional SaaS products cannot list here.
|
||||
|
||||
| Directory | Category | Notes |
|
||||
|---|---|---|
|
||||
| **AI Agents List (aiagentslist.com)** | Agents | Hosts the 593+ MCP server directory. |
|
||||
| **Glama.ai MCP servers** | MCP | 20K+ security-graded MCP servers. A/B/C/F grades matter — optimize for a good grade. |
|
||||
| **APITracker MCP directory** | MCP | 110+ servers, 90 official integrations. |
|
||||
| **Linux Foundation MCP Registry** | MCP | Canonical registry (PR-based submission, low volume but high signal). Anthropic donated MCP to LF in Dec 2025. |
|
||||
| **AI Agent Store** | Agents | Compare agents, platforms, frameworks. |
|
||||
| **AI Agents Base** | Agents | All-in-one directory. |
|
||||
| **AI Agents Directory** | Agents | Specialized, updated daily. |
|
||||
| **AI Agents Verse** | Agents | Curated directory. |
|
||||
| **AgentHunter** | Agents | "Discover the best AI agents." |
|
||||
| **Add AI Directory** | Agents | Catalogs agents + tools. |
|
||||
| **AI Agents Live** | Agents | Discovery + sharing. |
|
||||
| **AI Agents Marketplace** | Agents | Organized by 300+ human role equivalents. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 5 — No-Code Directories
|
||||
|
||||
Relevant for no-code platforms and builder tools.
|
||||
|
||||
| Directory | Est. DR | Notes |
|
||||
|---|---|---|
|
||||
| **NoCodeFinder** | ~45 | Accepts submissions. |
|
||||
| **No Code MBA Tools Directory** | ~55 | Categorized by project type. |
|
||||
| **We Are No Code Tools Repository** | ~40 | Curated. |
|
||||
| **NoCodeList** | ~30 | — |
|
||||
| **NoCodeDevs** | ~25 | — |
|
||||
| **NoCode.Tech** | ~35 | — |
|
||||
| **MakerPad / Zapier** | ~62 | Now owned by Zapier. No-code tool directory. |
|
||||
| **NoCodeFounders** | ~45 | No-code community + forum. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 6 — "Best of" Listicles (Editorial Outreach)
|
||||
|
||||
Not directories per se — these are blog posts on high-DR domains that you get included in via cold outreach. Often more valuable than directories because they combine a dofollow backlink with editorial trust + in-market buyer traffic + AI citation weight.
|
||||
|
||||
**Search patterns to find opportunities:**
|
||||
- `"best [category] tools" 2026`
|
||||
- `"best [competitor] alternative"`
|
||||
- `"top AI [category]"`
|
||||
- `"[category] tools review"`
|
||||
|
||||
**Outreach template (short):**
|
||||
> Hey [name], saw your post on [best X tools]. We launched [product] recently — thought it might be worth a mention. Happy to give you a free account + credits for readers. Here's a 60s demo: [link]. No worries if not a fit.
|
||||
|
||||
**Target:** 10 inclusions in 30 days. Each = dofollow backlink from DR 40–70 + referral traffic + AI citation fuel.
|
||||
|
||||
---
|
||||
|
||||
## Tier 7 — Integration Marketplaces
|
||||
|
||||
Only relevant once the product has integrations. These are the highest-DR backlinks available — worth engineering effort just to land them.
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Zapier App Directory** | 91 | Requires working Zapier integration. |
|
||||
| **HubSpot App Marketplace** | 93 | Requires HubSpot app. |
|
||||
| **Slack App Directory** | 89 | Requires Slack integration. |
|
||||
| **Airtable Marketplace** | 82 | Requires Airtable integration. |
|
||||
| **Notion Integrations Gallery** | 88 | Requires Notion integration. |
|
||||
| **Make (Integromat)** | ~70 | Requires Make module. |
|
||||
| **Pipedream** | ~70 | Requires Pipedream action. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 8 — Profile & Content Platforms
|
||||
|
||||
Create a profile or publish content on these high-DR platforms to earn a dofollow backlink. These are not traditional directories — they're content and identity platforms where your profile or published content links back to your site. Highest DR backlinks available without building integrations.
|
||||
|
||||
| Platform | DR | Category | Type | Notes |
|
||||
|---|---|---|---|---|
|
||||
| **WordPress.com** | 100 | Any | Blog | Create a free blog, link to main site in posts and profile. |
|
||||
| **Blogger** | 100 | Any | Blog | Google property. Free blog with dofollow links. |
|
||||
| **Tumblr** | 99 | Design | Blog | Highest DR blog platform. Project blog or microblog. |
|
||||
| **GitHub** | 98 | Tech | Code host | Profile + repo README links. Every software product should have this. |
|
||||
| **SoundCloud** | 96 | Music | Profile | Niche — relevant for audio/music products. |
|
||||
| **Weebly** | 95 | Any | Blog | Free site builder with dofollow profile link. |
|
||||
| **SlideShare** | 95 | Any | Content | Upload pitch decks, guides, presentations. |
|
||||
| **Flickr** | 95 | Photography | Profile | Product screenshot galleries with profile link. |
|
||||
| **GitLab** | 94 | Tech | Code host | Profile link. Mirror repos if open source. |
|
||||
| **eBay Stores** | 94 | E-commerce | Profile | Niche — relevant for physical/digital goods. |
|
||||
| **Etsy** | 93 | E-commerce | Profile | Niche — templates, digital downloads. |
|
||||
| **Substack** | 93 | Tech | Newsletter | Publish product updates, thought leadership. High-intent readers. |
|
||||
| **Bitbucket** | 93 | Tech | Code host | Profile link. Atlassian property. |
|
||||
| **Scribd** | 93 | Any | Content | Upload whitepapers, guides, case studies. |
|
||||
| **Disqus** | 93 | Professional | Profile | Profile with website link. Comment on industry blogs. |
|
||||
| **Behance** | 93 | Design | Profile | Portfolio/project links. Best for design-adjacent products. |
|
||||
| **Pastebin** | 93 | Tech | Code host | Code snippets with profile link. |
|
||||
| **Patreon** | 93 | Creator | Profile | Creator page with product links. |
|
||||
| **Imgur** | 93 | Any | Profile | Image hosting with profile link. |
|
||||
| **Dun & Bradstreet** | 93 | B2B | Directory | Business credibility. Feeds AI training corpora. |
|
||||
| **Ghost.org** | 92 | Any | Blog | Publish content with dofollow links. |
|
||||
| **Evernote** | 92 | Any | Content | Public notebooks with links. |
|
||||
| **Issuu** | 92 | Any | Content | Upload marketing PDFs, brochures, reports. |
|
||||
| **CodePen** | 92 | Tech | Profile | Front-end demos and profile link. |
|
||||
| **Kaggle** | 92 | AI | Profile | AI/data science community. Notebooks with links. |
|
||||
| **Houzz** | 92 | Home | Profile | Niche — home/interior products. |
|
||||
| **LiveJournal** | 91 | Any | Blog | Legacy but high DR. Blog with dofollow links. |
|
||||
| **Bandcamp** | 91 | Music | Profile | Niche — audio products. |
|
||||
| **Dev.to** | 90 | Tech | Blog | Technical articles with dofollow links. Cross-post with canonical URL. |
|
||||
| **Gravatar** | 90 | Professional | Profile | Profile with website link. Quick setup. |
|
||||
| **Replit** | 90 | Tech | Code host | Profile link. Interactive demos. |
|
||||
| **CodeProject** | 90 | Tech | Blog | Technical articles for dev audience. |
|
||||
| **Jimdo** | 89 | Any | Blog | Free site builder with profile link. |
|
||||
| **Calameo** | 89 | Any | Content | Digital publishing platform. Upload PDFs. |
|
||||
| **Buy Me a Coffee** | 88 | Creator | Profile | Creator page with product links. |
|
||||
| **ArtStation** | 88 | Design | Profile | Portfolio for creative/design products. |
|
||||
| **500px** | 88 | Photography | Profile | Product imagery with profile link. |
|
||||
| **IndiaMART** | 87 | B2B | Profile | Indian B2B marketplace. Niche but high DR. |
|
||||
| **Strikingly** | 87 | Any | Blog | Free one-page site with backlink. |
|
||||
| **Hashnode** | 85 | Tech | Blog | Dev blogging. Custom domain support. Dofollow links. |
|
||||
| **About.me** | 85 | Professional | Profile | One-page profile. Quick dofollow backlink. |
|
||||
| **Mixcloud** | 85 | Music | Profile | Niche — audio/podcast products. |
|
||||
| **4Shared** | 85 | Any | Content | File sharing with profile link. |
|
||||
| **HubPages** | 84 | Any | Blog | Article publishing platform. |
|
||||
| **AppSumo** | 84 | E-commerce | Marketplace | SaaS deals marketplace. Great for launch visibility + backlink. |
|
||||
| **TeachersPayTeachers** | 84 | Education | Profile | Niche — education products. |
|
||||
| **AuthorStream** | 70 | Any | Content | Presentation sharing. |
|
||||
| **Model Mayhem** | 72 | Design | Profile | Niche — creative industry. |
|
||||
| **Penzu** | 60 | Any | Blog | Online journal with profile link. |
|
||||
| **Crevado** | 50 | Design | Profile | Portfolio platform. |
|
||||
| **MyFolio** | 55 | Design | Profile | Portfolio platform. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 9 — Local Business & General Directories
|
||||
|
||||
Relevant for products with a physical presence, local customer base, or business address. Also useful for any product wanting pure DR-building backlinks from established directories.
|
||||
|
||||
| Directory | DR | Category | Notes |
|
||||
|---|---|---|---|
|
||||
| **Manta** | 76 | Local business | US business directory. Free listing. |
|
||||
| **ActiveSearchResults** | 74 | General | Search engine directory. |
|
||||
| **Hotfrog** | 72 | Local business | International business directory. |
|
||||
| **Spoke** | 70 | B2B | Business profile directory. |
|
||||
| **Locanto** | 70 | General | Classifieds + business listings. International. |
|
||||
| **MerchantCircle** | 68 | Local business | US small business directory. |
|
||||
| **Just Landed** | 65 | Local business | International directory. |
|
||||
| **Showmelocal** | 64 | Local business | US local search directory. |
|
||||
| **Cylex** | 64 | Local business | International business directory. |
|
||||
| **Brownbook** | 63 | Local business | Global business directory. |
|
||||
| **Tupalo** | 62 | Local business | European business directory. |
|
||||
| **WebWiki** | 60 | General | Website directory with reviews. |
|
||||
| **iBegin** | 60 | Local business | US business directory. |
|
||||
| **CitySquares** | 55 | Local business | US local business directory. |
|
||||
| **eLocal** | 55 | Local business | US service provider directory. |
|
||||
| **2FindLocal** | 53 | Local business | US local directory. |
|
||||
| **Chamber of Commerce** | 50 | Local business | Business directory + resources. |
|
||||
| **FindUsLocal** | 50 | Local business | Local search directory. |
|
||||
| **ezlocal** | 50 | Local business | US local business listings. |
|
||||
| **Yellow Pages Goes Green** | 49 | Local business | Eco-friendly business directory. |
|
||||
| **Where To?** | 46 | Local business | Local discovery directory. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 10 — Forums & Communities
|
||||
|
||||
Create a profile and participate in relevant communities. Most give dofollow profile links. Value comes from both the backlink and referral traffic from genuine participation. Follow the 90/10 rule: 90% helpful, 10% promotional.
|
||||
|
||||
| Forum | DR | Category | Notes |
|
||||
|---|---|---|---|
|
||||
| **Strava Clubs** | 90 | Fitness | Niche — fitness/health products only. |
|
||||
| **Foursquare** | 90 | Hospitality | Business listing with dofollow link. |
|
||||
| **SitePoint Forums** | 89 | Tech | Web dev community. Genuine participation required. |
|
||||
| **Mumsnet Forums** | 85 | Family | Niche — family/parenting products. Large UK audience. |
|
||||
| **Digital Point** | 82 | Marketing | SEO/marketing forum. |
|
||||
| **WebmasterWorld** | 77 | Marketing | SEO/webmaster community. High editorial standards. |
|
||||
| **BlackHatWorld** | 77 | Marketing | SEO/marketing forum. Despite the name, has legitimate discussions. |
|
||||
| **GrowthHackers** | 76 | Marketing | Growth marketing community. Dofollow articles + profile. |
|
||||
| **Warrior Forum** | 73 | Marketing | Internet marketing community. |
|
||||
| **Apsense** | 72 | Marketing | Business networking + marketing forum. |
|
||||
| **ActiveRain** | 70 | Real estate | Niche — real estate industry. |
|
||||
| **Quibblo** | 55 | General | Quiz/poll community with profile links. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 11 — Press Release, Article & Blog Directory Sites
|
||||
|
||||
Publish articles or press releases to earn dofollow backlinks. Best for product launches, funding announcements, major feature releases. Some accept any topic, others are PR-specific.
|
||||
|
||||
### Article & Blog Directories
|
||||
|
||||
| Site | DR | Type | Notes |
|
||||
|---|---|---|---|
|
||||
| **EzineArticles** | 80 | Article | Established article directory. Editorial review. |
|
||||
| **Feedspot** | 80 | Blog directory | Blog discovery + RSS aggregation. Submit your blog. |
|
||||
| **Alltop** | 73 | Blog directory | Guy Kawasaki's blog aggregator. |
|
||||
| **ArticlesBase** | 70 | Article | Article publishing platform. |
|
||||
| **Blogarama** | 64 | Blog directory | Blog directory with categories. |
|
||||
| **Sooper Articles** | 60 | Article | Article submission site. |
|
||||
| **OnToplist** | 60 | Blog directory | Blog ranking directory. |
|
||||
| **BlogEngage** | 55 | Blog directory | Blog promotion community. |
|
||||
| **BizSugar** | 55 | Business | Small business content sharing. |
|
||||
| **TechPluto** | 50 | Marketing | Tech/marketing blog directory. |
|
||||
|
||||
### Press Release Distribution
|
||||
|
||||
| Site | DR | Notes |
|
||||
|---|---|---|
|
||||
| **PRLog** | 80 | Free press release distribution. Good reach. |
|
||||
| **PR.com** | 77 | Free + paid press releases. Business directory too. |
|
||||
| **OpenPR** | 72 | Free international press release distribution. |
|
||||
| **1888 Press Release** | 69 | Free press release site. |
|
||||
| **NewswireToday** | 65 | Free press release distribution. |
|
||||
| **Online PR News** | 62 | Free press release distribution. |
|
||||
| **PR Free** | 62 | Free press release site. |
|
||||
|
||||
### Marketing & General Directories
|
||||
|
||||
| Site | DR | Notes |
|
||||
|---|---|---|
|
||||
| **SubmissionWebDirectory** | 61 | General web directory. |
|
||||
| **Site Promotion Directory** | 46 | Marketing-focused directory. |
|
||||
| **Semfirms** | 45 | Marketing services directory. |
|
||||
| **CabinetM** | 45 | Marketing technology directory. |
|
||||
| **Cold Email Kit** | 44 | Email marketing directory. |
|
||||
| **Directory LDM Studio** | 40 | General directory. |
|
||||
| **Quality Internet Directory** | 39 | General web directory. |
|
||||
| **ProofStories** | 32 | Marketing stories/case studies. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 12 — Social Bookmarking & Curation
|
||||
|
||||
Bookmark or curate content with dofollow links. Lower effort than publishing full articles. Most useful for building diverse backlink profile.
|
||||
|
||||
| Platform | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Scoop.it** | 91 | Content curation platform. Create topic pages with links. |
|
||||
| **Diigo** | 85 | Social bookmarking + annotation. Profile + bookmark links. |
|
||||
| **Pearltrees** | 84 | Visual content curation. Organize links into collections. |
|
||||
| **BibSonomy** | 70 | Academic bookmarking. Best for research/data products. |
|
||||
| **Folkd** | 64 | Social bookmarking. Tag and share links. |
|
||||
|
||||
---
|
||||
|
||||
## Tier 13 — Niche Vertical Directories
|
||||
|
||||
Industry-specific directories. Only submit if your product genuinely fits the vertical — forced listings get rejected and waste time.
|
||||
|
||||
### Legal
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Justia** | 85 | Legal services directory. |
|
||||
| **Lawyers.com** | 82 | Legal directory. |
|
||||
| **HG.org** | 75 | Legal resources directory. |
|
||||
|
||||
### Home & Construction
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Porch** | 80 | Home services marketplace. |
|
||||
| **BuildZoom** | 73 | Construction/contractor directory. |
|
||||
| **Tradify (FreeIndex)** | 55 | UK trades directory. |
|
||||
| **iBuildNew** | 45 | Australian home building directory. |
|
||||
|
||||
### Hospitality & Food
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **AllMenus** | 76 | Restaurant directory. |
|
||||
|
||||
### Design & Creative
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **LandBook** | 72 | Web design inspiration gallery. Submit landing pages. |
|
||||
| **Curated.design** | 52 | Design inspiration directory. |
|
||||
| **Webdesign Inspiration** | 45 | Website design showcase. |
|
||||
|
||||
### Health & Fitness
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Wellness.com** | 60 | Health & wellness directory. |
|
||||
| **YogaTrail** | 55 | Yoga/wellness directory. |
|
||||
| **MassageTherapy (AMBP)** | 45 | Massage therapy directory. |
|
||||
| **Athlinks** | 72 | Fitness/race results. Profile with links. |
|
||||
| **Fit Pro Directory** | 40 | Fitness professional directory. |
|
||||
|
||||
### Real Estate
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Placester** | 60 | Real estate marketing directory. |
|
||||
|
||||
### B2B & International
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Sulekha** | 73 | Indian business directory. |
|
||||
| **EU-Business** | 46 | European business directory. |
|
||||
|
||||
### Events
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| **Evensi Events** | 62 | Event discovery platform. |
|
||||
|
||||
### Education
|
||||
|
||||
| Directory | DR | Notes |
|
||||
|---|---|---|
|
||||
| *(TeachersPayTeachers listed in Tier 8 — Profile Platforms)* | | |
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
After any submission goes live, verify the backlink exists and is dofollow. You can:
|
||||
|
||||
1. **Manual:** Open the listing, right-click your product link, "Inspect" → check for `rel="nofollow"` or `rel="ugc"`. If absent, the link is dofollow.
|
||||
2. **curl:** `curl -sIL https://directory.com/your-listing | grep -i link`
|
||||
3. **SEO tools:** Ahrefs Site Explorer → Backlinks → filter by this directory's domain.
|
||||
|
||||
**Re-verify quarterly.** Directories sometimes change all outbound links to nofollow without warning — if DR stops moving, check whether your biggest inbound links have silently flipped.
|
||||
@@ -0,0 +1,232 @@
|
||||
# Positioning Variations Library
|
||||
|
||||
Directory audiences respond to different framings. Never copy-paste the same description everywhere — AI engines penalize duplicate content, and each directory type rewards a different opener.
|
||||
|
||||
Use this library to generate per-tier variants. Swap `[product]`, `[category]`, `[competitors]`, `[use-case]`, and `[audience]` with the real values.
|
||||
|
||||
---
|
||||
|
||||
## Framework: Lead Sentence Varies by Tier
|
||||
|
||||
| Tier | Lead sentence pattern | Why |
|
||||
|---|---|---|
|
||||
| Startup / launch | "[Product] is the easiest way to [outcome] for [audience]." | Founders scan for outcome clarity. |
|
||||
| SaaS directory | "[Product] is the [differentiator] alternative to [competitors]." | Catches "[competitor] alternative" search intent. |
|
||||
| AI directory | "[Product] uses [AI capability] to [outcome]." | TAAFT/Futurepedia audiences explicitly want AI. |
|
||||
| Agent / MCP | "[Product] is an MCP-native / agent-native [category]." | Niche but high-intent. Ruling-out competitors. |
|
||||
| No-code | "[Product] lets you build [output] without code." | Audience values speed, not technical depth. |
|
||||
| Dev tool | "[Product] is a [technical category] with [differentiator]." | Devs want substance upfront. |
|
||||
| B2B review | "[Product] helps [audience] [measurable business outcome]." | Reviewers want ROI language. |
|
||||
|
||||
---
|
||||
|
||||
## Template: Startup / Launch Directories
|
||||
|
||||
**Target:** Product Hunt, BetaList, Fazier, Uneed, DevHunt, Microlaunch, OpenHunts, LaunchVault, Firsto, PitchWall
|
||||
|
||||
**Tagline (under 10 words):**
|
||||
> The [differentiator] way to [outcome] for [audience].
|
||||
|
||||
**Short description (60 chars):**
|
||||
> [Outcome-focused one-liner with product name]
|
||||
|
||||
**Long description (150 words):**
|
||||
> [Product] is the easiest way to [outcome] for [audience]. Built for teams who [pain point], [product] removes [friction] by [how].
|
||||
>
|
||||
> Unlike [competitor category], [product] [key differentiator 1] and [key differentiator 2]. You can [action 1] in under [timeframe], [action 2] without [limitation], and [action 3] that would normally require [cost or technical skill].
|
||||
>
|
||||
> We built [product] because [founder origin story in one sentence]. It's now used by [audience examples] to [use case examples].
|
||||
>
|
||||
> Try it free at [url]. No credit card, no setup.
|
||||
|
||||
**Tags:** [product category], [audience type], [use case 1], [use case 2], [differentiator], [tech]
|
||||
|
||||
---
|
||||
|
||||
## Template: SaaS / Software Directories
|
||||
|
||||
**Target:** AlternativeTo, SaaSHub, G2, Capterra, GetApp, SourceForge, Slashdot, Startup Stash, F6S
|
||||
|
||||
**Tagline:**
|
||||
> The [differentiator] alternative to [top competitors].
|
||||
|
||||
**Long description:**
|
||||
> [Product] is a [differentiator] alternative to [competitor 1], [competitor 2], and [competitor 3] — built for [audience] who need [gap the competitors don't fill].
|
||||
>
|
||||
> Where [competitor 1] [limitation 1] and [competitor 2] [limitation 2], [product] [solves]. You get [feature 1], [feature 2], and [feature 3] in a single workspace, at [pricing relative to competitors].
|
||||
>
|
||||
> Key features:
|
||||
> • [Feature 1] — [benefit]
|
||||
> • [Feature 2] — [benefit]
|
||||
> • [Feature 3] — [benefit]
|
||||
> • [Feature 4] — [benefit]
|
||||
> • [Integration 1], [Integration 2], [Integration 3] integrations
|
||||
>
|
||||
> Trusted by [audience examples]. Start free at [url].
|
||||
|
||||
**Tags:** [competitor] alternative, [category], [audience], [differentiator], [top 3 features]
|
||||
|
||||
---
|
||||
|
||||
## Template: AI Directories
|
||||
|
||||
**Target:** TAAFT, Futurepedia, Toolify, Future Tools, aitools.inc, AIStage, LogicBalls, SaasAITools
|
||||
|
||||
**Tagline:**
|
||||
> AI-powered [category] for [audience].
|
||||
|
||||
**Long description:**
|
||||
> [Product] is an AI-powered [category] that [core AI capability]. It uses [specific models / techniques] to [outcome] — so [audience] can [job to be done] in a fraction of the time.
|
||||
>
|
||||
> What makes it AI-first:
|
||||
> • [AI feature 1] — [what it does] using [model/approach]
|
||||
> • [AI feature 2] — [what it does]
|
||||
> • [AI feature 3] — [what it does]
|
||||
> • [AI feature 4] — [what it does]
|
||||
>
|
||||
> [Product] is built on [tech stack] and supports [models/providers]. Use cases: [use case 1], [use case 2], [use case 3], [use case 4].
|
||||
>
|
||||
> Free tier available. No API keys required to start.
|
||||
|
||||
**Tags:** AI [category], [AI capability 1], [AI capability 2], AI for [audience], [use case 1], [use case 2], [LLM provider], [differentiator]
|
||||
|
||||
---
|
||||
|
||||
## Template: Agent / MCP Registries
|
||||
|
||||
**Target:** Glama, APITracker, Linux Foundation MCP Registry, AI Agents List, AI Agent Store, AgentHunter
|
||||
|
||||
**Tagline:**
|
||||
> MCP-native [category] for AI agents.
|
||||
|
||||
**Long description:**
|
||||
> [Product] is an MCP-native [category] that lets AI agents [capability]. It exposes [MCP server capabilities] via the Model Context Protocol, so agents in Claude, ChatGPT, Cursor, and any MCP-compatible client can [actions].
|
||||
>
|
||||
> MCP capabilities:
|
||||
> • [Tool 1] — [what the agent can do]
|
||||
> • [Tool 2] — [what the agent can do]
|
||||
> • [Tool 3] — [what the agent can do]
|
||||
> • [Resource 1] — [context surfaced]
|
||||
> • [Prompt 1] — [pre-built prompt]
|
||||
>
|
||||
> Authentication: [auth method]. Transports: stdio, HTTP, SSE. Security: [security posture].
|
||||
>
|
||||
> Installation: [one-line install command]. Docs: [docs URL].
|
||||
|
||||
**Tags:** MCP, MCP server, AI agent, agent [category], Claude integration, Model Context Protocol, [domain], [auth type]
|
||||
|
||||
---
|
||||
|
||||
## Template: No-Code Directories
|
||||
|
||||
**Target:** NoCodeFinder, No Code MBA Tools Directory, We Are No Code, NoCode.Tech
|
||||
|
||||
**Tagline:**
|
||||
> Build [output] without code.
|
||||
|
||||
**Long description:**
|
||||
> [Product] lets you build [output] without writing code. Drag, drop, or describe what you want and [product] handles the rest — [technical concept 1] and [technical concept 2] are automatic.
|
||||
>
|
||||
> What you can build:
|
||||
> • [Example project 1] — built in [timeframe]
|
||||
> • [Example project 2] — built in [timeframe]
|
||||
> • [Example project 3] — built in [timeframe]
|
||||
>
|
||||
> No-code friendly features:
|
||||
> • [Visual feature 1]
|
||||
> • [Visual feature 2]
|
||||
> • [AI-assisted feature]
|
||||
> • [Pre-built templates]
|
||||
>
|
||||
> Start free. No credit card. Templates included.
|
||||
|
||||
**Tags:** no code, no-code [category], visual [tool], drag and drop, [output type], [audience type]
|
||||
|
||||
---
|
||||
|
||||
## Template: Dev / Technical Directories
|
||||
|
||||
**Target:** DevHunt, Stackshare, GitHub, Dev.to, Hacker News Show HN
|
||||
|
||||
**Tagline:**
|
||||
> [Technical category] with [technical differentiator].
|
||||
|
||||
**Long description:**
|
||||
> [Product] is a [technical category] built on [tech stack]. It solves [technical problem] by [technical approach].
|
||||
>
|
||||
> Architecture:
|
||||
> • [Component 1] — [tech used]
|
||||
> • [Component 2] — [tech used]
|
||||
> • [Component 3] — [tech used]
|
||||
>
|
||||
> Why it's different: [technical insight or novel approach]. We chose [trade-off] because [reason].
|
||||
>
|
||||
> Open source: [yes/no/partial]. Self-hostable: [yes/no]. License: [license].
|
||||
>
|
||||
> API: [REST / GraphQL / MCP / gRPC]. SDKs: [languages]. Docs: [url].
|
||||
|
||||
**Tags:** [language], [framework], [category], open source, API, [tech stack component], [architecture approach]
|
||||
|
||||
---
|
||||
|
||||
## Template: B2B Review Platforms
|
||||
|
||||
**Target:** G2, Capterra, TrustRadius, GetApp, Gartner Digital Markets, Crozdesk
|
||||
|
||||
**Tagline:**
|
||||
> [Business outcome] for [audience].
|
||||
|
||||
**Long description:**
|
||||
> [Product] helps [audience] [achieve measurable business outcome]. Teams use it to [use case 1], [use case 2], and [use case 3] — reducing [metric] by [percentage] and increasing [metric] by [percentage].
|
||||
>
|
||||
> Key benefits:
|
||||
> • [Business benefit 1] with [how measured]
|
||||
> • [Business benefit 2] with [how measured]
|
||||
> • [Business benefit 3] with [how measured]
|
||||
>
|
||||
> Integrations: [enterprise integrations — HubSpot, Salesforce, Slack, etc.]
|
||||
>
|
||||
> Security: [SOC 2 / GDPR / compliance posture]. Support: [support tier]. Pricing: [pricing range].
|
||||
>
|
||||
> Trusted by [customer logos / company size]. Case studies at [url].
|
||||
|
||||
**Tags:** [business use case], [vertical], [audience role], [compliance], enterprise [category], [integration 1]
|
||||
|
||||
---
|
||||
|
||||
## Category Tag Library
|
||||
|
||||
Pull 5–8 tags per submission from the relevant sections. Never repeat the exact same tag set across two directories in the same tier.
|
||||
|
||||
### Universal
|
||||
[category], [audience], [differentiator], [use case], AI, no-code, SaaS, [tech stack]
|
||||
|
||||
### Industry
|
||||
B2B, B2C, DTC, ecommerce, fintech, edtech, healthtech, martech, devtools, productivity, creator tools, agency tools
|
||||
|
||||
### Job-to-be-done
|
||||
lead generation, lead qualification, customer onboarding, product recommendation, sales enablement, marketing automation, survey, assessment, calculator, quiz, intake form
|
||||
|
||||
### AI-specific
|
||||
AI agent, LLM, generative AI, conversational AI, RAG, MCP, agent framework, AI form, AI quiz, AI assistant, AI automation
|
||||
|
||||
### Technical
|
||||
open source, self-hosted, API-first, webhook, Zapier, no-code, low-code, embeddable, white-label, multi-tenant, SSO, SAML
|
||||
|
||||
---
|
||||
|
||||
## Do / Don't Quick Reference
|
||||
|
||||
**DO:**
|
||||
- Vary the opening sentence across tiers
|
||||
- Use real numbers and specific differentiators
|
||||
- Match tone to audience (technical for devs, business for G2, excited for PH)
|
||||
- Include a founder/origin angle in startup directories
|
||||
- Lead with the AI-first angle in AI directories
|
||||
|
||||
**DON'T:**
|
||||
- Copy-paste the same 150-word description everywhere
|
||||
- Use vague claims ("blazing fast", "game-changing")
|
||||
- Mention every feature — pick 3–5 per tier and rotate them
|
||||
- Lie about competitor features (AI engines cross-reference and de-rank)
|
||||
- Skip the tag list — it's how moderators route you to the right category
|
||||
@@ -0,0 +1,266 @@
|
||||
Directory,Tier,URL,Category,DR,Dofollow,Submission Date,Status,Live URL,Backlink Verified,Positioning Variant Used,Tags Used,Account Email,Notes
|
||||
Product Hunt,1,https://producthunt.com/posts/new,Launch,91,Yes,,Draft,,,Startup,,,
|
||||
Hacker News (Show HN),1,https://news.ycombinator.com/submit,Launch,91,No,,Draft,,,Dev,,,
|
||||
BetaList,1,https://betalist.com/submit,Launch,64,Yes,,Draft,,,Startup,,,
|
||||
Fazier,1,https://fazier.com/submit,Launch,30,Yes,,Draft,,,Startup,,,
|
||||
DevHunt,1,https://devhunt.org/submit,Launch,35,Yes,,Draft,,,Dev,,,
|
||||
Uneed,1,https://uneed.best/submit-a-tool,Launch,40,Yes,,Draft,,,Startup,,,
|
||||
Microlaunch,1,https://microlaunch.net/submit,Launch,30,Yes,,Draft,,,Startup,,,
|
||||
OpenHunts,1,https://openhunts.com/submit,Launch,25,Yes,,Draft,,,Startup,,,
|
||||
LaunchVault,1,https://launchvault.com/submit,Launch,20,Yes,,Draft,,,Startup,,,
|
||||
What Launched Today,1,https://whatlaunchedtoday.com,Launch,20,Yes,,Draft,,,Startup,,,
|
||||
Launching Next,1,https://launchingnext.com/submit,Launch,30,Yes,,Draft,,,Startup,,,
|
||||
PeerPush,1,https://peerpush.net/submit,Launch,25,Yes,,Draft,,,Startup,,,
|
||||
Firsto,1,https://firsto.co/submit,Launch,25,Yes,,Draft,,,Startup,,,
|
||||
GetByte,1,https://getbyte.co/submit,Launch,20,Yes,,Draft,,,Startup,,,
|
||||
Best of Web,1,https://bestofweb.io/submit,Launch,30,Yes,,Draft,,,Startup,,,
|
||||
Tiny Launch,1,https://tinylaunch.com/submit,Launch,20,Yes,,Draft,,,Startup,,,
|
||||
PitchWall,1,https://pitchwall.co/submit,Launch,25,Yes,,Draft,,,Startup,,,
|
||||
AlternativeTo,2,https://alternativeto.net/software/_/add/,SaaS,79,No,,Draft,,,SaaS,,,
|
||||
SaaSHub,2,https://saashub.com/submit,SaaS,77,Yes,,Draft,,,SaaS,,,
|
||||
G2,2,https://my.g2.com/sellers/welcome,SaaS,92,Yes,,Draft,,,B2B review,,,
|
||||
Capterra,2,https://www.capterra.com/vendors,SaaS,93,Yes,,Draft,,,B2B review,,,
|
||||
GetApp,2,https://www.getapp.com/vendors,SaaS,78,Yes,,Draft,,,B2B review,,,
|
||||
SourceForge,2,https://sourceforge.net/user/register,SaaS,92,Yes,,Draft,,,SaaS,,,
|
||||
Slashdot,2,https://slashdot.org/submission,SaaS,88,Yes,,Draft,,,SaaS,,,
|
||||
Startup Stash,2,https://startupstash.com/submit,SaaS,50,Yes,,Draft,,,Startup,,,
|
||||
SideProjectors,2,https://www.sideprojectors.com/project/new,SaaS,35,Yes,,Draft,,,Startup,,,
|
||||
F6S,2,https://www.f6s.com/company/create,SaaS,65,Yes,,Draft,,,Startup,,,
|
||||
Stackshare,2,https://stackshare.io/new-product,SaaS,60,Yes,,Draft,,,Dev,,,
|
||||
TrustRadius,2,https://www.trustradius.com/vendors,SaaS,72,Yes,,Draft,,,B2B review,,,
|
||||
Crozdesk,2,https://crozdesk.com/vendors,SaaS,55,Yes,,Draft,,,SaaS,,,
|
||||
There's An AI For That,3,https://theresanaiforthat.com/submit,AI,76,Yes,,Draft,,,AI,,,
|
||||
Futurepedia,3,https://www.futurepedia.io/submit-tool,AI,70,Yes,,Draft,,,AI,,,
|
||||
Toolify.ai,3,https://www.toolify.ai/submit,AI,71,Yes,,Draft,,,AI,,,
|
||||
Future Tools,3,https://www.futuretools.io/submit-a-tool,AI,69,Yes,,Draft,,,AI,,,
|
||||
AI Tools Neilpatel,3,https://neilpatel.com/ai-tools,AI,91,Yes,,Draft,,,AI,,,
|
||||
Good AI Tools,3,https://goodaitools.com/submit,AI,66,Yes,,Draft,,,AI,,,
|
||||
NewTools.site,3,https://newtools.site/submit,AI,51,Yes,,Draft,,,AI,,,
|
||||
aitools.inc,3,https://aitools.inc/submit,AI,66,Yes,,Draft,,,AI,,,
|
||||
AIStage,3,https://aistage.net/submit,AI,66,Yes,,Draft,,,AI,,,
|
||||
AItrendytools,3,https://www.aitrendytools.com/submit,AI,69,Yes,,Draft,,,AI,,,
|
||||
Grabon AI Directory,3,https://www.grabon.in/indulge/ai-tools/submit,AI,70,Yes,,Draft,,,AI,,,
|
||||
TopAI.tools,3,https://topai.tools/submit,AI,60,Yes,,Draft,,,AI,,,
|
||||
Supertools,3,https://supertools.therundown.ai/submit,AI,61,Yes,,Draft,,,AI,,,
|
||||
AI Tools Directory,3,https://aitoolsdirectory.com/submit,AI,55,Yes,,Draft,,,AI,,,
|
||||
LogicBalls,3,https://logicballs.com/submit,AI,40,Yes,,Draft,,,AI,,,
|
||||
SaasAITools,3,https://saasaitools.com/submit,AI,30,Yes,,Draft,,,AI,,,
|
||||
PoweredByAI,3,https://poweredbyai.app/submit,AI,35,Yes,,Draft,,,AI,,,
|
||||
TheAISurf,3,https://theaisurf.com/submit,AI,30,Yes,,Draft,,,AI,,,
|
||||
Aixyz,3,https://ai.xyz/submit,AI,30,Yes,,Draft,,,AI,,,
|
||||
AI Pedia Hub,3,https://aipediahub.com/submit,AI,40,Yes,,Draft,,,AI,,,
|
||||
Dofollow.Tools,3,https://dofollow.tools/submit,AI,30,Yes,,Draft,,,AI,,,
|
||||
AI Scout,3,https://aiscout.net/submit,AI,25,Yes,,Draft,,,AI,,,
|
||||
AiMatchPro,3,https://aimatchpro.ai/submit,AI,20,Yes,,Draft,,,AI,,,
|
||||
AIChief,3,https://aichief.com/submit,AI,35,Yes,,Draft,,,AI,,,
|
||||
AI Tools Love,3,https://aitools.love/submit,AI,25,Yes,,Draft,,,AI,,,
|
||||
AI Agents List,4,https://aiagentslist.com/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
Glama.ai MCP,4,https://glama.ai/mcp/servers,MCP,,Yes,,Draft,,,MCP,,,
|
||||
APITracker MCP,4,https://apitracker.io/mcp-servers,MCP,,Yes,,Draft,,,MCP,,,
|
||||
Linux Foundation MCP Registry,4,https://github.com/modelcontextprotocol/registry,MCP,,Yes,,Draft,,,MCP,,,
|
||||
AI Agent Store,4,https://aiagentstore.ai/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
AI Agents Base,4,https://aiagentsbase.com/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
AI Agents Directory,4,https://aiagentsdirectory.com/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
AgentHunter,4,https://agenthunter.com/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
AI Agents Live,4,https://aiagents.live/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
AI Agents Marketplace,4,https://aiagentsmarketplace.com/submit,Agent,,Yes,,Draft,,,Agent,,,
|
||||
NoCodeFinder,5,https://www.nocodefinder.com/submit,No-Code,45,Yes,,Draft,,,No-code,,,
|
||||
No Code MBA,5,https://www.nocode.mba/tools/submit,No-Code,55,Yes,,Draft,,,No-code,,,
|
||||
We Are No Code,5,https://www.wearenocode.com/submit,No-Code,40,Yes,,Draft,,,No-code,,,
|
||||
NoCodeList,5,https://nocodelist.co/submit,No-Code,30,Yes,,Draft,,,No-code,,,
|
||||
NoCodeDevs,5,https://www.nocodedevs.com/submit,No-Code,25,Yes,,Draft,,,No-code,,,
|
||||
NoCode.Tech,5,https://www.nocode.tech/submit,No-Code,35,Yes,,Draft,,,No-code,,,
|
||||
Zapier App Directory,7,https://zapier.com/developer,Integration,91,Yes,,Draft,,,Integration,,,
|
||||
HubSpot App Marketplace,7,https://ecosystem.hubspot.com/marketplace,Integration,93,Yes,,Draft,,,Integration,,,
|
||||
Slack App Directory,7,https://api.slack.com/apps,Integration,89,Yes,,Draft,,,Integration,,,
|
||||
Airtable Marketplace,7,https://airtable.com/marketplace,Integration,82,Yes,,Draft,,,Integration,,,
|
||||
Notion Integrations,7,https://www.notion.so/integrations,Integration,88,Yes,,Draft,,,Integration,,,
|
||||
Make (Integromat),7,https://www.make.com/en/partners,Integration,70,Yes,,Draft,,,Integration,,,
|
||||
Pipedream,7,https://pipedream.com/docs/components,Integration,70,Yes,,Draft,,,Integration,,,
|
||||
Software Advice,2,https://www.softwareadvice.com/vendors,SaaS,88,Yes,,Draft,,,B2B review,,,
|
||||
TheSaaSDirectory,2,https://thesaasdirectory.com,SaaS,88,Yes,,Draft,,,SaaS,,,
|
||||
Tech.co,2,https://tech.co,SaaS,80,Yes,,Draft,,,SaaS,,,
|
||||
Taalk,2,https://taalk.com,Startup,80,Yes,,Draft,,,Startup,,,
|
||||
Startup Fame,2,https://startupfa.me,Startup,77,Yes,,Draft,,,Startup,,,
|
||||
Indie Hackers,2,https://www.indiehackers.com,SaaS,76,Yes,,Draft,,,Startup,,,
|
||||
Slant,2,https://www.slant.co,SaaS,75,Yes,,Draft,,,SaaS,,,
|
||||
Gust,2,https://gust.com,Startup,75,Yes,,Draft,,,Startup,,,
|
||||
Inc42,2,https://inc42.com,Startup,75,Yes,,Draft,,,Startup,,,
|
||||
Wefunder,2,https://wefunder.com,Startup,76,Yes,,Draft,,,Startup,,,
|
||||
Startups.com,2,https://www.startups.com,Startup,68,Yes,,Draft,,,Startup,,,
|
||||
IndieHustles,2,https://www.indiehustles.com,SaaS,66,Yes,,Draft,,,SaaS,,,
|
||||
SaaSWorthy,2,https://www.saasworthy.com,SaaS,65,Yes,,Draft,,,SaaS,,,
|
||||
ToolsFine,2,https://toolsfine.com,SaaS,65,Yes,,Draft,,,SaaS,,,
|
||||
Bizcommunity,2,https://www.bizcommunity.com,B2B,65,Yes,,Draft,,,B2B,,,
|
||||
StartUs,2,https://startus.cc,Startup,62,Yes,,Draft,,,Startup,,,
|
||||
Today Launches,2,https://todaylaunches.com,Startup,60,Yes,,Draft,,,Startup,,,
|
||||
StartupBuffer,2,https://startupbuffer.com,Startup,57,Yes,,Draft,,,Startup,,,
|
||||
Feedough,2,https://www.feedough.com,Startup,55,Yes,,Draft,,,Startup,,,
|
||||
Indie Hacker Tools,2,https://www.indiehacker.tools,Startup,55,Yes,,Draft,,,Startup,,,
|
||||
Open Launch,2,https://open-launch.com,Startup,55,Yes,,Draft,,,Startup,,,
|
||||
New SaaSly,2,https://newsaasly.com,SaaS,52,Yes,,Draft,,,SaaS,,,
|
||||
Business Software,2,https://www.business-software.com,SaaS,49,Yes,,Draft,,,SaaS,,,
|
||||
Promote Project,2,https://www.promoteproject.com,Startup,47,Yes,,Draft,,,Startup,,,
|
||||
FiveTaco,2,https://fivetaco.com,SaaS,47,Yes,,Draft,,,SaaS,,,
|
||||
Cuspera,2,https://www.cuspera.com,SaaS,45,Yes,,Draft,,,SaaS,,,
|
||||
BetaBound,2,https://betabound.com,Startup,45,Yes,,Draft,,,Startup,,,
|
||||
Makerthrive,2,https://makerthrive.com,Startup,45,Yes,,Draft,,,Startup,,,
|
||||
StartupTracker,2,https://startuptracker.io,Startup,44,Yes,,Draft,,,Startup,,,
|
||||
BusinessHunt,2,https://businesshunt.co,SaaS,43,Yes,,Draft,,,SaaS,,,
|
||||
Launched.io,2,https://launched.io,Startup,40,Yes,,Draft,,,Startup,,,
|
||||
ProfitHunt,2,https://profithunt.co,Startup,40,Yes,,Draft,,,Startup,,,
|
||||
10words,2,https://10words.io,SaaS,40,Yes,,Draft,,,SaaS,,,
|
||||
TrustMRR,2,https://trustmrr.com,Startup,40,Yes,,Draft,,,Startup,,,
|
||||
OpenClawDir,2,https://openclawdir.com,Tech,35,Yes,,Draft,,,Dev,,,
|
||||
Build Voyage,2,https://buildvoyage.com,Startup,33,Yes,,Draft,,,Startup,,,
|
||||
AlphaDigits,2,https://alphadigits.com,SaaS,32,Yes,,Draft,,,SaaS,,,
|
||||
GPTForge,3,https://gptforge.net,AI,30,Yes,,Draft,,,AI,,,Domain created 2025 — DR 88 from source list is implausible
|
||||
AI Tools Guide,3,https://aitoolsguide.com,AI,77,Yes,,Draft,,,AI,,,
|
||||
AIToolly,3,https://aitoolly.com,AI,69,Yes,,Draft,,,AI,,,
|
||||
All The AI Tools,3,https://alltheaitools.com,AI,66,Yes,,Draft,,,AI,,,
|
||||
Aiforme.wiki,3,https://aiforme.wiki,AI,66,Yes,,Draft,,,AI,,,
|
||||
Noxilo,3,https://noxilo.com,AI,66,Yes,,Draft,,,AI,,,
|
||||
AI Generation,3,https://www.theaigeneration.com,AI,55,Yes,,Draft,,,AI,,,
|
||||
Every AI,3,https://every-ai.com,AI,55,Yes,,Draft,,,AI,,,
|
||||
BAI.tools,3,https://bai.tools,AI,53,Yes,,Draft,,,AI,,,
|
||||
The Rundown Tools,3,https://www.rundown.ai/tools,AI,40,Yes,,Draft,,,AI,,,
|
||||
AI NavHub,3,https://ainavhub.com,AI,38,Yes,,Draft,,,AI,,,
|
||||
WhatTheAI,3,https://whattheai.tech,AI,35,Yes,,Draft,,,AI,,,
|
||||
ToolAI,3,https://toolai.io,AI,31,Yes,,Draft,,,AI,,,
|
||||
LLM Relevance,3,https://www.llmrelevance.com,AI,30,Yes,,Draft,,,AI,,,
|
||||
MakerPad / Zapier,5,https://www.makerpad.co,No-Code,62,Yes,,Draft,,,No-code,,,
|
||||
NoCodeFounders,5,https://www.nocodefounders.com,No-Code,45,Yes,,Draft,,,No-code,,,
|
||||
WordPress.com,8,https://wordpress.com,Blog,100,Yes,,Draft,,,Profile,,,
|
||||
Blogger,8,https://www.blogger.com,Blog,100,Yes,,Draft,,,Profile,,,
|
||||
Tumblr,8,https://www.tumblr.com,Blog,99,Yes,,Draft,,,Profile,,,
|
||||
GitHub,8,https://github.com,Tech,98,Yes,,Draft,,,Profile,,,
|
||||
SoundCloud,8,https://soundcloud.com,Music,96,Yes,,Draft,,,Profile,,,
|
||||
Weebly,8,https://www.weebly.com,Blog,95,Yes,,Draft,,,Profile,,,
|
||||
SlideShare,8,https://www.slideshare.net,Content,95,Yes,,Draft,,,Profile,,,
|
||||
Flickr,8,https://www.flickr.com,Photography,95,Yes,,Draft,,,Profile,,,
|
||||
GitLab,8,https://gitlab.com,Tech,94,Yes,,Draft,,,Profile,,,
|
||||
eBay Stores,8,https://www.ebay.com,E-commerce,94,Yes,,Draft,,,Profile,,,
|
||||
Etsy,8,https://www.etsy.com,E-commerce,93,Yes,,Draft,,,Profile,,,
|
||||
Substack,8,https://substack.com,Newsletter,93,Yes,,Draft,,,Profile,,,
|
||||
Bitbucket,8,https://bitbucket.org,Tech,93,Yes,,Draft,,,Profile,,,
|
||||
Scribd,8,https://www.scribd.com,Content,93,Yes,,Draft,,,Profile,,,
|
||||
Disqus,8,https://disqus.com,Professional,93,Yes,,Draft,,,Profile,,,
|
||||
Behance,8,https://www.behance.net,Design,93,Yes,,Draft,,,Profile,,,
|
||||
Pastebin,8,https://pastebin.com,Tech,93,Yes,,Draft,,,Profile,,,
|
||||
Patreon,8,https://www.patreon.com,Creator,93,Yes,,Draft,,,Profile,,,
|
||||
Imgur,8,https://imgur.com,Content,93,Yes,,Draft,,,Profile,,,
|
||||
Dun & Bradstreet,8,https://www.dnb.com,B2B,93,Yes,,Draft,,,Profile,,,
|
||||
Ghost.org,8,https://ghost.org,Blog,92,Yes,,Draft,,,Profile,,,
|
||||
Evernote,8,https://evernote.com,Content,92,Yes,,Draft,,,Profile,,,
|
||||
Issuu,8,https://issuu.com,Content,92,Yes,,Draft,,,Profile,,,
|
||||
CodePen,8,https://codepen.io,Tech,92,Yes,,Draft,,,Profile,,,
|
||||
Kaggle,8,https://www.kaggle.com,AI,92,Yes,,Draft,,,Profile,,,
|
||||
Houzz,8,https://www.houzz.com,Home,92,Yes,,Draft,,,Profile,,,
|
||||
LiveJournal,8,https://www.livejournal.com,Blog,91,Yes,,Draft,,,Profile,,,
|
||||
Bandcamp,8,https://bandcamp.com,Music,91,Yes,,Draft,,,Profile,,,
|
||||
Dev.to,8,https://dev.to,Tech,90,Yes,,Draft,,,Profile,,,
|
||||
Gravatar,8,https://gravatar.com,Professional,90,Yes,,Draft,,,Profile,,,
|
||||
Replit,8,https://replit.com,Tech,90,Yes,,Draft,,,Profile,,,
|
||||
CodeProject,8,https://www.codeproject.com,Tech,90,Yes,,Draft,,,Profile,,,
|
||||
Jimdo,8,https://www.jimdo.com,Blog,89,Yes,,Draft,,,Profile,,,
|
||||
Calameo,8,https://www.calameo.com,Content,89,Yes,,Draft,,,Profile,,,
|
||||
Buy Me a Coffee,8,https://www.buymeacoffee.com,Creator,88,Yes,,Draft,,,Profile,,,
|
||||
ArtStation,8,https://www.artstation.com,Design,88,Yes,,Draft,,,Profile,,,
|
||||
500px,8,https://500px.com,Photography,88,Yes,,Draft,,,Profile,,,
|
||||
AppSumo,8,https://appsumo.com,E-commerce,84,Yes,,Draft,,,Profile,,,
|
||||
IndiaMART,8,https://www.indiamart.com,B2B,87,Yes,,Draft,,,Profile,,,
|
||||
Strikingly,8,https://www.strikingly.com,Blog,87,Yes,,Draft,,,Profile,,,
|
||||
Hashnode,8,https://hashnode.com,Tech,85,Yes,,Draft,,,Profile,,,
|
||||
About.me,8,https://about.me,Professional,85,Yes,,Draft,,,Profile,,,
|
||||
Mixcloud,8,https://www.mixcloud.com,Music,85,Yes,,Draft,,,Profile,,,
|
||||
4Shared,8,https://www.4shared.com,Content,85,Yes,,Draft,,,Profile,,,
|
||||
HubPages,8,https://hubpages.com,Blog,84,Yes,,Draft,,,Profile,,,
|
||||
TeachersPayTeachers,8,https://www.teacherspayteachers.com,Education,84,Yes,,Draft,,,Profile,,,
|
||||
AuthorStream,8,https://www.authorstream.com,Content,70,Yes,,Draft,,,Profile,,,
|
||||
Model Mayhem,8,https://www.modelmayhem.com,Design,72,Yes,,Draft,,,Profile,,,
|
||||
Penzu,8,https://penzu.com,Blog,60,Yes,,Draft,,,Profile,,,
|
||||
Crevado,8,https://crevado.com,Design,50,Yes,,Draft,,,Profile,,,
|
||||
MyFolio,8,https://myfolio.com,Design,55,Yes,,Draft,,,Profile,,,
|
||||
Manta,9,https://www.manta.com,Local business,76,Yes,,Draft,,,Local,,,
|
||||
ActiveSearchResults,9,https://www.activesearchresults.com,Local business,74,Yes,,Draft,,,Local,,,
|
||||
Hotfrog,9,https://www.hotfrog.com,Local business,72,Yes,,Draft,,,Local,,,
|
||||
Spoke,9,https://www.spoke.com,Local business,70,Yes,,Draft,,,Local,,,
|
||||
Locanto,9,https://www.locanto.com,General,70,Yes,,Draft,,,Local,,,
|
||||
MerchantCircle,9,https://www.merchantcircle.com,Local business,68,Yes,,Draft,,,Local,,,
|
||||
Just Landed,9,https://www.justlanded.com,Local business,65,Yes,,Draft,,,Local,,,
|
||||
Showmelocal,9,https://www.showmelocal.com,Local business,64,Yes,,Draft,,,Local,,,
|
||||
Cylex,9,https://www.cylex.us.com,Local business,64,Yes,,Draft,,,Local,,,
|
||||
Brownbook,9,https://www.brownbook.net,Local business,63,Yes,,Draft,,,Local,,,
|
||||
Tupalo,9,https://tupalo.com,Local business,62,Yes,,Draft,,,Local,,,
|
||||
WebWiki,9,https://www.webwiki.com,Local business,60,Yes,,Draft,,,Local,,,
|
||||
iBegin,9,https://www.ibegin.com,Local business,60,Yes,,Draft,,,Local,,,
|
||||
CitySquares,9,https://citysquares.com,Local business,55,Yes,,Draft,,,Local,,,
|
||||
eLocal,9,https://elocal.com,Local business,55,Yes,,Draft,,,Local,,,
|
||||
2FindLocal,9,https://www.2findlocal.com,Local business,53,Yes,,Draft,,,Local,,,
|
||||
Chamber of Commerce,9,https://www.chamberofcommerce.com,Local business,50,Yes,,Draft,,,Local,,,
|
||||
FindUsLocal,9,https://www.finduslocal.com,Local business,50,Yes,,Draft,,,Local,,,
|
||||
ezlocal,9,https://www.ezlocal.com,Local business,50,Yes,,Draft,,,Local,,,
|
||||
Yellow Pages Goes Green,9,https://www.yellowpagesgoesgreen.org,Local business,49,Yes,,Draft,,,Local,,,
|
||||
Where To?,9,https://www.where2go.com,Local business,46,Yes,,Draft,,,Local,,,
|
||||
SitePoint Forums,10,https://www.sitepoint.com/community,Tech,89,Yes,,Draft,,,Forum,,,
|
||||
Mumsnet Forums,10,https://www.mumsnet.com/Talk,Family,85,Yes,,Draft,,,Forum,,,
|
||||
Digital Point,10,https://forums.digitalpoint.com,Marketing,82,Yes,,Draft,,,Forum,,,
|
||||
WebmasterWorld,10,https://www.webmasterworld.com,Marketing,77,Yes,,Draft,,,Forum,,,
|
||||
BlackHatWorld,10,https://www.blackhatworld.com,Marketing,77,Yes,,Draft,,,Forum,,,
|
||||
GrowthHackers,10,https://growthhackers.com,Marketing,76,Yes,,Draft,,,Forum,,,
|
||||
Warrior Forum,10,https://www.warriorforum.com,Marketing,73,Yes,,Draft,,,Forum,,,
|
||||
Apsense,10,https://www.apsense.com,Marketing,72,Yes,,Draft,,,Forum,,,
|
||||
Strava Clubs,10,https://www.strava.com,Fitness,90,Yes,,Draft,,,Forum,,,
|
||||
Foursquare,10,https://business.foursquare.com,Hospitality,90,Yes,,Draft,,,Forum,,,
|
||||
ActiveRain,10,https://activerain.com,Real estate,70,Yes,,Draft,,,Forum,,,
|
||||
Quibblo,10,https://www.quibblo.com,General,55,Yes,,Draft,,,Forum,,,
|
||||
EzineArticles,11,https://ezinearticles.com,Article,80,Yes,,Draft,,,Article,,,
|
||||
PRLog,11,https://www.prlog.org,Press release,80,Yes,,Draft,,,PR,,,
|
||||
Feedspot,11,https://www.feedspot.com,Blog directory,80,Yes,,Draft,,,Article,,,
|
||||
PR.com,11,https://www.pr.com,Press release,77,Yes,,Draft,,,PR,,,
|
||||
Alltop,11,https://alltop.com,Blog directory,73,Yes,,Draft,,,Article,,,
|
||||
OpenPR,11,https://www.openpr.com,Press release,72,Yes,,Draft,,,PR,,,
|
||||
ArticlesBase,11,https://www.articlesbase.com,Article,70,Yes,,Draft,,,Article,,,
|
||||
1888 Press Release,11,https://www.1888pressrelease.com,Press release,69,Yes,,Draft,,,PR,,,
|
||||
NewswireToday,11,https://www.newswiretoday.com,Press release,65,Yes,,Draft,,,PR,,,
|
||||
Blogarama,11,https://www.blogarama.com,Blog directory,64,Yes,,Draft,,,Article,,,
|
||||
Online PR News,11,https://www.onlineprnews.com,Press release,62,Yes,,Draft,,,PR,,,
|
||||
PR Free,11,https://www.pr-free.com,Press release,62,Yes,,Draft,,,PR,,,
|
||||
SubmissionWebDirectory,11,https://www.submissionwebdirectory.com,General,61,Yes,,Draft,,,Article,,,
|
||||
Sooper Articles,11,https://www.sooperarticles.com,Article,60,Yes,,Draft,,,Article,,,
|
||||
OnToplist,11,https://www.ontoplist.com,Blog directory,60,Yes,,Draft,,,Article,,,
|
||||
BlogEngage,11,https://www.blogengage.com,Blog directory,55,Yes,,Draft,,,Article,,,
|
||||
BizSugar,11,https://www.bizsugar.com,Business,55,Yes,,Draft,,,Article,,,
|
||||
TechPluto,11,https://www.techpluto.com,Marketing,50,Yes,,Draft,,,Article,,,
|
||||
Semfirms,11,https://www.semfirms.com,Marketing,45,Yes,,Draft,,,Article,,,
|
||||
CabinetM,11,https://www.cabinetm.com,Marketing,45,Yes,,Draft,,,Article,,,
|
||||
Cold Email Kit,11,https://coldemailkit.com,Marketing,44,Yes,,Draft,,,Article,,,
|
||||
Directory LDM Studio,11,https://www.directory.ldmstudio.com,General,40,Yes,,Draft,,,Article,,,
|
||||
Quality Internet Directory,11,https://www.qualityinternetdirectory.com,General,39,Yes,,Draft,,,Article,,,
|
||||
Site Promotion Directory,11,https://www.sitepromotiondirectory.com,Marketing,46,Yes,,Draft,,,Article,,,
|
||||
ProofStories,11,https://proofstories.io,Marketing,32,Yes,,Draft,,,Article,,,
|
||||
Scoop.it,12,https://www.scoop.it,Curation,91,Yes,,Draft,,,Bookmarking,,,
|
||||
Diigo,12,https://www.diigo.com,Bookmarking,85,Yes,,Draft,,,Bookmarking,,,
|
||||
Pearltrees,12,https://www.pearltrees.com,Bookmarking,84,Yes,,Draft,,,Bookmarking,,,
|
||||
BibSonomy,12,https://www.bibsonomy.org,Research,70,Yes,,Draft,,,Bookmarking,,,
|
||||
Folkd,12,https://www.folkd.com,Bookmarking,64,Yes,,Draft,,,Bookmarking,,,
|
||||
Justia,13,https://www.justia.com,Legal,85,Yes,,Draft,,,Niche,,,
|
||||
Lawyers.com,13,https://www.lawyers.com,Legal,82,Yes,,Draft,,,Niche,,,
|
||||
Porch,13,https://porch.com,Home,80,Yes,,Draft,,,Niche,,,
|
||||
AllMenus,13,https://www.allmenus.com,Hospitality,76,Yes,,Draft,,,Niche,,,
|
||||
HG.org,13,https://www.hg.org,Legal,75,Yes,,Draft,,,Niche,,,
|
||||
Sulekha,13,https://www.sulekha.com,B2B,73,Yes,,Draft,,,Niche,,,
|
||||
BuildZoom,13,https://www.buildzoom.com,Home,73,Yes,,Draft,,,Niche,,,
|
||||
LandBook,13,https://land-book.com,Design,72,Yes,,Draft,,,Niche,,,
|
||||
Athlinks,13,https://www.athlinks.com,Fitness,72,Yes,,Draft,,,Niche,,,
|
||||
Evensi Events,13,https://evensi.com,Events,62,Yes,,Draft,,,Niche,,,
|
||||
Wellness.com,13,https://www.wellness.com,Health,60,Yes,,Draft,,,Niche,,,
|
||||
Placester,13,https://placester.com,Real estate,60,Yes,,Draft,,,Niche,,,
|
||||
YogaTrail,13,https://www.yogatrail.com,Health,55,Yes,,Draft,,,Niche,,,
|
||||
Tradify (FreeIndex),13,https://www.freeindex.co.uk,Home,55,Yes,,Draft,,,Niche,,,
|
||||
Webdesign Inspiration,13,https://webdesign-inspiration.com,Design,45,Yes,,Draft,,,Niche,,,
|
||||
iBuildNew,13,https://www.ibuildnew.com.au,Home,45,Yes,,Draft,,,Niche,,,
|
||||
EU-Business,13,https://www.eu-business.com,B2B,46,Yes,,Draft,,,Niche,,,
|
||||
MassageTherapy (AMBP),13,https://www.massagetherapy.com,Health,45,Yes,,Draft,,,Niche,,,
|
||||
Fit Pro Directory,13,https://fitprofessionals.net,Fitness,40,Yes,,Draft,,,Niche,,,
|
||||
Curated.design,13,https://www.curated.design,Design,52,Yes,,Draft,,,Niche,,,
|
||||
|
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: email-sequence
|
||||
description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," or "lifecycle emails." For in-app onboarding, see onboarding-cro.
|
||||
name: emails
|
||||
description: When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email program. Also use when the user mentions "email sequence," "drip campaign," "nurture sequence," "onboarding emails," "welcome sequence," "re-engagement emails," "email automation," "lifecycle emails," "trigger-based emails," "email funnel," "email workflow," "what emails should I send," "welcome series," or "email cadence." Use this for any multi-email automated flow. For cold outreach emails, see cold-email. For in-app onboarding, see onboarding.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Email Sequence Design
|
||||
@@ -12,7 +12,7 @@ You are an expert in email marketing and automation. Your goal is to create emai
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before creating a sequence, understand:
|
||||
|
||||
@@ -293,6 +293,7 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email
|
||||
|------|----------|:---:|-------|
|
||||
| **Customer.io** | Behavior-based automation | - | [customer-io.md](../../tools/integrations/customer-io.md) |
|
||||
| **Mailchimp** | SMB email marketing | ✓ | [mailchimp.md](../../tools/integrations/mailchimp.md) |
|
||||
| **Nitrosend** | AI-native email (sequences via prompts) | ✓ | [nitrosend.md](../../tools/integrations/nitrosend.md) |
|
||||
| **Resend** | Developer-friendly transactional | ✓ | [resend.md](../../tools/integrations/resend.md) |
|
||||
| **SendGrid** | Transactional email at scale | - | [sendgrid.md](../../tools/integrations/sendgrid.md) |
|
||||
| **Kit** | Creator/newsletter focused | - | [kit.md](../../tools/integrations/kit.md) |
|
||||
@@ -301,8 +302,10 @@ For implementation, see the [tools registry](../../tools/REGISTRY.md). Key email
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **lead-magnets**: For planning lead magnets that feed into nurture sequences
|
||||
- **churn-prevention**: For cancel flows, save offers, and dunning strategy (email supports this)
|
||||
- **onboarding-cro**: For in-app onboarding (email supports this)
|
||||
- **onboarding**: For in-app onboarding (email supports this)
|
||||
- **copywriting**: For landing pages emails link to
|
||||
- **ab-test-setup**: For testing email elements
|
||||
- **popup-cro**: For email capture popups
|
||||
- **ab-testing**: For testing email elements
|
||||
- **popups**: For email capture popups
|
||||
- **revops**: For lifecycle stages that trigger email sequences
|
||||
@@ -0,0 +1,93 @@
|
||||
{
|
||||
"skill_name": "emails",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "Create a welcome email sequence for new users who sign up for our project management tool's free trial. The trial is 14 days. We want to get them to their aha moment (creating their first project and inviting a team member).",
|
||||
"expected_output": "Should check for product-marketing.md first. Should create a welcome sequence (5-7 emails) following the core principles: one email one job, value before ask. Should map each email to a specific goal in the 14-day trial journey. Should include timing/delays between emails. Each email should follow the email copy structure: hook → context → value → CTA → sign-off. Should include subject lines following the subject line strategy. Should align sequence with the aha moment (first project + team invite). Output should follow the structured format with sequence overview and per-email specs.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Creates 5-7 email welcome sequence",
|
||||
"Follows one email one job principle",
|
||||
"Maps emails to trial timeline (14 days)",
|
||||
"Includes timing between emails",
|
||||
"Each email has hook, context, value, CTA",
|
||||
"Includes subject lines for each email",
|
||||
"Aligns with stated aha moment",
|
||||
"Output follows structured per-email format"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We need a lead nurture sequence for people who download our 'State of DevOps 2024' report. Goal is to get them to book a demo of our CI/CD platform.",
|
||||
"expected_output": "Should create a lead nurture sequence (6-8 emails). Should follow value before ask — first emails should provide related value, not immediately push for demo. Should map the sequence from awareness (report download) through consideration (related content, case studies) to decision (demo request). Should include timing between emails. Each email should have clear subject line, hook, single CTA. Should gradually increase commitment asks across the sequence.",
|
||||
"assertions": [
|
||||
"Creates 6-8 email lead nurture sequence",
|
||||
"Follows value before ask principle",
|
||||
"Maps from awareness through consideration to decision",
|
||||
"Includes timing between emails",
|
||||
"Each email has clear subject line and single CTA",
|
||||
"Gradually increases commitment asks",
|
||||
"Connects to original download topic"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "our email open rates have tanked. used to be 35% now we're at 18%. what's going on and how do we fix our subject lines?",
|
||||
"expected_output": "Should trigger on casual phrasing. Should diagnose potential causes of declining open rates: sender reputation, list hygiene, subject line quality, sending frequency, deliverability issues. Should apply the subject line strategy from the skill: test curiosity vs benefit vs urgency patterns, personalization, optimal length. Should recommend a re-engagement campaign to clean the list. Should provide specific subject line formulas and examples. Should suggest testing framework for subject lines.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Diagnoses potential causes beyond just subject lines",
|
||||
"Addresses sender reputation and deliverability",
|
||||
"Recommends list hygiene or re-engagement",
|
||||
"Applies subject line strategy with specific patterns",
|
||||
"Provides subject line formulas and examples",
|
||||
"Suggests testing framework"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Build a re-engagement sequence for subscribers who haven't opened any emails in 90 days. We have about 5,000 inactive subscribers.",
|
||||
"expected_output": "Should create a re-engagement sequence (3-4 emails). Should follow the re-engagement pattern: first email acknowledges absence and offers value, middle emails escalate with compelling reasons to re-engage, final email is a clear 'last chance' before removal. Should recommend aggressive subject lines to break through. Should include a sunset policy (remove non-responders after sequence completes). Should address the impact on deliverability of keeping inactive subscribers.",
|
||||
"assertions": [
|
||||
"Creates 3-4 email re-engagement sequence",
|
||||
"Acknowledges absence in first email",
|
||||
"Escalates through the sequence",
|
||||
"Includes 'last chance' final email",
|
||||
"Recommends sunset policy for non-responders",
|
||||
"Addresses deliverability impact of inactive subscribers",
|
||||
"Uses compelling subject lines"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "What's the ideal timing for our onboarding email sequence? We send the first email immediately after signup, but we're not sure about the rest.",
|
||||
"expected_output": "Should provide timing guidance for onboarding sequences. Should reference the timing and delays framework: immediate first email (welcome/confirmation), then suggest data-driven timing based on user behavior triggers vs fixed time delays. Should recommend behavior-triggered emails when possible (user completed action → next email) with time-based fallbacks. Should provide typical timing patterns for SaaS onboarding (day 0, day 1, day 3, day 5, day 7, etc.). Should note that optimal timing depends on product complexity and trial length.",
|
||||
"assertions": [
|
||||
"Provides timing guidance for onboarding sequences",
|
||||
"Recommends immediate first email",
|
||||
"Discusses behavior-triggered vs time-based timing",
|
||||
"Provides typical timing patterns",
|
||||
"Notes timing depends on product and trial length",
|
||||
"Recommends behavior triggers with time-based fallbacks"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Help me optimize our post-signup onboarding experience. Users sign up but 60% never complete setup.",
|
||||
"expected_output": "Should recognize this is an in-app onboarding optimization task, not an email sequence task. Should defer to or cross-reference the onboarding skill, which handles in-app onboarding flows, checklists, and activation optimization. May offer to help with the email component of onboarding but should make clear that onboarding is the primary skill for this task.",
|
||||
"assertions": [
|
||||
"Recognizes this as in-app onboarding optimization",
|
||||
"References or defers to onboarding skill",
|
||||
"Does not attempt full onboarding redesign using email patterns",
|
||||
"May offer email component support"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: free-tool-strategy
|
||||
description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," or "free resource." This skill bridges engineering and marketing — useful for founders and technical marketers.
|
||||
name: free-tools
|
||||
description: When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or brand awareness. Also use when the user mentions "engineering as marketing," "free tool," "marketing tool," "calculator," "generator," "interactive tool," "lead gen tool," "build a tool for leads," "free resource," "ROI calculator," "grader tool," "audit tool," "should I build a free tool," or "tools for lead gen." Use this whenever someone wants to build something useful and give it away to attract leads or earn links. For downloadable content lead magnets (ebooks, checklists, templates), see lead-magnets.
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# Free Tool Strategy (Engineering as Marketing)
|
||||
@@ -12,7 +12,7 @@ You are an expert in engineering-as-marketing strategy. Your goal is to help pla
|
||||
## Initial Assessment
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Before designing a tool strategy, understand:
|
||||
|
||||
@@ -172,7 +172,8 @@ Rate each factor 1-5:
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **page-cro**: For optimizing the tool's landing page
|
||||
- **lead-magnets**: For downloadable content lead magnets (ebooks, checklists, templates)
|
||||
- **cro**: For optimizing the tool's landing page
|
||||
- **seo-audit**: For SEO-optimizing the tool
|
||||
- **analytics-tracking**: For measuring tool usage
|
||||
- **email-sequence**: For nurturing leads from the tool
|
||||
- **analytics**: For measuring tool usage
|
||||
- **emails**: For nurturing leads from the tool
|
||||
@@ -0,0 +1,90 @@
|
||||
{
|
||||
"skill_name": "free-tools",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We want to build a free tool to drive leads for our SEO software. We're thinking about an SEO audit tool or a keyword research tool. Which would be better and how should we approach it?",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the evaluation scorecard to compare both tool ideas across dimensions (audience alignment, lead quality, build effort, SEO value, maintenance burden, competitive differentiation). Should reference the tool types from the skill (analyzers, testers). Should recommend the stronger option with rationale. Should discuss lead capture gating strategy (what's free vs what requires email). Should address MVP scope — what's the minimum valuable version. Should provide implementation recommendations.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies evaluation scorecard to compare options",
|
||||
"References tool types from the skill",
|
||||
"Recommends one option with clear rationale",
|
||||
"Discusses lead capture gating strategy",
|
||||
"Addresses MVP scope",
|
||||
"Provides implementation recommendations"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "I want to build a free ROI calculator for our HR software. Users input their company size and current processes, and it shows how much time and money they'd save.",
|
||||
"expected_output": "Should identify this as a calculator tool type. Should apply the ideation framework to validate the concept. Should discuss lead capture strategy: should the basic result be free and detailed report gated? Should address the build vs buy decision. Should recommend MVP scope (what inputs, what outputs, what formula). Should discuss SEO considerations for the tool page. Should reference the evaluation scorecard to score the idea.",
|
||||
"assertions": [
|
||||
"Identifies as calculator tool type",
|
||||
"Applies ideation framework to validate",
|
||||
"Discusses lead capture gating strategy",
|
||||
"Addresses build vs buy decision",
|
||||
"Recommends MVP scope (inputs, outputs, formula)",
|
||||
"Discusses SEO considerations",
|
||||
"References evaluation scorecard"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "give me some ideas for free tools we could build. we sell email marketing software for e-commerce brands.",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the ideation framework to generate tool ideas relevant to email marketing + e-commerce. Should provide 5-8 ideas across different tool types (calculators, generators, analyzers, testers). Examples: email subject line tester, email deliverability checker, email ROI calculator, email template generator, spam score checker. Should briefly score each against the evaluation dimensions. Should recommend top 2-3 to pursue.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Applies ideation framework",
|
||||
"Generates ideas across multiple tool types",
|
||||
"Ideas are relevant to email marketing + e-commerce",
|
||||
"Provides 5-8 ideas",
|
||||
"Briefly evaluates each idea",
|
||||
"Recommends top 2-3 to pursue"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "We built a free website speed test tool 6 months ago but it's barely getting any traffic. What went wrong and how do we fix it?",
|
||||
"expected_output": "Should diagnose why the tool isn't getting traffic. Should investigate: SEO strategy for the tool page (target keywords, on-page optimization), distribution strategy (was it launched and forgotten?), competitive landscape (are there dominant free tools already?), tool quality and UX (does it provide unique value?). Should apply the engineering as marketing principles. Should recommend a recovery plan: SEO improvements, content marketing around the tool, product improvements for differentiation.",
|
||||
"assertions": [
|
||||
"Diagnoses potential traffic issues",
|
||||
"Investigates SEO strategy for the tool",
|
||||
"Assesses competitive landscape",
|
||||
"Questions unique value proposition",
|
||||
"Applies engineering as marketing principles",
|
||||
"Recommends recovery plan with specific actions"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "Should we gate our free tool behind an email capture or make it completely free? We want leads but don't want to kill usage.",
|
||||
"expected_output": "Should apply the lead capture gating strategy framework. Should present the spectrum: fully ungated → partial gating (basic results free, detailed report gated) → fully gated. Should recommend partial gating as the typical best approach — give enough value to demonstrate the tool's worth, gate the detailed/actionable output. Should discuss tradeoffs: ungated = more SEO value and usage, gated = more leads but fewer users. Should provide specific gating recommendations based on tool type.",
|
||||
"assertions": [
|
||||
"Applies lead capture gating strategy",
|
||||
"Presents gating spectrum (ungated to fully gated)",
|
||||
"Recommends partial gating approach",
|
||||
"Discusses tradeoffs of each approach",
|
||||
"Provides specific gating recommendations",
|
||||
"Addresses SEO impact of gating decisions"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "How do I optimize the landing page for our free tool to get more signups? The tool itself is great but nobody finds it.",
|
||||
"expected_output": "Should recognize this is a landing page conversion optimization task, not a free tool strategy task. Should defer to or cross-reference the cro skill for optimizing the tool's landing page conversion rate. May provide free-tool-specific context (gating strategy, value demonstration) but should make clear that cro is the right skill for page conversion optimization.",
|
||||
"assertions": [
|
||||
"Recognizes this as page CRO, not free tool strategy",
|
||||
"References or defers to cro skill",
|
||||
"May provide free-tool-specific context",
|
||||
"Does not attempt full page CRO using free tool strategy patterns"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,340 @@
|
||||
---
|
||||
name: image
|
||||
description: "When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product mockups, profile banners, listing visuals, or brand assets. Also use when the user mentions 'AI image generation,' 'generate an image,' 'create a graphic,' 'product mockup,' 'hero image,' 'social media graphic,' 'banner image,' 'cover photo,' 'profile banner,' 'listing screenshot,' 'Flux,' 'Flux Kontext,' 'Midjourney,' 'DALL-E,' 'GPT Image,' 'ChatGPT Images,' 'Ideogram,' 'Gemini image,' 'Nano Banana,' 'Recraft,' 'Stable Diffusion,' 'Canva,' 'Figma,' 'image optimization,' 'compress images,' 'WebP,' or 'OG image.' Use this for general-purpose marketing image creation and optimization. For paid ad image creative and platform-specific ad specs, see ad-creative. For video production, see video."
|
||||
metadata:
|
||||
version: 2.0.1
|
||||
---
|
||||
|
||||
# Image
|
||||
|
||||
You are an expert visual content producer who helps create marketing images using AI generation models, design tools, and optimization best practices. Your goal is to help users produce professional visual assets efficiently — from blog heroes and social graphics to product mockups and profile banners.
|
||||
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
Gather this context (ask if not provided):
|
||||
|
||||
### 1. Image Goal
|
||||
- What type of image? (Blog hero, social graphic, product mockup, banner, brand asset, OG image)
|
||||
- What platform or placement? (Website, social, directory listing, app store, email)
|
||||
- What dimensions do you need?
|
||||
|
||||
### 2. Production Approach
|
||||
- Do you have existing brand assets? (Logo, colors, fonts, style guide)
|
||||
- Do you need photorealistic or illustrative style?
|
||||
- Is this a one-off or a template for repeated use?
|
||||
|
||||
### 3. Technical Context
|
||||
- Do you have API keys for any image tools? (Gemini, Replicate/Flux, Ideogram)
|
||||
- Budget constraints? (Some tools charge per image)
|
||||
- Do you need the image optimized for web performance?
|
||||
|
||||
---
|
||||
|
||||
## Choosing Your Approach
|
||||
|
||||
Pick the right tool for the job:
|
||||
|
||||
| Approach | Best For | Tools | When to Use |
|
||||
|----------|----------|-------|-------------|
|
||||
| **AI Generation** | Original images from text prompts | Gemini/Nano Banana, Flux, Ideogram | Blog heroes, social graphics, lifestyle scenes |
|
||||
| **AI Editing** | Modify existing images | Gemini, Flux Flex | Background removal, style changes, variations |
|
||||
| **Design Tools** | Templated, brand-consistent assets | Canva, Figma | Profile banners, social templates, presentations |
|
||||
| **Screenshot + Overlay** | Product UI showcases | Browser screenshot + code overlay | Product mockups, feature announcements |
|
||||
| **Stock Photography** | Generic business/lifestyle scenes | Unsplash, Pexels | When speed matters more than uniqueness |
|
||||
|
||||
---
|
||||
|
||||
## AI Image Generation
|
||||
|
||||
Generate original images from text prompts. The fastest way to create unique marketing visuals.
|
||||
|
||||
### Model Comparison
|
||||
|
||||
| Model | Best For | Text in Images | API | Cost |
|
||||
|-------|----------|:-:|-----|------|
|
||||
| **Gemini Image** (Google, "Nano Banana" / Nano Banana Pro) | All-around, editing, multi-image reference, text rendering | Good | [Gemini API](https://ai.google.dev/gemini-api/docs/image-generation) | Check [pricing](https://ai.google.dev/gemini-api/docs/pricing) |
|
||||
| **Flux** (Black Forest Labs — Pro 1.1, Kontext, Dev, Schnell) | Photorealism, brand consistency, batch; Kontext for in-image editing | Limited | [BFL API](https://docs.bfl.ai/), Replicate, fal.ai | Check [pricing](https://docs.bfl.ai/quick_start/pricing) |
|
||||
| **Ideogram 3.0** | Typography, branded graphics, accurate text rendering | Best | [Ideogram API](https://developer.ideogram.ai/) | Check [pricing](https://about.ideogram.ai/api-pricing) |
|
||||
| **ChatGPT Images 2.0 / GPT Image** (OpenAI) | General purpose, ChatGPT integration, native editing | Good | [OpenAI API](https://platform.openai.com/docs/guides/image-generation) | Check [pricing](https://platform.openai.com/docs/pricing) |
|
||||
| **Midjourney v7** | Artistic, high-aesthetic, art-directed visuals | Improved | No official API; Discord + Web | Subscription-based |
|
||||
| **Recraft V3** | Vector + brand-consistent illustrations, design assets | Strong | [Recraft API](https://www.recraft.ai/docs) | Per-credit |
|
||||
| **Stable Diffusion 3.5 / SDXL** | Self-hosted, customizable, fine-tunable | Varies | Open source | Free (GPU costs) |
|
||||
|
||||
**Note:** DALL-E 3 is fully deprecated. OpenAI's current image models are the GPT Image / ChatGPT Images family (`gpt-image-1` and later).
|
||||
|
||||
### When to Use Which
|
||||
|
||||
```
|
||||
Need text/headlines in the image?
|
||||
├── Yes → Ideogram 3.0 (best), Gemini (good), GPT Image / ChatGPT Images (decent)
|
||||
└── No ↓
|
||||
|
||||
Need product/brand consistency across many images?
|
||||
├── Yes → Flux (multi-image reference), Gemini Nano Banana Pro, Recraft V3
|
||||
└── No ↓
|
||||
|
||||
Need to edit an existing image (in-place)?
|
||||
├── Yes → Gemini (native editing), Flux Kontext, ChatGPT Images
|
||||
└── No ↓
|
||||
|
||||
Need vector / illustrative brand assets?
|
||||
├── Yes → Recraft V3 (best for vector + brand consistency), Midjourney (artistic)
|
||||
└── No ↓
|
||||
|
||||
Need highest visual quality / art direction?
|
||||
├── Yes → Flux Pro 1.1, Midjourney v7
|
||||
└── No ↓
|
||||
|
||||
Need volume at low cost?
|
||||
└── Flux Schnell, Gemini Flash, Stable Diffusion (self-hosted)
|
||||
```
|
||||
|
||||
### Prompting Basics
|
||||
|
||||
A strong image prompt follows: **Subject + Setting + Style + Lighting + Composition + Technical**
|
||||
|
||||
```
|
||||
A laptop on a minimal white desk showing a dashboard UI,
|
||||
soft directional lighting from the left, shallow depth of field,
|
||||
clean commercial photography style, 16:9 aspect ratio, 4K
|
||||
```
|
||||
|
||||
**Common mistakes:**
|
||||
- Too vague ("a business image") — add specific details
|
||||
- Forgetting aspect ratio — always specify dimensions
|
||||
- Requesting complex text — use overlays instead for anything beyond short headlines
|
||||
- No style direction — "photorealistic," "flat illustration," "3D render"
|
||||
|
||||
For detailed prompting guides per model, see [references/ai-image-prompting.md](references/ai-image-prompting.md).
|
||||
|
||||
---
|
||||
|
||||
## Design Tools
|
||||
|
||||
For templated, brand-consistent work where AI generation is overkill or too unpredictable.
|
||||
|
||||
### Canva
|
||||
|
||||
Best for non-designers who need polished output fast.
|
||||
|
||||
- **Strengths:** Massive template library, brand kit, Magic Resize (one design → all sizes), team collaboration
|
||||
- **Best for:** Social graphics, presentations, email headers, simple banners
|
||||
- **Limitations:** Less control than Figma, templates can look generic
|
||||
- **Agent-friendliness:** Has an API but limited — better as a human-in-the-loop tool
|
||||
|
||||
### Figma
|
||||
|
||||
Best for teams with design systems or pixel-perfect needs.
|
||||
|
||||
- **Strengths:** Design system components, auto layout, developer handoff, plugins
|
||||
- **Best for:** OG images via templates, design system assets, complex layouts
|
||||
- **Limitations:** Steeper learning curve, requires design skill
|
||||
- **Agent-friendliness:** Has an API and MCP server for reading designs
|
||||
|
||||
### When to Use Design Tools vs. AI Generation
|
||||
|
||||
| Scenario | Design Tool | AI Generation |
|
||||
|----------|:-:|:-:|
|
||||
| Exact brand guidelines must be followed | Yes | Maybe (with strong ref images) |
|
||||
| Need 20 size variants of one design | Yes (Canva Magic Resize) | No |
|
||||
| Unique hero image for a blog post | No | Yes |
|
||||
| Recurring social media template | Yes | No |
|
||||
| Product mockup with real UI | No (use screenshots) | No (hallucinated UI) |
|
||||
| Abstract/creative visual | No | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Marketing Image Workflows
|
||||
|
||||
### Blog & Article Hero Images
|
||||
|
||||
The image at the top of every post. Sets tone, improves shareability, required for OG/social previews.
|
||||
|
||||
1. **Define the concept** — what visual metaphor represents the topic?
|
||||
2. **Generate with AI** — use Flux or Gemini for photorealistic, Ideogram if text needed
|
||||
3. **Specify 1200x630** (works for both hero and OG image) or **1920x1080** for full-width
|
||||
4. **Optimize** — compress to <200KB, serve as WebP with JPEG fallback
|
||||
|
||||
**Prompt pattern:**
|
||||
```
|
||||
[Visual metaphor for topic], clean modern style,
|
||||
bright natural lighting, shallow depth of field,
|
||||
professional blog header aesthetic, 1200x630
|
||||
```
|
||||
|
||||
### Social Media Graphics
|
||||
|
||||
Platform-specific images for organic posts.
|
||||
|
||||
| Platform | Primary Size | Aspect Ratio | Notes |
|
||||
|----------|-------------|:---:|-------|
|
||||
| Twitter/X | 1200x675 | 16:9 | Large image card |
|
||||
| LinkedIn | 1200x627 | 1.91:1 | Feed image |
|
||||
| Instagram Feed | 1080x1080 | 1:1 | Square; 1080x1350 (4:5) also strong |
|
||||
| Instagram Stories | 1080x1920 | 9:16 | Full screen vertical |
|
||||
| Facebook | 1200x630 | 1.91:1 | Link share image |
|
||||
|
||||
**Workflow:**
|
||||
1. Create the hero concept at highest resolution needed
|
||||
2. Use Canva Magic Resize or manual crop for platform variants
|
||||
3. Add text overlays programmatically (Ideogram or post-processing) if needed
|
||||
4. Export at platform-specific dimensions
|
||||
|
||||
### Product Mockups & Screenshots
|
||||
|
||||
Showcase your product UI in context. AI models hallucinate UI — don't use them for this.
|
||||
|
||||
1. **Capture real screenshots** of your product at 2x resolution
|
||||
2. **Frame in device mockups** — use browser frame, laptop, or phone templates
|
||||
3. **Add context** — callout arrows, feature labels, before/after comparisons
|
||||
4. **Annotate with code** — Hyperframes or HTML/CSS for programmatic overlays
|
||||
|
||||
**Tools:** Browser DevTools (screenshot), Shottr (Mac), CleanShot X, or `screencapture` CLI.
|
||||
|
||||
### Profile & Listing Banners
|
||||
|
||||
Banners for profiles, directory listings, and marketplace pages. Often the first visual impression.
|
||||
|
||||
| Platform | Size | Notes |
|
||||
|----------|------|-------|
|
||||
| LinkedIn personal cover | 1584x396 | 4:1, safe zone center |
|
||||
| LinkedIn company cover | 1128x191 | 5.9:1; LinkedIn recommends up to 4200x700 |
|
||||
| Twitter/X header | 1500x500 | 3:1, partially obscured by avatar |
|
||||
| Product Hunt gallery | 1270x760 | 5:3, up to 6 images |
|
||||
| G2 profile | 1280x720 | 16:9, product screenshots preferred |
|
||||
| GitHub social preview | 1280x640 | 2:1, shows in link cards |
|
||||
| App Store screenshots | Varies by device | See aso skill for full specs |
|
||||
| Google Play feature graphic | 1024x500 | ~2:1, required for store listing |
|
||||
|
||||
**Best practices:**
|
||||
- **Keep text minimal** — banners are seen at small sizes on mobile
|
||||
- **Center critical content** — edges get cropped differently per device
|
||||
- **Show the product** — real UI screenshots outperform abstract graphics on directory listings
|
||||
- **Match your brand** — use consistent colors, fonts, logo placement
|
||||
- **Update seasonally** — stale banners signal an inactive product
|
||||
|
||||
**Workflow:**
|
||||
1. Pick the platform(s) and note exact dimensions
|
||||
2. For directories (Product Hunt, G2): use real product screenshots with light annotation
|
||||
3. For profiles (LinkedIn, Twitter): use brand colors + tagline + optional product shot
|
||||
4. Generate with Canva/Figma templates or Ideogram (if text-heavy)
|
||||
5. Test at actual display size — zoom out to check readability
|
||||
|
||||
### Brand Assets
|
||||
|
||||
Logos, icons, and illustrations. AI generation has limits here.
|
||||
|
||||
| Asset | AI Generation | Design Tool | Notes |
|
||||
|-------|:-:|:-:|-------|
|
||||
| Logo | Poor — inconsistent, not vector | Yes (Figma) | Always design or commission logos |
|
||||
| App icon | Decent starting point | Yes (Figma) | Generate concepts, refine manually |
|
||||
| Illustrations | Good for style exploration | Depends | AI for concepts, finalize in design tool |
|
||||
| Favicons | No | Yes | Derive from logo |
|
||||
| Social icons | No | Yes | Use platform-provided assets |
|
||||
|
||||
---
|
||||
|
||||
## Image Optimization
|
||||
|
||||
Every image on your site affects page speed, which affects SEO and conversions.
|
||||
|
||||
### Format Guide
|
||||
|
||||
| Format | Best For | Compression | Browser Support |
|
||||
|--------|----------|-------------|:---:|
|
||||
| **WebP** | Photos, graphics — default choice | Lossy + lossless | ~96% |
|
||||
| **AVIF** | Highest compression, newest | Better than WebP | ~94% |
|
||||
| **JPEG** | Fallback for older browsers | Lossy only | Universal |
|
||||
| **PNG** | Transparency, screenshots | Lossless | Universal |
|
||||
| **SVG** | Logos, icons, illustrations | Vector (scales) | Universal |
|
||||
|
||||
### Optimization Checklist
|
||||
|
||||
- [ ] **Serve WebP** with JPEG/PNG fallback (`<picture>` element or CDN auto-format)
|
||||
- [ ] **Resize to display size** — don't serve 4000px images in 800px containers
|
||||
- [ ] **Compress** — target quality 75-85% for photos, near-lossless for screenshots
|
||||
- [ ] **Lazy load** below-the-fold images (`loading="lazy"`)
|
||||
- [ ] **Set explicit dimensions** — `width` and `height` attributes prevent layout shift (CLS)
|
||||
- [ ] **Use a CDN** with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary)
|
||||
- [ ] **Add alt text** — descriptive, keyword-relevant, not stuffed
|
||||
|
||||
### Quick Optimization Commands
|
||||
|
||||
```bash
|
||||
# Convert to WebP (using cwebp)
|
||||
cwebp -q 80 input.png -o output.webp
|
||||
|
||||
# Batch convert with ImageMagick
|
||||
mogrify -format webp -quality 80 *.png
|
||||
|
||||
# Optimize JPEG (using jpegoptim)
|
||||
jpegoptim --max=80 --strip-all *.jpg
|
||||
|
||||
# Check image sizes on a page
|
||||
curl -s https://yoursite.com | grep -oP 'src="[^"]+\.(jpg|png|webp)"' | head -20
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## OG & Social Preview Images
|
||||
|
||||
The image that appears when your URL is shared on social media, Slack, Discord, etc.
|
||||
|
||||
### Required Meta Tags
|
||||
|
||||
```html
|
||||
<meta property="og:image" content="https://yoursite.com/og/page-name.jpg" />
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<meta property="og:image:height" content="630" />
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta name="twitter:image" content="https://yoursite.com/og/page-name.jpg" />
|
||||
```
|
||||
|
||||
### Dynamic OG Images
|
||||
|
||||
Generate OG images programmatically for pages with dynamic content (blog posts, user profiles):
|
||||
|
||||
- **Vercel OG** (`@vercel/og`) — generates images at the edge using JSX
|
||||
- **Satori** — converts HTML/CSS to SVG (powers Vercel OG)
|
||||
- **Cloudinary** — URL-based text overlay on template images
|
||||
|
||||
**Best for programmatic SEO:** Generate unique OG images per page using templates + dynamic data.
|
||||
|
||||
---
|
||||
|
||||
## Common Mistakes
|
||||
|
||||
1. **Using AI for product UI screenshots** — models hallucinate interfaces; capture real screenshots
|
||||
2. **Skipping image optimization** — unoptimized images are the #1 page speed killer
|
||||
3. **No OG image** — shared links look broken without a preview image
|
||||
4. **Wrong aspect ratio** — always check platform specs before generating
|
||||
5. **Text-heavy images without Ideogram** — most AI models butcher text; use Ideogram or add text in post
|
||||
6. **Generating without style direction** — "photorealistic," "flat illustration," "3D render" drastically changes output
|
||||
7. **Inconsistent brand visuals** — use Flux multi-reference or design templates for consistency
|
||||
8. **Huge images on landing pages** — compress, resize, lazy load
|
||||
|
||||
---
|
||||
|
||||
## Task-Specific Questions
|
||||
|
||||
1. What type of image do you need? (Blog hero, social graphic, mockup, banner, brand asset)
|
||||
2. What platform or placement? (This determines dimensions)
|
||||
3. Do you have brand assets to match? (Colors, fonts, logo, style guide)
|
||||
4. Is this a one-off or a repeatable template?
|
||||
5. Do you have API keys for any image generation tools?
|
||||
6. Does this need to be optimized for web performance?
|
||||
|
||||
---
|
||||
|
||||
## Related Skills
|
||||
|
||||
- **ad-creative**: For paid ad image creative, platform-specific ad specs, and scaled ad production
|
||||
- **video**: For AI video production and programmatic video
|
||||
- **social**: For what to post and content strategy
|
||||
- **cro**: For image placement and conversion optimization on landing pages
|
||||
- **seo-audit**: For image SEO (alt text, file names, lazy loading)
|
||||
- **aso**: For app store screenshot specs and optimization
|
||||
- **directory-submissions**: For Product Hunt gallery images and directory listing visuals
|
||||
@@ -0,0 +1,89 @@
|
||||
{
|
||||
"skill_name": "image",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "I need a hero image for a blog post about email deliverability. Make it visually striking.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should recommend AI generation as the approach for a one-off blog hero. Should propose a visual metaphor concept that represents email deliverability (e.g., letters being sorted through a maze, signals breaking through a wall, an inbox glow). Should specify 1200x630 (works for both hero and OG image). Should recommend Flux or Gemini for photorealistic, or Ideogram if text in image is needed. Should provide a prompt following Subject + Setting + Style + Lighting + Composition + Technical pattern. Should mention WebP optimization (target <200KB, JPEG fallback). Should not suggest using AI for product UI screenshots.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Recommends AI generation for one-off hero",
|
||||
"Proposes visual metaphor for topic",
|
||||
"Specifies 1200x630 dimensions",
|
||||
"Recommends Flux, Gemini, or Ideogram",
|
||||
"Provides structured prompt",
|
||||
"Mentions WebP optimization"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Generate me an image of our app's dashboard.",
|
||||
"expected_output": "Should refuse to use AI generation for product UI screenshots and explain why: models hallucinate interfaces, the result won't match the real UI. Should recommend the Product Mockups & Screenshots workflow: capture real screenshots of the product at 2x resolution, frame in device mockups (browser frame, laptop, phone), add callout arrows or feature labels for context, programmatically overlay annotations with Hyperframes or HTML/CSS. Should suggest tools: browser DevTools screenshot, Shottr, CleanShot X, or screencapture CLI. Should warn this is Common Mistake #1: using AI for product UI.",
|
||||
"assertions": [
|
||||
"Refuses to use AI generation for product UI",
|
||||
"Explains models hallucinate UI",
|
||||
"Recommends real screenshots at 2x resolution",
|
||||
"Mentions device mockups for framing",
|
||||
"Suggests specific screenshot tools",
|
||||
"Notes this as a common mistake"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "Need a Twitter/X header banner for our company. We just want to show our product and tagline.",
|
||||
"expected_output": "Should specify Twitter/X header dimensions: 1500x500 (3:1 aspect ratio). Should warn the banner is partially obscured by the avatar — center critical content and avoid important elements near the avatar overlap area. Should recommend keeping text minimal (seen at small sizes on mobile). Should suggest design tools (Canva or Figma) over AI generation since brand consistency matters. Should recommend Ideogram if heavy text rendering is needed since other AI models butcher text. Should suggest using brand colors + tagline + optional product shot. Should remind to test at actual display size by zooming out.",
|
||||
"assertions": [
|
||||
"Specifies 1500x500 dimensions",
|
||||
"Warns about avatar overlap area",
|
||||
"Recommends minimal text",
|
||||
"Suggests Canva or Figma over AI",
|
||||
"Mentions Ideogram for text-heavy designs",
|
||||
"Recommends testing at display size"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "I need 5 versions of the same hero image for Twitter, LinkedIn, Instagram feed, Instagram stories, and Facebook. What's the fastest way?",
|
||||
"expected_output": "Should recommend the Canva Magic Resize workflow over generating 5 separate images. Should list dimensions: Twitter/X 1200x675 (16:9), LinkedIn 1200x627 (1.91:1), Instagram feed 1080x1080 (1:1 — note 1080x1350 / 4:5 also strong), Instagram Stories 1080x1920 (9:16), Facebook 1200x630 (1.91:1). Should explain workflow: create the hero concept at highest resolution needed, use Canva Magic Resize for variants, manually crop if needed, add text overlays programmatically if required (Ideogram or post-processing), export at each platform's specs. Should note this is what Canva Magic Resize is specifically designed for.",
|
||||
"assertions": [
|
||||
"Recommends Canva Magic Resize",
|
||||
"Lists dimensions for all 5 platforms",
|
||||
"Notes Instagram 4:5 variant",
|
||||
"Suggests programmatic text overlays for variants",
|
||||
"Says start at highest resolution"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "What's the best image format for our website?",
|
||||
"expected_output": "Should recommend WebP as the default choice with JPEG/PNG fallback. Should explain the format guide: WebP for photos and graphics (lossy + lossless, ~96% browser support), AVIF for highest compression (~94% support, newer), JPEG as universal fallback (lossy only), PNG for transparency and screenshots (lossless, universal), SVG for logos and icons (vector, scales, universal). Should reference the optimization checklist: resize to display size, compress (target quality 75-85% for photos), lazy load below-the-fold, set explicit width/height attributes (prevents CLS), use a CDN with auto-optimization (Cloudflare, Vercel, Imgix, Cloudinary), add descriptive alt text. Should provide a quick cwebp or mogrify command. Should note skipping image optimization is the #1 page speed killer.",
|
||||
"assertions": [
|
||||
"Recommends WebP as default",
|
||||
"Mentions JPEG/PNG fallback strategy",
|
||||
"Lists optimization checklist items",
|
||||
"Mentions lazy loading",
|
||||
"Mentions explicit dimensions to prevent CLS",
|
||||
"Provides command line tool example"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "We're a SaaS that just launched. Need OG images for every blog post we ship — about 2 per week. Doing it manually is killing us.",
|
||||
"expected_output": "Should recommend Dynamic OG Images programmatic approach. Should explain options: Vercel OG (@vercel/og) generates images at the edge using JSX — best for programmatic SEO since you can dynamically pull post title, author, image into a template; Satori converts HTML/CSS to SVG (powers Vercel OG); Cloudinary for URL-based text overlay on template images. Should explain you build the template once with your branding then it generates unique OG images per page using post metadata. Should mention required meta tags: og:image (1200x630), og:image:width, og:image:height, twitter:card summary_large_image, twitter:image. Should note this is best for programmatic SEO.",
|
||||
"assertions": [
|
||||
"Recommends programmatic OG image generation",
|
||||
"Names Vercel OG, Satori, or Cloudinary",
|
||||
"Mentions template + dynamic data approach",
|
||||
"Lists required og:image meta tags",
|
||||
"Specifies 1200x630 dimensions",
|
||||
"Notes this is best for high-volume blogs"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,229 @@
|
||||
# AI Image Prompting Guide
|
||||
|
||||
How to write effective prompts for AI image generation models (Gemini/Nano Banana, Flux, Ideogram, DALL-E, Midjourney).
|
||||
|
||||
---
|
||||
|
||||
## Prompt Structure
|
||||
|
||||
A strong image prompt follows this formula:
|
||||
|
||||
```
|
||||
[Subject] + [Setting/context] + [Visual style] + [Lighting] + [Composition] + [Technical specs]
|
||||
```
|
||||
|
||||
### Example Prompts by Use Case
|
||||
|
||||
**Blog hero — SaaS product:**
|
||||
```
|
||||
A clean workspace with a laptop displaying a colorful analytics dashboard,
|
||||
minimalist desk with a coffee cup and notebook,
|
||||
bright natural window lighting from the right,
|
||||
shallow depth of field, commercial photography style,
|
||||
1200x630, high resolution
|
||||
```
|
||||
|
||||
**Social media graphic — announcement:**
|
||||
```
|
||||
Abstract flowing gradient in deep purple and electric blue,
|
||||
geometric shapes forming a network pattern,
|
||||
dramatic rim lighting on edges,
|
||||
modern tech aesthetic, clean and minimal,
|
||||
1080x1080, vibrant colors
|
||||
```
|
||||
|
||||
**Product lifestyle shot:**
|
||||
```
|
||||
A person in a modern office smiling while looking at a tablet,
|
||||
showing a project management interface on screen,
|
||||
warm candid photography, natural lighting,
|
||||
medium shot, shallow depth of field, editorial style
|
||||
```
|
||||
|
||||
**Profile banner — professional:**
|
||||
```
|
||||
Wide panoramic abstract background in navy blue and teal,
|
||||
subtle geometric grid pattern with soft gradient,
|
||||
clean corporate aesthetic, muted lighting,
|
||||
1584x396, no text, space for logo overlay on left third
|
||||
```
|
||||
|
||||
**Directory listing — Product Hunt:**
|
||||
```
|
||||
Product screenshot on a clean gradient background,
|
||||
soft shadow underneath, slight 3D perspective tilt,
|
||||
modern SaaS product presentation style,
|
||||
1270x760, bright and professional
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Style Keywords
|
||||
|
||||
### Photorealistic
|
||||
- "commercial photography"
|
||||
- "shot on Canon EOS R5"
|
||||
- "editorial style"
|
||||
- "natural lighting"
|
||||
- "shallow depth of field"
|
||||
|
||||
### Clean/Corporate
|
||||
- "clean modern aesthetic"
|
||||
- "minimal design"
|
||||
- "professional corporate style"
|
||||
- "bright and airy"
|
||||
- "white background"
|
||||
|
||||
### Illustrative
|
||||
- "flat vector illustration"
|
||||
- "isometric 3D render"
|
||||
- "hand-drawn sketch style"
|
||||
- "watercolor illustration"
|
||||
- "line art"
|
||||
|
||||
### Abstract/Brand
|
||||
- "flowing gradient"
|
||||
- "geometric pattern"
|
||||
- "abstract data visualization"
|
||||
- "particle effects"
|
||||
- "holographic iridescent"
|
||||
|
||||
### Tech/SaaS
|
||||
- "dark mode UI aesthetic"
|
||||
- "neon accent lighting"
|
||||
- "glassmorphism"
|
||||
- "futuristic minimal"
|
||||
- "developer-focused"
|
||||
|
||||
---
|
||||
|
||||
## Lighting Keywords
|
||||
|
||||
| Term | Effect | Best For |
|
||||
|------|--------|----------|
|
||||
| **Natural light** | Warm, organic feel | Lifestyle, editorial |
|
||||
| **Studio lighting** | Even, controlled | Product shots |
|
||||
| **Rim lighting** | Edge highlights, dramatic | Hero images, abstract |
|
||||
| **Soft directional** | Gentle shadows, dimensional | Blog headers |
|
||||
| **Volumetric** | Light rays, atmospheric | Dramatic, cinematic |
|
||||
| **Flat/even** | No shadows, clean | Icons, diagrams |
|
||||
| **Golden hour** | Warm orange tones | Lifestyle, outdoor |
|
||||
| **High key** | Bright, minimal shadows | Clean, corporate |
|
||||
|
||||
---
|
||||
|
||||
## Composition Keywords
|
||||
|
||||
| Term | Effect | Best For |
|
||||
|------|--------|----------|
|
||||
| **Rule of thirds** | Subject off-center | Editorial, lifestyle |
|
||||
| **Centered** | Subject in middle | Product shots, icons |
|
||||
| **Wide/panoramic** | Expansive view | Banners, headers |
|
||||
| **Close-up/macro** | Detail focus | Texture, product detail |
|
||||
| **Bird's eye/overhead** | Top-down view | Desk setups, flat lays |
|
||||
| **Negative space** | Room for text overlay | Blog headers, banners |
|
||||
| **Symmetrical** | Balanced, formal | Corporate, luxury |
|
||||
|
||||
---
|
||||
|
||||
## Model-Specific Tips
|
||||
|
||||
### Gemini Image (Google)
|
||||
|
||||
- Best all-around for marketing images — good quality, reasonable cost
|
||||
- Supports **image editing** — upload an existing image and describe changes
|
||||
- Decent text rendering — can handle short headlines
|
||||
- Specify "high resolution" for best output
|
||||
- Works well with detailed, descriptive prompts
|
||||
- Same API as text generation — easy to integrate
|
||||
|
||||
### Flux (Black Forest Labs)
|
||||
|
||||
- **Multi-image reference** is the killer feature — upload product screenshots, brand assets, or style references
|
||||
- Best for **brand consistency** across a set of images
|
||||
- Use Flux Pro for final assets, Flux Dev for rapid iteration
|
||||
- Flux Klein for high-volume batch generation (cheapest)
|
||||
- Style transfer via reference images > style keywords in prompt
|
||||
- Prompts can be shorter than other models — the references do heavy lifting
|
||||
|
||||
### Ideogram
|
||||
|
||||
- **Best text rendering** of any model (industry-leading accuracy)
|
||||
- Use when you need headlines, taglines, or brand names in the image
|
||||
- Style reference system (up to 3 images) for brand consistency
|
||||
- Supports "Magic Prompt" auto-enhancement
|
||||
- Keep text requests simple — 3-5 words max for reliability
|
||||
- Best for social graphics and banners that need text baked in
|
||||
|
||||
### GPT Image (OpenAI)
|
||||
|
||||
- Current models: `gpt-image-1` and variants (DALL-E 3 is deprecated)
|
||||
- Integrated with ChatGPT — conversational image generation
|
||||
- Good at following detailed prompts
|
||||
- Decent text rendering (behind Ideogram, comparable to Gemini)
|
||||
- Automatic prompt rewriting — may deviate from exact request
|
||||
- Best for quick one-offs through ChatGPT interface
|
||||
- API gives more control than ChatGPT interface
|
||||
|
||||
### Midjourney
|
||||
|
||||
- Highest aesthetic quality for artistic/editorial images
|
||||
- No official API — Discord-based or web interface
|
||||
- **Not agent-friendly** — use for manual creative exploration only
|
||||
- Style flags: `--style raw` for less stylized, `--ar 16:9` for aspect ratio
|
||||
- Best for hero images where pure visual quality matters most
|
||||
- V6+ has improved text rendering but still unreliable
|
||||
|
||||
---
|
||||
|
||||
## Common Prompt Mistakes
|
||||
|
||||
| Mistake | Why It Fails | Fix |
|
||||
|---------|-------------|-----|
|
||||
| "A professional image" | No visual detail | Describe subject, setting, style, lighting |
|
||||
| Long paragraph of text in image | Models can't render paragraphs | 3-5 words max; add text in post |
|
||||
| "Make it look good" | Not actionable | Specify style: "commercial photography, bright" |
|
||||
| 200+ word prompts | Models lose focus | 40-80 words, specific over comprehensive |
|
||||
| No aspect ratio | Random output size | Always specify dimensions or ratio |
|
||||
| "Logo in bottom right" | Unreliable placement | Add logos in post-processing |
|
||||
| "Make it viral" | Not a visual instruction | Describe the aesthetic you want |
|
||||
| Requesting UI screenshots | AI hallucinates interfaces | Capture real screenshots instead |
|
||||
|
||||
---
|
||||
|
||||
## Batch Generation Workflow
|
||||
|
||||
When you need multiple images with consistent style (e.g., a blog series or social campaign):
|
||||
|
||||
1. **Generate 3-4 test images** with different style prompts
|
||||
2. **Pick the winning style** based on brand fit
|
||||
3. **Save the exact prompt** as your template
|
||||
4. **Use Flux multi-reference** — upload the winning image as a style reference
|
||||
5. **Batch generate** variations with the same style, different subjects
|
||||
6. **Post-process** — add text overlays, logos, crop to platform sizes
|
||||
|
||||
---
|
||||
|
||||
## Aspect Ratios Quick Reference
|
||||
|
||||
| Use Case | Ratio | Pixels | Notes |
|
||||
|----------|-------|--------|-------|
|
||||
| Blog hero / OG image | 1.91:1 | 1200x630 | Universal web standard |
|
||||
| Full-width hero | 16:9 | 1920x1080 | Website headers |
|
||||
| Instagram Feed | 1:1 | 1080x1080 | Square |
|
||||
| Instagram Feed (tall) | 4:5 | 1080x1350 | More screen real estate |
|
||||
| Stories / Reels | 9:16 | 1080x1920 | Vertical full screen |
|
||||
| LinkedIn cover | 4:1 | 1584x396 | Personal profile |
|
||||
| Twitter/X header | 3:1 | 1500x500 | Profile banner |
|
||||
| Product Hunt gallery | 5:3 | 1270x760 | Launch page |
|
||||
| GitHub social preview | 2:1 | 1280x640 | Repo link card |
|
||||
|
||||
---
|
||||
|
||||
## Cost Optimization
|
||||
|
||||
- **Iterate at low quality first** — use Flux Dev or Gemini Flash for drafts, upgrade for finals
|
||||
- **Use references over long prompts** — Flux multi-reference produces more consistent results with fewer retries
|
||||
- **Batch similar requests** — generate all blog headers in one session with the same style
|
||||
- **Cache and reuse** — abstract backgrounds, patterns, and textures can be reused across multiple images
|
||||
- **Post-process instead of re-generate** — crop, overlay text, and adjust color in code rather than generating new images
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
name: launch-strategy
|
||||
description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' or 'product update.' This skill covers phased launches, channel strategy, and ongoing launch momentum."
|
||||
name: launch
|
||||
description: "When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user mentions 'launch,' 'Product Hunt,' 'feature release,' 'announcement,' 'go-to-market,' 'beta launch,' 'early access,' 'waitlist,' 'product update,' 'how do I launch this,' 'launch checklist,' 'GTM plan,' or 'we're about to ship.' Use this whenever someone is preparing to release something publicly. For ongoing marketing after launch, see marketing-ideas. For the offer being launched (bonuses, guarantees, scarcity, naming), see offers."
|
||||
metadata:
|
||||
version: 1.0.0
|
||||
version: 2.0.1
|
||||
---
|
||||
|
||||
# Launch Strategy
|
||||
@@ -12,7 +12,7 @@ You are an expert in SaaS product launches and feature announcements. Your goal
|
||||
## Before Starting
|
||||
|
||||
**Check for product marketing context first:**
|
||||
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
If `.agents/product-marketing.md` exists (or `.claude/product-marketing.md`, or the legacy `product-marketing-context.md` filename, in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
|
||||
|
||||
---
|
||||
|
||||
@@ -93,7 +93,7 @@ Tap into someone else's audience to shortcut the hardest part—getting noticed.
|
||||
1. List industry leaders your audience follows
|
||||
2. Pitch win-win collaborations
|
||||
3. Use tools like SparkToro or Listen Notes to find audience overlap
|
||||
4. Set up affiliate/referral incentives
|
||||
4. Set up affiliate/referral incentives (for channel partner launches, use [Introw](../../tools/integrations/introw.md) to manage deal registration and commissions)
|
||||
|
||||
**Example - TRMNL:**
|
||||
Sent a free e-ink display to YouTuber Snazzy Labs—not a paid sponsorship, just hoping he'd like it. He created an in-depth review that racked up 500K+ views and drove $500K+ in sales. They also set up an affiliate program for ongoing promotion.
|
||||
@@ -346,7 +346,8 @@ Even small changelog updates remind customers your product is evolving. This bui
|
||||
## Related Skills
|
||||
|
||||
- **marketing-ideas**: For additional launch tactics (#22 Product Hunt, #23 Early Access Referrals)
|
||||
- **email-sequence**: For launch and onboarding email sequences
|
||||
- **page-cro**: For optimizing launch landing pages
|
||||
- **emails**: For launch and onboarding email sequences
|
||||
- **cro**: For optimizing launch landing pages
|
||||
- **marketing-psychology**: For psychology behind waitlists and exclusivity
|
||||
- **programmatic-seo**: For comparison pages mentioned in post-launch
|
||||
- **sales-enablement**: For launch sales collateral and enablement materials
|
||||
@@ -0,0 +1,91 @@
|
||||
{
|
||||
"skill_name": "launch",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "We're launching a new B2B SaaS product for design teams in 6 weeks. It's a design review tool. We have a small audience (500 email subscribers, 2k Twitter followers). Help us plan the launch.",
|
||||
"expected_output": "Should check for product-marketing.md first. Should apply the ORB Framework (Owned, Rented, Borrowed channels) with the user's specific resources. Owned: email list (500 subscribers), website. Rented: Twitter (2k followers). Borrowed: partnerships, communities, Product Hunt. Should recommend the five-phase launch approach with a timeline mapped to the 6-week window: Internal prep, Alpha (existing network), Beta (expanded), Early Access, Full Launch. Should provide specific tactics for each phase. Should recommend building up the audience before launch day. Should include a launch day checklist.",
|
||||
"assertions": [
|
||||
"Checks for product-marketing.md",
|
||||
"Applies ORB Framework (Owned, Rented, Borrowed)",
|
||||
"Maps to user's specific channels and audience sizes",
|
||||
"Recommends five-phase launch approach",
|
||||
"Provides timeline mapped to 6-week window",
|
||||
"Provides specific tactics for each phase",
|
||||
"Recommends audience building before launch",
|
||||
"Includes launch day checklist"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "We want to launch on Product Hunt. Any tips? We've never done it before.",
|
||||
"expected_output": "Should apply the Product Hunt strategy section. Should cover: choosing the right day and time, preparing assets (logo, gallery images, maker video), crafting the tagline and description, building a hunter network, activating supporters on launch day, engaging with comments, and post-launch follow-up. Should recommend preparation timeline (start 2-4 weeks before). Should mention common mistakes to avoid. Should set realistic expectations about outcomes.",
|
||||
"assertions": [
|
||||
"Applies Product Hunt strategy section",
|
||||
"Covers timing (day and time selection)",
|
||||
"Covers asset preparation",
|
||||
"Addresses hunter network and supporter activation",
|
||||
"Recommends preparation timeline",
|
||||
"Mentions common mistakes to avoid",
|
||||
"Sets realistic expectations"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"prompt": "we just shipped a major feature update. how should we announce it? it's not a full product launch, just a big new feature.",
|
||||
"expected_output": "Should trigger on casual phrasing. Should apply the ongoing launch strategy section, specifically the major/medium/minor update matrix. Should identify this as a major feature update. Should recommend appropriate channels and tactics for a feature launch (less than a full product launch but more than a changelog entry). Should include: announcement email, blog post, social media push, in-app notification, and possibly a mini Product Hunt launch. Should provide a feature announcement framework.",
|
||||
"assertions": [
|
||||
"Triggers on casual phrasing",
|
||||
"Applies ongoing launch strategy / update matrix",
|
||||
"Identifies as major feature update",
|
||||
"Scales tactics appropriately (not full launch)",
|
||||
"Recommends announcement channels",
|
||||
"Includes email, blog, social, and in-app notification",
|
||||
"Provides feature announcement framework"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"prompt": "Our launch flopped. We launched 3 weeks ago and only got 50 signups. We expected at least 500. What went wrong and what can we do now?",
|
||||
"expected_output": "Should apply the post-launch product marketing section. Should diagnose potential failure causes: insufficient audience building pre-launch, wrong channels, weak value proposition messaging, poor launch execution, targeting the wrong audience. Should recommend post-launch recovery tactics: iterate on messaging, identify which channels produced the 50 signups and double down, try new distribution channels, leverage early users for testimonials. Should provide a specific 30-day recovery plan.",
|
||||
"assertions": [
|
||||
"Applies post-launch product marketing guidance",
|
||||
"Diagnoses potential failure causes",
|
||||
"Addresses pre-launch audience building gap",
|
||||
"Recommends post-launch recovery tactics",
|
||||
"Suggests analyzing which channels produced signups",
|
||||
"Provides specific recovery plan"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 5,
|
||||
"prompt": "How do we leverage partnerships and borrowed audiences for our launch? We don't have a big audience of our own.",
|
||||
"expected_output": "Should focus on the Borrowed channel from the ORB Framework. Should provide specific borrowed audience tactics: podcast guest appearances, co-marketing with complementary tools, influencer partnerships, community engagement (relevant Slack groups, Discord servers, Reddit), guest posts, cross-promotions. Should recommend how to identify and approach potential partners. Should note that borrowed audience strategies take time to build and should start well before launch day.",
|
||||
"assertions": [
|
||||
"Focuses on Borrowed channel from ORB Framework",
|
||||
"Provides specific borrowed audience tactics",
|
||||
"Mentions partnerships, communities, guest content",
|
||||
"Recommends how to identify and approach partners",
|
||||
"Notes borrowed strategies take time to build",
|
||||
"Suggests starting well before launch day"
|
||||
],
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 6,
|
||||
"prompt": "Give me some creative marketing ideas to promote our product. We're bootstrapped and don't have a big budget.",
|
||||
"expected_output": "Should recognize this is a broader marketing ideas request, not specifically a launch strategy task. Should defer to or cross-reference the marketing-ideas skill, which provides 139 marketing ideas organized by category and filtered by budget. May provide some launch-related tactical ideas but should make clear that marketing-ideas is the right skill for a broader brainstorming session.",
|
||||
"assertions": [
|
||||
"Recognizes this as broader marketing ideas request",
|
||||
"References or defers to marketing-ideas skill",
|
||||
"Does not attempt full marketing brainstorm using launch strategy patterns",
|
||||
"May provide some launch-related tactical ideas"
|
||||
],
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user