authoring-github-workflows
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-workflo
npx skills add dotnet/skills --skill authoring-github-workflows --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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
- When to Use
- When Not to Use
- The #1 Trap: # inside an unquoted expression becomes a YAML comment
- Other characters that force quoting in a plain scalar
- Workflow
- Step 1: Identify the changed/authored workflow files
- Step 2: Quote risky expression scalars
- Step 3: Validate with actionlint (authoritative)
- Step 4: Confirm a YAML-only check is not enough
- Step 5: Keep the CI gate green
- Validation
- Common Pitfalls
- References
git diff --name-only origin/main... -- .github/workflows/
curl -fsSLo actionlint.tar.gz \
Verify the download against the pinned checksum before extracting/executing it:
echo "${ACTIONLINT_SHA256} actionlint.tar.gz" | sha256sum -c -
tar -xzf actionlint.tar.gz actionlint
Focus on workflow/expression correctness; silence shell/py style noise:What does the authoring-github-workflows skill do?
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-workflo
How do I install it?
Run `npx skills add dotnet/skills --skill authoring-github-workflows --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From dotnet/skills, a repository with 4,927 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.