Imported from haoyutan/learn-nihongo-from-games (AGENTS.md). Install upstream with npx skills add haoyutan/learn-nihongo-from-games. Copyright stays with the author.

AGENTS.md

Guidance for AI agents working in this repository.

What this repository is

A personal Japanese-learning corpus, not a software project. There is no build, no test suite, no lint step, and no package manager — the deliverable is Markdown prose. "Correct output" means a study file that matches the format spec exactly and faithfully reproduces the Japanese source.

Read these two files before doing anything; they are the spec, and this file does not restate them:

Each resource folder owns its own README and its own format. Do not carry a convention from one resource into another without checking that resource's README.

Layout

nihongo/
├── README.md                    # repo-wide conventions + resource index
├── AGENTS.md                    # this file
└── Doraemon-Story-of-Seasons/
    ├── README.md                # format spec for this resource
    ├── Transcript/              # hand-typed dialogue transcriptions (the inputs)
    │   ├── C01/                 # one folder per chapter
    │   │   └── C01-S02.md       # C<chapter>-S<section>.md
    │   └── C02/
    │       └── C02-S01.md
    ├── Chapter-01/
    │   ├── Section-01.md        # CANONICAL — copy this structure
    │   ├── Section-02.md
    │   └── ...                  # through Section-07.md
    └── Chapter-02/
        └── Section-01.md

Transcript/ holds the hand-typed source transcriptions, one folder per chapter and one file per section file: Transcript/C01/C01-S02.md → Chapter-01/Section-02.md, Transcript/C02/C02-S01.md → Chapter-02/Section-01.md. The filename repeats the chapter, so it stays unambiguous on its own. These are inputs, never the deliverable — but they are kept, not scratch, since they are the record of what was on screen and get corrected alongside the section files. An empty transcript file means that section has not been transcribed yet.

Transcripts live inside the resource folder, because they are specific to that resource. A new resource gets its own Transcript/.

Which file to imitate

Always Chapter-01/Section-01.md. It is named as canonical by the resource README and is the only file demonstrating every required element.

Generating a section file from a transcript

1. Read both READMEs and Chapter-01/Section-01.md in full first.
2. Every source line becomes exactly one dialogue row. Do not merge, split, reorder, or drop lines — including bare ・・・。 silence lines, which are meaningful beats.
3. Set the # chapter title (identical for every file in the chapter) and the ## Section NN: Title heading beneath it.
4. Write ## 📜 Original Content (jump links + Japanese-only tables) and the per-scene ### Dialogue tables from the same source, then verify they match mechanically (below).
5. Fill all five ##### subsections per scene, in the fixed order, separated by ---.
6. Update the Progress table at the bottom of the resource README in the same change.
7. Report every suspected transcription typo to the user in the final response, as an explicit list with the evidence for each — not buried in the file alone.

Verify before claiming completion

The Original Content block duplicates every Japanese line, so drift is the most likely defect and is invisible on a quick read. Check it, don't eyeball it:

python3 - <<'EOF'
import re
f='Doraemon-Story-of-Seasons/Chapter-01/Section-02.md'   # target file
lines=open(f,encoding='utf-8').read().split('\n')
i=[n for n,l in enumerate(lines) if l.startswith('### Scene ')][0]

def rows(ls):
    out=[]
    for l in ls:
        if l.startswith('|') and not re.match(r'^\|[\s\-|]+\|$',l) and not l.startswith('| Speaker'):
            c=[x.strip() for x in l.strip('|').split('|')]
            out.append((c[0],c[1]))
    return out

oc=rows(lines[:i])
dlg,inD=[],False
for l in lines[i:]:
    if l.startswith('#### Dialogue'): inD=True; continue
    if l.startswith('#### Learning'): inD=False
    if inD and l.startswith('|'): dlg+=rows([l])

print(f'{len(oc)} vs {len(dlg)}')
for n,(a,b) in enumerate(zip(oc,dlg)):
    if a!=b: print('MISMATCH',n,a,'||',b)
EOF

Counts must be equal with no mismatches. Also confirm the heading list (grep -n '^#\{1,5\} ') matches Chapter-01/Section-01.md's shape — one #, one ##, then ### per scene (+1 for Original Content), #### ×2 per scene, ##### ×5 per scene.

Rules that are easy to get wrong

The Transcript/ files are hand-typed by the user while reading the text on screen. They are not a data dump, so they are the best available source and they can contain transcription typos. This cuts both ways:

• Never silently correct the Japanese. The section file must stay faithful to the transcript.
• Never silently preserve something that looks wrong either, and never rationalize it as a quirk of the game script. That produces confident learning notes explaining a form the game never used, which is worse than either alternative.
• Reproduce it verbatim, flag it, and ask. Put the line in the dialogue tables as typed, add a suspected transcription typo bullet in Context and nuance giving the likely intended reading plus the evidence, teach the intended form in the study notes, and raise it with the user. Once confirmed, fix the transcript and the section file together.

Useful evidence when judging — all four of these were real, confirmed cases in Sections 02–03, already corrected in both the transcript and the section files:

A near-miss single kana is the common shape (ど/で, あ/お, デ/テ), which is what typing from a screen produces.

Do not flag these — they are real features of the script, not errors: kana/kanji variation of one word (巻き込む / 巻きこむ), rough-speech phonology (ねえ, うるせえ, わかんねー, ～ちまう), casual particle dropping, and deliberate gibberish (the untranslated エラッ！？イフカティミク！？ lines before the ほんやくコンニャク).

Speaker labels are normalized; dialogue is not. The Speaker column uses standard in-game names (ドラえもん, のび太, しずか, ジャイアン, スネ夫), even when the transcript types a name in hiragana. Note the normalization in Context and nuance. Text inside the Japanese column keeps whatever the game said (のび太くん, どらえもんったら).

Scene headings carry no emoji. Only ### 📜 Original Content has one. Emoji in ### Scene NN breaks the [Scene NN](#scene-nn) anchors in editor previews. Anchors derive from heading text, not level, so ### Scene 01 is still #scene-01.

Blank line before every table, and a blank line closing any deep dive before the next ---. Without it, previews render the table as raw text.

JLPT column: N5–N1, or — plus a short tag for anything off the scale (— (school term), — (common spoken), — (rough spoken), — (series term)).

Writing the learning notes

Explanations are in English; do not mix languages in the default file. A -zh file is a separate deliverable, only when asked.

Aim at the density of Chapter-01/Section-01.md — it is the quality bar, not just the structural one. Concretely: vocabulary tables cover essentially every content word; grammar tables are complete for the scene before any deep dive; a deep dive is warranted when one pattern needs more than a table row (～ておく in Section-01 Scene 02; the adversity passive in Section-02); 4–5 study tips per scene.

Cross-link scenes explicitly. Callbacks are the main pedagogical payload — あと１０分 recurring across sections, ～ないと in one scene versus another, a grammar point tracked from its first appearance. Link with [Section-01](./Section-01.md) within a chapter, [Section-07](../Chapter-01/Section-07.md) across chapters, or in-file [Scene 01](#scene-01).

Character speech register matters and is worth its own table when a new speaker appears: Gian's -ai/-oi → -ee (ねえ, うるせえ) and ～ちまう/～ぜ; Shizuka's かしら/～ね; Suneo's stuttering. Explain them as register, not as errors.