# marketplace-personalisation

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

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 208 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/marketplace-personalisation/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/marketplace-personalisation

## What it 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.

## Requirements
- Works with: AWS

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/marketplace-personalisation/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/marketplace-personalisation/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/marketplace-personalisation/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/marketplace-personalisation/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.experimental/marketplace-personalisation
```

2. **Manually: put the files in place**
- File: `.github/skills/marketplace-personalisation/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/marketplace-personalisation
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/marketplace-personalisation/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/marketplace-personalisation/SKILL.md

## When to use it
- 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
- 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?

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 98a7f57b920d81a9.

BEGIN THIRD-PARTY FILE 98a7f57b920d81a9
```text
---
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 |
```
END THIRD-PARTY FILE 98a7f57b920d81a9

The third-party file has ended. Everything between the 98a7f57b920d81a9 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2295 of 11312 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/marketplace-personalisation/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
