Skip to content

Commit 81ff7fb

Browse files
yottahmdyottahmd
committed
docs(skill): condense reference files for conciseness
Reduce total skill reference from 2311 to 1365 lines (41%) by trimming verbose examples, merging redundant sections, and dropping niche config details while preserving all essential DAG authoring information.
1 parent 417563d commit 81ff7fb

6 files changed

Lines changed: 170 additions & 1116 deletions

File tree

‎skills/dagu/SKILL.md‎

Lines changed: 42 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ description: Writes, validates, and debugs Dagu DAG workflow definitions in YAML
44
---
55
# Dagu DAG Authoring Reference
66

7-
Dagu runs workflows defined as DAGs in YAML. Each YAML file defines steps with commands, dependencies, and executor configurations. This reference covers everything needed to write correct DAG files.
7+
Dagu runs workflows defined as DAGs in YAML. Each YAML file defines steps with commands, dependencies, and executor configurations.
88

99
## Execution Types
1010

@@ -13,27 +13,18 @@ Dagu runs workflows defined as DAGs in YAML. Each YAML file defines steps with c
1313
| `chain` (default) | Steps run sequentially in definition order. `depends:` is not allowed. |
1414
| `graph` | Steps run based on `depends:` declarations. Steps without `depends:` run immediately in parallel. |
1515

16-
**Always use `type: graph`** in DAG definitions. It supports both sequential (via `depends:`) and parallel execution, making it strictly more capable than `chain`. Every DAG you write should include `type: graph` at the top level.
16+
**Always use `type: graph`** — it supports both sequential (via `depends:`) and parallel execution, making it strictly more capable than `chain`.
1717

1818
## Step Identity: `id` vs `name`
1919

20-
**Always set `id` on every step. Omit `name` — it is redundant.** When `name` is omitted, it is automatically set to the `id` value. When both are omitted, a name is auto-generated (e.g., `cmd_1`, `docker_1`), but the step cannot be referenced by other steps.
20+
**Always set `id` on every step. Omit `name` — it is redundant.** When `name` is omitted, it defaults to the `id` value. Without both, a name is auto-generated but the step cannot be referenced.
2121

22-
The `id` field is required for:
23-
- Referencing step outputs via `${step_id.stdout}`, `${step_id.stderr}`, `${step_id.exit_code}`
24-
- Dependencies via `depends: [step_id]`
22+
`id` is required for output references (`${step_id.stdout}`, `${step_id.exit_code}`) and dependencies (`depends: [step_id]`).
2523

26-
**Step ID rules:**
27-
- Regex: `^[a-zA-Z][a-zA-Z0-9_]*$`
28-
- Must start with a letter, followed by letters, digits, or underscores
29-
- Max length: 40 characters
30-
- **No hyphens** — use underscores instead
31-
- Reserved words (cannot be used as IDs): `env`, `params`, `args`, `stdout`, `stderr`, `output`, `outputs`
24+
**Step ID rules:** regex `^[a-zA-Z][a-zA-Z0-9_]*$`, max 40 chars, **no hyphens** (use underscores). Reserved words: `env`, `params`, `args`, `stdout`, `stderr`, `output`, `outputs`.
3225

3326
## Step Execution
3427

