authoring-github-workflows

Validate GitHub Actions workflow YAML and fix expression quoting errors with actionlint.

5.3k|403|Updated Feb 3, 2026
One-click install
npx skills add https://github.com/dotnet/skills --skill authoring-github-workflows
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: authoring-github-workflows
Source: https://github.com/dotnet/skills/tree/main/.agents/skills/authoring-github-workflows
Command: npx skills add https://github.com/dotnet/skills --skill authoring-github-workflows

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

GitHub Actions workflow files can be syntactically valid YAML 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. The most common cause is a # character inside an unquoted ${{ }} expression being parsed as a YAML comment, silently truncating the value — a bug that yaml.safe_load and yamllint cannot catch.

Core Features & Use Cases

  • Quoting rules for expression scalars: A reference table of characters (#, :, leading */&/!/@, etc.) that force quoting of run-name, name, if, env, and with values containing ${{ }} expressions.
  • actionlint validation workflow: Step-by-step instructions to download a pinned, checksum-verified actionlint binary and run it with -shellcheck= -pyflakes= to focus on workflow/expression errors.
  • Use Case: After editing a workflow's run-name to include format('Evaluate PR #{0}', ...), quote the scalar and run actionlint to confirm GitHub Actions will actually load the file before merging.

Quick Start

Review my changes under .github/workflows/ for YAML quoting issues in ${{ }} expressions and validate them with actionlint.

Frequently Asked Questions about authoring-github-workflows

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
Why does my GitHub Actions workflow fail with 'This run likely failed because of a workflow file issue'?

This error means GitHub Actions rejected the workflow file at load time, so no jobs started. A common cause is a `#` inside an unquoted `${{ }}` expression being parsed as a YAML comment, truncating the value into an unterminated expression. Quote the scalar and validate with actionlint.

How do I validate GitHub Actions workflow YAML before merging?

Run actionlint against your workflow files, for example `actionlint -shellcheck= -pyflakes= .github/workflows/*.yml`. It understands the Actions schema and expression grammar, catching errors that plain YAML linters miss. A clean exit code 0 means the workflows are structurally valid.

When do I need to quote a ${{ }} expression in a GitHub Actions workflow?

Quote the entire scalar when the value contains a `#` preceded by a space, a colon followed by a space, or a leading special character like `*`, `&`, `!`, `@`, or backtick. Prefer double quotes when the inner expression uses single quotes, and never escape the `${{ }}` braces.

Is yamllint or yaml.safe_load enough to check GitHub Actions workflows?

No. YAML-only parsers accept the truncated-comment form where a `#` silently cuts off an expression, so they report success on workflows GitHub Actions will refuse to run. Only actionlint (or pushing and watching Actions parse it) validates the Actions layer.

Does this skill cover designing what a workflow should do?

No. It covers only syntactic and structural correctness of workflow YAML — quoting, parsing, and actionlint-level validity. For semantic and functional workflow design, including agentic-workflow behavior, use the complementary agentic-workflows agent guidance instead.