2 new efficiency skills to reduce cost and wasted cpu cycles in github actions and codespaces (#1766)

* fresh pull of updated stage with 2 skills and updated README only * adjusted skills after feedback and used skill analyser to review --------- Co-authored-by: Mark Heynes <mutl3y@heynes.biz>
2026-05-28 01:21:46 +00:00 · 2026-05-25 02:05:10 +01:00
parent 1d7582717e
commit 12666c97ee
9 changed files with 416 additions and 0 deletions
@@ -0,0 +1,79 @@
+---
+name: github-actions-efficiency
+description: 'Audit GitHub Actions workflow efficiency and recommend fixes to reduce CI minutes and costs.'
+---
+
+# GitHub Actions Efficiency
+
+Use this skill as a lean entrypoint for GitHub Actions efficiency work. Inspect the repo, identify the waste source, and load only the reference material needed for the current task.
+
+If no workflows exist yet, load [`references/actions.md`](./references/actions.md) and define a baseline before proceeding with the steps below.
+
+**If shell or `gh` CLI access is unavailable:** ask the user to paste `.github/workflows/` contents and `gh run list --limit 10` output. If only partial files are provided, note it: "Audit based on provided files only; some insights may be incomplete." Begin responses from files alone with: "**Static-only analysis** (not confirmed with live runs)."
+
+## Use This Skill When
+
+- The user wants to reduce GitHub Actions runtime, CI cost, or wasted workflow runs.
+- The repo has existing workflows in `.github/workflows/` or explicit GitHub Actions configuration questions.
+- The user asks for caching, concurrency, path filters, matrix reduction, job optimization, or workflow-specific fixes.
+- The user needs help creating a new GitHub Actions workflow or CI baseline from scratch.
+
+## Load Only What You Need
+
+- [`references/actions.md`](./references/actions.md) — audits, job gating, matrix reduction, live validation, and workflow-specific fixes.
+- [`references/reporting.md`](./references/reporting.md) — when the user asks for a before/after efficiency report.
+- [`references/patterns.md`](./references/patterns.md) — full YAML examples when inline audit commands are not enough.
+
+## Core Workflow
+
+### 1. Measure first
+
+```bash
+rg -n "on:|concurrency:|paths:|paths-ignore:|strategy:|matrix:|cache:" .github/workflows
+gh run list --limit 10
+run_id=$(gh run list --limit 1 --json databaseId --jq '.[0].databaseId')
+gh run view "$run_id" --log-failed
+```
+
+Look for: missing dependency caches, missing `concurrency` cancellation, over-broad triggers, duplicate workflow coverage, and expensive jobs that run on every change regardless of scope.
+
+### 2. Apply guardrails
+
+Check each proposed fix against these rules before recommending it:
+
+1. Does not hide required validation — drop any fix that removes release, schema, migration, or shared-library checks.
+2. Does not reduce parallelism without justification — drop unless the user prioritised cost over latency *and* the new critical path stays within 1.25× the original.
+3. Preserves only documented matrix legs — drop matrix legs with no explicit version or platform commitment.
+4. Write-back jobs use opt-in triggers — flag (do not drop) formatter or bot jobs that run automatically; recommend an opt-in trigger instead.
+5. Repo changes stay separate from org settings — split any fix that mixes repo-editable YAML with org-level or GitHub-account settings into two distinct recommendations.
+
+### 3. Select the top 3 fixes
+
+From the six candidates below, keep only those supported by audit evidence from step 1 *and* passing all guardrails from step 2. Rank survivors by estimated daily CI minutes saved (per-run savings × runs per day). Select all candidates that meet both criteria, up to a maximum of 3.
+
+1. Add dependency caching with lockfile-based keys
+2. Add or correct `concurrency` cancellation
+3. Remove duplicate workflow coverage before merging jobs
+4. Narrow workflow or job triggers safely
+5. Reduce matrix breadth to match risk and event type
+6. Parallelize independent jobs on the critical path
+
+### 4. Verify
+
+- If `gh` CLI access is available, validate path-gating and concurrency cancellation with a live test push on a non-protected branch.
+- If live validation is not possible, state that explicitly in the output.
+- Treat unexpected live behavior as a real bug even when the YAML looks correct.
+
+## Required Output
+
+1. **Waste sources** — top cost or latency drivers found in step 1
+2. **Proposed fixes** — top 3 (or all remaining) with supporting audit evidence
+3. **Validation** — what was proven live, what was checked locally only, and any remaining risk
+4. **Impact** — expected savings vs. measured savings; separate PR wall-clock time from total runner time
+
+## References
+
+- [`references/actions.md`](./references/actions.md)
+- [`references/reporting.md`](./references/reporting.md)
+- [`references/patterns.md`](./references/patterns.md)
+- [`references/review-rubric.md`](./references/review-rubric.md) — load when reviewing completed efficiency work
@@ -0,0 +1,77 @@
+# GitHub Actions Efficiency
+
+Load this reference only when the task involves GitHub Actions or CI workflow efficiency.
+
+If the repo is onboarding GitHub Actions for the first time, define a minimal baseline workflow first, then optimize using the rest of this guide.
+
+## Audit Order
+
+Inspect in this order:
+
+1. If `.github/workflows/` is missing or empty, gather baseline requirements first: triggering events, required checks, runtime versions, and repository-specific validation policy.
+2. `.github/workflows/*.yml`
+3. Docs describing CI expectations
+4. Existing reports or run history if the user wants measured impact
+
+For new setups, start with a small workflow that proves core checks, then add matrix breadth or additional jobs only when needed.
+
+Start with common, low-risk waste:
+
+1. Missing dependency caches
+2. Missing `concurrency` cancellation
+3. Over-broad workflow triggers
+4. Duplicate workflow coverage across files or jobs
+5. Expensive jobs that run on every change regardless of scope
+
+## Actions-Specific Guidance
+
+### Trigger scoping
+
+- Use `paths` or `paths-ignore` when whole workflows truly should not run for some file classes.
+- Use job-level gating when event-level filters are too coarse.
+- Prefer explicit changed-file detection when reliability matters more than clever filter expressions.
+
+### Job shaping
+
+- Do not merge jobs blindly. If separate jobs preserve parallelism and shorten the critical path, keep them separate.
+- Keep lightweight coordination or change-detection jobs separate from heavy execution jobs when that makes skip behavior obvious.
+- If a workflow-only change still runs the full suite, treat that as evidence the gating model is too broad.
+
+### Matrix reduction
+
+Match matrix breadth to the decision being made:
+
+- Full matrix for releases or explicit compatibility validation
+- Reduced compatibility matrix for runtime, plugin, packaging, or framework-integration changes
+- Single representative latest-version leg for ordinary code changes
+- No heavy test job for clearly non-runtime changes when lighter protection already exists
+
+### Optional maintenance jobs
+
+Formatting or autofix jobs that write back to a branch are often better as opt-in jobs.
+
+Good triggers:
+
+- PR label such as `ci:format`
+- Manual dispatch
+- Explicit comment-command flow if the repo already supports it
+
+If you use a label trigger, remember to listen for PR `labeled` and usually `unlabeled` events or the label change will not reevaluate the job.
+
+## Safe-Change Rules
+
+- Do not hide required release, migration, or shared-library validation.
+- Do not widen changed-file scope accidentally when replacing a wrapper action.
+- Treat severity drift as a regression risk.
+- Match the real check surface before replacing a broad action with native tools.
+
+## Live Validation
+
+Prefer live GitHub validation when possible:
+
+- Trigger `workflow_dispatch` workflows once
+- Verify stale-run cancellation with two quick updates
+- Verify path-gating with an incremental ignored-only or workflow-only change on an existing branch
+- Confirm heavy jobs skip in the UI instead of assuming they would
+
+Do not treat the first push on a brand-new branch as a clean path-ignore test.
@@ -0,0 +1,60 @@
+# Canonical Patterns
+
+Load this reference only when you need concrete examples during implementation.
+
+## Dependency Cache
+
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.npm
+    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+    restore-keys: |
+      ${{ runner.os }}-node-
+```
+
+Adapt the cache path and invalidation file to the repo's ecosystem.
+
+## Cancel Stale Runs
+
+```yaml
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+```
+
+## Scope Triggers
+
+```yaml
+on:
+  push:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "package.json"
+```
+
+Use `paths-ignore` when exclusion is easier to maintain than inclusion.
+
+## Job-Level Changed-File Gating
+
+Use a small change-detection step that emits explicit outputs such as:
+
+- `docs_relevant`
+- `runtime_relevant`
+- `compat_relevant`
+- `run_tests`
+
+Gate downstream jobs on those outputs when event-level filters are not expressive enough.
+
+## Matrix Reduction
+
+Use the minimum matrix that matches the decision:
+
+- Full matrix on release
+- Reduced compatibility matrix on sensitive runtime surfaces
+- Single representative leg for ordinary code changes
+
+## Optional Write-Back Job
+
+Use label-driven or manual triggers for jobs that mutate the PR branch, such as formatting bots.
@@ -0,0 +1,42 @@
+# Efficiency Reporting and Follow-Up Review
+
+Load this reference when the user asks what changed, wants a before/after report, or asks for another pass over remaining expensive jobs.
+
+## Reporting Rules
+
+- Separate expected savings from measured savings.
+- Do not claim exact time or cost savings without before/after run data.
+- Call out confounders such as cache warm-up, changed matrix breadth, runner changes, or unusually small PRs.
+
+Use this phrasing when data is incomplete:
+
+`I can report the efficiency mechanisms that changed, but I cannot honestly claim exact minutes saved without comparing before/after GitHub Actions runs.`
+
+## What To Measure
+
+Gather:
+
+1. A baseline sample before the change
+2. A post-change sample after caches warm
+3. Per-workflow or per-job duration comparisons
+4. Avoided runs, skipped jobs, or avoided matrix legs
+
+Always separate:
+
+- PR wall-clock time
+- Total runner time across jobs
+- Work avoided entirely
+
+These answer different questions. A change can reduce runner spend without materially improving the fastest feedback path.
+
+## Follow-Up Review Pass
+
+After the first round of fixes is validated, inspect the remaining expensive jobs:
+
+- Compare setup time versus execution time
+- Identify heavyweight wrapper actions and confirm what they really enforce
+- Review whether each matrix dimension still serves an active decision
+- Recheck after caches warm
+- Break down the dominant slow step before proposing further changes
+
+Keep the follow-up compact. Report the next few highest-value opportunities, not a long wishlist.
@@ -0,0 +1,12 @@
+# Review Rubric
+
+Load this reference when reviewing current or updated efficiency work.
+
+Use this rubric:
+
+- `Scope discipline`: only GitHub Actions guidance was loaded
+- `Safety`: required validation coverage was preserved
+- `Token efficiency`: the skill or report stayed focused on the active task
+- `Measurement quality`: expected and measured gains were clearly separated
+
+If one rubric dimension is weak, call that out explicitly instead of averaging it away.