SillyTavern Builder

A comprehensive Claude Code skill for developing SillyTavern frontend interfaces and background scripts using the Tavern Helper framework.

🎯 What is this?

This skill transforms Claude into an expert SillyTavern developer, providing:

• Complete tech stack knowledge (Vue 3, React, PixiJS, and 15+ utility libraries)
• Tavern Helper API mastery (TypeScript-safe alternatives to STScript)
• 264 STScript commands reference (slash commands for tavern operations)
• MVU variable framework expertise (message floor variable enhancement)
• Development best practices (webpack bundling, iframe constraints, live preview workflows)
• Quick-start templates (Tailwind, Vue components, reactive state management)

📦 Installation

For Claude Code Users

1. Clone this repository:

   git clone https://github.com/waylon256yhw/st-builder.git ~/.claude/skills/sillytavern-dev

2. Use the skill: Simply mention SillyTavern development tasks in your conversation, and Claude will automatically load this skill when relevant.

For Manual Reference

Browse the references/ folder for detailed documentation on specific topics.

🏗️ What Can You Build?

Frontend Interfaces (iframe with UI)

• Interactive status bars with animations and user interactions
• Complete game UIs that integrate with SillyTavern chat
• Custom character card visualizations
• MVU variable visualization dashboards
• Media players and multimedia experiences

Background Scripts (no UI)

• Auto-summarization every N messages
• Message reroll automation based on LLM analysis
• Custom jQuery enhancements to SillyTavern UI
• External service integrations (WebSocket, REST APIs)
• Event-driven workflows (time-based, chat-based triggers)

📚 Documentation Structure

sillytavern-dev/
├── SKILL.md                          # Main skill documentation (~5k words)
├── README.md                         # This file
├── assets/
│   └── tailwind.css                  # Quick-start Tailwind template
└── references/                       # Detailed documentation (loaded as needed)
    ├── api_reference.md              # Tavern Helper API (~10KB)
    ├── best_practices.md             # Do's and don'ts (~4KB)
    ├── mvu_framework.md              # MVU variable framework (~8.5KB)
    ├── stscript_commands.txt         # 264 STScript commands
    └── tech_stack.md                 # Complete dependency list (~6.5KB)

Progressive Disclosure Design

• Always loaded: Skill name and description (YAML frontmatter)
• On trigger: Main SKILL.md content
• As needed: Reference files and assets

🚀 Quick Start

Example 1: Create a Vue-based Status Bar

// src/status-bar/index.ts
import { ref, watchEffect } from 'vue';
import { klona } from 'klona';
import { getVariables, replaceVariables } from '@types/function/variables';

const state = ref({
  hp: 100,
  mp: 50,
  level: 1
});

// Sync with MVU variables
watchEffect(() => {
  replaceVariables(klona(state.value), {
    type: 'message',
    message_id: -1
  });
});

Example 2: Auto-Reroll Bad Messages

// src/auto-reroll/index.ts
import { eventOn, tavern_events } from '@types/function/event';
import { generate } from '@types/function/generate';

eventOn(tavern_events.MESSAGE_RECEIVED, async (message) => {
  const quality = await generate({
    prompt: `Rate this message quality 1-10: ${message.content}`,
    quietPrompt: true
  });

  if (parseInt(quality) < 5) {
    triggerSlash('/swipe');
  }
});

🛠️ Tech Stack

Core Frameworks

• Vue 3 (3.5.24) + Pinia + Vue Router - Primary UI framework
• React (19.2.0) + @pixi/react - Alternative for game-like UIs
• PixiJS (8.14.1) - WebGL rendering for multimedia experiences

Utilities

• jQuery (3.7.1) - DOM manipulation and SillyTavern UI integration
• Lodash (4.17.21) - Data manipulation utilities
• Zod (4.1.12) - Schema validation and type safety
• GSAP (3.13.0) - Animation engine (typewriter, tweens, etc.)
• Klona (2.0.6) - Deep cloning (remove Vue Proxy before saving)

Build System

• Webpack (5.102.1) - Bundles multi-component → single HTML
• TypeScript (6.0.0-dev) - Type-safe development
• Sass (1.94.0) - Advanced styling
• Tailwind CSS (4.1.17) - Utility-first CSS

See references/tech_stack.md for complete list with usage examples.

