Guide · Agent skill
How to use the Managed Airflow DAG Troubleshooting agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
This guide explains how to install and use the managed-airflow-dag-troubleshooting agent skill, a set of instructions that lets an AI agent investigate failed Apache Airflow DAG runs and task instances on Google Cloud's Managed Service for Apache Airflow (formerly Cloud Composer). A DAG is a workflow made of tasks. By the end you will know what the skill does, how to add it to your agent, how to ask for help in plain language, and what it needs before it can read your logs and code.
Managed Airflow DAG Troubleshootinggoogle/skills · Apache-2.0 Download the skill Quick start
- 1Get the skill ZIP. Download the ZIP file for the managed-airflow-dag-troubleshooting skill from the page where you found this guide.
- 2Install it. Unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ in a project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
- 3Set up gcloud access. Install the Google Cloud SDK with the composer, logging and storage components, and sign in with an account that can read the Composer environment, its logs and its DAG bucket.
- 4Describe the failure. Tell the agent which DAG run or task failed and in which environment and location, if you know them.
- 5Review the evidence. Check that the agent quotes the exact log text and names the failed task instance before you act on its fix.
- 6Apply the fix and re-run. Make the configuration or code change the agent recommends, then run the DAG again to confirm the task succeeds.
What an agent skill is and what this one does
An agent skill is a folder with a SKILL.md file that gives an AI agent specific instructions for one kind of task. The agent loads the skill when a request matches its description.
When a workflow run fails on Managed Airflow, this skill tells the agent to investigate in a fixed order: fetch the error logs for the task, check each task's state, download the DAG's source code, and compare the code's settings against the error messages. The agent then reports the specific failed task, the exact log text as evidence, and a concrete fix.
- Fetches task logs with gcloud logging read and looks for Python tracebacks, API error codes such as 400, 403, 404 and 500, and Airflow signals such as AirflowTaskTimeout.
- Checks task state and metadata such as execution state, try number and timestamps.
- Downloads the DAG file from the environment bucket and checks values such as table IDs, disk sizes and URI paths against the error text.
- Checks Cloud Logging for known platform errors that match the failure and reports all that it finds.
- Handles DAGs generated by Orchestration Pipelines by explaining the failure in terms of the pipeline YAML.
How to install the skill
Download the ZIP file for the skill from the page where you found this guide. Then choose one of the two options below.
For a personal setup, unzip the file into ~/.claude/skills/. To limit the skill to one project, unzip it into the .claude/skills/ folder inside that project.
If you use the Claude apps instead, upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into .claude/skills/ in your project
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
What you need before the skill can work
The skill runs no scripts of its own, but it uses the network. It reads logs and files through Google Cloud tools, so it needs working access to your project. Without credentials it cannot read logs or files and may not be able to fully diagnose the failure.
The skill's commands target gcloud composer, gcloud logging and gcloud storage. It is not designed for self-hosted Airflow or for other clouds.
- Google Cloud SDK (gcloud) with the composer, logging and storage components installed
- A Google Cloud account with credentials that can access the Composer environment, its logs and its DAG bucket
- Access to Cloud Logging and Cloud Storage for that environment
How to ask for help so the skill triggers
You do not need to name the skill. The skill is meant to be used when you are working out why a DAG run or task instance failed. Describe the failure and mention your environment, DAG or task if you know them.
Phrase the request around the failure itself. Requests about overall performance tuning or sizing of an environment are outside the skill, and it says so explicitly.
- "My DAG run failed on Cloud Composer. Find the failing task and tell me why."
- "Why did task load_sales in the daily_sales DAG fail in environment prod-composer in us-central1?"
- "The task is getting a 404 from BigQuery. Check whether the table ID in the DAG matches the error."
- "Check the logs for any known platform issues that match this Managed Airflow failure."
Example: how a diagnosis is reported
To look up a task's state for a whole DAG run, the skill uses a command of this form, with your own values filled in. It also runs gcloud storage cp to download the DAG file so it can compare the code with the log text.
A good answer from the agent names the task instance, quotes the log text word for word as evidence, identifies the root cause as a code error, configuration mismatch or environment timeout, and gives a specific fix such as a corrected Python snippet or an exact configuration change.
gcloud composer environments run {env_name} --location {location} tasks states-for-dag-run -- -d {dag_id} -r {run_id}Safety notes: scripts, network and attribution
The skill makes network calls to Google Cloud and reads your logs, code and bucket contents. It is written to only suggest steps you can actually take, and it does not run scripts.
Before running any gcloud command, the skill's attribution reference tells the agent to tag terminal commands with a metrics environment variable that names the skill and its version. The tag carries no user data. The reference says not to use gcloud config set for this, because that would persist beyond the current task.
- Runs scripts: no. Uses network: yes.
- Commands run in the terminal get the attribution prefix. Generated scripts, Terraform and user code do not.
- Review each command the agent proposes before you approve it, especially those that download files from your bucket.
What people use it for
- Finding which task in a failed daily DAG run caused the failure and why, using its log text.
- Checking whether a 404 or 403 from BigQuery matches a dataset ID, table ID or permission problem in the DAG code.
- Checking whether a task timeout (AirflowTaskTimeout) or a Compute Engine disk-size setting explains a failure.
- Checking whether a failure correlates with a known Managed Airflow platform issue in Cloud Logging.
- Explaining a failure in an Orchestration Pipeline DAG in terms of the logical actions in its pipeline YAML.
Frequently asked questions
How do I install the managed airflow dag troubleshooting skill?
Download the skill ZIP and unzip it into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project. In the Claude apps, upload the ZIP under Settings → Capabilities → Skills.
What do I need to use this skill?
You need the Google Cloud SDK (gcloud) with the composer, logging and storage components, a Google Cloud account with credentials for the Composer environment, its logs and its DAG bucket, and access to Cloud Logging and Cloud Storage. Without these, the skill may not be able to fully diagnose the failure.
Is this skill free to use?
The skill is licensed under Apache-2.0. The source does not state any pricing, and Google Cloud usage for logs, storage and Composer is a separate matter that the skill does not cover.
Does this work with self-hosted Airflow or other clouds?
No. The skill's commands target Google Cloud's gcloud composer, gcloud logging and gcloud storage tools, so it is built for Managed Service for Apache Airflow (formerly Cloud Composer).
Can this skill tune my Airflow environment for performance?
No. The skill explicitly excludes overall performance tuning and sizing recommendations for a Managed Airflow environment, and using it for that gives off-target results.
Why can't the skill find the cause of my DAG failure?
The most common reason in the source is missing access. The skill cannot read logs or files without credentials, so check that your gcloud account can read the Composer environment, its logs and its DAG bucket.
Does the skill run scripts on my machine?
The skill's listing says it runs no scripts, but it does use the network to fetch logs, task states and DAG files through gcloud.
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
This skill suits data engineers and platform teams who already use Google Cloud Composer or Managed Airflow and want the agent to read failure logs and DAG code in a consistent, evidence-based way. It is a poor fit if you need performance tuning or sizing advice, run self-hosted Airflow or another cloud, or do not have gcloud access to the project.
Download the skill