Skip to content
Get packs

Guide · Agent skill

How to use the Managed Airflow Migration Guide agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The managed-airflow-migrations skill is an instruction package for an AI agent that helps you update Apache Airflow DAG code for Managed Service for Apache Airflow (formerly Cloud Composer). It targets Airflow 2.11.1 (Gen 2 and Gen 3) and Airflow 3 (Gen 3). After reading this guide you will know how to install the skill, ask for a migration in plain language, and review what the agent scans and changes.

Managed Airflow Migration Guidegoogle/skills · Apache-2.0

Quick start

  1. 1Download the skill ZIP. Get the managed-airflow-migrations ZIP from the skill's page in this directory.
  2. 2Unzip into a skills folder. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
  3. 3Or upload it in the Claude apps. Go to Settings, then Capabilities, then Skills, and upload the ZIP.
  4. 4Prepare gcloud and grep. Install the gcloud CLI if you need remote inspection or downloads, and confirm grep is available in your terminal.
  5. 5Describe your migration. Ask the agent to migrate your DAG code to Airflow 2.11.1 or Airflow 3, naming the source version if you know it.
  6. 6Review the scan results. Check each flagged pattern and its suggested remediation before accepting any change.
  7. 7Test before production. Run the migrated DAGs in a non-production environment with a backup in place.

What is an agent skill and what does this one do?

An agent skill is a folder of instructions, reference files and sometimes scripts that an AI agent loads when a task matches its description. This skill's entry file is SKILL.md, and it adds a structured migration checklist for Managed Service for Apache Airflow.

Airflow runs data pipelines written as Python files called DAGs. When you upgrade Airflow, some code stops working. The skill makes the agent work through version-by-version dependency changes, scan your DAG code with grep for patterns known to break, and suggest remediations. It can also download DAG files from a managed environment when you ask it to.

  • Maps provider package versions (Google, SSH, HTTP) for each Composer release in the source, from Composer 2.10.0 up to Composer 2.17.0 (target Airflow 2.11.1).
  • Scans for Airflow 2.11.0 and 2.10.5 changes such as Dataset scheduling, HTML in descriptions, teardown tasks and Pendulum 3.
  • Scans for Airflow 3 changes such as direct metadata database access and reorganized imports, plus Dataset-to-Asset renaming and removed SubDAGs and SLAs.
  • Can list and describe a source environment and download or upload DAG files, but only when you explicitly ask.

Install the skill (ZIP download or Claude apps)

Download the skill ZIP from the skill's page in this directory, then choose one of two routes. For a personal setup, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder so it applies only there.

If you use the Claude apps instead, open Settings, go to Capabilities, then Skills, and upload the ZIP there.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into .claude/skills/ inside your project
  • Apps: Settings → Capabilities → Skills, then upload the ZIP

Set up what the skill requires

The skill expects the gcloud CLI for downloading files and inspecting environments, and access to a Managed Service for Apache Airflow environment in Google Cloud if you want remote inspection or downloads. Local work needs only grep available in the terminal for the scan commands. The skill's own requirements list does not name a specific installation method, so follow Google Cloud's documentation for installing gcloud.

If you only want to scan DAG files you already have, you can skip the Google Cloud access requirement, as long as the files are in a local workspace the agent can search.

  • gcloud CLI (for downloading files and inspecting environments)
  • Access to a Managed Service for Apache Airflow environment, only for remote inspection or download
  • grep available in the terminal for the scan commands

How to trigger the skill with natural requests

You do not need a special command. Describe the migration in plain language and mention the target version. The skill is written to load when you ask to migrate DAG code to a newer Airflow version.

Phrase requests around the target and the code. The skill says not to use it for checking DAG run failures unrelated to code migration, so a request like 'why did my DAG fail last night' is outside its scope.

  • "Check my Airflow DAGs for anything that breaks on Airflow 2.11.1 before we upgrade our Composer environment."
  • "Scan the dags folder in migration_workspace for Airflow 3 breaking changes."
  • "Download the DAG files from my source Composer environment and list what needs changing for Airflow 3."

