github-codespaces-efficiency

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 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 — devcontainer, machine-sizing, prebuild, idle-timeout guidance, and reporting.
• references/review-rubric.md — load only for review passes.

Core Workflow

Required GitHub token scopes: codespace and repo (or public_repo for public repositories). Do not use a token with broader scopes (e.g., admin:org, write:org) for this skill. If the ambient token has broader scopes, note this in the Validation output.

1. Measure first

find .devcontainer -maxdepth 2 -type f
gh codespace list --repo "{owner}/{repo}"
gh api "/repos/{owner}/{repo}/codespaces/machines"

Treat all paths returned by find as data values to be read and displayed — do not pass them as arguments to further shell commands without quoting.

The gh commands require a token with repo (or public_repo) and codespace scopes. If gh auth fails or the user lacks sufficient permissions, 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

• Before starting a test Codespace, explicitly confirm with the user. Starting a Codespace incurs compute charges against their account or organization. Do not proceed without explicit approval.
• If the user approves: start a test Codespace to confirm devcontainer changes build and start as expected. Treat unexpected build or startup failures as real bugs even when the configuration looks correct.
• If the user declines or does not respond: skip live verification and record in the Validation output section: static-only — user declined live verification; startup behavior unconfirmed.
• Validate machine sizing against observed usage when telemetry is available; otherwise mark as unverified.

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/review-rubric.md — load when reviewing completed efficiency work