Index of every page on this site: llms.txt
All skills
rshankras avatar

/referral-system

@f958982
Run it yourself

Generates referral/invite infrastructure with unique codes, deep link sharing, reward tracking, and fraud prevention. Use when user wants referral codes, invite friends flow, or viral growth mechanics.

Use this Skill: https://skilld.dev/gh/rshankras/claude-code-apple-skills/referral-system

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈55 tokens for metadata: the name and description. ≈2.3k when used: this file. ≈7.7k more on demand in 1 file.

Description uses 2.7% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈219 characters, or 2.7%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Referral System Generator

Generate a production referral/invite system with unique code generation, deep link sharing, reward tracking, fraud prevention, and SwiftUI views for inviting friends and monitoring referral performance.

When This Skill Activates

Use this skill when the user:

  • Asks to "add a referral system" or "referral codes"
  • Wants to "invite friends" or "refer a friend" flow
  • Mentions "viral growth" or "invitation system"
  • Asks about "referral rewards" or "referral tracking"
  • Wants "invite codes" or "shareable invite links"

Pre-Generation Checks

1. Project Context Detection

  • Check Swift version (requires Swift 5.9+)
  • Check deployment target (iOS 17+ / macOS 14+ for @Observable and SwiftData)
  • Identify source file locations
  • Check for existing entitlements (Associated Domains for deep links)

2. Conflict Detection

Search for existing referral/invite code:

