SKILL.md

$2b

English novel writing: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set --lang en

Chinese web novel writing: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)

Fan fiction: Create fanfic from source material with 4 modes (canon, au, ooc, cp)

Batch chapter generation: Generate multiple chapters with consistent quality

Import & continue: Import existing chapters from a text file, reverse-engineer truth files, and continue writing

Style imitation: Analyze and adopt writing styles from reference texts

Spinoff writing: Write prequels/sequels/spinoffs while maintaining parent canon

Standalone short fiction: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image

Cover generation: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing

Quality auditing: Detect AI-generated content and perform 33-dimension quality checks

Genre exploration: Explore trends and create custom genre rules

Analytics: Track word count, audit pass rate, and issue distribution per book

Initial Setup

First Time Setup

# Initialize a project directory (creates config structure)

inkos init my-writing-project

# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)

# Prefer --api-key-env so the key never appears in shell history:

export OPENAI_API_KEY=sk-xxx

inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o

# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:

# inkos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o

Multi-Model Routing (Optional)

# Assign different models to different agents — balance quality and cost

inkos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY

inkos config set-model auditor gpt-4o --provider openai

inkos config show-models

Agents without explicit overrides fall back to the global model.

Provider setup tip

When the user needs an aggregator provider, point them to Studio's service settings. InkOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use:

Chinese website: https://kkaiapi.com/

English website: https://en.kkaiapi.com/

Chinese API docs: https://kkaiapi.com/docs

English API docs: https://en.kkaiapi.com/docs

Chinese models/pricing: https://kkaiapi.com/models

English models/pricing: https://en.kkaiapi.com/models

View System Status

# Check installation and configuration

inkos doctor

# View current config

inkos status

Common Workflows

Workflow 1: Create a New Novel

Initialize and create book:

inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000

# Or with a creative brief (your worldbuilding doc / ideas):

inkos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md

Genres: xuanhuan (cultivation), xianxia (immortal), urban (city), horror, other

Returns a book-id for all subsequent operations

Generate initial chapters (e.g., 5 chapters):

inkos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"

The write next command runs the full pipeline: draft → audit → revise

--context provides guidance to the Architect and Writer agents

Returns JSON with chapter details and quality metrics

Review and approve chapters:

inkos review list book-id

inkos review approve-all book-id

Export the book (supports txt, md, epub):

inkos export book-id

inkos export book-id --format epub

Workflow 2: Continue Writing Existing Novel

List your books:

inkos book list

Continue from last chapter:

inkos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"

InkOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency

If only one book exists, omit book-id for auto-detection

Review and approve:

inkos review approve-all

Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw)

When InkOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls:

inkos interact --json --message "continue the current book, but keep the pacing tighter"

inkos interact --json --message "rewrite chapter 3"

inkos interact --json --book my-book --message "switch to auto mode"

This returns a structured payload containing:

the routed request

assistant response text

updated interaction session

execution state

pending decision

recent interaction events

Use this as the primary OpenClaw entry because it shares the same control layer as the project TUI.

Workflow 2.6: Steering Chapter Focus Before Writing

Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize".

Update the book-level control docs when needed:

Use update_author_intent to change the long-horizon identity of the book

Use update_current_focus to change the next 1-3 chapters' focus

Compile the next chapter intent:

plan_chapter(bookId, guidance?)

Generates story/runtime/chapter-XXXX.intent.md

Use this to verify what the system thinks the next chapter should do

Compose the actual runtime input package:

compose_chapter(bookId, guidance?)

Generates story/runtime/chapter-XXXX.context.json

Generates story/runtime/chapter-XXXX.rule-stack.yaml

Generates story/runtime/chapter-XXXX.trace.json

Only then write:

write_draft if the user wants intermediate review

write_full_pipeline if they want the usual write → audit → revise flow

Recommended orchestration:

user asks to redirect focus

update_current_focus

plan_chapter

compose_chapter

inspect the resulting intent/paths

write_draft or write_full_pipeline

Workflow 3: Import Existing Chapters & Continue

Use this when you have an existing novel (or partial novel) and want InkOS to pick up where it left off.

Import from a single text file (auto-splits by chapter headings):

inkos import chapters book-id --from novel.txt

