diff --git a/docs/README.skills.md b/docs/README.skills.md index 96d0c1677..08d035696 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -176,6 +176,8 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [geofeed-tuner](../skills/geofeed-tuner/SKILL.md)
`gh skills install github/awesome-copilot geofeed-tuner` | Use this skill whenever the user mentions IP geolocation feeds, RFC 8805, geofeeds, or wants help creating, tuning, validating, or publishing a self-published IP geolocation feed in CSV format. Intended user audience is a network operator, ISP, mobile carrier, cloud provider, hosting company, IXP, or satellite provider asking about IP geolocation accuracy, or geofeed authoring best practices. Helps create, refine, and improve CSV-format IP geolocation feeds with opinionated recommendations beyond RFC 8805 compliance. Do NOT use for private or internal IP address management — applies only to publicly routable IP addresses. | `assets/example`
`assets/iso3166-1.json`
`assets/iso3166-2.json`
`assets/small-territories.json`
`references/rfc8805.txt`
`references/snippets-python3.md`
`scripts/templates` | | [git-commit](../skills/git-commit/SKILL.md)
`gh skills install github/awesome-copilot git-commit` | Execute git commit with conventional commit message analysis, intelligent staging, and message generation. Use when user asks to commit changes, create a git commit, or mentions "/commit". Supports: (1) Auto-detecting type and scope from changes, (2) Generating conventional commit messages from diff, (3) Interactive commit with optional type/scope/description overrides, (4) Intelligent file staging for logical grouping | None | | [git-flow-branch-creator](../skills/git-flow-branch-creator/SKILL.md)
`gh skills install github/awesome-copilot git-flow-branch-creator` | Intelligent Git Flow branch creator that analyzes git status/diff and creates appropriate branches following the nvie Git Flow branching model. | None | +| [github-actions-efficiency](../skills/github-actions-efficiency/SKILL.md)
`gh skills install github/awesome-copilot github-actions-efficiency` | Audit GitHub Actions workflow efficiency and recommend fixes to reduce CI minutes and costs. | `references/actions.md`
`references/patterns.md`
`references/reporting.md`
`references/review-rubric.md` | +| [github-codespaces-efficiency](../skills/github-codespaces-efficiency/SKILL.md)
`gh skills install github/awesome-copilot github-codespaces-efficiency` | 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. | `references/codespaces.md`
`references/review-rubric.md` | | [github-copilot-starter](../skills/github-copilot-starter/SKILL.md)
`gh skills install github/awesome-copilot github-copilot-starter` | Set up complete GitHub Copilot configuration for a new project based on technology stack | None | | [github-issues](../skills/github-issues/SKILL.md)
`gh skills install github/awesome-copilot github-issues` | Create, update, and manage GitHub issues using MCP tools. Use this skill when users want to create bug reports, feature requests, or task issues, update existing issues, add labels/assignees/milestones, set issue fields (dates, priority, custom fields), set issue types, manage issue workflows, link issues, add dependencies, or track blocked-by/blocking relationships. Triggers on requests like "create an issue", "file a bug", "request a feature", "update issue X", "set the priority", "set the start date", "link issues", "add dependency", "blocked by", "blocking", or any GitHub issue management task. | `references/dependencies.md`
`references/images.md`
`references/issue-fields.md`
`references/issue-types.md`
`references/projects.md`
`references/search.md`
`references/sub-issues.md`
`references/templates.md` | | [github-release](../skills/github-release/SKILL.md)
`gh skills install github/awesome-copilot github-release` | Guides IA through releasing a new version of a GitHub library end-to-end. Handles SemVer versioning and Keep a Changelog formatting automatically. | `references/commit-classification.md`
`references/semver-rules.md` | diff --git a/skills/github-actions-efficiency/SKILL.md b/skills/github-actions-efficiency/SKILL.md new file mode 100644 index 000000000..e63a2bad1 --- /dev/null +++ b/skills/github-actions-efficiency/SKILL.md @@ -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 diff --git a/skills/github-actions-efficiency/references/actions.md b/skills/github-actions-efficiency/references/actions.md new file mode 100644 index 000000000..c63039035 --- /dev/null +++ b/skills/github-actions-efficiency/references/actions.md @@ -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. diff --git a/skills/github-actions-efficiency/references/patterns.md b/skills/github-actions-efficiency/references/patterns.md new file mode 100644 index 000000000..c030717ba --- /dev/null +++ b/skills/github-actions-efficiency/references/patterns.md @@ -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. diff --git a/skills/github-actions-efficiency/references/reporting.md b/skills/github-actions-efficiency/references/reporting.md new file mode 100644 index 000000000..de78b8faf --- /dev/null +++ b/skills/github-actions-efficiency/references/reporting.md @@ -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. diff --git a/skills/github-actions-efficiency/references/review-rubric.md b/skills/github-actions-efficiency/references/review-rubric.md new file mode 100644 index 000000000..a086e212b --- /dev/null +++ b/skills/github-actions-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 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. diff --git a/skills/github-codespaces-efficiency/SKILL.md b/skills/github-codespaces-efficiency/SKILL.md new file mode 100644 index 000000000..0e5e38999 --- /dev/null +++ b/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 diff --git a/skills/github-codespaces-efficiency/references/codespaces.md b/skills/github-codespaces-efficiency/references/codespaces.md new file mode 100644 index 000000000..df29ebb39 --- /dev/null +++ b/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 diff --git a/skills/github-codespaces-efficiency/references/review-rubric.md b/skills/github-codespaces-efficiency/references/review-rubric.md new file mode 100644 index 000000000..175f64427 --- /dev/null +++ b/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.