Reusable CI Auto-Fix Workflow Skill

Reusable CI Auto-Fix Workflow

Generate a reusable GitHub Actions workflow for automated CI failure analysis and remediation.

When to Use This Skill

| Use this skill when... | Use something else when... | |------------------------|---------------------------| | Setting up a reusable auto-fix workflow for multiple repos | Setting up auto-fix for a single repo (/workflow:auto-fix) | | Creating a caller workflow that invokes the reusable template | Fixing a single PR's checks (/git:fix-pr) | | Customizing auto-fix inputs for different project types | Inspecting workflow runs manually (/workflow:inspect) |

Context

Reusable workflow exists: !find .github/workflows -maxdepth 1 -name 'reusable-ci-autofix.yml' -type f
Caller workflow exists: !find .github/workflows -maxdepth 1 -name 'auto-fix.yml' -type f
Current workflows: !find .github/workflows -maxdepth 1 -name '*.yml' -type f
Claude secrets configured: !gh secret list

Parameters

Parse from $ARGUMENTS:

--setup: Create or update the reusable workflow in .github/workflows/reusable-ci-autofix.yml
--caller: Create the caller workflow in .github/workflows/auto-fix.yml
--workflows <names>: Comma-separated workflow names to monitor (for caller; default: auto-detect CI workflows)
--dry-run: Show what would be created without writing files

Execution

Execute this workflow generation process:

Step 1: Detect current state

Check if .github/workflows/reusable-ci-autofix.yml already exists
Check if .github/workflows/auto-fix.yml already exists
List all current workflow files and their name: fields
Check if CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY secret is configured

Step 2: Select workflows to monitor (for caller)

If --workflows provided, use those. Otherwise, auto-detect:

Good candidates:

CI/test workflows (lint, test, build, type-check)
Code quality checks (formatting, style)

Skip:

Release/deploy workflows
Claude-powered workflows (avoid recursive triggers)
Scheduled/audit workflows

Step 3: Generate the reusable workflow

If --setup or reusable workflow is missing, create .github/workflows/reusable-ci-autofix.yml using the template from REFERENCE.md § Reusable Workflow.

Key customization points:

Set the auto_fixable_criteria and not_auto_fixable_criteria defaults to match the project's tech stack
Set the verification_commands default to match the project's linter/formatter commands
Adjust max_turns if needed (default: 50)

Step 4: Generate the caller workflow

If --caller or caller workflow is missing, create .github/workflows/auto-fix.yml using the template from REFERENCE.md § Caller Workflow.

Key customization points:

Set the monitored workflow names in the workflows: list
Configure auto_fixable_criteria override if the project has specific fixable patterns
Configure verification_commands for the project's tools

Step 5: Validate and report

Verify both workflow YAML files are valid
List the monitored workflows
Check that required secrets exist (CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY)
Report any missing prerequisites

Architecture

Caller Workflow                    Reusable Workflow
(.github/workflows/auto-fix.yml)  (.github/workflows/reusable-ci-autofix.yml)

  workflow_run (failure)
  workflow_dispatch (pr_number)
        |
        v
  fan-out (if "all")
        |
        v
  jobs.auto-fix ──calls──────────> on: workflow_call
                                       |
                                       v
                                   Resolve PR branch
                                       |
                                       v
                                   Checkout + Gather context
                                       |
                                       v
                                   Dedup check (max 2 open auto-fix PRs)
                                       |
                                       v
                                   Claude Code Action
                                       |
                                   +---+---+
                                   |       |
                                   v       v
                                 Fixable  Complex
                                   |       |
                                   v       v
                                 Fix PR   Open issue

Safety Guards

| Guard | Purpose | |-------|---------| | !startsWith(commit, 'fix(auto):') | Prevent recursive auto-fix loops | | head_branch != 'main' (caller) | Never auto-fix protected branches | | Max 2 open auto-fix PRs | Prevent PR flooding | | Concurrency group per branch | One auto-fix at a time per branch | | max-turns limit | Cap Claude's iteration count | | timeout-minutes: 30 | Prevent runaway jobs |

Prerequisites

| Requirement | How to set up | |-------------|---------------| | CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY | Repository or org secret | | contents: write | Included in workflow permissions | | pull-requests: write | Included in workflow permissions | | issues: write | For creating issues on complex failures |

Agentic Optimizations

| Context | Command | |---------|---------| | Check workflow exists | test -f .github/workflows/reusable-ci-autofix.yml | | List CI workflows | grep -h '^name:' .github/workflows/*.yml | | Check secrets | gh secret list | | Recent failures | gh run list --status failure --json name,headBranch -L 10 | | Validate YAML | python3 -c "import yaml; yaml.safe_load(open('.github/workflows/reusable-ci-autofix.yml'))" |

Agent Skills: Reusable CI Auto-Fix Workflow

Install this agent skill to your local

Skill Files