Skills
Build referral programs with ak:referral-program-building
Design referral rewards, platform requirements, tracking, fraud controls, messages, and measurement while keeping product, data, payout, and send changes reviewable.
Use ak:referral-program-building to design a customer referral loop for a SaaS
or digital product. The Skill covers reward models, provider selection,
attribution, a technical implementation sketch, fraud controls, email drafts,
and measurement. It can also review an existing program and propose bounded
experiments.
The Skill produces a strategy and implementation blueprint. It does not make a schema production-ready, change the product, install tracking, collect personal data, send email, issue rewards, buy a provider, or launch the program without separate authorization and implementation review.
Choose ak:referral-program-building for customer referrals
Use ak:referral-program-building when
- You need to compare one-sided, two-sided, tiered, milestone, product-credit, discount, cash, gift, or status-based rewards against current economics.
- You need a build-versus-buy decision and integration requirements for a referral provider.
- You need a referral-code, link, attribution, reward-state, or dashboard blueprint.
- You need fraud review, reward-delay, manual approval, fulfillment email, and program measurement flows.
- You want to improve an existing refer-a-friend experience using supplied cohort and funnel evidence.
Choose another workflow when
- You need a compensated affiliate, creator, KOL/KOC, or agency program. Use
ak:affiliate-marketing. - You need a launch or campaign plan around an already approved referral
mechanic. Use
ak:launch-strategyorak:campaign. - You only need an implementation plan for an approved product change. Hand the reviewed referral contract to the appropriate engineering workflow.
- You do not know reward cost, margin, qualifying conversion, refund handling, or customer eligibility. Resolve the economics first.
Prepare the program and data contract
Provide the product and user journey, eligible referrers and referees, qualifying event, reward type and cost, currency, caps, refund or reversal rules, attribution window, consent and notice requirements, target surfaces, existing data model, email policy, fraud-review owner, fulfillment process, budget ceiling, and success measures.
Historical provider examples include Rewardful, ReferralCandy, Viral Loops, FirstPromoter, and Voucherify. Verify current price, feature, integration, security, contract, and data-processing terms before choosing or purchasing a provider.
| Runtime | Invocation | Availability boundary |
|---|---|---|
| Claude Code | /ak:referral-program-building ... | Native delivery is the default; plugin delivery is explicit. No product or provider connection is created by installation. |
| Cursor | /ak:referral-program-building ... | Slash invocation is user-verified. This does not prove provider or automation parity. |
| Codex | $ak:referral-program-building ... | Native Skill discovery is supported. Hook projection is partial, and integrations remain separate. |
See Runtime adapters for projection limits.
Invoke a blueprint-first workflow
/ak:referral-program-building "Design a two-sided product-credit referral proposal for the supplied subscription economics. Define eligibility, attribution, caps, reward states, fraud review, fulfillment messages, and metrics. Produce a technical blueprint only; do not change the product, select a vendor, collect data, send email, or issue rewards"/ak:referral-program-building "Design a two-sided product-credit referral proposal for the supplied subscription economics. Define eligibility, attribution, caps, reward states, fraud review, fulfillment messages, and metrics. Produce a technical blueprint only; do not change the product, select a vendor, collect data, send email, or issue rewards"$ak:referral-program-building "Design a two-sided product-credit referral proposal for the supplied subscription economics. Define eligibility, attribution, caps, reward states, fraud review, fulfillment messages, and metrics. Produce a technical blueprint only; do not change the product, select a vendor, collect data, send email, or issue rewards"The canonical argument shape is [product or program-type]. Add the economic,
data, implementation, communication, and payout boundaries explicitly.
Follow the referral-program stages
- Define the program. Confirm participants, qualifying event, reward on each side, caps, exclusions, attribution, refund and reversal behavior, budget, owner, and non-goals.
- Model reward economics. Compare reward types and milestones using current margin, service cost, liability, redemption, fulfillment, tax, provider fee, and fraud exposure. Keep amounts as scenarios until approved.
- Choose build or provider requirements. Map payment, product, CRM, email, analytics, webhook, mobile, reporting, accessibility, security, and privacy needs. Use current primary evidence for any buying recommendation.
- Design the technical contract. Define code creation, referral links, attribution, states, idempotency, reversals, caps, audit records, dashboards, and failure handling. Treat the bundled schema and endpoint examples as a starting sketch only.
- Add abuse and review controls. Define self-referral, velocity, duplicate, payment, refund, device or network signals, manual review, appeal, reward delay, and false-positive handling.
- Prepare communication and launch. Draft introduction, progress, reminder, and fulfillment messages; test end to end; soft-launch only after product, data, finance, legal, support, and go/no-go approval.
- Measure and iterate. Record participation, referred conversion, reward cost, fulfillment, refund, fraud, customer quality, and incremental value using explicit definitions and comparison periods.
Review the packaged technical sketch
The Skill reference proposes these exact illustrative surfaces:
| Surface | Canonical names in the sketch |
|---|---|
| User fields | id, email, referral_code, referred_by_id, created_at |
| Referral fields | id, referrer_id, referee_id, status, reward_amount, conversion_timestamp, created_at |
| Click fields | id, referral_code, ip_address, device_fingerprint, click_timestamp, converted |
| Generate | POST /api/referrals/generate → referral_code, referral_url, share_urls |
| List for a user | GET /api/users/:id/referrals → referrals and stats with total, converted, pending |
| Apply a code | POST /api/referrals/apply with referral_code and email → success, message, discount_applied |
| Convert | POST /api/referrals/:id/convert → success, reward_issued |
The reference schema is not a production contract
The sketch stores email, IP address, and a device fingerprint and uses simple state and attribution examples. Before implementation, review authentication, authorization, consent, minimization, encryption, retention, deletion, idempotency, race conditions, reward liability, abuse, accessibility, audit, observability, regional rules, and recovery. Do not copy the SQL or JavaScript directly into a live system.
The reference also shows cookie, UTM, subdomain, deep-link, and mobile attribution patterns. Provider and platform behavior changes; validate the chosen mechanism and obtain privacy and engineering approval before collecting or persisting any signal.
Keep product, data, email, and payout effects separate
| Proposed effect | Approval boundary |
|---|---|
| Database, API, UI, cookie, or mobile change | Require an approved engineering plan, security and privacy review, tests, migration and rollback strategy, and product sign-off. |
| IP, device, email, or referral-event collection | Approve lawful basis, notice, allowed fields, access, retention, deletion, vendor flow, and false-positive handling. |
| Email or in-product message | Approve audience, trigger, consent, sender, claims, amounts, frequency, opt-out, and support path before sending. |
| Reward creation or fulfillment | Approve eligibility, amount, currency, caps, tax, refund and reversal, accounting, payment authority, and dispute handling. |
| Vendor purchase or integration | Approve current price, contract, credentials, data processing, access scope, operational owner, and exit plan. |
Review outputs and evidence
The canonical report path is
assets/reports/performance/{date}-referral-program.md when the packaged
asset-organizing convention is used. A complete result should include program
rules and economics, provider requirements, technical contract, threat and
privacy review questions, message drafts, rollout gates, metric definitions,
source systems, approval owners, and unresolved decisions.
Do not present historical conversion, retention, cost, growth, or ROI examples as expected results. For an existing program, preserve query definitions, date ranges, cohort selection, reward status, refunds, and data gaps with the report.
Troubleshoot safely
| Symptom | Safe next step |
|---|---|
The runtime does not recognize ak:referral-program-building | Confirm Marketing Kit target and scope, restart the runtime, then follow Runtime cannot find a Skill or Agent. |
| Reward amounts are not sustainable | Remove them from launch scope, rerun the model with current margin and liability, and obtain finance approval. |
| A provider recommendation looks stale | Verify current official features, pricing, data terms, integrations, and migration options before purchase. |
| Attribution produces duplicates or disputes | Define precedence, idempotency, deduplication, reversals, manual review, and audit evidence before issuing rewards. |
| Fraud rules block legitimate users | Stop automatic action, preserve evidence, review bias and shared-network cases, and use an approved appeals process. |
| Email copy contains invented earnings or urgency | Remove the claim, replace placeholders with approved facts, and keep the message unsent until review. |
| Implementation has already changed production | Stop rollout, capture current state and affected records, follow the product's recovery plan, and do not apply broad corrective writes. |
Know the current limits
- Bundled provider details, prices, benchmarks, implementation patterns, and case-study outcomes are historical examples, not current guarantees.
- The Skill cannot guarantee participation, conversion, retention, lower acquisition cost, viral growth, customer value, fraud prevention, or ROI.
- The implementation sketch does not replace product, engineering, security, privacy, legal, finance, accounting, tax, accessibility, or support review.
- Installation does not create provider access, a production data contract, a payout mechanism, or authority to contact customers.
Continue with the Marketing Kit overview or compare
ak:affiliate-marketing before choosing the growth
model.
Design affiliate programs with ak:affiliate-marketing
Define partner economics, platform requirements, recruitment, compliance, fraud controls, and measurement without committing spend or contacting partners by default.
Design, analyze, or optimize a funnel with ak:funnel
Map funnel stages and metrics, audit observed drop-off, or produce prioritized optimization and test recommendations.