Turns a dbt Core project into an Airflow DAG/TaskGroup using Astronomer Cosmos. Use turning a dbt Core project into an Airflow DAG or TaskGroup with Astronomer Cosmos. Before implementing, verify dbt engine, warehouse, Airflow version, execution environment, DAG vs TaskGroup, and manifest availabili

Cosmos + dbt Core: Implementation Checklist Execute steps in order. Prefer the simplest configuration that meets the user's constraints. Version note : This skill targets Cosmos 1.11+ and Airflow 3.x. If the user is on Airflow 2.x, adjust imports accordingly (see Appendix A). Reference : Latest stable: https://pypi.org/project/astronomer cosmos/ Before starting , confirm: (1) dbt engine = Core (not Fusion → use cosmos dbt fusion ), (2) warehouse type, (3) Airflow version, (4) execution environment (Airflow env / venv / container), (5) DbtDag vs DbtTaskGroup vs individual operators, (6) manifest availability. 1. Configure Project (ProjectConfig) Approach When to use Required param Project path Files available locally dbt project path Manifest only dbt manifest load manifest path + project name 2. Choose Parsing Strategy (RenderConfig) Pick ONE load mode based on constraints: Load mode When to use Required inputs Constraints dbt manifest Large projects; containerized execution; fastest ProjectConfig.manifest path Remote manifest needs manifest conn id dbt ls Complex selectors; need dbt native selection dbt installed OR dbt executable path Can also be used with containerized execution dbt ls file dbt ls selection without running dbt ls every parse RenderConfig.dbt ls path select / exclude won't work automatic (default) Simple setups; let Cosmos pick (none) Falls back: manifest → dbt ls → custom CRITICAL : Containerized execution ( DOCKER / KUBERNETES /etc.) 3. Choose Execution Mode (ExecutionConfig) Reference : See [reference/cosmos config.md](reference/cosmos config.md execution modes executionconfig) for detailed configuration examples per mode. Pick ONE execution mode: Execution mode When to use Speed Required setup WATCHER Fastest; single dbt build visibility Fastest dbt adapter in env OR dbt executable path or dbt Fusion WATCHER KUBERNETES Fastest isolated method; single dbt build visibility Fast dbt installed in container LOCAL + DBT RUNNER dbt + adapter in the same Python installation as Airflow Fast dbt 1.5+ in requirements.txt LOCAL + SUBPROCESS dbt + adapter available in the Airflow deployment, in an isolated Python installation Medium dbt executable path AIRFLOW ASYNC BigQuery + long running transforms Fast Airflow ≥2.8; provider deps KUBERNETES Isolation between Airflow and dbt Medium Airflow ≥2.8; provider deps VIRTUALENV Can't modify image; runtime venv Slower py requirements in operator args Other containerized approaches Support Airflow and dbt isolation Medium container config 4. Configure Warehouse Connection (ProfileConfig) Reference : See [reference/cosmos config.md](reference/cosmos config.md profileconfig warehouse connection) for detailed ProfileConfig options and all ProfileMapping classes. Option A: Airflow Connection + ProfileMapping (Recommended) Option B: Existing profiles.yml CRITICAL : Do not hardcode secrets; use environment variables. 5. Configure Testing Behavior (RenderConfig) Reference : See [reference/cosmos config.md](reference/cosmos config.md testing behavior renderconfig) for detailed testing options. TestBehavior Behavior AFTER EACH (default) Tests run immediately after each model (default) BUILD Combine run + test into single dbt build AFTER ALL All tests after all models complete NONE Skip tests 6. Configure operator args Reference : See [reference/cosmos config.md](reference/cosmos config.md operator args configuration) for detailed operator args options. 7. Assemble DAG / TaskGroup Option A: DbtDag (Standalone) Option B: DbtTaskGroup (Inside Existing DAG) Option C: Use Cosmos operators directly Setting Dependencies on Individual Cosmos Tasks 8. Safety Checks Before finalizing, verify: [ ] Execution mode matches constraints (AIRFLOW ASYNC → BigQuery only) [ ] Warehouse adapter installed for chosen execution mode [ ] Secrets via Airflow connections or env vars, NOT plaintext [ ] Load mode matches execution (complex selectors → dbt ls) [ ] Airflow 3 asset URIs if downstream DAGs scheduled on Cosmos assets (see Appendix A) Appendix A: Airflow 3 Compatibility Import Differences Airflow 3.x Airflow 2.x from airflow.sdk import dag, task from airflow.decorators import dag, task from airflow.sdk import chain from airflow.models.baseoperator import chain Asset/Dataset URI Format Change Cosmos ≤1.9 (Airflow 2 Datasets): Cosmos ≥1.10 (Airflow 3 Assets): CRITICAL : Update asset URIs when upgrading to Airflow 3. Appendix B: Operational Extras Caching Cosmos caches artifacts to speed up parsing. Enabled by default. Reference: https://astronomer.github.io/astronomer cosmos/configuration/caching.html Memory Optimized Imports When enabled: Artifact Upload to Object Storage dbt Docs Hosting Cosmos serves dbt docs in the Airflow UI. The config depends on your Airflow major version (each uses a different UI plugin system) — it is not a free single vs multi choice: Airflow Config Scope Since 2 (FAB plugin) DBT DOCS DIR (+ DBT DOCS CONN ID , DBT DOCS INDEX FILE NAME ) Single project Cosmos 1.4.0+ 3.1+ (FastAPI) DBT DOCS PROJECTS (JSON) One or more projects Cosmos 1.11.0+ Airflow 2: Airflow 3.1+: Pick by Airflow version, not project count. The single project settings are the Airflow 2 path; Cosmos publishes no deprecation notice for them — do not describe them as "legacy" or "deprecated." Reference: https://astronomer.github.io/astronomer cosmos/configuration/hosting docs.html Related Skills cosmos dbt fusion : For dbt Fusion projects (not dbt Core) authoring dags : General DAG authoring patterns testing dags : Testing DAGs after creation

cosmos-dbt-core