MMSkills: Towards Multimodal Skills for General Visual Agents

Paper: arXiv:2605.13527 Code: DeepExperience/MMSkills Code reference: main @ adf6bc36 (2026-05-18)

1. Motivation (研究动机)

现有 agent skill 通常把可复用经验写成 text prompt、code snippet、execution graph 或 learned routine。这个假设在纯语言或结构化 API 场景里可行，但对 visual agent 不够：GUI / game 任务的关键不是只知道“下一步做什么”，还要知道当前屏幕是否已经进入可执行状态、哪些视觉证据说明操作成功/失败、什么时候应该停止。论文给出的典型失败是：desktop agent 知道要操作某个 dialog，却没有识别 dialog 还没 ready；game agent 知道目标，却需要视觉 cue 判断是“仍在推进”还是“已经完成”。

MMSkills 要解决的问题是：把 agent 的可复用技能从 text-only procedural knowledge 扩展为 multimodal procedural knowledge。也就是说，一个 skill 不能只是“步骤说明 + 几张截图”，而要绑定三类信息：可复用 textual procedure、状态化的 when-to-use / when-not-to-use / verification cue，以及能在 runtime 帮助识别这些状态的 multi-view keyframes。

这个问题值得研究，因为 visual agent 的可复用经验如果只能靠长 demonstration replay，会太长、太 instance-specific，也很难迁移；如果压缩成纯文本，又会 verbose but underspecified。MMSkills 的目标是在两者之间建立一个紧凑表示：保留视觉决策所需的证据，但不把完整轨迹塞进上下文，从而让 frontier VLM 和较小 VLM 都能借助外部 multimodal skill library 做更稳的 GUI / game 决策。

Figure 1 解读：这张图用 LibreOffice Calc chart creation 说明 text-only skill 的核心缺口。纯文本说明能告诉 agent 创建 chart 的大致步骤，但不一定能识别当前是否在 Sheet2、dialog 是否打开、chart title 是否已设置；MMSkills 把状态卡和 full/focus/before/after views 绑定到 procedure 上，使 branch agent 能先判断 skill 是否适用，再给 main agent 结构化 guidance。

2. Idea (核心思想)

核心 insight 是：对 general visual agent 来说，skill 的最小可复用单元不是 action list，而是“procedure + decision-relevant visual state”。MMSkills 因此把每个 skill 表示为 state-conditioned package，并在 inference 时用 temporary branch 消化视觉证据，再把压缩后的 planner guidance 交回主轨迹。

关键创新有两点：第一，用 runtime state cards 明确记录 when-to-use、when-not-to-use、visible cues、verification cues 和 available views；第二，用 branch loading 代替 direct loading，让 main agent 不直接吞下大量 reference screenshots，而是只接收 applicable / subgoal / plan / do_not_do / verify 这类结构化决策支持。

与 text-only skills（例如只在 prompt 里加入 reusable procedure）相比，MMSkills 的差异不是“多了图片”，而是图片被绑定到状态判别和完成验证上；与 demonstration replay 相比，它不是回放整条轨迹，而是把公共非测试轨迹压缩为可检索、可审计、可按需加载的 state-conditioned skill package。

3. Method (方法)

3.1 Overall framework

论文把系统拆成三个模块：Multimodal Skill Package、Skill Generator from Public Trajectories、Branch-loaded Multimodal Skills Agent。整体 runtime 可以写成：main agent 在当前视觉观察 $O_t$ 和历史 $H_t$ 下，要么直接行动，要么调用一个候选 skill branch： $\text{direct}:A_t={\pi }_{\text{main}}(O_t,H_t,C_I),$ $\text{branch}:G_t=\mathrm{Branch}(O_t,H_t,M_t),A_t={\pi }_{\text{main}}(O_t,H_t,C_I,G_t).$ Branch 的输出是结构化 guidance： $G_t=({\mathrm{applicable}}_t,{\mathrm{subgoal}}_t,{\mathrm{plan}}_t,{do\_not\_do}_t,{\mathrm{verify}}_t).$ 这里的关键约束是：$G_t$ 只是 planning signal，最终 action 仍必须由 main agent 根据 live observation grounded 到当前屏幕。这样可以利用 reference evidence，又避免把 reference screenshot 当作坐标模板。

Figure 2 解读：左侧是 skill package 的文件结构：SKILL.md 存 textual procedure，state_cards.json 存状态条件和可加载视图，Images/ 存 full-frame、focus-crop、before/after 等 keyframes。中间是从 public non-test trajectories 生成 skill library 的五阶段 pipeline。右侧是 inference-time branch loading：main agent 看到 available skills，但只有在需要时才打开 temporary branch；branch 先做 gated view selection，再做 planner guidance，最后返回 compact JSON 给 main agent。

3.2 Multimodal Skill Package

每个 MMSkill 被定义为： $M=(D,P,S,K),$ 其中 $D$ 是 compact descriptor，$P$ 是 reusable textual procedure，$S=\{S_j{\}}_{j=1}^m$ 是 runtime state cards，$K=\{K_j{\}}_{j=1}^m$ 是与 state cards 对齐的 keyframe bundles。一个 pair $(S_j,K_j)$ 对应一个 decision-relevant procedural state：procedure 告诉 agent 工作流，state card 告诉它何时适用/不适用，keyframes 让这个状态在 runtime 可识别。

Runtime state card 不是普通 image caption，而是 agent-facing state node： $S_j=({when\_to\_use}_j,{when\_not\_to\_use}_j,{visible\_cues}_j,{verification\_cue}_j,V_j),V_j={available\_views}_j.$ 其中 when_to_use / when_not_to_use 负责适用性判断，visible_cues 指出要看哪些视觉证据，verification_cue 定义进度或完成检查，available_views 说明 branch 可以加载哪些 reference views。

Keyframe bundle 的视图集合为： $V=\{full\_frame,focus\_crop,\mathrm{before},\mathrm{after}\},$ $K_j=\{K_{jv}:v\in V_j,v\in V\}.$ full_frame 保留全局上下文，focus_crop 定位局部视觉 cue，before/after 表达转移和完成验证。text-only skill 是退化形式 $(D,P,\varnothing ,\varnothing )$；MMSkills 的增量是把 decision condition 和 visual evidence 一起纳入可复用单元。

3.3 Skill Generator from Public Trajectories

Generator 输入 public, non-evaluation trajectories： ${\tau }_i=(I_i,O_{i,1:T_i},A_{i,1:T_i}),$ 其中 $I_i$ 是任务指令，$O_{i,t}$ 是视觉观察，$A_{i,t}$ 是执行动作。给定 domain $d$ 的 trajectory pool $T_d$，meta-skill-guided Generator 写成： $G_F:T_d\mapsto M_d.$ 论文的 generation pipeline 是五阶段： $T_d\stackrel{\text{embed+cluster}}{\to }{C}_d\stackrel{\text{cluster plan}}{\to }{A}_d\stackrel{\text{merge}}{\to }{R}_d\stackrel{\text{text draft}}{\to }{\hat{M}}_d\stackrel{\text{image ground+audit}}{\to }{M}_d.$

• Phase 0 task embedding and clustering：把 task instructions 和 trajectory metadata embed 后聚类，得到语义集中的 workflow clusters。
• Phase 1 cluster-level skill planning：LLM agent 为每个 cluster 提出 atomic skills，明确 workflow boundary、completion condition、covered task ids。
• Phase 2 skill merging：去重、合并并泛化 cluster-level skill plans；拒绝过宽的 umbrella skills。
• Phase 3 text-first drafting：先不读图，选择 reference tasks，草拟 descriptor $D$、procedure $P$ 和 planned state cards。
• Phase 4 image grounding and audit：读取 selected keyframes，ground focus regions，构造 multi-view bundles，并用 meta-skill quality gates 审计最终 package。

对一个 merged skill $r\in R_d$，最终化过程为： ${\hat{M}}_r=(D_r,P_r,{\hat{S}}_r,{\hat{K}}_r)\stackrel{\text{ground+audit}}{\to }{M}_r=(D_r,P_r,S_r,K_r).$ 直觉上，这个设计不想保存原始 demonstration，而是只保存“诊断性状态”：哪些状态要识别，哪些视觉 cue 说明应该继续/跳过/验证完成。这样比 demonstration replay 更短，也比 text-only procedure 更可执行。

论文公式与 released code 实现差异：论文描述了完整 Phase 0–4 的 trajectory-to-skill Generator；main@adf6bc36 的公开 repo 主要释放 runtime layer、OSWorld integration、task-to-skill mappings、代表性 skill library 和 agent adapter。可核验代码覆盖 branch-loaded runtime、state-card / image loading 和 evaluation runner，但没有完整复现论文中所有 Generator 阶段的训练/生成 launcher。

3.4 Branch-loaded Multimodal Skills Agent

直接把 MMSkill 全量塞进 main context 会有两个问题：state cards + multi-view images 带来上下文压力；reference screenshots 可能把 agent 锚定到旧 UI，而不是 live environment。Branch loading 把“skill-environment grounding”移到临时 branch 中。

Stage 1: gated view selection. 当 main agent 请求 $M_t=(D_t,P_t,S_t,K_t)\in C_I$ 时，branch 先选择相关 state cards 和 view types： $(J_t,R_t)=\mathrm{SelectViews}(O_t,H_{t-1},P_t,S_t),V_t=\{K_{jv}:j\in J_t,v\in R_{t,j}\}.$ 如果 textual procedure 和 state cards 已足够，$R_{t,j}$ 可以为空；否则 branch 只加载必要的 full/focus/before/after views。

Stage 2: branch planning. Branch 再把 live state 与 selected evidence 对齐，输出： $G_t=\mathrm{PlanBranch}(O_t,H_{t-1},P_t,\{S_j:j\in J_t\},V_t).$ Main agent 不机械执行 $G_t$，而是把它当成下一步 grounded action 的 planner prior。

Figure 5 解读：Appendix prompt surface 展示了 main agent、Stage-1 selector、Stage-2 planner 的职责隔离。Main agent 可以选择 act / wait / done / load skill；Stage 1 只能返回要不要加载视觉 evidence 以及加载哪些 state views；Stage 2 不能执行 GUI action，只能返回结构化 planner JSON。这个隔离是 MMSkills 避免“reference image 直接污染主轨迹”的关键。

3.5 Runtime algorithm and source-grounded pseudocode

论文 Appendix D 的 Algorithm 1 可概括为：先按 instruction 做 candidate skill pre-recall；每一步观察当前 screenshot；main agent 决定直接 action 还是请求 skill；若请求 skill，就进入 Stage-1 view selection 和 Stage-2 planner branch；最后 main agent 根据 branch guidance 选择 grounded action。

Code reference: main @ adf6bc36 (2026-05-18) — pseudocode and mapping based on this commit

def resolve_candidate_skills(task, domain, resolver, top_k=6):
    """Based on mm_agents/task_skill_resolver.py."""
    mapped = resolver.lookup_domain_or_global_mapping(domain, task.id)
    ranked = resolver.select_top_skills(mapped, top_k=top_k)
    skill_names = []
    for entry in ranked:
        skill_dir = resolver.resolve_skill_directory_name(entry)
        if skill_dir is not None:
            skill_names.append(skill_dir)
    return skill_names

def load_mmskill_package(skill_loader, skill_name):
    """Based on mm_agents/skill_loader.py and _mm_skill_adapter_base.py."""
    text = skill_loader.load_skill_content(skill_name)          # SKILL.md / procedure
    bundles = skill_loader.load_state_bundles(skill_name, runtime=True)
    if bundles is None:
        cards = skill_loader.load_state_cards(skill_name, runtime=True)
    else:
        cards = None
    return {"procedure": text, "state_bundles": bundles, "state_cards": cards}

def select_state_views(llm, loader, skill_name, live_obs, history, procedure, state_bundles):
    """Reflects MMSkillAgent Stage-1 plus SkillLoader.load_selected_state_views."""
    request = llm.return_one_load_state_views_call(
        screenshot=live_obs,
        history=history,
        procedure=procedure,
        state_bundle_previews=state_bundles,
    )
    # request is JSON: visual_reference_needed, why_not_text_only, requests[{state_id, views, reason}]
    selected, missing = loader.load_selected_state_views(
        skill_name,
        request.get("requests", []),
        runtime=True,
    )
    if missing:
        raise ValueError("requested state_id/view_type cannot be resolved")
    return selected

def plan_branch(llm, live_obs, history, procedure, selected_state_views):
    """Reflects MMSkillAgent Stage-2 planner summary parser."""
    summary = llm.return_one_json_block(
        screenshot=live_obs,
        history=history,
        procedure=procedure,
        selected_state_views=selected_state_views,
        required_keys=[
            "skill_applicability", "subgoal", "plan", "do_not_do",
            "fallback_if_no_progress", "expected_state", "completion_scope",
        ],
    )
    assert summary["skill_applicability"] in {"effective", "ineffective", "uncertain"}
    return summary

def branch_loaded_agent_step(main_agent, branch_llm, loader, obs, history, candidate_skills):
    """Runtime form of Algorithm 1 and _MMSkillAdapterBase._run_skill_branch."""
    decision = main_agent.choose_action_or_load_skill(obs, history, candidate_skills)
    if decision.kind == "action":
        return decision.action
 
    skill = load_mmskill_package(loader, decision.skill_name)
    selected_views = []
    if main_agent.skill_mode == "multimodal":
        selected_views = select_state_views(
            branch_llm, loader, decision.skill_name, obs, history,
            skill["procedure"], skill["state_bundles"] or skill["state_cards"],
        )
    guidance = plan_branch(branch_llm, obs, history, skill["procedure"], selected_views)
    return main_agent.ground_action_from_live_screen(obs, history, guidance)

3.6 Code-to-paper mapping

Code reference: main @ adf6bc36 (2026-05-18)

Paper Concept	Source File	Key Class/Function
Branch-loaded multimodal runtime	mm_agents/mm_skill_agent.py, mm_agents/_mm_skill_adapter_base.py	MMSkillAgent, _build_branch_view_selection_*, _build_branch_planner_*, _run_skill_branch
Skill package parsing and state bundles	mm_agents/skill_loader.py	SkillLoader.load_skill_content, load_state_bundles, load_state_cards, load_selected_state_views, resolve_state_view_requests
Candidate skill pre-recall / task mapping	mm_agents/task_skill_resolver.py, task_skill_mappings/	TaskSkillResolver.resolve_task_skills, _select_top_skills, resolve_task_skill_names
Text-only ablation path	mm_agents/general_text_skill_agent.py	text-only skill branch / inline-context variants used for ablation
OSWorld evaluation runner	osworld_integration/run.py, osworld_integration/lib_run_single.py	--agent_type mm_skill, --skill_mode multimodal, run_single_example
Released skill library format	skills_library/*/*/	SKILL.md, runtime_state_cards.json, state_cards.json, Images/
Product-neutral adapter	agent_integrations/mmskills-agent-adapter/	search / download / inspect scripts for external agent products

4. Experimental Setup (实验设置)

4.1 Datasets / benchmarks and scale

• OSWorld：360 GUI test cases；应用分布包括 Chrome、GIMP、LibreOffice Calc / Impress / Writer、Multi-app、OS、Thunderbird、VLC、VS Code。
• macOSWorld：143 test cases；File management 29、Media 12、Productivity 35、System/interface 29、System apps 38。
• VAB-Minecraft：来自 VisualAgentBench 的 Minecraft visual-agent benchmark；evaluation 使用 official test set，skill source 使用 official training set，二者 disjoint。
• Super Mario Bros / LMGame-Bench：从多个 source cases 生成技能，最终 evaluation 使用 4 个 held-out cases。

Skill source 方面，GUI skills 来自 OpenCUA 非测试轨迹：Ubuntu 共 4,205 trajectories（Chrome 718、Impress 605、VS Code 605、OS 497、GIMP 492、Writer 490、Thunderbird 300、Calc 298、VLC 200），macOS 共 3,157 trajectories（Productivity 1,424、System apps 768、File management 341、Media 315、System/interface 309）。论文报告的 skill package 规模为：OSWorld 247 skills / 879 state cards / 1,898 views；macOSWorld 248 skills / 522 state cards / 1,097 views；VAB-Minecraft 24 skills；Super Mario Bros 10 skills。

4.2 Baselines and model families

比较条件包括：No skill、Text-only skill、MMSkills。Ablation 还包括 direct loading、branch loading without view selection、without state cards、without images 等变体。模型包括 Gemini 3.1 Pro、Gemini 3 Flash、Qwen3-VL-235B-A22B-Thinking、GLM-5V-Turbo、Kimi-K2.6、Qwen3-VL-8B-Instruct。

4.3 Metrics

• OSWorld / macOSWorld：application-level 或 domain-level success rate，以及 overall success rate。
• VAB-Minecraft：success rate 和 average score。
• Super Mario Bros：total performance 和 total reward。
• Skill usage dynamics：Invoked (%)、Calls/case、Steps、Step $\Delta$、selected views 分布（Full / Focus / Before / After）。
• Behavior shift：action primitive distribution、每任务低层 action 数、exact repeated actions、same-mode repeats、20-step budget normalized longest same-mode run。

4.4 Runtime / evaluation config

论文说明所有 agent 都从 visual observations 规划：GUI 用 desktop screenshots，game 用 game screenshots；OSWorld 和 macOSWorld 主要在 AWS 上用 official benchmark images / task definitions 跑 full evaluations；GUI benchmark 的最大交互预算是 20 steps。Released code 中 osworld_integration/run.py 对应配置包括：--screen_width=1920、--screen_height=1080、--max_steps=20、--max_trajectory_length=3、--agent_type 支持 general / general_text_skill / mm_skill，--skill_mode 支持 text_only / multimodal，--task_skill_top_k=6，--skills_library_dir=skills_library。论文没有训练一个新 neural model，因此没有 LR / batch size / GPU training schedule；这里的“config”主要是 inference-time evaluation and skill-loading config。

5. Experimental Results (实验结果)

5.1 Main OSWorld results

Base model	No skill	Text-only	MMSkills	Main takeaway
Gemini 3.1 Pro	44.08	40.76	50.11	MMSkills 比 no-skill +6.03 pp；text-only 在该模型上反而低于 baseline。
Gemini 3 Flash	36.65	40.27	47.97	MMSkills 比 no-skill +11.32 pp。
Qwen3-VL-235B	21.34	28.57	39.17	MMSkills 比 no-skill +17.83 pp，说明外部视觉 procedural knowledge 对较弱/开放模型帮助更大。
GLM-5V	28.71	36.61	38.51	text-only 有帮助，但 multimodal package 进一步提升。
Kimi-K2.6	34.98	39.66	46.59	MMSkills 比 no-skill +11.61 pp。
Qwen3-VL-8B-Instruct	10.78	14.93	25.40	小模型提升最明显，OSWorld +14.62 pp。

5.2 Auxiliary GUI and game results

Model	Benchmark metric	No skill	Text-only	MMSkills
Gemini 3 Flash	macOSWorld overall	55.94	53.85	65.73
Gemini 3 Flash	VAB-Minecraft success / avg score	67.24 / 0.7462	68.96 / 0.7541	73.28 / 0.7884
Gemini 3 Flash	Super Mario total perf. / reward	411.00 / 766.67	548.00 / 912.00	624.00 / 1081.33
Qwen3-VL-235B	macOSWorld overall	47.55	43.36	51.75
Qwen3-VL-235B	VAB-Minecraft success / avg score	52.59 / 0.6308	55.17 / 0.6634	62.07 / 0.7114
Qwen3-VL-235B	Super Mario total perf. / reward	454.50 / 955.50	610.50 / 1138.25	788.00 / 1514.25
GLM-5V	macOSWorld overall	34.97	51.75	51.75
GLM-5V	VAB-Minecraft success / avg score	56.03 / 0.6701	61.20 / 0.6938	68.10 / 0.7495
GLM-5V	Super Mario total perf. / reward	612.75 / 1191.50	794.50 / 1218.00	950.50 / 1384.50
Qwen3-VL-8B-Instruct	macOSWorld overall	6.29	4.90	6.29
Qwen3-VL-8B-Instruct	VAB-Minecraft success / avg score	23.28 / 0.3017	29.31 / 0.3754	38.79 / 0.4668
Qwen3-VL-8B-Instruct	Super Mario total perf. / reward	415.25 / 928.75	596.50 / 997.25	764.00 / 1128.75

结果说明 MMSkills 不只适用于 Ubuntu desktop；在 macOSWorld、Minecraft、Super Mario 中也有迁移收益。尤其是 Qwen3-VL-8B-Instruct，OSWorld 从 10.78% 到 25.40%，VAB-Minecraft 从 23.28% 到 38.79%，说明显式视觉 procedural knowledge 能部分补偿较小模型的内化先验不足。

5.3 Ablations: skill content and branch loading

Figure 3 解读：Panel A 比较 skill package components：text-only branch loading 已能超过 no-skill，但去掉 state cards 或去掉 images 都会削弱完整 MMSkills，说明二者互补：state cards 负责状态判别，keyframes 负责视觉证据 grounding。Panel B 比较 loading 方式：direct-full loading 容易污染 main context；view selection 可以缓解但不够，branch loading + view selection 才是完整机制。

5.4 Skill invocation and interaction dynamics

Table 3 显示 MMSkills 被调用得更频繁，但不是简单增加 overhead：OSWorld 上 Gemini 3 Flash 的 invoked 从 text-only 41.11% 到 MMSkills 62.50%，steps 从 no-skill 13.11 降到 11.86；Qwen3-VL-235B 的 invoked 从 37.50% 到 65.28%，steps 从 15.22 降到 9.87，Step $\Delta =-5.35$。VAB-Minecraft 上 Gemini 3 Flash 的 steps 从 16.92 降到 13.75，Qwen3-VL-235B 从 34.74 降到 27.07。Selected views 中 focus crops 在三组设置里占主导，说明 branch 确实在按需加载局部视觉 evidence，而不是盲目加载所有截图。

5.5 Behavioral shifts

Figure 4 解读：MMSkills 的收益不只是 final success rate。它改变了 action distribution：Qwen3-VL-235B 的 click share 从 75.8% 降到 63.7%，keyboard 和 DONE 增加，说明它从 click-heavy trial-and-error 转向更结构化的输入和完成判断；exact repeated actions 从 21.8% 降到 6.2%，最长 same-mode run 也降低，表明 state cards 和 verification cues 能减少重复卡顿。

Figure 6 解读：Appendix F 把相同 behavioral analysis 扩展到 GLM-5V 和 Kimi-K2.6。方向与 Figure 4 一致：MMSkills 往往减少低价值重复动作，并让 DONE / verification-related behavior 更早出现。这个现象支持论文主张：skill package 不只是提供步骤，而是在 runtime 改变 agent 对“当前状态是否适合继续”的判断。

5.6 Representative cases

Figure 7 解读：这个 Calc case 展示 branch-loaded MMSkills 如何把 spreadsheet construction 拆成局部 subgoals，并用状态卡检查 active sheet、header ranges、chart/table progress。它说明 MMSkills 的 guidance 不是替 main agent 点击，而是给 main agent 当前屏幕下的 next grounded decision。

Figure 8 解读：Terminal / file organization case 展示了另一类视觉环境：agent 需要判断文件是否已经移动/压缩、命令结果是否符合预期。MMSkills 的 verification cue 和 before/after evidence 可以帮助 agent 少走重复检查或错误路径。

5.7 Limitations and conclusion

作者明确指出三个主要限制：依赖 source-trajectory coverage；skill generation 或 visual grounding 可能出错；branch loading 带来 extra inference cost（额外推理成本）。进一步扩展到 embodied 或 safety-critical settings 需要更强 verification 和 online skill repair。整体结论是：把 reusable skills 表示为 multimodal procedural knowledge，能在 GUI 和 game visual-agent benchmark 中稳定补充 model-internal priors，尤其对较小模型和需要视觉状态判别的任务更有价值。