SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsstory-setup

story-setup

Writing & research

View repository

Updated 10-16 10:46

About this skill

story-setup: Web fiction writing toolset infrastructure deployment

You are the writing infrastructure deployer. Deploy the web fiction writing toolset 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 describes 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

  • The parameter is check, or the user only asks to check the deployment, diagnose the environment, or troubleshoot an unavailable agent: 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 inspection follow the deployment and merge rules of this file and the host deployment files.

Phase 1: Determine the 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 (the host deployment steps, Claude/Codex/Antigravity hooks merging, Antigravity Skills materialization and agent generation, and recursive copy safety checks depend on them). If any are missing, the skill package was not fully installed,stop immediately, do not write any deployment files, and in the report distinguish between "missing directory", "empty directory", and "missing script or deployment file", and give the repair instruction: "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/, do not contain SKILL.md, will not be the execution directory, and should not be used for verification. The project copies of Antigravity / ZCode / OpenClaw / Reasonix / generic are full skill copies and come with SKILL.md, so the 9 subdirectories are complete by nature; verify them as usual.

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

    • agents_version missing, non-integer, or less than 34 → mark as pending update, continue executing the current deployment
    • agents_version: 34 → use AskUserQuestion to confirm whether to redeploy; in the prompt state 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 is greater than 34 → the current story-setup is older than the project deployment; stop to avoid a downgrade overwrite, 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), redeploy those targets 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) → use AskUserQuestion to ask "This folder was previously set up for {deployed host name}, but you are now using {current host name}. Do you want to install it for that too?" ("Install for that too (recommended)", "Only update the original"), and 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 run. When the user explicitly requests adding or removing target hosts, 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 contains .opencode/plugins/story-hooks.ts or .opencode/agents/(during multi-target deployment, OpenCode was previously 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 the 追踪/ subdirectory, or a user-defined structure)

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

  3. Check whether the .active-book file exists: exists → display the currently active book title; 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 settled:

    • 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 's Codex section → target_cli = codex
    • .agents/hooks.json、.agents/agents/, or .agents/rules/oh-story.md 's Antigravity marker → target_cli = antigravity
    • .zcode/、.zcode/config.json、zcode.json、.zcode/skills/、.zcode/commands/、AGENTS.md 's ZCode section → target_cli = zcode
    • openclaw.json、.openclaw/, or AGENTS.md 's OpenClaw section (the heading line contains 网文写作工具集（OpenClaw））→ target_cli = openclaw
    • .reasonix/、reasonix-plugin.json、REASONIX.md, or AGENTS.md 's Reasonix section (the heading line contains 网文写作工具集（Reasonix））→ target_cli = reasonix
    • AGENTS.md 's generic section (the heading line contains 网文写作工具集（通用 Agent / Web AI））→ target_cli = generic

    The latter three types only recognize each target'smutually exclusivemarkers:skills/*/SKILL.md 's metadata.openclaw is not treated as an OpenClaw signal (all 13 skills carry it, and the skills/ deployed by the three skills-only paths are the same);.agents/skills/ is shared by Antigravity, Codex, and Reasonix, so it is not treated as authoritative on its own either.

  6. Once target_cli：

    • Step 4 determined the current host → target_cli That's it. When the project has markers for other hosts, use AskUserQuestion to ask in plain language: "This folder previously had writing tools installed for {other host name} too — should they be updated together this time?" Options: "Only install {current host name} (recommended)" and "Update together". If the author said at the start that multiple are needed, follow that.
    • Cannot determine, and the project markers correspond to exactly one host → AskUserQuestion asks "Last time it was installed for {host name} — is it still that one this time?", if yes use it, if not ask per the next item.
    • Cannot determine, other cases → Use AskUserQuestion to ask: "Which software are you talking to me in right now?" The options use product names plus a short explanation: Claude Code (Anthropic's CLI / desktop app), 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 under "Other".
    • The author's answer is mapped as follows: "Claude Code → claude-code, Web-based AI or other tools → generic, the rest take the lowercase product name" to target_cli; multiple ends is the end selected among 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 is the installation/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 all 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 consistent results when executed repeatedly. If it fails midway for environmental reasons (tool unavailable, permission denied, network failure), just rerun this Phase from the start; there is no need to clean up half-finished work first;create only if absent 's user state file (see the Owner class in each deployment checklist) will not be overwritten a second time.

The two columns have different base directories: in the deployment checklist, Source path is relative to this skill package being executed,Target path is relative to the user's project root. Before executing each line (and each recursive copy step in each host's deployment algorithm), first concretize the wildcards into a single source/target, then use this SKILL.md 's sibling scripts/copy-path-safety.py to check. This script follows existing symlinks by Path.resolve / realpath semantics, and when both sides exist uses samefile to verify the filesystem object;merely converting to an absolute path or comparing strings does not count as completing the check. Read its JSON:status: same is a no-op, copying is forbidden; only copy_allowed: true allows copying;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 copies of the skill, and on rerun what is executed is the copy in the project; Reasonix / Codex may also load via .agents/skills → ../skills symlink, where different path text may still point to the same directory, and a literal copy would nest the directory inside itself and fill up the disk.

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

