Deckmate

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

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:

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]?"