Crowd9/giveaway-skills / skills/giveaway-prize-picker
giveaway-prize-picker
VerifiedChoose and evaluate giveaway, contest, sweepstakes or raffle Prizes, budgets and fulfilment. Use for 'what should we give away', 'is this a good Prize', 'giveaway budget', 'Prize bundle', 'what Prize gets the most entries', 'B2B giveaway Prize', 'webinar giveaway', or 'attract buyers, not freebie hunters'.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 21.4 KB |
| evals/cases.md | markdown | 14.0 KB |
| evals/evals.json | config | 36.7 KB |
| references/buyer-prizes.md | markdown | 9.0 KB |
| references/decision-criteria.md | markdown | 28.1 KB |
| references/evidence-and-limitations.md | markdown | 34.7 KB |
| references/evidence-detail.md | markdown | 3.2 KB |
| references/examples.md | markdown | 4.9 KB |
| references/gleam-setup.md | markdown | 3.0 KB |
| references/house-style.md | markdown | 4.7 KB |
| references/prize-taxonomy.md | markdown | 17.6 KB |
| references/prize-values-by-category-and-size.json | config | 12.3 KB |
| references/roi-benchmarks.md | markdown | 14.7 KB |
| scripts/budget.py | script | 16.6 KB |
| scripts/roi.py | script | 23.3 KB |
| scripts/style_check.pyexecutable | script | 40.3 KB |
scripts/budget.py
View on GitHub#!/usr/bin/env python3
"""Giveaway budget calculator. Python 3.8+, no dependencies. Every number in is an estimate and every number out is one.
Price one 500 USD grand Prize and five 60 USD runner-up Prizes that cost us 60% of retail, where one Entrant in five is overseas.
python3 budget.py --currency USD --prize "Grand Prize" 500 1 --prize "Runner-up" 60 5 \
--cost-ratio 0.6 --shipping 25 --international-share 0.2 --international-shipping 60 \
--duty-rate 0.1 --tax-on-prize 0 --substitute-reserve 1 --admin-hours 6 --hourly 50 --promotion 300 --contingency 0.08
Check the arithmetic still works after an edit.
python3 budget.py --self-test
--cost-ratio is what a unit costs you as a fraction of retail (1.0 for bought at retail, 0.5 for own product at half).
Pass --winners with the number of people winning to show cost per Winner. Prize units may share a Winner.
Shipping and duty apply to physical units only (end the Prize name with "(digital)" to skip them).
For bundles or multiple parcels, --shipping-total overrides calculated shipping with the complete delivery quote.
For mixed-cost Prizes, --substitute-reserve-amount sets the actual replacement reserve instead of using the global cost ratio.
Every figure is in one currency. For a Prize bought or shipped in another, convert before you enter it and pass --rate
"1 USD = 0.92 EUR, 9 Sep 2026" so the rate and the date it was taken sit on the printed breakdown.
"""
import argparse, json, math, sys
def compute(a):
shipping_total = getattr(a, "shipping_total", None)
reserve_amount = getattr(a, "substitute_reserve_amount", None)
for field, value in (("shipping total", shipping_total), ("substitute reserve amount", reserve_amount)):
if value is not None and (not math.isfinite(value) or value < 0):
raise ValueError(field + " must be finite and nonnegative")
if reserve_amount is not None and a.substitute_reserve:
raise ValueError("choose substitute reserve units or an amount, not both")
for field in ("cost_ratio", "shipping", "international_share", "international_shipping", "duty_rate", "tax_on_prize", "substitute_reserve", "admin_hours", "hourly", "promotion", "contingency"):
value = getattr(a, field)
if not math.isfinite(value) or value < 0:
raise ValueError(field.replace("_", " ") + " must be finite and nonnegative")
if a.international_share > 1:
raise ValueError("international share must be between zero and one")
consolation_values = (a.consolation_quantity, a.consolation_unit_cost, a.consolation_max_liability)
consolation = None
if any(v is not None for v in consolation_values):
if any(v is None for v in consolation_values):
raise ValueError("consolation requires quantity, unit cost and maximum liability together")
if any(not math.isfinite(v) or v < 0 for v in consolation_values):
raise ValueError("consolation values must be finite and nonnegative")
if a.consolation_quantity != int(a.consolation_quantity):
raise ValueError("consolation quantity must be a whole number")
full_redemption_cost = a.consolation_quantity * a.consolation_unit_cost
if full_redemption_cost > a.consolation_max_liability + 1e-9:
raise ValueError("consolation maximum liability must cover quantity times unit cost")
consolation = {"quantity": a.consolation_quantity, "unit_cost": a.consolation_unit_cost,
"full_redemption_cost": full_redemption_cost, "maximum_liability": a.consolation_max_liability}
if a.budget is not None and (not math.isfinite(a.budget) or a.budget < 0):
raise ValueError("budget must be finite and nonnegative")
if a.winners is not None and (not isinstance(a.winners, int) or isinstance(a.winners, bool) or a.winners < 1):
raise ValueError("winners must be a positive integer")
prizes = []
for p in a.prize:
name, retail, units = p[0], float(p[1]), int(p[2]); digital = name.lower().endswith("(digital)")
if not math.isfinite(retail) or retail < 0 or units <= 0:
raise ValueError("Prize retail must be finite and nonnegative, and units must be positive")
prizes.append({"name": name, "retail": retail, "units": units, "digital": digital})
retail_total = sum(p["retail"] * p["units"] for p in prizes)
cost_total = retail_total * a.cost_ratio
phys_units = sum(p["units"] for p in prizes if not p["digital"])
intl_units = phys_units * a.international_share; dom_units = phys_units - intl_units
shipping = dom_units * a.shipping + intl_units * a.international_shipping
if shipping_total is not None:
shipping = shipping_total
duty = sum(p["retail"] * p["units"] for p in prizes if not p["digital"]) * a.international_share * a.duty_rate
winner_tax = retail_total * a.tax_on_prize
substitute = a.substitute_reserve * (max((p["retail"] for p in prizes), default=0) * a.cost_ratio)
if reserve_amount is not None:
substitute = reserve_amount
admin = a.admin_hours * a.hourly
consolation_reserve = consolation["maximum_liability"] if consolation else 0
subtotal = cost_total + shipping + duty + winner_tax + substitute + admin + a.promotion + consolation_reserve
contingency = subtotal * a.contingency
shipping_label = "Shipping (quoted total)" if shipping_total is not None else "Shipping (domestic + international units)"
lines = [("Prize cost to you (retail x cost ratio)", cost_total), (shipping_label, shipping),
("Duties on international units", duty), ("Prize tax you cover", winner_tax), ("Substitute reserve", substitute),
("Admin time", admin), ("Promotion", a.promotion), ("Consolation maximum liability", consolation_reserve),
("Contingency", contingency)]
total = subtotal + contingency
result = {"currency": a.currency, "prizes": prizes, "retail_value_total": retail_total, "lines": lines, "total_estimate": total,
"headline_value_you_can_state": retail_total, "cost_per_prize_unit": total / max(1, sum(p["units"] for p in prizes)),
"winners": a.winners, "cost_per_winner": total / a.winners if a.winners is not None else None,
"consolation": consolation}
if a.budget is not None:
result.update(budget=a.budget, budget_remaining=a.budget - total, within_budget=total <= a.budget + 1e-9)
return result
def main(argv):
ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
ap.add_argument("--currency", default="USD"); ap.add_argument("--prize", nargs=3, action="append", metavar=("NAME", "RETAIL", "UNITS"), default=[])
ap.add_argument("--winners", type=int, help="number of people winning, which can differ from the number of Prize units")
ap.add_argument("--cost-ratio", type=float, default=1.0); ap.add_argument("--shipping", type=float, default=0.0)
ap.add_argument("--shipping-total", type=float, help="total delivery quote for all parcels, overrides calculated shipping only")
ap.add_argument("--international-share", type=float, default=0.0); ap.add_argument("--international-shipping", type=float, default=0.0)
ap.add_argument("--duty-rate", type=float, default=0.0); ap.add_argument("--tax-on-prize", type=float, default=0.0)
reserve = ap.add_mutually_exclusive_group()
reserve.add_argument("--substitute-reserve", type=float, default=0.0, help="units of the most expensive Prize held back at cost")
reserve.add_argument("--substitute-reserve-amount", type=float, help="actual replacement reserve in the chosen currency, instead of units at the global cost ratio")
ap.add_argument("--admin-hours", type=float, default=0.0); ap.add_argument("--hourly", type=float, default=0.0)
ap.add_argument("--promotion", type=float, default=0.0); ap.add_argument("--contingency", type=float, default=0.08)
ap.add_argument("--consolation-quantity", type=int, help="maximum number of consolation redemptions offered")
ap.add_argument("--consolation-unit-cost", type=float, help="all-in cost per consolation redemption")
ap.add_argument("--consolation-max-liability", type=float, help="reserve included in total, must cover quantity times unit cost")
ap.add_argument("--budget", type=float, help="hard total to compare against the estimate, including consolation and contingency")
ap.add_argument("--rate", help='exchange rate and the date you took it, e.g. "1 USD = 0.92 EUR, 9 Sep 2026"')
ap.add_argument("--json", action="store_true"); ap.add_argument("--self-test", action="store_true")
a = ap.parse_args(argv)
if a.self_test: return self_test()
if not a.prize: ap.error("at least one --prize NAME RETAIL UNITS")
try:
r = compute(a)
except ValueError as exc:
ap.error(str(exc))
exit_code = 1 if r.get("within_budget") is False else 0
if a.json: print(json.dumps(r, indent=2)); return exit_code
c = r["currency"]
print(f"Retail value you can state: {c} {r['retail_value_total']:,.0f}")
for label, v in r["lines"]: print(f" {label:44} {c} {v:,.0f}")
if r["consolation"]:
offer = r["consolation"]
print(f"Consolation capped at {offer['quantity']} redemptions at {c} {offer['unit_cost']:,.2f} each, maximum liability {c} {offer['maximum_liability']:,.2f}.")
print(f"Total estimate: {c} {r['total_estimate']:,.0f} (about {c} {r['cost_per_prize_unit']:,.0f} per Prize unit). Estimates only. Confirm prices and shipping quotes before committing.")
if r["winners"] is not None:
print(f"Cost per Winner: {c} {r['cost_per_winner']:,.0f} across {r['winners']} Winner(s).")
if a.budget is not None:
label = "Estimated budget remaining" if r["within_budget"] else "Over budget"
print(f"{label}: {c} {abs(r['budget_remaining']):,.2f}")
if a.rate: print(f"Converted at {a.rate}. Rates move, so re-check before committing.")
elif a.international_share: print(f"Multi-region prize with everything priced in {c}. Pass --rate with the exchange rate and the date you took it.")
return exit_code
def self_test():
class A: pass
a = A(); a.currency = "USD"; a.prize = [["Grand", "500", "1"], ["Runner (digital)", "60", "5"]]; a.cost_ratio = 0.5; a.shipping = 20; a.international_share = 0.5
a.international_shipping = 60; a.duty_rate = 0.1; a.tax_on_prize = 0; a.substitute_reserve = 1; a.admin_hours = 2; a.hourly = 50; a.promotion = 100; a.contingency = 0.1
a.consolation_quantity = None; a.consolation_unit_cost = None; a.consolation_max_liability = None; a.budget = None; a.winners = None
r = compute(a); L = dict(r["lines"])
assert r["retail_value_total"] == 800 and L["Prize cost to you (retail x cost ratio)"] == 400
assert abs(L["Shipping (domestic + international units)"] - (0.5 * 20 + 0.5 * 60)) < 1e-9 # one physical unit split
assert abs(L["Duties on international units"] - 500 * 0.5 * 0.1) < 1e-9 and L["Substitute reserve"] == 250 and L["Admin time"] == 100
assert abs(r["total_estimate"] - (400 + 40 + 25 + 0 + 250 + 100 + 100) * 1.1) < 1e-6
a.consolation_quantity = 20; a.consolation_unit_cost = 1.5; a.consolation_max_liability = 35; a.budget = 1050
r = compute(a)
assert r["consolation"]["full_redemption_cost"] == 30
assert dict(r["lines"])["Consolation maximum liability"] == 35
assert abs(r["total_estimate"] - 1045) < 1e-6
assert r["within_budget"] and abs(r["budget_remaining"] - 5) < 1e-6
a.budget = 1000
r = compute(a)
assert not r["within_budget"] and abs(r["budget_remaining"] + 45) < 1e-6
for quantity, unit_cost, liability in [(20, 1.5, 29), (20, None, 35), (-1, 1.5, 35), (20, float("nan"), 35)]:
a.consolation_quantity, a.consolation_unit_cost, a.consolation_max_liability = quantity, unit_cost, liability
try:
compute(a)
except ValueError:
pass
else:
raise AssertionError("invalid consolation offer accepted")
a.consolation_quantity = a.consolation_unit_cost = a.consolation_max_liability = None
a.international_share = 0.004; a.shipping = 0; a.international_shipping = 100
assert abs(dict(compute(a)["lines"])["Shipping (domestic + international units)"] - 0.4) < 1e-9
for field, bad in [("shipping", -1), ("cost_ratio", float("nan")), ("promotion", float("inf")), ("international_share", 1.1)]:
previous = getattr(a, field); setattr(a, field, bad)
try:
compute(a)
except ValueError:
pass
else:
raise AssertionError("invalid budget input accepted: " + field)
setattr(a, field, previous)
for prize in [["Invalid", "-1", "1"], ["Invalid", "nan", "1"], ["Invalid", "10", "0"], ["Invalid", "10", "-1"]]:
a.prize = [prize]
try:
compute(a)
except ValueError:
pass
else:
raise AssertionError("invalid prize accepted")
import contextlib, io
args = ["--prize", "Camera", "400", "1", "--prize", "Lens", "200", "1", "--contingency", "0"]
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(args + ["--winners", "1", "--json"]) == 0
bundle = json.loads(output.getvalue())
assert bundle["cost_per_prize_unit"] == 300 and bundle["cost_per_winner"] == 600
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(args + ["--winners", "1"]) == 0
assert "300 per Prize unit" in output.getvalue() and "Cost per Winner: USD 600" in output.getvalue()
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(args) == 0
assert "300 per Prize unit" in output.getvalue() and "Cost per Winner" not in output.getvalue()
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(args + ["--winners", "2", "--json"]) == 0
assert json.loads(output.getvalue())["cost_per_winner"] == 300
for count in ("0", "-1", "1.5"):
with contextlib.redirect_stderr(io.StringIO()):
try:
main(args + ["--winners", count])
except SystemExit as exc:
assert exc.code == 2
else:
raise AssertionError("invalid Winner count accepted")
# Shipping quotes count parcels, independently of Prize units and Winners.
shipping_args = args + ["--shipping", "25", "--json"]
for extra, expected_shipping, expected_total in [
(["--winners", "1"], 50, 650),
(["--winners", "1", "--shipping-total", "25"], 25, 625),
(["--winners", "1", "--shipping-total", "50"], 50, 650),
(["--winners", "2", "--shipping-total", "65"], 65, 665),
(["--winners", "1", "--shipping-total", "0"], 0, 600),
]:
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(shipping_args + extra) == 0
result = json.loads(output.getvalue())
assert result["lines"][1][1] == expected_shipping
assert result["total_estimate"] == expected_total
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(shipping_args + ["--shipping-total", "25", "--international-share", "0.5", "--duty-rate", "0.1"]) == 0
result = json.loads(output.getvalue())
assert dict(result["lines"])["Duties on international units"] == 30
assert result["total_estimate"] == 655
mixed = ["--prize", "Own product", "100", "1", "--prize", "Device", "500", "1",
"--cost-ratio", str(530 / 600), "--contingency", "0", "--json"]
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(mixed + ["--substitute-reserve-amount", "500"]) == 0
result = json.loads(output.getvalue())
assert result["lines"][0][1] == 530 and dict(result["lines"])["Substitute reserve"] == 500
assert result["total_estimate"] == 1030
with contextlib.redirect_stdout(io.StringIO()) as output:
assert main(mixed + ["--substitute-reserve-amount", "0"]) == 0
assert json.loads(output.getvalue())["total_estimate"] == 530
for option in ("--shipping-total", "--substitute-reserve-amount"):
for bad in ("-1", "nan", "inf"):
with contextlib.redirect_stderr(io.StringIO()):
try:
main(args + [option, bad])
except SystemExit as exc:
assert exc.code == 2
else:
raise AssertionError("invalid override accepted: " + option)
with contextlib.redirect_stderr(io.StringIO()):
try:
main(mixed + ["--substitute-reserve", "1", "--substitute-reserve-amount", "500"])
except SystemExit as exc:
assert exc.code == 2
else:
raise AssertionError("conflicting reserve options accepted")
print("self-test passed"); return 0
if __name__ == "__main__": sys.exit(main(sys.argv[1:]))
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |