DeckMate - Stream Deck Integration Assistant

DeckMate helps you create and manage Stream Deck integrations for VSCode and Claude Code workflows. It understands both the native Stream Deck profile format AND provides tooling for developer workflow integrations.

When to Use This Skill

Use this skill when:

• Creating new Stream Deck profiles for development workflows
• Adding buttons, snippets, or scripts for Stream Deck
• Setting up TAC (Tactical Agentic Coding) integrations
• Understanding the Stream Deck profile format
• Building automation scripts triggered by Stream Deck
• Converting integration blueprints to actual profiles

Stream Deck Profile Format (Native)

File Structure

Stream Deck profiles are .streamDeckProfile files, which are ZIP archives containing:

ProfileName.streamDeckProfile (ZIP)
└── {UUID}.sdProfile/
    ├── manifest.json              # Profile metadata
    └── Profiles/
        └── {PAGE_ID}/
            ├── manifest.json      # Button/action configuration
            └── Images/
                └── *.png          # Button icons (72x72 or 144x144)

Root Manifest Schema

{UUID}.sdProfile/manifest.json:

{
  "Device": {
    "Model": "20GBD9901",
    "UUID": ""
  },
  "Name": "Profile Name",
  "Pages": {
    "Current": "page-uuid-here",
    "Pages": ["page-uuid-here", "another-page-uuid"]
  },
  "Version": "2.0"
}

Device Models:

• 20GBD9901 - Stream Deck (15 keys)
• 20GAT9901 - Stream Deck Mini (6 keys)
• 20GAV9901 - Stream Deck XL (32 keys)
• 20GBA9901 - Stream Deck + (8 keys + 4 dials)
• 20GAA9901 - Stream Deck Mobile

Page Manifest Schema

Profiles/{PAGE_ID}/manifest.json:

{
  "Controllers": [
    {
      "Type": "Keypad",
      "Actions": {
        "0,0": { /* Action at row 0, col 0 */ },
        "0,1": { /* Action at row 0, col 1 */ },
        "1,0": { /* Action at row 1, col 0 */ }
      }
    },
    {
      "Type": "Encoder",
      "Actions": {
        "0,0": { /* Dial 1 */ },
        "1,0": { /* Dial 2 */ }
      }
    }
  ]
}

Action Schema

Each action in the Actions object:

{
  "ActionID": "unique-uuid-here",
  "LinkedTitle": false,
  "Name": "Display Name",
  "Settings": {
    /* Action-specific settings */
  },
  "State": 0,
  "States": [
    {
      "Image": "Images/filename.png",
      "Title": "Button Label",
      "FontFamily": "",
      "FontSize": 12,
      "FontStyle": "",
      "FontUnderline": false,
      "ShowTitle": true,
      "TitleAlignment": "bottom",
      "TitleColor": "#ffffff",
      "OutlineThickness": 2
    }
  ],
  "UUID": "com.elgato.streamdeck.system.hotkey"
}

Built-in Action UUIDs

System Actions

UUID	Name	Description
com.elgato.streamdeck.system.hotkey	Hotkey	Send keyboard shortcut
com.elgato.streamdeck.system.hotkeyswitch	Hotkey Switch	Toggle between two hotkeys
com.elgato.streamdeck.system.open	Open	Open file/folder/URL
com.elgato.streamdeck.system.website	Website	Open URL in browser
com.elgato.streamdeck.system.text	Text	Type text string
com.elgato.streamdeck.system.multimedia	Multimedia	Media controls
com.elgato.streamdeck.profile.backtoparent	Back	Navigate to parent folder
com.elgato.streamdeck.profile.openchild	Open Folder	Navigate to subfolder

Hotkey Settings

{
  "Settings": {
    "Coalesce": true,
    "Hotkeys": [
      {
        "KeyCmd": false,
        "KeyCtrl": true,
        "KeyModifiers": 2,
        "KeyOption": false,
        "KeyShift": false,
        "NativeCode": 67,
        "QTKeyCode": 67,
        "VKeyCode": 67
      }
    ]
  }
}

KeyModifiers Bitmask:

• 1 = Shift
• 2 = Ctrl
• 4 = Alt/Option
• 8 = Cmd/Win

Common VKeyCodes:

• A-Z: 65-90
• 0-9: 48-57
• F1-F12: 112-123
• Enter: 13
• Tab: 9
• Space: 32
• Escape: 27

Open Action Settings

{
  "Settings": {
    "openInBrowser": false,
    "path": "/path/to/file/or/folder"
  }
}

Text Action Settings

{
  "Settings": {
    "text": "Text to type"
  }
}

Website Action Settings

{
  "Settings": {
    "openInBrowser": true,
    "url": "https://example.com"
  }
}

Developer Integration Files

For complex developer workflows, DeckMate uses Integration Definition files (JSON) that serve as blueprints. These are NOT native Stream Deck profiles but documentation/configuration that can be used to:

1. Document intended integrations
2. Generate scripts and snippets
3. Provide context for manual Stream Deck setup
4. Track TAC leverage points

Integration Definition Structure

streamdeck/
├── profiles/                    # Integration blueprints (NOT native profiles)
│   └── tac-lesson4-integrations.json
├── snippets/                    # Text content for Text actions
│   └── piter-framework.md
├── scripts/                     # Shell scripts for hotkey-triggered terminals
│   └── adw-plan-build.sh
└── vscode/
    └── snippets.code-snippets   # VSCode autocomplete snippets

Integration Definition Schema

{
  "name": "Integration Set Name",
  "description": "What this set provides",
  "version": "1.0.0",
  "source_lesson": "lessons/lesson-N.md",
  "buttons": [
    {
      "position": 0,
      "name": "Button Name",
      "icon": "emoji-hint",
      "type": "hotkey|text|open|website|script",
      "action": {
        /* Type-specific configuration */
      },
      "leverage_point": "TAC LP reference",
      "priority": "high|medium|low"
    }
  ],
  "snippets": [
    {
      "name": "Snippet Name",
      "file": "snippets/filename.ext",
      "trigger": "vscode-prefix"
    }
  ]
}

Creating Stream Deck Actions for Developers

Terminal Command via Hotkey + Script

1. Create a shell script in streamdeck/scripts/:

#!/bin/bash
# my-command.sh
claude "/chore $1"

2. Create a keyboard shortcut in your terminal app to run the script

3. Configure Stream Deck hotkey to trigger that shortcut

Text Injection (Snippets)

Use the com.elgato.streamdeck.system.text action:

{
  "UUID": "com.elgato.streamdeck.system.text",
  "Settings": {
    "text": "## PITER Framework\n\n### P - Prompt Input\n..."
  }
}

Open VSCode Folder

Use the com.elgato.streamdeck.system.open action:

{
  "UUID": "com.elgato.streamdeck.system.open",
  "Settings": {
    "openInBrowser": false,
    "path": "/path/to/project/specs"
  }
}

Launch Terminal with Command

Option 1: Using Open action with terminal app

{
  "UUID": "com.elgato.streamdeck.system.open",
  "Settings": {
    "path": "/usr/bin/wt",
    "arguments": "-w 0 nt claude"
  }
}

Option 2: Multi-action with hotkey sequence

