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.
68
83%
Does it follow best practices?
Impact
—
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 strong skill description with excellent trigger terms and completeness, clearly defining both what the skill does and when to use it. Its main weakness is that the 'what' portion could be more specific about the concrete actions performed during migration (e.g., updating DAG syntax, handling deprecated APIs, updating imports). The proactive detection instruction ('If you detect Airflow 2.x code...') is a nice touch for discoverability.
Suggestions
Add specific concrete actions the skill performs, such as 'Updates deprecated imports, refactors DAG definitions, migrates TaskFlow API usage, handles removed configuration options' to improve specificity.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | The description names the domain (Airflow 2.x to 3.x migration) and mentions some actions like 'migrating', 'upgrade', and 'modernize', but doesn't list specific concrete actions such as updating specific APIs, refactoring DAG definitions, handling deprecated operators, or updating configuration files. | 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, plus proactive detection of Airflow 2.x code). The explicit trigger guidance is thorough. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'Airflow 3 migration', 'upgrade', 'compatibility issues', 'breaking changes', 'modernize', '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 with a clear niche: specifically Airflow 2.x to 3.x migration. The combination of 'Airflow', 'migration', '2.x to 3.x', and 'breaking changes' makes it very unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
77%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, well-structured migration guide with excellent actionability—concrete commands, executable code examples, and precise mapping tables. The workflow is clearly sequenced with validation steps. The main weaknesses are moderate verbosity in the architecture section and the inline content being somewhat heavy for a top-level SKILL.md when reference files are supposedly available.
Suggestions
Consider moving the quick reference tables and detailed architecture/metadata DB access patterns into the reference files, keeping only the most critical 2-3 import changes inline as examples.
Trim the architecture explanation to focus solely on the code impact (ORM access fails at runtime) rather than explaining the component topology.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is mostly efficient and avoids explaining basic concepts Claude knows, but some sections could be tightened—e.g., the architecture explanation about DAG processor, Triggerer, and API server is somewhat verbose for a migration guide. The quick reference tables are well-structured and dense. | 2 / 3 |
Actionability | Provides fully executable code examples (ListDagsOperator, REST API calls), specific Ruff commands with exact flags, concrete import mapping tables, and precise context key replacements. The guidance is copy-paste ready and specific. | 3 / 3 |
Workflow Clarity | The 'Migration at a Glance' section provides a clear 5-step sequence with explicit validation (re-running Ruff after changes), incremental implementation, and a caution to test updated logic. The workflow includes feedback loops (step 4: re-run after each major change) and covers destructive/breaking changes with explicit checkpoints. | 3 / 3 |
Progressive Disclosure | The skill references four detailed reference files (config-changes.md, migration-patterns.md, removed-methods.md, migration-checklist.md) with clear descriptions, which is good structure. However, no bundle files were provided to verify these exist, and the main SKILL.md itself is quite long with inline tables and code that could potentially be offloaded to reference files. The balance between overview and detail leans toward too much inline content. | 2 / 3 |
Total | 10 / 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
535a040
- 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.