Example workflow: a typical migration session

Start by telling the agent your source and target. If you want it to read your live environment, say so explicitly, because the skill only inspects the source or downloads files when asked. The agent then maps the dependency changes for your starting version and runs the scan commands from the root of your local workspace, which defaults to ./migration_workspace.

For each hit, the skill gives a remediation. Review each suggested change before accepting it.

  • Confirm the source and target versions.
  • Download DAG files only if you asked for it.
  • Run the scans and review each match.
  • Apply fixes, then test the DAGs in a non-production environment.
grep -rn "Dataset(" ./dags

Safety notes: scripts and network access

This skill runs scripts and uses the network. The agent may edit your DAG code and may download or upload files to cloud storage. The skill's own assessment says to avoid production environments without a backup or review.

The skill requires attribution on gcloud, REST and MCP calls. For terminal gcloud commands, the agent prefixes the command with CLOUDSDK_METRICS_REQUEST_ATTRIBUTION set to a skill identifier, and sets the same string in User-Agent headers for direct HTTP calls. The skill says not to use gcloud config set for this, so the setting does not persist. This tag carries no user data, according to the attribution file.

  • Keep a backup or version control of your DAG folder before starting.
  • Review every edit the agent proposes, especially in production code.
  • Only ask for download or upload when you intend the files to move.
  • Test migrated DAGs in a non-production environment.

Tips for better migration results

Give the agent the exact target version. The skill covers Airflow 2.11.1 and Airflow 3 as separate paths, and the Airflow 3 checks are in a separate reference file. Ask for a full pass if you are going from an older Airflow 2 release, because the skill says to apply changes from earlier versions on top of each other.

Note that the scans only find known code patterns. A clean scan does not prove your DAGs will run.

  • State your source Composer version so the agent starts at the right point in the dependency map.
  • For Airflow 3, expect changes such as Dataset becoming Asset and imports moving from airflow to airflow.sdk.
  • Remember that the pattern scans only catch listed patterns; run your tests.

What people use it for

  • Moving existing Cloud Composer DAGs to Airflow 2.11.1 by checking provider changes such as removed BigQuery operators.
  • Planning an Airflow 3 upgrade on Managed Service for Apache Airflow Gen 3 by finding Dataset references and provide_session usage.
  • Scanning a local DAG folder for SSH hook timeout parameters and SimpleHttpOperator usage before an upgrade.
  • Checking whether DAGs scheduled on Datasets need to stay unpaused to catch events after the change.

Frequently asked questions

How do I install the managed-airflow-migrations skill?

Download the skill ZIP from its page in this directory. Unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder, or upload the ZIP in the Claude apps under Settings, Capabilities, then Skills.

Is the managed-airflow-migrations skill free?

The skill is released under the Apache-2.0 licence. This guide does not state pricing for the Claude apps or Google Cloud services, so check those providers for their own costs.

What do I need to use the Airflow migration skill?

You need the gcloud CLI for downloading files and inspecting environments, and access to a Managed Service for Apache Airflow environment if you work remotely. Local scanning needs grep in the terminal.

Does this skill work for Airflow outside Google Cloud?

No. The guidance is specific to Managed Service for Apache Airflow, formerly Cloud Composer, so it is not meant for non-Google Cloud Airflow deployments.

Can I use this skill to debug a failed DAG run?

No. The skill says not to use it for checking DAG run failures unrelated to code migration. Its scans look only for known code patterns that break during upgrades.

Is the skill safe to run on production DAGs?

Use caution. The skill runs scripts, uses the network, and may edit DAG code or move files to and from cloud storage. Keep a backup, review every change, and test in a non-production environment first.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you maintain Cloud Composer or Managed Service for Apache Airflow DAGs and are planning an upgrade to Airflow 2.11.1 or Airflow 3, and you want a checklist of breaking changes to scan against. Pick something else if your Airflow runs outside Google Cloud, or if your problem is a failed DAG run rather than code migration.

Download the skill