Retro Game Gather

View saved version →

---
name: collect-games
description: Manage what the user wants and owns in Retro Game Gather (RGG) — the wishlist and the library. Use when the user wants a game, bought a game, asks whether they already own something, plans a shopping trip, updates purchase details, registers a list of owned games, or has more than one copy of a game. Japanese triggers include 欲しい, ウィッシュリストに追加, 買った, 手に入れた, 持ってたっけ, 買い物リスト, 中古屋に行く, 購入金額, 2本目, 手放した.
---

# Wishlist and library

The app's flow is: add wanted games to the wishlist, then move them to the library when bought. A game is in one or the other, never both.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`. For more than one copy of a game, read `references/physical-copies.md`.

## Add a wanted game

1. Identify the game (see the find-games skill). Make sure the platform is the one the user wants.
2. addToWishlist with only what the user said: priority, planned date, target price, store. Do not ask for optional fields the user did not mention.
3. Map words to priority only when the user states it clearly (for example 絶対欲しい → 5). Otherwise leave it unset.
4. If the game is already owned, the tool refuses. Tell the user they already have it.

## Record a purchase

1. Identify the game.
2. addToLibrary with the purchase details the user gave (date, price in yen, store, rating, memo). If the game was on the wishlist it moves automatically and keeps the wishlist's date, price, place and memo unless you pass new values. Pass the actual purchase values when the user states them.
3. Condition words (箱説付き, ソフトのみ) are attributes. Match them to the user's labels from listAttributes (type library); do not invent labels.
4. Report what was saved, including when it moved from the wishlist.

## Register many owned games

For a list, spreadsheet or long message:

1. Call getAccount and check the remaining library capacity and today's usage.
2. Identify the titles with searchGamesBatch (up to 20 rows per call).
3. Show the resolved list. Ask only about rows that are ambiguous or not found.
4. Preview with addToLibraryBatch `dryRun: true`, then save after the user agrees.

## Check before buying

- "Do I own X?": search the library (getLibrary `title`) and the wishlist. Remember that ports on other platforms are different games.
- Shopping trip: getWishlist sorted by priority, without the overdue filter, so games with no planned date are included. `wishDateOverdue` is a filter, not a sort: to show overdue games first, fetch `"overdue"` and `"not_overdue"` (which includes games with no planned date) separately and list the overdue ones first. Use `"overdue"` alone only when the user asks for overdue games. If you shorten the list, say what you left out. Include target price and store, and keep it short enough to read in a shop.

## Corrections and removal

- Purchase details: updateLibraryEntry. Omitted fields stay as they are.
- "I sold it" can mean one copy or the game. If the user has several copies, see `references/physical-copies.md`. removeFromLibrary also deletes the game's play records, play logs and copies. Say so and wait for a clear yes before confirming.

Referenced files: 3 — file references are metadata, not package contents.

View saved version →

---
name: find-games
description: Identify Japanese retro games in Retro Game Gather (RGG) and introduce them with cited sources. Use when the user asks what a game is, wants a game looked up by title, nickname, JAN barcode or model number, asks which platforms a game came out on, or wants games found by platform, genre or release period. Japanese triggers include ゲームを調べて, どんなゲーム, 紹介して, 探して, 型番, バーコード, 何機種で出た, ファミコンのRPG.
---

# Find and introduce games

RGG's value here is exact identification of games released in Japan, plus curated links to sources about each game. RGG does not store introductions or reviews. You write those from the sources you actually read.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`.

## Identify the game

1. Pick the identifier the user gave: title or nickname → `query`; barcode number → `janCode`; package or disc code → `modelNumber`.
2. If the user named a platform ("SFC版", "PS版"), resolve it with listPlatforms and set `platformIds`.
3. Read the candidates. Numbered sequels, ports, remakes and compilations often match together. Choose from title, platform and release date. Ask only when the choice changes the answer, and ask with the short list, not an open question.
4. A match on `alias` is a reading or nickname, not the official title. Say which game you took it to be.
5. A match with `edition: true` came from a バージョン違い (e.g. a budget re-release). The result is the parent game. RGG does not know which edition the user owns unless they record it as a physical copy (PREMIUM).
6. If nothing matches, retry with a short hiragana reading or a common abbreviation before saying the game is not covered. Coverage is Japan-released retro games only; do not invent titles or data.

Always quote official titles exactly as RGG returns them.

## Introduce a game

