<!-- Copyright 2026 FlagOS Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

FL Plugin — Model Migration Skill

Usage

/model-migrate-flagos <model_name> [upstream_folder] [plugin_folder]

Execution

Step 1: Parse arguments and validate paths

Extract from user input:

• {{modelname}} = first argument (required, snakecase)
• {{upstream_folder}} = second argument or /tmp/vllm-upstream-ref
• {{plugin_folder}} = third argument or current working directory

If {{upstreamfolder}} doesn't exist, ask user whether to clone it. If {{pluginfolder}} doesn't exist, error out.

→ Tell user: Confirm parsed model name and paths.

Step 2: Load references and resolve placeholders

Read these files (relative to this SKILL.md):

• references/procedure.md — step-by-step migration procedure
• references/compatibility-patches.md — 0.13.0 patch catalog
• references/operational-rules.md — communication, TaskList, bash rules, resilience

The procedure references executable scripts in scripts/:

• scripts/validate_migration.py — automated code review (Step 6)
• scripts/benchmark.sh — benchmark verification (Step 9)
• scripts/serve.sh — serve model locally (Step 10.1, also used for E2E)
• scripts/request.sh — test request (Step 10.2)
• scripts/e2e_eval.py — E2E correctness verification (Step 11)
• scripts/e2etestprompts.json — test prompts for E2E (5 text + 5 multimodal)
• scripts/e2econfig.template.json — E2E config template (copy to e2econfig.json and fill in)
• scripts/e2eremoteserve.sh — manage GT server on remote machine via SSH

Then investigate upstream source + HuggingFace to resolve all placeholders:

Naming conventions vary per model — always verify from actual source, never guess.

→ Tell user: Present all resolved values. Use AskUserQuestion if anything is ambiguous.

Step 3: Execute procedure

With placeholders resolved, execute every step in procedure.md sequentially. Apply patches from compatibility-patches.md during the copy-then-patch step. Follow operational-rules.md throughout.

→ Tell user: Before starting, output a numbered plan. Report progress at each step boundary.

Scripts Reference

Examples

Example 1: Typical new model

User says: "/model-migrate-flagos kimi_k25"
Actions:
  1. Parse → model_name=kimi_k25, defaults for upstream/plugin paths
  2. Clone upstream, find vllm/model_executor/models/kimi_k25.py
  3. Discover it wraps DeepseekV2 → follow kimi_k25 (wrapper) pattern
  4. Copy file, apply P1+P2 patches, create config bridge
  5. Register, validate, test, benchmark, serve+request
  6. E2E verification against upstream GT
Result: kimi_k25 fully working in plugin, all 11 steps passed

Example 2: Re-run after upstream update

User says: "migrate qwen3_5 again, upstream updated"
Actions:
  1. Idempotent re-run — overwrite existing files with fresh upstream copy
  2. Re-apply patches, re-validate, re-test
  3. Re-run E2E to confirm no regression
Result: qwen3_5 updated to match latest upstream, no regressions

Troubleshooting

General principle: When any runtime error occurs, first compare vLLM upstream code against both the plugin adaptation and the installed 0.13.0 environment. The diff is the fastest path to root cause. See operational-rules.md § Debugging Priority: Upstream-First for the full protocol.