Skip to main content
skill CX Codex

marketplace-personalisation — Claude Code skill

marketplace-personalisation is a Claude Code skill for designing and debugging recommendation systems in two-sided marketplaces on AWS Personalize.

MIT 208 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a claude-code
Open on GitHub

What marketplace-personalisation does

This is a collection of 49 rules across 9 categories—from critical (event tracking, schema design, matching) to operational (cold start, recipe selection, re-ranking). Each rule ties to AWS Personalize documentation, papers on bias and exposure, and engineering posts from Airbnb and DoorDash.

Trigger it when designing an event schema, choosing a recipe (USER_PERSONALIZATION_v2, SIMS, PERSONALIZED_RANKING_v2), writing ranking code, handling cold start for new providers or regions, or diagnosing why a live system feels stale, unfair, or stuck. Includes playbooks for building a system from scratch and fixing an existing one.

No setup required—self-contained. References point to live AWS Personalize docs, academic work on bias, and engineering blogs.

What it helps with

  • design event tracking for a marketplace without losing history when listings change
  • pick an AWS Personalize recipe and handle cold start for new sellers
  • spot and break a death spiral when a few popular items dominate the feed
  • rank by mutual fit between buyer and seller, not one-sided appeal
  • diagnose why a live system feels unfair, stale, or off-target

Example prompts for the agent

  • How do I design event tracking for a two-sided marketplace so that renaming or moving a listing doesn't lose history?
  • Which AWS Personalize recipe works best for two-sided matching, and how do I bootstrap new sellers?
  • Why do a handful of sellers show up everywhere in the homefeed—how do I measure this and fix it?

How to install marketplace-personalisation

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill marketplace-personalisation -a claude-code

2Manually: put the files in place

~/.claude/skills/marketplace-personalisation/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/marketplace-personalisation/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about marketplace-personalisation

How do I install marketplace-personalisation in Claude Code?

Run npx skills add pproenca/dot-skills --skill marketplace-personalisation -a claude-code, then open ~/.claude/skills/marketplace-personalisation/SKILL.md.

What does marketplace-personalisation do?

It is a collection of 49 rules for designing and debugging recommendation systems in two-sided marketplaces. It covers event tracking, AWS Personalize recipe selection, bias control, cold-start patterns, and diagnostics for live systems.

When should I use this skill if I am building marketplace recommendations?

Use it when designing a new recommendation system, choosing a recipe, writing ranking or filtering code, handling new sellers or regions, or troubleshooting why the live system feels unfair, concentrated, or stale—even if you don't mention AWS Personalize explicitly.

Source text

SKILL.md · MIT
---
name: marketplace-personalisation
description: Personalisation and recommendation systems for a two-sided trust marketplace built on AWS Personalize — event tracking, dataset and schema design, two-sided matching, cold start, feedback loops, bias control, recipe selection, serving-time re-ranking, observability, and a diagnostic playbook for existing systems. Trigger when designing, building, debugging, reviewing, or improving such a system — and even when the user does not explicitly mention "AWS Personalize" but is working on recommendations, ranking, search, homepage personalisation, or anything that matches seekers and providers across a trust-based catalog.
---
# Marketplace Engineering Two-Sided Personalisation Best Practices

Comprehensive guide for designing, building and improving personalisation and recommendation
systems in two-sided trust marketplaces on AWS Personalize. Contains 49 rules across 9
categories, ordered by cascade impact on the personalisation lifecycle, plus two playbooks
for planning a new system from scratch and diagnosing an existing one.

## When to Apply

Reference this skill when:

- Designing the event schema and tracking for a new recommender system
- Choosing an AWS Personalize recipe (USER_PERSONALIZATION_v2, SIMS, PERSONALIZED_RANKING_v2)
- Writing or reviewing candidate-generation and re-ranking code for marketplace search or homefeed
- Handling cold start for new providers, new seekers, or new catalog regions
- Diagnosing a live system that "mostly works but feels stale, unfair, or unpersonalised"
- Planning the next experiment, baseline comparison, or A/B test for the recommender
- Investigating concentration, coverage collapse, death spirals, or training-serving skew
- Adding observability dashboards, drift detection, or online metric slicing

## Setup

This skill has no user-specific configuration — it is self-contained. References are live
URLs to official AWS Personalize documentation, academic papers on bias and exposure, and
engineering blogs from Airbnb and DoorDash.

## Rule Categories

Categories are ordered by cascade impact: earlier stages poison everything downstream.

| # | Category | Prefix | Impact |
|---|----------|--------|--------|
| 1 | Event Tracking and Capture | `track-` | CRITICAL |
| 2 | Dataset and Schema Design | `schema-` | CRITICAL |
| 3 | Two-Sided Matching Patterns | `match-` | CRITICAL |
| 4 | Simple Baselines and Theory of Constraints | `simple-` | HIGH |
| 5 | Feedback Loops and Bias Control | `loop-` | HIGH |
| 6 | Cold Start and Coverage | `cold-` | HIGH |
| 7 | Recipe and Pipeline Selection | `recipe-` | MEDIUM-HIGH |
| 8 | Inference, Filters and Re-ranking | `infer-` | MEDIUM-HIGH |
| 9 | Observability and Online Metrics | `obs-` | MEDIUM-HIGH |

