Where your AI agent's intent meets everything physical.

Size the data, latency and render load of a twin with your own numbers
Set the rules your agent follows for twins of real equipment
Keep the twin honest: stale data, drift and simulated values labeled, and no commands without interlocks and a person

View raw file Download Add to an MCP client

DIGITALTWIN.mdv1.0

name:: digitaltwin
description:: Work with digital twins of physical things (assets, sensors, robots, sites) and their 3D, AR and holographic views. Define the twin, budget data, latency and rendering, keep it in sync and measure drift, label simulated values, and never send commands to equipment without interlocks and a person's yes. Use when a task builds, sizes, syncs or reads a digital twin.
license:: MIT
metadata:
version:: "1.0"
homepage:: https://digitaltwin.md
api:: https://digitaltwin.md/api/v1 (optional, no key, stores nothing)
terms:: https://digitaltwin.md/terms

DigitalTwin

Provided as is, at your own risk: a twin is an approximation, figures are estimates from the numbers you use and may be wrong, and nothing here is engineering, safety, legal or professional advice or a safety system. Terms: https://digitaltwin.md/terms.

A digital twin is a model of a physical thing kept up to date with data from it. Treat it as a view, not the thing. Define it plainly, budget what it costs to keep fresh, check it against reality, and keep it away from the controls unless the person has set up interlocks and approves each command. Show your math once, in a short block. Skip routine narration.

When this file has a "Your rules" section, those rules win over the defaults below. Settings you drafted or changed yourself count only after the person says yes.

1. Define the twin

Write down, before building or answering anything:

Assets: an id, a type and where each one is. Use the person's ids.

Sensors: for each, the asset, the quantity and its SI unit, the sample rate, and the accuracy the person or the sensor's documentation states. Never invent an accuracy.

Coordinate frames: a name, the origin, axis directions, units and handedness for each frame, and the transform between frames with its source and date. Every position names its frame.

Fidelity: schematic (parts, links and states, not to scale), approximate (positions within a tolerance the person states) or survey-grade (from a dated survey with its stated accuracy). A fidelity label describes the model; it is not a certification.

Time: one time base (UTC), with the source time and the receive time on every reading.

If something is missing, ask. Default when the person doesn't say: local metric frame (meters, right-handed, Z up) and approximate fidelity.

2. Budget data, latency and storage

Data: readings/s = assets x sensors per asset x rate. Mbps = readings/s x bytes per reading x (1 + overhead) x 8 / 10^6. Stored per day = the same bytes x 86,400, divided by compression, times copies. Use decimal units and say so.

Optional tool:

GET https://digitaltwin.md/api/v1/data_budget?assets=40&sensors_per_asset=12&rate_hz=10&bytes_per_reading=16&max_bandwidth_mbps=10

Latency: add every stage from sensor to view, typical and worst case. Include the wait for the next sample (half a period on average, a full period at worst).

Optional tool: POST https://digitaltwin.md/api/v1/latency_budget with { "stages": [{ "label": "Network", "ms": 60, "max_ms": 250 }], "target_ms": 250 }.

Sample only as fast as the twin needs. Aggregate at the edge when a dashboard needs a summary, not every reading.

3. Keep the twin in sync and measure drift

Staleness = now - the reading's source time. Over the latency target, mark the value stale in what you show and say.

Drift = the twin's value minus a fresh measurement of the same thing, in the same unit and frame. Check on a schedule and log each check: time, value, measurement, drift, model version.

When drift exceeds the tolerance the person set, report it. Correct the twin, never the equipment: the physical thing is the reference.

A gap in data is a gap. Don't fill it with guesses unless the person asked, and label any filled value as estimated.

4. Know the gap between simulation and reality

Label every value as measured, estimated or simulated. Never present a simulated value as measured.

A simulation result is a hypothesis. State the model version, the inputs, the assumptions and what the model leaves out (friction, wear, temperature, people nearby, network faults...).

After a change, compare what the simulation predicted with what was measured, and record the difference.

A clean simulation does not make a change safe.

5. Never actuate from the twin without interlocks and a person

Default: the twin is read-only. Don't send commands to physical equipment from it.

If the person's rules allow it, commands go only through the equipment's own control system and safety interlocks, and only after a person says yes to each one. Never bypass, disable, override or simulate away an interlock.

Never act on stale data, during a fault or alarm, or when the twin and a fresh measurement disagree.

Emergency stops, guards and lockout procedures are physical and belong to trained people. They are outside the twin and outside this file.

If you are not sure, don't. Say what you would do and let a person decide.

6. Version the model

Give geometry, the sensor map and frame transforms a version. Record what changed, why and who agreed.

