Files
skills/public/referral-program.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

318 lines
21 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>referral-program</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/referral-program">
<link rel="alternate" type="text/markdown" href="/referral-program.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/referral-program.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>referral-program</h1><p class="lede">When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy. Also use when the user mentions &#x27;referral,&#x27; &#x27;affiliate,&#x27; &#x27;ambassador,&#x27; &#x27;word of mouth,&#x27; &#x27;viral loop,&#x27; &#x27;refer a friend,&#x27; &#x27;partner program,&#x27; &#x27;referral incentive,&#x27; &#x27;how to get referrals,&#x27; &#x27;customers referring customers,&#x27; or &#x27;affiliate payout.&#x27; Use this whenever someone wants existing users or partners to bring in new customers. For launch-specific virality, see launch-strategy.</p><h1>Referral &amp; Affiliate Programs</h1>
<p>You are an expert in viral growth and referral marketing. Your goal is to help design and optimize programs that turn customers into growth engines.</p>
<h2>Before Starting</h2>
<p><strong>Check for product marketing context first:</strong> If <code>.agents/product-marketing-context.md</code> exists (or <code>.agents/product-marketing-context.md</code> in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.</p>
<p>Gather this context (ask if not provided):</p>
<h3>1. Program Type</h3>
<ul><li>Customer referral program, affiliate program, or both?</li><li>B2B or B2C?</li><li>What&#x27;s the average customer LTV?</li><li>What&#x27;s your current CAC from other channels?</li></ul>
<h3>2. Current State</h3>
<ul><li>Existing referral/affiliate program?</li><li>Current referral rate (% who refer)?</li><li>What incentives have you tried?</li></ul>
<h3>3. Product Fit</h3>
<ul><li>Is your product shareable?</li><li>Does it have network effects?</li><li>Do customers naturally talk about it?</li></ul>
<h3>4. Resources</h3>
<ul><li>Tools/platforms you use or consider?</li><li>Budget for referral incentives?</li></ul>
<hr>
<h2>Referral vs. Affiliate</h2>
<h3>Customer Referral Programs</h3>
<p><strong>Best for:</strong></p>
<ul><li>Existing customers recommending to their network</li><li>Products with natural word-of-mouth</li><li>Lower-ticket or self-serve products</li></ul>
<p><strong>Characteristics:</strong></p>
<ul><li>Referrer is an existing customer</li><li>One-time or limited rewards</li><li>Higher trust, lower volume</li></ul>
<h3>Affiliate Programs</h3>
<p><strong>Best for:</strong></p>
<ul><li>Reaching audiences you don&#x27;t have access to</li><li>Content creators, influencers, bloggers</li><li>Higher-ticket products that justify commissions</li></ul>
<p><strong>Characteristics:</strong></p>
<ul><li>Affiliates may not be customers</li><li>Ongoing commission relationship</li><li>Higher volume, variable trust</li></ul>
<hr>
<h2>Referral Program Design</h2>
<h3>The Referral Loop</h3>
<pre><code>Trigger Moment → Share Action → Convert Referred → Reward → (Loop)</code></pre>
<h3>Step 1: Identify Trigger Moments</h3>
<p><strong>High-intent moments:</strong></p>
<ul><li>Right after first &quot;aha&quot; moment</li><li>After achieving a milestone</li><li>After exceptional support</li><li>After renewing or upgrading</li></ul>
<h3>Step 2: Design Share Mechanism</h3>
<p><strong>Ranked by effectiveness:</strong></p>
<ol><li>In-product sharing (highest conversion)</li><li>Personalized link</li><li>Email invitation</li><li>Social sharing</li><li>Referral code (works offline)</li></ol>
<h3>Step 3: Choose Incentive Structure</h3>
<p><strong>Single-sided rewards</strong> (referrer only): Simpler, works for high-value products</p>
<p><strong>Double-sided rewards</strong> (both parties): Higher conversion, win-win framing</p>
<p><strong>Tiered rewards</strong>: Gamifies referral process, increases engagement</p>
<p><strong>For examples and incentive sizing</strong>: See <a href="references/program-examples.md">references/program-examples.md</a></p>
<hr>
<h2>Program Optimization</h2>
<h3>Improving Referral Rate</h3>
<p><strong>If few customers are referring:</strong></p>
<ul><li>Ask at better moments</li><li>Simplify sharing process</li><li>Test different incentive types</li><li>Make referral prominent in product</li></ul>
<p><strong>If referrals aren&#x27;t converting:</strong></p>
<ul><li>Improve landing experience for referred users</li><li>Strengthen incentive for new users</li><li>Ensure referrer&#x27;s endorsement is visible</li></ul>
<h3>A/B Tests to Run</h3>
<p><strong>Incentive tests:</strong> Amount, type, single vs. double-sided, timing</p>
<p><strong>Messaging tests:</strong> Program description, CTA copy, landing page copy</p>
<p><strong>Placement tests:</strong> Where and when the referral prompt appears</p>
<h3>Common Problems &amp; Fixes</h3>
<p>| Problem | Fix | |---------|-----| | Low awareness | Add prominent in-app prompts | | Low share rate | Simplify to one click | | Low conversion | Optimize referred user experience | | Fraud/abuse | Add verification, limits | | One-time referrers | Add tiered/gamified rewards |</p>
<hr>
<h2>Measuring Success</h2>
<h3>Key Metrics</h3>
<p><strong>Program health:</strong></p>
<ul><li>Active referrers (referred someone in last 30 days)</li><li>Referral conversion rate</li><li>Rewards earned/paid</li></ul>
<p><strong>Business impact:</strong></p>
<ul><li>% of new customers from referrals</li><li>CAC via referral vs. other channels</li><li>LTV of referred customers</li><li>Referral program ROI</li></ul>
<h3>Typical Findings</h3>
<ul><li>Referred customers have 16-25% higher LTV</li><li>Referred customers have 18-37% lower churn</li><li>Referred customers refer others at 2-3x rate</li></ul>
<hr>
<h2>Launch Checklist</h2>
<h3>Before Launch</h3>
<ul><li>[ ] Define program goals and success metrics</li><li>[ ] Design incentive structure</li><li>[ ] Build or configure referral tool</li><li>[ ] Create referral landing page</li><li>[ ] Set up tracking and attribution</li><li>[ ] Define fraud prevention rules</li><li>[ ] Create terms and conditions</li><li>[ ] Test complete referral flow</li></ul>
<h3>Launch</h3>
<ul><li>[ ] Announce to existing customers</li><li>[ ] Add in-app referral prompts</li><li>[ ] Update website with program details</li><li>[ ] Brief support team</li></ul>
<h3>Post-Launch (First 30 Days)</h3>
<ul><li>[ ] Review conversion funnel</li><li>[ ] Identify top referrers</li><li>[ ] Gather feedback</li><li>[ ] Fix friction points</li><li>[ ] Send reminder emails to non-referrers</li></ul>
<hr>
<h2>Email Sequences</h2>
<h3>Referral Program Launch</h3>
<pre><code>Subject: You can now earn [reward] for sharing [Product]
We just launched our referral program!
Share [Product] with friends and earn [reward] for each signup.
They get [their reward] too.
[Unique referral link]
1. Share your link
2. Friend signs up
3. You both get [reward]</code></pre>
<h3>Referral Nurture Sequence</h3>
<ul><li>Day 7: Remind about referral program</li><li>Day 30: &quot;Know anyone who&#x27;d benefit?&quot;</li><li>Day 60: Success story + referral prompt</li><li>After milestone: &quot;You achieved [X]—know others who&#x27;d want this?&quot;</li></ul>
<hr>
<h2>Affiliate Programs</h2>
<p><strong>For detailed affiliate program design, commission structures, recruitment, and tools</strong>: See <a href="references/affiliate-programs.md">references/affiliate-programs.md</a></p>
<hr>
<h2>Task-Specific Questions</h2>
<ol><li>What type of program (referral, affiliate, or both)?</li><li>What&#x27;s your customer LTV and current CAC?</li><li>Existing program or starting from scratch?</li><li>What tools/platforms are you considering?</li><li>What&#x27;s your budget for rewards/commissions?</li><li>Is your product naturally shareable?</li></ol>
<hr>
<h2>Tool Integrations</h2>
<p>For implementation, see the <a href="../../tools/REGISTRY.md">tools registry</a>. Key tools for referral programs:</p>
<p>| Tool | Best For | Guide | |------|----------|-------| | <strong>Rewardful</strong> | Stripe-native affiliate programs | <a href="../../tools/integrations/rewardful.md">rewardful.md</a> | | <strong>Tolt</strong> | SaaS affiliate programs | <a href="../../tools/integrations/tolt.md">tolt.md</a> | | <strong>Mention Me</strong> | Enterprise referral programs | <a href="../../tools/integrations/mention-me.md">mention-me.md</a> | | <strong>Dub.co</strong> | Link tracking and attribution | <a href="../../tools/integrations/dub-co.md">dub-co.md</a> | | <strong>Stripe</strong> | Payment processing (for commission tracking) | <a href="../../tools/integrations/stripe.md">stripe.md</a> |</p>
<hr>
<h2>Related Skills</h2>
<ul><li><strong>launch-strategy</strong>: For launching referral program effectively</li><li><strong>email-sequence</strong>: For referral nurture campaigns</li><li><strong>marketing-psychology</strong>: For understanding referral motivation</li><li><strong>analytics-tracking</strong>: For tracking referral attribution</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/referral-program.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>