Automatically splits by 第X章 pattern

Custom split pattern: --split "Chapter\\s+\\d+"

Import from a directory of separate chapter files:

inkos import chapters book-id --from ./chapters/

Reads .md and .txt files in sorted order

Resume interrupted import:

inkos import chapters book-id --from novel.txt --resume-from 15

Continue writing from the imported chapters:

inkos write next book-id --count 3

InkOS reverse-engineers all 7 truth files from the imported chapters

Generates a style guide from the existing text

New chapters maintain consistency with imported content

Workflow 4: Style Imitation

Analyze reference text:

inkos style analyze reference_text.txt

Examines vocabulary, sentence structure, tone, pacing

Import style to your book:

inkos style import reference_text.txt book-id --name "Author Name"

All future chapters adopt this style profile

Style rules become part of the Reviser's audit criteria

Workflow 5: Spinoff/Prequel Writing

Import parent canon:

inkos import canon spinoff-book-id --from parent-book-id

Creates links to parent book's world state, characters, and events

Reviser enforces canon consistency

Continue spinoff:

inkos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"

Workflow 6: Fine-Grained Control (Draft → Audit → Revise)

If you need separate control over each pipeline stage:

Generate draft only:

inkos draft book-id --words 3000 --context "protagonist escapes" --json

Audit the chapter (33-dimension quality check):

inkos audit book-id chapter-1 --json

Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more

Revise with specific mode:

inkos revise book-id chapter-1 --mode polish --json

Modes: polish (minor), spot-fix (targeted), rewrite (major), rework (structure), anti-detect (reduce AI traces)

Workflow 7: Monitor Platform Trends

inkos radar scan

Analyzes trending genres, tropes, and reader preferences

Informs Architect recommendations for new books

Workflow 8: Detect AI-Generated Content

# Detect AIGC in a specific chapter

inkos detect book-id

# Deep scan all chapters

inkos detect book-id --all

Uses 11 deterministic rules (zero LLM cost) + optional LLM validation

Returns detection confidence and problematic passages

Workflow 9: View Analytics

inkos analytics book-id --json

# Shorthand alias

inkos stats book-id --json

Total chapters, word count, average words per chapter

Audit pass rate and top issue categories

Chapters with most issues, status distribution

Token usage stats: total prompt/completion tokens, avg tokens per chapter, recent trend

Workflow 10: Write an English Novel

# Create an English LitRPG novel (language auto-detected from genre)

inkos book create --title "The Last Delver" --genre litrpg --chapter-words 3000

# Or set language explicitly

inkos book create --title "My Novel" --genre other --lang en

# Set English as default for all projects

inkos config set-global --lang en

10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy

Each genre has dedicated pacing rules, fatigue word lists (e.g., "delve", "tapestry", "testament"), and audit dimensions

Use inkos genre list to see all available genres

Workflow 11: Fan Fiction

# Create a fanfic from source material

inkos fanfic init --title "My Fanfic" --from source-novel.txt --mode canon

# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)

inkos fanfic init --title "What If" --from source.txt --mode au --genre other

Imports and analyzes source material automatically

Fanfic-specific audit dimensions and information boundary controls

Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)

Workflow 12: Rename Characters or Entities Across Entire Book

# Via interact

inkos interact --json --message "把林烬改成张三"

inkos interact --json --message "rename Lin Jin to Zhang San"

# Via slash command

inkos interact --json --message "/rename 林烬 => 张三"

Scans all chapters + all truth files (story_bible, current_state, character_matrix, etc.)

Replaces every occurrence in one pass

Returns count of files touched

Workflow 13: Patch Specific Text in a Chapter

inkos interact --json --message "/replace 5 旧文本 => 新文本"

Precisely replaces text in chapter 5 only

Marks chapter for review after patching

Workflow 14: Interactive TUI Dashboard

inkos

Launches a full-screen Ink + React dashboard with conversational creation

Slash command autocomplete (Tab), input history (arrow keys)

Themed activity animations per operation (writing, auditing, revising, planning)

Bilingual i18n (Chinese / English)

Shares the same interaction kernel as inkos interact and Studio

Workflow 15: Standalone Short Fiction Package

Use this when the user wants a complete short story or short-fiction deliverable that is separate from the active long-form book.