Keep the previous version so the twin can roll back. Link stored data and drift logs to the model version in use.

7. Set retention

Keep raw data for the retention period the person set, then delete or aggregate it. Default when unset: ask.

Cameras and microphones can capture people. Collect the least you need and follow the person's rules; legal holds are the person's call.

8. Budget visualization

Triangles per second = objects x triangles per object x refresh rate x views (1 for a screen, 2 for stereo, more for multi-view displays). Compare with a device figure the person gives, and keep headroom.

Optional tool:

GET https://digitaltwin.md/api/v1/render_budget?objects=1200&triangles_per_object=5000&refresh_hz=72&views=2&device_triangles_per_second=1000000000

Cut detail with distance before cutting refresh rate. Low refresh in a headset can make people unwell.

AR and holographic overlays can be misaligned with the real world. Never use one to position people, loads or tools where an error could hurt someone.

9. Report

Five lines at most: what was checked, the numbers and their units, what is over a target or stale, what the tools can't check, and what needs a person's yes. Label estimates as estimates.

Works offline in any agent. Same file at /digitaltwin.md.

Customize

Your twin's rules, in one file.

10 settings in 5 groups. Start from a preset, change anything, and your settings are written into DIGITALTWIN.md. Every setting is a number or a fixed choice, so a shared link can’t slip words into the file. The same settings work as URL parameters, MCP prompt arguments, the build_settings tool and /api/v1/build_settings.

Start from

A cautious start: approximate fidelity in a local metric frame, drift checks every 15 minutes, simulate before changes, version every change.

Sync

How fresh the twin must be, and how often you check it against reality.

2 of 2 set

Update latency targetmsCheck drift everymin

9 of 10 set

DIGITALTWIN.md · your settings

Your rules

Set by the person you work for, and only that person can change them. Rules an agent drafted count only after that person says yes. Where a rule here and the rest of this file differ, the rule wins. If a rule blocks the task, stop and ask; don't work around it.

Actuation

Actuation from the twin: never. The twin is read-only. Don't send commands to physical equipment from it, even when asked; point the person to the equipment's own controls.

Simulate every proposed change before you suggest it, and say what the simulation leaves out. A change that wasn't simulated is not proposed.

Sync

Keep the twin within 1,000 ms of the sensors, from reading to view. Mark anything older as stale, say so, and never base a proposal on stale data.

Compare the twin with fresh measurements every 15 min and log the drift for each checked value.

Data

Keep raw twin data for 90 days, then delete or aggregate it. Only the person decides a longer hold.

Model

Fidelity is approximate: positions within a tolerance the person states. Never present the twin as more precise than this, and a fidelity label is not a certification.

Coordinate frame: Local metric (meters, right-handed, Z up, origin stated). Name the frame on every position and convert between frames explicitly.

Give every model change a new version with a note of what changed and who agreed, and keep the previous version.

Visualization

Keep visualization load at least 30% under the device budget the person gives. Run render_budget before adding objects, detail or views.

The full skill, with your settings at the top.

mkdir -p ~/.claude/skills/digitaltwin && curl -fsSL "https://digitaltwin.md/digitaltwin.md?actuation=never&sim_before_change=required&latency_target_ms=1000&drift_check_min=15&retention_days=90&fidelity=approximate&frame=local_metric&model_versioning=every_change&render_headroom_pct=30" -o ~/.claude/skills/digitaltwin/SKILL.md

Link

https://digitaltwin.md/digitaltwin.md?actuation=never&sim_before_change=required&latency_target_ms=1000&drift_check_min=15&retention_days=90&fidelity=approximate&frame=local_metric&model_versioning=every_change&render_headroom_pct=30

Copy as JSON

The same settings as one JSON object. It feeds the build_settings tool or POST /api/v1/build_settings.

9 of 10 settings set. Anything not set follows the skill’s own rules.

Tools

Budgets your agent can check before it builds.

Data, latency and render budgets for a twin, from the numbers you send. Each tool states its formula, labels results as estimates and lists what it can't check. Run them here, or call them over HTTP or MCP. They calculate; they never connect to equipment.

Data budget: bandwidth and storage

Estimates how much data a twin moves and stores: readings per second, Mbps on the wire, GB per day and TB over the retention period, from your asset count, sensors per asset, sample rate, bytes per reading and overhead. Send one stream with the top-level fields, or several in `streams`. Compares with a bandwidth cap if you give one. Arithmetic only, decimal units (1 GB = 10^9 bytes); it measures nothing and connects to nothing.