1. Get `externalLinks` (included in getGameDetail by default).
2. Choose sources for the question: fan wikis for story, systems and trivia; Wikipedia for an overview; the Media Arts Database (メディア芸術データベース) and Game Preservation Society (ゲーム保存協会) for bibliographic facts; IGDB for international information; PULSE (a Japanese game-tracking service) for how players rate the game.
3. Open the URLs with your browsing tool and read the section for the right platform version. Use URLs as returned; never build them from the title.
4. Write the introduction from what you read and cite the pages. Keep RGG's registered facts (release date, publisher, platform, model number, price) separate from what the sources say.
5. Avoid ending spoilers unless the user asks.
6. If you cannot open a source, say so. Do not present unread content as sourced.

## Explore by conditions

- "RPGs on the Famicom", "games released in 1994": browseGames with `platformIds`, `genreId` (from listGenres), and release dates. This needs PREMIUM.
- Without PREMIUM, searchGames still needs a title or identifier. Suggest narrowing by a series name, or point to platform and genre browsing in the app: https://docs.retrogather.com/guides/search-games/
- For genres such as "action RPG", pass the single genreId from listGenres. Do not combine a main and a sub genre yourself.

## Next steps to offer

After identifying a game, offer the natural next action once: add it to the wishlist, or to the library if they own it (see the collect-games skill). Do not add anything without the user asking.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: log-play
description: Record what the user played in Retro Game Gather (RGG) — play sessions, starting a game, clearing it, pausing or giving up, and replays. Use when the user reports playing a retro game, finishing it, stopping, or wants to start over. Japanese triggers include 遊んだ, やった, 何時間プレイ, 始めた, クリアした, エンディング, 積んだ, 諦めた, 中断, もう一周, プレイログ, プレイ記録.
---

# Record play

In the app, a game moves through play statuses and collects play logs: プレイ予定 (PLANNED) → プレイ中 (PLAYING) → クリア済 (COMPLETED), with 一時停止 (PAUSED) and 途中断念 (DROPPED) on the side. Each session is a play log. Only games in the library can have a play record.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`.

## Before writing

1. Identify the game and find its current record with getPlayRecords (`title`). The record shows the status and `playId`.
2. If the game is not in the library, ask whether the user owns it. Add it (collect-games skill) only if they say yes. Some people play borrowed or downloaded versions and do not want them in their library.
3. If there is no play record yet, create one with addPlayRecord. Use `status: "PLAYING"` when they are playing now. A new PLAYING record starts today; for play that began earlier, see "Past dates" below.

## Log a session

- addPlayLog with `gameId` (or `playId`), `playTime` in minutes, and `memo`.
- Convert time exactly: 2時間半 = 150, 45分 = 45. If the user gave no duration, ask. Do not estimate.
- The memo is required and should be what the user played or felt, in their words. If they only said "played for an hour", ask one short question ("何をしましたか？") or offer a one-line memo drawn from their message for approval. Do not invent progress.
- `playDate` defaults to today in Japan time. Convert "昨日" and similar yourself.
- The log does not change the status. If the record is still PLANNED, move it to PLAYING with updatePlayRecord and mention it.

## Clear a game

The app's clear log (クリアログ) is a play log plus the status change and a rating. Through the tools it takes two steps:

1. addPlayLog with the final session's minutes and the user's impressions.
2. updatePlayRecord with `status: "COMPLETED"` and `rating` (1–5) if the user gave one. The end date defaults to today. If they cleared on another day, set `playEndDate` (see "Past dates").

Ask for a rating once if they did not give one. Leave it empty if they prefer.

## Past dates

The start date must be on or before the end date, and it is checked after each update. When the user reports play that happened before today:

- Put the day on the log (`playDate`) and, for a clear, on `playEndDate`.
- Send the start date in the same updatePlayRecord call as the status and end date (`playStartDate`, `playEndDate`, `status` together). A record created today as PLAYING starts today, so a separate end-date update for yesterday would be rejected.
- For a new game played and cleared on one past day ("昨日初めて遊んでクリアした"), create the record with addPlayRecord (default PLANNED, which has no start date), add the log, then set status, start and end dates in one updatePlayRecord call.
- If you do not know when the user started, ask. Do not change an existing start date by guesswork.
- If the log was saved but the status update failed, do not add the log again. Fix the dates and retry only the update.

## Pause, give up, start again

- Pause or stop: updatePlayRecord `status: "PAUSED"` or `"DROPPED"`. If the user's words could mean either (積んだ, 止めた), ask which.
- Replay (もう一周): addPlayRecord `replay: true`. On PREMIUM the old cycle stays in the history. On FREE and LIGHT the previous record and its logs are replaced. Tell the user that before confirming.
- Hardware: if the user names the console they played on, set `consoleId` from getConsoles (LIGHT and above).

## After writing

Confirm in one or two lines: the game, what changed, and the new total play time if returned. Do not repeat the same write because a list looks stale; the write response is the result.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: organize-collection
description: Organize a Retro Game Gather (RGG) collection with tags, collection goals, owned consoles and maintenance logs, and custom entries for games the database lacks. Use when the user wants to group games, set a goal such as completing a series or a platform, register their hardware or its repairs, or add a game or platform RGG does not cover. Japanese triggers include タグ付け, 分類, コンプリート, シリーズを集める, コレクション, 達成率, ゲーム機を登録, 本体, メンテナンス, 修理, 電池交換, 登録されていないゲーム, 同人, 海外版.
---

# Organize the collection

These features depend on the plan: tags and consoles need LIGHT or above; collections and custom data need PREMIUM. If a tool is missing, tell the user once which plan it needs and continue with what is available.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`.

