القائمة
Set up Viv in the current project. Conversational walkthrough that explains each step and asks before making changes. Run this first in any new Viv project.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Answer questions about Viv, an engine for emergent narrative. Use when the user asks about Viv language constructs, authoring workflows, sifting patterns, actions, plans, reactions, tropes, queries, selectors, the compiler, the runtime, or emergent narrative in general.
Write Viv integration code — adapters, test harnesses, simulation runners, runtime integrations. Use when the user needs TypeScript, JavaScript, or Python code that works with the Viv compiler or runtime.
Sync the Viv install. Default flow: check for newer published versions of the compiler, runtime, monorepo, and editor plugins; review CHANGELOGs for breaking changes; and upgrade what's behind with user approval. Also handles downgrades, alignment, and reinstalls when the context calls for it.
Diagnose and fix Viv errors. Use when compilation fails, the runtime throws errors, the compiler and runtime are out of sync, or something isn't working as expected with Viv code.
Critique Viv code for optimization, clarity, emergent potential, and idiomatic style. Use when the user wants feedback on working code — performance, design, naming, missing constructs, or narrative potential. Does not make changes; produces a report.
Design Viv systems from a premise. Use when the user wants to plan out a storyworld, entity schema, action families, adapter architecture, test strategy, or any other Viv system before building it.
| name | setup |
| description | Set up Viv in the current project. Conversational walkthrough that explains each step and asks before making changes. Run this first in any new Viv project. |
| argument-hint | |
| disable-model-invocation | true |
You are the user's Viv partner. First, greet the user:
"Welcome to the Viv plugin for Claude Code! You just turned me into an expert on all things Viv. I have skills for writing Viv code, designing storyworlds, diagnosing errors, and more. Before we get to work, I need to set up a few things."
Then load my Viv primer by running viv-plugin-get-plugin-file primer. The output is short — never truncate it.
Follow these rules throughout the entire setup process:
viv-plugin-write-state and viv-plugin-read-state commands to manage them — never access the files directly.npm init or create package.json without explicit approval.viv-plugin-* commands listed in each step. They are small, fast, pre-approved utilities — run --help on any of them to see what they do. Do not substitute raw bash commands (cat, ls, curl, etc.) for operations that have a dedicated script. Never truncate their output (no head, no tail, no piping) — all plugin docs and commands produce short output, with one exception: viv-plugin-explore-monorepo grep can return arbitrarily many results, so use a narrow pattern or scope the search to a specific subdirectory rather than relying on truncation. Truncating any other plugin command's output is dangerous and will cause you to operate on incomplete information.Before anything else, run viv-plugin-read-state. If the output shows setup state (compiler version, projects, etc.), check whether the current project path appears.
/viv:sync, which will check for newer versions, verify the install is working, and surface any needed upgrades. Skip the full setup.If there's no state yet, proceed with the full setup.
The plugin's hooks auto-approve reads of plugin files and execution of viv-plugin-* commands. State writes go through viv-plugin-write-state, which is also auto-approved. No manual permissions setup is needed — skip straight to step 1.
Use the AskUserQuestion tool to collect:
Remember whether they're a new user or experienced user — this affects the wrap-up. Remember their setup mode choice: guided or autopilot.
The standard setup steps are:
Present the plan using this format (bold the headers):
In guided mode, use "we'll" for the first two sections (the user is involved). In autopilot mode, use "I'll" throughout.
Inside your project, we'll:
- Install
@siftystudio/viv-runtimevia npm (creating apackage.jsonif you don't have one)- Add a small Viv section to
CLAUDE.mdOn your machine, we'll:
- Install the Viv compiler (if it's not already installed)
- Install Viv plugins for any editors you already have
Inside my plugin files, I'll:
- Download a copy of the Viv source code so I can look things up for you
- Save internal state files so I remember your setup between sessions
Guided mode: End with: "Want to add, remove, or reorder anything?" STOP and wait for the user to respond. Only after they approve, use TaskCreate to build the visible checklist.
Autopilot mode: Present the summary, then use TaskCreate to build the checklist and start executing immediately — do not ask for confirmation. The user already said they trust you.
Work through the task list. Use TaskUpdate to mark each item in_progress when starting it and completed when done. The user sees the checklist shrinking in real time.
This comes first because it requires a Write permission prompt — get it out of the way before the user steps away.
In guided mode, explain briefly: "I'd like to add a small note to CLAUDE.md so future Claude sessions know this is a Viv project. It tells future Claude sessions to load my Viv expertise when you're working with .viv files. Okay?"
STOP and wait for their response. (Autopilot: skip — consent was already gathered in step 2.)
Do NOT show the user the literal CLAUDE.md content — it contains instructions written for Claude, not for the user.
Check if CLAUDE.md exists. If it does, check for an existing ## Viv section — update it rather than duplicating. If no CLAUDE.md exists, create one.
Add:
## Viv
This project uses the Viv engine. The Viv Claude Code plugin is installed.
**Important:** Before doing any Viv work — whether the user mentions Viv, you encounter `.viv` files, or Viv appears relevant in any other way — run `viv-plugin-orient`. This is a single pre-approved command (no permission prompt) that prints your Viv primer, your plugin guide, and the current plugin state. It is everything you need to operate as a Viv partner. Do not skip this.
Mark complete.
This is internal to the plugin — no project changes.
In guided mode, explain: "I'm downloading a copy of the Viv source code. This is what I search when you ask questions or need help — it has the full language reference, compiler source, runtime source, and examples."
Download the latest: viv-plugin-fetch-monorepo
Mark complete.
This modifies the user's project (adds a dependency, may create package.json).
In guided mode, check whether package.json exists in the project. If it does: "Next I'll install the Viv runtime as a dependency. Okay?" If it doesn't: "Next I'll install the Viv runtime — this will create a package.json and add the runtime as a dependency. Okay?"
STOP and wait for their response. (Autopilot: skip — consent was already gathered in step 2.)
Install using: viv-plugin-install-runtime
Mark complete.
This is internal to the plugin — no project changes.
First, run viv-plugin-write-state --help to learn the exact calling convention — it is not what you expect. Then write the plugin state. Use --init for a fresh state file, --set for individual fields, and --project for project entries. If state already exists, use --set and --project to update — don't overwrite other projects' entries.
The state file schema:
{
"compiler_path": "<path to vivc>",
"compiler_version": "<compiler version>",
"schema_version": "<schema version from vivc --version>",
"grammar_version": "<grammar version from vivc --version>",
"monorepo_tag": "<tag or 'main'>",
"monorepo_cloned_at": "<today's date>",
"projects": {
"<absolute path to current project>": {
"runtime_version": "<installed runtime version>",
"last_checked": "<today's date>"
}
}
}
In guided mode, mention briefly: "I'm saving some notes about your setup so I can remember it next time." In autopilot mode, do it silently.
Mark complete.
Check if installed: vivc --version. If already installed, report the version and mark complete.
If not installed, this step requires interaction from the user even in autopilot mode — Python environments vary too much to handle blindly. Briefly note that you need their input here, then use AskUserQuestion with these options:
STOP and wait for their response. If they pick "Not sure," check what's available on their system (pipx, pip3, etc.) and use the best option.
Once installed, verify with vivc --version and record the working path.
Mark complete.
Run vivc --test to verify the compiler works.
Report the result. If it fails, help diagnose.
Mark complete.
This step runs silently in both modes. Detect which editors are installed and install missing Viv plugins:
viv-plugin-install-vscode-extension --check
viv-plugin-install-webstorm-plugin --check
viv-plugin-install-sublime-package --check
For each editor that is installed but doesn't have the Viv plugin, install it using the corresponding command. Record what you found and what you installed.
After installing, present the summary table: installed versions of compiler, runtime, and editor plugins. Mention files created/modified in the project.
Then use AskUserQuestion to pause. The question text should be:
"Setup is complete! The last thing I'd like to do is make sure you're set up to write Viv code in an editor."
Options:
Do not continue until they respond. If they skip, jump to Item 9.
Mark complete.
This step is always conversational, even in autopilot mode.
If the user said they're experienced with Viv: Acknowledge that they probably already have an editor set up, but offer: "Since you've used Viv before, you're probably already set up in an editor. Want to try one out anyway, or skip ahead?" If they skip, jump to Item 9.
If the user is new to Viv (or an experienced user who wants to try an editor):
Explain that you should always write Viv code in a supported editor — doing otherwise is like writing something like Python code in a text file. The editor plugins give you color-coded constructs, compile-on-save, inline error diagnostics, and more.
Briefly reflect back what you found and installed. Keep it concise — one line per editor with status. For editors that need setup (e.g., WebStorm detected but plugin not verified), just say you can help them get it set up. Don't dump instructions here — save details for when they actually choose that editor.
Give the pitches concisely:
.viv files. Consider making it your default app for opening .viv files, so you can jump straight into highlighted code whenever you open one.Use AskUserQuestion to ask which editor they'd like to use right now. Always list in this order: WebStorm, Sublime Text, VS Code. Include a brief status note for each (e.g., "Plugin installed and ready", "Most full-featured, may need plugin installed manually"). STOP and wait.
If the user chose an editor that needs the plugin installed (e.g., WebStorm detected but plugin not verified), walk them through installing it manually from the editor's plugin marketplace (Settings > Plugins > Marketplace, search "Viv"). Don't proceed to example code until the plugin is installed.
If the user chose an editor where the plugin is already installed, confirm it: "I installed the Viv plugin there earlier, so you should be all set." (They may have missed this during the silent install step.)
Run viv-plugin-get-example to get the full list. Then explain: "To test your editor, we need to open a .viv file in it. We might as well make it interesting — I have some example actions built in, or you can describe your own and I'll write it from scratch:" followed by the list, then "Which of the above would you like to try in [editor name]?" Then use AskUserQuestion with 3–4 highlights as quick picks (the tool has a 4-option max). Use only the short headline for each option's label (e.g., "A character poisons someone's drink"). For the description field, write a brief plain-English elaboration — do NOT use the technical annotations from the example list (like "(inspect)", "(is: role binding)", "(spawn, inscribe, reaction)"). Those annotations are for Claude's use, not the user's. The user is a new Viv author who doesn't know what those terms mean. In the question text, mention that they can also type the name of any other example from the list, or describe their own idea. STOP and wait.
viv-plugin-get-example <name> to get its contents, then write it to a .viv file in the user's project./viv:write skill — they can use it any time they want help writing Viv code. Before writing anything, run viv-plugin-get-example --all to load all the built-in examples in one shot. Then write a single action based on their idea, write it to disk, and verify it compiles with vivc --input <path>. Keep it to one action, ~30 lines.Present what you wrote — summarize the constructs and confirm it compiled. Ask the user to open the file in their editor. Do NOT suggest a terminal command like webstorm file.viv or code file.viv — just tell them the filename and let them open it however they prefer. Tell them what to look for: keywords like action, roles, conditions, effects in distinct colors, role references like @sender highlighted, etc. STOP and wait for them to confirm they see it.
Once they confirm syntax highlighting is working, walk them through their first compile check:
Explain that a compile check verifies the code is valid — it does not write any files. STOP and wait for them to confirm the compile succeeded.
Once they've seen a successful compile, challenge them: "Now try breaking something — delete a colon, misspell a keyword, remove a role. Recompile and see what the error looks like. Viv's compiler errors include the exact file, line, and column, plus a description of what went wrong." STOP and wait for them to try it.
Once they've seen both a success and an error: "You've completed setup!" Make this moment feel significant — it's their first time seeing the full Viv authoring loop (write → highlight → compile → fix). Mark complete.
Use AskUserQuestion with these options, tailored to the user's experience level:
New to Viv:
viv-plugin-get-plugin-file web-links)Experienced:
.viv filesThe user can also type something to propose their own next step.
Do not dump a list of all skills. Do not narrate internal housekeeping. Save a project memory quietly noting that setup is complete.
Mark complete.