inkos short run \

  --direction "modern short fiction marriage reversal evidence-driven heroine" \

  --chapters 12 \

  --chars 1000

Outputs are written under shorts/<story-name>/final/:

full.md — complete short-fiction manuscript

sales-package.md — synopsis and selling points

cover-prompt.md — cover prompt

cover.png — cover image when a cover provider is configured

For OpenClaw/Studio/agent orchestration, call the short_fiction_run tool when the user asks for a new complete short-fiction package. Do not use it for the next chapter of an existing long-form book.

Workflow 16: Standalone Cover Tool

Use this when the user only wants a cover for an existing title, synopsis, or visual direction. Do not rerun the short-fiction pipeline.

In Studio or agent mode, ask naturally:

Generate a short-fiction cover for "The Divorce Papers He Regretted", modern city, high-drama reversal.

For tool-using agents, call generate_cover with:

title — required

intro or sellingPoints — optional story context

coverPrompt — optional visual direction

outputDir — optional; defaults to covers/<title>/

The standalone cover tool writes:

covers/<title>/cover-prompt.md

covers/<title>/cover.png

If cover image generation fails, report the provider/configuration error plainly. Do not rewrite the story, do not rerun short_fiction_run, and do not suggest unrelated external tools unless the user asks.

InkOS Studio (Web Workbench)

inkos studio launches a local web UI (default port 4567) that provides a visual interface for all InkOS operations:

Book management — create, delete, export (TXT/MD/EPUB), configure per-book settings

Short fiction & cover tools — generate independent short-fiction packages, synopsis/selling points, cover prompts, and standalone covers

Chapter review & editing — approve/reject drafts, edit content inline, multi-mode revision (polish/spot-fix/rewrite/anti-detect)

Real-time writing progress — SSE-based live updates during chapter generation

Market radar — AI-powered trend analysis with platform/genre recommendations

Analytics — word count, audit pass rate, chapter ranking, token usage

AI detection — scan chapters for AI-generated content

Style analysis — analyze reference texts and import writing styles

Genre management — create/customize genre profiles with fatigue words, pacing rules, audit dimensions

Daemon control — start/stop background writing with event log

Truth file editor — view and edit canonical knowledge base per book

Config editor — LLM provider, model routing, notifications

inkos studio              # Start on default port 4567

inkos studio -p 8080      # Start on custom port

The right-side AI Assistant panel in Studio shares the same interaction kernel as TUI and inkos interact. You can type natural language commands (rename entities, write chapters, audit, export) directly in the assistant panel.

Advanced: Natural Language Agent Mode

For flexible, conversational requests:

inkos agent "写一部都市题材的小说，主角是一个年轻律师，第一章三千字"

Agent interprets natural language and invokes appropriate commands

Useful for complex multi-step requests

Input Governance Tools

These tools are the preferred control surface for chapter steering:

plan_chapter(bookId, guidance?)

Generates chapter intent for the next chapter

Use before writing when the user wants to change focus

compose_chapter(bookId, guidance?)

Generates runtime context/rule-stack/trace artifacts

Use after planning and before writing

update_author_intent(bookId, content)

Rewrites story/author_intent.md

Use for long-horizon changes to the book's identity

update_current_focus(bookId, content)

Rewrites story/current_focus.md

Use for local steering over the next 1-3 chapters

Short Fiction and Cover Agent Tools

These are the preferred tools when InkOS is driven by OpenClaw, Studio chat, or inkos agent:

short_fiction_run

Creates an independent short-fiction package from a direction

Runs outline → outline review/revision → full draft → draft review/revision → synopsis/selling points/cover prompt → optional cover image

Writes to shorts/<story-name>/

Use only when the user asks for a separate complete short story / short-fiction deliverable

generate_cover

Generates only a cover prompt and cover image

Writes to covers/<title>/ by default

Use when the user asks to create or regenerate a cover for an existing title, synopsis, or completed short

Also use when the user changes the cover prompt through chat; pass the revised visual direction as coverPrompt and reuse the existing outputDir when available

Do not rerun story generation unless the user explicitly asks for a new story

write_truth_file remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.

Key Concepts

Book ID Auto-Detection

