Migrating Airflow 2 To 3

This tackles the messy work of moving Apache Airflow 2.x DAGs to 3.x, where the biggest gotcha is that workers can no longer talk directly to the metadata database. It leans on Ruff's AIR rules to auto-fix imports and deprecated operators, then walks you through the manual stuff like replacing session.query calls with the Airflow Python client or REST API, updating context keys (execution_date is gone), and handling the switch from Datasets to Assets. The skill includes search patterns for ORM usage and provider_session decorators, plus a checklist for config changes and scheduling quirks. Honestly most valuable if you've got custom operators or task functions that touch the metadata DB, since that's where the breaking changes bite hardest.

skills.sh installs: 1.1K
GitHub stars: 459
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add astronomer/agents --skill migrating-airflow-2-to-3 --agent claude-code

Installs into .claude/skills of the current project.

Files

Airflow 2 to 3 Migration

This skill helps migrate Airflow 2.x DAG code to Airflow 3.x, focusing on code changes (imports, operators, hooks, context, API usage).

Important: Before migrating to Airflow 3, strongly recommend upgrading to Airflow 2.11 first, then to at least Airflow 3.0.11 (ideally directly to 3.1). Other upgrade paths would make rollbacks impossible. See: https://www.astronomer.io/docs/astro/airflow3/upgrade-af3#upgrade-your-airflow-2-deployment-to-airflow-3. Additionally, early 3.0 versions have many bugs - 3.1 provides a much better experience.