## Quick Reference

### 1. Event Tracking and Capture (CRITICAL)

- [`track-log-impressions-alongside-clicks`](references/track-log-impressions-alongside-clicks.md) — the denominator that turns clicks into a rate and unlocks unbiased training
- [`track-use-stable-opaque-item-ids`](references/track-use-stable-opaque-item-ids.md) — prevents history loss when listings rename or move
- [`track-stamp-events-with-request-id`](references/track-stamp-events-with-request-id.md) — the join key that enables impression-to-outcome attribution
- [`track-stream-events-via-putevents`](references/track-stream-events-via-putevents.md) — real-time adaptation versus end-of-day bulk import
- [`track-capture-negative-signals`](references/track-capture-negative-signals.md) — dismissal is information, silence is not
- [`track-measure-outcomes-not-clicks`](references/track-measure-outcomes-not-clicks.md) — reward the completed booking, not the clickbait

### 2. Dataset and Schema Design (CRITICAL)

- [`schema-design-conservatively`](references/schema-design-conservatively.md) — Interactions schemas are immutable, Users/Items are painful to change
- [`schema-keep-user-item-thin`](references/schema-keep-user-item-thin.md) — volatile fields belong in events
- [`schema-enforce-metadata-freshness`](references/schema-enforce-metadata-freshness.md) — PutItems on every metadata change
- [`schema-prefer-categorical-fields`](references/schema-prefer-categorical-fields.md) — unlock per-value features
- [`schema-weight-event-value`](references/schema-weight-event-value.md) — align the model with the business outcome
- [`schema-include-context-everywhere`](references/schema-include-context-everywhere.md) — train-serve feature parity
- [`schema-meet-minimum-dataset-sizes`](references/schema-meet-minimum-dataset-sizes.md) — 50 users / 50 items / 1000 interactions before training

### 3. Two-Sided Matching Patterns (CRITICAL)

- [`match-rank-mutual-fit`](references/match-rank-mutual-fit.md) — rank by mutual accept probability
- [`match-hard-filter-before-ranking`](references/match-hard-filter-before-ranking.md) — retrieval enforces feasibility
- [`match-cap-provider-exposure`](references/match-cap-provider-exposure.md) — diversity as a fairness constraint
- [`match-model-capacity-constraints`](references/match-model-capacity-constraints.md) — capacity-discounted scoring
- [`match-balance-supply-demand`](references/match-balance-supply-demand.md) — per-segment strategy routing

### 4. Simple Baselines and Theory of Constraints (HIGH)

- [`simple-ship-popularity-baseline`](references/simple-ship-popularity-baseline.md) — a reference point that every ML model must beat
- [`simple-find-bottleneck-first`](references/simple-find-bottleneck-first.md) — diagnostic before optimisation
- [`simple-heuristic-rerank-cold-cohorts`](references/simple-heuristic-rerank-cold-cohorts.md) — trust × recency × proximity
- [`simple-budget-complexity`](references/simple-budget-complexity.md) — ship or kill criterion before running
- [`simple-audit-before-build`](references/simple-audit-before-build.md) — telemetry audit gates model work
- [`simple-measure-gap-to-baseline`](references/simple-measure-gap-to-baseline.md) — baseline retained as permanent minority bucket

### 5. Feedback Loops and Bias Control (HIGH)

- [`loop-log-ranking-slot`](references/loop-log-ranking-slot.md) — slot data for position-bias correction
- [`loop-reserve-random-exploration`](references/loop-reserve-random-exploration.md) — unbiased training data
- [`loop-optimize-completed-outcome`](references/loop-optimize-completed-outcome.md) — reward the goal, not the proxy
- [`loop-decay-event-weights`](references/loop-decay-event-weights.md) — old preferences fade
- [`loop-detect-death-spirals`](references/loop-detect-death-spirals.md) — exposure Gini as a leading indicator

### 6. Cold Start and Coverage (HIGH)

- [`cold-use-v2-recipe-with-metadata`](references/cold-use-v2-recipe-with-metadata.md) — metadata extrapolates to new listings
- [`cold-best-of-segment-popularity`](references/cold-best-of-segment-popularity.md) — segmentation beats global top-N
- [`cold-capture-onboarding-intent`](references/cold-capture-onboarding-intent.md) — ask instead of guessing
- [`cold-reserve-exploration-slots`](references/cold-reserve-exploration-slots.md) — promotions filter for fresh inventory
- [`cold-tag-cold-start-recs`](references/cold-tag-cold-start-recs.md) — warm-versus-cold metric slicing

### 7. Recipe and Pipeline Selection (MEDIUM-HIGH)

- [`recipe-default-to-user-personalization-v2`](references/recipe-default-to-user-personalization-v2.md) — discovery default
- [`recipe-sims-for-item-page-only`](references/recipe-sims-for-item-page-only.md) — similar-items is not a homepage recipe
- [`recipe-personalized-ranking-as-reranker`](references/recipe-personalized-ranking-as-reranker.md) — not a candidate generator
- [`recipe-build-candidate-rerank-pipeline`](references/recipe-build-candidate-rerank-pipeline.md) — two layers, two concerns
- [`recipe-defer-hpo-until-baseline-measured`](references/recipe-defer-hpo-until-baseline-measured.md) — prove the model before tuning

