InkOS

Autonomous novel writing CLI agent - use for creative fiction writing, novel generation, style imitation, chapter continuation/import, EPUB export, and AIGC...

Security Scan

The skill appears to be a coherent CLI for novel generation, but the metadata omits that it will accept and persist LLM API keys and create configuration files, and the npm install step introduces moderate supply-chain risk.

Purpose & Capability

The name/description (autonomous novel-writing CLI) matches the instructions and the declared required binaries (node, inkos). However, the skill metadata declares no required env vars or config paths, while the SKILL.md shows explicit commands to set an LLM API key and create a project config (e.g., `inkos config set-global --api-key sk-xxx`, `inkos init`), which will persist secrets/config on disk. That omission is an inconsistency to be aware of.

Instruction Scope

The runtime instructions tell the agent to run local CLI commands that read/write project files, import local text directories, and create config/truth files — all expected for a writing CLI. The instructions do not tell the agent to access unrelated system paths or exfiltrate data to unexpected endpoints. Still, they do instruct storing LLM API keys in config and reading user files (e.g., novel.txt, ./chapters/), so the agent will have local filesystem access within the project.

Install Mechanism

Install is via npm (@actalk/inkos). This is the expected distribution mechanism for a Node CLI and is reasonable, but npm packages can run install scripts (postinstall) and introduce supply-chain risk. No direct downloads from untrusted URLs are used, which lowers the immediate risk compared with arbitrary archives, but you should inspect the published package and its install scripts before trusting it.

Credentials

Metadata lists no required environment variables or primary credential, yet SKILL.md explicitly demonstrates configuring LLM providers and an API key (OpenAI/Anthropic) and implies those credentials will be saved to project config. The skill will therefore handle sensitive credentials, but that is not declared in the metadata — a proportionality/visibility mismatch.

Persistence & Privilege

always is false (no forced inclusion). The skill creates and writes project configuration and truth files (normal for its purpose) and will persist API keys in its config if the user runs the shown commands. This is expected behavior, but users should be aware secrets may be written to disk by default.

What to consider before installing

This skill looks like a legitimate Node-based CLI for novel writing, but before installing or using it you should: 1) Inspect the npm package (@actalk/inkos) and its package.json (check for postinstall scripts and the published source) and review the GitHub repo linked as the homepage. 2) Be aware the tool will create project config and may persist LLM API keys (the README shows `inkos config set-global --api-key sk-xxx`), so avoid storing high-privilege keys you don't want on disk. Use limited-scope or dedicated API keys, environment-based secrets, or a proxy if possible. 3) Run the tool in a sandbox/container if you are unsure about supply-chain risk. 4) Verify where configs are stored (project dir vs. user home) and inspect those files after first-run. If you need stronger assurance, request the upstream source code or a reproducible build before granting any production LLM credentials.

InkOS - Autonomous Novel Writing Agent

InkOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a 5-agent pipeline (Radar → Architect → Writer → Auditor → Reviser) to generate, audit, and revise novel content with style consistency and quality control.

The Writer uses a two-phase architecture: Phase 1 (creative writing, temp 0.7) produces the chapter text, then Phase 2 (state settlement, temp 0.3) updates all truth files for long-term consistency.

When to Use InkOS

• Novel writing: Create and continue writing novels/books in Chinese web novel genres
• 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
• 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 compatible)
inkos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key sk-xxx --model gpt-4o

View System Status

# Check installation and configuration
inkos doctor

# View current config
inkos status

Common Workflows

Workflow 1: Create a New Novel

1. Initialize and create book:

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

   • Genres: xuanhuan (cultivation), xianxia (immortal), urban (city), horror, other
   • Returns a book-id for all subsequent operations

2. 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

3. Review and approve chapters:

   inkos review list book-id
   inkos review approve-all book-id
   

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

   inkos export book-id
   inkos export book-id --format epub
   

Workflow 2: Continue Writing Existing Novel

1. List your books:

   inkos book list
   

2. 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

3. Review and approve:

   inkos review approve-all
   

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.

1. 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+"

2. Import from a directory of separate chapter files:

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

   • Reads .md and .txt files in sorted order

3. Resume interrupted import:

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

4. 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

1. Analyze reference text:

   inkos style analyze reference_text.txt
   

   • Examines vocabulary, sentence structure, tone, pacing

2. 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

1. 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

2. 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:

1. Generate draft only:

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

2. 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

3. 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

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

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. During import chapters, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.

Two-Phase Writer Architecture

The Writer agent operates in two phases:

• Phase 1 (Creative): Generates the chapter text at temperature 0.7 for creative expression. Only outputs chapter title and content.
• Phase 2 (Settlement): Updates all truth files at temperature 0.3 for precise state tracking. Ensures world state, character arcs, and plot hooks stay consistent.

This separation allows creative freedom in writing while maintaining rigorous continuity tracking.

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 --name "my-genre" --rules "rule1,rule2,rule3"

Copy and Modify Existing Genre

inkos genre copy xuanhuan --name "dark-xuanhuan" --rules "darker tone, more violence"

Command Reference Summary

Command	Purpose	Notes
inkos init [name]	Initialize project	One-time setup
inkos book create	Create new book	Returns book-id
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 config set-global	Configure LLM provider	OpenAI/Anthropic/compatible
inkos doctor	Diagnose issues	Check installation
inkos update	Update to latest version	Self-update
inkos up/down	Daemon mode	Background processing
inkos review list/approve-all	Manage chapter approvals	Quality gate

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

1. Provide rich context: The more guidance in --context, the more coherent the narrative
2. Start with style: If imitating an author, run inkos style import before generation
3. Import first: For existing novels, use inkos import chapters to bootstrap truth files before continuing
4. Review regularly: Use inkos review to catch issues early
5. Monitor audits: Check inkos audit metrics to understand quality bottlenecks
6. Use spinoffs strategically: Import canon before writing prequels/sequels
7. Batch generation: Generate multiple chapters together (better continuity)
8. Check analytics: Use inkos analytics to track quality trends over time
9. Export frequently: Keep backups with inkos export

Support & Resources

• Homepage: https://github.com/Narcooo/inkos
• Configuration: Stored in project root after inkos init
• Truth files: Located in .inkos/ directory per book
• Logs: Check output of inkos doctor for troubleshooting