debugging-dags
- Repo stars 39
- Author updated Live
- Author repo awesome-omni-skill
- Domain
- DevOps
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @diegosouzapw · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Windows
- Runtime requirements
- No special requirements
- Permissions
-
- Read-only
- Write / modify
- Network behavior
- Local-only
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: debugging-dags
description: Comprehensive DAG failure diagnosis and root cause analysis. Use for complex debugging requests…
category: devops
runtime: no special runtime
---
# debugging-dags output preview
## PART A: Task fit
- Use case: Comprehensive DAG failure diagnosis and root cause analysis. Use for complex debugging requests requiring deep investigation like "diagnose and fix the pipeline", "full root cause analysis", "why is this failing and how to prevent it". For simple debugging ("why did dag fail", "show logs"), the airflow entrypoint skill handles it directly. This skill provides structured investigation and prevention recommendations..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “Running the CLI / Step 1: Identify the Failure / Step 2: Get the Error Details” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “Comprehensive DAG failure diagnosis and root cause analysis. Use for complex debugging requests requiring deep investigation like "diagnose and fix the pipeline", "full root cause analysis", "why is this failing and how to prevent it". For simple debugging ("why did dag fail", "show logs"), the airflow entrypoint skill handles it directly. This skill provides structured investigation and prevention recommendations.”.
- **02** When the source has headings, the agent prioritizes “Running the CLI / Step 1: Identify the Failure / Step 2: Get the Error Details” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files; mostly runs locally; usually needs no extra API key.
## Running Rules
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files.
Start with a small task and check whether the result follows “Running the CLI / Step 1: Identify the Failure / Step 2: Get the Error Details”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: debugging-dags
description: Comprehensive DAG failure diagnosis and root cause analysis. Use for complex debugging requests…
category: devops
source: diegosouzapw/awesome-omni-skill
---
# debugging-dags
## When to use
- Comprehensive DAG failure diagnosis and root cause analysis. Use for complex debugging requests requiring deep investi…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “Running the CLI / Step 1: Identify the Failure / Step 2: Get the Error Details” and keep inference separate from source facts.
- read files, write/modify files; mostly runs locally; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "debugging-dags" {
input -> user goal + target files + boundaries + acceptance criteria
context -> Running the CLI / Step 1: Identify the Failure / Step 2: Get the Error Details
rules -> SKILL.md triggers / order / output contract
runtime -> no special runtime | read files, write/modify files | mostly runs locally
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} DAG Diagnosis
You are a data engineer debugging a failed Airflow DAG. Follow this systematic approach to identify the root cause and provide actionable remediation.
Running the CLI
Run all af commands using uvx (no installation required):
uvx --from astro-airflow-mcp af <command>
Throughout this document, af is shorthand for uvx --from astro-airflow-mcp af.
Step 1: Identify the Failure
If a specific DAG was mentioned:
- Run
af runs diagnose <dag_id> <dag_run_id>(if run_id is provided) - If no run_id specified, run
af dags statsto find recent failures
If no DAG was specified:
- Run
af healthto find recent failures across all DAGs - Check for import errors with
af dags errors - Show DAGs with recent failures
- Ask which DAG to investigate further
Step 2: Get the Error Details
Once you have identified a failed task:
- Get task logs using
af tasks logs <dag_id> <dag_run_id> <task_id> - Look for the actual exception - scroll past the Airflow boilerplate to find the real error
- Categorize the failure type:
- Data issue: Missing data, schema change, null values, constraint violation
- Code issue: Bug, syntax error, import failure, type error
- Infrastructure issue: Connection timeout, resource exhaustion, permission denied
- Dependency issue: Upstream failure, external API down, rate limiting
Step 3: Check Context
Gather additional context to understand WHY this happened:
- Recent changes: Was there a code deploy? Check git history if available
- Data volume: Did data volume spike? Run a quick count on source tables
- Upstream health: Did upstream tasks succeed but produce unexpected data?
- Historical pattern: Is this a recurring failure? Check if same task failed before
- Timing: Did this fail at an unusual time? (resource contention, maintenance windows)
Use af runs get <dag_id> <dag_run_id> to compare the failed run against recent successful runs.
On Astro
If you're running on Astro, these additional tools can help with diagnosis:
- Deployment activity log: Check the Astro UI for recent deploys — a failed deploy or recent code change is often the cause of sudden failures
- Astro alerts: Configure alerts in the Astro UI for proactive failure monitoring (DAG failure, task duration, SLA miss)
- Observability: Use the Astro observability dashboard to track DAG health trends and spot recurring issues
On OSS Airflow
- Airflow UI: Use the DAGs page, Graph view, and task logs to inspect recent runs and failures
Step 4: Provide Actionable Output
Structure your diagnosis as:
Root Cause
What actually broke? Be specific - not "the task failed" but "the task failed because column X was null in 15% of rows when the code expected 0%".
Impact Assessment
- What data is affected? Which tables didn't get updated?
- What downstream processes are blocked?
- Is this blocking production dashboards or reports?
Immediate Fix
Specific steps to resolve RIGHT NOW:
- If it's a data issue: SQL to fix or skip bad records
- If it's a code issue: The exact code change needed
- If it's infra: Who to contact or what to restart
Prevention
How to prevent this from happening again:
- Add data quality checks?
- Add better error handling?
- Add alerting for edge cases?
- Update documentation?
Quick Commands
Provide ready-to-use commands:
- To clear and rerun the entire DAG run:
af runs clear <dag_id> <run_id> - To clear and rerun specific failed tasks:
af tasks clear <dag_id> <run_id> <task_ids> -D - To delete a stuck or unwanted run:
af runs delete <dag_id> <run_id>
Decide Fit First
Design Intent
How To Use It
Boundaries And Review