twin-analyze

Pack digital-twin recordings into deterministic bundles for non-Anthropic models to narrate as advisory reports.

Updated Jul 8, 2026
One-click install
npx skills add https://github.com/arthur0n/xenodot-twin --skill twin-analyze-arthur0n
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: twin-analyze
Source: https://github.com/arthur0n/xenodot-twin/tree/main/plugin/skills/twin-analyze
Command: npx skills add https://github.com/arthur0n/xenodot-twin --skill twin-analyze-arthur0n

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? You have recorded digital-twin telemetry (tag history, binding maps, property sidecars) and want a plain-language analysis of a window of it, but you want that narration done by a swappable non-Anthropic model (OpenRouter, Ollama, Hermes, or even a human pasting into a chat UI) without giving that model any access to your project files. ## Core Features & Use Cases - Deterministic bundle contract: Packs a recording plus optional binding map and property sidecar into one byte-stable, size-budgeted (~100 KB) JSON bundle with sha256 provenance for every input. - Three reviewed task templates: summarize-window, narrate-anomalies, and inspection-report, each embedding mandatory honesty rules (cite only bundle stats, name bound elements, propose no actions). - Framework-written advisory reports: The worker returns only a body string; the framework wraps it in provenance frontmatter (provider, model, bundle hash, window) and writes it to reports/analysis/ and nowhere else. - Use Case: Record a day of plant tag history, run npm run analyze -- --task narrate-anomalies --recording day.ndjson --map binding_map.json, and receive a Markdown report narrating range crossings, sequence gaps, and step deltas, naming the physical element behind each tag. ## Quick Start Ask the agent to run npm run analyze with the summarize-window task on your recording file and binding map to produce an advisory analysis report under reports/analysis/.

Frequently Asked Questions about twin-analyze

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I analyze a digital-twin recording with another AI model?

Run npm run analyze with a task (summarize-window, narrate-anomalies, or inspection-report) and either a prebuilt bundle or a recording file plus optional map and sidecar. The framework packs a deterministic bundle, dispatches it to your configured worker, and writes the report to reports/analysis/.

What models can I use as analysis workers?

The default openai-compatible worker covers any /v1/chat/completions endpoint, including OpenRouter, local Ollama or llama.cpp, and vLLM. A hermes worker reuses the existing Hermes runs-API bridge, and you can also skip the worker entirely and paste the bundle into any chat UI by hand.

How do I configure the analysis worker endpoint?

Add an analysis block to .xenodot.json with worker, apiUrl, apiKey, and model, or set the ANALYSIS_WORKER, ANALYSIS_API_URL, ANALYSIS_API_KEY, and ANALYSIS_MODEL environment variables. Run npm run analysis:check to probe the endpoint with a free GET /v1/models call before spending on a real run.

Can the analysis model modify my project files?

No. Workers return only a body string and carry no filesystem or subprocess access; the framework alone writes the report under reports/analysis/ with provenance frontmatter. Reports are advisory input for humans or gated agents and are never executed or auto-adopted.

Why does bundle creation fail with a size budget error?

Bundles are capped at about 100 KB so they fit any provider's context. When over budget the CLI fails without writing a file and names the levers: narrow the time window, select fewer tags with --tags, or lower --points-per-tag; --allow-oversize overrides with a loud warning.

When should I not use twin-analyze?

Do not use it as a build or verify gate, since analysis writes no project files and verify_twin.sh never runs it. It also does not perform anomaly detection beyond narrating the deterministic stats block, and live-source wiring belongs to the twin-bind-data skill instead.