How to use the Studio Lights Control agent skill (StudioLights)

What is an agent skill, and what does StudioLights make the agent do?

An agent skill is a folder of instructions and tools that an AI assistant can load when a request matches the skill's purpose. StudioLights covers one job: controlling studio lights.

Once installed, the agent can switch the lights to a saved scene such as 'recording' or 'normal', set brightness or color temperature for a named light, or save the current light levels as a new scene. It talks to the amaran Desktop app running on your computer over a local connection, then reads back each light's state to confirm the change happened. Your fixtures and scenes are stored in your own user folder, not inside the skill.

• Named scenes: recording, normal, full, off, or any scene you save
• Per-light brightness (0–100 in the tool) and color temperature
• Saving the current state as a new scene
• A read-back after every write, so a change is only reported as done when the light confirms it

What you need before you install

The skill has specific requirements. Check these first, because the tool will fail without them.

It runs on a Mac with the amaran Desktop app installed and signed in to a Sidus account. Your Aputure or amaran studio lights must already be paired in amaran Desktop. The tool is run with Bun, and it needs a devices.json file with your fixture node IDs in your user folder, which the setup guide helps you create.

• Mac with amaran Desktop installed and signed in
• Aputure or amaran studio lights paired in amaran Desktop
• Bun runtime (the tool is run with bun)
• A devices.json file in your USER folder, created via Setup.md
• The skill runs scripts; it does not use the network (per its listing)

Install the StudioLights skill

Download the StudioLights ZIP from this page and unzip it. Then choose one of two places to put it. For a personal install that applies everywhere, unzip it into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder.

If you use the Claude apps, you can instead upload the ZIP under Settings → Capabilities → Skills.

The tool finds your user folder from the skill folder's name, so the skill folder and its USER folder must share the name StudioLights.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

Create devices.json with your fixture node IDs

The skill will not guess your lights. Your fixtures are listed in devices.json in the USER folder at LIFEOS/USER/CUSTOMIZATIONS/SKILLS/StudioLights/. Each entry holds a fixture's name, node ID, model and whether it supports color temperature.

To find the node IDs, run the device listing command. It works before the file exists. If a light is daylight-only, it reports no color temperature, and you mark it in devices.json so the tool skips that setting for it.

• File location: LIFEOS/USER/CUSTOMIZATIONS/SKILLS/StudioLights/devices.json
• Scenes are saved in scenes.json in the same folder
• Free-form notes can go in Config.md; the tool does not read it
• Lights that report no color temperature need "supportsCct": false

Trigger the skill with natural requests

You do not need to use commands. Ask the assistant in plain language and the Control intent runs the tool. Requests such as 'lights for recording', 'set the lights for recording' or 'dim the key light to 30%' match the skill's triggers.

Scene changes move each light to the levels saved under that scene name. If you ask for a per-light change and then say to save it, the scene is stored with the levels you chose. The assistant will not pick new levels on your behalf.

• 'recording' or 'set lights for recording' applies the recording scene
• 'lights back to normal' applies the normal scene
• 'key light to 30%' changes one light
• 'save this as recording' stores the current levels

Examples of how the tool runs

Under the hood, the assistant calls Tools/Lights.ts with a short command. A scene change uses the scene subcommand, a single light uses set with a name and intensity, and saving uses scene save with the name you chose.

Writes run one at a time. The tool spaces commands so a scene takes about half a second per light, so a rig with several lights needs a short wait.

• Scene: bun Tools/Lights.ts scene recording
• Single light: bun Tools/Lights.ts set key --intensity 30
• Save: bun Tools/Lights.ts scene save recording

Safety notes and tips

The skill itself says lighting scenes need a visual check. Brightness and heat can matter for safety, so do not rely on a scene when nobody is watching the lights. If a light reports a different level from the one you asked for, the tool reports a mismatch and the assistant should not say the change worked.

If a Shortcut or other tool calls a scene by name, renaming the scene in scenes.json will break that caller silently, so update the caller when you rename. amaran Desktop must stay running; the tool launches it and waits up to 30 seconds if it is closed. The phone apps for these lights offer no automation path.

• Do not use it for house lights such as Philips Hue or thermostats; the skill excludes them
• Check the lights visually after a scene change
• Update any Shortcut or caller when you rename a scene
• Sign in to amaran Desktop once if it opens signed out