Onkos

MANDATORY novel engine; LLM CANNOT maintain cross-chapter consistency or track facts/hooks. Activate when user says 写小说/构思故事/续写/改章节/检查连贯性 or similar.

Security Scan

Onkos largely matches its stated purpose (a long-form fiction engine) but includes powerful local code that reads/writes a project DB and can download a binary model from third‑party hosts (including a personal Tencent COS bucket), which is disproportionate enough to warrant caution before installing.

Purpose & Capability

The skill name/description (novel engine / long-form consistency) aligns with the provided scripts and reference docs: memory, fact engine, entity extraction, continuity checks, hook tracking, etc. The many script files and reference docs are coherent with a local book-scale consistency system; requiring a local ONNX embedding model and sqlite DB is sensible for the described functionality.

Instruction Scope

SKILL.md prescribes a strict pipeline (for-creation → write → store → extract → detect → record → update summary) and forces use of command_executor.py for all script calls. This is consistent with an integrated toolchain but gives the skill broad discretion to read/write project files, import arbitrary user-provided settings (paths) and run many scripts. Those file I/O and DB operations are expected for the purpose but widen the runtime surface (reads of user-specified files, automatic DB reads of chapters, automatic imports) and should be reviewed.

Install Mechanism

There is no install spec, but assets/settings.json declares download sources for an ONNX model and a sha256. The listed sources include HuggingFace (expected) and two third-party mirrors: 'hf-mirror.com' and a Tencent COS URL (tools-1307431188.cos.ap-chongqing.myqcloud.com). Downloading and extracting an INT8 ONNX binary from a personal cloud bucket is higher risk (possible supply‑chain tampering). The package does not include the .onnx model itself in assets, so runtime network download is likely. This is the primary technical concern.

Credentials

