SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsstory-setup

story-setup

Writing & research

View repository

Updated 10-16 09:30

About this skill

story-setup: Web fiction writing toolkit infrastructure deployment

You are the writing infrastructure deployer. Deploy the web fiction writing toolkit to the user's project directory: adapted CLIs use dedicated hooks/agents/config; environments such as NarraFork, Web AI, and custom Agents use the generic file mode.

Iron rule of execution: do not overwrite the user's existing configuration; merge rather than replace.

The order for the author's first deployment: determine the current host → confirm the project root → deploy per host → accept → tell the author the next step. This file only writes the process common to all hosts; each host's dedicated deployment checklist, algorithm, verification, and installation report prompts are in their respective deployment files,read only the one for this deployment's target host(see Phase 2).

Select mode

  • If the argument is check, or the user only asks to check the deployment, diagnose the environment, or troubleshoot when an agent is unavailable: fully read references/diagnostics.md, and follow its process to only check and report; do not enter the deployment process below.
  • When the user asks to install, update, or repair: execute the deployment process below. Repairs explicitly authorized after checking follow the deployment and merge rules of this file and the host deployment files.

Phase 1: Determine host and project

First self-check the reference directory: take the directory where the currently executing SKILL.md resides as the basis, list the subdirectories under the references/ at the same level as it, and verify whether all 9 names below are presentand all non-empty——agent-references、templates、opencode、codex、antigravity、zcode、openclaw、reasonix、generic; the same-level references/deploy-*.md(8 host deployment files),scripts/merge-claude-settings.py、scripts/merge-codex-hooks.py、scripts/merge-antigravity-hooks.py、scripts/generate-antigravity-agents.mjs、scripts/deploy-antigravity-skills.py and scripts/copy-path-safety.py must also exist (host deployment steps, Claude/Codex/Antigravity hooks merging, Antigravity Skills materialization and agent generation, and recursive copy safety checks depend on them). If anything is missing, the skill package was not fully installed,stop immediately, do not write any deployment file, and in the report distinguish between "missing directory", "directory is empty", and "missing script or deployment file", and give repair instructions: "The story-setup reference package is incomplete, missing {path}. Reinstall oh-story-claudecode according to your installation method (for command-line installs, rerun npx skills add zenstory-ai/oh-story-claudecode -y -g; for marketplace / Plugin Management installs, reinstall in the panel), then execute /story-setup."