Glob: **/*Referral*.swift, **/*Invite*.swift, **/*InviteCode*.swift
Grep: "referralCode" or "inviteCode" or "ReferralManager"

If existing referral system found:

  • Ask if user wants to replace or extend it
  • If extending, identify integration points

3. Deep Link Setup Detection

Search for existing deep link handling:

Glob: **/*DeepLink*.swift, **/*UniversalLink*.swift
Grep: "onOpenURL" or "userActivity" or "NSUserActivity"

If deep link handling exists, integrate with it rather than generating a standalone handler.

Configuration Questions

Ask user via AskUserQuestion:

  1. Reward type?

    • Both-get (referrer and invitee both earn a reward) -- recommended
    • Referrer-only (only the person who shares gets rewarded)
    • Points-based (both parties earn points toward rewards)
  2. Code format?

    • Short alphanumeric (e.g., A7K2M9) -- recommended
    • Custom prefix (e.g., MYAPP-A7K2M9)
    • Username-based (e.g., john-A7K2)
  3. Sharing method?

    • Deep link (universal link with embedded code) -- recommended
    • Clipboard copy (copy code to pasteboard)
    • Share sheet (system share with link and message)
    • All of the above
  4. Storage?

    • SwiftData (local persistence, recommended for most apps)
    • UserDefaults (lightweight, for simple single-code scenarios)
    • CloudKit (sync across devices)

Generation Process

Step 1: Read Templates

Read templates.md for production Swift code.

Step 2: Create Core Files

Generate these files:

  1. ReferralCode.swift -- Model with unique code generation, expiration, usage tracking
  2. ReferralManager.swift -- @Observable manager for code lifecycle and redemption
  3. ReferralReward.swift -- Reward configuration, conditions, and fulfillment tracking

Step 3: Create UI Files

  1. InviteView.swift -- SwiftUI invite screen with code display and sharing
  2. ReferralDashboardView.swift -- Stats view for referral performance

Step 4: Create Integration Files

  1. ReferralDeepLinkHandler.swift -- Deep link parsing and redemption triggering

Step 5: Determine File Location

Check project structure:

  • If Sources/ exists -> Sources/Referral/
  • If App/ exists -> App/Referral/
  • Otherwise -> Referral/

Output Format

After generation, provide:

Files Created

Referral/
├── ReferralCode.swift            # Code model with generation and validation
├── ReferralManager.swift         # @Observable manager for code lifecycle
├── ReferralReward.swift          # Reward config and fulfillment tracking
├── InviteView.swift              # Invite screen with share actions
├── ReferralDashboardView.swift   # Referral stats dashboard
└── ReferralDeepLinkHandler.swift # Deep link parsing and redemption

Integration Steps

Add deep link handling in your App struct:

@main
struct MyApp: App {
    @State private var referralManager = ReferralManager()
    private let deepLinkHandler = ReferralDeepLinkHandler()

    var body: some Scene {
        WindowGroup {
            ContentView()
                .environment(referralManager)
                .onOpenURL { url in
                    if let code = deepLinkHandler.extractCode(from: url) {
                        Task {
                            await referralManager.redeemCode(code)
                        }
                    }
                }
        }
    }
}

Present the invite screen:

struct ProfileView: View {
    @State private var showInvite = false

    var body: some View {
        Button("Invite Friends") { showInvite = true }
            .sheet(isPresented: $showInvite) {
                InviteView()
            }
    }
}

Show referral dashboard:

NavigationLink("My Referrals") {
    ReferralDashboardView()
}

Testing

@Test
func generatedCodeIsUnique() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())

    let code1 = await manager.generateCode(for: "user-1")
    let code2 = await manager.generateCode(for: "user-2")

    #expect(code1.value != code2.value)
}

@Test
func redemptionGrantsReward() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = await manager.generateCode(for: "referrer-1")

    let result = await manager.redeemCode(code.value, redeemedBy: "invitee-1")

    #expect(result == .success)
    #expect(manager.rewards(for: "referrer-1").count == 1)
    #expect(manager.rewards(for: "invitee-1").count == 1)
}

@Test
func selfReferralIsRejected() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = await manager.generateCode(for: "user-1")

    let result = await manager.redeemCode(code.value, redeemedBy: "user-1")

    #expect(result == .fraudDetected(.selfReferral))
}

@Test
func expiredCodeIsRejected() async throws {
    let manager = ReferralManager(store: InMemoryReferralStore())
    let code = ReferralCode(
        value: "EXPIRED1",
        ownerID: "user-1",
        expiresAt: Date.distantPast
    )

    let result = await manager.redeemCode(code.value, redeemedBy: "user-2")

    #expect(result == .expired)
}

Common Patterns

Generate and Share a Referral Code

// Generate code for current user
let code = await referralManager.generateCode(for: currentUserID)

// Share via system share sheet
let shareURL = deepLinkHandler.buildShareURL(for: code)
let message = "Join me on MyApp! Use my code \(code.value) for a bonus."
let activityItems: [Any] = [message, shareURL]

Redeem a Referral Code

// On app launch or deep link open
let result = await referralManager.redeemCode(codeString, redeemedBy: currentUserID)

switch result {
case .success:
    showRewardAnimation()
case .alreadyRedeemed:
    showAlert("You've already used a referral code.")
case .expired:
    showAlert("This referral code has expired.")
case .fraudDetected(let reason):
    logger.warning("Fraud detected: \(reason)")
case .invalid:
    showAlert("Invalid referral code.")
}

Track Rewards

// Check pending rewards
let pending = referralManager.pendingRewards(for: currentUserID)
for reward in pending {
    await fulfillReward(reward)
    await referralManager.markFulfilled(reward)
}

Gotchas

Fraud Prevention

  • Self-referral: Always verify referrer ID != redeemer ID. Users will try creating alt accounts.
  • Device fingerprinting: Consider storing device identifiers to detect multi-account abuse.
  • Rate limiting: Cap the number of referrals per user per time period (e.g., 50 per month).
  • Code reuse: Each invitee should only be able to redeem one referral code ever.

App Store Guidelines

  • Guideline 3.1.1: Digital content or features unlocked as referral rewards must stay consistent with IAP rules (no custom unlock mechanisms in place of IAP), and digital gift cards or vouchers can only be sold via IAP.
  • Guideline 5.6.3 (Discovery Fraud): Referral rewards must not be tied to leaving or boosting App Store ratings or reviews, or otherwise manipulate charts, search, reviews, or referrals.
  • Incentivized installs: Apple may reject apps that reward users purely for downloading. Tie rewards to meaningful in-app actions (e.g., completing a first task, making a purchase).

Deep Link Expiration

  • Universal links require an apple-app-site-association file on your server.
  • Referral deep links should have a TTL (default 30 days) to prevent stale code accumulation.
  • Handle the case where a user taps a referral link but the app is not installed (redirect to App Store, then capture code on first launch).

Data Privacy

  • Referral codes should not expose user PII (no emails or phone numbers in codes).
  • Provide opt-out: let users disable their referral code at any time.
  • Comply with GDPR/CCPA if tracking referral relationships across users.

References

  • templates.md -- All production Swift templates
  • Related: generators/deep-linking -- Universal link and deep link infrastructure
  • Related: generators/share-card -- Visual share cards for social sharing
  • Related: generators/analytics-setup -- Track referral funnel events

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts10d3 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides a standard generator for a referral and invitation system in iOS and macOS applications. It includes templates for managing referral codes, reward tracking, and deep linking with appropriate fraud prevention logic. No security issues or malicious patterns were detected.

  • Socket11d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

Signed by skilld at f958982. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated 2 weeks ago
What it can do
Reads files Edits files Runs commands
last_verified
2026-11-08
review_by
2027-06-22
os_version
iOS 27 / macOS 27
All 7 allowed tools
ReadWriteEditGlobGrepBashAskUserQuestion

README badge

README badge for rshankras/claude-code-apple-skills/referral-system