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
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/marketplace-personalisation/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/marketplace-personalisation/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a codex2Manually: put the files in place
.agents/skills/marketplace-personalisation/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a cursor2Manually: put the files in place
.cursor/skills/marketplace-personalisation/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.experimental/marketplace-personalisation2Manually: put the files in place
.github/skills/marketplace-personalisation/SKILL.md1Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a gemini-cli2Platform CLI
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/marketplace-personalisationManually: put the files in place
.devin/skills/marketplace-personalisation/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill marketplace-personalisation -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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