English | 中文

oh-story-claudecode

A web novel writing skill pack for Claude Code, OpenCode, OpenClaw, Codex CLI, and workbuddy. Covers the full pipeline for long-form and short-form Chinese web novels: trend scanning, deconstruction, writing, AI tone removal, and cover generation.

Core Approach

Tropes = deterministic emotional payoff

Professional authors follow a three-step method:

1. Scan — analyze trending charts, identify genres, characters, and entry points.
2. Deconstruct — break down pacing and plot materials, build a personal module library.
3. Commercialize — learn and apply hooks, payoff density, expectation management.

Built around four pillars: reverse-engineering hits · plot modularization · layered state management · human-AI collaboration.

Starting in v0.6.21: short-form writing reference cleanup — story-short-write drops stale long-form inherited references and now uses short-format / short-craft / short-deslop plus four genre packs (wife-chasing crematorium, revenge face-slap, CEO/wealthy family, domestic/palace intrigue) for short-story format, direct emotion, pacing density, and AI-tone cleanup; existing deployed projects should rerun /story-setup and start a new session to pick up the updated narrative-writer short-story exception.

Starting in v0.6.20: long-form outline reinforcement — benchmark rhythm transfer (reflow a hit book's deconstructed pacing into your volume outline by normalized key points, with a chapter-summary fallback when the rhythm file is absent) and chapter positioning & tension-pacing (fixing "every chapter reads like a standalone short story": chapters are typed by their position in the unit-arc, so relationship/breathing/transition chapters no longer have to manufacture a hook and a payoff while still keeping read-through pull, with a "no emotional-motif clustering" guardrail; positioning is optional and non-quota).

Starting in v0.6.19: Codex CLI support (.agents/skills repo discovery plus $story-setup deployment of .codex/agents/*.toml and .codex/hooks.json) and OpenClaw compatibility; custom style 设定/文风.md takes priority over benchmarks; a deterministic post-write backstop (truncation / repetition / engineering-term / sentence-stutter detection); OpenCode subagents auto-assigned cost-tiered models to cut spend; and chapter outlines budgeted by word count to end the under-length rewrite loop.

Starting in v0.6.18, the toolkit fully supports the OpenCode CLI (auto-discovered agents, command and hook adapters) and ships a built-in update reminder; serialized writing adds per-chapter dialogue-voice and style-drift self-checks, and cover generation crop-fills to each platform's exact size (e.g. 番茄 600×800).

Pipeline Overview

flowchart LR
    classDef entry fill:#f0f0f0,color:#333,stroke:#999,stroke-width:1px
    classDef phase fill:#e8f4fd,color:#1a1a2e,stroke:#4a9be8,stroke-width:1px
    classDef final fill:#fce4ec,color:#333,stroke:#e57373,stroke-width:1px

    entry_l{{"Long-form Author"}}:::entry
    entry_s{{"Short-form Author"}}:::entry
    entry_r{{"Has an Idea"}}:::entry
    entry_i{{"Existing Novel"}}:::entry

    subgraph S0 ["  Setup"]
        setup["/story-setup"]:::phase
    end

    subgraph S1 ["  Trend Scanning"]
        direction TB
        scan_l["Long-form Scan"]:::phase
        scan_s["Short-form Scan"]:::phase
    end

    subgraph S2 ["  Deconstruction"]
        direction TB
        analyze_l["Long-form Deconstruction"]:::phase
        analyze_s["Short-form Deconstruction"]:::phase
    end

    subgraph S3 ["  Writing"]
        direction TB
        write_l["Long-form Write"]:::phase
        write_s["Short-form Write"]:::phase
    end

    subgraph S4 ["  Polish"]
        deslop["De-AI-ify"]:::final
    end

    entry_l --> setup
    entry_s --> setup
    setup --> scan_l
    setup --> scan_s
    scan_l --> analyze_l
    scan_s --> analyze_s
    analyze_l --> write_l
    analyze_s --> write_s
    entry_r -.->|Skip Prep| write_l
    entry_r -.->|Skip Prep| write_s
    entry_i -.->|Import Existing| setup
    setup -.->|Reverse Import| write_l
    write_l --> deslop
    write_s --> deslop

Installation

Option 1 Tell Claude Code / OpenCode / OpenClaw / Codex directly:

Install this skill https://github.com/worldwonderer/oh-story-claudecode

Option 2 Command line:

npx skills add worldwonderer/oh-story-claudecode -y -g

-g installs globally (available in every directory); drop -g to install only into the current directory. Re-run the same command to update.

After updating, if a project has already run /story-setup, re-run /story-setup from the project root to sync hooks / agents / references. Per-version changes are in CHANGELOG.md and Releases.

Codex users: Use it in-place: Codex scans $REPO_ROOT/.agents/skills (a symlink to skills/) and discovers all 13 skills; invoke via $story, $story-setup, or /skills. On Windows, enable git core.symlinks=true or the symlink breaks — then use the $story-setup deployment below. After $story-setup deploys into a writing project, it creates .codex/agents/*.toml, .codex/hooks.json, .codex/hooks/story_codex_hook.py, and .codex/skills/story-setup/references/agent-references/. Trust the project .codex/ layer, review/trust hooks in /hooks, and open a fresh Codex session so custom agents load.

OpenCode users: After global install, opencode auto-discovers skills from ~/.claude/skills/; trigger story-setup with natural language on first use (e.g., "use story-setup to deploy the web novel environment"), then exit and re-enter with opencode -c for slash commands to work. Some hook behaviors differ from Claude Code (session-start / session-end / compact, etc.) — see the OpenCode section in CONTRIBUTING.md.

OpenClaw users: Current support is skills-only. OpenClaw can discover the 13 story skills from workspace skills/, .agents/skills, ~/.agents/skills, ~/.openclaw/skills, or configured extra skill roots. SKILL.md files use OpenClaw-compatible single-line name / description plus single-line JSON metadata.openclaw. When story-setup targets OpenClaw, it copies the skills into project skills/ and writes an OpenClaw AGENTS.md; agents/hooks are intentionally deferred, so outline-before-prose guards are soft skill checks rather than runtime enforcement. If new skills do not appear immediately, open a fresh OpenClaw session or wait for the skills watcher to refresh.

Multi-agent collaboration needs setup + a fresh session: the 7 specialist agents (story-architect, narrative-writer, consistency-checker, etc.) are written into your project's .claude/agents/ by /story-setup, or into .codex/agents/*.toml by $story-setup. Claude Code and Codex register custom agents most reliably at session start, so after setup finishes you must trust the project config and open a fresh matching CLI session before story-review's multi-perspective review and the agent collaboration in the writing flow take effect; otherwise skills get "subagent_type unavailable / Codex unknown agent_type" and fall back to solo (single perspective). OpenClaw Phase 1 does not deploy agents and defaults to skills + solo fallback. To check Claude/Codex agents: run /story-review in the new session — a header of Effective Mode: full/lean means agents registered, Fallback: ... -> solo means you're still in the old session or the current runtime did not expose that agent.

Skills

Natural language also triggers: 帮我开书 ("help me start writing") → story-long-write, 这篇太AI了 ("this is too AI-ish") → story-deslop, 把我的书导进来 ("import my book") → story-import, 沈栀现在什么状态 ("what's Shen Zhi's current status") → story-explorer.

Cover generation example

Deconstruction demo — Coiling Dragon

Full output from /story-long-analyze deep mode on the first 23 chapters of Coiling Dragon:

demo/拆文库-盘龙/
├── 概要.md              # Novel overview + chapter index
├── 拆文报告.md           # 5-dimension scoring + pacing analysis + takeaways
├── 文风.md              # Benchmark voice: sentence rhythm, punctuation, dialogue subtext, emotion pacing
├── 章节/
│   ├── 第1章_深度拆解.md  # Golden三章 deep analysis
│   └── 第1-23章_摘要.md   # Per-chapter summary + plot points + character mentions
├── 角色/
│   ├── 林雷.md           # Protagonist full profile
│   ├── 霍格.md           # Core supporting
│   ├── 希尔曼.md         # Core supporting
│   ├── 德林柯沃特.md      # Core supporting
│   ├── 沃顿.md           # Functional character
│   └── 角色关系.md        # Relationship network
├── 剧情/
│   ├── 故事线.md          # Framework + 4 plotlines + 2 storylines
│   ├── 节奏.md            # Pacing + key-info progression + emotional trigger eruption rhythm
│   └── 情绪模块.md        # Reader needs + emotional engine + reusable writing modules
└── 设定/
    ├── 世界观/
    │   ├── 背景设定.md    # Core rules + special settings
    │   ├── 力量体系.md    # Battle qi + magic + ranks
    │   ├── 地理.md        # Andaluxia + Yulan Continent
    │   └── 金手指.md      # Panlong Ring + Delin Cowort
    └── 势力/
        └── 巴鲁克家族.md  # Baluk family (dragon-blood lineage)

Long-form deconstruction also produces 文风.md, plus 剧情/节奏.md (pacing, key-info progression, emotional trigger eruption rhythm) and 剧情/情绪模块.md (reader needs, emotional engine, reusable writing modules); daily writing consumes these through 对标/{书名}/剧情/ to keep voice, pacing, and emotion modules close to the benchmark.

Deconstruction demo — Once I Hid My Love (曾将爱意私藏, short-form)

/story-short-analyze deconstructing the short story 《曾将爱意私藏》 (~8,500 chars, win-back / "faked-death" genre):

demo/拆文库-曾将爱意私藏/
├── 原文/原文.txt        # Source backup
├── 拆文报告.md          # Story core + 5-dim scores + 6-facet payoff + cognitive reversal + 9-layer resonance
├── 情节节点.md          # 54 plot points (source quotes + emotion markers −9~+9)
├── 写作手法.md          # POV / dialogue / info-gap / object-hook — 11 techniques
└── _meta.json           # structure_counts (Phase 7 gate basis)

Short-form deconstruction outputs 拆文报告 / 情节节点 / 写作手法; downstream /story-short-write writes a new same-genre story from them.

Import demo — 让你管账号，你高燃混剪炸全网 (long-form continuation project)

/story-import reverse-builds the author's already-published first 20 chapters (~37k chars) into a continuation-ready writing project, handed off to /story-long-write for daily writing from chapter 21:

demo/让你管账号，你高燃混剪炸全网/
├── 正文/        Chapters 001–020 (published source text)
├── 大纲/        大纲.md · 卷纲_第1卷.md · 细纲_第001–020章.md (one file per chapter)
├── 设定/        角色/ (6 character files) · 世界观/{background · cheat-system}
│                关系.md · 题材定位.md · 文风.md
├── 追踪/        伏笔.md (foreshadowing) · 时间线.md (timeline) · 角色状态.md (state) · 上下文.md
└── 参考资料/    作品信息.md

Per-chapter extraction (events / characters / settings / foreshadowing / timeline) is reverse-engineered into a continuation bible, so the author seamlessly continues from chapter 21.

Agent System

Writing skills internally coordinate 7 specialized agents: