Developer Tools

Ansight

Name: Ansight
Author: Ansight

Ansight v0.1.0

Ansight gives your coding agent runtime evidence from real mobile apps, so it can debug and verify what actually happened instead of guessing from source code. Install the Ansight SDK into an iOS, Android, .NET MAUI, React Native, Flutter, or Capacitor app, and every development session records logs, network requests, telemetry, screenshots, visual trees, and touches. This plugin's 27 skills let the agent use that evidence through the Ansight CLI: • Set up the CLI and start the local host • Investigate a recorded session: bracket a time window and correlate logs, failed requests, screenshots, and UI trees around an error • Operate a running app: boot a simulator or emulator, launch the app, tap and type through the semantic UI, and capture before-and-after evidence • Call remote tools the app exposes for authoritative in-process state • Annotate sessions for review • Score automation readiness and automation-ID coverage • Author and run repeatable, source-controlled UI tests • Add platform-specific SDK setup and custom remote tools for each supported framework Requirements: the Ansight CLI is installed separately, and live workflows need a development or QA build with the SDK integrated plus execution access to the machine running the Ansight host. Installing the plugin in a cloud-only environment does not by itself provide access to a local device or simulator.

Language: English · Automatically detected from descriptions.

ChatGPT marketplace listing ↗Website ↗Privacy policy ↗Terms ↗Support ↗

Package details

Publisher declarations from the archived package. These are separate from our research and the live service's terms.

Package license: MIT
Package author: Ansight
Keywords: ansight, mobile, debugging, testing, ios, android, maui, react-native, flutter

Declared capabilities

Read
Write

Package observed Sep 30, 2026.

plugin.json .codex-plugin/plugin.json

Files & skills

File archives

Plugin package42 files · 73.4 KBBrowse files →

Skill instructions

ansight-annotate-session7.84 KB

View saved version →

---
name: ansight-annotate-session
description: Add, update, verify, or remove timeline and UI-anchored annotations on one Ansight session. Use for requested review metadata, screenshot geometry, or visual-tree target binding; do not use merely to read annotations, investigate evidence, or operate the live app.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/ansight-install.md → [ansight-install](../ansight-install/SKILL.md)
- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)

# Annotate An Ansight Session

Attach concise review metadata to one exact session. Keep the observed fact in the label, supporting context in notes, and inference explicitly qualified.

## Prerequisites And Routing

CLI annotation requires the Ansight CLI and a session available from local history or an imported archive. The app does not need to remain installed or connected, and its SDK does not need to be present, when annotating retained evidence.

- A UI-anchored annotation also requires a captured screenshot frame; a semantic target requires a corresponding persisted visual-tree snapshot.
- Direct diagnostic annotation tools such as `ansight_inject_annotation` require an available diagnostic tool connection and a resolvable session. A live-only tool path also requires an initialized SDK session.
- If new live evidence must first be captured, use the Ansight Operate Live App skill; if the app lacks the SDK integration, follow `https://www.ansight.ai/skills/ansight-install.md`.
- If the CLI cannot access the session, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.

Do not install or reconnect the SDK solely to add metadata to an existing recorded or imported session.

Annotation writes change retained session metadata. Resolve the session and read existing annotations before creating or replacing one:

```sh
ansight session show <session-id> --json
ansight session annotations <session-id> --json
```

Use a stable, meaningful annotation ID when the note may be updated. A CLI upsert with an existing ID replaces the stored annotation, so preserve any geometry, target, evidence, custom data, and capture metadata that should remain.

## Add A Timeline Annotation With The CLI

Use CLI fields for a point-in-time or range annotation:

```sh
ansight session annotation upsert <session-id> \
--annotation-id <stable-id> \
--label <label> \
--notes <notes> \
--source agent \
--start <utc> \
--end <utc> \
--json
```

Omit `--end` for an instantaneous marker. Use ISO-8601 UTC timestamps taken from session evidence. Do not manufacture precision beyond the evidence that established the moment.

## Ground A UI Annotation

A UI annotation is still time-based, but also anchors geometry to a captured screenshot frame. Establish the frame before writing:

```sh
ansight session images <session-id> --json
ansight session screenshot export <session-id> --frame-id <frame-id> --output <path>
ansight session trees <session-id> --json
```

Choose the frame that displays the observed issue. If the annotation targets a semantic element, choose a visual-tree snapshot whose `screenshotFrameId` matches that frame or whose timestamp clearly corresponds to it. Preserve the snapshot ID, automation ID, element metadata, and bounds returned by that tree.

Geometry coordinates are normalized to the captured frame:

- `x = left / frameWidth`
- `y = top / frameHeight`
- `width = regionWidth / frameWidth`
- `height = regionHeight / frameHeight`

Clamp values to `0.0` through `1.0` and verify the region stays inside the frame. Do not estimate geometry without inspecting the exported frame or trustworthy visual-tree bounds.

## Write A UI Annotation From A CLI JSON File

Create a complete annotation JSON file and pass it to the CLI:

```json
{
"annotationId": "checkout-submit-disabled",
"startUtc": "2026-08-28T03:14:15Z",
"label": "Submit button remained disabled",
"source": "agent",
"notes": "Observed after the address request completed.",
"geometry": [
{
"geometryId": "checkout-submit-disabled-rect",
"frameId": "<frame-id>",
"capturedAtUtc": "2026-08-28T03:14:15Z",
"kind": 1,
"x": 0.62,
"y": 0.71,
"width": 0.25,
"height": 0.08,
"text": "Disabled submit control",
"strokeColor": "#FF3B30",
"strokeWidth": 2
}
],
"target": {
"kind": "visualTreeElement",
"source": "agent",
"targetId": "<target-id>",
"visualTreeSnapshotId": "<snapshot-id>",
"type": "Button",
"elementKind": "button",
"label": "Submit",
"automationId": "CheckoutSubmit",
"normalizedBounds": {
"x": 0.62,
"y": 0.71,
"width": 0.25,
"height": 0.08
}
}
}
```

Then upsert and verify:

```sh
ansight session annotation upsert <session-id> --file <annotation.json> --json
ansight session annotations <session-id> --json
```

The CLI file contract uses `geometry`, singular. Its geometry enum is numeric: point `0`, rectangle `1`, ellipse `2`, free draw `3`, line `4`, and arrow `5`. Each geometry requires a unique `geometryId`, exact `frameId`, `capturedAtUtc`, `kind`, `x`, and `y`; rectangles and ellipses also need width and height, while free-draw, line, and arrow shapes need normalized points appropriate to the shape.

A target is optional. Include it only when it was derived from an actual visual-tree snapshot. Geometry identifies what region to draw, while the target records semantic element context.

## Use Diagnostic Annotation Tools Without Mixing Schemas

When the client exposes `ansight_inject_annotation`, use that tool directly for creation. It accepts `geometries`, plural, and string kinds `point`, `rectangle`, `ellipse`, or `freeDraw`. It can resolve by `sessionId` or an unambiguous `appId` and can default `startUtc` to the session's latest timestamp.

Use `ansight_update_annotation` for a partial update when available. It supports source guards and explicit clear operations, avoiding accidental loss of fields. Use `ansight_delete_annotation` only for an authorized removal.

Do not copy a diagnostic-tool `geometries` payload into the CLI `--file` contract, and do not send CLI numeric kinds to the diagnostic tools.

## Preserve Existing Annotations During CLI Updates

Before updating an existing ID through the CLI:

1. Read the annotation with `session annotations`.
2. Copy the full existing object into a working JSON file.
3. Change only the intended fields.
4. Upsert with `--file`.
5. Read it back and compare the ID, timestamps, geometry frame IDs, target snapshot ID, and source.

Do not update a UI annotation with only `--label` and `--start`; that replacement would omit its existing geometry and target.

## Verify Or Remove

Verification should confirm that the stored annotation belongs to the intended session and that its time and frame fall within the capture. Export the referenced screenshot again when spatial placement matters.

Delete through the CLI only when explicitly requested:

```sh
ansight session annotation delete <session-id> <annotation-id> --json
```

Report the session ID, annotation ID, source, time range, frame and snapshot IDs, geometry kind and normalized bounds, verification performed, and whether an existing annotation was replaced or removed.

Referenced files: 1

ansight-app-inspection9.77 KB

View saved version →