The criterion is "is there a SKILL.md": only look at the SKILL.md at the same level as the currently executing references/. The in-project .claude/skills/story-setup/、.codex/skills/story-setup/ and OpenCode's skills/story-setup/ only have references/agent-references/and do not contain SKILL.md, so they will not be the execution directory, and you should not use them for verification either. The project copies of Antigravity / ZCode / OpenClaw / Reasonix / generic are full skill copies that come with SKILL.md, so the 9 subdirectories are already complete; verify as usual.

  1. Check whether the current directory has already been deployed (if .story-deployed）

    • agents_version is missing, not an integer, or less than 34 → mark as pending update, and continue executing the current deployment
    • agents_version: 34 → use AskUserQuestion to confirm whether to redeploy; in the prompt state clearly that redeployment only usesthe current local skill packageto refresh the project files; to get a new version of the skill itself, you must first update oh-story-claudecode (npx skills add or marketplace), then come back and rerun
    • agents_version greater than 34 → The current story-setup is older than the project deployment; stop to avoid overwriting with a downgrade, prompt to update oh-story-claudecode first, and do not write any deployment files
    • Also read the target_cli field.For deployed projects, the value in sentinel takes precedence: when non-empty (a comma-separated multi-target combination is kept as-is), these targets are redeployed as usual, without asking the author to choose again; Step 4 still determines the current host: if it is determined and is not among them (the author switched software) → AskUserQuestion asks "This folder was previously set up for {deployed host name}, and you are now using {current host name}. Do you want to install for this one too?" ("Install for this one too (recommended)", "Only update the original one"); if the former is chosen, add it to target_cli; if it cannot be determined, do not ask. Only when the field is missing or empty do steps 4-6 apply. When the user explicitly requests adding or removing target platforms, use AskUserQuestion to modify based on the existing values, and write the modified values back to sentinel.
    • target_cli does not include opencode, but the project has .opencode/plugins/story-hooks.ts or .opencode/agents/(during multi-target deployment, OpenCode was blocked by the version gate) → use AskUserQuestion to ask whether to add OpenCode back; if adding back is chosen, first pass references/deploy-opencode.md 's "deployment prerequisites", and after passing, write back to target_cli

  2. Check whether there is a book-title directory (a directory containing 追踪/ subdirectory, or a user-defined structure)

    • Yes → identify as a long-form project and display the current project information
    • No → identify as a new project or short-form project

  3. Check whether the .active-book file exists: exists → display the currently active book; does not exist → skip

  4. Determine the current host (if it can be determined, do not ask the author). Check them in order, and use the first one that can be decided:

    • Your own runtime environment: the system prompt, available tool names, or skill invocation syntax already indicate that you are running in Claude Code, Codex, OpenCode, Google Antigravity (including the command line agy), ZCode, OpenClaw, or Reasonix;
    • The installation location of the currently executing SKILL.md has a host-specific directory (such as .claude/、.codex/、.zcode/、.gemini/、.openclaw/、.opencode/）；
    • Cannot be determined (for example, a web-based AI, a self-built Agent, or the above signals contradict each other) → the project markers in Step 5 are only candidates, and Step 6 asks the author.

  5. See which host markers already exist in the project:

    • .claude/ or CLAUDE.md → target_cli = claude-code
    • opencode.json、opencode.jsonc or .opencode/ → target_cli = opencode
    • .codex/、.codex/config.toml、.codex/agents/、.codex/hooks.json、AGENTS.md → target_cli = codex
    • .agents/hooks.json、.agents/agents/, or .agents/rules/oh-story.md in target_cli = antigravity
    • .zcode/、.zcode/config.json、zcode.json、.zcode/skills/、.zcode/commands/、AGENTS.md → target_cli = zcode
    • openclaw.json、.openclaw/, or AGENTS.md (the title line contains 网文写作工具集（OpenClaw））→ target_cli = openclaw
    • .reasonix/、reasonix-plugin.json、REASONIX.md, or AGENTS.md (the title line contains 网文写作工具集（Reasonix））→ target_cli = reasonix
    • AGENTS.md (the title line contains 网文写作工具集（通用 Agent / Web AI））→ target_cli = generic

    The latter three categories only recognize each target'smutually exclusivemarkers:skills/*/SKILL.md 's metadata.openclaw is not used as an OpenClaw signal (all 13 skills have it; the skills/ deployed by the three skills-only paths is the same);.agents/skills/ is shared by Antigravity, Codex, and Reasonix, and does not independently serve as a criterion either.

  6. Decide target_cli：

    • Step 4 determined the current host → target_cli That's it. When the project contains markers for other hosts, use AskUserQuestion to ask in plain language: "This folder has previously had writing tools installed for {other host names} too — do you want to update those together this time?" Options: "Only install {current host name} (recommended)" and "Update together". If the author said at the start that they want to install multiple, follow that.
    • Cannot determine, and the project markers happen to have exactly one host → use AskUserQuestion to ask "Last time it was installed for {host name}; is it still that one this time?" If yes, use it; if not, ask according to the next item.
    • Cannot determine, other cases → use AskUserQuestion to ask: "Which software are you talking to me in right now?" For the options, use the product name plus a short description: Claude Code (Anthropic's CLI / desktop version), Codex (OpenAI's CLI), OpenCode, Google Antigravity (including the agy CLI), ZCode, OpenClaw, Reasonix (DeepSeek's CLI), web-based AI or other tools (NarraFork, self-built Agent, etc.), several of them. When the question tool cannot fit that many options at once, put the ones that appeared in the project markers first, and let the author write the remaining names directly in "Other".
    • Convert the author's answer according to "Claude Code → claude-code, web-based AI or other tools → generic, everything else to the lowercase product name" into target_cli; for multi-end, use the end selected from claude-code,opencode,codex,antigravity,zcode,openclaw,reasonix,generic .

  7. Confirm the project root (usually not asked): the project root is the current working directory. Only when the current directory is the user's home directory, a disk root directory, a system directory, or the install/source directory of this skill package itself, ask the author in plain language: "Which folder should the writing tools be installed in? Usually it's the folder where the manuscript is kept." In other cases, deploy directly and state where it was installed in the "Deployment details" of the installation report.

Phase 2: Deploy infrastructure

All of Phase 2 is idempotent: directory copying, file writing, and the merge algorithms in each host's deployment files produce the same result when run repeatedly. If it fails midway for environmental reasons (tool unavailable, permission denied, network failure), just rerun this Phase from the beginning; there is no need to clean up the half-finished work first;create only if absent 's user status file (see the Owner class in each deployment checklist) will not be overwritten a second time.

The base directories of the two columns are different: in the deployment checklist, Source path is relative to this skill package currently being executed,Target path is relative to the user's project root. Before executing each row (as well as each recursive copy step in each host's deployment algorithm), first instantiate the wildcards into a single source/target, then use the SKILL.md at the same level as this scripts/copy-path-safety.py to check. This script follows existing symlinks according to Path.resolve / realpath semantics, and when both sides exist uses samefile to verify the filesystem object;converting to an absolute path only or comparing strings does not count as completing the check. Read its JSON:status: same is a no-op, copying is forbidden; only when copy_allowed: true may you copy;source_missing、unsafe_target_within_source or filesystem_identity_error must stop that step and report. When the script cannot be run, you may only use the current environment's filesystem API to perform exactly the same canonical realpath, same-object, and target-descendant checks; if you cannot confirm, stop, and do not attempt to copy. The project copies of OpenClaw / Reasonix / generic are full skill copies; when rerun, what is executed is the copy in the project; Reasonix / Codex may also be loaded via .agents/skills → ../skills symlink, and different path text may also point to the same directory; copying literally would nest the directory inside itself and fill up the disk.

Clean up self-nesting residue before deployment：{.claude,.codex,.zcode}/skills/story-setup/references/agent-references/ and the project root skills/story-setup/references/agent-references/ if there are extra agent-references/ levels (possibly multiple nested levels), as well as skills/story-setup/skills/, delete the entire section before deploying, and list the deleted paths in the installation report.

Step 1: Deploy by host

For target_cli each host in,fully readthe corresponding deployment file, and execute in order according to its deployment checklist (mechanically checkable) and algorithm; do not read other hosts' files.

target_cli deployment file
claude-code references/deploy-claude-code.md
opencode references/deploy-opencode.md(first pass its "deployment prerequisites" version gate)
codex references/deploy-codex.md
antigravity references/deploy-antigravity.md
zcode references/deploy-zcode.md
openclaw references/deploy-openclaw.md
reasonix references/deploy-reasonix.md
generic references/deploy-generic.md

During multi-endpoint deployment, several hosts share the root AGENTS.md, merge into one copy according to the "AGENTS.md merge strategy" below; when one endpoint is blocked by its own prerequisites (such as the OpenCode version gate, Antigravity missing Node), handle it according to that endpoint's deployment file, and other endpoints deploy as usual.

Step 2: Create deployment marker

  • Create .story-deployed file (sentinel file)
  • write the following fields (YAML key: value format, read by hook using references/templates/hooks/lib/sentinel.sh ): 
    deployed_at: <date -u +"%Y-%m-%dT%H:%M:%SZ">
agents_version: 34
setup_skill_version: 1.3.2
target_cli: claude-code（或 opencode、codex、antigravity、zcode、openclaw、reasonix、generic，或其任意组合）
resolver_strategy: project-local-skill-reference
references_dir: .claude/skills/story-setup/references/agent-references（Codex 写 .codex/skills/...；Antigravity 写 .agents/skills/...；ZCode 写 .zcode/skills/...；OpenCode / OpenClaw / Reasonix / generic 写 skills/...；多端用逗号分隔）
  • This file is used by session-start.sh and the writing skill to detect deployment status and avoid repeated prompts
  • Also create any additional markers required by the "deployment marker supplement" in the host deployment file (such as Claude Code's restart confirmation marker)
  • If .story-deployed already exists but agents_version is missing, not an integer, or less than 34, update hooks/agents/rules/reference bundle according to this process (see UPGRADING.mdfor specific changes); if greater than 34 , it has already stopped in Phase 1 and must not be downgraded or overwritten

Phase 3: Verify installation

In check-only mode, reuse items 1–2, skip item 3, and among them, sub-items that require actually executing a hook or writing a fixture are changed to static validation only (files exist, syntax is valid, registration entries are complete); do not run hooks that would write to the project, and do not create a deployment marker.

  1. For target_cli each host in, execute the "Verification" section of its deployment file.
  2. Verify the deployment marker:
    • Check whether .story-deployed exists and contains a timestamp,agents_version: 34、setup_skill_version: 1.3.2、target_cli、resolver_strategy、references_dir
  3. Output the installation report. The reader is an author who does not understand programming; write in this order:
    • First write "What you can do now": in book-writing terms, list what is truly available after this deployment (such as "you can start a new book, continue writing: say /story-long-write", "you can break down a benchmark book"), and truthfully translate endpoint limitations (such as "in this tool, manuscript review is done by me alone, there is no division-of-labor assistant").
    • Then write "What you still need to do": each item should be actionable, such as "start a new session", "open /hooks in Codex and trust the oh-story entries", "install Node first"; if there is none, write "no further action needed". These two sections must not contain script names, field names, status names, or file paths; the content required to be prompted in the installation report by each host deployment file should first be translated into these two sections.
    • Finally, a brief "Deployment details": which folder it was installed in, deployed files, merged configurations, deleted residual paths, summary required by the host deployment file (such as OpenCode model configuration), and technical reasons, placed at the end of the report.

Template placeholders

Placeholder Replacement rule Example
{项目名} User project name or directory name "Sword Comes", "Dark Guard"
{书名} Book name directory name (consistent with the directory) Same as {项目名} , or user-defined
{目标平台} Target publishing platform Qidian, Fanqie, Jinjiang, Zhihu Yanyan
{作者名} User pen name or nickname Use "Author" when unspecified

Remove the curly braces when replacing. If the user does not specify a project name, use the current directory name. Unspecified placeholders are kept as-is and not replaced. The CLAUDE.md merge strategy is in the Claude Code deployment file.

AGENTS.md merge strategy (OpenCode / Codex / ZCode / OpenClaw / Reasonix / generic)

When the user already has AGENTS.md, merge by marker/section:

  1. Prefer to recognize the story-setup managed block marker (if an old project already has the marker, only replace the content inside the marker)
  2. When there is no marker, read the user's existing AGENTS.md and split it into a section map by ## headings
  3. OpenCode uses skills/story-setup/references/opencode/AGENTS.md.tmpl; Codex uses skills/story-setup/references/codex/AGENTS.md.tmpl; ZCode uses skills/story-setup/references/zcode/AGENTS.md.tmpl; OpenClaw uses skills/story-setup/references/openclaw/AGENTS.md.tmpl; Reasonix uses skills/story-setup/references/reasonix/AGENTS.md.tmpl; generic Web AI / other Agents use skills/story-setup/references/generic/AGENTS.md.tmpl
  4. The template's standard sections (Skill routing table, file structure, collaboration rules, collaborating with the author, restoring context after Compact; sections that exist in the template but not in the user's file are added directly) override sections with the same name; sections unique to the user are retained
  5. When deploying to multiple ends simultaneously, keep only one copy of the common paragraphs usable by Codex/OpenCode/ZCode/OpenClaw/Reasonix/generic together; tool-specific instructions are distinguished by subsections to avoid overwriting each other

Redeploy

  • .story-deployed does not exist → fresh install, all of Phase 2 is executed
  • .story-deployed exists and agents_version: 34 → prompt that it is already deployed, use AskUserQuestion to confirm whether to redeploy; in the prompt state that redeployment only uses the current local skill package to refresh project files, and updates to the skill itself go through npx skills add or the marketplace
  • .story-deployed exists but agents_version is missing, not an integer, or less than 34 → prompt that an update is needed, re-execute Phase 2 to overwrite the agents/hooks/rules/reference bundle, CLAUDE.md / AGENTS.md / settings.local.json / .codex/hooks.json / .agents/hooks.json / .zcode/config.json follow the merge strategy
  • .story-deployed exists and agents_version is greater than 34 → the current skill version is too old, stop and prompt to update oh-story-claudecode first; do not overwrite the newer deployment in the project

Reference materials

File Purpose
references/deploy-*.md 8 host deployment files: each one's deployment checklist, algorithm, validation, and installation report prompt; per Phase 2 Step 1, only read the one for the target host
references/diagnostics.md Check-only mode
UPGRADING.md Upgrade key points for each version

Process handoff

Pipeline: deployment Location: initialization (frontmost)

Timing Jump to Command
Deployment complete, start writing story-long-write / story-short-write /story-long-write or /story-short-write
Import an existing novel for deconstruction story-import /story-import
Needs a browser login session (ranking scan/deconstruct text to get the original text) browser-cdp /browser-cdp; generic requires the platform to allow local scripts/browser control

Invocation syntax for each end: Claude /名、Codex/ZCode $名, Antigravity via /skills browsing or direct naming, OpenClaw /skill 名, Reasonix / generic direct naming skill.