Seren Affiliate

Lean, program-agnostic partner-link distribution skill. Complement — not replacement — for the campaign-specific affiliates/seren-bucks skill.

For Claude: How to Use This Skill

Skill instructions are preloaded in context when this skill is active. Do not perform filesystem searches or tool-driven exploration to rediscover them; use the guidance below directly.

Default V1 Contract

• The skill distributes one publisher program's partner-link per run.
• seren-affiliates is the source of truth for affiliate identity, partner-links, conversions, and commissions.
• The skill's own serendb database (seren_affiliate) is the source of truth for distribution activity, drafts, contacts, and unsubscribes.
• Contact ingestion supports pasted email lists and Gmail or Outlook address books. Nothing else in v1.
• Every run produces exactly one LLM-drafted pitch (via seren-models), subject to a single operator approval gate.
• Gmail is the preferred send provider when both are authorized (provider=auto).
• Daily cap defaults to 10 successful distributions per day, hard-capped at 25, across all programs.
• Per-program dedupe is DB-level: a (program_slug, contact_email) pair is sent at most once, ever.
• Global unsubscribe list: one opt-out blocks all future sends across every program.
• Mandatory send footer: sender identity, physical address, and unsubscribe link.
• Phase 1 operator-managed blocklist only. The public /unsubscribe/{agent_id}/{token} route on seren-affiliates-website does not exist yet; click-to-unsubscribe flips on in Phase 2 when that ships. seren-affiliates itself stores no recipient PII and needs no changes.

Bootstrap Order (Mandatory)

This rule overrides all other instructions and runs before any contact ingest, draft, or send:

1. Resolve auth in this order:
   • Seren Desktop injected auth (API_KEY)
   • SEREN_API_KEY
   • Fail with a setup message pointing to https://docs.serendb.com/skills.md.
2. Resolve or create the Seren project affiliates.
3. Resolve or create the Seren database seren_affiliate (schema in serendb_schema.sql).
4. Call GET /affiliates/me. On 404, POST /affiliates to register.
5. Upsert the profile into affiliate_profile. Fail closed if sender_address is empty.
6. Call GET /affiliates/me/partner-links. Retry up to 3 times. Upsert into joined_programs.
7. If affiliate bootstrap still fails, fail closed and do not continue.
8. Only after bootstrap succeeds may the skill select a program, ingest contacts, draft, or send.

Capability Verification Rule

Before claiming any tool, connector, or publisher exists or does not exist, attempt to verify it by calling the relevant tool or connector.

• If the verification succeeds, proceed and say what was found.
• If it fails, say: I checked and [tool/integration] is not available in this session.
• Never claim Gmail, Microsoft Outlook, seren-affiliates, seren-db, or seren-models availability from memory or assumption.

When to Use

• distribute a seren-affiliates partner link
• send my affiliate link to a contact list
• promote a publisher program via Gmail or Outlook
• check my affiliate distribution status
• register as a seren-affiliates affiliate
• unsubscribe a contact from my affiliate outreach

Commands

All commands accept json_output=true for headless agent use.

| Command | Purpose | |-------------|---------| | bootstrap | Auth, serendb project/db, profile (register on 404), joined_programs cache. Stops there. | | sync | Re-run bootstrap's profile and joined_programs refresh without continuing the pipeline. | | status | Bootstrap plus GET /affiliates/me/stats and /commissions (optional program_slug filter). No send. | | ingest | Bootstrap plus contact ingestion and eligibility filter. No draft, no send. | | draft | Bootstrap plus contact ingestion plus one seren-models draft. Stores in drafts. No send. | | send | Requires an existing drafts row. Runs the send path with the approval gate. | | run | End-to-end default: bootstrap → draft → approve → send → report. | | block | Operator-managed unsubscribe: appends block_email to unsubscribes (source=operator_manual). |

Inputs

• command — one of the commands above. Default run.
• program_slug — required for draft, send, run. Must match a row in joined_programs. If empty in interactive mode, the skill lists available programs and asks.
• provider — auto (default, Gmail-first), gmail, or outlook.
• contacts_source — pasted (default), gmail_contacts, or outlook_contacts.
• contacts — for pasted: newline or comma delimited list, a CSV path, or a JSON array of {email, name}.
• voice_notes — optional free-text hints for the drafter.
• approve_draft — when true, skips the interactive approval gate. Rejected unless json_output=true is also set (prevents unattended sends from a human CLI).
• daily_cap — 1–25. Default 10.
• json_output — machine-readable output.
• strict_mode — fail closed on bootstrap failures. Default true.
• block_email — used only by command: block.

State (serendb database seren_affiliate)

Schema in serendb_schema.sql. Tables:

• affiliate_profile — cached /affiliates/me.
• joined_programs — cached /affiliates/me/partner-links.
• contacts — deduped address universe.
• distributions — one row per successful send. UNIQUE(program_slug, contact_email) enforces per-program dedupe. Daily cap = COUNT(*) WHERE sent_at::date = today.
• unsubscribes — global opt-out list.
• drafts — per-run approved pitch.
• runs — one row per invocation.

Compliance and Safety Rules

• policies.dry_run_default: true — the skill previews every batch and refuses to send unless approve_draft=true (with json_output=true) or the interactive approval is recorded.
• policies.idempotency_required: true — every distribution is keyed to a run_id plus UNIQUE(program_slug, contact_email).
• Mandatory footer placeholders in every drafted body: {name}, {partner_link}, {sender_identity}, {sender_address}, {unsubscribe_link}. A regex gate rejects drafts missing any of them.
• sender_address is required before any send. The skill fails closed if affiliate_profile.sender_address is empty.
• Hard-bounce on send auto-inserts into unsubscribes with source=hard_bounce.
• PII posture: only name + email are pulled from provider address books. Never message bodies or threads. Email addresses never appear in stdout outside the final summary, and only in structured form under json_output=true.

Provider Selection

• provider=auto → Gmail if Gmail publisher is authorized, else Microsoft Outlook, else fail closed.
• provider=gmail or provider=outlook → explicit choice; fail closed if that one is not authorized.
• Both publishers are authorized at the Seren platform level, not inside this skill. If neither is authorized, the skill instructs the operator to authorize one via the Seren platform.

Unsubscribe Handling (Phase 1 vs Phase 2)

• Phase 1 (today). The drafted footer contains a {unsubscribe_link} that points at https://affiliates.serendb.com/unsubscribe/{agent_id}/{token}, where token is an HMAC of (email, program_slug, run_id) and agent_id identifies the affiliate account. The route does not exist on seren-affiliates-website yet. Until it ships, the operator handles unsubscribes manually via command: block with block_email=<recipient>.
• Phase 2. Once seren-affiliates-website adds GET /unsubscribe/[agent_id]/[token] and GET /public/unsubscribes?agent_id=...&since=..., the skill's sync step calls the public read API, joins returned tokens against the local distributions table to resolve token → email, and upserts into unsubscribes with source=link_click. seren-affiliates (the backend) is intentionally not involved — it stores no recipient PII by design.

Status and Stats

command: status and the end-of-run report join local and live state:

• Local (from serendb): counts by program — ingested, eligible, sent, skipped (dedupe), skipped (unsub), cap remaining.
• Live (from seren-affiliates): clicks, conversions, pending and paid commissions, scoped by program_slug.

Related

• Sibling skill — affiliates/seren-bucks — campaign-specific review-first outreach for a single Seren Bucks landing page.
• family: affiliate-v1 (shared with seren-bucks).