---
name: ansight-app-inspection
description: Route an ambiguous Ansight app request to the narrowest live-operation, remote-tool, session-investigation, annotation, readiness-audit, workspace-automation, or platform-inspection skill. Use only when the request does not already identify the required Ansight workflow.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md → [ansight-operate-live-app](../ansight-operate-live-app/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md → [ansight-use-remote-app-tools](../ansight-use-remote-app-tools/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md → [ansight-investigate-session](../ansight-investigate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md → [ansight-annotate-session](../ansight-annotate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-assess-automation-readiness/SKILL.md → [ansight-assess-automation-readiness](../ansight-assess-automation-readiness/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-ui-testing/SKILL.md → [ansight-ui-testing](../ansight-ui-testing/SKILL.md)
- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)
- https://www.ansight.ai/skills/dotnet/ansight-app-inspection-dotnet.md → [ansight-app-inspection-dotnet](../ansight-app-inspection-dotnet/SKILL.md)
- https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md → [ansight-app-inspection-ios](../ansight-app-inspection-ios/SKILL.md)
- https://www.ansight.ai/skills/android/ansight-app-inspection-android.md → [ansight-app-inspection-android](../ansight-app-inspection-android/SKILL.md)
- https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md → [ansight-app-inspection-react-native](../ansight-app-inspection-react-native/SKILL.md)
- https://www.ansight.ai/skills/flutter/ansight-app-inspection-flutter.md → [ansight-app-inspection-flutter](../ansight-app-inspection-flutter/SKILL.md)
- https://www.ansight.ai/skills/cordova/ansight-app-inspection-cordova.md → [ansight-app-inspection-cordova](../ansight-app-inspection-cordova/SKILL.md)


# Ansight App Inspection Router Skill

Use this skill to choose a workflow, not to perform one. Once a specialist is selected, load it completely, stop following this router, and do not route back here from that specialist.

## Goal

Select one primary skill that owns the requested outcome. Add another skill only when the request crosses a real capability boundary.

## Choose The Primary Skill

| Request | Use this skill |
| --- | --- |
| Start or reuse the host, boot a target, launch or stop an app, resolve a live session, use tree-first interactive actions/batches with screenshot fallback, and verify | Installed `$ansight-operate-live-app`; fallback: `https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md` |
| Discover and call bundled or app-specific tools exposed by a connected app | Installed `$ansight-use-remote-app-tools`; fallback: `https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md` |
| Inspect a live or recorded session, correlate telemetry and other evidence, or create a non-destructive session slice | Installed `$ansight-investigate-session`; fallback: `https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md` |
| Add or update a timeline annotation, screenshot geometry, or visual-tree target | Installed `$ansight-annotate-session`; fallback: `https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md` |
| Score integration strength or automation readiness and produce a remediation plan | Installed `$ansight-assess-automation-readiness`; fallback: `https://www.ansight.ai/skills/agents/ansight-assess-automation-readiness/SKILL.md` |
| Create or maintain tests, tasks, triggers, Trends definitions, sanitizers, schemas, or workspace registration | Installed `$ansight-ui-testing`; fallback: `https://www.ansight.ai/skills/agents/ansight-ui-testing/SKILL.md` |
| Prepare the CLI, resident host, or workstation dependencies | Installed `$ansight-cli-setup`; fallback: `https://www.ansight.ai/skills/ansight-cli-setup.md` |

This table selects ownership, not a sequence. The chosen specialist owns its prerequisite checks, authorization boundaries, commands, verification, and reporting.

## Combine Skills Sparingly

- Pair live operation with remote tools only when the request needs both visible UI behavior and in-process state or operations.
- Pair a core evidence skill with one platform inspection skill only when framework internals, platform logging, reflection suites, or platform-specific tool semantics matter.
- Pair investigation with annotation only when the user asks both to analyze evidence and to write review metadata. Reading an annotation does not require the annotation skill.
- A readiness audit may use live operation, remote tools, investigation, or a platform skill as evidence helpers, but the readiness skill remains the owner of scoring and reporting. Load those helpers directly; never reload this router.
- Workspace authoring does not require live-operation or investigation skills unless the user also requests execution or runtime verification.

## Platform Inspection Skills

| App shape | Use this skill |
| --- | --- |
| .NET MAUI, .NET for Android, .NET for iOS, .NET Mac Catalyst | `https://www.ansight.ai/skills/dotnet/ansight-app-inspection-dotnet.md` |
| Native iOS SwiftUI or UIKit | `https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md` |
| Native Android Kotlin or Java | `https://www.ansight.ai/skills/android/ansight-app-inspection-android.md` |
| React Native or Expo development build with iOS and Android native projects | `https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md` |
| Flutter with Android and/or iOS targets | `https://www.ansight.ai/skills/flutter/ansight-app-inspection-flutter.md` |
| Cordova-family or Ionic app built with Capacitor 8 | `https://www.ansight.ai/skills/cordova/ansight-app-inspection-cordova.md` |

If more than one app or platform is present, ask which running app/session should be inspected unless the user supplied an explicit app id, session id, device, or app name.

## Detection Hints

Inspect the repo, `ansight app list --json`, and focused `ansight app tools
<session-id> --query <terms> --detail summary --json` results before choosing.
Do not load an unfiltered full tool catalog merely to identify a platform:

- `.csproj`, `MauiProgram.cs`, `TargetFramework` values such as `net*-android`, `net*-ios`, or `net*-maccatalyst`: use the .NET inspection skill.
- `.xcodeproj`, `.xcworkspace`, `Package.swift`, `Podfile`, `Info.plist`, SwiftUI `App`, or UIKit `AppDelegate` without React Native app files: use the native iOS inspection skill.
- `settings.gradle`, `build.gradle`, `build.gradle.kts`, `AndroidManifest.xml`, and Kotlin or Java `Application` without React Native app files: use the native Android inspection skill.
- `package.json` with `react-native` or `expo`, generated `ios/` and `android/` projects, `metro.config.*`, or `@react-native/*`: use the React Native inspection skill.
- `pubspec.yaml` with Flutter, `lib/main.dart`, and Flutter target folders: use the Flutter inspection skill.
- `package.json` with `@capacitor/core`, `capacitor.config.*`, and native target folders: use the Cordova / Capacitor inspection skill.

React Native and Expo, Flutter, and Capacitor take precedence over their generated native target folders. Expo Go cannot load the native bridge; only route Expo development builds. A .NET MAUI app takes precedence over its `Platforms/iOS` and `Platforms/Android` folders.

When source-code clues are unavailable, use the Ansight app/session metadata and remote app tool catalog:

- MAUI or `.NET` names, `maui.*` tools, or .NET package metadata: .NET.
- React tool ids such as `react.get_component_tree` or `react.get_shadow_tree`: React Native.
- Flutter tool ids such as `flutter.get_widget_tree` or `flutter.find_widgets`: Flutter.
- DOM tool ids such as `dom.get_document` with adapter metadata `@ansight/capacitor`: Cordova / Capacitor.
- Native iOS bundle ids, UIKit visual-tree metadata, or Swift package names: native iOS.
- Android package ids, Android view hierarchy metadata, or Gradle module names: native Android.
- `reflect.*` tool ids indicate a platform reflection suite is installed; route by app/session metadata and neighboring platform tool families before using reflection.

## Route And Stop

1. Classify the requested outcome and select one primary skill from the table.
2. Inspect repository markers only when a platform skill may be required.
3. Add at most the directly needed platform or evidence helper skills.
4. Let the selected specialist route to CLI setup or SDK installation if its actual prerequisites are missing.
5. Stop following this router and continue with the selected skill or deliberate combination.

If platform detection remains ambiguous, generic evidence skills can still work with standard Ansight surfaces. Ask the user to choose a platform only before a platform-specific operation would materially change the workflow.

ansight-app-inspection-android4.55 KB

View saved version →

---
name: ansight-app-inspection-android
description: Add native Android Kotlin and Java semantics to an Ansight operation. Use alongside a selected core Ansight workflow when Android view or Compose rendering, preferences, storage, reflection, ADB fallback, or Android tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md → [ansight-operate-live-app](../ansight-operate-live-app/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md → [ansight-use-remote-app-tools](../ansight-use-remote-app-tools/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md → [ansight-investigate-session](../ansight-investigate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md → [ansight-annotate-session](../ansight-annotate-session/SKILL.md)

# Ansight Android Inspection Semantics

Use this companion skill for native Android Kotlin or Java evidence. Do not use it for React Native, .NET for Android, Flutter, native iOS, or generic JVM work.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these Android semantics:

- live lifecycle or visible UI interaction: `https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md`
- bundled or app-specific remote tools: `https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md`
- live or recorded evidence investigation: `https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md`
- annotation writes: `https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md`

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret Android-specific evidence or choose among cataloged Android tool families.

## Interpret Android UI Evidence

- Use cataloged native `ui.*` tools when the Android hierarchy, screenshots, node details, overlays, platform widgets, or native hit testing are material.
- Treat native visual-tree output as the rendered Android hierarchy. For Jetpack Compose or mixed UIs, do not infer the complete composable source structure or state from host-view evidence alone.
- Correlate screenshots with the corresponding tree when layout, labels, visibility, hit targets, or navigation state matter.

## Interpret Android State And Tools

- Treat native UI, database, file, SharedPreferences, secure-storage, artifact, and `reflect.*` tools as optional catalog entries rather than guaranteed Android capabilities.
- Use SharedPreferences and secure-storage tools only for stores, keys, or prefixes explicitly exposed by the catalog and app guard.
- Use `reflect.*` only against returned registered roots. It normally comes from a Debug or explicit local-development dependency such as `ai.ansight:ansight-tools-reflection-android`.
- An absent tool family may reflect build-variant gating, pairing policy, or local guards; report the observed catalog rather than changing the integration automatically.

## Emulator And Device Semantics

- Prefer Ansight lifecycle, semantic UI, and evidence surfaces before direct ADB access.
- Use `adb`, emulator or device logs, Gradle output, app-data extraction, or source inspection only after the owning core skill identifies a concrete Ansight capability gap.
- State whether a fallback observed the Android process, operating-system logs, package data, build output, or UI outside Ansight.

## Report Android-Specific Evidence

In addition to the core skill's report, name the Android application ID and device or emulator when available, distinguish native hierarchy evidence from Compose inference, and identify any storage, reflection, or ADB fallback surface used.

ansight-app-inspection-cordova4.44 KB

View saved version →

---
name: ansight-app-inspection-cordova
description: Add Capacitor DOM and native-platform semantics to an Ansight operation. Use alongside a selected core Ansight workflow when WebView DOM, JavaScript errors, native hierarchy, bridge state, or DOM tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md → [ansight-operate-live-app](../ansight-operate-live-app/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md → [ansight-use-remote-app-tools](../ansight-use-remote-app-tools/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md → [ansight-investigate-session](../ansight-investigate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md → [ansight-annotate-session](../ansight-annotate-session/SKILL.md)


# Ansight Cordova / Capacitor Inspection Semantics

Use this companion skill for supported Cordova-family apps built with Capacitor. Do not infer support for a classic Apache Cordova app or a web-only project without the Ansight Capacitor bridge.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these Capacitor semantics:

- live lifecycle or visible UI interaction: `https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md`
- bundled or app-specific remote tools: `https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md`
- live or recorded evidence investigation: `https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md`
- annotation writes: `https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md`

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret Capacitor-specific evidence or choose among cataloged DOM and native tool families.

## Interpret DOM And Native Evidence

- Use cataloged `dom.get_document`, `dom.inspect_node`, or `dom.query_selector` when DOM ownership, WebView structure, attributes, styles, or bridge-rendered content are material.
- Use cataloged native `ui.*` tools for UIKit or Android hierarchy, screenshots, native overlays, platform views, and rendering or hit-testing outside the DOM.
- Treat DOM nodes, native nodes, automation IDs, and reflection roots as separate namespaces unless a returned schema explicitly connects them.
- Compare DOM and native evidence when diagnosing a mismatch between WebView state and rendered platform UI.
- `dom.invoke_action` and similar DOM actions are remote writes. Keep semantic device interaction as the default for a visible user flow and follow the core remote-tool skill for authorized internal operations.

## JavaScript, Bridge, And Fallback Semantics

A paired build may stream captured JavaScript errors, app-provided logs, Ansight diagnostics, telemetry, screenshots, touches, and tool results. Use browser devtools only when WebView console, network, or runtime evidence unavailable through Ansight is required; use Xcode or Android system logs for complete native process output.

Use browser devtools, Xcode, ADB, simulator or emulator tools, app-container access, or source inspection only after the owning core skill identifies a concrete Ansight capability gap. Report whether the gap was in the DOM adapter, native hierarchy, bridge, cataloged tools, retained evidence, or device control.

## Report Capacitor-Specific Evidence

In addition to the core skill's report, name the native target, distinguish DOM evidence from native hierarchy evidence, and identify any JavaScript, bridge, native, or fallback surface used.

ansight-app-inspection-dotnet4.75 KB

View saved version →

---
name: ansight-app-inspection-dotnet
description: Add .NET MAUI and .NET mobile platform semantics to an Ansight operation. Use alongside a selected core Ansight workflow when MAUI hierarchy, bindings, handlers, native rendering, reflection, or .NET tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md → [ansight-operate-live-app](../ansight-operate-live-app/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md → [ansight-use-remote-app-tools](../ansight-use-remote-app-tools/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md → [ansight-investigate-session](../ansight-investigate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md → [ansight-annotate-session](../ansight-annotate-session/SKILL.md)


# Ansight .NET Inspection Semantics

Use this companion skill for .NET MAUI, .NET for Android, .NET for iOS, or .NET Mac Catalyst evidence. Do not use it for native-only iOS or Android, React Native, Flutter, server, console, or web apps.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these .NET semantics:

- live lifecycle or visible UI interaction: `https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md`
- bundled or app-specific remote tools: `https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md`
- live or recorded evidence investigation: `https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md`
- annotation writes: `https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md`

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret .NET-specific evidence or choose among cataloged .NET tool families.

## Interpret .NET UI Evidence

- Prefer cataloged `maui.*` tools when the question requires MAUI page, element, bindable-property, binding, resource, layout, handler, navigation, or binding-context semantics that the unified tree does not expose.
- Use cataloged native `ui.*` tools when the issue concerns the rendered UIKit or Android hierarchy, native screenshots, platform widgets, overlays, or native hit testing.
- Treat MAUI, native, and reflection identifiers as separate namespaces unless a returned schema explicitly connects them.
- Correlate screenshots with the relevant MAUI or native tree when layout, visibility, labels, hit targets, or navigation state matter.

## Interpret .NET State And Tools

- Treat `maui.*`, `ui.*`, database, file, preference, secure-storage, artifact, and `reflect.*` families as optional catalog entries rather than guaranteed .NET capabilities.
- Use `reflect.*` only against roots returned by `reflect.list_roots`. It normally comes from `Ansight.Tools.Reflection` or an all-in-one package enabled in a Debug or explicit local-development configuration.
- An absent reflection catalog may mean the development-only suite, runtime policy, or local guard is intentionally unavailable; report that state instead of enabling it automatically.
- MAUI operations such as setting bindable properties, inflating XAML, adding elements, invoking element actions, or invoking binding-context commands are remote mutations. Follow the core remote-tool skill's authorization, baseline, verification, and cleanup rules.

## Platform Fallbacks

Use direct simulator, emulator, device, app-container, or source inspection only after the owning core skill identifies a concrete Ansight capability gap. Report whether the gap was in the MAUI view, native hierarchy, cataloged tools, retained evidence, or device control, and identify the fallback used.

## Report .NET-Specific Evidence

In addition to the core skill's report, name the observed .NET target shape and distinguish evidence from the MAUI tree, native hierarchy, reflection roots, or other cataloged .NET tool families.

ansight-app-inspection-flutter4.24 KB

View saved version →

---
name: ansight-app-inspection-flutter
description: Add Flutter widget and native-platform semantics to an Ansight operation. Use alongside a selected core Ansight workflow when widget hierarchy, navigation, native rendering, physical-device logging, or Flutter tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md → [ansight-operate-live-app](../ansight-operate-live-app/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md → [ansight-use-remote-app-tools](../ansight-use-remote-app-tools/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md → [ansight-investigate-session](../ansight-investigate-session/SKILL.md)
- https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md → [ansight-annotate-session](../ansight-annotate-session/SKILL.md)


# Ansight Flutter Inspection Semantics

Use this companion skill for Flutter apps targeting iOS or Android. Do not route a native-only app here merely because generated Flutter platform folders are present elsewhere in the repository.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these Flutter semantics:

- live lifecycle or visible UI interaction: `https://www.ansight.ai/skills/agents/ansight-operate-live-app/SKILL.md`
- bundled or app-specific remote tools: `https://www.ansight.ai/skills/agents/ansight-use-remote-app-tools/SKILL.md`
- live or recorded evidence investigation: `https://www.ansight.ai/skills/agents/ansight-investigate-session/SKILL.md`
- annotation writes: `https://www.ansight.ai/skills/agents/ansight-annotate-session/SKILL.md`

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret Flutter-specific evidence or choose among cataloged Flutter and native tool families.

## Interpret Flutter Evidence

- Use cataloged `flutter.get_widget_tree`, `flutter.inspect_widget`, `flutter.find_widgets`, or `flutter.get_navigation_state` only when widget ownership, Flutter layout, widget state, or navigation semantics are material.
- Use cataloged native `ui.*` tools for UIKit or Android hierarchy, screenshots, platform views, overlays, and native rendering or hit-testing issues.
- Treat Flutter widget IDs, native nodes, automation IDs, and reflection roots as separate namespaces unless a returned schema explicitly connects them.
- Compare widget and native evidence when diagnosing a mismatch between Flutter state and rendered platform UI.
- Treat Flutter, native, storage, artifact, and `reflect.*` families as optional catalog entries, and treat any Flutter action tool as a remote mutation.

## Physical Device And Fallback Semantics

A paired physical build can stream app-provided logs, Ansight diagnostics, telemetry, screenshots, touches, and tool results. Use Xcode device logging or Android system logs only when complete OS or process output not captured by the app is required.

Use Flutter tooling, Xcode, ADB, simulator or emulator tools, device logs, or source inspection only after the owning core skill identifies a concrete Ansight capability gap. Report the gap and exact fallback.

## Report Flutter-Specific Evidence

In addition to the core skill's report, name the Flutter target platform, distinguish widget-tree evidence from native hierarchy evidence, and identify any Flutter tool or platform fallback used.

ansight-app-inspection-ios4.87 KB

View saved version →

---
name: ansight-app-inspection-ios
description: Add native iOS SwiftUI and UIKit semantics to an Ansight operation. Use alongside a selected core Ansight workflow when UIKit hierarchy, SwiftUI hosting, Apple storage, Simulator control, reflection, or iOS tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

# Ansight iOS Inspection Semantics

Use this companion skill for native iOS SwiftUI or UIKit evidence. Do not use it for React Native, .NET for iOS, Flutter, native Android, or generic Swift package work.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these iOS semantics:

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret iOS-specific evidence or choose among cataloged iOS tool families.

## Interpret iOS UI Evidence

- Use cataloged native `ui.*` tools when UIKit hierarchy, screenshots, node details, overlays, z-order, platform widgets, or native hit testing are material.
- SwiftUI content may appear through UIKit hosting containers. Treat the native visual tree as the rendered hierarchy, not the original SwiftUI source or complete SwiftUI state.
- Correlate screenshots with the corresponding tree when layout, labels, visibility, hit targets, or navigation state matter.

## Interpret iOS State And Tools

- Treat native UI, database, file, UserDefaults, Keychain, artifact, and `reflect.*` tools as optional catalog entries rather than guaranteed iOS capabilities.
- Use UserDefaults and Keychain tools only for stores, suites, services, accounts, and keys explicitly exposed by the catalog and app guard.
- Use `reflect.*` only against returned registered roots. It normally comes from a Debug or explicit local-development product such as `AnsightToolsReflection`.
- An absent tool family may reflect build gating, pairing policy, or local guards; report the observed catalog rather than changing the integration automatically.

## Simulator And Device Semantics

- For iOS Simulator touch and control, prefer Ansight's native SimulatorKit HID bindings. Do not introduce Appium for a simulator when that binding is available.
- Treat `xcrun simctl` as a lifecycle, discovery, screenshot, pasteboard, and simulator-state fallback rather than a touch-injection mechanism.
- A paired physical build can provide app-supplied logs and Ansight evidence. Use Xcode device logging only when complete OS or process console output not captured by the app is required.
- Reserve Appium or XCUITest for physical-device needs or an explicit, reported fallback.

## Platform Fallbacks

Use Xcode, `simctl`, app-container access, device logs, or source inspection only after the owning core skill identifies a concrete Ansight capability gap. Report the gap and the exact fallback used.

## Report iOS-Specific Evidence

In addition to the core skill's report, name the bundle identifier and device or simulator when available, distinguish SwiftUI inference from observed UIKit hierarchy, and identify any native, storage, reflection, or fallback surface used.

ansight-app-inspection-react-native5.08 KB

View saved version →

---
name: ansight-app-inspection-react-native
description: Add React Native and Expo development-build semantics to an Ansight operation. Use alongside a selected core Ansight workflow when React component, shadow-tree, native hierarchy, navigation, memory, or React tool behavior affects interpretation; do not use as the primary live-operation, remote-tool, session-investigation, or annotation workflow.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

# Ansight React Native Inspection Semantics

Use this companion skill for React Native apps and Expo development builds with native Ansight integration. Expo Go cannot load the native bridge. Do not use this skill for native-only iOS or Android, .NET, Flutter, or web-only projects.

## Keep The Core Workflow In Charge

Select the skill that owns the requested outcome before applying these React Native semantics:

The selected core skill owns session selection, authorization, command procedure, verification, reporting, and any relevant workspace reuse. Use this skill only to interpret React Native-specific evidence or choose among cataloged React and native tool families.

## Choose The Correct Tree

- Use a cataloged React component tree for composite-component ownership, logical structure, and explicitly available props or state.
- Use a cataloged React shadow tree for the committed host layout with composite components flattened out.
- Use cataloged native `ui.*` tools for UIKit or Android hierarchy, native screenshots, platform widgets, overlays, and native rendering or hit-testing issues.
- Treat React component IDs, shadow nodes, native nodes, automation IDs, and reflection roots as separate namespaces unless a returned schema explicitly connects them.
- Compare React and native evidence when diagnosing a mismatch between JavaScript state and rendered platform UI.

## Interpret React Native Tools

- Treat `react.*`, native UI, storage, artifact, custom, and `reflect.*` tools as optional catalog entries rather than guaranteed React Native capabilities.
- Use `react.get_component_tree`, `react.get_shadow_tree`, `react.find_components`, `react.get_component`, or `react.get_navigation_state` only when the current catalog returns them.
- Navigation state requires an app-registered navigation reference. Props and state may be absent or sanitized; do not treat omission as a runtime failure.
- Use React Native memory channels from retained telemetry when available before assuming JavaScript heap data requires a separate sampler.
- `react.invoke_component_action` and other React actions are remote writes. Require the action to be cataloged and app-allow-listed, then follow the core remote-tool skill's authorization and verification rules.
- Native `reflect.*` tools operate only on registered native roots and should remain development-only, such as under `__DEV__` or a native Debug build.

## Platform Fallbacks

Use Metro output, native build output, Xcode, ADB, simulator or emulator tools, app-container access, or source inspection only after the owning core skill identifies a concrete Ansight capability gap. Report whether the gap was in the React tree, native hierarchy, JavaScript or native tool catalog, retained evidence, or device control.

## Report React Native-Specific Evidence

In addition to the core skill's report, name the React Native App ID and native bundle or application ID when available, identify every tree type used, and distinguish React inference from observed native evidence.

ansight-assess-automation-readiness19.4 KB

View saved version →

---
name: ansight-assess-automation-readiness
description: Audit and score an app's Ansight integration strength and automation readiness. Use for a requested evidence-backed readiness score, automation-ID coverage assessment, blocker analysis, comparison, or prioritized remediation plan; do not use for routine app inspection or workspace authoring.
---

## OpenAI plugin integration

# Assess Ansight Automation Readiness

Produce an evidence-backed audit with separate scores for Ansight Integration Strength and Automation Readiness. Treat a rich telemetry integration and a reliably automatable app as related but distinct outcomes.

## Preserve Audit Safety

- Audit read-only evidence by default.
- Do not create tests, tasks, triggers, Trends definitions, identifiers, or app tools unless the user also requests implementation.
- Do not sign in, purchase, delete, submit, or otherwise mutate meaningful app data merely to improve audit coverage.
- Use safe navigation only when the user has authorized live interaction. Stop before destructive or externally visible actions.
- Treat remote write tools as privileged. Report their schemas and guards without invoking them unless invocation is necessary and authorized.
- Do not award runtime points from source code alone. Mark implemented-but-unverified capabilities explicitly.

## Establish Scope

1. Resolve the exact repository, app ID, build, platform, device or simulator, and session when available.
2. Select one to three representative critical flows. Prefer a primary user journey, a data-entry or state-changing journey, and a recovery or error journey.
3. Name the screen states sampled in each flow. Avoid claiming whole-app coverage from one screen.
4. Record available evidence modes: `source`, `live`, `replay`, and `repeat_run`.
5. If multiple live sessions match, do not guess. Narrow by explicit app, session, platform, device, or build evidence before proceeding.
6. Score materially different build profiles separately. If the user does not specify one, audit the development or test build intended for automation and name production or other profiles as unscored. Do not blend a development integration with a production build that intentionally excludes Ansight.

This skill owns the audit, scoring, and report. Load evidence helpers directly when needed: Ansight Operate Live App for lifecycle or visible interaction, Ansight Remote App Tools for in-process state, Ansight Investigate Session for retained evidence, and an already available platform inspection skill for platform-specific semantics. Do not load the Ansight App Inspection router from this skill. Use the Ansight Workspace Automation skill only when the user separately asks to create or run repository-owned automation.

## Gather Evidence

### Inspect The Repository

Locate SDK initialization, app identity, development-build guards, tool registration, logging or telemetry bridges, and existing `ansight/tests`, `ansight/tasks`, `ansight/triggers`, and `ansight/trends` definitions. Search for platform-native identifier APIs and shared control wrappers, but use source matches only as leads.

Do not calculate identifier coverage from raw text-search counts. A declaration may not render, a shared component may cover many instances, and a platform identifier may not map to Ansight's live `automationId` field.

### Inspect Ansight Runtime Evidence

Prefer structured Ansight CLI evidence before direct device or simulator access:

1. Discover apps and live or captured sessions.
2. Select the exact target and inspect app/session state.
3. Discover the live app-tool catalog rather than assuming a tool exists.
4. Confirm available logs, lifecycle or navigation events, telemetry, screenshots, visual trees, artifacts, data inspection, and custom app tools.
5. Inspect schemas and the ordered `read`, `write`, or `critical` policy for app tools.
6. Record an evidence locator for every scored claim: file and line, session and timestamp, tool result, screenshot, or automation run.

Start with:

```sh
ansight host status --json
ansight app list --json
ansight session list --connected --json
ansight session show <session-id> --json
ansight app tools <session-id> --policy read --detail summary --include-unavailable --max-results 50 --json
ansight app tools <session-id> --policy write --detail summary --include-unavailable --max-results 50 --json
ansight app tools <session-id> --policy critical --detail summary --include-unavailable --max-results 50 --json
```

These summaries partition direct matches by policy without loading every
argument and result schema; supplemental prerequisite entries can have another
policy. If a response is truncated, refine it with `--feature`, `--category`,
`--id-prefix`, or `--query`. Retrieve
`--tool-id <exact-id> --detail full` only for tools that materially support a
scored claim or blocker, adding `--include-unavailable` when the denial itself
is the evidence.

### Measure UI Addressability

For each sampled screen state, inventory every eligible target:

- include actionable controls, navigation targets, input fields, important status or result regions, and elements needed for assertions;
- exclude decorative elements that neither receive actions nor establish a meaningful postcondition;
- count repeated rows individually when automation must distinguish them;
- require a selector to resolve uniquely within the rendered state, either directly or through a stable contextual ancestor.

Count a target as having a stable unique automation ID only when its observed Ansight `automationId` is:

- present in the live or captured visual tree;
- unique in the state where it is used;
- attached to the element that receives the action or exposes the assertion state;
- semantic and independent of localized display text, list position, timestamps, random values, or mutable user content; and
- expected to survive relaunches and ordinary UI refactors.

Calculate:

```text
automation ID coverage = stable unique ID targets / eligible targets
```

Report both counts and the percentage. Also report duplicate critical IDs, missing critical IDs, and IDs that exist but are volatile or attached at the wrong level. Prefer an ID backed by stable domain identity for repeated content; use a stable ancestor plus another exact selector when a globally unique child ID is inappropriate.

### Verify Actionability And Determinism

When safe interaction is authorized, verify focused queries before broad tree dumps. Confirm that representative controls can be queried and acted on, and that the resulting state can be observed through a stable condition. Do not treat a delivered tap or typed value as success without checking its postcondition.

Look for:

- query, assertion, tap, typing, secret entry, scrolling, back, launch, and wait capabilities;
- explicit loading, empty, success, validation, and error states that can be awaited without fixed sleeps;
- repeatable authentication, test-data seeding, reset, cleanup, and environment selection;
- guarded app tools that expose domain state or deterministic setup more reliably than screen scraping;
- named assertions and bounded capabilities in repository tests or tasks;
- event-driven diagnostic enrichment from triggers;
- reusable timing windows from spans;
- deterministic telemetry budgets from Trends definitions; and
- consistent results across at least two clean repetitions when claiming repeatability.

## Score The Audit

Use the rubric below before assigning points or a readiness label. Score only demonstrated evidence, give partial credit when appropriate, and list unverified implementation separately from earned points.

Create an audit JSON matching the rubric. Keep temporary audit input outside the app repository unless the user requests it as a deliverable. Resolve the scorer relative to this `SKILL.md`, then run:

```bash
python3 <skill-directory>/scripts/score_readiness.py <audit.json>
```

Use `--format json` when structured output is more useful. Pass `-` as the audit path to read JSON from standard input when a no-write environment can stream the input. If neither a temporary file nor standard input is available, calculate from the same rubric manually and disclose that the scorer was not executed. Treat the script's applied gates and calculated totals as authoritative whenever it is run. Do not manually raise a gated outcome.

## Report The Result

Lead with the outcome, evidence confidence, scope, and material blockers. Include:

1. overall score and label;
2. Integration Strength out of 50;
3. Automation Readiness out of 50 after gates;
4. evidence modes and confidence;
5. sampled flows and screen states;
6. automation-ID numerator, denominator, percentage, duplicates, and critical misses;
7. a criterion table containing score, evidence, and gap;
8. critical blockers and unverified claims;
9. prioritized fixes ordered by impact and effort; and
10. the next three automation scenarios that become viable after the fixes.

Use these remediation priorities:

- **P0:** unsafe control surface, no observable UI, no actionable UI, unstable app identity, or missing identifiers on critical actions and assertions.
- **P1:** insufficient identifier coverage, duplicate IDs, nondeterministic setup, unobservable loading/error states, or missing postconditions.
- **P2:** incomplete telemetry, artifacts, repository automation assets, cross-platform evidence, or convenience tooling.

Never describe an app as automation-ready when a rubric gate limits it to `Conditional` or `Not ready`. When only source evidence is available, provide the score as a provisional baseline and name the exact live checks required to raise confidence.

## Apply The Rubric

Use the strongest available evidence in this order:

1. successful repeated automation run;
2. focused live Ansight query or action plus verified postcondition;
3. captured session evidence with timestamps;
4. source implementation and build or static validation; and
5. documentation or assertion without verification.

Source evidence can prove that integration code exists, but not that the running app exposes it. Give source-only claims no more than half of the applicable runtime-focused criterion and list the missing live verification. Use partial points, keep every score within its maximum, and attach evidence for every positive score.

### Integration Strength: 50 Points

#### `connection_and_identity`: 10

- **9–10:** The exact app and build are discoverable; identity is stable; live/replay sessions reconnect and carry useful platform, version, device, and environment metadata.
- **6–8:** Connection and identity work, but some metadata, lifecycle behavior, or verification is incomplete.
- **3–5:** SDK/setup is present but discovery, identity, or session continuity is fragile or source-only.
- **0–2:** No reliable evidence that the CLI host can identify and inspect the intended app.

#### `runtime_observability`: 15

- **13–15:** Logs, errors, lifecycle/navigation or domain events, telemetry, screenshots, and time correlation provide a useful causal timeline.
- **9–12:** Most core evidence is present, with one meaningful blind spot or inconsistent capture.
- **5–8:** Basic logs or screenshots exist, but diagnosis still depends heavily on reproduction or inference.
- **0–4:** Runtime evidence is absent, noisy without context, or not available through Ansight.

#### `inspection_surface`: 15

- **13–15:** Current UI hierarchy plus relevant app-owned state, files, preferences, database data, artifacts, or framework-specific inspection are available with clear schemas.
- **9–12:** UI inspection is strong but deeper state is limited, or useful tools exist with notable schema/coverage gaps.
- **5–8:** A partial tree or a small inspection surface exists, but critical state remains opaque.
- **0–4:** The agent is effectively limited to pixels, generic logs, or direct device access.

#### `guarded_app_control`: 10

- **9–10:** Narrow, structured app tools cover needed setup or domain actions; policies are explicit; mutating/debug tools are development-gated and least-privilege.
- **6–8:** Useful control exists with minor schema, guard, or coverage limitations.
- **3–5:** Control is ad hoc, overly broad, source-only, or difficult to use safely.
- **0–2:** No app-owned control exists where needed, or reachable write tools are unsafe.

### Automation Readiness: 50 Points

#### `ui_addressability`: 20

- **18–20:** At least 90% of eligible critical-flow targets have stable unique automation IDs; no critical duplicates; action and assertion targets are correctly attached.
- **14–17:** At least 80% coverage with no unresolved duplicates on critical targets.
- **10–13:** At least 70% coverage, or good coverage with some volatile, misplaced, or ambiguous IDs.
- **5–9:** At least 40% coverage; automation depends substantially on text, coordinates, hierarchy position, or OCR.
- **0–4:** Less than 40% coverage or no trustworthy visual-tree selector surface.

Do not award a band whose percentage threshold is not met. Use the lower band even if the existing IDs are high quality.

#### `actionability`: 10

- **9–10:** Representative controls can be queried, tapped, typed into, scrolled to, and asserted as applicable; every action has an observable postcondition.
- **6–8:** The main happy path works but one control family, gesture, secret input, or state transition is unreliable.
- **3–5:** Only a narrow subset works or actions depend on coordinates/text and weak postconditions.
- **0–2:** The agent cannot safely operate and verify the sampled critical flow.

#### `deterministic_state`: 10

- **9–10:** Launch state, authentication, data seeding, reset/cleanup, environment selection, loading, and asynchronous completion are controllable and observable.
- **6–8:** Most setup is repeatable with one manual or timing-sensitive dependency.
- **3–5:** State can be prepared but relies on shared data, fixed sleeps, manual intervention, or fragile ordering.
- **0–2:** Runs cannot start from or return to a known state.

#### `repository_automation_assets`: 5

- **5:** Critical flows have focused repository tests or deterministic tasks with bounded capabilities, named assertions, and observable validation; triggers enrich evidence only where appropriate; and relevant trend-sensitive behavior uses inline observation spans and deterministic metric budgets.
- **3–4:** Useful definitions exist but coverage, assertions, or reuse is incomplete.
- **1–2:** Only prototypes, external scripts, or undocumented manual prompts exist.
- **0:** No reusable automation asset exists.

Do not hide a zero when a greenfield app intentionally has no automation assets. Explain that the score reflects expected sequencing when the audit is explicitly pre-automation.

#### `repeatability`: 5

- **5:** At least three clean repetitions pass with stable selectors and state; required platforms/builds have evidence.
- **3–4:** Two clean repetitions pass, or one target platform is verified while another remains untested.
- **1–2:** One successful run exists or repetitions expose intermittent failures.
- **0:** No end-to-end repetition evidence exists.

## Apply Readiness Gates

Apply every gate supported by evidence. Gates cap the Automation Readiness subscore after raw points:

| Blocker code | Meaning | Readiness cap |
| --- | --- | ---: |
| `no_ui_observation` | No trustworthy visual tree or equivalent state observation | 20 |
| `no_ui_action` | Sampled critical flow cannot be safely operated | 24 |
| `id_coverage_below_70` | Stable unique ID coverage is below 70% | 34 |
| `duplicate_critical_ids` | A critical selector is ambiguous in a rendered state | 34 |
| `no_deterministic_reset` | A clean start or reset cannot be reproduced | 39 |
| `no_stable_app_identity` | Automation cannot select the target app/build reliably | 34 |

Add `unsafe_mutating_tools` when app or remote write tools are reachable outside the intended development/test boundary or without appropriate scope, authorization, or runtime guards. Broad all-tool access that is compile-time isolated to a clearly identified developer build does not trigger this blocker by itself; penalize `guarded_app_control` when the surface is broader than the audit flows require and document the residual risk. The blocker changes the headline outcome to `Blocked — unsafe control surface` until remediated without automatically altering the numeric score.

The scorer derives `id_coverage_below_70` and `duplicate_critical_ids` from metrics when applicable. Add all other blocker codes explicitly. If no rendered state can be observed, set both target counts to zero, add `no_ui_observation`, and describe coverage as unmeasured rather than 0%.

## Assign Labels And Confidence

Overall labels use the gated total:

- **90–100:** Strong
- **75–89:** Good
- **60–74:** Developing
- **40–59:** Weak
- **0–39:** Minimal

Automation Readiness labels use the gated subscore:

- **43–50:** Automation-ready
- **35–42:** Pilot-ready
- **25–34:** Conditional
- **0–24:** Not ready

Evidence confidence is:

- **High:** `source`, at least one of `live` or `replay`, and `repeat_run`;
- **Medium:** any two of `source`, runtime evidence (`live` or `replay`), and `repeat_run`; and
- **Low:** anything less.

Keep score and confidence separate. A high provisional score with low confidence remains unverified.

## Create Scorer Input

Pass a JSON object with all nine criteria. Scores may be integers or decimals.

```json
{
"target": "Example app / iOS development build",
"evidenceModes": ["source", "live", "repeat_run"],
"criteria": {
"connection_and_identity": { "score": 9, "evidence": ["Live session abc identifies build 42"], "gap": "" },
"runtime_observability": { "score": 12, "evidence": ["Logs and screenshots are time-correlated"], "gap": "Navigation events are absent" },
"inspection_surface": { "score": 13, "evidence": ["Focused visual-tree queries and preferences inspection work"], "gap": "" },
"guarded_app_control": { "score": 7, "evidence": ["Read-only state tool is schema-described"], "gap": "No reset tool" },
"ui_addressability": { "score": 15, "evidence": ["17 of 20 eligible targets have stable unique IDs"], "gap": "Three missing IDs" },
"actionability": { "score": 8, "evidence": ["Tap, type, scroll, and assertions verified"], "gap": "Secret entry untested" },
"deterministic_state": { "score": 6, "evidence": ["Test account is reusable"], "gap": "No full reset" },
"repository_automation_assets": { "score": 3, "evidence": ["One bounded login task exists"], "gap": "No recovery-flow coverage" },
"repeatability": { "score": 4, "evidence": ["Two clean repetitions pass"], "gap": "Android untested" }
},
"metrics": {
"eligibleTargets": 20,
"stableUniqueAutomationIds": 17,
"duplicateCriticalAutomationIds": 0,
"criticalTargetsMissingIds": 1,
"representativeFlows": 2,
"attemptedRepeatedRuns": 2,
"successfulRepeatedRuns": 2
},
"blockers": ["no_deterministic_reset"]
}
```

Keep criterion evidence concise in scorer input. Put detailed evidence locators and remediation notes in the final audit report.

Referenced files: 2

ansight-cli-setup7.28 KB

View saved version →

---
name: ansight-cli-setup
description: Prepare a developer workstation or agent to use the Ansight CLI by verifying the executable and dependencies, starting or reusing the resident host, and proving structured discovery. Use when setup is requested or those prerequisites are not ready; do not use for ordinary app operation once they work.
---

## OpenAI plugin integration

# Ansight CLI Setup Skill

Use this skill when a user wants an agent or developer workstation prepared for Ansight without modifying an app SDK integration.

## Goal

Make the `ansight` executable the canonical local interface, verify its dependencies, start or reuse its resident host, and prove that structured CLI commands can discover apps and sessions.

## Required Constraints

- Use `ansight` commands directly and do not add a separate client bridge or daemon configuration.
- Prefer `--json` whenever command output will be consumed by an agent or script.
- Preserve any running host and its selected data directory.
- Do not install or modify an app SDK unless the user separately requests it.
- Do not start a second host against the same data directory.
- Keep the resident host on the developer machine and do not expose its local ports publicly.
- Treat macOS Keychain and resident-host IPC denials as execution-sandbox boundaries, not damaged Ansight credentials. Do not delete Keychain items, sign the user out, create a parallel file-backed secret store, or restart a healthy host to work around them.

## Workflow

1. Confirm the executable and command surface:

```sh
ansight help
ansight version --json
ansight update check --json
ansight doctor --json
```

2. Check for a resident host:

```sh
ansight host status --json
```

3. If no host is running, start one in a persistent terminal:

```sh
ansight host run
```

Use `ansight host run --open` when the user also wants the local browser explorer. Use the same `--data-dir` on status and management commands when a custom data directory is required.

4. From another terminal, verify the host and discovery surface:

```sh
ansight host status --json
ansight app list --json
ansight session list --connected --limit 20 --json
```

5. A simulator, emulator, Mac Catalyst app, or desktop app registers
automatically with the local host. To enroll a physical device, issue a
generic one-use terminal QR and scan it from the app's developer-only Ansight
surface:

```sh
ansight pairing issue --qr
```

Do not require app registration before this first connection. Once the SDK
supplies its real App ID, optionally link it to a repository with
`ansight app register <app-id> --name <name> --codebase <path>`.

6. For agent workflows, prove the machine-readable inspection path with the selected session:

```sh
ansight session show <session-id> --json
ansight app tools <session-id> \
--policy read \
--detail summary \
--max-results 10 \
--json
```

This is a compact discovery check. For a real app question, use the
installed `$ansight-use-remote-app-tools` skill: search with focused terms,
then retrieve the selected exact tool with `--tool-id <id> --detail full`.
Session listing is summary-only and cursor-paginated. Follow `nextCursor`
with `--cursor` only when the first filtered page does not contain the
intended session, and preserve the same filters between pages.

7. For fast live interaction, verify `ansight app interact --help`. Once the exact
session is selected, the live-operation skill can open one persistent process:

```sh
ansight app interact --session <session-id> --repository <repository-root> --jsonl
```

Keep its process handle and send JSON Lines on stdin. This built-in duplex
connection returns compact fresh UI trees and supports semantic targets,
coordinate fallback, sequential batches and saved task execution. Screenshot
and tree evidence capture is automatic. `--repository` is optional for gestures and
required for `tasks`/`task`. This does not create another host, agent, app
process or recording session. Setup alone does not authorize live mutations.

8. Report the executable used, doctor result, host state, data directory, discovered app/session identifiers, and any manual pairing or persistent-terminal step that remains.

## Troubleshooting

- CLI device launches show simulator/emulator windows by default. Pass `--headless` on each device-launching command when windowless operation is requested; `--json`, `--silent`, and CI do not imply it. This skips Simulator.app on iOS and adds `-no-window` for new Android emulators without closing existing windows or changing physical devices. See [headless device launches](https://www.ansight.ai/docs/cli/commands#headless-device-launches).
- After an update or local build install, compare `ansight version --json` and `ansight host status --json`. A running host keeps its loaded code, so new launch options require an updated host too. Coordinate an authorized restart rather than interrupting a shared host automatically.
- Run `ansight doctor --json` first and use its required/optional capability results instead of guessing at missing dependencies.
- In a sandboxed agent environment, `OSStatus -50` while reading the Ansight macOS Keychain item or `Permission denied` for a `CoreFxPipe_ansight-*` path usually means the sandbox denied Keychain or resident-host IPC access. Retry the exact command outside the sandbox with explicit user approval and the narrowest command permission the client supports. If that succeeds, continue Ansight commands in that approved execution context; do not repair or replace the credential store.
- If the same command also fails outside the sandbox, treat it as a real host or credential problem and preserve both outputs for diagnosis.
- If a command cannot find the resident host, compare the `--data-dir` value and current OS user.
- If no live session appears, confirm the host is running and the app is a development build. Host-local targets should auto-register; a physical device should have scanned a current `ansight pairing issue --qr` invite.
- If multiple sessions match, select one explicitly; never guess.
- Use `ansight help` and `ansight <command> help` as the authoritative syntax for the installed version.

## Done Criteria

- `ansight version --json` reports the expected version string, daily build
number, and public or preview channel, and any available update is reported.
- `ansight doctor --json` completes and required capabilities are understood.
- Exactly one intended resident host is running or the user has the explicit command needed to start it.
- `ansight host status --json` succeeds.
- App and connected-session discovery has been checked through the CLI.
- No separate client bridge or legacy daemon configuration was added.

ansight-create-remote-tool-android9.2 KB

View saved version →

---
name: ansight-create-remote-tool-android
description: Use this skill when implementing a custom Ansight remote tool for a native Android Kotlin or Java app. Create a narrow androidSimpleTool or AndroidTool with a stable id, explicit read/write/critical ToolPolicy, structured JSON results, local-development build-variant gating, runtime ToolGuard access, registration through AnsightOptions.addTool/addTools or AnsightRuntime.registerTool, and verification through the Ansight CLI.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.


# Ansight Android Remote Tool Skill

Use this skill when a user wants to add an app-specific Ansight remote tool to a native Android app.

Do not use this skill for React Native, .NET Android, Flutter, server, desktop, or generic JVM projects.

## What A Remote Tool Is

An Ansight remote tool is an app-specific, agent-facing tool that a developer exposes from inside the running Android app. Instead of forcing an agent to infer everything from screenshots, logs, visual trees, or generic reflection, a remote tool lets the agent ask targeted questions about the app's own domain and runtime state. CLI clients discover the tool by its stable id, call it with structured arguments, let the app execute the operation in-process under its active tool guard, and receive a structured JSON result.

Use a custom remote tool when app-specific state would help an agent understand a bug, explain current behavior, or make a better code fix. For example, a 3D Android app could expose the active scene id, camera transform, selected entity ids, visible mesh counts, animation state, physics flags, and narrow actions such as selecting an entity, moving the debug camera, or toggling a diagnostic overlay. A map app using Mapbox, Esri, Google Maps, or a similar library could expose camera center/zoom/bearing/tilt, loaded style id, sources, layers, tile-load errors, selected feature ids, annotations, current bounds, and safe actions such as toggling a debug layer or flying to a known fixture location.

Prefer a remote tool over broad reflection, ad hoc scripts, or manual emulator/device poking when the app can expose a precise, reviewable answer to questions such as "why is the map blank?", "why is this model offscreen?", "which domain object is selected?", or "what runtime state differs from the expected fixture?"

Do not treat remote tools as public APIs, production automation endpoints, or general command runners. They are privileged local-development capabilities and must be gated by build variant, a maximum runtime policy, stable ids, and explicit argument validation.

## Goal

Create the smallest useful Android custom tool for a local development workflow, register it with the existing Ansight runtime setup, keep it out of distributable builds, guard it at runtime, and verify that the CLI can discover and invoke it.

## Required Constraints

- prefer Kotlin for new Android tool code when the app uses Kotlin
- use a stable id such as `myapp.diagnostics_snapshot`; do not use display text as the id
- prefer one small tool per operation
- choose the narrowest `ToolPolicy`: `Read`, `Write`, or `Critical`
- validate flattened string arguments and fail closed on invalid input
- return structured JSON results
- place custom tool code in `src/debug/...` when Ansight is a `debugImplementation`
- keep custom tool code out of Play Store, CI release, and other distributable variants
- default the active guard to read-only unless the requested workflow needs mutation
- do not expose secrets, arbitrary command dispatch, broad scripting, production endpoints, or destructive app actions

## Workflow

1. Inspect the existing Ansight install path, Gradle dependency scope, app module, and `Application` startup.
2. Identify the narrow operation the user needs. Split broad requests into separate read/write/critical tools.
3. Choose where the tool can compile safely:
   - `src/debug/kotlin` or `src/debug/java` when the Ansight dependency is `debugImplementation`
   - a local-development flavor/source set when the app uses internal variants
   - main source only when the dependency is intentionally present there and guarded
4. Implement the tool with `androidSimpleTool(...)` or a concrete Android tool type that matches the existing codebase.
5. Register the tool before building `AnsightOptions`, or register it at runtime only after Ansight has initialized.
6. Configure `withReadOnlyToolAccess()`, `withReadWriteToolAccess()`, or `withAllToolAccess()` to match the tool policy.
7. Build a debug target and, when practical, a release target that omits the tool.
8. Pair the app with the resident CLI host and verify discovery and execution through `ansight app tools` and `ansight app call`.

## Implementation Pattern

Use `androidSimpleTool(...)` for small app-owned operations:

```kotlin
import ai.ansight.runtime.AndroidToolResult
import ai.ansight.runtime.ToolPolicy
import ai.ansight.runtime.androidSimpleTool
import org.json.JSONObject

val diagnosticsSnapshotTool = androidSimpleTool(
    id = "myapp.diagnostics_snapshot",
    name = "Diagnostics Snapshot",
    description = "Returns a small app-specific diagnostic summary.",
    category = "myapp",
    policy = ToolPolicy.Read,
    keywords = "diagnostics health queues",
) { arguments, _ ->
    val includeQueues = arguments["includeQueues"]?.toBooleanStrictOrNull() ?: false
    val snapshot = diagnostics.createSnapshot()

    AndroidToolResult.success(
        JSONObject()
            .put("connectionState", snapshot.connectionState)
            .apply {
                if (includeQueues) {
                    put("pendingQueueCount", snapshot.pendingQueueCount)
                }
            }
    )
}
```

For arguments that are required or constrained, return a failure result instead of silently guessing. Keep error messages stable enough for an agent to act on.

## Registration

Register tools from the same startup path that builds Ansight options:

```kotlin
val options = Ansight.developerOptions(
    clientName = "Android App",
)
    .apply {
        if (BuildConfig.DEBUG) {
            addTool(diagnosticsSnapshotTool)
            withReadOnlyToolAccess()
        } else {
            withToolsDisabled()
        }
    }
    .build()
```

Use runtime registration only when the tool depends on state that is unavailable during options construction:

```kotlin
if (BuildConfig.DEBUG) {
    AnsightRuntime.registerTool(diagnosticsSnapshotTool, replaceExisting = true)
}
```

Registered tools stay hidden and unusable until the active guard allows their `ToolPolicy`.

## Build Variant Gating

When the app uses:

```kotlin
debugImplementation("ai.ansight:ansight-android:1.4.0-preview.1")
```

put custom tool code under the debug source set:

```text
app/src/debug/kotlin/com/example/app/ansight/DiagnosticsSnapshotTool.kt
```

If release code needs to call a shared registration hook, create a no-op release implementation with the same app-owned API. Do not make release depend on Ansight just to satisfy debug-only tool code.

## Policy And Guard Choice

| Policy | Use for | Guard that enables it |
| --- | --- | --- |
| `ToolPolicy.Read` | Inspecting non-secret app state without mutation. | `withReadOnlyToolAccess()` |
| `ToolPolicy.Write` | Ordinary UI and app-state changes. | `withReadWriteToolAccess()` |
| `ToolPolicy.Critical` | Destructive actions, secret access, broad runtime inspection, or arbitrary app-code invocation. | `withAllToolAccess()` |

Use a custom guard only when the app needs narrower product-specific policy than the built-in presets.

## Verification

Run the relevant local development build:

```bash
./gradlew :app:assembleDebug
```

When practical, also run:

```bash
./gradlew :app:assembleRelease
```

After the app is paired and connected:

- `ansight app tools <session-id> --tool-id <tool-id> --detail full --include-unavailable --json` should return the exact custom tool entry and its denial state; invoke it only when `executable` is true
- `ansight app call <session-id> <tool-id> --arguments '{ "includeQueues": true }' --json` should invoke it
- if the tool is missing, check the active session, source set, dependency scope, registration path, and guard
- if invocation fails, inspect the returned error, app logs, and argument parsing

## Done Criteria

- the tool has a stable id, category, description, policy, and structured JSON result
- custom tool code is included only in the intended local development variant
- distributable variants omit the tool or keep tools disabled
- the tool is registered from the existing Ansight startup path
- the active guard allows only the required maximum policy
- the CLI can discover and invoke the tool in a paired local development session
- final response names the tool id, policy, source set or build variant, files changed, and verification performed

ansight-create-remote-tool-cordova2.06 KB

View saved version →

---
name: ansight-create-remote-tool-cordova
description: Use this skill when implementing a custom Ansight remote tool for a Cordova-family Capacitor app. Create a narrow JavaScript registerTool handler with a stable id, explicit read/write/critical policy, structured results, development-only registration, runtime guard access, and CLI verification.
---

## OpenAI plugin integration

# Ansight Cordova / Capacitor Remote Tool Skill

Use this skill to expose app-specific JavaScript state that existing DOM, native, artifact, and reflection tools do not answer precisely.

## Workflow

1. Define a narrow question or action and choose a stable namespaced id.
2. Prefer `read`; use `write` for ordinary mutation and `critical` for destructive, secret-bearing, or arbitrary code-invoking operations.
3. Register after bridge initialization:

```ts
const registration = Ansight.registerTool(
{
id: "app.get_sync_state",
name: "Get sync state",
policy: "read",
},
async () => ({
success: true,
result: { state: "idle" },
}),
);

await registration.ready;
```

4. Keep registration inside the app's explicit development guard and use the least-permissive tool access.
5. Avoid secrets, full stores, arbitrary JavaScript evaluation, unbounded DOM scraping, and broad method invocation.
6. Test success, invalid inputs, failures, unregistration, denied guard access, and discovery/invocation through `ansight app tools` and `ansight app call`.

Report the tool id, policy, exposed data or mutation, guard, registration location, and verification.

ansight-create-remote-tool-dotnet13.2 KB

View saved version →

---
name: ansight-create-remote-tool-dotnet
description: Use this skill when implementing a custom Ansight remote tool for a .NET MAUI, .NET for Android, .NET for iOS, or .NET Mac Catalyst app. Create a narrow Ansight.Tools.ITool implementation with stable tool ids, ToolSchema arguments and results, the shared read/write/critical ToolPolicy, local-development MSBuild gating with AnsightRemoteToolsPolicy, registration through AddTool/AddTools or a WithMyAppTools extension, and verification through the Ansight CLI.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.


# Ansight .NET Remote Tool Skill

Use this skill when a user wants to add an app-specific Ansight remote tool that a paired agent can call through the Ansight CLI.

## What A Remote Tool Is

An Ansight remote tool is an app-specific, agent-facing tool that a developer exposes from inside the running app. Instead of forcing an agent to infer everything from screenshots, logs, visual trees, or generic reflection, a remote tool lets the agent ask targeted questions about the app's own domain and runtime state. CLI clients discover the tool by its stable id, call it with structured arguments, let the app execute the operation in-process under its active `ToolGuard`, and receive a structured result.

Use a custom remote tool when app-specific state would help an agent understand a bug, explain current behavior, or make a better code fix. For example, a 3D app could expose the active scene id, camera transform, selected entity ids, visible mesh counts, animation state, physics flags, and narrow actions such as selecting an entity, moving the debug camera, or toggling a diagnostic overlay. A map app using Mapbox, Esri, or a similar library could expose camera center/zoom/bearing/pitch, loaded style id, sources, layers, tile-load errors, selected feature ids, annotations, current bounds, and safe actions such as toggling a debug layer or flying to a known fixture location.

Prefer a remote tool over broad reflection, ad hoc scripts, or manual app poking when the app can expose a precise, reviewable answer to questions such as "why is the map blank?", "why is this model offscreen?", "which domain object is selected?", or "what runtime state differs from the expected fixture?"

Do not treat remote tools as public APIs, production automation endpoints, or general command runners. They are privileged local-development capabilities and must be gated by build configuration, a maximum runtime policy, and stable schemas.

## Goal

Create the smallest useful custom remote tool for a local development workflow, register it with the existing Ansight setup, keep it excluded from protected builds, guard it at runtime, and verify that the CLI can discover and invoke it.

## Required Constraints

- implement `Ansight.Tools.ITool`
- prefer one small tool class per operation
- use a stable id such as `myapp.diagnostics_snapshot`; do not use display text as the id
- declare explicit `ToolSchema` objects for arguments and results
- choose the narrowest `ToolPolicy`: `Read`, `Write`, or `Critical`
- parse and validate flattened string arguments inside `Execute(...)`
- return `ToolResult.Failure(...)` with a stable `errorCode` for invalid requests or app-side failures
- register tools only in local development builds
- keep `AnsightRemoteToolsPolicy=AllowedWithWarnings` only when custom tools are intentionally included
- use `AnsightRemoteToolsPolicy=Disallowed` for protected Release, CI, TestFlight, App Store, Play Store, or other distributable builds
- do not expose secrets, account data, production endpoints, arbitrary command dispatch, broad script execution, or destructive app actions

## Workflow

1. Inspect the existing Ansight integration and package shape.
   - MAUI all-in-one apps usually call `builder.UseAnsight<App>(...)`.
   - Non-MAUI all-in-one apps usually call `Options.CreateBuilder().WithAnsightSdk(...)`.
   - Core-only apps build options manually and register tools with `AddTool(...)`, `AddTools(...)`, or suite-specific `With...Tools(...)` methods.
2. Identify the narrow operation the user needs. If the request is broad, split it into multiple read/write/critical tools or implement only the safest first tool.
3. Add a project-local MSBuild flag that includes custom tool code only in local development builds.
4. Create shared metadata for ids and schemas.
5. Implement one `ITool` class for the operation.
6. Register the tool through a project-local extension method such as `WithMyAppTools(...)`.
7. Configure the runtime guard to allow only the needed maximum policy.
8. Build the app and confirm protected builds fail or omit the tool when expected.
9. Run the app, pair it with the resident CLI host, and verify discovery and execution through `ansight app tools` and `ansight app call`.

## MSBuild Pattern

Use an app-specific flag so custom tool code is absent from protected builds:

```xml
<PropertyGroup Condition="'$(Configuration)' == 'Debug'">
  <MyAppAnsightRemoteToolsEnabled>true</MyAppAnsightRemoteToolsEnabled>
</PropertyGroup>

<PropertyGroup>
  <MyAppAnsightRemoteToolsEnabled Condition="'$(MyAppAnsightRemoteToolsEnabled)' == ''">false</MyAppAnsightRemoteToolsEnabled>
  <AnsightRemoteToolsPolicy Condition="'$(AnsightRemoteToolsPolicy)' == '' and '$(MyAppAnsightRemoteToolsEnabled)' == 'true'">AllowedWithWarnings</AnsightRemoteToolsPolicy>
  <AnsightRemoteToolsPolicy Condition="'$(AnsightRemoteToolsPolicy)' == ''">Disallowed</AnsightRemoteToolsPolicy>
</PropertyGroup>

<PropertyGroup Condition="'$(MyAppAnsightRemoteToolsEnabled)' == 'true'">
  <DefineConstants>$(DefineConstants);MYAPP_ANSIGHT_TOOLS</DefineConstants>
</PropertyGroup>
```

Wrap custom tool files or classes in the same symbol:

```csharp
#if MYAPP_ANSIGHT_TOOLS
// Custom Ansight tools live here.
#endif
```

Do not manually define `ANSIGHT_REMOTE_TOOLS`. The Ansight SDK defines it when `AnsightRemoteToolsPolicy` resolves to `Allowed` or `AllowedWithWarnings`.

## Recommended Shape

For more than one custom tool, keep the code organized like a small first-party suite:

- `MyAppToolIds`
- `MyAppToolSchemas`
- one `ITool` implementation per operation
- `MyAppAnsightOptionsBuilderExtensions`
- optional wrappers for user confirmation or product-specific access checks

## Shared Metadata

```csharp
#if MYAPP_ANSIGHT_TOOLS
using Ansight.Tools;

internal static class MyAppToolIds
{
    public const string DiagnosticsSnapshot = "myapp.diagnostics_snapshot";
}

internal static class MyAppToolSchemas
{
    public static ToolSchema DiagnosticsSnapshotArguments { get; } = ToolSchema.Object(
        description: "Arguments for reading a small app diagnostic summary.",
        properties: new Dictionary<string, ToolSchema>
        {
            ["includeQueues"] = ToolSchema.Boolean("Include queue counters in the result.")
        });

    public static ToolSchema DiagnosticsSnapshotResult { get; } = ToolSchema.Object(
        description: "App diagnostic summary payload.",
        properties: new Dictionary<string, ToolSchema>
        {
            ["connectionState"] = ToolSchema.String("Current backend connection state."),
            ["pendingQueueCount"] = ToolSchema.Integer("Pending queue count when includeQueues is true.")
        },
        required: new[] { "connectionState" });
}

#endif
```

## Tool Implementation

Arguments arrive as flattened string values. Parse them explicitly and fail closed on invalid input.

```csharp
#if MYAPP_ANSIGHT_TOOLS
using System.Text.Json.Nodes;
using Ansight.Tools;

internal sealed record DiagnosticsSnapshot(
    string ConnectionState,
    int PendingQueueCount);

internal sealed class DiagnosticsSnapshotTool(
    Func<DiagnosticsSnapshot> snapshotProvider) : ITool
{
    public string Category => "myapp";

    public ToolPolicy Policy => ToolPolicy.Read;

    public string Id => MyAppToolIds.DiagnosticsSnapshot;

    public string Name => "Diagnostics Snapshot";

    public string Description => "Returns a small app-specific diagnostic summary.";

    public string Keywords => "diagnostics health queues";

    public ToolSchema ArgumentsSchema => MyAppToolSchemas.DiagnosticsSnapshotArguments;

    public ToolSchema ResultSchema => MyAppToolSchemas.DiagnosticsSnapshotResult;

    public Task<ToolResult> Execute(IReadOnlyDictionary<string, string> arguments)
    {
        ArgumentNullException.ThrowIfNull(arguments);

        var includeQueues = arguments.TryGetValue("includeQueues", out var includeQueuesText)
                            && bool.TryParse(includeQueuesText, out var parsedIncludeQueues)
                            && parsedIncludeQueues;

        var snapshot = snapshotProvider();
        var payload = new JsonObject
        {
            ["connectionState"] = snapshot.ConnectionState
        };

        if (includeQueues)
        {
            payload["pendingQueueCount"] = snapshot.PendingQueueCount;
        }

        return Task.FromResult(ToolResult.Success(payload));
    }
}
#endif
```

For MAUI tools that read or mutate UI state, marshal onto the main thread inside the tool or a shared helper before touching controls, pages, bindings, or handlers.

## Registration

Expose a project-local registration method instead of scattering `new Tool(...)` calls through app startup:

```csharp
#if MYAPP_ANSIGHT_TOOLS
using Ansight;
using Ansight.Tools;

internal static class MyAppAnsightOptionsBuilderExtensions
{
    public static Options.OptionsBuilder WithMyAppTools(
        this Options.OptionsBuilder builder,
        Func<DiagnosticsSnapshot> snapshotProvider)
    {
        ArgumentNullException.ThrowIfNull(builder);
        ArgumentNullException.ThrowIfNull(snapshotProvider);

        return builder.AddTools(new ITool[]
        {
            new DiagnosticsSnapshotTool(snapshotProvider)
        });
    }
}
#endif
```

For a core-only setup:

```csharp
var optionsBuilder = Options.CreateBuilder();

#if MYAPP_ANSIGHT_TOOLS
optionsBuilder = optionsBuilder.WithMyAppTools(diagnostics.CreateSnapshot);
#endif

var options = optionsBuilder
    .WithReadOnlyToolAccess()
    .Build();
```

For the all-in-one package:

```csharp
var options = Options.CreateBuilder()
    .WithAnsightSdk(ansight =>
    {
#if MYAPP_ANSIGHT_TOOLS
        ansight.WithMyAppTools(diagnostics.CreateSnapshot);
#endif
        ansight.WithReadOnlyToolAccess();
    })
    .Build();
```

For MAUI:

```csharp
builder.UseAnsight<App>(ansight =>
{
#if MYAPP_ANSIGHT_TOOLS
    ansight.WithMyAppTools(diagnostics.CreateSnapshot);
#endif
    ansight.WithReadOnlyToolAccess();
});
```

Registered tools stay hidden and unusable until the active guard allows their `ToolPolicy`.

## Policy And Guard Choice

Choose the narrowest policy. A maximum includes every lower policy:

| Policy | Use for | Guard that enables it |
| --- | --- | --- |
| `ToolPolicy.Read` | Inspecting non-secret app state without mutation. | `WithReadOnlyToolAccess()` |
| `ToolPolicy.Write` | Ordinary UI and app-state changes. | `WithReadWriteToolAccess()` |
| `ToolPolicy.Critical` | Destructive actions, secret access, broad runtime inspection, or arbitrary app-code invocation. | `WithAllToolAccess()` |

Use `WithToolsDisabled()` for builds or runtime paths where remote tools must not be discoverable or executable. Use `WithToolGuard(...)` when the app needs a narrower product-specific policy than the built-in presets.

For sensitive internal tools, add a runtime consent or policy wrapper in addition to build-time inclusion and `ToolGuard`. Runtime confirmation is not a substitute for excluding tools from public distribution builds.

## Verification

Build and run the relevant local development target:

```bash
dotnet build path/to/App.csproj -c Debug
```

Also verify a protected configuration when practical:

```bash
dotnet build path/to/App.csproj -c Release
```

After the app is paired and connected, use the CLI:

- `ansight app tools <session-id> --tool-id <tool-id> --detail full --include-unavailable --json` should return the exact custom tool entry and its denial state; invoke it only when `executable` is true.
- `ansight app call <session-id> <tool-id> --arguments '{ "includeQueues": true }' --json` should invoke the tool.
- If the tool is missing, check the app connection, build symbol, `AnsightRemoteToolsPolicy`, registration path, and active guard.
- If invocation fails, inspect the returned `errorCode`, app logs, and argument parsing.

## Done Criteria

- the tool implements `ITool` with stable metadata, schemas, and policy
- custom tool code is included only in the intended local development build
- protected builds omit the tool or fail with `AnsightRemoteToolsPolicy=Disallowed`
- the tool is registered from the existing Ansight startup path
- the active guard allows only the required maximum policy
- the CLI can discover and invoke the tool in a paired local development session
- the final response names the tool id, policy, build flag, files changed, and verification performed

ansight-create-remote-tool-flutter2.22 KB

View saved version →

---
name: ansight-create-remote-tool-flutter
description: Use this skill when implementing a custom Ansight remote tool for a Flutter app. Create a narrow Dart registerTool handler with a stable id, explicit read/write/critical policy, structured results, development-only registration, runtime guard access, and CLI verification.
---

## OpenAI plugin integration

# Ansight Flutter Remote Tool Skill

Use this skill to expose app-specific Flutter or Dart state that existing widget, native, artifact, and reflection tools do not answer precisely.

## Workflow

1. Define the narrow question or action and choose a stable namespaced id such as `app.get_sync_state`.
2. Prefer `read`; use `write` for ordinary mutation and `critical` for destructive, secret-bearing, or arbitrary code-invoking operations.
3. Define argument and result schemas where useful.
4. Register after runtime initialization:

```dart
final registration = await Ansight.instance.registerTool(
const AnsightToolDefinition(
id: 'app.get_sync_state',
name: 'Get sync state',
policy: AnsightToolPolicy.read,
),
(arguments, context) async => const AnsightToolResult.success(
result: <String, Object?>{'state': 'idle'},
),
);
```

5. Keep registration inside `kDebugMode` or the app's explicit developer variant and configure the least-permissive `AnsightToolGuard`.
6. Avoid secrets, unbounded object graphs, raw reflection, and broad arbitrary method invocation.
7. Test handler success, invalid arguments, expected failure, unregistration, denied guard access, and discovery/invocation through `ansight app tools` and `ansight app call`.

Report the tool id, policy, exposed data or mutation, guard, registration location, and verification.

ansight-create-remote-tool-ios9.45 KB

View saved version →

---
name: ansight-create-remote-tool-ios
description: Use this skill when implementing a custom Ansight remote tool for a native iOS SwiftUI or UIKit app. Create a narrow AnsightTool with a stable descriptor id, explicit read/write/critical policy, structured result payloads, Debug or local-development build gating, runtime tool guard access, registration through AnsightRuntime.shared.registerTool, and verification through the Ansight CLI.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.


# Ansight iOS Remote Tool Skill

Use this skill when a user wants to add an app-specific Ansight remote tool to a native iOS app.

Do not use this skill for React Native, .NET iOS, Flutter, server, desktop, or generic Swift Package projects.

## What A Remote Tool Is

An Ansight remote tool is an app-specific, agent-facing tool that a developer exposes from inside the running iOS app. Instead of forcing an agent to infer everything from screenshots, logs, visual trees, or generic reflection, a remote tool lets the agent ask targeted questions about the app's own domain and runtime state. CLI clients discover the tool by its stable id, call it with structured arguments, let the app execute the operation in-process under its active tool guard, and receive a structured result payload.

Use a custom remote tool when app-specific state would help an agent understand a bug, explain current behavior, or make a better code fix. For example, a 3D iOS app could expose the active scene id, camera transform, selected entity ids, visible mesh counts, animation state, physics flags, and narrow actions such as selecting an entity, moving the debug camera, or toggling a diagnostic overlay. A map app using Mapbox, Esri, Apple MapKit, or a similar library could expose camera center/zoom/bearing/pitch, loaded style id, sources, layers, tile-load errors, selected feature ids, annotations, current bounds, and safe actions such as toggling a debug layer or flying to a known fixture location.

Prefer a remote tool over broad reflection, ad hoc scripts, or manual simulator/device poking when the app can expose a precise, reviewable answer to questions such as "why is the map blank?", "why is this model offscreen?", "which domain object is selected?", or "what runtime state differs from the expected fixture?"

Do not treat remote tools as public APIs, production automation endpoints, or general command runners. They are privileged local-development capabilities and must be gated by Debug or local-development build settings, a maximum runtime policy, stable ids, and explicit argument validation.

## Goal

Create the smallest useful iOS custom tool for a local development workflow, register it with the existing Ansight runtime setup, keep it out of distributable builds, guard it at runtime, and verify that the CLI can discover and invoke it.

## Required Constraints

- implement an executable `AnsightTool` for app-specific operations
- use a stable id such as `myapp.diagnostics_snapshot`; do not use display text as the id
- prefer one small tool per operation
- choose the narrowest policy: read, write, or critical
- validate string arguments and fail closed on invalid input
- return structured result payloads
- compile or register custom tools only in Debug or an explicit local-development build path
- set `ANSIGHT_ALLOW_REMOTE_TOOLS=true` only for builds that intentionally include remote tools
- default the active guard to read-only unless the requested workflow needs mutation
- do not expose secrets, arbitrary command dispatch, broad scripting, production endpoints, or destructive app actions

## Workflow

1. Inspect the existing Ansight install path, package manager, app target, and SwiftUI or UIKit startup.
2. Identify the narrow operation the user needs. Split broad requests into separate read/write/critical tools.
3. Choose a local-development build gate:
   - `#if DEBUG` for simple Debug-only tools
   - a project-specific Swift active compilation condition for internal developer builds
   - target membership limited to a developer-only target when appropriate
4. Implement a concrete `AnsightTool` with stable descriptor metadata.
5. Register the tool after Ansight initializes or during the same startup path.
6. Configure `.withReadOnlyToolAccess()`, `.withReadWriteToolAccess()`, or `.withAllToolAccess()` to match the tool policy.
7. Build a Debug target and, when practical, a Release target that omits the tool or disables tools.
8. Pair the app with the resident CLI host and verify discovery and execution through `ansight app tools` and `ansight app call`.

## Implementation Pattern

Use a concrete executable tool for app-owned operations:

```swift
#if DEBUG
import Ansight

struct DiagnosticsSnapshotTool: AnsightTool {
    let diagnostics: DiagnosticsService

    var descriptor: AnsightToolDescriptor {
        AnsightToolDescriptor(
            id: "myapp.diagnostics_snapshot",
            name: "Diagnostics Snapshot",
            description: "Returns a small app-specific diagnostic summary.",
            category: "myapp",
            policy: .read,
            keywords: "diagnostics health queues"
        )
    }

    func execute(arguments: [String: String]) throws -> AnsightToolExecutionResult {
        let includeQueues = arguments["includeQueues"] == "true"
        let snapshot = diagnostics.createSnapshot()

        var result: [String: AnsightToolValue] = [
            "connectionState": .string(snapshot.connectionState)
        ]

        if includeQueues {
            result["pendingQueueCount"] = .number(Double(snapshot.pendingQueueCount))
        }

        return .success(.object(result))
    }
}
#endif
```

For UI state, marshal onto the main actor before touching SwiftUI, UIKit, views, scenes, delegates, or navigation state.

## Registration

Register from the existing Ansight startup path:

```swift
try AnsightRuntime.shared.initializeAndActivateAnsightSdk { options in
#if DEBUG
    options.withReadOnlyToolAccess()
#else
    options.withToolsDisabled()
#endif
}

#if DEBUG
try AnsightRuntime.shared.registerTool(
    DiagnosticsSnapshotTool(diagnostics: diagnostics),
    replaceExisting: true
)
#endif
```

Descriptor-only registration is useful for catalog metadata, but app-specific executable tools should provide a concrete `AnsightTool`.

Registered tools stay hidden and unusable until the active guard allows their policy.

## Build Gating

Use Debug or a named local-development condition for custom tools. Protected Release, TestFlight, App Store, CI release, and other distributable builds should omit custom tool code or initialize Ansight with tools disabled.

If the project uses a build setting for remote tools, keep it limited to local development:

```text
ANSIGHT_ALLOW_REMOTE_TOOLS=true
```

Enrollment does not use a build setting or bundled config. A Simulator registers
automatically; for a physical iPhone, run `ansight pairing issue --qr` and scan
the generic terminal QR once. The SDK supplies its real App ID.

Do not set `ANSIGHT_ALLOW_REMOTE_TOOLS=true` for distributable builds.

## Policy And Guard Choice

| Policy | Use for | Guard that enables it |
| --- | --- | --- |
| `AnsightToolPolicy.read` | Inspecting non-secret app state without mutation. | `withReadOnlyToolAccess()` |
| `AnsightToolPolicy.write` | Ordinary UI and app-state changes. | `withReadWriteToolAccess()` |
| `AnsightToolPolicy.critical` | Destructive actions, secret access, broad runtime inspection, or arbitrary app-code invocation. | `withAllToolAccess()` |

Use a custom guard only when the app needs narrower product-specific policy than the built-in presets.

## Verification

Run the relevant local development build:

```bash
xcodebuild -scheme MyApp -configuration Debug -destination 'platform=iOS Simulator,name=iPhone 16' build
```

When practical, also run a release-style build without developer enrollment or remote-tool flags:

```bash
xcodebuild -scheme MyApp -configuration Release -destination 'generic/platform=iOS' build
```

After the app is paired and connected:

- `ansight app tools <session-id> --tool-id <tool-id> --detail full --include-unavailable --json` should return the exact custom tool entry and its denial state; invoke it only when `executable` is true
- `ansight app call <session-id> <tool-id> --arguments '{ "includeQueues": true }' --json` should invoke it
- if the tool is missing, check the active session, compilation condition, target membership, registration path, and guard
- if invocation fails, inspect the returned error, app logs, and argument parsing

## Done Criteria

- the tool has a stable descriptor id, category, description, policy, and structured result
- custom tool code is included only in the intended local development build
- distributable builds omit the tool or keep tools disabled
- the tool is registered from the existing Ansight startup path
- the active guard allows only the required maximum policy
- the CLI can discover and invoke the tool in a paired local development session
- final response names the tool id, policy, build gate, files changed, and verification performed

ansight-create-remote-tool-react-native9.65 KB

View saved version →

---
name: ansight-create-remote-tool-react-native
description: Use this skill when implementing a custom Ansight remote tool for a React Native app. Create a narrow JavaScript-backed registerTool handler or a native Swift/Kotlin tool, use stable ids, explicit read/write/critical policy, structured results, developer-only registration with __DEV__ or native build gates, runtime ToolGuard access, and verification through the Ansight CLI.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/ios/ansight-create-remote-tool-ios.md → [ansight-create-remote-tool-ios](../ansight-create-remote-tool-ios/SKILL.md)
- https://www.ansight.ai/skills/android/ansight-create-remote-tool-android.md → [ansight-create-remote-tool-android](../ansight-create-remote-tool-android/SKILL.md)


# Ansight React Native Remote Tool Skill

Use this skill when a user wants to add an app-specific Ansight remote tool to a React Native app.

Do not use this skill for native-only iOS, native-only Android, .NET, Flutter, server, desktop, or web-only projects.

## What A Remote Tool Is

An Ansight remote tool is an app-specific, agent-facing tool that a developer exposes from inside the running React Native app. It can be registered from JavaScript or native Swift/Kotlin code. Instead of forcing an agent to infer everything from screenshots, logs, component trees, visual trees, or generic reflection, a remote tool lets the agent ask targeted questions about the app's own domain and runtime state. CLI clients discover the tool by its stable id, call it with structured arguments, let the app execute the operation under its active tool guard, and receive a structured JSON-compatible result.

Use a custom remote tool when app-specific state would help an agent understand a bug, explain current behavior, or make a better code fix. For example, a 3D React Native app could expose the active scene id, camera transform, selected entity ids, visible mesh counts, animation state, physics flags, and narrow actions such as selecting an entity, moving the debug camera, or toggling a diagnostic overlay. A map app using Mapbox, Esri, Google Maps, Apple MapKit, or a similar library could expose camera center/zoom/bearing/pitch, loaded style id, sources, layers, tile-load errors, selected feature ids, annotations, current bounds, and safe actions such as toggling a debug layer or flying to a known fixture location.

Prefer a remote tool over broad reflection, ad hoc scripts, or manual simulator/emulator/device poking when the app can expose a precise, reviewable answer to questions such as "why is the map blank?", "why is this model offscreen?", "which domain object is selected?", or "what runtime state differs from the expected fixture?"

Do not treat remote tools as public APIs, production automation endpoints, or general command runners. They are privileged local-development capabilities and must be gated by `__DEV__` or native build configuration, a maximum runtime policy, stable ids, and explicit argument validation.

## Goal

Create the smallest useful React Native custom tool for a local development workflow, register it with the existing Ansight bridge setup, keep it out of distributable builds, guard it at runtime, and verify that the CLI can discover and invoke it.

## Required Constraints

- prefer a JavaScript-backed tool when the operation can safely run in JavaScript
- use native Swift or Kotlin only when the operation needs native-only state or platform APIs
- use a stable id such as `myapp.diagnostics_snapshot`; do not use display text as the id
- prefer one small tool per operation
- choose the narrowest policy: `"read"`, `"write"`, or `"critical"`
- validate flattened string arguments and fail closed on invalid input
- return structured JSON-compatible results
- register custom tools only when the app's development-only condition is true, usually `__DEV__`
- keep native custom tool registration behind Debug or local-development native build gates
- default the active guard to read-only unless the requested workflow needs mutation
- do not expose secrets, arbitrary command dispatch, broad scripting, production endpoints, or destructive app actions

## Workflow

1. Inspect the existing `@ansight/react-native` initialization path and app bootstrap.
2. Identify whether the operation belongs in JavaScript or native code.
3. Identify the development-only condition that controls registration.
4. Implement one narrow tool with stable metadata, explicit policy, argument validation, and a structured result.
5. Register JavaScript-backed tools after Ansight initializes, or register native tools after the native bridge has initialized Ansight.
6. Configure `withReadOnlyToolAccess()`, `withReadWriteToolAccess()`, or `withAllToolAccess()` to match the tool policy.
7. Run JavaScript checks and native builds where practical.
8. Pair the app with the resident CLI host and verify discovery and execution through `ansight app tools` and `ansight app call`.

## JavaScript Tool Pattern

Use JavaScript-backed tools for app state that is already available in React Native:

```ts
import Ansight from "@ansight/react-native";

export async function registerAnsightAppTools(diagnostics: DiagnosticsService) {
  if (!__DEV__) {
    return;
  }

  const registration = Ansight.registerTool(
    {
      id: "myapp.diagnostics_snapshot",
      name: "Diagnostics Snapshot",
      category: "myapp",
      policy: "read",
      description: "Returns a small app-specific diagnostic summary.",
      keywords: "diagnostics health queues",
    },
    async (arguments) => {
      const includeQueues = arguments.includeQueues === "true";
      const snapshot = await diagnostics.createSnapshot();

      return {
        success: true,
        result: {
          connectionState: snapshot.connectionState,
          ...(includeQueues
            ? { pendingQueueCount: snapshot.pendingQueueCount }
            : {}),
        },
      };
    },
  );

  await registration.ready;
}
```

Call `registration.unregister()` or `Ansight.unregisterTool(id)` when a temporary tool should be removed.

## Native Tool Choice

Use native tools when the handler must access Swift or Kotlin-only state, platform APIs, native dependency instances, or native storage that should not be bridged into JavaScript.

For native iOS custom tools, follow:

```text
https://www.ansight.ai/skills/ios/ansight-create-remote-tool-ios.md
```

For native Android custom tools, follow:

```text
https://www.ansight.ai/skills/android/ansight-create-remote-tool-android.md
```

Register native custom tools after the React Native bridge has initialized Ansight. Android runtime initialization rebuilds the native tool registry from bridge options, so tools registered too early can be cleared.

## Registration Timing

Initialize Ansight first, enable the narrowest guard, then register JavaScript-backed tools:

```ts
const builder = Ansight.createOptionsBuilder();

if (__DEV__) {
  builder.withReadOnlyToolAccess();
} else {
  builder.withToolsDisabled();
}

await Ansight.initializeAndActivate(builder.build());
await registerAnsightAppTools(diagnostics);
```

If tools are registered from a feature module, make registration idempotent and use stable ids so repeated app bootstrap does not create duplicate tool entries.

## Policy And Guard Choice

| Policy | Use for | Guard that enables it |
| --- | --- | --- |
| `"read"` | Inspecting app state without mutation. | `withReadOnlyToolAccess()` |
| `"write"` | Creating, updating, replaying, or resetting app state. | `withReadWriteToolAccess()` |
| `"critical"` | Destructive actions, secret access, broad runtime inspection, or arbitrary app-code invocation. | `withAllToolAccess()` |

Raise the maximum to `write` or `critical` only when the workflow genuinely depends on it.

## Verification

Run the app's actual checks, for example:

```bash
npm test
npm run typecheck
npx react-native run-ios
npx react-native run-android
```

Use the package manager and platform commands already used by the app.

After the app is paired and connected:

- `ansight app tools <session-id> --tool-id <tool-id> --detail full --include-unavailable --json` should return the exact custom tool entry and its denial state; invoke it only when `executable` is true
- `ansight app call <session-id> <tool-id> --arguments '{ "includeQueues": true }' --json` should invoke it
- if the tool is missing, check `__DEV__`, initialization order, registration timing, platform build, and guard
- if invocation fails, inspect the returned error, JavaScript logs, native logs, and argument parsing

## Done Criteria

- the tool has a stable id, category, description, policy, and structured result
- custom tool registration runs only in the intended development-only path
- distributable builds omit the tool or keep tools disabled
- JavaScript or native registration happens after the relevant Ansight initialization
- the active guard allows only the required policy
- the CLI can discover and invoke the tool in a paired local development session
- final response names the tool id, policy, JS or native registration path, files changed, and verification performed

ansight-install8.54 KB

View saved version →

---
name: ansight-install
description: Use this skill when installing or configuring Ansight but the app platform has not been selected yet. Install the Ansight CLI with the official platform script when needed, run ansight doctor to identify environment dependencies, obtain approval before installing missing tools, route to the matching platform-specific SDK skill, and finish with CLI enrollment and structured session verification.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/dotnet/ansight-install-dotnet.md → [ansight-install-dotnet](../ansight-install-dotnet/SKILL.md)
- https://www.ansight.ai/skills/ios/ansight-install-ios.md → [ansight-install-ios](../ansight-install-ios/SKILL.md)
- https://www.ansight.ai/skills/android/ansight-install-android.md → [ansight-install-android](../ansight-install-android/SKILL.md)
- https://www.ansight.ai/skills/react-native/ansight-install-react-native.md → [ansight-install-react-native](../ansight-install-react-native/SKILL.md)
- https://www.ansight.ai/skills/flutter/ansight-install-flutter.md → [ansight-install-flutter](../ansight-install-flutter/SKILL.md)
- https://www.ansight.ai/skills/cordova/ansight-install-cordova.md → [ansight-install-cordova](../ansight-install-cordova/SKILL.md)
- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)

# Ansight Install Router Skill

Use this skill when the user asks an agent to install or configure Ansight and the prompt does not already name the target SDK.

This is a routing skill. Do not perform a full SDK integration from this file. Identify the app platform, then fork into or load the matching platform-specific install skill and follow that skill as the source of truth.

## CLI Prerequisite

Treat the official website installers as the only supported CLI bootstrap. Do
not reconstruct their download, checksum, PATH, skill, account, or resident-host
steps manually.

1. Detect the current operating system and whether `ansight` resolves on PATH.
2. If the CLI is missing, show the matching command and ask the user to approve
running it. If the agent is authorized to install developer tooling, run the
approved command directly; otherwise ask the user to run it and wait for the
result.

macOS or Linux:

```sh
curl -fsSL https://www.ansight.ai/install.sh | bash
```

Windows PowerShell:

```powershell
irm https://www.ansight.ai/install.ps1 | iex
```

3. Open a new shell if PATH changes are not visible, then verify the installed
CLI rather than assuming installation succeeded:

```sh
ansight version --json
ansight doctor --json
```

The scripts are published with the website at
`https://www.ansight.ai/install.sh` and
`https://www.ansight.ai/install.ps1`.

## Doctor-Led Dependency Setup

Use `ansight doctor --json` as the source of truth for the current machine.
Do not guess dependencies from the app platform alone.

- Explain every required failure and every optional capability that affects the
requested workflow.
- Before using Homebrew, apt, dnf, winget, dotnet tool installation, npm, or any
other package manager, show the exact packages and commands and ask the user
to approve installing them.
- Do not install an optional dependency merely because Doctor reports it as
missing. Ask whether the user wants the feature it enables.
- After approved dependency changes, rerun `ansight doctor --json` and report
what changed. Do not claim the workstation is ready while a required check is
still failing.
- Use `https://www.ansight.ai/docs/cli/dependencies` for the platform-specific
installation commands and the feature enabled by each dependency.

## Routing Rules

Inspect the repo before choosing:

- Use the .NET install skill for .NET MAUI, .NET for Android, .NET for iOS, and .NET Mac Catalyst apps.
- Use the iOS install skill for native SwiftUI or UIKit apps.
- Use the Android install skill for native Android Kotlin apps.
- Use the React Native install skill for React Native apps and Expo development builds with generated iOS and Android native projects.
- Use the Flutter install skill for Flutter apps with Android and/or iOS targets.
- Use the Cordova / Capacitor install skill for Cordova-family or Ionic apps built with Capacitor 8.

If more than one app is present, ask which app should be configured unless the user's prompt clearly identifies one.

## Remote Tool Default

When the selected install enables reflection, mention the concrete `reflect.*` tool family and default the reflection package or suite to a development-time dependency: Debug or explicit local-development variants only, with runtime guards. Do not enable `reflect.*` for distributable builds unless the user explicitly requests it and accepts the policy.

## Platform Skills

| Platform | Use This Skill |
| --- | --- |
| .NET MAUI, .NET Android, .NET iOS, .NET Mac Catalyst | `https://www.ansight.ai/skills/dotnet/ansight-install-dotnet.md` |
| Native iOS SwiftUI or UIKit | `https://www.ansight.ai/skills/ios/ansight-install-ios.md` |
| Native Android Kotlin | `https://www.ansight.ai/skills/android/ansight-install-android.md` |
| React Native / Expo development build | `https://www.ansight.ai/skills/react-native/ansight-install-react-native.md` |
| Flutter | `https://www.ansight.ai/skills/flutter/ansight-install-flutter.md` |
| Cordova / Capacitor | `https://www.ansight.ai/skills/cordova/ansight-install-cordova.md` |

## Detection Hints

- `.csproj`, `MauiProgram.cs`, `TargetFramework` values such as `net*-android`, `net*-ios`, or `net*-maccatalyst`: .NET.
- `.xcodeproj`, `.xcworkspace`, `Package.swift`, `Podfile`, `Info.plist`, SwiftUI `App`, or UIKit `AppDelegate` without React Native app files: native iOS.
- `settings.gradle`, `build.gradle`, `build.gradle.kts`, `AndroidManifest.xml`, and Kotlin `Application` without React Native app files: native Android.
- `package.json` with `react-native` or `expo`, generated `ios/` and `android/` projects, `metro.config.*`, or `@react-native/*`: React Native / Expo development build.
- `pubspec.yaml` with a Flutter SDK dependency, `lib/main.dart`, and Flutter `android/` or `ios/` targets: Flutter.
- `package.json` with `@capacitor/core`, `capacitor.config.*`, and native `android/` or `ios/` projects: Cordova / Capacitor.

React Native and Expo, Flutter, and Capacitor take precedence over the native iOS or Android project folders they contain. Expo Go cannot load the native Ansight bridge; route only Expo development builds with generated native projects. If a classic Apache Cordova app does not use Capacitor 8, report that the current `@ansight/capacitor` adapter is not a drop-in target.

## Workflow

1. Install and verify the CLI through the [CLI prerequisite](#cli-prerequisite).
2. Run the [Doctor-led dependency setup](#doctor-led-dependency-setup), obtaining approval before installing missing tools.
3. Inspect the repository root and likely app directories.
4. Identify the target platform and app module.
5. If the current agent supports subagents or thread forking, fork the implementation into the matching platform-specific skill.
6. If the current agent cannot fork, load or follow the matching platform-specific skill directly in the current task.
7. Continue with the selected skill's workflow, including automatic host-local registration, one-shot physical-device QR enrollment, runtime guards, minimal platform privacy declarations, verification, and `ansight-readme.md`.
8. Use the Ansight CLI for host status, generic physical-device QR enrollment, connected-session discovery, optional post-discovery app-to-codebase registration, and tool verification. If CLI setup needs more detail, load `https://www.ansight.ai/skills/ansight-cli-setup.md`.
9. Include the selected skill URL in the final response so the user can audit which route was used.

Do not claim a platform-specific setup was completed until the selected skill's verification steps have actually passed or the remaining manual steps are listed.

ansight-install-android4.66 KB

View saved version →

---
name: ansight-install-android
description: Install the native Android Ansight SDK with automatic emulator registration and one-shot CLI QR enrollment for physical devices. Add the aggregate dependency, initialize from Application, expose the SDK scanner from a developer-only surface, keep remote tools development-only, verify the Gradle build, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/android/ansight-app-inspection-android.md → [ansight-app-inspection-android](../ansight-app-inspection-android/SKILL.md)

# Ansight Android Install Skill

Use this skill for native Android Kotlin or Java apps.

## Outcome

The finished app must:

- include `ai.ansight:ansight-android` in a local-development build;
- initialize Ansight once from `Application.onCreate()`;
- register automatically on an emulator and expose
`Ansight.enrollFromQrCode(activity)` from a developer-only UI for physical devices;
- reconnect automatically after the first successful scan;
- keep broad or mutating remote tools out of distributable builds; and
- require no generated JSON, build secret, certificate, or manual app registration.

## Workflow

1. Identify the app module, `Application` class, debug variant, and existing developer menu.
2. Add the aggregate dependency, normally:

```kotlin
dependencies {
debugImplementation("ai.ansight:ansight-android:1.4.0-preview.1")
}
```

3. Initialize from `Application.onCreate()`:

```kotlin
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
if (BuildConfig.DEBUG) {
Ansight.initializeAndActivateDeveloperMode(
application = this,
clientName = "Android App",
)
}
}
}
```

4. Add a developer-only action that owns an `Activity`:

```kotlin
Ansight.enrollFromQrCode(activity)
```

5. Do not add a camera permission. The SDK uses Google Code Scanner. The
aggregate SDK merges ordinary network access and clear-text development
traffic into the manifest.
6. Keep reflection, secure-storage access, writes, and deletes disabled unless
the requested development workflow requires them.
7. Create or update `ansight-readme.md` with the scanner location, build
verification command, and CLI enrollment commands. Do not add an enrollment
payload or token to it.
8. Run `./gradlew :app:assembleDebug` and relevant tests.
9. Start or reuse the resident CLI host. An emulator registers automatically.
For a physical device, issue one generic host QR and scan it from the
developer-only surface:

```sh
ansight host run
ansight pairing issue --qr
ansight session list --connected --app-id <app-id> --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json
```

Do not require `ansight app register` before the first connection. After the
SDK supplies its real App ID, optionally link the discovered app to the
repository with `ansight app register <app-id> --codebase <repository-path>`.

## Enrollment Behavior

An emulator registers automatically through loopback. For a physical device,
the developer runs `ansight pairing issue --qr` against the resident host and
scans the terminal QR once. The first connection registers the app installation and stores a random
installation id and enrollment state in app-private preferences. Later
developer launches reconnect automatically while the registration remains
active.

If the app already owns a scanner, pass its result through the SDK payload-text
connection API instead of adding a second scanner.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the native
Android companion only when Android platform semantics are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/android/ansight-app-inspection-android.md
```

ansight-install-cordova4.19 KB

View saved version →

---
name: ansight-install-cordova
description: Install @ansight/capacitor with automatic simulator or emulator registration and one-shot CLI QR enrollment for physical devices. Add and sync the Capacitor bridge, initialize native defaults, expose enrollFromQrCode from a developer-only surface, keep remote tools development-only, verify web and native builds, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/cordova/ansight-app-inspection-cordova.md → [ansight-app-inspection-cordova](../ansight-app-inspection-cordova/SKILL.md)

# Ansight Cordova / Capacitor Install Skill

Use this skill for Capacitor 8 apps. Classic Apache Cordova is not currently a
drop-in target for `@ansight/capacitor`.

## Workflow

1. Inspect `package.json`, Capacitor config, web bootstrap, native projects,
debug guard, and existing developer menu.
2. Install and sync:

```shell
npm install @ansight/capacitor
npx cap sync
```

3. Initialize from development-only bootstrap:

```ts
if (isDevelopmentBuild) {
await Ansight.initializeAndActivate(
Ansight.createOptionsBuilder()
.withAnsightDefaults()
.withReadOnlyToolAccess()
.build(),
);
}
```

Replace `isDevelopmentBuild` with the app's existing explicit development
variant flag; do not hard-code it to `true`.

4. Add a developer-only scanner action:

```ts
await Ansight.enrollFromQrCode({
clientName: "My Capacitor App",
});
```

5. `scanPairingQrCode(...)` is an API alias. Use `connect(payload, ...)` when
the app already owns a scanner.
6. Keep DOM and native tools behind the app's local-development guard. Prefer
read-only DOM and native inspection; leave actions, reflection, secure
storage, writes, and deletes off unless required.
7. Android requires no app camera permission for the SDK scanner. On iOS, add
`NSCameraUsageDescription` and `NSLocalNetworkUsageDescription`. Add no ATS
exception or unrelated permissions.
8. Create or update `ansight-readme.md` with the scanner location, selected
tools, build checks, and CLI enrollment commands. Do not include an enrollment payload.
9. Run package checks, `npx cap sync`, and practical native debug builds.
10. Start or reuse the resident CLI host. A simulator or emulator registers
automatically. For a physical device, issue one generic host QR and scan it
from the developer-only surface:

Do not require `ansight app register` before the first connection. After
the SDK supplies its real App ID, optionally link the discovered app to the
repository with `ansight app register <app-id> --codebase <repository-path>`.

Simulator and emulator builds register automatically through native loopback.
The first physical-device scan registers the native app installation. Its random installation
id and enrollment state remain in app-private storage, so later developer
launches reconnect automatically.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the Capacitor
companion only when DOM, bridge, or native-platform semantics are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/cordova/ansight-app-inspection-cordova.md
```

ansight-install-dotnet4.15 KB

View saved version →

---
name: ansight-install-dotnet
description: Install Ansight in a .NET MAUI, Android, iOS, or Mac Catalyst app with automatic local CLI-host registration and one-shot QR enrollment for physical devices. Add the all-in-one package, initialize at app startup, expose the SDK scanner from a developer-only surface, keep remote tools development-only, verify target builds, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Run Ansight CLI commands using the execution tools in ChatGPT Work or Codex on the machine that owns the resident host. If this environment cannot execute commands or reach that host, explain the missing prerequisite and do not claim a live inspection succeeded. A remote workspace or cloud agent does not automatically have access to the developer’s local host. Resolve relative helper paths from this skill’s directory. When this workflow references another bundled skill, read its local SKILL.md completely before following it.

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/dotnet/ansight-app-inspection-dotnet.md → [ansight-app-inspection-dotnet](../ansight-app-inspection-dotnet/SKILL.md)


# Ansight .NET Install Skill

Use this skill for .NET MAUI, .NET for Android, .NET for iOS, and .NET Mac
Catalyst apps.

## Workflow

1. Identify the app project, target frameworks, startup path, debug guard, and
   existing developer menu.
2. For MAUI, install the all-in-one package:

```shell
dotnet add package Ansight.Maui --prerelease
```

   Then initialize before `builder.Build()`:

```csharp
builder.UseMauiApp<App>();

#if DEBUG
builder.UseAnsight<App>();
#endif
```

   For non-MAUI apps, install `Ansight` and initialize:

```csharp
#if DEBUG
var options = Options.CreateBuilder()
    .WithAnsightSdk()
    .Build();

Runtime.InitializeAndActivate(options);
#endif
```

3. Add a developer-only scanner action:

```csharp
var result = await Runtime.HostConnection.ConnectAsync(
    HostConnectionRequest.QrCode());
```

4. If the app already owns a QR scanner, pass its text through
   `HostConnectionRequest.PayloadText(...)`.
5. Keep all-in-one and broad remote-tool packages in local-development builds.
   Use a protected Release/CI policy for distributable builds.
6. Add only platform privacy declarations needed by the scanner and local
   network flow. Do not add an embedded resource, MSBuild-generated enrollment
   file, certificate, or host address.
7. Create or update `ansight-readme.md` with the scanner location, tool policy,
   build checks, and CLI enrollment commands. Do not include an enrollment payload or token.
8. Run `dotnet build` and relevant tests for every target changed.
9. Start or reuse the resident CLI host. A simulator, emulator, Mac Catalyst,
   or desktop build registers automatically. For a physical device, issue one
   generic host QR and scan it from the developer-only surface:

```sh
ansight host run
ansight pairing issue --qr
ansight session list --connected --app-id <app-id> --json
ansight app tools <session-id> --detail summary --include-unavailable --max-results 50 --json
```

   Do not require `ansight app register` before the first connection. After the
   SDK has supplied its real App ID, optionally link that discovered app to its
   repository with `ansight app register <app-id> --codebase <repository-path>`.

## Enrollment Behavior

Host-local targets register through automatic loopback and do not need a scan.
The first physical-device scan registers the installation and stores a random installation id
and enrollment state in app-private storage. `HostConnectionRequest.Auto()` and
normal host auto-probe reconnect it on later developer launches.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the .NET
companion only when MAUI or .NET-specific semantics are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/dotnet/ansight-app-inspection-dotnet.md
```

ansight-install-flutter3.92 KB

View saved version →

---
name: ansight-install-flutter
description: Install ansight_flutter with automatic simulator or emulator registration and one-shot CLI QR enrollment for physical devices. Add the package, initialize the runtime and instrumentation, expose enrollFromQrCode from a developer-only surface, configure required native privacy declarations, verify Flutter and native builds, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/flutter/ansight-app-inspection-flutter.md → [ansight-app-inspection-flutter](../ansight-app-inspection-flutter/SKILL.md)

# Ansight Flutter Install Skill

Use this skill for Flutter apps with Android and/or iOS targets.

## Workflow

1. Inspect `pubspec.yaml`, `main.dart`, target platforms, debug guard, and
existing developer menu.
2. Add `ansight_flutter: 1.4.0-preview.1` and run `flutter pub get`.
3. Initialize after `WidgetsFlutterBinding.ensureInitialized()` and before
`runApp(...)`:

```dart
if (kDebugMode) {
await Ansight.instance.initializeAndActivate(AnsightOptions.developer());
await AnsightFlutterInstrumentation.instance.install();
}
```

4. Add a developer-only scanner action:

```dart
await Ansight.instance.enrollFromQrCode(
clientName: 'My Flutter App',
);
```

5. `scanPairingQrCode(...)` is an API alias. Use the payload connection API
when the app already owns a scanner.
6. Keep widget and native tools behind `kDebugMode` or an equivalent explicit
developer variant. Prefer read-only access.
7. Android requires no app camera permission for the SDK scanner. On iOS, add
`NSCameraUsageDescription` and `NSLocalNetworkUsageDescription`. Add no ATS
exception or unrelated permissions.
8. Create or update `ansight-readme.md` with the scanner location, tool profile,
build checks, and CLI enrollment commands. Do not include an enrollment payload.
9. Run `flutter analyze`, `flutter test`, and practical target builds.
10. Start or reuse the resident CLI host. A simulator or emulator registers
automatically. For a physical device, issue one generic host QR and scan it
from the developer-only surface:

Do not require `ansight app register` before the first connection. After
the SDK supplies its real App ID, optionally link the discovered app to the
repository with `ansight app register <app-id> --codebase <repository-path>`.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the Flutter
companion only when widget or native-platform semantics are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/flutter/ansight-app-inspection-flutter.md
```

ansight-install-ios4.66 KB

View saved version →

---
name: ansight-install-ios
description: Install the native iOS Ansight SDK with automatic Simulator registration and one-shot CLI QR enrollment for physical devices. Add the aggregate SwiftPM product or pod, initialize from app startup, expose the SDK scanner from a developer-only surface, add only Apple-required privacy descriptions, verify the build, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md → [ansight-app-inspection-ios](../ansight-app-inspection-ios/SKILL.md)

# Ansight iOS Install Skill

Use this skill for native SwiftUI or UIKit apps.

## Outcome

The finished app must:

- link the aggregate `Ansight` product for local development;
- initialize `AnsightRuntime.shared` once from app startup;
- register automatically in Simulator or Mac Catalyst and expose the SDK QR
scanner from a developer-only UI for physical devices;
- reconnect automatically after the first successful scan;
- add only the privacy descriptions required by the chosen flow; and
- require no generated JSON, build setting secret, certificate, or manual app
registration.

## Workflow

1. Identify the app target, bundle id, startup delegate, dependency manager,
debug configuration, and existing developer menu.
2. Add the aggregate SwiftPM product:

```swift
.package(
url: "https://github.com/ansight-ai/ansight-sdk.git",
exact: "1.4.0-preview.1"
)
```

Use `pod 'Ansight', '1.4.0-preview.1'` when the project already uses
CocoaPods.
3. Keep both the import and initialization behind the app's Debug or explicit
internal-build compilation condition. Initialize once:

```swift
#if DEBUG
try AnsightRuntime.shared.initializeAndActivateAnsightSdk()
#endif
```

4. Add a developer-only scanner action:

```swift
let result = await AnsightRuntime.shared.connect(
.qrCode(title: "Scan Ansight Enrollment QR")
)
```

5. Add `NSCameraUsageDescription` because the SDK scanner uses the camera. Add
`NSLocalNetworkUsageDescription` for physical devices connecting to the CLI host.
Do not add Bluetooth, location, contacts, photos, Bonjour, or ATS clear-text
exceptions.
6. Keep reflection, secure-storage access, writes, and deletes disabled unless
the requested development workflow requires them.
7. Create or update `ansight-readme.md` with the scanner location, build
verification command, and CLI enrollment commands. Do not add an enrollment
payload or token to it.
8. Build the relevant simulator and, where practical, physical-device target.
9. Start or reuse the resident CLI host. Simulator and Mac Catalyst builds
register automatically. For a physical device, issue one generic host QR and
scan it from the developer-only surface:

## Enrollment Behavior

Simulator and Mac Catalyst register automatically through loopback. The first
physical-device scan registers the app installation and stores a random installation
id and enrollment state privately. Later developer launches reconnect
automatically. The client uses Network.framework for its local clear-text
`ws://` development connection, so no ATS exception or certificate is needed.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the native iOS
companion only when SwiftUI, UIKit, or Apple-platform semantics are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/ios/ansight-app-inspection-ios.md
```

ansight-install-react-native4.1 KB

View saved version →

---
name: ansight-install-react-native
description: Install @ansight/react-native in React Native or Expo development builds with automatic simulator or emulator registration and one-shot CLI QR enrollment for physical devices. Add and link the package, initialize native defaults, expose enrollFromQrCode from a developer-only surface, keep remote tools development-only, verify JavaScript and native builds, and inspect the app through the Ansight CLI.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/agents/ansight-app-inspection.md → [ansight-app-inspection](../ansight-app-inspection/SKILL.md)
- https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md → [ansight-app-inspection-react-native](../ansight-app-inspection-react-native/SKILL.md)

# Ansight React Native Install Skill

Use this skill for React Native apps, including Expo development builds, with native Android and iOS projects. Expo Go cannot load the native Ansight bridge.

## Workflow

1. Identify the package manager, bootstrap path, native projects, app ids,
debug guard, and existing developer menu.
2. Install and link:

```shell
npm install @ansight/react-native
npx pod-install
```

3. Initialize once from app bootstrap:

```ts
if (__DEV__) {
await Ansight.initializeAndActivate({
useNativeAllInOneDefaults: true,
toolGuard: "readOnly",
});
}
```

4. Add a developer-only scanner action:

```ts
await Ansight.enrollFromQrCode({
clientName: "React Native App",
});
```

5. `scanPairingQrCode(...)` is an API alias. If the app already owns a scanner,
pass its result to `connect(...)`.
6. Keep native and React inspection tools behind `__DEV__` or the app's
equivalent local-development guard. Disable tools outside that guard.
7. Android requires no app camera permission for the SDK scanner. On iOS, add
`NSCameraUsageDescription` and `NSLocalNetworkUsageDescription`. Add no ATS
exception or unrelated permissions.
8. Create or update `ansight-readme.md` with the scanner location, selected tool
profile, build checks, and CLI enrollment commands. Do not include an enrollment payload.
9. Run JavaScript checks and practical Android/iOS debug builds.
10. Start or reuse the resident CLI host. A simulator or emulator registers
automatically. For a physical device, issue one generic host QR and scan it
from the developer-only surface:

Do not require `ansight app register` before the first connection. After
the SDK supplies its real App ID, optionally link the discovered app to the
repository with `ansight app register <app-id> --codebase <repository-path>`.

## Enrollment Behavior

Simulator and emulator builds register automatically through native loopback.
The first physical-device scan registers the native app installation. Its random installation
id and enrollment state remain in app-private native storage, so later
developer launches reconnect automatically.

## Recommended Inspection Skills

Use the main router to select the core inspection workflow. Add the React
Native companion only when React, shadow-tree, or native-rendering semantics
are material:

```text
https://www.ansight.ai/skills/agents/ansight-app-inspection.md
https://www.ansight.ai/skills/react-native/ansight-app-inspection-react-native.md
```

ansight-investigate-session8.92 KB

View saved version →

---
name: ansight-investigate-session
description: Investigate one live or recorded Ansight session through retained evidence. Use to bracket and correlate logs, network, telemetry, screenshots, trees, touches, artifacts, and annotations or create an evidence slice; do not use to prepare the workstation, drive the live UI, or write annotations.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

# Investigate An Ansight Session

Build a timestamped evidence trail from one exact session before reading source code or proposing a cause. Treat missing evidence as a finding, not permission to fill gaps with assumptions.

Use `--json` throughout. Keep timestamps in UTC and preserve source IDs such as frame IDs, snapshot IDs, request IDs, annotation IDs, channel IDs, and artifact snapshot IDs.

## Prerequisites And Routing

Recorded-session investigation requires the Ansight CLI or another exposed Ansight diagnostic surface and a session available from local history or an imported archive. The target app does not need to remain installed, connected, or currently integrated with the SDK when retained evidence is sufficient.

- For a live investigation, the app's development or QA build must contain an initialized Ansight SDK and be connected to the host. Use the Ansight Operate Live App skill to establish that session.
- If the SDK integration is missing and new live evidence must be captured, follow `https://www.ansight.ai/skills/ansight-install.md`.
- If the CLI or resident host cannot access local or imported sessions, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.

Do not require or install the SDK merely to inspect an existing recorded or imported session.

## Select The Session

Start with focused discovery. When the user supplied an exact session ID, query
the lightweight session-summary index and confirm that the returned
`sessionId` is an exact match:

```sh
ansight session list --app-id <app-id> --from <utc> --to <utc> --limit 20 --json
ansight session list --search <session-id> --limit 1 --json
```

Do not use `ansight session show <session-id> --json` for discovery. Its JSON
response can materialize the session's retained logs, metrics, and visual trees,
which is unnecessarily large for agent context. Use the summary index above,
then query only the evidence surface needed for the investigation.

Add `--connected` only when the task requires a live session. Use app identity, device profile, capture time, tags, retained evidence totals, and connection state to choose. Do not silently choose among multiple plausible sessions.
The time filters select sessions whose capture intervals overlap the requested
range. Follow `nextCursor` with `--cursor` only when the first filtered page is
insufficient, preserving the same filters between pages.

Read existing annotations early because they may already define the relevant moment or region:

```sh
ansight session annotations <session-id> --json
```

## Bracket The Investigation

Define the smallest interval that can answer the question. Prefer, in order:

1. an existing annotation's `startUtc` and `endUtc`;
2. a stable app event, log, request, touch, or screenshot timestamp near the reproduction;
3. a narrow interval around a telemetry detector result;
4. the whole session only when no reliable anchor exists.

State the interval before correlating evidence. Expand it deliberately when a cause may precede the visible symptom.

## Reuse Workspace Evidence Boundaries

When a linked `ansight/` workspace exists, use its maintained definitions as evidence leads: Trends results can provide established observation spans, telemetry budgets, and regression comparisons, while triggers can explain automatically captured artifacts. Confirm that each definition's App ID, event labels, inputs, and session match the investigation before relying on it. Route any request to create or change these definitions to the Ansight Workspace Automation skill.

## Build The Evidence Stack

Use the surfaces that match the hypothesis rather than dumping every retained item.

### Logs And Network

```sh
ansight session logs <session-id> --start <utc> --end <utc> --minimum-priority warning --json
ansight session logs <session-id> --start <utc> --end <utc> --contains <text> --json
ansight session network <session-id> --start <utc> --end <utc> --failed --json
ansight session network <session-id> --start <utc> --end <utc> --host <host> --json
```

Begin with high-signal filters, then widen severity, streams, sources, tags, status classes, or text only as needed. Include network bodies only when the request needs them and captured content is safe to inspect.

### Telemetry

Run the built-in detectors as leads:

```sh
ansight session telemetry analyze <session-id> --kind all --json
```

Use `--kind fps-drop` or `--kind memory-spike` for a focused check. Threshold flags change detector sensitivity; they do not establish a product requirement. Use `--fail-on-detection` only when exit code `11` should mean a finding was detected.

Inspect channel metadata and samples:

```sh
ansight session metrics <session-id> --json
ansight session metrics <session-id> --channel <channel-id> --limit <count> --json
```

The metrics command selects by channel and newest-sample limit, not by time range. Choose a limit that includes the investigation interval, then filter and correlate the returned UTC sample timestamps. Never imply that `--limit` isolated a time window.

### Visual And Interaction Evidence

```sh
ansight session images <session-id> --json
ansight session trees <session-id> --json
ansight session touches <session-id> --json
```

Join screenshots and visual trees through `screenshotFrameId` and nearby capture timestamps. Use touches to establish what input occurred, not whether the intended postcondition succeeded. Export one relevant frame when visual inspection is needed:

```sh
ansight session screenshot export <session-id> --frame-id <frame-id> --output <path>
```

### App-Supplied Evidence

```sh
ansight session artifacts <session-id> --json
ansight session artifact export <session-id> --snapshot-id <id> --path <artifact-path> --output <path>
```

Inspect only artifacts relevant to the hypothesis. Preserve their snapshot ID, capture time, and path in the report.

## Slice Evidence Safely

| Need | Preferred action |
| --- | --- |
| Inspect a narrow log or network interval | Use `--start` and `--end`; do not create another session |
| Correlate all evidence surfaces for a durable interval | Create a derived session with `session extract` |
| Reuse an annotation's exact interval | Extract by annotation ID |
| Remove evidence from the original session | Use `session trim` only with explicit authorization |

Create a non-destructive derived slice only when the user asks to retain, hand off, replay, or repeatedly inspect it:

```sh
ansight session extract <session-id> --start <utc> --end <utc> --name <name> --json
ansight session extract <session-id> --annotation <annotation-id> --name <name> --json
```

The new session is a separate local capture. Record its returned session ID. Do not call `session trim` during ordinary investigation: `cut` and `keep` mutate the existing session timeline.

## Correlate Before Concluding

For each candidate explanation:

1. Identify the earliest supporting event.
2. Check what changed immediately before and after it across an independent surface when available.
3. Distinguish correlation from causation.
4. Check for contradictory evidence and normal control periods.
5. State capture gaps, truncation, missing channels, sparse screenshots, or absent visual trees.

Prefer runtime evidence over a source-only explanation. Read source after the observed behavior identifies a component, handler, request, or state transition to inspect.

## Report A Reproducible Evidence Trail

Report the selected session and why it matched; UTC interval and anchor; material commands and filters; timestamped observations with IDs; strongest supported explanation and confidence; contradictory or missing evidence; any derived slice and its session ID; and the smallest next verification step.

Do not present detector output, an input attempt, or a single coincident log as proof by itself.

Referenced files: 1

ansight-operate-live-app18.1 KB

View saved version →

---
name: ansight-operate-live-app
description: Operate an Ansight-connected app through its live lifecycle or visible semantic UI while preserving before-and-after evidence. Use to boot a target, launch or stop an app, resolve a live session, interact, or verify visible state; do not use merely to prepare the CLI, analyze a recording, or call app-internal remote tools.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

# Operate A Live App With Ansight

Establish one exact live session, observe before acting, perform the smallest authorized interaction, and verify the outcome from fresh evidence. Use `--json` for discovery and evidence commands, and keep the selected session ID explicit after resolution.

## Prerequisites And Routing

Live operation requires the Ansight SDK to be installed, initialized, and enabled in the app's development or QA build. Keep SDK enrollment, capture, and remote capabilities excluded from protected builds unless the app's documented policy explicitly permits them.

- If the app does not contain a working Ansight SDK integration, follow `https://www.ansight.ai/skills/ansight-install.md` before attempting live operation.
- If the `ansight` executable, resident host, or device dependencies are not ready, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.
- If a development build is connected but the requested work needs app-internal tools, follow the Ansight Remote App Tools skill after resolving the session.

Do not install or modify the SDK merely because no session is currently connected. First distinguish a missing integration from an app that is stopped, using the wrong build configuration, or temporarily disconnected.

## Keep The Lifecycle Layers Separate

| Layer | Start or attach | Stop | Meaning |
| --- | --- | --- | --- |
| Resident host | `ansight host status --json`; `ansight host run` | `ansight host stop` | Local capture and control service shared by sessions |
| Device | `ansight device list --json`; `ansight device start <platform> <device-id>` | `ansight device shutdown <platform> <device-id>` | Simulator, emulator, or physical target |
| App process | `ansight device launch <platform> <device-id> <app-id>` | `ansight device terminate <platform> <device-id> <app-id>` | Installed app instance |
| Ansight session | The SDK connects when the enabled app reaches the host | `ansight session disconnect <session-id>` | Live evidence stream retained as a recording after disconnect |

There is no separate `ansight session start` command. Start the host and app, then discover the session created by the SDK connection. `session delete` removes retained data; it is not a stop command.

Do not stop a host, device, or app that was already running unless the user asked. A resident host can be shared by other work.

## Choose Device Window Behavior

Device launches show simulator/emulator windows by default. When the user wants
windowless operation, pass `--headless` on the command that starts the device:

```sh
ansight device start ios <simulator-id> --headless --json
ansight device start android <avd-name> --headless --json
```

The same flag applies to automatic launches by `app execute`, `app-graph explore
--launch`, replay, tests, and profiling, plus tool-requested starts during a
command. iOS skips opening Simulator.app; new Android emulators use `-no-window`.
It does not close existing windows, restart running emulators, or affect physical
devices. Reusing a connected session leaves its window state unchanged.
`--json`, `--silent`, and CI do not imply headless mode.

## Establish The Exact Session

1. Check the host:

```sh
ansight host status --json
```

If the CLI or workstation is not configured, follow the Ansight CLI Setup skill. If no host is running and live control is required, run `ansight host run` in a durable terminal and leave it attached.

2. Inspect devices only when the app must be launched or the user named a target:

```sh
ansight device list --all --json
```

Start only the exact simulator or emulator needed. A physical iOS target is verified rather than booted.

3. Launch the installed development or QA app when it is not already running:

```sh
ansight device launch <ios|android> <device-id> <app-id> --json
```

4. Discover and select the live session:

```sh
ansight session list --connected --app-id <app-id> --limit 20 --json
ansight session show <session-id> --json
```

Match the App ID, device profile, platform, and connection state. If multiple sessions still match, do not choose the newest silently; use the user's supplied device or ask which instance is in scope.
Follow `nextCursor` with `--cursor` only when the first filtered page does
not contain the intended session, and keep the same filters on later pages.

5. Record the session ID and initial observation timestamp or evidence IDs.

## Fast Direct Exploration

For interactive exploration or human-style navigation, prefer one persistent process:

```sh
ansight app interact --session <session-id> --jsonl
```

Retain its process/PTY handle and write JSON Lines to stdin; do not start a new
CLI process for every gesture. The resident-host pipe remains open. This is direct
control by the current agent, not `app execute` or a delegated agent.

The initial `ready` response and every action include a compact `ui` observation
from fresh accessibility/visual trees, plus an automatically retained screenshot.
Prefer `ui.nodes` to choose and verify semantic targets; no separate tree or
screenshot request is needed. Use exact automation IDs, or exact text narrowed by
role and `ancestorAutomationId`. The bridge resolves targets freshly and refuses
missing or ambiguous matches without input:

```json
{"id":"query","command":"type","target":{"automationId":"search-field"},"value":"Kalymnos"}
{"id":"select","command":"tap","target":{"text":"Kalymnos","role":"button"}}
```

These IDs are examples; use those actually observed. Targeted `type` focuses and
replaces the field by default; `replaceExisting:false` appends. Untargeted `type`
appends to the focused field. Never mix a target and coordinates. Trees are bounded
to 128 visible semantic nodes and 256 characters per text field; `ui.truncated`
means absence is not proof that a target does not exist. Use focused semantic
inspection below for omitted details or longer exact selectors.

View `screenshot.artifactPath` for custom-rendered controls, visual questions,
missing/insufficient tree semantics, or a mismatch between tree and expected state.
The PNG is an SDK app screenshot, not a generated image. Coordinates are a fallback
normalized to that screenshot (0–1):

```json
{"id":"1","command":"tap","x":0.5,"y":0.8}
{"id":"2","command":"swipe","x":0.5,"y":0.8,"endX":0.5,"endY":0.2}
{"id":"3","command":"pinch","x":0.5,"y":0.5,"scale":1.5}
{"id":"4","command":"type","value":"Kalymnos"}
{"id":"5","command":"back"}
```

Read each result before deciding an unknown next target. `snapshot` optionally
refreshes asynchronous state; do not append it routinely after an action or task.
Evidence capture is implicit. Screenshots use bounded visual settling (300 ms
quietness, a 900 ms grace for unchanged screens, and a 2 s sampling window).
`screenshot.settling.status` is `stable`, `unchanged`, or `timed_out`; quiet pixels
do not prove a network request or semantic goal completed. `ui_unsettled` stops a
batch and retains the latest screenshot; inspect before continuing, never replay
the action just to obtain evidence.
`previousScreenshot` is the last observed frame, not a claim that nothing changed
since then. Reobserve when the app may have changed independently.

For a known sequence that needs no intermediate decisions, send one batch instead
of paying a tool round trip for every action:

```json
{"id":"search","command":"batch","commands":[{"id":"focus","command":"tap","x":0.5,"y":0.8},{"id":"query","command":"type","value":"Kalymnos"}]}
```

Batches run in order, with automatic evidence for every action. The response has
ordered `results` and `skippedIds`; execution stops at the first failure, including
missing evidence or a timeout. Earlier actions are not rolled back. Never replay
the whole batch after partial completion. Use 1–32 commands with unique IDs
(including the batch ID), no nested batches or `exit`, and at most 65536 characters
per line. Check child statuses, then use the top-level `ui` and `screenshot` for
the final executed child's state. Inspect intermediate screenshots only when a
failure, visual question, or missing semantic evidence requires it. Top-level
`timing` separates summed input/capture time from host batch wall time; it excludes
the agent's reasoning and tool round trips.

To reuse maintained tasks, pin the trusted repository when opening the process:

```sh
ansight app interact --session <session-id> --repository <repository-root> --jsonl
```

```json
{"id":"catalog","command":"tasks"}
{"id":"run","command":"task","taskId":"search.find","input":{"query":"Kalymnos"}}
```

Use the returned catalog's exact task ID and input schema. `task` uses the existing
task engine in the same app/session, captures resulting evidence automatically,
and returns `task.status`, named assertions and tool calls. Only `Passed` is
successful; a normal return without assertions is `Inconclusive`. Task commands
can be batch children. Run only behavior the user authorized; opening the bridge
does not authorize every available task. Default action timeout is 15 seconds;
task timeout is 120 seconds (`--timeout-ms` up to 60000 and `--task-timeout-ms` up
to 300000). A timeout/disconnect can leave execution uncertain and fresh evidence
unavailable; observe before deciding how to recover.

Before manually beginning a maintained multi-step flow, inspect the matching task's
complete behavior once (including its source when the catalog is ambiguous).
If it enters a query and selects a result, invoke it with the query directly—do
not focus/type first and then have the task repeat those steps. If a user explicitly
wants manual exploration, keep that route instead of running the same task afterward.

Failures report whether input succeeded and whether evidence is available. Do not
blindly repeat a timed-out action; it may already have executed. An `exit` command
or stdin EOF detaches without stopping the app or host. Ctrl+C cancels the connection.
If the installed CLI/host does not support `app interact`, use the semantic workflow
below and report the limitation; do not restart a shared host without authorization.

Use focused semantic inspection below for assertions or details omitted from `ui`.
Do not repeatedly request full trees or discover workspace tasks merely
to navigate quickly when the user requested direct exploration.

## Reuse Existing Workspace Behavior

Before manually performing a multi-step flow, make one focused repository-task search when a linked workspace exists and the request resembles maintained repeatable behavior:

When already connected with `--repository`, send `tasks` on that connection and
use `task` to execute the selected behavior. Do not open a separate CLI process.
Otherwise use:

```sh
ansight task list --app-id <app-id> --repository <repository-root> --json
```

Run a returned task only when its complete behavior and input schema exactly match the request. Treat a passed task and its named assertions as authoritative evidence; do not replay a failed, rejected, or inconclusive task manually and risk duplicating state changes. Skip task discovery for a simple one-step interaction or when no repository workspace is linked. Run a whole workspace test only when the user requested that scenario.

## Observe Before Acting

For precise semantic workflows (as distinct from screenshot-driven exploration), start with:

```sh
ansight ui snapshot --session <session-id> --json
ansight ui find --session <session-id> --automation-id <id> --json
```

Use the narrowest stable selector available:

1. exact `--automation-id`;
2. exact text plus role;
3. an ancestor-qualified selector;
4. `--index` only after a fresh find proves the intended match.

All supplied selector fields constrain the same node. Treat node identifiers and result indexes as observation-scoped. Re-observe after navigation, dialogs, list changes, or other material state transitions.

If in-process framework or domain state would answer the question more directly, follow the Ansight Remote App Tools skill instead of guessing from the UI.

## Interact And Capture Evidence

Use one small action at a time:

```sh
ansight ui tap --session <session-id> --automation-id <id> --json
ansight ui type --session <session-id> --automation-id <id> --value <text> --json
ansight ui swipe --session <session-id> --ancestor <id> --direction up --length 0.6 --json
ansight ui pinch --session <session-id> --automation-id <id> --scale 1.8 --json
ansight ui back --session <session-id> --json
```

UI actions use real device input and return structured before-and-after evidence. The persistent bridge is the tree-first fast path; these one-shot commands provide richer selectors and assertions. Raw `ansight input` is a fallback when these surfaces have a concrete capability gap.

Do not mutate app state merely to make an assertion pass. A validation-only request authorizes observation, not repair.

## Record Bounded Executions In Depth

`app execute`, `app-graph run`, and `app-graph explore` accept
`--reasoning fast|balanced|deep`. Omitting it selects **Fast**, the normal default
for responsive execution. Balanced and Deep express progressively greater
emphasis on reasoning depth; actual model and provider budget come from the
server configuration. Every mode must satisfy the same requested steps and
verification. Preserve the user's selected mode; do not automatically raise it
after a failure.

This is the same **Reasoning mode** used by agentic test runs, session replay, and
AI task extraction in Session Replay. The server resolves the model and provider
reasoning effort from the client's configuration and selects the credential
handoff. Leave `--model-transport` at its default `auto` unless a transport override
is requested for diagnostics; no `--execution` flag is needed. The hidden legacy
`--model` override is for diagnostics and cannot be combined with explicit
`--reasoning`.

For example, when the user requests Deep:

```sh
ansight app execute <session-id> --reasoning deep --prompt "<goal>" --json
```

When the user needs a replayable or exportable account of an agent-driven run, add `--trace` to the command that performs it:

```sh
ansight app execute <session-id> --prompt "<goal>" --trace --json
ansight app execute <session-id> --prompt "<goal>" --app-graph --trace --json
ansight app-graph run <graph-id> <session-id> --trace --json
ansight app-graph explore <app-id> --trace --json
```

For `app execute`, `--trace` retains the full model context, assistant text, tool payloads, App Graph plan details, and exportable execution graph. App Graph `run` and `explore` use it to retain the full exportable agent trace. Without the flag, Ansight deliberately stores only lightweight audit metadata such as status, timing, token and call counts, and payload hashes.

Use `--trace` when the run must be inspected in depth, replayed in the local player, exported, or used as detailed evaluation evidence. Treat the resulting trace as potentially sensitive because it can contain model context and tool payload bodies; do not enable it solely to obtain ordinary status or timing evidence.

## Wait And Verify

Wait for a specific asynchronous state instead of sleeping:

```sh
ansight ui wait --session <session-id> --automation-id <id> --condition visible --timeout-ms 15000 --json
```

Then verify the requested postcondition from fresh state:

```sh
ansight ui assert --session <session-id> --automation-id <id> --expected-visible true --json
ansight ui snapshot --session <session-id> --json
```

An action response proves that input was attempted. It does not prove the requested outcome. Use an assertion, focused observation, or resulting session evidence for that conclusion.

## End Only The Intended Layer

- When the user wants an `app execute` run to close the app afterward, add `--close-app-on-completion`. It closes only that app process after success, failure, or cancellation, including when reusing an existing session. Multi-device runs close each selected app instance. The device, its window, and the resident host stay running. The default is to leave the app open; `--headless` controls windowless startup independently. A cleanup warning means the app may still be running; do not claim it closed without verification.
- End the live evidence stream while retaining the recording: `ansight session disconnect <session-id> --json`.
- Stop the app process: `ansight device terminate <platform> <device-id> <app-id> --json`.
- Shut down a virtual target only when the user requested it or this workflow exclusively started it.
- Stop the resident host only when explicitly requested or when this workflow started a dedicated host and no other session depends on it.

The app may reconnect while its SDK remains active. After a requested stop, confirm with `ansight session list --connected --app-id <app-id> --limit 20 --json`.

## Report The Evidence Trail

Report the selected App ID, device, and session; initial observation; each state-changing CLI command; fresh verification; important timestamps or evidence IDs; and any fallback outside Ansight. Distinguish observed state, executed action, and inferred explanation.

Referenced files: 1

ansight-ui-testing27.5 KB

View saved version →

---
name: ansight-ui-testing
description: Initialize, author, extract, debug, validate, run, or maintain source-controlled Ansight workspace automation. Use for tests, tasks, triggers, trends, sanitizers, schemas, or workspace registration; do not use for routine live interaction, session investigation, or readiness scoring unless needed to build or verify a workspace asset.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

- https://www.ansight.ai/skills/ansight-cli-setup.md → [ansight-cli-setup](../ansight-cli-setup/SKILL.md)
- https://www.ansight.ai/skills/ansight-install.md → [ansight-install](../ansight-install/SKILL.md)

# Ansight Workspace Automation

Build and maintain the repository-owned `ansight/` playbook for one app. Prefer the Ansight CLI for workspace initialization, scaffolding, discovery, execution, and validation. Edit the generated source files when their behavior or policy must be implemented.

## Understand The Workspace Components

| Component | What it accomplishes | Why use it |
| --- | --- | --- |
| Test (`ansight/tests/**/*.json`) | Gives a bounded agent a natural-language user journey and observable final-state validation. | Use it when the path requires observation or decisions and success can be proved through Ansight evidence. |
| Task (`ansight/tasks/**/*.ts`) | Encodes an explicitly invoked, deterministic sequence of known tool calls with named assertions. | Use it to make a stable app-specific workflow faster, cheaper, and repeatable without asking an agent to rediscover every step. |
| Trigger (`ansight/triggers/**/*.ts`) | Reacts automatically to one matching app or session event and may request one bounded app action. | Use it to enrich future session evidence at a meaningful moment, such as capturing app-owned diagnostics after an error. Do not use it as a scheduler or general background worker. |
| Trends (`ansight/trends/**/*.json`) | Defines a stable SDK-event observation span, calculates deterministic telemetry metrics, evaluates fixed budgets, and optionally compares each metric with comparable historical runs. | Use it for repeatable FPS, memory, duration, evidence, or other numeric trend rules and regression monitoring rather than subjective agent judgment. |
| Sanitizer (`ansight/sanitizers/**/*.ts`) | Redacts, transforms, or removes sensitive content while Ansight creates a separate session archive. | Use it before exporting or sharing captured data; it does not modify the original session. |
| Schemas and support files (`ansight/schema`, declarations, and `tsconfig.json`) | Provide versioned contracts, editor completion, and local or CI validation. | Use them to author against the installed host contract and catch invalid definitions before discovery or execution. They are not runtime workflows. |

A test is agentic; a task is deterministic; a trigger is event-driven; Trends turns event instrumentation into an observation span, metric budgets, and optional regression monitoring; and a sanitizer protects an exported copy.

## Prerequisites And Scope

Authoring and validating a workspace require the Ansight CLI, but they do not require a connected app. If the executable or local host is not ready, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`.

Running a test or task, verifying a trigger against live events, or capturing new evidence requires a development or QA build with an initialized Ansight SDK integration and the matching App ID. If the integration is missing, follow `https://www.ansight.ai/skills/ansight-install.md`. Do not require the SDK merely to edit definitions or extract a draft from an existing recorded session.

Workspace authoring does not authorize execution. Run a test or task, connect a trigger, rebuild Trends history, export a sanitized archive, or synchronize cloud history only when the user requested that state-changing operation or verification.

For workspace automation requests, prefer existing SDK and host capabilities. Verify their execution, transfer, and persistence behavior before concluding that app changes are required. An unverified capability is an uncertainty, not evidence that a new tool is needed.

Preserve the requested outcome: copying a file does not automatically require a transactional snapshot or custom artifact provider. If existing capabilities demonstrably cannot satisfy the request, explain the specific gap and propose app integration work separately, unless that work is already authorized.

## Inspect And Initialize With The CLI

Resolve the repository root and exact App ID, then inspect the existing `ansight/` tree before adding anything:

```sh
ansight app list --json
ansight app get <app-id> --json
```

Initialize missing workspace directories and canonical support files with:

```sh
ansight workspace init <repository-root> --app-id <app-id> --json
```

Registration links the App ID to the trusted codebase and enables automatic Trends evaluation when matching sessions finalize. Use `--no-register` only when the user wants scaffolding without that link. Initialization is idempotent and preserves customized files; do not use `--force` unless replacing support files is explicitly intended.

When a workspace already exists but its app registration must be added or repaired, use:

```sh
ansight app register <app-id> --codebase <repository-root> --json
```

## Scaffold Before Editing

Use the CLI generators when they exist so collision checks, canonical declarations, and current defaults come from the installed host:

```sh
ansight workspace add test <repository-root> <id> --app-id <app-id> --json
ansight workspace add task <repository-root> <id> --app-id <app-id> --json
ansight workspace add trigger <repository-root> <id> --app-id <app-id> --json
ansight workspace add sanitizer <repository-root> <id> --json
```

Then edit the generated definition. Existing files fail safely unless `--force` is supplied; do not replace one silently. There is no `workspace add trends` command, so create strict JSON files from the current [Trends contract](https://www.ansight.ai/docs/workspace/trends).

Derive stable IDs from paths by removing the extension and replacing directory separators with dots. Preserve local naming conventions. Use contract version `1`, strict portable JSON, and the canonical declarations produced by the installed host. Do not invent runtime APIs or schema fields.

## Tests: Agentic Journeys

Read the current [Workspace Tests](https://www.ansight.ai/docs/workspace/tests) contract before authoring. Keep actions and journey context in `prompt`; keep observable success criteria in `validation`. Require the exact `appId`. Put only secret aliases in `requiredSecrets`, never secret values. Trends evaluation is session-driven and independent of workspace test outcomes.

List and validate before execution:

```sh
ansight test list <repository-root> --json
ansight test validate <repository-root> --json
```

Run only when requested. Add `--trace` when the result needs the full model context, tool payloads, and exportable execution graph rather than lightweight audit metadata:

```sh
ansight test run <repository-root> <test-id> --trace --json
ansight test run-all <repository-root> --trace --json
```

Agentic `test run`, `test run-all`, and the compatibility `test run-inline`
command accept `--reasoning fast|balanced|deep`. Omitting it selects **Fast**, the
normal default for responsive execution. Balanced and Deep express progressively
greater emphasis on reasoning depth; actual model and provider budget come from
the server configuration. Every mode must satisfy the same requested steps and
verification. Preserve the user's choice; do not automatically raise the mode
after a failure. For a requested Balanced run, for example:

```sh
ansight test run <repository-root> <test-id> --reasoning balanced --json
```

This **Reasoning mode** is shared with app execution, replay, App Graph agent
runs, and AI task extraction in Session Replay. The server resolves the model
and provider reasoning effort from the client's configuration and selects the
credential handoff. No `--execution` flag is needed. Leave `--model-transport` at
its default `auto` unless a transport override is requested for diagnostics.
The hidden legacy `--model` override is for diagnostics and cannot be combined
with explicit `--reasoning`. Reasoning is a run option, not a test-schema field.

Test launches show simulator/emulator windows by default. When a local or CI
run should be windowless, add `--headless` to `test run` or `test run-all`; the
flag applies to all selected targets and tool-requested device starts. It is a
CLI option, not a test-schema field. `--json` and `--silent` do not imply it.
iOS skips opening Simulator.app; newly started Android emulators use
`-no-window`. Existing windows, reused sessions, and physical devices are left
alone.

Use `ansight test inspect <run-id> --json` for persisted results and `ansight test export <run-id> <output.zip> --app-id <app-id>` when a detailed trace and its portable session archives must be retained or shared. Treat traces as potentially sensitive.

## Tasks: Deterministic Reuse

Read the current [Workspace Tasks](https://www.ansight.ai/docs/workspace/tasks) and [Task API](https://www.ansight.ai/docs/workspace/task-api-reference) before authoring. A task descriptor must remain statically extractable, its input schema must be rooted at an object, tool calls must be awaited serially, and at least one stable named `check` assertion must establish success. A normal return without assertions is `Inconclusive`.

### Compose Existing Tasks

Before duplicating a stable workflow inside another task, inspect the workspace
catalog with `ansight.tasks.list({ query, feature, maxResults })`. Use the exact
discovered `taskId`, and compose a task only when the candidate's complete
behavior, input schema, and postcondition match the dependency. Do not select a
task merely because its title or a fuzzy match looks plausible.

```ts
type OpenGuideOutput = { guideVisible: boolean };

const catalog = await ansight.tasks.list({
query: "open area 3D guide",
feature: "map",
maxResults: 10
});
const child = catalog.tasks.find(candidate => candidate.taskId === "map.open-guide");
if (!child) throw new Error("The guide task is unavailable.");

const result = await ansight.tasks.run<OpenGuideOutput>({
taskId: child.taskId,
input: { area: "Secret Garden" }
});
expect(result.output?.guideVisible, { id: "guide-opened" }).toBe(true);
```

`ansight.tasks.list` and `ansight.tasks.run` need no `hostTools` declaration and
must be awaited serially like other task APIs. Both remain pinned to the
caller's exact repository, App ID, and live session; a child cannot select a
different repository, app, session, or device. Discovery uses the same task
metadata, input-schema, synonym, and conservative typo matching as external
task discovery. `maxResults` defaults to 10 and is capped at 20.

`run` resolves only when the child status is `Passed`. Any other status rejects
the call and fails the parent unless the parent deliberately handles the error;
catch an error only when that failure is an explicitly supported branch. Each
child keeps its own run ID, assertions, timeout, action budget, tool-call audit,
and persisted result. Each discovery or child execution costs one parent action,
but child actions consume only the child's budget. The parent's remaining
deadline caps the complete child call. Child assertions are not merged into the
parent, so the parent must still make its own stable named assertion.

The host rejects direct self-calls and recursive call cycles and permits at most
eight task execution levels in one call chain. Use a shared TypeScript helper
instead of task composition when only pure in-process logic is being reused.

### Ground UI Selectors In Recorded Evidence

For a task derived from a session, every selector must come from the UI evidence
captured inside the selected extraction period. Build a selector inventory from
the visual-tree snapshots and, when text is visible but absent from those trees,
retained screenshot OCR. Do not infer a selector from the task description or
from implementation terminology.

Apply these rules to `nodeId`, `automationId`, `text`, `role`, `type`,
`ancestorAutomationId`, and `action` fields used by `ansight.ui` or
`ansight.keyboard` calls:

- Every literal selector value must match a visible captured UI node. All fields
in a compound selector must match the same observed node.
- OCR can establish a `text` value only. It is not evidence for an automation
ID, node ID, role, type, ancestor automation ID, or supported action.
- Logs, telemetry, source code, framework navigation state, handoff text, task
descriptions, and inferred component names are context, not selector
evidence. A page, sheet, or view-model class name is not a `type` selector
unless a captured UI node reports that exact type.
- Prefer an observed automation ID. Otherwise use exact visible text, adding an
observed role or ancestor only when needed to disambiguate it.
- Keep evidence-derived selectors as inline string literals so they can be
checked statically. Do not hide them behind variables, input values, spreads,
computed keys, or helper-returned objects during extraction.
- When no stable observed selector exists, leave a `REVIEW:` diagnostic or omit
the unsupported step. Never fabricate a plausible selector or silently replace
it with a coordinate tap.

When the extraction surface offers **Require recorded selectors**, leave it
enabled. Treat its selector-call scan as an additional validation pass: it must
reject an unobserved literal or a dynamically assembled selector that cannot be
proven against the selected period. If that validation is unavailable, enforce
the same invariant manually from `session trees` and retained screenshots. Do
not claim that an extracted task is grounded merely because it compiles.

Discover the exact path-derived task ID and run it only when its whole semantic behavior matches the request:

```sh
ansight task list --app-id <app-id> --repository <repository-root> --json
ansight task run <task-id> --app-id <app-id> --repository <repository-root> --session-id <session-id> --json
```

Treat `Passed` plus its named assertions as completion evidence. Do not replay the same multi-step mutation manually after a terminal task result.

### Execute Through An Existing Interactive Connection

For repeated live actions and task runs, keep one process and resident-host pipe
open instead of spawning a CLI per step:

```sh
ansight app interact --session <session-id> --repository <repository-root> --jsonl
```

Retain the process handle, read its automatic `ready.ui` observation, and send JSON
Lines on stdin:

```json
{"id":"catalog","command":"tasks"}
{"id":"run","command":"task","taskId":"search.find","input":{"query":"Kalymnos"}}
{"id":"sequence","command":"batch","commands":[{"id":"query","command":"type","target":{"automationId":"search-field"},"value":"Kalymnos"},{"id":"submit","command":"tap","target":{"automationId":"search-submit"}}]}
```

Choose IDs and inputs from the returned catalog; these are examples, not tasks
guaranteed to exist. The repository, app and session stay fixed. Task execution
uses the normal engine and returns its status, assertions and tool calls under
`task`; only `Passed` succeeds. Evidence is automatic, including after a failed
task. No capture flag or separate screenshot request is needed.
Each action also returns compact fresh `ui.nodes`; prefer semantic targets and
tree-based verification, opening screenshots for visual checks or missing semantics.
Targeted `type` focuses and replaces text by default (`replaceExisting:false`
appends); untargeted `type` appends. Use observed IDs, not the example IDs above.
Do not manually focus/type before a task that already owns those operations.
Inspect its source once if its full behavior is unclear from the catalog.

Batches contain 1–32 known commands, execute serially, and stop on first failure.
They return ordered `results` and `skippedIds`, preserving evidence per action,
plus top-level final-child `ui`, `screenshot`, and aggregate `timing`. Read child
statuses and final semantic state; inspect intermediate PNGs only when needed.
IDs must be unique within the batch, nested batches and `exit` are forbidden,
and each line is limited to 65536 characters. Do not batch flows that require
deciding targets from intermediate screenshots. A failed batch is not rolled
back; never blindly replay completed or timed-out mutations. Automatic screenshots
settle within a bounded window; `ui_unsettled` retains evidence and stops the batch.
`stable` or `unchanged` pixels are not proof of a task's semantic postcondition.

Task timeout defaults to 120 seconds (`--task-timeout-ms`, maximum 300000); other
commands default to 15 seconds (`--timeout-ms`, maximum 60000). Timeout or
disconnect may interrupt capture and leave execution uncertain. `exit` or stdin
EOF detaches without stopping the app/host. This direct bridge is not `app
execute`, an agentic test, or a new recording session. Use the live-operation
skill for tree-first navigation with screenshot fallback, and keep execution authorization scoped
to the requested task.

`task run` and `repo task run` also accept `--headless` for device starts
requested by permitted host tools. They still require a connected session;
the flag does not authorize or perform an initial app launch for the task.

### Extract A Task From Recorded Behavior

AI task extraction in Session Replay offers **Reasoning mode: Fast / Balanced /
Deep**, defaulting to Fast and using the same client configuration as agentic
runs. Preserve the user's selection. The CLI `task extract` command below
generates a deterministic draft from recorded events and does not use a model;
do not add `--reasoning` to it. Deterministic `task run` and `repo task run` also
have no reasoning mode.

Use extraction when an existing session contains the exact deterministic behavior to preserve. Inspect its time bounds, touches, and visual-tree targets first:

```sh
ansight session show <session-id> --json
ansight session touches <session-id> --json
ansight session trees <session-id> --json
ansight task extract <session-id> --start <timestamp-or-offset> --end <timestamp-or-offset> --workspace <repository-root> --title <title> --json
```

Keep the extraction period narrow enough that the selector inventory represents
the behavior being preserved. Inspect representative beginning, middle, and end
snapshots when the period has many trees or screenshots. Treat the generated
TypeScript as a draft. Review every `REVIEW:` comment, define the required
starting state, apply the recorded-evidence selector rules above, and replace the
generated UI-stability check with a meaningful product outcome assertion.
Manually author unsupported long presses or multi-touch gestures; a tap without
a stable selector remains unresolved. Type-check, rediscover, and run the task
against a connected development build before relying on it.

### Debug A Failed Task Before Repairing It

Preserve the failed task result and its evidence before editing or replaying.
Start with the first failed tool call rather than the final exception or a nearby
application log:

1. Map the failed tool name and occurrence number to the corresponding source
call, and record its complete selector and state constraints.
2. Use the tool-call timestamps to bracket the task run. Inspect UI evidence
after the preceding successful action and through the failed call.
3. Compare every visual-tree source available at those snapshots. Framework,
native, and accessibility trees can expose different nodes. If a node exists
only in the native tree, that proves the native node—not a missing framework
class or inferred component type.
4. Inspect retained screenshot OCR when visible text is missing from the trees.
Keep the distinction between OCR text and structured selector fields.
5. Search logs only to determine whether a failed selector came from
implementation terminology. A string appearing only in logs is affirmative
evidence that it was not grounded as a UI selector.
6. Compare the UI before and after the preceding action and propose replacements
only from nodes or OCR text that newly appeared or became relevant there.

Classify the result before changing the task:

| Evidence | Likely diagnosis | Repair direction |
| --- | --- | --- |
| Selector never appears in any tree or OCR result | Invented or stale selector | Replace it with an observed selector, or leave the step unresolved. |
| Selector appears only in logs, source, or framework names | Implementation string used as UI evidence | Remove it; use captured UI text or a captured automation ID. |
| Matching node exists, but not with the requested visibility, enabled state, role, ancestor, or action | State constraint or compound-selector mismatch | Correct only the constraint contradicted by the captured node. |
| Matching node appears after the preceding action but after the wait timeout | Timing or transition problem | Wait on the observed postcondition and use a bounded timeout supported by replay evidence. |
| Several nodes match | Ambiguous selector | Add an observed role, ancestor, or index only when the same evidence proves it. |
| UI is visible in a screenshot or native tree but absent from a framework tree | Evidence-layer coverage gap | Use an exact selector exposed by an available tree, or OCR-backed visible text; do not invent the missing framework node. |

In Session Replay task extraction, run the draft against a connected session and
use **Debug why this task failed** when it is offered. Its failed-call mapping,
selector-presence finding, and newly visible selector suggestions are evidence
leads; verify the proposed selector against the retained tree or OCR provenance
before accepting it. Outside that UI, use the `task run --json` result and the
session evidence commands above. Do not invent an `ansight task debug` command.

After repairing the first supported cause, restore a known starting state and
run the task again. Stop after a terminal result; do not blindly repeat a timed
out or partially completed mutation. A passing run must still contain the named
product-outcome assertion, not merely successful tool calls.

## Triggers: Event-Driven Evidence

Read the current [Workspace Triggers](https://www.ansight.ai/docs/workspace/triggers) and [Trigger API](https://www.ansight.ai/docs/workspace/trigger-api-reference) before authoring. Keep the descriptor statically extractable, select one exact normalized event kind, and use declarative ANDed conditions. A handler may return no action or one bounded app action; it must not call unrelated host tools.

Inspect without executing code, then connect only with authorization:

```sh
ansight repo automation inspect <app-id> <repository-root> --json
ansight repo automation connect <app-id> <repository-root> --json
ansight repo automation list --json
ansight repo automation runs <app-id> --json
ansight repo automation disconnect <app-id> --json
```

Connected triggers are trusted local code and persist with the linked workspace across resident-host restarts. External edits are not hot-reloaded; inspect again and reconnect after changing definitions. A missing run is not evidence of success.

## Trends: Deterministic Metrics And Regression Evidence

An Ansight Trends definition starts when one matching SDK event arrives and completes when its matching end event arrives. Its inline `span` gives a meaningful app operation—such as launch, login, search, synchronization, or loading one item—a stable identity and time boundary for its metrics.

Inspect SDK event labels in source or captured session evidence before defining a span; never invent them. Treat the labels as a versioned instrumentation contract. Match optional event type or telemetry channel only when needed to disambiguate identical labels.

A session can contain several completed instances of the same operation. Choose `firstCompleted`, `lastCompleted`, `exactlyOne`, or `all` deliberately for the intended analysis. When paired start and end events carry the same non-empty `details`, Ansight keeps that value as a group so repeated operations such as loading “Secret Garden” and “Seaside” form separate metric and regression series. Set `maximumDurationMs` high enough for a realistic slow run but low enough to prevent an unrelated later end event from closing an abandoned start.

A Trends definition selects telemetry inside each chosen span, calculates deterministic `metrics`, and applies each metric's `budget`. Keep behavioral assertions in test validation and numeric trend rules in Trends definitions.

An optional `regression` belongs on the metric it monitors. Use [Trends](https://www.ansight.ai/docs/workspace/trends) for reference, regression, confirmation, and comparable-series rules. Inspect stored results with:

```sh
ansight trends history --app-id <app-id> --json
```

Changing a regression policy does not rewrite prior decisions automatically. Preview with `ansight trends rebuild --app-id <app-id> --dry-run --json`; apply the rebuild only when the user asked to replace stored decisions under the current rules.

Validation proves definitions and references are coherent. Only a finalized registered session produces metrics and historical comparison decisions.

## Sanitizers: Privacy-Safe Exports

Read [Sanitizers](https://www.ansight.ai/docs/workspace/sanitizers) before implementing a privacy policy. Use the generated typed sanitizer, return an edited item to retain it or `null` to remove it, fail closed for screenshots that neither OCR nor visual-tree text can inspect, and make an explicit keep-or-remove decision for binary artifacts.

Type-check the sanitizer, create a separate archive through `ansight session sanitize` or `ansight session export --sanitizer`, and inspect representative logs, network metadata, screenshots, trees, annotations, analyses, text artifacts, and binary artifacts in the result before sharing it. Never describe an uninspected sanitized archive as safe.

## Validate The Complete Workspace

Run only the checks whose files and configurations exist:

```sh
ansight test validate <repository-root> --json
npx tsc -p ansight/tasks/tsconfig.json
npx tsc -p ansight/triggers/tsconfig.json
npx tsc -p ansight/sanitizers/tsconfig.json
```

Resolve every validation warning. The runtime strips TypeScript types but does not type-check modules before execution. Re-run discovery after external edits, and reconnect triggers after changing them. Treat the installed host as authoritative when checked-in schemas or declarations disagree with it.

## Report Results

Report the workspace root, App ID and registration state, component type, path-derived ID, scaffold or files changed, validation and discovery performed, and whether execution was requested. For tests, report the outcome and whether `--trace` was enabled. For tasks, report terminal status and named assertions. For triggers, report connection and run state. For Trends, distinguish validation from an actual runtime evaluation. For sanitizers, report the output archive and inspection performed without claiming that the original session was modified.

Referenced files: 1

ansight-use-remote-app-tools9.44 KB

View saved version →

---
name: ansight-use-remote-app-tools
description: Discover and call bundled or app-specific remote tools exposed by one connected Ansight session. Use for authoritative in-process framework or domain state and authorized remote operations; do not use merely to establish the host/session, implement new tools, or replace a visible UI workflow.
---

## OpenAI plugin integration

Use these bundled files for the canonical skill URLs referenced below; keep public URLs when writing documentation for the user’s app:

# Use Ansight Remote App Tools

Use the live app's authenticated tool catalog as the source of truth. Remote tools expose framework, platform, storage, diagnostic, or app-domain state from inside the connected process; they are not inferred APIs.

This skill requires one exact connected session. Use the Ansight Operate Live App skill when the host, device, app, or session must first be started or selected.

## Prerequisites And Routing

Remote-tool use requires:

- the Ansight SDK installed and initialized in the app's development or QA build;
- the relevant bundled or app-specific tool packages included by that build;
- runtime policy and local guards configured to expose the permitted maximum policy; and
- a live SDK session connected to the resident host.

If the SDK integration is missing, follow `https://www.ansight.ai/skills/ansight-install.md`. If the CLI or resident host is not ready, follow `https://www.ansight.ai/skills/ansight-cli-setup.md`. If the app is installed but not connected, follow the Ansight Operate Live App skill.

An empty or blocked catalog does not by itself prove that installation is missing. It may reflect build gating, omitted tool packages, current app state, pairing limits, or a runtime guard. Report the observed catalog and denial state before proposing an integration change; do not enable remote tools in a protected build merely to complete an inspection.

## Decide When A Remote Tool Is Appropriate

Prefer a remote tool when it can answer an in-process question more authoritatively than screenshots or logs, such as current navigation state, bindings, selected domain objects, database rows, sandbox files, preferences, registered reflection roots, or an app-generated diagnostic artifact.

Keep semantic UI interaction as the default when the requested behavior is a visible user flow. Do not bypass taps, typing, navigation, or observable postconditions with an opaque internal mutation merely because a write tool exists.

## Discover The Current Catalog

Search the catalog immediately before choosing a tool. Start with compact,
executable read-tool metadata using a few intent-bearing terms:

```sh
ansight app tools <session-id> \
--query "<focused terms>" \
--policy read \
--detail summary \
--json
```

Use `--feature <domain>` for a broad product capability, `--category <exact>`
or `--id-prefix <prefix>` for a known family, and `--max-results <1-50>` to
bound direct matches. Focused searches return executable tools by default. Use
`--include-unavailable` only when the task is to inspect denial or availability
state. If `isTruncated` is true or the matches remain ambiguous, refine the
search instead of fetching the full catalog.

After selecting one exact ID, fetch its current complete definition:

```sh
ansight app tools <session-id> \
--tool-id <exact-tool-id> \
--detail full \
--json
```

This second response is the authority for the selected tool's schemas,
policy, executability, denial, and prerequisite IDs. Do not use an unfiltered
full catalog as the normal discovery step.

Each entry can expose:

- exact tool ID, category, name, description, and keywords;
- `read`, `write`, or `critical` policy;
- whether it is currently executable;
- a `denial` object when app state, the local guard, or the paired-client maximum blocks it;
- argument and result schemas;
- prerequisite tool IDs;
- catalog revision and argument encoding.

Catalog availability is live state. Query it again after reconnecting, changing
app state, or receiving a stale-availability failure. Use `--if-revision
<revision>` only to avoid transferring an unchanged catalog; an unchanged
response is not a new inspection.

Never invent a tool ID, assume a bundled family is installed, or reuse a schema from another app version.

## Choose The Narrowest Tool

1. Start with a compact search for executable read tools.
2. Select one exact ID, fetch its full definition, and match the returned description and schemas to the question.
3. Follow every returned `prerequisiteToolIds` entry and copy exact returned identifiers into the dependent call.
4. Treat tool IDs, node IDs, automation IDs, database IDs, paths, tags, surface IDs, and reflection root IDs as separate namespaces unless a schema explicitly connects them.
5. Use a write tool only when the user requested the corresponding app mutation.
6. Use a critical tool only with explicit authorization for that exact effect and only when the catalog and runtime guard permit it.

Do not attempt to bypass a denial by changing local guards, calling a differently named tool, or using reflection as a substitute.

## Recognize Bundled Families Without Assuming Them

The catalog may contain:

- framework inspection such as `maui.*`, `flutter.*`, `react.*`, or `dom.*`;
- native visual-tree and screenshot tools such as `ui.*`;
- database or structured data tools;
- sandbox file tools;
- preferences or allow-listed secure-storage tools;
- registered-root reflection tools under `reflect.*`;
- artifact query and request tools;
- app-specific domain tools.

Use platform-specific inspection skills when a returned family has platform semantics that affect interpretation. Use a platform's `ansight-create-remote-tool-*` skill only when the user asks to implement a new tool; creation is outside this skill.

## Call One Exact Tool

Prefer an arguments file for nontrivial or nested schemas:

```sh
ansight app call <session-id> <tool-id> --arguments-file <arguments.json> --json
```

For a small object, inline arguments are acceptable:

```sh
ansight app call <session-id> <tool-id> --arguments '<json-object>' --json
```

Validate the object against the returned argument schema. Do not add speculative fields, translate identifiers across namespaces, or reinterpret omitted required values.

For a state-changing call or visual diagnostic action, request post-call evidence when it is useful:

```sh
ansight app call <session-id> <tool-id> \
--arguments-file <arguments.json> \
--after-tree \
--after-screenshot \
--after-delay-ms <0-2000> \
--json
```

Post-call evidence supplements the tool result. It does not establish success unless it proves the requested postcondition.

## Batch Only Already-Known Calls

Use `app batch` for up to 32 ordered calls only when their exact IDs, schemas, arguments, and dependencies are already known and no intermediate reasoning is required:

```sh
ansight app batch <session-id> --calls-file <calls.json> --json
```

Each item can contain `toolId`, `arguments`, `after`, and `callId`. Keep the default stop-on-failure behavior when later calls depend on earlier ones. Use `--continue-on-error` only for independent evidence reads whose remaining results are still useful after one failure.

Do not batch exploratory mutations, critical operations, or calls that require inspecting an intermediate result before choosing the next arguments.

## Mutation And Verification

For an authorized write or critical operation:

1. Capture a read-only baseline from the same authoritative surface.
2. State the exact target and expected effect.
3. Execute the smallest call once.
4. Re-run the baseline read or another independent verification.
5. Verify the visible UI as well when the effect is user-facing.
6. Report rollback or cleanup when the operation created temporary state.

For files, preferences, secure storage, databases, and reflection, remain inside the roots, keys, schemas, and members explicitly published by the app. Do not expose secrets or broaden access to complete the task.

## Handle Failure As Evidence

- A denial means the tool is unavailable under the current app state or guard. Report its code and reason.
- A schema error means the call was malformed; correct it only from the returned schema.
- A prerequisite failure means the dependent call must not proceed.
- A disconnected session requires fresh session and catalog discovery before retrying.
- A successful tool response proves only the operation described by its result schema; verify broader product outcomes separately.

## Report The Tool Trail

Report the selected session, catalog revision, exact tool IDs and policies, prerequisites followed, arguments at a safe summary level, material result fields, mutations performed, before-and-after evidence, verification outcome, denials, and any fallback outside the remote-tool surface.

Referenced files: 1

Technical details

First seen: Sep 30, 2026 · 22:02 UTC
Last seen: Oct 1, 2026 · 12:00 UTC
Collection status: Collected

plugins_6aa24265df788191a25e7db0cdeca894

Download listing JSON