sillytavern-extension-builder

SillyTavern Extension Builder

Overview

Create production-ready SillyTavern third-party extensions with the documented extension APIs and packaging rules.

Workflow

1. Define the extension contract.

• Confirm extension slug, display name, minimum supported SillyTavern version, required modules, and whether the feature is UI-only, slash-command-only, or background worker based.
• If the user does not provide a slug, generate a lowercase kebab-case slug.

2. Scaffold baseline files.

• Prefer scripts/scaffold_extension.sh to generate manifest.json, index.js, style.css, and settings.html.
• Choose template mode:
  • default for UI/event-focused extensions.
  • slash for slash-command-first extensions.
• If the user already has files, perform minimal edits instead of full rewrites.

3. Wire extension lifecycle and settings.

• Keep extension settings under extension_settings[EXTENSION_NAME].
• Call loadExtensionSettings(EXTENSION_NAME) before reading setting values.
• Use saveSettingsDebounced() after setting changes.
• Register startup/event handlers inside jQuery(async () => { ... }).

4. Implement user-facing behavior.

• For DOM/UI integration, use documented APIs (context helpers, templates, settings rendering).
• For command behavior, add slash commands and argument parsing with the slash-command APIs when needed.
• For background logic, use a module worker class and gate execution by current chat context.

5. Validate compatibility and packaging.

• Ensure manifest keys are correct and file names match actual files.
• Ensure import paths are valid from the extension directory.
• Keep third-party dependency usage explicit and minimal.
• Package as a repo or zip with only required runtime files.

6. Return deliverables.

• Provide final file set and a concise integration note.
• Include install path expectations and any required module prerequisites.

Output Rules

• Prefer minimal-diff changes when editing an existing extension.
• Keep settings schema stable; migrate old keys instead of silently breaking them.
• Use deterministic IDs/command names (derive from extension slug).
• If introducing a slash command, include help text and argument validation.
• If introducing a module worker, include clear stop conditions for idle/no-chat states.

Resources

• references/writing-extensions-reference.md
  • Condensed upstream authoring guidance, required file anatomy, APIs, and release rules.
• references/st-extension-example-walkthrough.md
  • Practical breakdown of the city-unit/st-extension-example template and reuse patterns.
• references/extension-quality-guidelines.md
  • Research-backed recommendations for quality, maintainability, security, and release readiness.
• references/template-selection-guide.md
  • Decision guide for choosing default vs slash scaffold mode and migrating between them.
• assets/templates/extension/manifest.json
  • Starter manifest with placeholders.
• assets/templates/extension/index.js
  • Starter extension entrypoint with settings and event wiring.
• assets/templates/extension/style.css
  • Starter CSS file referenced by manifest.
• assets/templates/extension/settings.html
  • Starter settings template for renderExtensionTemplateAsync.
• assets/templates/extension-slash/manifest.json
  • Slash-command-first starter manifest.
• assets/templates/extension-slash/index.js
  • Slash-command-first starter entrypoint with parser registration and validation.
• assets/templates/extension-slash/style.css
  • Minimal stylesheet for command help/settings rows.
• assets/templates/extension-slash/settings.html
  • Starter settings block for enabling/disabling command behavior.
• scripts/scaffold_extension.sh
  • Generator script for new extension skeletons.

Notes

• The docs and extension APIs evolve. If behavior is uncertain, prefer upstream docs over assumptions and keep code conservative.
• Keep code style aligned with existing SillyTavern extension conventions (imports, settings handling, and event registration).