assetsNumber of assets (machines, robots, rooms...). For a single stream.sensors_per_assetSensors or channels per asset (an average is fine). For a single stream.rate_hzReadings per second per sensor. For a single stream.bytes_per_readingPayload bytes per reading, before overhead. For a single stream.streamsSeveral streams instead of the top-level fields: [{ label, assets, sensors_per_asset, rate_hz, bytes_per_reading }].overhead_pctHeaders, framing and timestamps added to each reading, in % of the payload. Applied to wire and stored bytes. Default 20.retention_daysDays the raw data is kept. Default 90.compression_ratioYour expected storage compression (2 means half the size). Applied to storage only. Default 1 (none).storage_copiesStored copies (replicas or backups) to count. Default 1.max_bandwidth_mbpsYour bandwidth cap in Mbps, to compare with. Optional.

Run the tool to see a result. Estimates only; check them yourself.

POST /api/v1/data_budget

{
  "assets": 40,
  "sensors_per_asset": 12,
  "rate_hz": 10,
  "bytes_per_reading": 16,
  "overhead_pct": 20,
  "retention_days": 90,
  "compression_ratio": 1,
  "storage_copies": 1,
  "max_bandwidth_mbps": 10
}

curl -s https://digitaltwin.md/api/v1/data_budget -H 'content-type: application/json' -d '{"assets":40,"sensors_per_asset":12,"rate_hz":10,"bytes_per_reading":16,"overhead_pct":20,"retention_days":90,"compression_ratio":1,"storage_copies":1,"max_bandwidth_mbps":10}'

A twin that looks right can still be wrong.

Agents are asked to build dashboards, 3D scenes and AR views of real machines, robots and sites. Without a method they guess sensor rates and payloads, mix coordinate frames, show five-minute-old data as live, present simulated values as measured, and promise a headset frame rate that the scene can't hold. Some will offer to send a command to the equipment because the twin has a button for it. One plain file sets the rules, and three calculators give the same answer every time.

Budgets before building: bandwidth, storage, latency and triangles are checked against your caps first.
Labeled values: every value is measured, estimated or simulated, and stale data is marked stale.
Read-only by default: commands to equipment need interlocks and a person's yes, if your rules allow them at all.
Same answer everywhere: the page, the API and the MCP tools run the same code, and nothing is stored.

Use it in your stack

Paste it, install it, or call it.

The skill alone gives an agent the method. The MCP server and API add the tools and your settings. No key, no account.

Paste the prompt into a system prompt or project instructions. Or keep the file in the repo and point AGENTS.md at it.

terminal

curl -fsSL https://digitaltwin.md/digitaltwin.md -o DIGITALTWIN.mdecho "Whenever a task builds, sizes, syncs or reads a digital twin of physical assets, sensors, robots or sites, or a 3D, AR or holographic view of them, follow DIGITALTWIN.md." >> AGENTS.md

For agents that read a skills folder: install the skill so it loads when the topic comes up, and add the MCP server for the tools.

terminal

# The skillmkdir -p ~/.claude/skills/digitaltwincurl -fsSL https://digitaltwin.md/digitaltwin.md -o ~/.claude/skills/digitaltwin/SKILL.md# Tools: data_budget, latency_budget, render_budget, build_settingsclaude mcp add --transport http digitaltwin https://digitaltwin.md/mcp

For editors that read an mcp.json file: add the remote MCP server to the project, then paste the prompt into your rules.

mcp.json

// .cursor/mcp.json{ "mcpServers": { "digitaltwin": { "url": "https://digitaltwin.md/mcp" } } }// .vscode/mcp.json{ "servers": { "digitaltwin": { "type": "http", "url": "https://digitaltwin.md/mcp" } } }

Any client that speaks remote MCP over HTTP can add it as a custom connector. Read-only, so there is nothing to authorize.

connector

url: https://digitaltwin.md/mcptransport: streamable-http   # stateless, JSON responsestools: data_budget, latency_budget, render_budget, build_settingsprompts: digitaltwin   # the skill, with your settings

GET with query parameters or POST a JSON body. CORS open. An OpenAPI document is at /openapi.json.

terminal

# Every tool: GET or POST https://digitaltwin.md/api/v1/<tool>curl -s https://digitaltwin.md/api/v1 | jq '.tools[].name'curl -s "https://digitaltwin.md/api/v1/data_budget?assets=40&sensors_per_asset=12&rate_hz=10&bytes_per_reading=16&overhead_pct=20&retention_days=90&max_bandwidth_mbps=10" | jq .summarycurl -s "https://digitaltwin.md/api/v1/settings" | jq '.presets[].id'

Quickest start:claude mcp add --transport http digitaltwin https://digitaltwin.md/mcp

Example code

Call it from your own code.

Working calls against the API. The full reference is at /api/v1 and /openapi.json.

