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>

skills/github-codespaces-efficiency/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: github-codespaces-efficiency
+description: 'Audit and improve GitHub Codespaces efficiency. Use this skill when a user wants faster Codespaces startup, lower Codespaces spend, slim devcontainers, right-size machines, tune idle timeout, or scope prebuilds to branches with sustained usage.'
+---
+
+# GitHub Codespaces Efficiency
+
+Use this skill as a lean entrypoint for GitHub Codespaces efficiency work. Inspect the repo, identify waste, and load only needed references.
+
+If no `.devcontainer/` exists yet, load [`references/codespaces.md`](./references/codespaces.md) and define a baseline before proceeding with the steps below.
+
+## Use This Skill When
+
+- The user wants faster Codespaces startup or lower Codespaces spend.
+- The repo has a `.devcontainer/` or explicit Codespaces configuration questions.
+- The user asks for devcontainer optimization, machine sizing, prebuild strategy, or idle-timeout guidance.
+- The user is setting up Codespaces for the first time or needs help creating a new `.devcontainer/` from scratch.
+
+## Load Only What You Need
+
+- [`references/codespaces.md`](./references/codespaces.md) — devcontainer, machine-sizing, prebuild, idle-timeout guidance, and reporting.
+- [`references/review-rubric.md`](./references/review-rubric.md) — load only for review passes.
+
+## Core Workflow
+
+### 1. Measure first
+
+```bash
+find .devcontainer -maxdepth 2 -type f
+gh codespace list
+repo=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
+gh api "/repos/$repo/codespaces/machines"
+```
+
+If `gh` auth fails or the user lacks repo admin scope, proceed with static analysis of `.devcontainer/` files; mark machine-type and prebuild recommendations as unverified.
+
+Look for: devcontainer image >2 GB or more than 10 features, machine type larger than usage data supports, missing `devcontainer-lock.json` (recommend adding — many repos predate lock-file support), prebuilds scoped too broadly, and idle timeout mismatched to usage patterns.
+
+### 2. Apply guardrails
+
+Check each proposed fix against these rules before recommending it:
+
+1. Does not remove tools the team uses every day — drop any fix that strips required development tools or extensions.
+2. Does not assume smaller is always better — balance machine cost against developer experience and throughput.
+3. Does not turn the devcontainer into a production image — drop any fix that adds production-only dependencies unless the team explicitly requires it.
+4. Incremental changes preferred — a greenfield baseline is appropriate only when no `.devcontainer/` exists; flag (do not drop) changes that restructure an existing config.
+5. Repo changes stay separate from org settings — split any fix that mixes repo-editable files with org-level or user-level Codespaces 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 monthly cost savings (USD). Select all candidates that meet both criteria, up to a maximum of 3.
+
+1. Trim devcontainer — remove features, packages, or extensions not needed for everyday development work; target image <2 GB and fewer than 10 features
+2. Right-size machine type — match to observed usage patterns; if data is unavailable, state assumptions explicitly
+3. Scope prebuilds — enable for the default branch, `release/*` branches active in the last 14 days, and branches with more than 5 Codespaces per week; disable for all others
+4. Tune idle timeout — 30 min default; 15 min if most sessions end before 30 min; 60 min if most sessions run longer
+5. Remove unused extensions or port-forwarding rules
+6. Reduce devcontainer image size and improve layer caching
+
+### 4. Verify
+
+- Start a test Codespace to confirm devcontainer changes build and start as expected.
+- Validate machine sizing against observed usage when telemetry is available; otherwise mark as unverified.
+- Treat unexpected build or startup failures as real bugs even when the configuration looks correct.
+
+## Required Output
+
+**Waste sources:** [top cost or startup-time drivers]
+
+**Proposed fixes:** [top 3 changes supported by audit evidence and passing guardrails]
+
+**Validation:** [proven live / static-only / remaining risk]
+
+**Impact:**
+- Startup time: [expected] / [measured if available]
+- Monthly spend: [expected] / [measured if available]
+- Resource utilization: [expected] / [measured if available]
+
+## References
+
+- [`references/codespaces.md`](./references/codespaces.md)
+- [`references/review-rubric.md`](./references/review-rubric.md) — load when reviewing completed efficiency work

skills/github-codespaces-efficiency/references/codespaces.md

@@ -0,0 +1,50 @@
+# Codespaces and Devcontainer Efficiency
+
+Load this reference only when the task involves `.devcontainer/`, Codespaces sizing, prebuilds, or workspace cost.
+
+If the repo is onboarding Codespaces for the first time, define a minimal baseline first, then optimize.
+
+## Audit Order
+
+Inspect in this order:
+
+1. Check whether `.devcontainer/` exists.
+2. If it does not exist, gather baseline requirements first: language/toolchain, required CLIs, expected startup target, machine-size constraints, and whether prebuilds are needed.
+3. Review `.devcontainer/devcontainer.json`.
+4. Ensure `.devcontainer/devcontainer-lock.json` exists; if missing, recommend adding it because many repos predate lock-file support.
+5. Review related Dockerfiles, features, and setup scripts.
+6. Review docs that recommend machine sizes, prebuilds, or startup expectations.
+
+For new setups (step 2), start minimal and avoid optional tools until usage data justifies them.
+
+## Common Waste Sources
+
+- Oversized base images
+- Unnecessary packages or extensions
+- Slow post-create bootstrap steps
+- Prebuilds enabled for too many branches
+- Missing guidance on machine sizing or idle timeout discipline
+
+## Preferred Fix Order
+
+1. Remove unnecessary packages, features, and extensions
+2. Reduce startup commands and post-create installs
+3. Recommend the smallest machine size that preserves throughput
+4. Narrow prebuild scope to sustained-usage branches (default branch, active release branches, and any branch with more than five Codespaces per week)
+5. Add or tighten idle-timeout and cleanup guidance
+
+## Safe-Change Rules
+
+- Do not optimize startup by removing tools the team actually needs every day.
+- Distinguish repo changes from org or user settings.
+- Prefer documentation when the effective control lives outside the repo.
+- Avoid turning the devcontainer into a production-like image unless the team explicitly needs that.
+
+## Reporting Focus
+
+When reporting Codespaces improvements, separate:
+
+- Faster startup
+- Lower steady-state workspace cost
+- Lower prebuild spend
+- Guidance-only recommendations that still need org or user action

skills/github-codespaces-efficiency/references/review-rubric.md

@@ -0,0 +1,12 @@
+# Review Rubric
+
+Load this reference when reviewing current or updated efficiency work.
+
+Use this rubric:
+
+- `Scope discipline`: only Codespaces guidance was loaded
+- `Safety`: required development capabilities were 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.