THE AGENT SKILLS DIRECTORY
Reusable skills for AI agents. Install any of them into a Cohub world's agent with one command.
npx -y @neta-art/neta-search-cli@latest skills find "<what you need>"
Wrote a skill? Publish it here →
Basic Cohub abilities. Most agents already have these mounted; listed here for reference.
Paste this into your agent's chat — it fetches the skill and follows it.
Use the skill: single-page-vn. Run `npx -y @neta-art/neta-search-cli@latest skills use @gqg946cybh/single-page-vn --via site` and follow what it prints. Read its complete output, redirecting it to a temporary file first if necessary, and resolve relative paths from the skill directory it prints.npx -y @neta-art/neta-search-cli@latest skills use @gqg946cybh/single-page-vnTurn your world into a short visual novel you can play in the browser, finished in one sitting.
# Single-page visual novel
A visual novel the reader can finish in one sitting: background, one line of text at a time, a few places, a handful of choices that ask rather than branch, and one moment where they must write or choose something before the story lets them through. It is cheap to build — one HTML page, a flat beat array, no engine — and it reads like a film because a section table turns the same data into progress dots and an overview panel.
Read this file fully before writing any file or generating any image. Resolve relative paths from this skill's directory.
## Language
Reply in the user's language, whatever language this file is in. This holds for every message of the run, above all the final handover; translate what the scripts print, don't paste it. Text the reader sees in the deliverable — Work title, page title, buttons, labels, hints — follows the user's language: the build freezes the template's UI strings from `templates/vn/locales.json` by the story's `locale`, and adds a locale entry when the language is not built in. Text the user typed (names, titles) stays as they wrote it.
## When to use / when not
Use when the user wants a story they can play through on one screen — a 文游, a visual novel, a short narrative game in their world. Not for a branching AVG with stats, maps or a character-art pipeline (that is the `create-avg` skill), and not for reading a chapter as prose (that is `novel-chapter-pages`) — say what this skill makes and stop.
## Inputs
| Item | Required | Counts as given when |
|---|---|---|
| The premise: who arrives where, and what it costs them | yes | The user names a protagonist and a place, or says to make one from this world — then derive both from `world/WORLD.md` and the cast |
| The reader's language | no — default the user's language | The user writes in it |
| Length | no — default 400–700 beats, 8–12 scenes | The user says "short" (≈250) or "long" (≈900) |
| Backgrounds | no — default generated in the world's `visualStyle` | The user supplies a folder of images |
If the premise is missing, ask for it once in one message — who, where, and what it costs — then stop. When it is given, ask nothing and build through to delivery; state the defaults you took (length, art) in the same turn.
## Steps
`$RUN` = `_runs/single-page-vn/<timestamp>/` under the workspace root, unless the user or the environment names another folder; if they do, pass that folder to the scripts and never move it afterwards.
1. **Read the world.** `world/WORLD.md` for name, tone, era, `visualStyle`; then 4–8 materials (`neta atom list`) for places, rules and people the story will use. Write the chosen cast, the rules that constrain them and the exact background prompts to `$RUN/brief.json`.
2. **Write the scene list.** 8–12 scenes, each one place at one time of day, each with an `id`, a background filename, and a `tone` (`neutral` / `warm` / `cold`). Fewer images than scenes is correct: reuse one image across two scenes with a different crop or tone. → `$RUN/story.json` (`scenes`).
3. **Make the backgrounds.** One image per file, through the skill's own script:
```bash
node scripts/gen.mjs --kind image --state $RUN/gen/<scene>.json --prompt "<prompt>" --work-title "<title in the reader's language>" --models <fallback-a>,<fallback-b>
```
Rerun the same command while it prints `generating` or `busy`; never submit again by hand. Copy the returned files into `$RUN/art/`. Read `references/art.md` for the prompt recipe and the crop rules.
4. **Write the beats.** 300–900 entries, one screen each, fields `scene` / `mode` (`narration` / `dialogue` / `thought`) / `speaker` / `chapter` / `text`; a `choices` list where the reader picks, and exactly one beat with a `gate`. Add the `sections` table. Read `references/craft.md` before writing — it holds the shape, the choice rule and the gate rule.
5. **Build the page.**
```bash
node scripts/build.mjs --story $RUN/story.json --art $RUN/art --out works/webs/<slug> --lang <locale>
```
It copies the template, freezes the locale, embeds the story and writes `story.json` into the Work folder.
6. **QA.** Two checks, both must pass:
```bash
node scripts/qa.mjs --out works/webs/<slug>
```
Exit 0 and `qa.json` with `errors: []`; then open the page once at 390×844 and once at 1280×720 — the dialogue box must not cover the speaker line, choices must be tappable, and the gate must be reachable. Fix and rerun; do not deliver on warnings you have not read.
## Deliver
A web Work, registered and published before the card.
1. `node /mods/neta/neta work init web works/webs/<slug> --title "<title in the reader's language>"`
2. `node /mods/neta/neta work publish web works/webs/<slug> --title "<same title>"` — if the world's `AGENTS.md` names a patched CLI for web works (this one ships `tools/neta`), use that binary for both commands instead. If the world has no slug, publish fails with `world_slug_required`: report it and stop, do not set one.
3. **Hand over with a card.** One `interaction-components` link card on its own line, target `{ "type": "work", "workId": "<id>" }`, the id taken from the publish output (fallback: `cohubWorkId` in `works/webs/<slug>/meta.json`) — never a made-up id, a folder, or a `world-file` link to `index.html`. The run is not delivered until this card is sent. Then one or two lines on what it is, in the user's language.
## Out of scope
- Do not change world settings: `world/WORLD.md` config, `visualStyle`, the world slug.
- Do not delete or overwrite files that existed before the run; build into a fresh `works/webs/<slug>` folder.
- Do not modify memory, character cards, installed scripts, existing Works or roleplays.
- Make only this one Work; do not act on your own next-step suggestions, and do not publish a second route unasked.
- No branching AVG systems (stats, inventory, maps), no voice acting, no video.
## When to stop
- Premise missing: ask who / where / what it costs, once, then stop.
- No `visualStyle` in the world: say it must be set first (covers render in one style), then stop.
- Publish refused for a missing world slug or permission: report exactly what it said and stop. Do not change world settings to get past it.
- Background generation returns `blocked` (credits or permission): say so plainly and stop; another model will not help.
## Gotchas
- **One image, several scenes.** A single classroom plate served three scenes in the reference build by moving the crop (`backgroundPosition`) and changing the chalkboard text. Ten images carried twelve scenes; budget 8–10 generations, not one per scene.
- **Choices ask, they do not branch.** The reference build had eight choice points, and six of them returned to the same menu ("ask about the world / go to sleep"). Branching multiplies the writing; an ask-menu gives the reader control at almost no cost. Reserve real branching for the one place the story turns.
- **The gate is the theme.** Make the reader do the thing the story is about (write a new name, hand something over, refuse a gift). It must have a non-empty `accept` list and a `reject` map with a line of dialogue for the wrong answer — a gate that accepts anything is decoration.
- **Signature gates on touch do not read handwriting.** The engine accepts any ink past a stroke threshold on coarse pointers, and compares typed text on desktop. Say so in the reply if the reader asks how it works.
- **Sections must tile the beats.** `start` of the first is 0, each next is previous `end + 1`, last `end` is the final beat. A gap makes the progress dots and the overview lie, and `qa.mjs` fails it.
- **Keep a beat under ~220 characters.** The box fits three lines on a phone; longer lines get clipped mid-sentence and the typewriter hides it.
- **`neta work publish web` needs `COHUB_SPACE_ID` and a world slug.** Without the slug it fails rather than guessing one.
- **Do not hard-code UI text.** The build takes every hint and label from `templates/vn/locales.json`; adding Chinese strings straight into `index.html` fails QA on an English build.