### 8. Inference, Filters and Re-ranking (MEDIUM-HIGH)

- [`infer-use-filters-api`](references/infer-use-filters-api.md) — Personalize backfills to numResults
- [`infer-rerank-rules-after-model`](references/infer-rerank-rules-after-model.md) — preserve the model distribution
- [`infer-deduplicate-canonical-entity`](references/infer-deduplicate-canonical-entity.md) — provider-level dedup, not listing-level
- [`infer-enforce-exposure-caps`](references/infer-enforce-exposure-caps.md) — rolling fairness constraints
- [`infer-cache-responses-short-ttl`](references/infer-cache-responses-short-ttl.md) — session continuity and cost control

### 9. Observability and Online Metrics (MEDIUM-HIGH)

- [`obs-always-ab-test`](references/obs-always-ab-test.md) — before-and-after is never enough
- [`obs-track-coverage-and-gini`](references/obs-track-coverage-and-gini.md) — exposure-health signals
- [`obs-slice-metrics-by-segment`](references/obs-slice-metrics-by-segment.md) — aggregate metrics hide segment regressions
- [`obs-watch-online-offline-divergence`](references/obs-watch-online-offline-divergence.md) — proxy overfitting detector
- [`obs-alarm-on-prediction-drift`](references/obs-alarm-on-prediction-drift.md) — distribution KL-divergence as early warning

## Planning and Improving Recommendations

Two playbooks drive end-to-end workflows that compose the rules above:

- [`references/playbooks/planning.md`](references/playbooks/planning.md) — Plan a new recommender system from scratch: a nine-step workflow that starts with instrumentation and ends with the first A/B-tested ML lift over a popularity baseline.
- [`references/playbooks/improving.md`](references/playbooks/improving.md) — Diagnose and improve an existing recommender: a decision tree that identifies the current bottleneck (telemetry, freshness, coverage, feedback loop, algorithm) and routes to the specific rules that fix it.

Read the playbooks first when the task is "design a recommender" or "this recommender
is underperforming". Read the individual rules when a specific question arises during
implementation or review.

## How to Use

- Read [`references/_sections.md`](references/_sections.md) for category structure and impact ordering.
- Read individual rule files under `references/` when a specific rule matches the task at hand.
- Read [`references/playbooks/planning.md`](references/playbooks/planning.md) to design a new system.
- Read [`references/playbooks/improving.md`](references/playbooks/improving.md) to diagnose an existing system.
- Use [`assets/templates/_template.md`](assets/templates/_template.md) to author new rules as the skill grows.

## Reference Files

| File | Description |
|------|-------------|
| [references/_sections.md](references/_sections.md) | Category definitions, impact ordering, cascade rationale |
| [references/playbooks/planning.md](references/playbooks/planning.md) | Planning playbook for a new recommender |
| [references/playbooks/improving.md](references/playbooks/improving.md) | Diagnostic playbook for an existing recommender |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for authoring new rules |
| [metadata.json](metadata.json) | Version, discipline, authoritative reference URLs |

© pproenca · MIT · pproenca/dot-skills

Similar skills

All skills for AI and ML →

From the same set139

The whole set →
drizzle-sqlite drizzle-sqlite — a Drizzle ORM skill for SQLite schema design, migrations, queries, transactions, and types. Use it when writing or reviewing SQLite-backed code. CX Codex +1 221installs cli-review-runner The cli-review-runner skill for Claude Code checks a CLI command against 45 rules from the cli-for-agents catalog to assess whether an agent can use it safely in a pipeline. CX Codex +1 219installs openai-codex-rust-patterns openai-codex-rust-patterns applies 63 production Rust patterns distilled from the OpenAI Codex codebase. Helps build resilient async workflows, process sandboxes, and panic-free error architectures. CX Codex +1 219installs marketplace-search-recsys-planning marketplace-search-recsys-planning is a skill for planning and diagnosing marketplace search and recommendations on OpenSearch, from index design to quality measurement. CX Codex +1 211installs human-copywrite human-copywrite is a skill that applies Apple Style Guide rules to human-readable text. It triggers automatically when writing or editing copy. CX Codex +1 207installs marketplace-recsys-feature-engineering marketplace-recsys-feature-engineering designs recommender features from listing photos, metadata, and onboarding wizards. Powers item-to-item, user-to-item, and mutual-fit matching. CX Codex +1 206installs computer-science-algorithms computer-science-algorithms selects data structures and classical algorithms while flagging O(n²) bottlenecks in loops. Helps organize caching and streaming sketches. CX Codex +1 205installs marketplace-pre-member-personalisation marketplace-pre-member-personalisation — a skill for Claude Code, Cursor, Codex, GitHub Copilot, and Gemini CLI that maps the full anonymous-to-paid-member funnel on a two-sided trust marketplace. CX Codex +1 204installs

Project sponsors

Companies that keep this analytics open