Inko Handwriting

Inko handwriting

Inko writes text the way a person does — real pen strokes, not a font — and returns A4 pages (PNG + PDF, 300 dpi). This skill makes you the expert operator: you prepare the content, pick paper / size / handwriting / pen with the user, generate for their request for free, and deliver standard flat page images or PDFs. Preserve the natural handwriting, not a simulated camera: no perspective, desk scenes, shadows, page curl, scanner effects or photo compositing.

Current pricing — skill 1.6.0 (2026-10-08)

Lyric 1 and Logic 1 handwriting inference is free on both the website and this API / Skill. No per-character fee, minimum charge, membership or recharge is required; an authenticated account with zero balance can generate. The website's DeepSeek assistant is billed separately for actual API token usage. This handwriting CLI does not call DeepSeek; the external AI agent's own model fees belong to its provider, not Inko handwriting inference. Each user also gets one free custom-handwriting seat; never suggest purchasing an extra seat.

All scripts are in scripts/ next to this file (call them with the path you installed to, e.g. python .claude/skills/inko-handwriting/scripts/inko.py …). They print JSON on stdout — read it, don't guess.

What the models can write changes as they learn: this skill never lists it. Get it live — inko.py charset (plain text: Greek, pinyin tones, superscripts, ½, ⑪, 「」 … per model, and what custom handwritings can't write) and inko.py models --symbols (LaTeX commands inside $…$) — and let the free quote have the last word. For Logic math, read references/writing-math.md §5 before preparing formulas. When either command reports skill_update, tell the user once that a newer version of this skill is available (git pull the inko-skill clone, then python install.py).

What changed in skill 1.5.0 (2026-10-06): the lists of writable characters and LaTeX commands moved out of these files into the live inko.py charset / models --symbols, so the skill stays right as the models learn (Greek letters, pinyin tones, superscripts, ½, ⑪, 「」 … were added on 2026-10-06).

What changed on 2026-10-04 (skill 1.4.0): both models were retrained on English handwriting (word spacing, capitals, baseline); the layout engine breaks a formula wider than a whole line at =, ≤, + … instead of shrinking it; generated formulas keep the same size as the text around them; Logic can have its own 常用字迹; removing the visible label needs only the signed agreement (no seat).

First time in a session

bashCopy code
python scripts/inko.py doctor          # Python deps, API reachable, key valid, balance, the user's 常用字迹 / favourites

• No key: ask the user to create one at https://inkotype.com (账户 → API key), ideally a separate key for you with a daily spending limit. Save it with python scripts/inko.py auth (reads the key from stdin; --project stores it in ./.inko/key instead of the user config dir). Never repeat the key back, never write it into project files or commits.
• Missing Pillow/numpy: python -m pip install -r scripts/requirements.txt.
• inko.py keeps a small git-ignored ./.inko/ folder in the working directory: jobs.jsonl (job log), plans/ (what each job was made from), optionally key. Results go to ./inko-output/<time>-<id>/. You may keep the user's other choices in ./.inko/prefs.json yourself (write it with your file tool, e.g. {"pen": "gel|blue", "paper": "ruled8"}): read it at the start of later sessions and reuse them — no script reads it for you. Their preferred handwriting lives on their Inko account instead (常用字迹, below), so every agent and the website share it.

Rules that matter (and why)

1. Free inference: validate first, then generate for the user's request. inko.py generate without --yes only checks the content and settings. Quotes remain useful for character support, page count, fit and handwriting; the price should be 0. Once the user has requested generation and essential settings are resolved, run with --yes without asking for payment confirmation or a top-up. --max-cents defaults to 0: an unexpected positive quote is blocked, not silently hidden. Check the API base / service pricing and report the discrepancy instead of assuming inference is paid. Free does not mean unlimited: respect authentication, rate limits and queue capacity.
2. Keep the AI labels. Every page carries a visible label 「AI生成 · Inko」 and hidden AIGC metadata, required by Chinese law (GB 45438-2025) and Inko's terms. Never crop, cover, blur, recolour or paint over the label, never strip metadata, never re-save through tools that drop it. The scripts here re-apply the label (≥ 5 % of the shortest side, readable contrast) and copy the metadata on every output — use them rather than ad-hoc image code. If the user asks to remove the label, explain it's a legal requirement. Only accounts whose owner signed the AI-labelling agreement (《AI 生成内容标识协议》) on the website can request label-free pages themselves (--label none, see account.can_remove_label; anyone else gets 403 label_required; no seat or purchase is involved), and they still have to disclose AI generation when sharing. Don't bring up label removal unless the user asks.
3. No forgeries. Inko refuses IOUs, receipts, contracts, certificates, leave notes, signatures and similar documents (content_blocked, not charged). Don't try to work around it (splitting text, renaming things, compositing a signature). Don't imitate a specific real person's handwriting without their consent.
4. Look before you hand over. Open the PNG / final image yourself (you can view images; zoom into a few lines) and check it: all text present, nothing overlapping, no odd wide gaps (around formulas especially), writing sitting on the ruled lines (not crossing them), left edges not ruler-straight (drifted — see post-processing), label intact, and the usual weak spots — punctuation right after a formula, digits in dates, units. Layout / spacing / pen problems are fixed locally from scene.zip without regenerating (post-processing); only wrong characters need a rewrite. inko.py rewrite JOB --yes re-writes the whole job once for free with a new seed: other characters change too, so compare both versions and keep the better one; a rewrite can't be rewritten. If a character that matters is still wrong after that, rephrase the text around it (a digit in a heading → Chinese numeral, drop a comma right after a formula) and generate again — still free, but at most once or twice rather than retrying endlessly; otherwise deliver the best version and say which character is off. inko.pdf is made of the same pages as the PNGs — check the PNGs, and copy the PDF to a meaningful name when delivering.
5. Content quality is your job. Inko writes exactly what you give it. Typos, a wrong answer or a clumsy line break will be faithfully hand-written — proofread the text first.
6. Do what was asked, exactly. "Copy this" means every character, line break, capital and punctuation mark kept — no summarising, tidying or "fixing" the source. "Only the final answers" means only the results: no question text, no working, no checks, no 解 / 答 prefixes. A complete document is delivered as one document that may run over several pages, never shortened or split into repeated copies. If a question is unreadable or a condition is missing, ask — don't guess an answer.

Workflow

1. Understand the goal: what content, for what (homework to hand in, notes, a letter, a mock-up…), on what paper, and the final form (flat PNG pages, PDF, or both). Images supplied as questions are input material only.
2. Prepare the content (the part users value most — see the scenario guides below). For math, solve it and write the solution the way a student writes it, not the way a textbook typesets it: each formula on the same line as its lead-in (所以 $x=4$, 移项得 $2x=8$), never $$…$$ (a centred line of its own — textbook look), no full stops (。．.) anywhere in a solution, commas at most. Long = chains simply run on: with logic-1 inko.py cuts them into pieces that continue on the next line (formula_splits; --keep-formulas turns it off), and the layout engine breaks anything still wider than a line at = / ≤ / + — never break a chain into lines yourself. Prose keeps its 。. Check every character against what the models can write (references/writing-text.md, "What can be written") before the quote does it for you.
3. Choose model, handwriting, size, paper, pen. Defaults are fine for anything the user doesn't care about.
4. Confirm in one message — see "Ask the user" below. Don't interrogate; ask only what changes the result.
5. Free checks: inko.py quote (plain) or inko.py layout --preview (custom layout) → fix any unsupported characters/symbols (the output says where) and any math_style warnings ($$, full stops, a lead-in cut off from its formula), show the preview if placement matters.
6. Generate (inko.py generate … --yes) → pages land in ./inko-output/<time>-<id>/ with job.json (and plan.json for layout jobs).
7. Post-process only as needed (table below). Keep the generated page flat; optional line-position adjustment uses drift (scene.py drift when the job came with scene.zip, else compose.py drift) → look at the result → deliver file paths, cost, and what the user can tweak next ("bluer ink? bolder strokes? a different handwriting? move something yourself in the editor?").

For image/PDF homework, also follow the completeness checklist in references/scenarios.md. Automatic preparation means reusing the user's defaults, not repeatedly asking style questions; it does not create permission for unrelated paid services. A website adapter's provided tools and layout rules take precedence over CLI-only instructions.

Pick the model

Formulas decide it: one $x^2$ means logic-1. Chemistry like H₂O can be plain text in either model (whether the subscript ₂ is written as-is or as H2O: see inko.py charset). Answers that are only numbers ("只写最终答案": x=4, -3, 40) need no formulas and can stay with lyric-1. Without --model, inko.py picks this way automatically and says so in its output.

Never ask the user to choose a model or to resolve a handwriting/model clash. When the job needs logic-1 but the handwriting they picked (or their 常用字迹) is Lyric-only — every custom handwriting and most presets are — use their Logic 常用字迹 (default-style shows default_styles["logic-1"]), else one of their Logic favourites, else leave out --style (Inko uses the account's Logic default), and say so in one line: 「含公式，公式部分用 Logic 1 的字迹写」. Only a handwriting they explicitly named for this job and that can't do Logic is worth a sentence before going on.

Choose the handwriting — the user's own choices come first. Go down this list and stop at the first that applies:

1. They name one for this job (No.205, 「用我自己的字」, 「这次写工整点」) → --style, or filter by that description.
2. Their 常用字迹 (default handwriting, saved on their account): leave out --style and Inko uses it. There can be two: a general one and, optionally, Logic's own (one of the account's 8) — inko.py default-style lists what each model really uses (default_styles). The quote says which handwriting will be used (style.source: default = their 常用字迹; system = Inko's fallback). When no 常用字迹 can do this job's model — custom handwritings are Lyric-only, Logic only has the account's 8 — the quote's style_note says so; then continue with 3.
3. Their favourites (收藏): inko.py styles --favorites --model <the job's model> — pick the one that fits the job (neat for homework to hand in, relaxed for notes), or offer two or three.
4. Nothing saved: filter by what the job needs (references/styles.md). Never settle for the fallback: Lyric's is No.001, one of the most casual, joined-up hands.

When the user says 「以后都用这个」, save it for them: inko.py default-style CODE (add --model logic-1 for a Logic handwriting meant only for math; it changes their account, the website included — only on request).

Plain pages or a custom layout?

• Plain (--text/--file, --paper white|cream|grid, --size small|medium|large): paragraphs flow on A4. Fast, good for essays and "just write this". Every line of your text is a paragraph and gets a 2-character first-line indent (no switch) — for lists, notes and solutions use a layout with "indent": 0. Squared (5 mm grid) paper exists only here.
• Layout (--layout layout.json): exact size in mm, line spacing, margins, ruled / 作文纸 / 田字格 / letter paper, titles centred and bigger, no indent, text boxes anywhere (answers, name, date), writing along a curve, per-character pen or handwriting. Use when exact page placement matters. Read references/layout.md; templates are in assets/layouts/; inko.py accepts shorthands so you never count character positions. Check with inko.py layout --spec layout.json --preview preview.png (free, local preview). For squared paper, use plain --paper grid; custom layouts currently use the built-in flat paper types.

Ask the user (only what's missing)

Put the open questions in one message, with your suggested default for each, in the user's language. Never ask in pieces over several turns, never re-ask what they already told you (in this request, earlier, or in ./.inko/prefs.json), and never treat your recommendation as their answer. Typical:

• Detail level (math/homework): 详细（每步都写，适合交作业/给人讲懂）/ 适中（关键步骤）/ 简洁（像草稿，跳步）
• Handwriting: if they have a usable 常用字迹, just say you'll use it (no question needed). Otherwise offer 2–4 candidates as a contact sheet — favourites first (inko.py styles --favorites / inko.py styles … + inko.py previews CODES) — or ask "工整 / 自然 / 潦草，偏圆还是偏方？"; their own custom handwriting if they have one (lyric-1).
• Paper & size: white / cream / grid / ruled 8 mm / 7 mm / 作文纸 / 田字格 / letter; character size (small ≈ 6 mm, medium ≈ 7 mm, large ≈ 8.5 mm tall). This is the one question worth asking for a first job when the user gave only the content: recommend 「A4 竖版白纸」 first. "A4" alone is already an answer (portrait, white, no lines); an uploaded page to write on is one too.
• Pen: original / gel 中性笔 / ballpoint 圆珠笔 / fountain 钢笔 / pencil 铅笔; black / blue / blue-black; thinner–bolder.
• Output: standard flat PNG pages / PDF / both.
• Characters the models can't write (the live list: inko.py charset; the quote flags each one): ask once whether to use the writable equivalent the list suggests, with your recommendation first and one or two real examples from their text. If they already said how, or told you not to ask about such things, just apply the recommended form and mention it.
• Cost: state that handwriting inference is free; do not ask for payment confirmation for a zero quote.

If the user said "you decide" / 「随便」 / 「默认」 / 「不要问」 or the request is clear, decide, state your choices in one line, and proceed after validation. Don't stop for payment confirmation or optional layout preferences (margins, line spacing, alignment).

Post-processing (all local, instant, free)

Prefer the API's own pen options (--pen-type/--pen-color/--pen-weight/--pen-ink) when generating — they are applied at full quality; use ink.py for colours the API doesn't have (red, green, purple, #hex), textures like marker, or quick "what if" variants without regenerating. All edits stay on the flat page. paper.py make can draw a separate standard paper background; it does not paste handwriting into a photo. Details: references/postprocess.md.

Scenario guides

Read the relevant guide for content and flat-page layout decisions.

• references/scenarios.md — math answers, notes, letters, essays and copying practice as flat pages or PDF.
• references/writing-math.md — how students actually write solutions (解/由…得/所以/答), detail levels, the Logic symbol table, substitutions for unsupported symbols, LaTeX pitfalls.
• references/writing-text.md — paragraphs, punctuation, letters, essays, English text, line breaks that look natural.
• references/styles.md — choosing a handwriting from descriptions ("工整好看", "像男生写的", "潦草"), facets, previews.
• references/layout.md — the layout JSON (papers, d, boxes, marks, pens), recipes, reading the plan.
• references/postprocess.md — ink / PDF / optional flat-page drift options with examples.
• references/scene.md — the editable glyph package (scene.zip): inspect, tighten gaps, drift, move, restyle, the browser editor for the user, rendering with the label.
• references/api.md — endpoints, parameters, limits, billing, job states, files and expiry.
• references/troubleshooting.md — every error code and what to do; common script problems.

Writing JSON and LaTeX safely

LaTeX backslashes die in shells and JSON (\frac → form-feed + rac, \neq → newline + eq). Write text and layout files with your file-writing tool (not echo/heredoc), double every backslash inside JSON strings ("\\frac{a}{b}"), and pass them with --file / --layout. inko.py refuses input that shows swallowed backslashes and says why.