migrating-airflow-2-to-3
Guide for migrating Apache Airflow 2.x projects to Airflow 3.x. Use when the user mentions Airflow 3 migration, upgrade, compatibility issues, breaking changes, or wants to modernize their Airflow codebase. If you detect Airflow 2.x code that needs migration, prompt the user and ask if they want you to help upgrade. Always load this skill as the first step for any migration-related request.
89
87%
Does it follow best practices?
Impact
Pending
No eval scenarios have been run
Passed
No known issues
Quality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a well-structured skill description with excellent trigger terms and completeness, clearly specifying both when to use it and the domain it covers. Its main weakness is that it lacks specificity about the concrete migration actions it performs (e.g., updating imports, handling deprecated APIs, converting specific patterns), instead focusing more on the triggering conditions and meta-behavior like prompting the user.
Suggestions
Add specific concrete actions the skill performs, such as 'Updates deprecated operator imports, converts classic DAG definitions to TaskFlow API, resolves breaking API changes, and updates configuration settings.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (Airflow 2.x to 3.x migration) and mentions some actions like detecting Airflow 2.x code and prompting the user, but it doesn't list specific concrete migration actions (e.g., updating operator imports, replacing deprecated APIs, converting DAG definitions). The actions described are more about when to trigger than what the skill concretely does. | 2 / 3 |
Completeness | Clearly answers both 'what' (guide for migrating Airflow 2.x to 3.x) and 'when' (explicit 'Use when...' clause listing multiple trigger scenarios including migration, upgrade, compatibility issues, breaking changes, and modernization). Also includes proactive detection guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'Airflow 3 migration', 'upgrade', 'compatibility issues', 'breaking changes', 'modernize their Airflow codebase', and 'Airflow 2.x code'. These cover a good range of terms users would naturally use when seeking migration help. | 3 / 3 |
Distinctiveness Conflict Risk | Highly distinctive — the combination of 'Apache Airflow', '2.x to 3.x', and 'migration' creates a very specific niche that is unlikely to conflict with other skills. The version-specific migration focus clearly differentiates it from general Airflow or general migration skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
85%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a strong migration skill with excellent actionability, clear workflow sequencing, and well-organized progressive disclosure. The code examples are executable and the reference tables provide immediate value. The main area for improvement is trimming some architectural explanation that Claude doesn't need to perform the migration effectively.
Suggestions
Trim the 'Architecture & Metadata DB Access' section to focus on the code impact and replacement patterns, removing the bullet points explaining what the DAG processor and Triggerer are.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Generally efficient but includes some explanatory content Claude doesn't need (e.g., explaining what the DAG processor and Triggerer are, the architecture overview). The quick reference tables and code examples are well-targeted, but sections like 'Architecture & Metadata DB Access' could be trimmed to focus on just the code impact and patterns. | 2 / 3 |
Actionability | Provides fully executable code examples (ListDagsOperator, REST API calls), specific ruff commands with exact flags, concrete import mapping tables, and precise search patterns. The migration steps are copy-paste ready with real commands like `ruff check --preview --select AIR --fix --unsafe-fixes .`. | 3 / 3 |
Workflow Clarity | The 'Migration at a Glance' section provides a clear 5-step sequence with explicit validation (re-running Ruff after changes, manual search checklist). It includes feedback loops ('implement changes incrementally, re-running Ruff and code searches after each major change') and cautions about testing updated logic. The workflow handles a complex migration process with appropriate checkpoints. | 3 / 3 |
Progressive Disclosure | Excellent structure with a concise overview in the main file and clear one-level-deep references to four specific reference files (config-changes.md, migration-patterns.md, removed-methods.md, migration-checklist.md). Each reference is clearly labeled with its purpose, and the main file contains just enough detail to be immediately useful without being overwhelming. | 3 / 3 |
Total | 11 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
frontmatter_unknown_keys | Unknown frontmatter key(s) found; consider removing or moving to metadata | Warning |
Total | 10 / 11 Passed | |
- Repository
- astronomer/agents
- Commit
0642adb
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.