matlab/matlab-agentic-toolkit/matlab-discover-hardware

Hardware Discovery

1. What this skill is for

Use this skill to perform hardware discovery tasks from natural language: list connected devices, search by capability, inspect a device's details and capabilities, and check if required support packages or add-ons are installed.

This skill exposes hardware discovery functionality through MATLAB helper functions bundled in scripts/. Always use the provided helpers — do not attempt to replicate their behavior or call any internal MATLAB functions directly.

When To Use

Activate this skill when the user asks about:

• What hardware is connected or available (e.g., "what's plugged in?", "what devices do I have?")
• Which devices support a given capability (e.g., "what supports CAN?", "which devices can do analog input?")
• Details or capabilities of a specific device (e.g., "tell me about the Arduino Due", "what can the NI USB-6211 do?")
• Whether required support packages or add-ons for a device are installed
• What needs to be installed to use a specific device

When Not To Use

Do not activate this skill for:

• Non-hardware MATLAB work (general scripting, algorithm development, plotting, etc.)
• Acquiring or streaming data from a device (use device-specific skills instead)
• Configuring or programming a specific device after discovery (use device-specific skills)
• Installing support packages directly — this skill only reports install state; defer to an install-capable skill when one is available
• Listing all installed MATLAB products or support packages without a hardware context (use matlab-list-products instead)

2. Device-specific skill routing

This skill handles hardware discovery only — enumerating MATLAB-supported devices, searching by capability, and checking install state. When the user's intent goes beyond discovery (connecting, configuring, acquiring data, troubleshooting, or using a device), always explore the currently loaded skills for a matching device-specific skill.

Routing rule: When the user asks to use a device (not just discover it), search the available skills list for any skill whose name or description matches the device type, hardware category, or the user's task. Do not maintain a hardcoded list of skills to defer to — discover them dynamically at runtime.

How to route:

1. Complete the discovery step (confirm device exists, check install state)
2. Tell the user what you found (e.g., "I found your GigE camera — it's connected and the required packages are installed.")
3. Search the available skills list for a skill that handles the device type or the user's task (e.g., a skill mentioning "arduino", "camera", "DAQ", "OPC UA", etc.)
4. If a matching skill is found: silently invoke it to handle the usage/connection/troubleshooting task — do not name the skill to the user
5. If no matching skill is found: fall back to discovery-only output (see below)

If no device-specific skill is found for the device category, you are restricted to discovery-level output only:

