agentleFS
petr-korobeinikovpetr-korobeinikov/skills/skills/actionlint/SKILL.md

actionlint

Skill1 starsChanged 5 months agoMITView on GitHub

Validates GitHub Actions workflow files with actionlint before they are committed, so obviously broken workflows never land in the repository. Installs actionlint through the mise skill when the project lacks it.

  • Installs packages

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. About 0 are common, 6 are distinctive, and 8 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Keep obviously broken GitHub Actions workflows out of the repository.

    line 19
  2. Distinctive:

    Before a commit that touches workflow files, run actionlint over the staged ones.

    line 20
  3. Distinctive:

    If anything is ambiguous, a prerequisite is missing, or you're unsure how to proceed — stop and ask the operator instead of guessing.

    line 30
  4. Very specific:

    Run the procedure when the staged changes include a workflow file — .github/workflows/*.yml or .github/workflows/*.yaml.

    line 41
  5. Distinctive:

    If no staged file matches, this skill does not apply.

    line 43
  6. Very specific:

    Run every step below from the repository root — cd "$(git rev-parse --show-toplevel)" — since the paths git prints are relative to it, and …

    line 60
  7. Very specific:

    If it's missing, install it via the mise skill (see Installing actionlint below) — never brew / go install / curl-pipe.

    line 76
  8. Distinctive:

    If actionlint can't be installed that way (no mise, or the project doesn't use mise), tell the operator and stop — don't reach for another …

    line 79
  9. Very specific:

    Don't rewrite the workflow blindly: if the fix isn't obvious, ask the operator.

    line 113
  10. Very specific:

    After a fix, re-stage it (git add) and re-run from step 3.

    line 115
  11. Very specific:

    If the mise skill is available, let it own the details (version pinning, mise.lock, the backend policy) — that's the canonical path here.

    line 133
  12. Very specific:

    If the repo already has .github/actionlint.yaml (or .yml), actionlint uses it automatically (self-hosted runner labels, config-variables, …

    line 159
  13. Very specific:

    Use the actionlint-system hook id: it runs the binary already on PATH (the mise-managed one) instead of fetching its own via the Go …

    line 188
  14. Distinctive:

    After the check, state which workflow files were linted, the exit code, the problems found (if any), and whether the commit is cleared or …

    line 202

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

actionlint

Keep obviously broken GitHub Actions workflows out of the repository. Before a commit that touches workflow files, run actionlint over the staged ones; any non-zero exit blocks the commit until it's fixed.

This pairs with vcs-identity-check and vcs-commit-msg as one more pre-commit precondition — the three are independent, so their order doesn't matter.

When in doubt, ask the operator

If anything is ambiguous, a prerequisite is missing, or you're unsure how to proceed — stop and ask the operator instead of guessing. One question is cheaper than a wrong commit, a misfired fix, or tokens spent working around a gap you could resolve by asking. This applies to every step below.

When this runs (the gate)

Run the procedure when the staged changes include a workflow file — .github/workflows/*.yml or .github/workflows/*.yaml. If no staged file matches, this skill does not apply; stay silent.

Remote is not checked. Workflow files under .github/workflows/ exist only for GitHub Actions (GitHub.com and GitHub Enterprise alike), so their presence is already a sufficient signal — checking that a remote points at github.com would only add false negatives on Enterprise (custom domain) and on local repos with no remote yet.

Scope is workflow files only. actionlint does not lint action.yml / action.yaml (composite-action metadata), so those are out of scope here.

Procedure

Run every step below from the repository root — cd "$(git rev-parse --show-toplevel)" — since the paths git prints are relative to it, and actionlint must resolve them from the same directory.

  1. Collect the staged workflow files (Added / Copied / Modified / Renamed — deletions don't need linting):

    git diff --cached --name-only --diff-filter=ACMR -- .github/workflows \
      | grep -E '\.ya?ml$'

    Empty result → the gate doesn't match; stop.

  2. Ensure actionlint is available: command -v actionlint. If it's missing, install it via the mise skill (see Installing actionlint below) — never brew / go install / curl-pipe. If actionlint can't be installed that way (no mise, or the project doesn't use mise), tell the operator and stop — don't reach for another installer.
  3. Confirm staged and working-tree versions agree. actionlint reads from the working tree, not the index, so a staged workflow carrying extra unstaged edits would be linted in a different version than the one committed:

    git diff --name-only -- <staged-files…>

    Any output → the versions diverge; stop and ask the operator to re-stage or set the edits aside, rather than linting content that won't be committed.

  4. Lint the staged files, passing them as arguments so unrelated errors in untouched legacy workflows don't block this commit:

    actionlint <staged-files…>

    Run plain actionlint — it auto-uses shellcheck / pyflakes only when they're on PATH, nothing to toggle for the gate. With step 3 clean, this checks exactly what will be committed.

  5. Act on the exit code ($?):
    • 0 — clean; the workflow part of the commit is good to go.
    • 1 — actionlint found problems in the workflow, including invalid YAML and a wrong workflow structure (these carry the [syntax-check] tag) — this is the "obviously broken" case. Show the output and keep the commit blocked. Don't rewrite the workflow blindly: if the fix isn't obvious, ask the operator. After a fix, re-stage it (git add) and re-run from step 3; the commit clears only once exit is 0.
    • 2 — invalid command-line argument: a mistake in how actionlint was invoked, not a workflow problem. Fix the invocation (step 4) and re-run.
    • 3 — actionlint could not read a file (could not read …): usually the paths didn't resolve — confirm the command ran from the repository root, then re-run.
  6. Clear the commit only on exit 0. This skill is the gate, not the commit itself — on 0 the workflow check has passed and the normal commit flow (vcs-identity-check / vcs-commit-msg) continues. Any non-zero exit keeps the commit blocked; don't reach for --no-verify or otherwise bypass it.

Installing actionlint when it's missing

Install with mise. If the mise skill is available, let it own the details (version pinning, mise.lock, the backend policy) — that's the canonical path here.

Without that skill but with the mise binary, add actionlint yourself under [tools] in mise.toml:

[tools]
actionlint = "<version>"

Resolve <version> from mise latest actionlint (all versions: mise ls-remote actionlint) — pin it fully, no latest. The raw name actionlint resolves through aqua to aqua:rhysd/actionlint. Either way: never brew, go install, or a curl-pipe script.

This skill does not install shellcheck or pyflakes. actionlint picks them up automatically when they're on PATH (extending its checks into run: shell and Python), and their absence is not an error. To turn the integrations off deterministically, pass empty values: actionlint -shellcheck= -pyflakes=.

Existing actionlint config

If the repo already has .github/actionlint.yaml (or .yml), actionlint uses it automatically (self-hosted runner labels, config-variables, per-path ignores). Respect it: don't overwrite it, and don't run -init-config over it. The config is optional — actionlint runs fine without one.

Optional: enforce with a pre-commit hook

The procedure above protects commits the agent makes. To also catch hand-typed commits, offer a pre-commit hook (install only with the user's agreement — propose, don't impose).

actionlint ships an official pre-commit-framework integration. In .pre-commit-config.yaml:

- repo: https://github.com/rhysd/actionlint
  rev: <vX.Y.Z>
  hooks:
    - id: actionlint-system

Set rev to the matching release tag — v plus the version from mise latest actionlint (so version X.Y.Z → tag vX.Y.Z), also listed at https://github.com/rhysd/actionlint/releases.

Use the actionlint-system hook id: it runs the binary already on PATH (the mise-managed one) instead of fetching its own via the Go toolchain (actionlint) or Docker (actionlint-docker). Install the pre-commit runner itself through the mise skill (it's a Python CLI → the pypi backend).

Not in scope

  • SHA-pinning uses: references — that's pinact / Dependabot, not actionlint.
  • CI integration (handle separately).

Reporting

After the check, state which workflow files were linted, the exit code, the problems found (if any), and whether the commit is cleared or blocked.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.