1. Open terminal (Ctrl+`)
2. Type command text
3. Send Enter

TAC Leverage Points Reference

When creating integrations, tag them appropriately:

LP	Name	Stream Deck Use Case
1	Context	Open ai_docs/, load context files
2	Model	-
3	Prompt	Text injection of prompts
4	Tools	Launch Claude, terminal commands
5	Standard Out	Status posting scripts
6	Types	Open type definition files
7	Documentation	Open docs folders
8	Tests	Run test scripts
9	Architecture	Navigate project structure
10	Plans	Open specs/, create plans
11	Templates	Inject slash commands
12	ADWs	Launch ADW workflows

Common Developer Patterns

Launch Claude Interactive

{
  "UUID": "com.elgato.streamdeck.system.open",
  "Name": "Claude",
  "Settings": {
    "path": "/path/to/terminal",
    "arguments": "claude"
  }
}

Inject Slash Command

{
  "UUID": "com.elgato.streamdeck.system.text",
  "Name": "/chore",
  "Settings": {
    "text": "/chore "
  }
}

Open Project Folder

{
  "UUID": "com.elgato.streamdeck.system.open",
  "Name": "Specs",
  "Settings": {
    "path": "/home/user/project/specs"
  }
}

Git Quick Commit (Multi-Action)

Use Stream Deck's Multi-Action to chain:

1. Hotkey: Ctrl+` (open terminal)
2. Text: git add -A && git commit -m ""
3. Hotkey: Left Arrow (position cursor)

Creating a Profile Programmatically

Python Helper

import json
import zipfile
import uuid
import os

def create_profile(name: str, buttons: list, device_model: str = "20GBD9901"):
    """Create a .streamDeckProfile file."""
    profile_uuid = str(uuid.uuid4()).upper()
    page_uuid = str(uuid.uuid4())

    # Root manifest
    root_manifest = {
        "Device": {"Model": device_model, "UUID": ""},
        "Name": name,
        "Pages": {"Current": page_uuid, "Pages": [page_uuid]},
        "Version": "2.0"
    }

    # Build actions from buttons
    actions = {}
    for btn in buttons:
        pos = f"{btn['row']},{btn['col']}"
        actions[pos] = {
            "ActionID": str(uuid.uuid4()),
            "LinkedTitle": False,
            "Name": btn["name"],
            "Settings": btn.get("settings", {}),
            "State": 0,
            "States": [{
                "Title": btn["name"],
                "ShowTitle": True,
                "TitleAlignment": "bottom",
                "TitleColor": "#ffffff"
            }],
            "UUID": btn["uuid"]
        }

    # Page manifest
    page_manifest = {
        "Controllers": [{"Type": "Keypad", "Actions": actions}]
    }

    # Create ZIP
    with zipfile.ZipFile(f"{name}.streamDeckProfile", "w") as zf:
        sd_dir = f"{profile_uuid}.sdProfile"
        zf.writestr(f"{sd_dir}/manifest.json", json.dumps(root_manifest))
        zf.writestr(f"{sd_dir}/Profiles/{page_uuid}/manifest.json", json.dumps(page_manifest))

    return f"{name}.streamDeckProfile"

Usage

buttons = [
    {
        "row": 0, "col": 0,
        "name": "Claude",
        "uuid": "com.elgato.streamdeck.system.open",
        "settings": {"path": "/usr/bin/claude"}
    },
    {
        "row": 0, "col": 1,
        "name": "/chore",
        "uuid": "com.elgato.streamdeck.system.text",
        "settings": {"text": "/chore "}
    }
]

create_profile("TAC Developer", buttons)

Workflow: From Integration Definition to Profile

1. Define integrations in profiles/*.json (blueprint)
2. Create supporting files (scripts, snippets)
3. Generate or manually create .streamDeckProfile
4. Import into Stream Deck app

Best Practices

Button Layout (15-key Stream Deck)

Row 0: [High Priority Actions - Most Used]
Row 1: [Medium Priority - Regular Use]
Row 2: [Low Priority / Navigation]

Icon Guidelines

• Size: 72x72 (standard) or 144x144 (retina)
• Format: PNG with transparency
• Style: Simple, high-contrast icons
• Text: Avoid text in icons, use Title instead

Naming Conventions

• Buttons: Short (1-2 words), action-oriented
• Scripts: kebab-case.sh (e.g., run-tests.sh)
• Snippets: Descriptive with extension (e.g., piter-framework.md)

Troubleshooting

Profile Won't Import

• Verify ZIP structure is correct
• Check manifest.json syntax
• Ensure Device Model matches your hardware

Button Does Nothing

• Check action UUID is valid
• Verify Settings match action type
• For hotkeys, verify key codes

Script Not Running

chmod +x scripts/my-script.sh

Commands

DeckMate responds to these requests:

• "Create a Stream Deck hotkey for [shortcut]"
• "Add a text injection button for [content]"
• "Generate a profile from my integration definition"
• "What UUID do I need for [action type]?"
• "Show me the Stream Deck profile structure"
• "Create a button that opens [folder]"
• "What's the key code for [key]?"