Skill: rijoyai/affiliate-kol-roi-monitor (version 0.1.0)

--- name: affiliate-kol-roi-monitor description: Automate affiliate and KOL reconciliation, attribution, true ROAS, commission math, and renewal strategy. Use when the user has more than ~5 KOL or affiliate partners, needs real ROAS (not vanity clicks), must match orders to creators, settle commissions net of refunds, spot fake or low-quality traffic, or wants influencer performance reports and tiered renewal offers. Also trigger on affiliate payout disputes, UTM vs discount-code attribution, "which creator actually sold," commission spreadsheets, or CAC by creator — even if they only say "clean up our affiliate mess." Do NOT use for generic social media growth tips with no orders or payouts, pure content calendars without performance data, or single one-off creator contracts with no reconciliation need. compatibility: required: [] --- # Affiliate & KOL ROI Monitor You replace **manual commission runs**, **order-to-creator matching**, and **influencer performance reporting** with a repeatable workflow: **attribution data → net of refunds → profit-aware economics → tiered renewals**. ## Core workflow (always follow in order) 1. **Extract attribution data** — Map each order (or session) to a creator: discount codes, UTM (`utm_source`, `utm_medium`, `utm_campaign`), affiliate platform IDs, first-touch / last-touch rules. State the rule you use. 2. **Exclude refund / chargeback orders** — Remove or weight down refunded revenue and reversed commissions for the reporting window. Call out partial refunds. 3. **Compute actual profit (where inputs allow)** — Revenue net of refunds × margin (or COGS) minus **creator cost** (fixed fee + variable commission) = contribution per creator. If margin unknown, show revenue net of refunds and CAC using **payout as cost**. 4. **Tiered renewal proposals** — Rate each creator; propose continue / renegotiate / pause with concrete terms (rate, cap, exclusivity, content minimums). ## When NOT to use - No order or payout data — only branding or follower counts. - Single creator, no reconciliation — simple contract review only. - Paid ads (Meta/Google) without affiliate linkage — use ads ROAS skills. ## Gather context (infer first; ask gaps) 1. Platform: Shopify, WooCommerce, Impact, ShareASale, custom spreadsheet? 2. Attribution: code-only, UTM-only, or hybrid; window (e.g. 7-day click). 3. Commission model: % of sale, flat per order, hybrid, tiered by volume. 4. Refund policy: full window for affiliate eligibility; chargebacks. 5. Gross margin or COGS % (or confirm "use payout as CAC proxy"). 6. Renewal date or campaign end. For fraud heuristics and renewal rubric detail, read `references/affiliate_playbook.md` when needed. ## Mandatory success output: master table Every **full** affiliate reconciliation or ROI report must include this table (one row per creator; use **Influencer ID** as the stable key — handle, platform ID, or internal code): | Influencer ID | Orders attributed | Actual revenue | CAC | Renewal rating | |---------------|-------------------|----------------|-----|----------------| | … | … | … | … | … | **Column definitions** - **Influencer ID**: Stable identifier (agree with merchant). - **Orders attributed**: Count of orders matched to this creator in the window, **after** refund/chargeback exclusion (state rule). - **Actual revenue**: **Net revenue** attributable to that creator (gross order value minus refunds for attributed orders), same currency. - **CAC**: **Customer acquisition cost for that creator’s attributed sales** — typically `(fixed fees + variable commissions + product/samples allocated)` divided by **new customers** or by **attributed orders**; if only payout is known, define CAC as **total creator cost / attributed orders** and label it clearly. - **Renewal rating**: Tier such as **A (renew strong)**, **B (renew with caps)**, **C (renegotiate or shorten)**, **D (pause / investigate fraud)** — always tie to numbers (conversion, refund rate, traffic quality). Below the table, add: **ROAS proxy** (revenue / creator cost), **fraud or quality flags** if any, and **renewal terms** per tier. ## Pushy deliverables (when user asks vaguely) If they ask "who should we keep" or "affiliate ROI" without structure, still output: the **master table**, **attribution rule summary**, **refund-adjusted figures**, and **at least two renewal scenarios** (e.g. same rate vs reduced rate + cap). ## Report outline (full run) 1. Scope — date range, attribution rule, currency. 2. Master table — required columns above. 3. Refund / chargeback impact — table or bullets per creator if material. 4. Profit or contribution — formula stated; margin assumptions if used. 5. Fraud / low-quality signals — spikes, refund rate, session quality (if data exists). 6. Renewal playbook — A/B/C/D actions and suggested contract language bullets. ## Split with other skills - **Paid social ads** without affiliates → not this skill. - **Legal contracts** → flag for counsel; you provide economic summary only.

path: assets/README.md
content: # Assets

Optional: commission statement templates, renewal one-pagers. Skill defaults to Markdown tables and narrative.

path: evals/README.md
content: # Evals

Test prompts and expectations live in `evals.json`. Run with_skill vs without_skill per skill-creator under e.g. `affiliate-kol-roi-monitor-workspace/iteration-N/`.

path: evals/evals.json
content: {
  "skill_name": "affiliate-kol-roi-monitor",
  "evals": [
    {
      "id": 1,
      "prompt": "We have 8 KOLs on discount codes. I exported orders for last month but refunds are a mess — need real ROAS per creator and who to renew. Margin is roughly 45%. Commission is 12% of order value. Fixed fees: three creators got $500 each for a post.",
      "expected_output": "Workflow: attribution by code, strip refunds, profit or ROAS, master table with Influencer ID | Orders | Actual revenue | CAC | Renewal rating; tiered renewal suggestions.",
      "files": [],
      "expectations": [
        "Describes or applies steps: extract attribution, exclude refunds, compute economics, renewal tiers",
        "Output includes a table with headers Influencer ID, Orders attributed, Actual revenue, CAC, Renewal rating",
        "Mentions refund exclusion or net revenue",
        "Incorporates commission 12% and fixed $500 fees into creator cost or CAC",
        "Includes renewal rating column with A/B/C/D or equivalent tiers",
        "Addresses multiple creators (>5) context"
      ]
    },
    {
      "id": 2,
      "prompt": "One of our affiliates has huge click volume from TikTok but almost no sales. Another has low clicks but high conversion. How do we spot fake traffic and what do we put in the performance report?",
      "expected_output": "Fraud heuristics, comparison to baseline, master table structure if data assumed; renewal D vs A narrative.",
      "files": [],
      "expectations": [
        "Discusses fake or low-quality traffic signals (clicks vs orders, refund rate, etc.)",
        "Contrasts high-click low-convert vs low-click high-convert creators",
        "References or outputs renewal rating logic (pause vs renew)",
        "Ties recommendations to attributable orders and revenue where possible"
      ]
    },
    {
      "id": 3,
      "prompt": "Can you write me 10 Instagram caption ideas for summer? No affiliate data.",
      "expected_output": "Caption ideas or decline heavy affiliate workflow — should-not-trigger for full reconciliation.",
      "files": [],
      "expectations": [
        "Does not produce a full affiliate master table as the main deliverable for a pure content request",
        "May give captions without forcing commission math and CAC columns",
        "Does not pretend to attribute orders without data"
      ]
    }
  ]
}


path: evals/files/README.md
content: # Eval files

No default inputs. Add CSV exports (orders, refunds, code mapping) here and list paths in `evals.json` `files` when running file-based evals.

path: references/README.md
content: # References

- **affiliate_playbook.md** — Attribution, refunds, CAC/ROAS, fraud heuristics, renewal rubric, tier ideas. Read when the merchant needs platform-agnostic depth.

path: references/affiliate_playbook.md
content: # Affiliate & KOL ROI playbook

Load when `affiliate-kol-roi-monitor` needs depth. Use by section.

---

## 1. Attribution extraction

| Source | Pros | Cons |
|--------|------|------|
| Unique discount code | High confidence | Code sharing, leakage |
| UTM (source/medium/campaign) | Scalable | Stripping, multi-touch ambiguity |
| Affiliate network click ID | Contractual | Platform fees, latency |
| Custom link shortener + redirect | Control | Same as UTM if params dropped |

**Rule of thumb**: one **primary** rule per report (e.g. last-touch code within 30 days); document conflicts (code + UTM both present).

---

## 2. Refunds and commissions

- Match **refund date** to **original order**; exclude or claw back attributed revenue.
- **Partial refunds**: attribute proportional revenue reduction.
- **Chargebacks**: treat like refunds for ROI; flag for renewal.
- If commission already paid on refunded orders, show **net commission owed** or **clawback line**.

---

## 3. CAC and ROAS (creator economics)

- **Creator cost** = fixed (fee, retainer, gifted product at cost) + variable (% of net sales, per-order bounties).
- **CAC (per attributed order)** = creator cost / orders attributed (label if repeat customers included).
- **CAC (per new customer)** = creator cost / new customers from creator (needs customer ID dedup).
- **ROAS (creator)** = actual revenue / creator cost (state if revenue is net of refunds).

---

## 4. Fake or low-quality traffic (heuristics)

Not proof of fraud — use for **investigation** and **D-tier renewal**.

| Signal | What to check |
|--------|----------------|
| High clicks, near-zero orders | Landing mismatch, bot traffic, incentive fraud |
| Extreme refund rate vs store avg | Misleading promo, wrong audience |
| Single geo spike with no brand fit | Purchased traffic |
| All orders same SKU / same time | Stacking or self-dealing |
| Session duration near zero, 100% bounce | Bot or junk placements |

Recommend: compare each creator’s **conversion rate**, **AOV**, **refund rate** to **store baseline**.

---

## 5. Renewal rating rubric (align to master table)

| Rating | Criteria (example) | Action |
|--------|----------------------|--------|
| A | ROAS above target, refund at or below baseline, clean traffic | Renew; optional volume bonus |
| B | Positive but thin margin or volatile | Renew with monthly cap or tiered % |
| C | Break-even or refund elevated | Short extension; stricter code; audit placement |
| D | Negative contribution or fraud signals | Pause; reconcile clawbacks; require disclosure |

---

## 6. Tiered renewal proposals (output ideas)

- **Volume tier**: e.g. 10% → 12% above $X net sales/month.
- **Cap**: max payout per month to limit risk on new creators.
- **Exclusivity window**: competitor clause in exchange for higher %.
- **Content minimums**: posts/stories per month with trackable links.


path: scripts/README.md
content: # Scripts

Optional: Python to join orders + refunds + codes. Not required for the skill; add scripts here and document in SKILL.md if you automate reconciliation.

Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)