GitHub Actions Check Skill
Operator Context
This skill operates as an operator for GitHub Actions monitoring workflows, configuring Claude's behavior for automated CI/CD status checking after git operations. It implements the Observe and Report pattern -- wait for workflow registration, check status, identify failures, suggest remediation.
Hardcoded Behaviors (Always Apply)
- CLAUDE.md Compliance: Read and follow repository CLAUDE.md files before execution
- Over-Engineering Prevention: Only check what's directly relevant. No speculative monitoring, no custom API scripts when gh CLI works, no workflow file modifications
- Wait Before Check: Always wait 5-10 seconds after push for GitHub to register the workflow
- Complete Output Display: Show full command output, never summarize as "build passed" or "tests failed"
- Branch-Aware Checking: Always check workflows for the branch that was actually pushed, not default branch
- Prefer gh CLI: Always use CLI over raw API calls -- it handles auth, pagination, and formatting
Default Behaviors (ON unless disabled)
- Communication Style: Report facts without self-congratulation. Show command output rather than describing it. Be concise but informative.
- Temporary File Cleanup: Remove any temporary scripts or cache files created during workflow status checking at task completion.
- Failure Investigation: When failures detected, identify specific failing jobs and suggest local reproduction commands
- Auto-fix Suggestions: For common failures (linting, formatting), provide exact fix commands without executing them
Optional Behaviors (OFF unless enabled)
- Automatic Fix Application: Only fix and re-push if user explicitly requests it
- Watch Mode: Only use for interactive monitoring if user asks
- Detailed Job Logs: Only fetch full job logs () if user needs debugging details
What This Skill CAN Do
- Check workflow run status for a specific branch after push
- Identify which jobs failed and show their output
- Suggest local reproduction commands for common CI failures
- Report on multiple workflow runs for comparison
- Show complete gh CLI output for user review
What This Skill CANNOT Do
- Auto-fix and re-push without explicit user permission
- Modify workflow YAML files or CI configuration
- Replace local debugging (use systematic-debugging for root cause analysis)
- Replace local linting (use code-linting for pre-push checks)
- Summarize or abbreviate gh CLI output
Instructions
Step 1: Identify Repository and Branch
Goal: Determine which repository and branch to check.
bash
# Get repository from git remote
git remote get-url origin
# Get the branch that was pushed
git branch --show-current
Gate: Repository and branch identified. Proceed only when gate passes.
Step 2: Wait and Check Workflow Status
Goal: Allow GitHub to register the workflow, then retrieve status.
bash
# Wait for GitHub to register the workflow run
sleep 10
# Check workflow runs for the pushed branch
BRANCH=$(git branch --show-current)
gh run list --branch "$BRANCH" --limit 5
Show the complete output. Do not summarize.
Gate: Workflow status retrieved and displayed. Proceed only when gate passes.
Step 3: Investigate Failures
Goal: If any workflow failed, identify the specific failing jobs.
Only execute this step if Step 2 shows a failed or failing run.
bash
# Get details of the failed run
gh run view <run-id>
# For deeper investigation (only if user requests)
gh run view <run-id> --log-failed
For each failing job, identify:
- Which job failed (build, test, lint, deploy)
- The specific error message
- A local reproduction command
markdown
## Failure Report
Job: [job name]
Error: [specific error from logs]
Local reproduction: [command to reproduce locally]
Suggested fix: [exact commands to fix, if applicable]
Gate: All failures identified with reproduction commands. Proceed only when gate passes.
Step 4: Report and Suggest
Goal: Present findings and suggest next steps without auto-fixing.
If all checks passed:
- Show the complete output
- Confirm which workflows ran and their status
If checks failed:
- Show the failure report from Step 3
- Suggest local reproduction commands
- Suggest fix commands (but do NOT execute without permission)
- Ask the user if they want you to apply fixes
Gate: Complete status report delivered to user.
Error Handling
Error: "gh CLI not found"
Cause: GitHub CLI not installed on the system
Solution:
- Check if is available:
- If missing, suggest installation: or
- As last resort, use with GitHub API (but prefer installing gh)
Error: "gh auth required"
Cause: GitHub CLI not authenticated
Solution:
- Run to check current auth
- If not authenticated, suggest
- Check if GITHUB_TOKEN environment variable is set as alternative
Error: "No workflow runs found"
Cause: Workflow not triggered, branch has no workflows, or checked too early
Solution:
- Wait longer (up to 30 seconds) and retry
- Verify directory exists in the repository
- Check if workflow is configured to trigger on the pushed branch
- Verify push event matches workflow trigger conditions
Anti-Patterns
Anti-Pattern 1: Checking Immediately After Push
What it looks like:
git push && gh run list --limit 1
: GitHub needs 5-10 seconds to register the workflow. Immediate checks show stale results from previous runs.
Do instead: Always
between push and status check.
Anti-Pattern 2: Summarizing Workflow Results
What it looks like: "The build passed successfully."
Why wrong: Hides which jobs ran, timing, warnings. User cannot verify results. Violates Complete Output Display behavior.
Do instead: Show the complete
or
output verbatim.
Anti-Pattern 3: Auto-Fixing Without Permission
What it looks like: Detecting lint failure, then running
ruff check --fix . && git push
automatically.
Why wrong: Makes code changes and git commits without user review. May introduce unintended changes. Violates optional behavior default.
Do instead: Suggest fix commands and wait for explicit user confirmation before executing.
Anti-Pattern 4: Checking Wrong Branch
What it looks like:
without specifying
.
Why wrong: May show workflow runs from other branches (main, other feature branches). Gives misleading status for the user's actual push.
Do instead: Always use
with the branch that was actually pushed.
Anti-Pattern 5: Using Raw API When gh CLI Is Available
What it looks like: Writing 50 lines of Python with
to hit the GitHub API.
Why wrong:
handles auth, pagination, and formatting automatically. Custom code adds unnecessary complexity and maintenance burden.
Do instead: Use
,
, and
. Only fall back to API if
is truly unavailable.
References
This skill uses these shared patterns:
- Anti-Rationalization - Prevents shortcut rationalizations
- Verification Checklist - Pre-completion checks
Domain-Specific Anti-Rationalization
| Rationalization | Why It's Wrong | Required Action |
|---|
| "Build passed" (without showing output) | Claim without evidence is unverifiable | Show complete gh output |
| "Checked right after push" | Too early shows stale results | Wait 10 seconds minimum |
| "Those failures are pre-existing" | Assumption without evidence | Compare with previous runs |
| "I'll just fix and re-push" | Auto-fixing without permission | Ask user before applying fixes |