If your project contains only one book, most commands accept book-id as optional. You can omit it for brevity:

# Explicit

inkos write next book-123 --count 1

# Auto-detected (if only one book exists)

inkos write next --count 1

--json Flag

All content-generating commands support --json for structured output. Essential for programmatic use:

inkos draft book-id --words 3000 --context "guidance" --json

Truth Files (Long-Term Memory)

InkOS maintains 7 files per book for coherence:

World State: Maps, locations, technology levels, magic systems

Character Matrix: Names, relationships, arcs, motivations

Resource Ledger: In-world items, money, power levels

Chapter Summaries: Events, progression, foreshadowing

Subplot Board: Active and dormant subplots, hooks

Emotional Arcs: Character emotional progression

Pending Hooks: Unresolved cliffhangers and promises to reader

All agents reference these to maintain long-term consistency. Since 0.6.0, truth files are backed by schema-validated JSON in story/state/ with automatic bootstrap from markdown for legacy books. During import chapters, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.

Multi-Phase Writer Architecture

The Writer operates across multiple phases with specialized agents:

Planner: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.

Composer: Selects relevant context from truth files by relevance scoring, compiles rule stack and runtime artifacts.

Phase 1 (Creative, temp 0.7): Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.

Phase 2a (Observer, temp 0.5): Over-extracts 9 categories of facts from the chapter text.

Phase 2b (Reflector, temp 0.3): Outputs a JSON delta with hookOps (upsert/mention/resolve/defer), currentStatePatch, and chapterSummary. Code-layer validates via Zod schema and applies immutably.

Normalizer: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).

Auditor: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).

Reviser: Auto-fixes critical issues, self-correction loop until clean.

