referral-engine

v1.0.0 MIT growth updated 2026-09-27

Track where your referrals stand — log each referral (referrer, referred, date, status: asked/sent/converted) in a CSV and get a pipeline summary with counts, per-referrer totals, and conversion rate. Includes ask-message templates for requesting referrals without being awkward. Use when you want referrals to become a system instead of luck.

$ skillbank install referral-engine@1.0.0
# pins exactly 1.0.0 · README + changelog included

Referral Engine

Overview

Referrals are the cheapest leads a local business gets, and most owners treat them as luck. Referral Engine makes them a pipeline: log every ask, every referral that comes in, and every one that turns into paying work — then see at a glance who's sending you business and what your conversion rate is. Pair the tracker with the ask templates in references/ask-templates.md so the asking part stops feeling awkward.

All data stays local — nothing is uploaded.

Installation

1. Copy the referral-engine/ directory anywhere convenient. 2. Make the script executable (Unix):


   chmod +x scripts/tracker.py

No pip install needed — standard library only.

Configuration

No config file. Keep one CSV with these columns:

| Column | Required | Description | |------------|----------|----------------------------------------------------------| | referrer | yes | Who sent (or was asked to send) the referral. | | referred | yes | The person referred. | | date | yes | ISO date (YYYY-MM-DD) the row was logged. | | status | yes | One of: asked, sent, converted. |

One row per referral at its current status — when an asked becomes a sent, update the row; don't add a second one.

Inputs

| Command | Arguments | Returns | |---------------------------|------------------------------------------------|--------------------------------------| | tracker.py <referrals.csv> | CSV with referrer, referred, date, status | Pipeline summary + conversion rate. |

Conversion rate = converted ÷ sent. Bad dates, unknown statuses, or missing columns exit with a clear error and a nonzero exit code — never a raw traceback.

Worked example


$ cat > referrals.csv << 'EOF'
referrer,referred,date,status
Maya Thompson,Tom Baker,2026-08-10,asked
Maya Thompson,Lisa Nguyen,2026-08-20,converted
Robert Chen,Sam Rivera,2026-09-01,converted
Robert Chen,Amy Foster,2026-09-05,sent
Robert Chen,Pat Owens,2026-09-15,sent
Dana Lee,Chris Patel,2026-09-10,asked
Dana Lee,Jordan Kim,2026-09-12,sent
EOF
$ ./scripts/tracker.py referrals.csv
Referral pipeline
=================

Total referrals: 7

| Status    | Count | Meaning |
|-----------|-------|---------|
| asked     | 2     | you asked for a referral |
| sent      | 3     | a referral came in |
| converted | 2     | it became paying work |

Conversion rate (converted / sent): 66.7%

Per referrer

| Referrer | Asked | Sent | Converted |
|----------|-------|------|-----------|
| Dana Lee | 1 | 1 | 0 |
| Maya Thompson | 1 | 0 | 1 |
| Robert Chen | 0 | 2 | 1 |

Two takeaways from that sample: Robert Chen is the best source, and Dana Lee's asks aren't turning into sends yet — follow up with Dana (see the ask templates).

Safety notes

A referral log is a relationship record. Keep the CSV private, never share the per-referrer table, and don't rank or pressure referrers publicly — thank the senders, not the numbers.

Version history

Changelog

1.0.0 — 2026-09-27

  • Initial release. scripts/tracker.py summarizes a referral CSV into
  • pipeline counts, per-referrer totals, and conversion rate. Added references/ask-templates.md with ask-message templates.

← back to catalog