my-device

name	my-device
description	TODO: Comprehensive description including device type, vendor, model, measurement capabilities, data formats, and use cases. This description determines when Claude activates this skill.

[Device Name] — Skill Guide

This file is the primary operational reference for AI agents controlling this device. It covers control modes, workflows, safety constraints, and code patterns.

Control Modes

API Mode

• Protocol: TODO (e.g., gRPC on localhost:3081, REST on :8080, serial /dev/ttyUSB0)
• Library: TODO (e.g., bruker.api.topspin.Topspin(), requests, pyserial)
• Authentication: TODO (e.g., none, API key, token)
• Connect snippet:

from devices.<device_name>.adapter import DeviceAdapter

adapter = DeviceAdapter()
adapter.connect()  # TODO: document what happens on connect

GUI Mode

• Software: TODO (e.g., TopSpin 5.x, Gen5 3.x)
• Key UI elements: TODO (e.g., command bar at bottom, File menu, Run button)
• Common commands: TODO (list the most-used commands/clicks)

Offline Mode

• Supported formats: TODO (e.g., .csv, .fid, .tif, .xlsx)
• Processing library: TODO (e.g., nmrglue, pandas, tifffile)
• Limitations: TODO (e.g., cannot acquire new data, no real-time control)

Workflows

Acquire

When: TODO (e.g., user requests a new measurement, protocol calls for data collection)

Steps:

1. TODO: Connect to device (adapter.connect())
2. TODO: Configure parameters (adapter.acquire(param=value))
3. TODO: Wait for acquisition to complete
4. TODO: Verify data was collected

Code:

adapter = DeviceAdapter()
adapter.connect()
# TODO: fill in acquisition parameters
raw_data = adapter.acquire(
    # param1="value1",
    # param2="value2",
)

Output: TODO (e.g., raw FID file, CSV with absorbance readings, TIFF image stack)

Process

When: TODO (e.g., after acquisition, when user provides a data file)

Steps:

1. TODO: Load raw data (processor.load(path))
2. TODO: Apply transforms (processor.transform(raw)) — list specific transforms
3. TODO: Extract results (processor.extract(processed))

Code:

from devices.<device_name>.processor import DeviceProcessor

processor = DeviceProcessor()
raw = processor.load("/path/to/data")
processed = processor.transform(raw)
results = processor.extract(processed)
# results is a dict with keys: TODO (list expected keys)

Output: TODO (e.g., dict with peaks, concentrations, images)

Analyze

When: TODO (e.g., after processing, when user asks "what does this data mean?")

Code:

from devices.<device_name>.brain import DeviceBrain

brain = DeviceBrain()
interpretation = brain.analyze(results, context="TODO: what context helps")
summary = brain.summarize([interpretation])

Output: TODO (e.g., natural language interpretation, compound identification, quality assessment)

Safety

• Safety level: TODO (normal / strict / critical — must match skill.yaml)
• Physical hazards: TODO (e.g., high voltage, radiation, cryogens, biohazard, lasers)
• Parameter bounds: TODO (e.g., max temperature 300C, max voltage 5V, max RPM 14000)
• Actions requiring confirmation: TODO (e.g., long acquisitions, high-power settings)
• Emergency stop: TODO (e.g., hardware E-stop button, software abort command, adapter.disconnect())
• Never do: TODO (e.g., never change X while Y is running, never exceed Z parameter)

Progressive Disclosure

Official Documentation (docs/)

Directory	What's There	When to Read
docs/manual/	TODO: Operator and safety manuals	Setting up, troubleshooting, safety questions
docs/api/	TODO: Programming interface reference	Writing adapter code, understanding commands
docs/specs/	TODO: Hardware specifications	Checking device limits, capabilities
docs/formats/	TODO: Data file format documentation	Parsing raw data, understanding file structure
docs/science/	TODO: Domain science background	Interpreting results, explaining to users
docs/commands/	TODO: Command reference	Looking up specific device commands
docs/guides/	TODO: Step-by-step guides	Complex workflows, advanced usage

User Knowledge (user/)

File	What's There	When to Read
user/MEMORY.md	Operational history, calibration notes, quirks discovered	Before any operation — check for known issues
user/system_config.md	This specific instrument's configuration	On connect — verify expected setup
user/calibration_log.md	Calibration event records	Before quantitative measurements
user/protocols/	Lab-specific SOPs and workflows	When user references a protocol by name
user/findings/	Accumulated experimental findings	When analyzing similar samples

Data Formats

Input

• TODO: Format name, file extension, structure description

Output

• TODO: Format name, file extension, structure description

Known Quirks

• TODO: Quirk 1 and its workaround
• TODO: Quirk 2 and its workaround