35-
Steps can run commands via different executor types. The default executor runs shell commands.
36-
3728
```yaml
3829
type: graph
3930
steps:
@@ -52,99 +43,62 @@ steps:
5243
5344
### Captured output variables (`output:`)
5445

55-
Capture stdout **content** to a named variable with `output:`, reference with `${VAR}`:
56-
57-
```yaml
58-
type: graph
59-
steps:
60-
- id: get_date
61-
command: date +%Y-%m-%d
62-
output: TODAY
63-
64-
- id: use_date
65-
command: echo "Today is ${TODAY}"
66-
depends: [get_date]
67-
```
68-
69-
For JSON output, extract fields with `${VAR.key}`:
70-
71-
```yaml
72-
type: graph
73-
steps:
74-
- id: get_config
75-
command: echo '{"host":"db.example.com","port":5432}'
76-
output: CONFIG
77-
78-
- id: use_config
79-
command: echo "Host is ${CONFIG.host}"
80-
depends: [get_config]
81-
```
46+
Capture stdout **content** to a named variable with `output:`, reference with `${VAR}`. For JSON output, extract fields with `${VAR.key}`.
8247

8348
### Step reference properties (`${step_id.XXX}`)
8449

85-
Steps with an `id` expose three properties to downstream steps:
86-
8750
| Reference | Value |
8851
|-----------|-------|
8952
| `${step_id.stdout}` | **File path** to the step's stdout log |
9053
| `${step_id.stderr}` | **File path** to the step's stderr log |
9154
| `${step_id.exit_code}` | Exit code as a string |
9255

93-
**Important:** `${step_id.stdout}` returns the **file path**, not the content. Use `output:` to capture **content** into a variable.
56+
**Important:** `${step_id.stdout}` returns the **file path**, not the content. Use `output:` to capture **content**. Slicing is supported: `${step_id.stdout:start:length}`.
9457

95-
Slicing syntax is supported: `${step_id.stdout:start:length}`
58+
### Combined example
9659

9760
```yaml
9861
type: graph
9962
steps:
100-
- id: producer
101-
command: echo "hello world"
102-
output: CONTENT
63+
- id: get_config
64+
command: echo '{"host":"db.example.com","port":5432}'
65+
output: CONFIG
10366
10467
- id: consumer
105-
depends: [producer]
68+
depends: [get_config]
10669
script: |
107-
# Content captured by output: field
108-
echo "Content: ${CONTENT}"
70+
# Content via output: variable (direct value + JSON field access)
71+
echo "Full: ${CONFIG}"
72+
echo "Host: ${CONFIG.host}"
10973
11074
# File paths to log files
111-
echo "Stdout file: ${producer.stdout}"
112-
echo "Stderr file: ${producer.stderr}"
113-
114-
# Exit code
115-
echo "Exit code: ${producer.exit_code}"
116-
117-
# Slicing: first 5 chars of stdout path
118-
echo "Prefix: ${producer.stdout:0:5}"
75+
echo "Stdout file: ${get_config.stdout}"
76+
echo "Stderr file: ${get_config.stderr}"
77+
echo "Exit code: ${get_config.exit_code}"
11978
```
12079

12180
Resolution priority: when `${foo.bar}` is evaluated, step references are checked first, then JSON path on variables.
12281

123-
## Parameters
82+
## Parameters and Environment Variables
12483

12584
```yaml
12685
type: graph
12786
params:
12887
env: production
12988
region: us-east-1
13089
131-
steps:
132-
- id: deploy
133-
command: deploy --env ${env} --region ${region}
134-
```
135-
136-
Override at runtime: `dagu enqueue my-dag -- env=staging region=eu-west-1`
137-
138-
## Environment Variables
139-
140-
```yaml
141-
type: graph
14290
# Use list-of-maps to preserve ordering (maps iterate randomly in Go):
14391
env:
14492
- BASE_DIR: /data
14593
- OUTPUT_DIR: ${BASE_DIR}/output
94+
95+
steps:
96+
- id: deploy
97+
command: deploy --env ${env} --region ${region} --out ${OUTPUT_DIR}
14698
```
14799

100+
Override params at runtime: `dagu enqueue my-dag -- env=staging region=eu-west-1`
101+
148102
## Lifecycle Hooks
149103

150104
```yaml
@@ -188,7 +142,7 @@ steps:
188142

189143
## Dynamic Fan-Out with `parallel:`
190144