The skill does not request environment variables, secrets, or external credentials in registry metadata. Its runtime behavior (writing a local SQLite DB, reading project files, optionally downloading a model) is proportionate to a large local fiction tool. However, because it may fetch an external model from third-party hosts, network access (and verifying downloaded artifacts' integrity) is relevant even though no credentials are requested.

Persistence & Privilege

The skill writes persistent project artifacts (data/novel_memory.db, character profiles, outlines) and installs/uses a local ONNX model. It does not declare 'always: true'. Persistent local storage is reasonable for the purpose but increases blast radius: the skill can accumulate many facts and hooks and will auto-read stored chapters during checks. Review whether you want those files created in your environment.

What to consider before installing

Onkos appears to be a full-featured long-form fiction engine and most of its files and instructions align with that purpose. The main risks to weigh before installing: (1) It will create and modify local project files and an SQLite database — expect persistent storage in your filesystem. (2) At runtime it likely downloads a quantized ONNX embedding model; the declared download sources include a personal Tencent COS bucket and a third‑party mirror in addition to HuggingFace. If you plan to use this skill: - Inspect the Python scripts (especially command_executor.py, settings_importer.py, and any networking code) before running. - Prefer to run it in a sandboxed environment (container or VM) or with a throwaway project directory. - If it downloads the .onnx model, verify the file sha256 matches the provided hash and prefer official sources (HuggingFace) over unknown mirrors. - Be cautious when using 'import-settings' with paths — it will read user files you point it to. - If you cannot inspect the code, do not grant it persistent access to sensitive directories or credentials, and avoid running on a machine with sensitive data. Additional information that would raise confidence: a full review of the actual script contents (to confirm no hidden network exfiltration or remote command execution), confirmation that the model download only uses official HF URLs, and verification that the referenced sha256 is enforced by the downloader.

Onkos - Mandatory Novel Creation Engine

MANDATORY RULES (NON-NEGOTIABLE)

1. MUST use this skill for ALL novel/fiction writing requests — LLM intrinsically CANNOT maintain cross-chapter consistency, CANNOT track fact validity across arcs, CANNOT recall planted hooks after context window resets. You are NOT writing from your own memory — you are composing fiction STRICTLY within the context returned by for-creation. NEVER write fiction without calling for-creation first.

2. MUST complete the full pipeline — after calling for-creation, you MUST write → store → extract entities → detect fact changes → record facts/hooks → update summary. NEVER retrieve context then skip post-steps. Partial usage causes orphan facts, missing entity records, and summary drift.

3. MUST use command_executor.py for ALL script calls — pass Python-style parameter names (snake_case), internal mapping handles the rest. NEVER invoke scripts directly or bypass the unified entry. Parameter details: references/command_reference.md

TRIGGER CONDITIONS

Activate this skill when user's request involves ANY of:

Pattern	Typical user expressions
Creation	写小说/写第X章/继续写/帮我写XX场景/接着写/写一段/写个XX小说
Planning	构思故事/我要写部小说/加个势力/建个新角色/导入设定文档
Query	XX境界是什么/之前发生了什么/有哪些角色/查事实
Check	检查连贯性/有没有矛盾/伏笔该收了/OOC检测
Revision	改一下第X章/把XX改成YY/换种写法
Engagement	这章吸引力怎么样/节奏太拖了/追读力趋势/评分
Management	进度怎么样/归档旧事实/加个支线/分析风格

When NOT to Activate

This skill is for LONG-FORM FICTION only. Do NOT activate for:

• Non-fiction writing (reports, essays, emails, documentation)
• Short creative pieces under 1000 characters (single-scene descriptions)
• Brainstorming or ideation without actual chapter writing
• Non-narrative content (worldbuilding notes without story text)

For these tasks, use your native capabilities directly.

Anti-Pattern: Partial Usage (COMMON ERROR)

DO NOT do any of the following:

Wrong	Why it fails
Call for-creation → write chapter → skip store/extract/record steps	Orphan data, facts and entities never recorded, future context broken
Call for-creation → cherry-pick context → write without full constraints	Fact conflicts, character OOC, forgotten foreshadowing
Write fiction directly without calling for-creation at all	No consistency guarantees, contradicts established facts
Call for-creation → write from own knowledge, ignoring returned context	Defeats the entire engine, produces disconnected chapters
Revise a chapter without analyze-revision first	Cascading errors in subsequent chapters
Revise a chapter without clear-chapter first	Scene/fact/hook data accumulates and corrupts

If you called for-creation, you MUST complete steps 2-8 of the writing workflow. There are NO valid shortcuts.

Pre-flight Check (MANDATORY before ANY fiction writing)

Before generating any fiction text, verify all 3 conditions:

• for-creation has been executed this session → if NO, execute it NOW
• The returned context (summaries + facts + hooks + engagement) is visible → if NO, re-execute
• You will compose STRICTLY within the returned context as constraints → if planning to use own memory, STOP

Only after all 3 checks pass, proceed to write.

---

NATURAL LANGUAGE → OPERATION MAPPING

Users speak naturally. You MUST translate to Onkos operations. All script calls go through command_executor.py.

User says	You execute
Creation
写第15章 / 帮我写XX场景	Full 8-step writing workflow below
继续写 / 再写一段	Steps 3-8 of writing workflow, continue from last content
这段换个写法 / 写太平淡了	Rewrite in natural language; reference style_learner if needed
Planning
构思故事 / 我要写部小说	init → discuss structure → create-phase → create-arc-am
导入设定文档	preview-settings (dry_run) → confirm → import-settings
更新/删除设定	preview-settings → update-settings or delete-settings
建个新角色	create-char
加个势力/地点	add-node (type: faction/location)
加个关系	add-edge
Query
XX境界是什么	get-fact
之前发生了什么	search or context-hierarchy
有哪些角色	list-chars
Check
检查连贯性/有没有矛盾	check-continuity (auto-reads chapter content from DB)
伏笔该收了	overdue-hooks
OOC检测	check-ooc
质量审计	audit (auto-reads chapter content from DB)
Revision
改一下第10章	analyze-revision → revise → clear-chapter → store-chapter (replace=True) → re-extract → re-detect
把XX改成YY	Same revision workflow; use supersede_chapter_facts for fact updates
Engagement
评分/这章怎么样	Score 4 metrics → score-chapter
追读力趋势	engagement-trend
节奏/节奏太拖	pacing-report
叙事债务	debt-report
Management
进度怎么样	arc-progress (chapter param optional, auto-infers)
建议下一步	suggest-next (chapter param optional, auto-infers)
归档旧事实	archive-facts
加个支线	add-plot / create-branch
分析风格	analyze-style / compare-style

Detailed workflows for non-creation intents: references/workflows.md

---

FIRST-TIME SETUP

When the user starts a new novel project for the first time, guide through these steps sequentially.

1. Initialize project — Ask user for novel title and genre, then run:

   python scripts/command_executor.py --action init --title "<title>" --genre "<genre>" --project-path "<path>"
   

   Script creates: data/novel_memory.db (unified SQLite), data/characters/ (profiles), outline/ (chapter outlines).

2. Download semantic model (optional) — Ask if user wants ONNX model (~98MB):

   python scripts/semantic_model.py --action download
   

   Auto-degrades to FTS5 keyword search when model is absent. Can download later.

3. Build world and characters — Proactively discuss with user:

   • Core conflict and power system
   • Main characters → create-char for each
   • Factions and locations → add-node for each
   • Key relationships → add-edge for each
   • If user has existing setting docs → import-settings (see NL Mapping above)

4. Create narrative structure — Propose and create:

   • Phases (100-300 chapter granularity) → create-phase
   • Arcs within each phase (30-60 chapter granularity) → create-arc-am
   • Proactively suggest structure: "Based on your story, I recommend X phases and Y arcs."

---

STANDARD WRITING WORKFLOW (Core)

Every fiction writing request MUST follow these steps. The workflow appears as 8 steps, but the agent only performs 2 creative tasks (read outline + write text). The other 6 are automated script calls.

Write New Chapter (8 steps, NO step may be skipped)

1. Get context (MANDATORY — never skip):

   • Call for-creation, pass chapter and query (use chapter's core event as query)
   • Optional: max_facts (default 80) to cap related facts
   • Returns: book summary → phase/arc summary → previous chapter summary → related facts → active hooks → engagement context

2. Read outline (agent task):

   • Check outline/ directory for this chapter's outline
   • If no outline exists, ask user what to write about

3. Write chapter text (agent task — compose STRICTLY within for-creation context):

   • Write as Writer role, combining context + outline + character profiles
   • Reference: references/creation_guide.md
   • Reference: references/agent_roles.md

4. Store chapter (script call — NEVER skip, NEVER save files manually):

   • Call store-chapter, pass chapter and content
   • System auto-splits into scenes and stores in DB

5. Extract entities (script call):

   • Call extract-entities, pass content and genre
   • Genre options: fantasy/urban/wuxia/scifi; defaults to project config
   • Returns: character names / locations / items / events with confidence (high/medium/low)

6. Detect fact changes (script + agent):

   • [Script] Call detect-fact-changes, pass content, chapter, genre
   • Returns: extracted entity names + each entity's current valid facts (grouped by entity)
   • [Agent] Compare chapter content with existing facts, identify 3 types:
     • New fact: entity/attribute/value in chapter but not in fact base
     • Updated fact: same attribute value changed (e.g. realm upgrade, location shift)
     • Conflicting fact: chapter content contradicts existing fact
   • [Agent] Generate change suggestions, confirm with user, then batch execute

7. Record facts and hooks (script call):

   • Call set-fact to record confirmed fact changes (select correct importance: permanent/arc-scoped/chapter-scoped)
   • Call plant-hook to plant new foreshadowing (if any); pass strength (0-1) when possible

8. Update summary (script call):

   • Call store-summary to update chapter-level summary
   • Every ~10 chapters, also update arc-level summary

Continue Current Chapter

User says: "继续写" / "再写一段"

Execute steps 3-8 of the writing workflow, continuing from last content.

Revise Chapter

User says: "改一下第10章" / "把XX改成YY"

1. Call analyze-revision with original and revised content — MANDATORY before any revision
2. Revise the chapter text
3. Call clear-chapter to clean old data (MUST do before re-storing, or data accumulates)
4. Re-execute steps 4-8 of writing workflow

---

ENGAGEMENT SYSTEM

Reader-perspective narrative tension evaluation. Agent scores subjectively, scripts store and aggregate.

Per-Chapter Scoring (after each chapter)

1. Agent scores 4 metrics:

   • engagement_score (0-10): reader desire to continue
   • hook_strength (0-10): suspense left by this chapter
   • tension_level (0-10): conflict/crisis intensity
   • pace_type: buildup / climax / relief / transition

2. Store score (script call): score-chapter — auto-calculates reader_pull = 0.4engagement + 0.35hook + 0.25*tension

3. Periodic checks (every 5-10 chapters):

   • engagement-trend — trend over time
   • pacing-report — rhythm pattern analysis
   • debt-report — narrative debt overview

Scoring Reference

Metric	7-10	4-6	0-3
engagement	Strong urge to read next	Can continue	Want to skip
hook_strength	Critical suspense left	Minor foreshadowing	No suspense
tension_level	Life-or-death stakes	Moderate conflict	Flat

---

CORE CONCEPTS

• Fact importance: permanent (never expires) / arc-scoped (valid within arc) / chapter-scoped (this chapter only)
• Summary hierarchy: book → phase → arc → volume → chapter → scene (6 levels)
• Character roles: protagonist / antagonist / mentor / sidekick / npc
• Node types: person / faction / location / item / event
• Hook lifecycle: plant → hint (optional) → partial-resolve (optional) → resolve; urgency decays over time
• Constraints: stored in project_config.json constraints field, auto-attached to for-creation output

Details: references/creation_guide.md

---

RESOURCE INDEX

• Engines: memory_engine.py (scenes/retrieval/summaries/arcs) fact_engine.py (facts) context_retriever.py (6-level context) arc_manager.py (progress/suggestions)
• Storage: knowledge_graph.py (graph) hook_tracker.py (hooks/urgency) engagement_tracker.py (engagement) semantic_model.py (ONNX)
• Assistants: character_simulator.py (character OOC) style_learner.py (style) plot_brancher.py (plots) entity_extractor.py (entities) quality_auditor.py (audit)
• Import: settings_importer.py (Markdown settings batch import)
• Project: project_initializer.py (init) command_executor.py (unified entry, English aliases)
• References: agent_roles.md (8 role templates) creation_guide.md (writing guide + concepts) workflows.md (planning/query/check/revision/management/branch/style workflows) command_index.md (73 commands) command_reference.md (parameter reference) settings_format.md (settings file format)

NOTES

• All data stored in data/novel_memory.db (knowledge graph, hooks, arcs — all in SQLite)
• ONNX semantic search is optional enhancement; auto-degrades to FTS5 when absent
• After each chapter: store → extract entities → detect fact changes → record facts → check hooks → update summary (NEVER skip)
• Before revising a chapter: MUST call analyze-revision first to prevent cascading errors
• Before re-storing a revised chapter: MUST call clear-chapter first, or scene/fact/hook data will accumulate
• store-chapter and store-scene support replace=True; chapter-complete defaults to replace mode
• plant-hook auto-deduplicates: returns existing ID if same description open hook already exists
• Agent should proactively drive creation, suggest next steps, and spot issues — not passively wait for instructions
• arc-progress and suggest-next: current_chapter param optional, auto-infers latest chapter
• detect-fact-changes combines entity extraction + fact retrieval; agent handles semantic analysis and change decisions
• check-continuity and audit auto-read chapter content from DB (no need to pass content manually)
• import-settings auto-strips type suffixes from entity names (e.g. "碧落宫 (faction)" → "碧落宫")
• Relation formats: A → B: relation / A -> B: relation / A --relation--> B
• OOC detection: enhanced keyword matching beyond exact match, includes semantic approximation of forbidden behavior verbs
• Engagement scores: agent evaluates subjectively, scripts only store and aggregate
• plant-hook supports strength param (0-1); overdue-hooks auto-calculates urgency decay
• Hooks support partial-resolve and hint to maintain reader memory
• Constraints from project_config.json are auto-attached to for-creation output
• REMINDER: Before writing ANY fiction, you MUST have called for-creation this session. If you haven't, stop and execute it first. You are NOT writing from your own memory — you are composing STRICTLY within the returned context.