authoring-dags

Workflow and best practices for writing Apache Airflow DAGs. Use when creating a new DAG, write pipeline code, handling questions about DAG patterns and conventions or extending an existing DAG with a follow-up/downstream task. ANY request shaped like 'add a DAG named X', 'write a pipeline', 'add a task that runs after Y', or 'extend the DAG'. For testing and debugging DAGs, see the testing-dags skill.

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

73%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body delivers a well-sequenced, highly actionable workflow with genuine validation feedback loops and clean delegation to external skills. Its weaknesses are redundancy (ASCII diagram and duplicated CLI tables) and a dangling reference path for the best-practices file that carries the skill's core DAG-writing patterns.

Suggestions

Replace the ASCII workflow diagram with a one-line numbered phase list — the six phase headings already convey the same sequence at a fraction of the tokens.

Remove the duplicated 'af config connections/variables/providers/version' rows from the CLI Quick Reference table (or drop the Phase 1 table) so each command appears once.

Fix the dangling 'reference/best-practices.md' reference — either include the file in the bundle (e.g., under references/) or inline a minimal correct/incorrect DAG pattern example so the core writing guidance is reachable.

Dimension	Reasoning	Score
Conciseness	Mostly efficient tables and commands, but the ~30-line ASCII workflow diagram duplicates the six phase headers, the CLI Quick Reference re-lists six commands already tabulated in Phase 1, and Phases 5-6 restate content delegated to the testing-dags skill — more than minor tightening opportunities.	3 / 5
Actionability	Concrete, executable af CLI commands and glob patterns throughout ('af runs trigger-wait <dag_id> --timeout 300', '/dags//*.py'), but the body contains no inline DAG code example — the core writing patterns are delegated entirely to the reference file.	4 / 5
Workflow Clarity	Six clearly sequenced phases with explicit validation checkpoints (Phase 4 fix-and-retry on 'af dags errors'), a dedicated iterate/feedback loop, and approval gates (user approval in Phase 2, consent before triggering in Phase 5) — matching the top anchor.	5 / 5
Progressive Disclosure	Good structure with clearly signaled, one-level-deep references (best-practices reference and testing-dags skill), but the referenced 'reference/best-practices.md' does not exist in the skill bundle, leaving the sole pointer to the core pattern knowledge dangling.	4 / 5
	Total	16 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong description: it states concrete capabilities, gives explicit and natural 'Use when...' triggers including quoted request shapes, and cleanly boundaries the skill against testing-dags. Minor gaps in capability and keyword coverage keep specificity and trigger quality just below full marks.

Dimension	Reasoning	Score
Specificity	Names the domain and several concrete actions ('creating a new DAG', 'write pipeline code', 'extending an existing DAG with a follow-up/downstream task'), but coverage is not comprehensive — validation, operators, and connections work is not mentioned.	4 / 5
Completeness	Explicitly answers both what ('Workflow and best practices for writing Apache Airflow DAGs') and when ('Use when creating a new DAG... ANY request shaped like...'), with concrete trigger phrases and explicit boundary guidance to the testing-dags skill.	5 / 5
Trigger Term Quality	Strong natural trigger phrasings ('add a DAG named X', 'write a pipeline', 'add a task that runs after Y', 'extend the DAG') with synonyms, but a few common user terms are missing (e.g., 'schedule a task', 'dependency', .py file mentions).	4 / 5
Distinctiveness Conflict Risk	Clear Airflow-DAG-authoring niche with distinct triggers, and it explicitly delegates testing/debugging to the testing-dags skill, leaving only minimal overlap risk with related skills.	5 / 5
	Total	18 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning
relative_links	Relative link issues: 1 missing	Warning

	Total	14 / 16 Passed

Repository: astronomer/agents
Path: skills/authoring-dags/SKILL.md
Commit: 1ec1a1f

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

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.