1. Present device details and install state (using the helpers in §4)
2. Provide the HardwareSupportUrl or suggest MATLAB documentation
3. STOP. Do not write device-specific code (e.g., videoinput(, webcam(, arduino(, readVoltage(, gigecam(). Do not provide step-by-step usage workflows, connection examples, or troubleshooting scripts from training data. You are a discovery skill — usage guidance belongs to the device-specific skill, even when that skill is not loaded.

Bad (improvising usage code when no device skill is found):

cam = webcam("Logitech Webcam C925e");
img = snapshot(cam);

Good (discovery-only fallback):

"Your Logitech Webcam C925e is detected and the required packages are
installed. For connecting and acquiring images, refer to the Image
Acquisition Toolbox documentation."

3. One-time bootstrap (path setup)

Before invoking any helper, add the bundled scripts/ folder to the MATLAB path once per session:

addpath(fullfile("<skill-root>", "scripts"))

Replace <skill-root> with the absolute path of this skill's folder (e.g., .../.claude/skills/matlab-discover-hardware).

This addpath is the only allowed path mutation in this skill. After bootstrap:

• Do not call addpath, rmpath, or cd again
• Do not call clear all
• Do not create new .m files

If a helper call fails with Undefined function, re-run the bootstrap once. If it still fails, report the error to the user; do not invent workarounds.

The bootstrap addpath is performed automatically before skill activation — you do not need to include it in your helper calls.

4. Public helper surface

Use only these 4 public helpers (located in scripts/):

Internal — do not call: hardwareDeviceCache.m, getDeviceAddOns.m, and getAddOnDetails.m exist in scripts/ only because the public helpers depend on them. They are not part of the agent surface and must not be invoked directly.

Duplicate-name behavior: getDeviceDetails returns one struct per matching device (struct array if multiple share a name). getDeviceSetupInfo and isRequiredAddOnsInstalled return a single result (all same-name devices share add-on requirements).

Important: Always use the public helpers listed above. Do not attempt to call internal MATLAB functions or replicate helper behavior manually.

5. Task routing

Pick the helper that matches the user's intent. Combine all calls for a task into the minimum number of `evaluate_matlab_code` invocations (see §6 for batching recipes).

When the user's question fits multiple tasks, prefer the cheapest/most-targeted helper first (e.g., listHardwareDevices(Capability=...) before getDeviceDetails).

6. Workflow patterns and batching

Critical: minimize MCP round-trips

Each evaluate_matlab_code call is an MCP round-trip that requires user approval. Batch multiple helper calls into a single `evaluate_matlab_code` invocation whenever possible. The helpers share an internal cache (60 s TTL), so calling them sequentially in one script is efficient.

Rules:

1. Combine Layer 1 + Layer 2 calls when you already know the device name
2. Combine install-state checks with the detail call that precedes them
3. Target 1–2 MCP calls total for any single user question

Batching recipes

Recipe A: "What hardware is connected?" (1 MCP call)

deviceList = listHardwareDevices();
disp(deviceList)
clear deviceList

Recipe B: "Tell me about <device>" / "What can <device> do?" (2 MCP calls)

Call 1 — discover (to confirm device exists):

deviceList = listHardwareDevices();
disp(deviceList)
clear deviceList

Call 2 — details + install-state check (combined):

details = getDeviceDetails("<deviceName>");
disp(details);
isInstalled = isRequiredAddOnsInstalled("<deviceName>");
if ~isInstalled
    setupInfo = getDeviceSetupInfo("<deviceName>");
    disp(setupInfo);
end
clear details isInstalled setupInfo

If the user names the device directly and you are confident in the name (e.g., they typed "Arduino Due"), skip Call 1 and do everything in a single call:

details = getDeviceDetails("<deviceName>");
disp(details);
isInstalled = isRequiredAddOnsInstalled("<deviceName>");
if ~isInstalled
    setupInfo = getDeviceSetupInfo("<deviceName>");
    disp(setupInfo);
end
clear details isInstalled setupInfo

Multi-result handling: getDeviceDetails returns a struct array when multiple devices share the same name (e.g., two "Kvaser Virtual" channels). If numel(details) > 1, do not present all results — instead trigger the disambiguation flow (§6 Plain-text disambiguation) using ConnectionInfo or other distinguishing fields from each element's BasicInfo.

Recipe C: "What do I need to install for <device>?" (1 MCP call)

setupInfo = getDeviceSetupInfo("<deviceName>");
disp(setupInfo)
clear setupInfo

Recipe D: Capability search (1–2 MCP calls)

results = listHardwareDevices(Capability="<keyword>");
disp(results)
clear results

If results are found and user wants details, follow with Recipe B Call 2.

Discover-then-detail

Call a Layer 1 helper (listHardwareDevices or listHardwareDevices(Capability=...)) before drilling into a Layer 2 helper. Do not guess device names. Exception: if the user explicitly names a device, skip discovery and go directly to Layer 2 (see Recipe B single-call variant).

Capability-first search

When the user describes a task ("I want to read CAN messages"), call listHardwareDevices(Capability="CAN") before naming a specific device.

If the capability search returns no results, do not guess alternative keywords or invent suggestions from your own knowledge. Instead:

1. Call listHardwareDevices() to show all connected devices
2. Present the list to the user and ask which device they intended to use for the task
3. Once the user identifies a device, proceed with the Install-state check workflow

Install-state check

When the user asks what they need for a device, or asks how to use / whether they can use a specific device, use Recipe C (getDeviceSetupInfo includes the install-state boolean). If packages are missing, list them by human-readable name. Silently check the available skills list for an install-capable skill — if one exists, offer to install on the user's behalf without naming the skill. Only fall back to telling the user to open MATLAB Add-On Explorer (Home tab → Add-Ons → Get Add-Ons) if no such skill is available.