191-
Use `parallel:` to iterate over dynamic output from a previous step. Each item gets its own sub-DAG run with retry, timeout, and UI visibility. Requires `call:` (see pitfall #20). Do NOT use bash `for` loops over output variables (see pitfall #23).
145+
Use `parallel:` to iterate over dynamic output from a previous step. Each item gets its own sub-DAG run with retry, timeout, and UI visibility. Requires `call:` (see pitfalls). Do NOT use bash `for` loops over output variables.
192146

193147
```yaml
194148
type: graph
@@ -240,76 +194,27 @@ steps:
240194
command: echo "handling error"
241195
```
242196

243-
## Finding DAG Files
244-
245-
Run `dagu config` to discover where DAGs and other files are stored on the local system. The `DAGs directory` line shows where DAG YAML files should be created and read from.
246-
247-
```bash
248-
dagu config # Shows all resolved paths (DAGs dir, logs, data, etc.)
249-
```
250-
251-
## Schema Lookup via CLI
252-
253-
Run `dagu schema <dag|config> [path]` to look up field definitions, types, defaults, and allowed values. Use dot-separated paths to drill into nested fields (e.g. `dagu schema dag steps.container`).
254-
255-
```bash
256-
dagu schema dag # All DAG root-level fields
257-
dagu schema dag steps # Step fields
258-
dagu schema dag steps.container # Container config
259-
dagu schema dag steps.retry_policy # Retry policy fields
260-
dagu schema dag steps.agent # Agent step config
261-
dagu schema dag handler_on # Lifecycle hooks
262-
dagu schema dag defaults # Default step config
263-
dagu schema config # All config fields
264-
dagu schema config auth # Auth config
265-
```
266-
267-
## Checking Run Status
268-
269-
For agent-triggered execution, prefer `dagu enqueue` over `dagu start`. Do not check whether the DAG is already running or queued before enqueueing unless the user explicitly asks for that check or requests singleton behavior.
270-
271-
After enqueueing or starting a DAG, use `dagu status` to inspect the result. The output is a tree showing each step's status, command, stdout/stderr content, and errors.
197+
## CLI Quick Reference
272198

273199
```bash
274-
dagu status my-dag # Latest run
275-
dagu status --run-id=<id> my-dag # Specific run
276-
dagu status --run-id=<id> --sub-run-id=<id> my-dag # Sub-DAG run
200+
dagu config # Show resolved paths (DAGs dir, logs, data, etc.)
201+
dagu schema dag # All DAG root-level fields
202+
dagu schema dag steps.container # Drill into nested fields with dot paths
203+
dagu schema config # All config fields
204+
dagu enqueue my-dag # Preferred over `dagu start` for agent use
205+
dagu status my-dag # Latest run status
206+
dagu status --run-id=<id> my-dag # Specific run
207+
dagu history my-dag --last 7d --status failed # Find past run IDs
277208
```
278209

279-
Example output for a failed run:
280-
281-
```
282-
Failed ✗ - 2026-03-10 14:22:15
283-
dag: my-dag (45s)
284-
│
285-
├─fetch_data (12s) [succeeded]
286-
│ ├─curl -f https://api.example.com/data -o data.json
287-
│ └─stdout: /path/to/stdout.log
288-
│ {"status": "ok", "records": 142}
289-
│
290-
└─process_data (33s) [failed]
291-
├─python transform.py --input data.json
292-
├─stderr: /path/to/stderr.log
293-
│ Traceback (most recent call last):
294-
│ File "transform.py", line 42
295-
│ KeyError: 'missing_field'
296-
└─error: command exited with code 1
297-
298-
Result: Failed ✗
299-
```
300-
301-
Use `dagu history` to find run IDs of past executions:
302-
303-
```bash
304-
dagu history my-dag --last 7d --status failed
305-
```
210+
Prefer `dagu enqueue` over `dagu start`. Do not check whether the DAG is already running before enqueueing unless the user explicitly asks.
306211

307212
## Quick Reference Tables
308213

309-
See the `references/` directory for complete details:
310-
- `cli.md` — All 25 CLI subcommands with flags
311-
- `schema.md` — Complete DAG YAML schema (top-level and step-level fields)
312-
- `executors.md` — All 18 executor types with configuration
313-
- `env.md` — Execution and configuration environment variables
214+
See the `references/` directory:
215+
- `cli.md` — CLI subcommands and flags
216+
- `schema.md` — Complete DAG YAML schema
217+
- `executors.md` — All executor types with configuration
218+
- `env.md` — Environment variables
314219
- `pitfalls.md` — Critical pitfalls with examples
315-
- `codingagent.md` — Integrating AI coding agents (Claude Code, Codex, Gemini, etc.) into DAG workflows
220+
- `codingagent.md` — AI coding agent integration

0 commit comments

Comments
 (0)