## Tags

- Create with addTag. A name is enough; the server picks an unused colour. Do not ask the user to choose a colour.
- Add or remove games with updateTagGames `mode: "add"` or `"remove"`. Use `"replace"` only when the user wants the whole set redefined; it needs the tag's current revision.
- Tags hold the user's own groups. Official tags are managed in the app.

## Collection goals (マイコレクション)

Help the user turn a goal into a collection:

1. **Purpose**: collect the games (`purposeType: "LIBRARY"`) or clear them (`"PLAY"`).
2. **Scope**: listed games (`INDIVIDUAL`), everything in a tag (`TAG`), or a whole platform (`PLATFORM`). A series usually fits a tag or a list; "every Virtual Boy game" fits a platform.
3. Confirm the name and scope, then addCollection.
4. Progress: getCollectionGames. `summary` has the totals; `achieved: false` lists what is not achieved yet.
5. "Not achieved" is not the same as "not owned". Check each game's library status before suggesting anything:
   - Not in the library (usually a LIBRARY goal): offer to add it to the wishlist (collect-games skill), a few at a time and only with the user's OK.
   - Owned but not cleared (a PLAY goal): suggest adding it to the planned list or starting it (log-play and plan-next-game skills). Never send owned games to the wishlist; the tool refuses them anyway.
   - Owned but not meeting the collection's required attributes: explain the condition. Do not change attributes just to make the goal count as achieved.

## Consoles and maintenance

- A console is the user's hardware (e.g. "初代スーファミ 1号機"), not a database platform. addConsole with a name the user will recognize; link platforms it plays with `platformPriorities`.
- Repairs and upkeep: addConsoleMaintenanceLog. Past work uses `status: "DONE"` and `completedDate`; planned work uses `"SCHEDULED"` and `scheduledDate`.
- Removing a console also removes its maintenance logs.

## Games RGG does not cover (custom data)

1. Search first: searchGames by title, then by hiragana reading or abbreviation. Only continue if it is really missing.
2. Explain that custom entries are the user's own data, not part of RGG's database.
3. Resolve the platform and publisher: public ones via listPlatforms / listCompanies, or create custom ones first (addCustomPlatform / addCustomCompany).
4. addCustomGame needs the publisher, main genre and release date as well as the title and platform. These do not need to be exact: users often want to register a game from just its title and platform, and every value can be corrected later with updateCustomGame. Also add the hiragana reading (`titleKana`) so the game can be found by the hiragana search in step 1. Genre accepts main genres only.
5. If you filled in values the user did not give, tell them which ones.
6. A custom game is not owned automatically. Offer to add it to the library or wishlist.

App reference: https://docs.retrogather.com/guides/manage-collection/ , https://docs.retrogather.com/guides/manage-console/ , https://docs.retrogather.com/features/game-data-management/

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: plan-next-game
description: Help the user choose what to play next from their Retro Game Gather (RGG) backlog. Use when the user asks what to play, wants to clear their backlog, has limited time tonight, or asks about games they planned to finish. Japanese triggers include 積みゲー, 次に何を遊ぶ, 何やろう, 今夜遊べる, 崩す, プレイ予定, クリア目標.
---

# Choose the next game

RGG stores the backlog; you make the suggestion. Base it on the user's data and say what it is based on.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`.

## Where the backlog is

1. **Planned games first.** getPlayRecords `statuses: ["PLANNED"]`. Users add games they intend to play here; it is the app's backlog.
2. **Paused games** (`"PAUSED"`) are candidates for "something to resume".
3. **Overdue goals.** `clearTargetOverdue: "overdue"` finds unfinished games past their clear target date.
4. **The wider library** only when the above is empty or the user asks. First ask for a condition (platform, genre, era), then getLibrary with that filter and `fields` including `latestPlay`. Do not page through the whole library as a first step.

## Reading the data correctly