Truth files use structured JSON (story/state/*.json) as the authoritative source, with markdown projections for human readability. Hook admission control prevents duplicate/family hooks from inflating the hook table.

Context Guidance

The --context parameter provides directional hints to the Writer and Architect:

inkos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"

Context is optional but highly recommended for narrative coherence

Supports both English and Chinese

Genre Management

View Built-In Genres

inkos genre list

inkos genre show xuanhuan

Create Custom Genre

inkos genre create my-genre --name "My Genre"

# Options: --numerical, --power, --era

inkos genre create dark-xuanhuan --name "Dark Xuanhuan" --numerical --power

Copy Built-in Genre for Customization

inkos genre copy xuanhuan

# Copies to project genres/ directory for editing

Command Reference Summary

Command

Purpose

Notes

inkos init [name]

Initialize project

One-time setup

inkos book create

Create new book

Returns book-id. --brief <file>, --lang en/zh, --genre litrpg/progression/...

inkos book list

List all books

Shows IDs, statuses

inkos write next

Full pipeline (draft→audit→revise)

Primary workflow command

inkos draft

Generate draft only

No auditing/revision

inkos audit

33-dimension quality check

Standalone evaluation

inkos revise

Revise chapter

Modes: polish/spot-fix/rewrite/rework/anti-detect

inkos agent

Natural language interface

Flexible requests

inkos style analyze

Analyze reference text

Extracts style profile

inkos style import

Apply style to book

Makes style permanent

inkos import canon

Link spinoff to parent

For prequels/sequels

inkos import chapters

Import existing chapters

Reverse-engineers truth files for continuation

inkos detect

AIGC detection

Flags AI-generated passages

inkos export

Export finished book

Formats: txt, md, epub

inkos analytics / inkos stats

View book statistics

Word count, audit rates, token usage

inkos radar scan

Platform trend analysis

Informs new book ideas

inkos short run

Generate standalone short fiction

Outputs manuscript, sales package, cover prompt, optional cover

inkos config set-global

Configure LLM provider

OpenAI/Anthropic/custom (any OpenAI-compatible)

inkos config set-model <agent> <model>

Set model override for a specific agent

--provider, --base-url, --api-key-env for multi-provider routing

inkos config show-models

Show current model routing

View per-agent model assignments

inkos doctor

Diagnose issues

Check installation

inkos update

Update to latest version

Self-update

inkos up/down

Daemon mode

Background processing. Logs to inkos.log (JSON Lines). -q for quiet mode

inkos review list/approve-all

Manage chapter approvals

Quality gate

inkos fanfic init

Create fanfic from source material

--from <file>, --mode canon/au/ooc/cp

inkos genre list

List all available genres

Shows English and Chinese genres with default language

inkos genre create <id>

Create custom genre profile

--name, --numerical, --power, --era

inkos genre copy <id>

Copy built-in genre to project

For customization

inkos write rewrite <book> <ch>

Rewrite a specific chapter

Deletes chapter and later, rewrites from that point

inkos book update [book-id]

Update book settings

--chapter-words, --target-chapters, --status, --lang

inkos book delete <book-id>

Delete book and all chapters

--force to skip confirmation

inkos plan chapter [book-id]

Generate chapter intent

Preview what next chapter will do before writing

inkos compose chapter [book-id]

Generate runtime artifacts

Context, rule-stack, trace for next chapter

inkos consolidate [book-id]

Consolidate chapter summaries

Reduces context for long books (volume-level summaries)

inkos eval [book-id]

Quality evaluation report

--json, --chapters <range>. Composite quality score

inkos studio

Start web workbench

-p for port. Local web UI for book management

inkos fanfic show [book-id]

Display parsed fanfic canon

Shows imported source material analysis

inkos fanfic refresh [book-id]

Re-import and regenerate fanfic canon

--from <file> for updated source material

inkos interact

Shared interaction endpoint

--json, --message, --book. Primary entry for OpenClaw

inkos (no args)

Launch TUI dashboard

Full-screen Ink + React interactive dashboard

Error Handling

Common Issues

"book-id not found"

Verify the ID with inkos book list

Ensure you're in the correct project directory

"Provider not configured"

Run inkos config set-global with valid credentials

Check API key and base URL with inkos doctor

"Context invalid"

Ensure --context is a string (wrap in quotes if multi-word)

Context can be in English or Chinese

"Audit failed"

Check chapter for encoding issues

Ensure chapter-words matches actual word count

Try inkos revise with --mode rewrite

"Book already has chapters" (import)

Use --resume-from <n> to append to existing chapters

Or delete existing chapters first

Running Daemon Mode

For long-running operations:

# Start background daemon

inkos up

# Stop daemon

inkos down

# Daemon auto-processes queued chapters

Tips for Best Results

Provide rich context: The more guidance in --context, the more coherent the narrative

Start with style: If imitating an author, run inkos style import before generation

Import first: For existing novels, use inkos import chapters to bootstrap truth files before continuing

Review regularly: Use inkos review to catch issues early

Monitor audits: Check inkos audit metrics to understand quality bottlenecks

Use spinoffs strategically: Import canon before writing prequels/sequels

Batch generation: Generate multiple chapters together (better continuity)

Check analytics: Use inkos analytics to track quality trends over time

Export frequently: Keep backups with inkos export

Security & Trust

License: the ClawHub skill descriptor is MIT-0 per platform policy, but the underlying @actalk/inkos, @actalk/inkos-core, and @actalk/inkos-studio npm packages are AGPL-3.0-only. Running InkOS and distributing modified versions are governed by AGPL. Full source on GitHub for auditability.

No install hooks: npm package has no preinstall/postinstall/install scripts. Install is inert.

Local-only file I/O: all read/write stays inside the project directory (books/*, inkos.json, inkos.log). No writes outside the working directory.

No telemetry: InkOS does not phone home, collect usage stats, or ship any data to InkOS-controlled servers. The only outbound traffic is to the LLM provider endpoint you explicitly configure.

Credential handling: always prefer --api-key-env <VAR_NAME> over --api-key <literal> so keys never hit shell history. Keys are stored in inkos.json under your project directory — treat it like a secret and add it to .gitignore if you commit the project.

Custom provider base-URL: --provider custom forwards your API key to whatever URL you specify. Only point it at endpoints you trust (your own proxy or an audited reverse-proxy). Never paste an untrusted --base-url.

No elevated privileges: InkOS requires no sudo, no global state mutation, no network listening port (Studio binds localhost:4567 only).

Support & Resources

Homepage: https://github.com/Narcooo/inkos

Configuration: Stored in project root after inkos init

Truth files: Located in books/<id>/story/ per book, with structured JSON in story/state/

Logs: Check output of inkos doctor for troubleshooting

inkos