Agent skill
validate-workflow
Validate GitHub Actions workflow files for syntax, best practices, and correctness. Use before committing workflow changes or when workflows fail.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/validate-workflow
SKILL.md
CI Workflow Validation Skill
Validate GitHub Actions workflow files for correctness.
When to Use
- Creating new workflow
- Modifying existing workflow
- Workflow syntax errors
- Before committing workflow changes
Quick Reference
# List workflows
gh workflow list
# View workflow details
gh workflow view <workflow-name>
# Validate YAML
yamllint .github/workflows/*.yml
# Lint with actionlint
actionlint .github/workflows/*.yml
Validation Methods
1. GitHub CLI
# View workflow
gh workflow view deploy.yml
# List all workflows
gh workflow list
# Get workflow metadata
gh api repos/owner/repo/actions/workflows
2. actionlint
pip install actionlint
actionlint .github/workflows/*.yml
3. yamllint
yamllint .github/workflows/*.yml
Common Issues
| Issue | Example | Fix |
|---|---|---|
| Syntax error | on: [push pull_request] |
Add comma: on: [push, pull_request] |
| Invalid action version | uses: actions/checkout@v99 |
Use valid version: @v4 |
| Missing required field | Job missing runs-on |
Add runs-on: ubuntu-latest |
| Invalid context | ${{ job.status }} in wrong place |
Move to correct context |
Workflow Checklist
- Valid YAML syntax
-
ontrigger configured correctly - All jobs have
runs-on - All steps have
runoruses - Action versions are specific (not @main)
- All secrets/vars available
- Timeouts set appropriately
- Permissions configured correctly
Best Practices
name: Quality Check
on: [push, pull_request]
jobs:
quality:
runs-on: ubuntu-latest
timeout-minutes: 10
permissions:
contents: read
steps:
- uses: actions/checkout@v4 # Specific version
- uses: actions/cache@v3
with:
path: ~/.cache/pip
key: ${{ runner.os }}-pip
- run: just pre-commit-all
Validation Workflow
# 1. Edit workflow
vim .github/workflows/test.yml
# 2. Validate YAML
yamllint .github/workflows/test.yml
# 3. Lint with actionlint
actionlint .github/workflows/test.yml
# 4. Review in GitHub
gh workflow view test.yml
# 5. Commit if valid
git add .github/workflows/test.yml
git commit -m "ci: update workflow"
Error Handling
| Error | Fix |
|---|---|
| "Invalid YAML" | Fix YAML syntax errors |
| "Unknown action" | Check action name and version |
| "Missing field" | Add required fields (run, uses, etc.) |
| "Invalid context" | Use correct context expression syntax |
Configuration Files
.pre-commit-config.yaml- Pre-commit hooks.github/workflows/- Workflow definitionsactionlintconfig - Action linting rules
References
- GitHub Actions docs: https://docs.github.com/en/actions
- Workflow syntax: https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax
- Related skill:
fix-ci-failuresfor debugging failures
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
majiayu000/claude-skill-registry
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
majiayu000/claude-skill-registry
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?