📖 Key Concepts

Project Types

Frontend Interface (index.ts + index.html):

• Runs as sandboxed iframe in message floors
• Has its own UI rendered in chat
• Final output: single bundled HTML file

Script (index.ts only):

• Runs as background iframe (no UI)
• Can manipulate SillyTavern's main page via jQuery
• Final output: single bundled JS file

API Priority Order

1. Tavern Helper API (highest priority) - TypeScript-safe, type-checked

   getChatMessages()
   replaceVariables(data, {type: 'chat'})

2. STScript Commands (fallback) - For features not yet in Tavern Helper

   triggerSlash('/setentryfield ...')

3. SillyTavern Native (last resort) - Direct access to internals

   SillyTavern.getContext()

Variable Types

• Global: Shared across all chats
• Character: Bound to character card
• Chat: Bound to specific chat file
• Message: Bound to specific message floor
• Script: Private to your script
• Extension: Shared among extension scripts

See references/api_reference.md for complete API documentation.

🎨 Development Workflow

Local Development

1. Create project in tavern_helper_template/src/your-project/
2. Write code using TypeScript + Vue/React
3. Build: pnpm run build → outputs to dist/your-project/
4. Preview: Deploy to VPS or use local server
5. Load in SillyTavern: Import via Tavern Helper

Live Preview (VPS Users)

# Create symlink for live updates
ln -s /root/tavern_helper_template /root/web-dev/st-dev

# Access at https://dev.piepia.space/st-dev/dist/your-project/index.html
# Claude can preview via WebFetch + browsermcp

Build Commands

pnpm run build        # Production build (minified)
pnpm run build:dev    # Development build (with source maps)
pnpm run watch        # Auto-rebuild on file changes

⚠️ Common Pitfalls

❌ Don't Do This

// Don't use DOMContentLoaded (doesn't fire on network load)
document.addEventListener('DOMContentLoaded', () => {});

// Don't use Node.js APIs (browser environment only)
import fs from 'fs';

// Don't save Vue Proxy directly to variables
replaceVariables(state.value, {type: 'chat'}); // ❌ Has Proxy wrapper

✅ Do This Instead

// Use jQuery ready handler
$(() => {
  toastr.success('Loaded!');
});

// Only use browser APIs
import { debounce } from 'lodash';

// Remove Proxy before saving
import { klona } from 'klona';
replaceVariables(klona(state.value), {type: 'chat'}); // ✅ Clean object

See references/best_practices.md for complete list.

🔧 MVU Framework Integration

When working with message floor variables, use the MVU (MagVarUpdate) framework:

// Wait for MVU initialization
await waitGlobalInitialized('Mvu');

// Get current message variables
const data = Mvu.getMvuData({ type: 'message', message_id: -1 });

// Parse AI output for variable updates
const newData = await Mvu.parseMessage(oldData, aiOutput);

// Save back to message
Mvu.replaceMvuData(newData, { type: 'message', message_id: -1 });

// Listen to variable changes
eventOn(Mvu.events.AFTER_UPDATE, (data) => {
  console.log('Variables updated:', data.stat_data);
});

See references/mvu_framework.md for complete API.

📜 STScript Commands

264 slash commands are available for direct tavern operations:

triggerSlash('/echo Hello World');           // Show toast
triggerSlash('/trigger');                    // Trigger AI reply
triggerSlash('/genraw ...');                 // Raw LLM generation
triggerSlash('/buttons labels=["Yes","No"]'); // Show dialog
triggerSlash('/setvar key=foo value=bar');   // Set variable (prefer API)

See references/stscript_commands.txt for complete list.

🤝 Contributing

This skill is maintained as part of the SillyTavern development ecosystem. Contributions welcome:

1. Fork this repository
2. Add/improve documentation in references/
3. Submit pull request with clear description

📄 License

MIT License - Free to use for any SillyTavern development projects.

🔗 Related Resources

• SillyTavern: https://github.com/SillyTavern/SillyTavern
• Tavern Helper: https://n0vi028.github.io/JS-Slash-Runner-Doc/
• MVU Framework: https://github.com/MagicalAstrogy/MagVarUpdate
• Template Repository: (Add your tavern_helper_template repo here)

---

Built with Claude Code | Generated by Claude as a comprehensive development skill