Step 1: Deploy by host

For target_cli each host infully readthe corresponding deployment file, and execute in order according to the deployment checklist (mechanically verifiable) and algorithm within it; do not read the files of other hosts.

target_cli Deployment file
claude-code references/deploy-claude-code.md
opencode references/deploy-opencode.md(first pass the "deployment prerequisites" version gate within it)
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

For multi-endpoint deployment, several hosts share root AGENTS.md, merge into one according to the "AGENTS.md merge strategy" below; when one endpoint is blocked by its own prerequisites (such as 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, hooks read with 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 the additional markers required by the "deployment marker supplement" in the host deployment file (such as the Claude Code restart confirmation marker)
  • If .story-deployed already exists but agents_version is missing, non-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

Check-only mode reuses items 1–2, skips item 3, and among them, sub-items requiring actual hook execution or fixture writing are changed to static validation only (file exists, syntax valid, registration items complete), without running hooks that would write to the project, and without creating deployment markers.

  1. For target_cli each host in , execute the "Verify" section of its deployment file.
  2. Verify 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 installation report. The reader is an author who does not understand programming; write in this order:
    • First write "What you can do now": use book-writing language to 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, review is done by me alone, with no division-of-labor assistant").
    • Then write "What you still need to do": item by item and actionable, such as "open a new session", "in Codex open /hooks and trust the oh-story entries", "install Node first"; if none, write "no other action needed". These two sections must not contain script names, field names, status names, or file paths; the content required by "installation report must prompt" in each host deployment file should first be translated into these two sections.
    • Finally, a brief "Deployment details": which folder it is installed in, deployed files, merged configuration, 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 Come," "Hidden 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 an AGENTS.md, merge by marker/section:

  1. Prioritize recognizing the story-setup management block marker (if an old project already has the marker, replace only 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 ## heading
  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 present in the template but absent from 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; distinguish tool-specific explanations as subsections to avoid overwriting each other

Redeploy

  • .story-deployed does not exist → fresh installation, all of Phase 2 is executed
  • .story-deployed exists and agents_version: 34 → prompt that it is already deployed, and AskUserQuestion to confirm whether to redeploy; state in the prompt that redeployment only uses the current local skill package to refresh project files, and that 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, while 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 manifest, algorithm, verification, and installation report prompts; per Phase 2 Step 1 read only the target host's file
references/diagnostics.md Check-only mode
UPGRADING.md Key upgrade points for each version

Process linkage

Pipeline: deployment Location: initialization (earliest)

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
Requires browser login state (ranking scan/deconstruction to fetch the original text) browser-cdp /browser-cdp; generic requires the platform to allow local scripts/browser control

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