Index of every page on this site: llms.txt
All skills
Run it yourself

Builds visual novels and choice-driven stories in Ren'Py or any engine: routes and endings, save-anywhere, backlog, skip-read-only and typewriter text. Use for a VN or dating sim, or loads at the wrong line, skip running through unread text or an unreachable ending. Not for dialogue in a larger game or Ink and Yarn (`dialogue-systems`) or text box widgets (`godot-ui-control`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/visual-novel

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈98 tokens for metadata: the name and description. ≈1.8k when used: this file. ≈1.4k more on demand in 1 file.

Description uses 4.9% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈394 characters, or 4.9%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Visual novel

Owns the shape of a branching story and the reading conveniences players expect. The script runtime (Ren'Py, Ink, Yarn Spinner) does the stepping; this skill decides routes, flags, saves and the reader-facing systems, and checks them.

When to use

  • The game is mostly reading text with character art, backgrounds and choices.
  • Planning routes and endings, affection systems, save behaviour, backlog, skip and auto, or checking that every ending can be reached.

When not to use: NPC conversations inside another genre (dialogue-systems, with rpg for quests); Ink or Yarn integration code (dialogue-systems); the text box and choice menu widgets (godot-ui-control, game-ui-ux).

Workflow

  1. Find the engine. In Ren'Py (game/*.rpy), the engine already has save-anywhere, rollback, history, skip, auto-forward and text speed: restyle its screens and preferences, and spend the effort on routes and flags. Elsewhere, build those systems from refs §4-5.
  2. Draw the route map before writing: common route, the lock-in point (often about a third of the way through), each route's endings, and a true ending gated on finishing others if wanted. Write the flags and the thresholds each ending needs next to it.
  3. Size the script. Readers average roughly 200-250 words per minute, so 1,000 words is about 4-5 minutes; a 2-hour VN is about 25,000-30,000 words. Give a meaningful choice or reaction every 5-15 minutes of reading, and make at least one later line visibly react to each important choice.
  4. Track state as booleans for one-off decisions and counters for affection. For each route, add up the maximum affection the choices can give and set the ending threshold below it, with some slack for missed choices.
  5. Saves resume the exact line with all flags, and seen-text data lives in a persistent store shared by all saves (refs §4).
  6. Check it. Run what applies and report the output:
    • Ren'Py: ./renpy.sh <project> lint --error-code (exit 1 on lint errors), and ./renpy.sh <project> test for scripted test cases;
    • Ink: inklecate -o story.json story.ink (exit 1 on compile errors; -s prints word counts), then a breadth-first walk with inkjs: Continue() while canContinue, save state.ToJson() at each choice, LoadJson() and ChooseChoiceIndex(i) for each branch, and collect currentTags at each end. Tag ending lines (for example # ending: alice_good) and assert every planned ending appears. Cap the depth and dedupe states for big scripts;
    • any engine: save at a choice, quit, load, and confirm the same line and choices appear; enable skip on a fresh profile and confirm it stops at the first unseen line.

Reader systems

System Default Notes
Text speed instant or fast by default, with a slider Ren'Py's own default is instant (preferences.text_cps = 0)
Skip read text only; stops at choices and unseen lines Ren'Py: preferences.skip_unseen = False
Auto-forward delay scaled by line length; pauses at choices Ren'Py: preferences.afm_time = 15
Backlog 100-200 lines, with voice replay rollback in Ren'Py doubles as backlog
Saves many slots with thumbnail, date and chapter, plus quick save autosave at chapter starts and before choices
Galleries CG, music and ending lists unlocked across all saves Ren'Py persistent data

Pattern 1: typewriter reveal that does not jump

# Set the full text once, then reveal by visible-character count.
def show_line(speaker, text):
    name_label.text = speaker
    body.text = text                         # wrapping decided once, on the full text
    shown = 0.0
    while shown < visible_length(body) and not advance_pressed():
        shown += cps * frame_dt()
        body.visible_characters = int(shown)
        wait_frame()
    body.visible_characters = -1             # first press completes the line
    backlog.append((speaker, text)); seen.add(line_id)
    wait_for_advance()                       # second press moves on

Godot 4.7: RichTextLabel.visible_characters with visible_characters_behavior = TextServer.VC_CHARS_AFTER_SHAPING (the default leaves hidden text out of line breaking, so words still jump). Unity 6.3: TMP_Text.maxVisibleCharacters.

Gotchas

  • Load resumes at the start of a scene → only a checkpoint or node name is saved. Ink saves the exact position with state.ToJson(); Yarn Spinner restores only the node (refs §4).
  • Old saves break after an update → lines moved or edited under a save. Give lines stable IDs, keep released labels, and test loading saves from the previous build.
  • Ren'Py flag not saved or reset on load → declared with define (meant for constants) instead of default. Story state uses default.
  • Skip runs through new text → seen-text stored per save, or skip set to "all". Store seen line IDs in persistent data shared by all saves.
  • An ending is unreachable → thresholds above the maximum the choices can give, or a flag set on one branch and read on another. Run the reachability walk (step 6).
  • Choices feel fake → branches merge back immediately with no reaction. Pay each choice off with at least one later line, sprite or option.
  • Text jumps between lines or shows raw tags → the reveal slices the string (Pattern 1).
  • Branch explosion → fully separate trees for every choice. Branch and merge, with flags that vary lines, and reserve full routes for the big decisions.
  • Text baked into code or images → no translation path. Keep strings in the script or a table keyed by line ID, and leave room for 30% longer text in the box.

References

  • references/script-and-flow.md: read when designing the script data model, choosing a route structure, picking ending logic from flags, writing save-anywhere data (Ink, Yarn Spinner and Ren'Py specifics), backlog, skip and auto behaviour, staging conventions or localisation.

Related: dialogue-systems (Ink and Yarn runtimes), save-systems (slots, versioning), game-ui-ux with godot-ui-control (text box, choices, backlog screen), audio-design (music, voice), prototype-fast (test the branch map in plain text first).

Version notes

Last verified: 2026-11-11.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    The visual-novel skill provides guidance for building branching stories and contains instructions for project linting and testing using engine-specific tools. It includes shell command execution patterns for Ren'Py and Ink compilers and presents an indirect prompt injection surface as it processes external game script files to perform automated checks.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/visual-novel