Agent skill

Marionette Debug

by bladeofgod in bladeofgod/flutter-ai-harness

适用：通过仓库 Marionette MCP 连接运行中的 Flutter App，执行临时诊断或由 app-operator 严格按 Spec 回归。不适用：构建/安装 App、操作原生系统 UI、在 Profile/Release 中启用 Binding 或修改代码。触发词：App 卡住、黑屏、路由错误、检查 UI、Marionette、VM Service、App…

MITAuto-check passedMobile

Install Marionette Debug

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/marionette-debug .claude/skills/marionette-debug && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .claude/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/marionette-debug .agents/skills/marionette-debug && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .agents/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/marionette-debug .cursor/skills/marionette-debug && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .cursor/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/bladeofgod/flutter-ai-harness.git --path .claude/skills/marionette-debug

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/marionette-debug .gemini/skills/marionette-debug && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .gemini/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/marionette-debug .github/skills/marionette-debug && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .github/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install bladeofgod/flutter-ai-harness marionette-debug --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/bladeofgod/flutter-ai-harness.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/marionette-debug .opencode/skills/marionette-debug && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "marionette-debug" agent skill from https://github.com/bladeofgod/flutter-ai-harness/tree/main/.claude/skills/marionette-debug into .opencode/skills/marionette-debug/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "marionette-debug", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: marionette-debug
GitHub stars: 116
Token cost: ~322 tokens
SKILL.md length: 102 words
Files: 1
Skills in repo: 11
Repo updated: Sep 7, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Works in 4 steps: 从调用方获取 flutter run 输出中的 ws://.../ws VM… → 使用 marionette MCP 的 connect 连接并确认目标… → 优先使用稳定 Key、Semantics 或稳定文本定位元素，不使用坐标。 → …
Mobile work in your project
SKILL.md covers 公共流程, 诊断模式 and Operator 模式
Calls make and flutter

What it does

Marionette Debug is an agent skill from bladeofgod/flutter-ai-harness. 适用：通过仓库 Marionette MCP 连接运行中的 Flutter App，执行临时诊断或由 app-operator 严格按 Spec 回归。不适用：构建/安装 App、操作原生系统 UI、在 Profile/Release 中启用 Binding 或修改代码。触发词：App 卡住、黑屏、路由错误、检查 UI、Marionette、VM Service、App Operator、Spec 回归。

Its SKILL.md is about 320 tokens, which your agent loads only when the skill is triggered. It is a single SKILL.md file with no bundled scripts.

It sits in Mobile. It works with Flutter and Model Context Protocol. The repository describes itself as: An AI-native engineering harness for production Flutter and hybrid mobile app repositories. The licence is MIT.

When your agent uses it

Mobile work in your project

Example prompts

“/marionette-debug”

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

从调用方获取 flutter run 输出中的 ws://.../ws VM Service URI。
使用 marionette MCP 的 connect 连接并确认目标 Flutter Isolate/Binding。
优先使用稳定 Key、Semantics 或稳定文本定位元素，不使用坐标。
任务结束或失败后使用 disconnect 断开连接。

What it can do on your machine

Read from SKILL.md and the folder at commit 9f1a1ca. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Shell commands in SKILL.md call:
- make
- flutter
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Marionette Debug loads about 322 tokens when it runs. Until then it costs about 55 tokens; SKILL.md has 102 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~55
When it runs · the whole SKILL.md, loaded when a task matches: ~322

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from bladeofgod/flutter-ai-harness at commit 9f1a1ca, republished under its MIT licence (© bladeofgod). 102 words, ~322 tokens.

Download SKILL.mdSave it as .claude/skills/marionette-debug/SKILL.md (or your agent's skills folder).

name: marionette-debug
description: 适用：通过仓库 Marionette MCP 连接运行中的 Flutter App，执行临时诊断或由 app-operator 严格按 Spec 回归。不适用：构建/安装 App、操作原生系统 UI、在 Profile/Release 中启用 Binding 或修改代码。触发词：App 卡住、黑屏、路由错误、检查 UI、Marionette、VM Service、App Operator、Spec 回归。
paths: app/apps/**/lib/main.dart, .mcp.json, .claude/agents/app-operator.md, Makefile

Marionette 运行时

仓库已提供 .mcp.json 和 Demo App Binding。首次 Clone 仍需运行 make marionette-install 并批准项目级 MCP Server；不可用时准确报告缺失前置，并改用普通 Flutter 日志/Debugger。

公共流程

从调用方获取 flutter run 输出中的 ws://.../ws VM Service URI。
使用 marionette MCP 的 connect 连接并确认目标 Flutter Isolate/Binding。
优先使用稳定 Key、Semantics 或稳定文本定位元素，不使用坐标。
任务结束或失败后使用 disconnect 断开连接。

Marionette 只操作 Flutter Widget Tree，不操作系统权限弹窗等原生 UI。不得记录 VM Service URI、凭据、设备标识、主机名、用户名或真实用户数据；日志和截图入库前必须脱敏。不得 hot reload 或修改代码。

诊断模式

没有行为 Spec、目标是临时定位问题时：

获取当前交互元素，并在支持时截图。
拉取最近日志，与可见状态对照。
只执行复现问题所需的最少交互，不探索无关页面或修改无关 App 数据。
汇报可见状态、日志、复现位置和下一步诊断，不仅凭截图宣称根因。

诊断模式不得自行生成回归通过结论；需要回归验证时交给 app-operator。

Operator 模式

由 app-operator 调用且已有 ready Spec、passed Audit 和明确平台时：

行为契约、操作顺序和 Assertion 以 Spec 为唯一依据。
只执行 Spec 的 Step、Assertion 和 Teardown，不做探索动作。
首次失败时采集脱敏截图和最近日志；条件允许时仍执行 Teardown。
按 ui-behavior-spec 写入该平台的结构化运行报告，不把临时诊断结果冒充 Spec 通过。

Files

Just SKILL.md in .claude/skills/marionette-debug of bladeofgod/flutter-ai-harness.

Open the folder on GitHubat commit 9f1a1ca

Compare with similar skills

Marionette Debug next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Marionette Debug compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Marionette Debug this skillbladeofgod/flutter-ai-harness	116	—	~322	Automated safety check: Pass	MIT	1 mo ago
Marionette Flutter Drive Appleancodepl/marionette_mcp	473	—	~11k	Automated safety check: Pass	Apache-2.0	3 days ago
Aaalice Dev SessionsAaalice233/Aaalice_NAI_Launcher	187	—	~902	Automated safety check: Pass	MIT	3 days ago
macOS Desktop QAsesori-ai/sesori_apps_monorepo	126	—	~2.3k	Automated safety check: Pass	Custom licence	yesterday
AI App Bridge UsemobileAiDev/ai-app-bridge	227	—	~1.4k	Automated safety check: Pass	Apache-2.0	yesterday
Aaalice Hot ReloadAaalice233/Aaalice_NAI_Launcher	187	—	~531	Automated safety check: Pass	MIT	3 days ago

Similar skills

Marionette Flutter Drive App
leancodepl/marionette_mcp
Set up and drive a running Flutter app (debug or profile) with Marionette — an AI agent's hands and eyes for the app.
473 GitHub stars~11k tokensUpdated 3 days ago
MobileAuto-check passed
Aaalice Dev Sessions
Aaalice233/Aaalice_NAI_Launcher
管理 Aaalice NAI Launcher 项目专用的 Windows 与 Android Flutter 开发会话。用户提到 PC热重载、安卓热重载、启动/关闭/重建独立命令行窗口、模拟器启动异常或检查双端会话时使用。
187 GitHub stars~902 tokensUpdated 3 days ago
MobileAuto-check passed
macOS Desktop QA
sesori-ai/sesori_apps_monorepo
Build, launch, inspect, and exercise the Sesori macOS desktop app as a real QA target.
126 GitHub stars~2.3k tokensUpdated yesterday
MobileAuto-check passed
AI App Bridge Use
mobileAiDev/ai-app-bridge
使用 AI App Bridge 观察、操作和验证 Android、iOS、Flutter、WebView 或 Web App；适用于真实交互、流程自动化和设备诊断。
227 GitHub stars~1.4k tokensUpdated yesterday
MobileAuto-check passed
Aaalice Hot Reload
Aaalice233/Aaalice_NAI_Launcher
为 Aaalice NAI Launcher 修改代码后选择并执行 Windows/Android 的 r 热重载、R 热重启或完整重建，并验证结果。已有开发会话运行时，代码修改完成后自动使用；用户要求热重载、热重启、修改后刷新或查看 Flutter 日志时也使用。
187 GitHub stars~531 tokensUpdated 3 days ago
MobileAuto-check passed
Aaalice Runtime Verify
Aaalice233/Aaalice_NAI_Launcher
用户要求自动化运行验收、界面操作、截图检查或双端 UI 测试时，自动启动或复用 Aaalice NAI Launcher 热重载会话，通过项目级 Dart/Flutter MCP 验证应用；Android 系统界面按需使用 ADB。
187 GitHub stars~963 tokensUpdated 3 days ago
MobileAuto-check passed

More from bladeofgod/flutter-ai-harness

All 11 skills in this repo

Getx Patterns
bladeofgod/flutter-ai-harness
适用：代码使用 GetxController、GetxService、Rx、Obx、GetBuilder、Get.find、Bindings 或 Worker。不适用：GetX 路由、Dialog、Snackbar，或 Controller 内隐式查找 API。触发词：GetX、Obx、.obs、Rx、Get.find、GetxService、Worker、Binding。
116 GitHub stars~462 tokensUpdated 1 mo ago
Auto-check passed
UI Behavior Spec
bladeofgod/flutter-ai-harness
适用：根据已批准任务、产品规则、原型或 Figma 输入生成、审计或执行 Version 1 UI 行为 Spec。不适用：替代产品决策、实现 UI、操作系统原生界面或探索未定义流程。触发词：UI Spec、行为契约、plan-spec、spec-writer、spec-auditor、app-operator、Marionette 验收。
116 GitHub stars~1.4k tokensUpdated 1 mo ago
Auto-check passed
Flutter Debug Runtime
bladeofgod/flutter-ai-harness
适用：在 App Operator 或 Marionette 验证前，为 Android/iOS 构建、安装并启动 Flutter Debug App，获取 VM Service URI。不适用：Release 构建、签名配置、系统权限自动化、账号登录或测试数据准备。触发词：flutter run、Debug App、设备安装、VM Service URI、App Operator 前置环境。
116 GitHub stars~274 tokensUpdated 1 mo ago
Auto-check passed
Dart Coding Standards
bladeofgod/flutter-ai-harness
适用：编写或审查 Dart/Flutter 生产代码，尤其是 Controller、Service、Stream、异步任务和依赖注入。不适用：Kotlin、Swift 或生成代码规范。触发词：Dart、Controller、Service、StreamSubscription、unawaited、dynamic、DI、重构。
116 GitHub stars~228 tokensUpdated 1 mo ago
Auto-check passed
Figma To Flutter
bladeofgod/flutter-ai-harness
适用：读取 Figma 或根据节点实现 Flutter UI，包括 Token 反查、Auto Layout、组件 Variant、Asset 和视觉验证。不适用：替代产品决策，或从像素推断设计稿不可见的数据行为。触发词：Figma URL、node-id、design-to-code、视觉还原、Auto Layout、design token。
116 GitHub stars~270 tokensUpdated 1 mo ago
Auto-check passed
Go Router
bladeofgod/flutter-ai-harness
适用：新增 Route、Redirect、ShellRoute/StatefulShellRoute、DeepLink、路由参数、Observer 或 Route 级 Controller 装配。不适用：GetX 导航或没有明确兼容边界的任意 Navigator Stack。触发词：GoRouter、GoRoute、redirect、deep link、shell…
116 GitHub stars~295 tokensUpdated 1 mo ago
Auto-check passed

Works with

Questions about Marionette Debug

What does Marionette Debug do?

When should I use Marionette Debug?

Marionette Debug fits situations like: mobile work in your project.

How do I install Marionette Debug in Claude Code?

Run `npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a claude-code`. Or copy the skill folder (.claude/skills/marionette-debug in bladeofgod/flutter-ai-harness) into .claude/skills/marionette-debug in your project. Claude Code loads it when a task matches its description.

How do I install Marionette Debug in Codex?

Run `npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a codex`. Or copy the skill folder (.claude/skills/marionette-debug in bladeofgod/flutter-ai-harness) into .agents/skills/marionette-debug in your project. Codex loads it when a task matches its description.

Can I use Marionette Debug in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add bladeofgod/flutter-ai-harness --skill marionette-debug -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/marionette-debug, .gemini/skills/marionette-debug, .github/skills/marionette-debug and .opencode/skills/marionette-debug in your project.

What does Marionette Debug need to run?

Going by SKILL.md and its folder, Marionette Debug needs the command-line tools its instructions call (make and flutter).

Does Marionette Debug access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Marionette Debug safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Marionette Debug use?

Marionette Debug is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Marionette Debug use?

About 322 tokens (SKILL.md is roughly 1.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Marionette Debug?

Skills that share tags, products or a category with Marionette Debug: Marionette Flutter Drive App (leancodepl/marionette_mcp, 473 stars), Aaalice Dev Sessions (Aaalice233/Aaalice_NAI_Launcher, 187 stars), macOS Desktop QA (sesori-ai/sesori_apps_monorepo, 126 stars) and AI App Bridge Use (mobileAiDev/ai-app-bridge, 227 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Marionette Debug?

bladeofgod (a GitHub user) maintains it in bladeofgod/flutter-ai-harness, which has 116 GitHub stars. The repository holds 11 skills in this directory. The repository was last updated on September 7, 2026.

Source: bladeofgod/flutter-ai-harness on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Marionette Debug

Facts

At a glance

What it does

When your agent uses it

Example prompts

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Marionette 运行时

公共流程

诊断模式

Operator 模式

Files

Compare with similar skills

Similar skills

More from bladeofgod/flutter-ai-harness

Related

Questions about Marionette Debug