skills.rest
digitaldrummerj
digitaldrummerjCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

companion-upgrades

Write Companion upgrade scripts that migrate config, actions, and feedbacks across breaking changes.

Updated May 19, 2026
Search Tags:#typescript#breaking changes#data migration#config migration#bitfocus companion#companion-module#upgrade script
One-click install
npx skills add https://github.com/digitaldrummerj/bitfocus-companion-skills --skill companion-upgrades-digitaldrummerj
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: companion-upgrades
Source: https://github.com/digitaldrummerj/bitfocus-companion-skills/tree/main/plugins/companion-upgrades
Command: npx skills add https://github.com/digitaldrummerj/bitfocus-companion-skills --skill companion-upgrades-digitaldrummerj

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires @companion-module/base.

What problem does it solve? Breaking changes in a Bitfocus Companion module—renamed config fields, action IDs, feedback IDs, or option IDs—can silently destroy users' saved button configurations. This Skill provides the patterns and API reference needed to write upgrade scripts that safely migrate existing user data to the new schema. ## Core Features & Use Cases - Versioned Migration Model: Explains the CompanionStaticUpgradeScript array where each index maps to a version, and why scripts must never be removed or reordered. - Migration Patterns: Provides copy-ready examples for renaming config fields, migrating action and feedback options, and converting value formats. - Helper Factories: Covers EmptyUpgradeScript, CreateConvertToBooleanFeedbackUpgradeScript, and CreateUseBuiltinInvertForFeedbacksUpgradeScript from @companion-module/base. - Use Case: You renamed the config field 'ipAddress' to 'host' and changed an action ID from 'setInput' to 'set_input'. Use this Skill to write upgrade scripts that rewrite saved user configs and actions so existing button setups keep working after the update. ## Quick Start Ask the agent to create a Companion upgrade script that renames a config field and migrates saved actions to a new action ID.

Frequently Asked Questions about companion-upgrades

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write a Companion upgrade script for a breaking change?▼

Add a function to the UpgradeScripts array typed as CompanionStaticUpgradeScript<ModuleConfig>. Each function receives props containing config, actions, and feedbacks, mutates them as needed, and returns updatedConfig, updatedActions, and updatedFeedbacks.

How do I rename an action ID without breaking saved buttons?▼

Add an upgrade script that maps over props.actions and rewrites matching actionId values to the new ID, also renaming any changed option keys. Return the mutated array as updatedActions so Companion applies the migration to saved button configurations.

Can I remove or reorder scripts in the UpgradeScripts array?▼

No. Each array index corresponds to a module version, so removing or reordering scripts breaks migrations for existing users. Always append new scripts to the end and use EmptyUpgradeScript for versions with no changes.

How do I convert advanced feedbacks to boolean feedbacks in Companion?▼

Use CreateConvertToBooleanFeedbackUpgradeScript from @companion-module/base with a map of old feedback IDs to new boolean feedback IDs. It converts feedback type, preserves user options, and remaps the IDs automatically.

Why is my Companion upgrade script not migrating user config?▼

Common causes are forgetting to return all three result properties, mutating without returning the arrays, or not checking that old fields exist before migrating. Cast config to any when accessing renamed fields and return updatedConfig, updatedActions, and updatedFeedbacks.

Related Skills

Explore More Software Engineering Skills→
invowkinvowk

invowk-schema

Enforce consistent schemas for invkfile.cue and invkmod module definitions.

Official
Advanced
fabriqaaifabriqaai
13

project-migrate

Migrate FIRE projects by adding constitution.md and updating state.yaml schema.

Official
Advanced
code-yeongyucode-yeongyu
67.6k

pre-publish-review

Orchestrate a 16-agent pre-publish release gate for npm packages.

Community
Advanced
JDL440JDL440

Editorial Controls Split Migration

Migrate legacy depth_level to split editorial control fields across UI surfaces.

Community
Advanced