# stream-feeds-migration

`/stream-feeds-migration` produces the `mapping` object for an Activity Feeds **v2 → v3** sync configuration by looking at what your v2 app's data actually contains, rather than at what your schema is believed to contain. The same mapping drives both migration paths (the live syncer and the bulk exporter), so getting it right once fixes both.

<Admonition type="note">

This is not a build pack. It emits a **configuration object**, it does not scaffold or modify an app. It needs your **v2 app's** API key and secret and is read-only against that app. Once the mapping is settled, hand off to your platform pack (`/stream-react`, `/stream-swift`, `/stream-android`, `/stream-react-native`, `/stream-flutter`) to build against v3, and to [`/stream-docs`](https://getstream.io/agent-skills/docs/skills/stream-docs/) for v3 Feeds API questions.

</Admonition>

## What it produces

The `mapping` object, ready to paste into your app's sync configuration, with every key justified by evidence in your data:

- **Activity field mapping**: id sources (`id`, `foreign_id`), field renames, reshare/reply parents, activity attachments, and where the `extra_context` bag should land.
- **Reaction classification**: each reaction kind sorted into a v3 comment, bookmark, comment bookmark, or plain reaction, plus comment text, reply, and attachment paths.
- **The keys it deliberately left out**: with the default that already covers your app's shape, so an absent key reads as a decision rather than an oversight. An empty mapping (`{}`) is a valid, correct answer for an app that already matches v3 conventions.

It also states plainly what a sample **cannot** prove (user fields are never sampled, only recent activities are seen, rare shapes hide in the tail), so you know what still needs confirming.

## Example prompts

```bash
/stream-feeds-migration what mapping do we need for our app?
/stream-feeds-migration build the v2 to v3 sync mapping for my feeds app
/stream-feeds-migration a migrated activity landed in v3 with no text, review our mapping
/stream-feeds-migration our comments came through as plain reactions, what's wrong with the mapping?
```

## How it works

1. **Credentials into the environment.** You export the v2 app's key and secret yourself (`! export STREAM_API_KEY=… STREAM_API_SECRET=…`) so the secret never enters the conversation. The skill never reads a `.env` file.
2. **Sample the live v2 app.** The skill ships a small sampling script (Python, standard library only, the only executable file in the whole pack) that calls the read-only migration sample endpoints to pull the most recent activities and a spread of reactions, returning the **raw** stored payloads so the real field names and nesting are visible. It writes one local JSON file and nothing else.
3. **Analyze and emit.** It works through activities, reactions, and users against the full key catalogue, then returns the `mapping` object with each key explained and the sample's limits called out.

<Admonition type="tip">

The generated mapping plugs directly into the Dashboard migration flow. For the full end-to-end migration (the Dashboard modal, the three migration phases, and a reference for every mapping key with before/after examples), see the [**Feeds v2 → v3 migration guide**](https://getstream.io/activity-feeds/docs/node/v2-to-v3-migration/). That guide also documents the sample endpoints if you want to validate a mapping by hand.

</Admonition>


---

This page was last updated at 2026-08-22T17:29:30.352Z.

For the most recent version of this documentation, visit [https://getstream.io/agent-skills/docs/skills/stream-feeds-migration/](https://getstream.io/agent-skills/docs/skills/stream-feeds-migration/).