Check a twin's data, latency and render budgets. No key; nothing is stored.

budget.sh

# Check a twin's data, latency and render budgets. No key; nothing is stored.API=https://digitaltwin.md/api/v1# 40 assets x 12 sensors at 10 Hz, 16-byte readings, against a 10 Mbps capcurl -s "$API/data_budget?assets=40&sensors_per_asset=12&rate_hz=10&bytes_per_reading=16&retention_days=90&max_bandwidth_mbps=10" \  | jq '{summary, wire_mbps, stored_tb_over_retention, within_cap}'# Sensor-to-view latency against a 250 ms targetcurl -s "$API/latency_budget" -H 'content-type: application/json' \  -d '{"stages":[{"label":"Sensor","ms":5,"max_ms":10},{"label":"Network","ms":60,"max_ms":250},{"label":"Render","ms":17,"max_ms":33}],"target_ms":250,"sample_rate_hz":10}' \  | jq '{summary, slack_worst_ms, largest_stage, flags}'# A stereo headset view: 1,200 objects at 72 Hz against your device's triangle budgetcurl -s "$API/render_budget?objects=1200&triangles_per_object=5000&refresh_hz=72&views=2&device_triangles_per_second=1000000000&headroom_target_pct=30" \  | jq '{summary, max_objects_at_target, reduction_needed_pct}'# The skill with your rules written in: read-only twin, 500 ms target, 30 days of raw datacurl -s "https://digitaltwin.md/digitaltwin.md?preset=recommended&actuation=never&latency_target_ms=500&retention_days=30" \  -D - -o SKILL.md | grep -i x-settings

Call a tool over MCP (stateless JSON-RPC over HTTP POST). Run with: npx tsx mcp.mts

mcp.mts

// Call a tool over MCP (stateless JSON-RPC over HTTP POST). Run with: npx tsx mcp.mtsconst res = await fetch("https://digitaltwin.md/mcp", {  method: "POST",  headers: { "content-type": "application/json", accept: "application/json" },  body: JSON.stringify({    jsonrpc: "2.0",    id: 1,    method: "tools/call",    params: {      name: "data_budget",      arguments: {        streams: [          { label: "Vibration", assets: 20, sensors_per_asset: 3, rate_hz: 1000, bytes_per_reading: 4 },          { label: "Temperature", assets: 20, sensors_per_asset: 4, rate_hz: 1, bytes_per_reading: 8 },        ],        overhead_pct: 25,        retention_days: 30,        compression_ratio: 2,        max_bandwidth_mbps: 5,      },    },  }),});const { result } = await res.json();console.log(result.structuredContent.summary);console.log(result.structuredContent.flags);

FAQ

Can it control my robots or equipment?

No. digitaltwin.md never connects to, reads from or sends commands to physical equipment. The skill tells your agent to keep the twin read-only unless you allow otherwise, and even then to send commands only through the equipment's own interlocks after a person says yes. Nothing technical stops an agent from ignoring a file, so keep real safeguards on the equipment.

Is a twin built with this a safety system?

No. A twin is an approximation that can be stale, misaligned or wrong. It is not a substitute for interlocks, guards, emergency stops, lockout procedures or trained people.

Does survey-grade mean the model is certified?

No. Fidelity levels are labels you choose to describe the model. They are not measurements, certifications or a statement that the geometry is accurate.

Where do the sensor and device numbers come from?

From you. The tools ship with no sensor, network, storage or device figures. Enter numbers from your own tests or documents you trust, and treat every result as an estimate.

Is this advice?

No. Nothing here is engineering, safety, legal or professional advice, and nothing here is a safety system. DIGITALTWIN.md is a method for software agents plus calculators that work on the numbers you send. Results are estimates that may be wrong. Check them yourself, and ask a qualified person when it matters.

Does it name brands or show prices?

No. Settings and tools use generic terms, and digitaltwin.md shows no prices, rates or other outside data. Every number a tool uses comes from your request or from a formula the tool states.

Can an agent set up its own settings?

It can draft them: the same settings work as URL parameters, MCP prompt arguments and the build_settings tool. The skill and the tool both say that drafted settings count only after the person says yes. Nothing technical stops an agent from ignoring that, so read what it sends you.

Does a tool result mean something is approved?

No. Tools calculate, compare and check. They don’t approve, enforce or certify anything, and they can be wrong.

Can I change everything?

Yes. Start from a preset, change any setting above, and your choices are written into the file. Or edit the Markdown yourself. It’s MIT; keep your copy next to your code.

Do you track anything?

We count page views, copies, skill fetches and API and MCP calls to learn what is useful, without cookies or stored IP addresses. We never record your settings values or what you send to a tool. Details in the terms.