- PLANNED means "intends to play", not "never played". Check `hasHistory` and start dates.
- A library game without a play record is "not recorded", not proof it was never played.
- Present results as candidates from the user's records (登録情報上の候補).
- If fewer candidates match than the user asked for, show the ones that match. Do not add games they do not own.

## Making the suggestion

- Ask one question if it helps: time available, mood, platform at hand.
- Game length and style: use what you know or read from the game's `externalLinks` (see the find-games skill). Say when it is your estimate.
- Keep the list short (three to five) with one line of reasoning each.

## Next steps to offer

- Start the chosen game, depending on its latest record (see the log-play skill):
  - PLANNED or PAUSED: updatePlayRecord to PLAYING.
  - No play record: addPlayRecord with `status: "PLAYING"`.
  - COMPLETED, or DROPPED and the user wants to start over: this is a replay. Use addPlayRecord with `replay: true`, never updatePlayRecord — changing a finished record to PLAYING erases its end date and rating. On FREE and LIGHT a replay replaces the previous record and its logs; say so first.
  - DROPPED and it is unclear whether the user wants to continue or start over: ask.
- Set a goal: updatePlayRecord `clearTargetDate`.
- Add a wanted game to the planned list: addPlayRecord (status defaults to PLANNED) for games already in the library.

Referenced files: 2 — file references are metadata, not package contents.

View saved version →

---
name: review-activity
description: Summarize the user's retro gaming activity from Retro Game Gather (RGG) — purchases, spending, play time, clears, and collection progress over a period. Use for monthly or yearly recaps, "how much did I spend", "what did I play", trends by platform or genre, and collection goals. Japanese triggers include 振り返り, 今月, 今年, まとめて, いくら使った, 購入金額, プレイ時間, クリアした本数, 傾向, 達成率.
---

# Look back on activity

RGG computes the numbers; you write the story. Never recount totals yourself from paged lists when an analytics tool gives them.

For RGG concepts see `references/service-guide.md`; for Japanese terms see `references/glossary-ja.md`.

## Pick the source

| Question                                         | Tool                                                                                                                             |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| Purchases, spending, counts by platform or genre | getLibraryAnalytics with `sections` (`summary`, `purchase`, `platform`, `genre`, `rating`) and `buyDateFrom` / `buyDateTo`       |
| Clears, drops, statuses, play time over time     | getPlayAnalytics with `sections` (`summary`, `monthlyResults`, `status`, `playTimeTrend`, `platform`, `genre`, `completionPace`) |
| What happened in a month, day by day             | getCalendarEvents `month: "YYYY-MM"`                                                                                             |
| What the user wrote about a game                 | getPlayLogs `playId` with `fields: ["memo"]`                                                                                     |
| Collection progress (PREMIUM)                    | getCollections, then getCollectionGames `summary`                                                                                |

Request only the sections you need.

## Read the numbers correctly

- Spending from getLibraryAnalytics counts one row per game at its active copy's price. If the user has several copies of a game (PREMIUM), the app's per-copy total can be higher. Say so when reporting spending.
- Play time and clears are different measures. `monthlyResults` gives clears and drops per month; it has no minutes. Minutes played come from `playTimeTrend` (from play logs).
- `playTimeTrend` covers at most 90 days per call; `playTimeTrendGranularity: "month"` changes the grouping, not that limit. For a longer period, split it into ranges of 90 days or less that do not overlap, keep the other filters the same, and add up the minutes RGG returns. If that needs many calls, agree on the period with the user first.
- With `playTimeTrendGranularity` `week` or `month`, each point has `from` / `to` (YYYY-MM-DD, JST, inclusive): the first and last days counted in that point. Weeks are ISO weeks starting on Monday, and `period` stays `YYYY-Www`. The first and last points are cut to `playTimeTrendFrom` / `playTimeTrendTo` (a range starting on a Thursday gives a first week that starts on that Thursday), and `minutes` covers only `from`–`to`. Quote these dates instead of working them out from `period`. `day` points have no `from` / `to`, since `period` is the date.
- By default the analytics use each game's latest record. On PREMIUM, set `includeHistory: true` to include earlier cycles (for example a game cleared this year and now being replayed). If you use latest records only, say so in the answer.
- Report play time in the unit returned (minutes), converting to hours only for display.
- State the period and filters you used ("2026年1月1日〜9月30日、全プラットフォーム").
- Dates are Japan time.

## Writing the recap

- Lead with two or three facts that stand out, then the details.
- Quote game titles exactly as RGG returns them.
- Use the user's own memos for colour, and do not invent experiences they did not record.
- Keep numbers from RGG separate from your interpretation.

Referenced files: 2 — file references are metadata, not package contents.