/authoring-github-workflows

name: authoring-github-workflows
description: "Author and review GitHub Actions workflow YAML safely so syntactically-valid YAML can't ship a workflow that GitHub Actions refuses to run. USE FOR: editing, adding, or reviewing any file under .github/workflows/, writing run-name/name/if/env/run values that contain ${{ }} expressions, diagnosing a run that fails with 'This run likely failed because of a workflow file issue' and no jobs starting, deciding when a workflow scalar must be quoted, validating workflows with actionlint. DO NOT USE FOR: authoring application YAML unrelated to GitHub Actions, Azure Pipelines, GitLab CI, or non-workflow YAML. SCOPE: this skill covers *syntactic/structural* correctness of workflow YAML (quoting, parsing, actionlint); for *semantic and functional* workflow design (what a workflow should do, agentic-workflow behavior), see .github/agents/agentic-workflows.agent.md — the two are complementary. INVOKES: actionlint (downloaded pinned binary) plus git/grep for inspection."
license: MIT

Authoring GitHub Actions Workflows Safely

GitHub Actions workflow files are YAML, but **valid YAML is not the same as a valid workflow**. A workflow can parse cleanly with `yaml.safe_load` (or a casual review) yet still be rejected by GitHub Actions at load time — producing the opaque failure *"This run likely failed because of a workflow file issue"* with **zero jobs started**. This skill teaches the YAML-vs-Actions traps (the `#`-as-comment trap above all), how to quote expression scalars correctly, and how to validate with `actionlint` before merge.

> **Scope: syntactic vs. semantic.** This skill is about the *syntactic and structural* correctness of workflow YAML — quoting, parsing, and `actionlint`-level validity that determines whether GitHub Actions will load and run a file at all. It is **not** about *what* a workflow should do or how an agentic workflow should behave. For *semantic and functional* guidance (designing workflow logic, agentic-workflow patterns, gh-aw authoring), use [`.github/agents/agentic-workflows.agent.md`](../../../.github/agents/agentic-workflows.agent.md). The two are complementary: get the behavior right with the agent, get the YAML right with this skill.

When to Use

• Editing, adding, or reviewing any file under `.github/workflows/`.
• Writing a `run-name`, `name`, `if`, `env`, `with`, or `run` value that embeds a `${{ }}` expression.
• A workflow run failed with *"This run likely failed because of a workflow file issue"* and **no jobs ran**.
• Eval/CI on `main` suddenly breaks for every run after a workflow edit merged, even though the change "looked fine."
• Deciding whether a YAML scalar needs quoting.

When Not to Use

• Authoring non-Actions YAML (app config, Kubernetes, Compose, Azure Pipelines, GitLab CI).
• Pure shell/script logic inside an already-valid `run:` block (that is a scripting task, not a workflow-syntax task).

The #1 Trap: `#` inside an unquoted expression becomes a YAML comment

In YAML, a space followed by `#` starts a **comment**. In an unquoted (plain) scalar, everything from that space-then-`#` to end-of-line is silently discarded:

# BAD — the run-name is silently truncated at " #"
run-name: ${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}

YAML parses this as `run-name: ${{ inputs.pr_number != '' && format('Evaluate PR` — an **unterminated `${{` expression**. `yaml.safe_load` succeeds (it just sees a truncated string with a trailing comment), so the bug passes naive validation, but GitHub Actions rejects the malformed expression and refuses to start any run.

# GOOD — wrap the whole value in double quotes so '#' stays inside the scalar
run-name: "${{ inputs.pr_number != '' && format('Evaluate PR #{0} @ {1}', inputs.pr_number, inputs.head_sha) || '' }}"

The inner expression already uses single quotes, so double-quoting the scalar is safe. This is exactly the bug that broke `dotnet/skills` evaluation on `main` (PR #746 → fixed by quoting).

Other characters that force quoting in a plain scalar

| Character / pattern | Why it breaks | Fix | |---------------------|---------------|-----| | space then `#` (space-hash) | Starts a YAML comment; truncates the value | Quote the whole value | | Leading `*`, `&`, `!`, `?`, `\|`, `>`, `@`, `` ` `` | YAML anchors/aliases/tags/block scalars | Quote the value | | Leading `{` or `[` | Parsed as flow mapping/sequence (a bare `${{ }}` starts with `$`, which is safe, but `{{` after a leading char is risky) | Quote the value | | `:` then space (colon-space) inside the value | Parsed as a nested mapping key | Quote the value | | Leading/trailing spaces that matter | Plain scalars strip them | Quote the value | | Values that are `true`/`false`/`yes`/`no`/`on`/`off`/numbers but must stay strings | YAML type coercion | Quote the value |

**Rule of thumb:** if a `name`, `run-name`, `if`, `env`, or `with` value contains a `${{ }}` expression *and* any literal `#`, `:`, or leading special character, **wrap the entire scalar in double quotes**.

Workflow

Step 1: Identify the changed/authored workflow files

git diff --name-only origin/main... -- .github/workflows/

For each file, scan every line that contains `${{` together with a `#`, a colon-space, or a leading special character.

Step 2: Quote risky expression scalars

Wrap the full value in double quotes when the value embeds an expression and contains a `#` or other special character (see the table above). Prefer double quotes when the inner expression uses single quotes, and vice-versa. Do **not** escape the `${{ }}` braces — quoting the scalar is enough.

Step 3: Validate with actionlint (authoritative)

`actionlint` understands the GitHub Actions schema *and* the expression grammar, so it catches exactly this class of bug that plain YAML linters miss. Download a pinned release and run it:

ACT