{"owner":"actions","repo":"runner-images","hasSkills":true,"totalSkillsCount":1,"totalTokensCount":1842,"categories":["copilot-instructions"],"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md"],"skills":{".github/copilot-instructions.md":"# GitHub Copilot Instructions for Actions Runner Images Repository\n\n## Scope and goals\n\n- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [Available Images](../README.md#available-images) section of README.md. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization.\n- Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette.\n- Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing.\n\n## Architecture overview\n\n- **What this repo builds:** the source used to generate the VM images for [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) (Actions) and Microsoft-hosted agents (Azure Pipelines). See [README.md](../README.md#about).\n- **Platforms and labels:** Ubuntu, Windows, and macOS across multiple versions and architectures (x64/arm64). See [Available Images](../README.md#available-images) for the supported YAML labels.\n- **Build systems:**\n  - Windows and Ubuntu images are built with [Packer](https://www.packer.io/) (HCL2 templates) on **Azure**.\n  - macOS images are also Packer (HCL2), but use the **Anka** builder (`*.anka.pkr.hcl`) for virtualization instead of Azure; macOS CI does not accept external contributions yet (see [CONTRIBUTING.md](../CONTRIBUTING.md#macos)).\n- **Build flow:** a Packer template provisions a temporary Azure VM, runs install scripts in order, runs validation tests, captures a managed image, then generates the image's software report. A failed step aborts the build and cleans up resources. Details: [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md).\n\n## Repository map\n\n| Path | What lives here |\n| --- | --- |\n| `images/<os>/` | Per-image sources, where `<os>` is a Packer-built VM image: `ubuntu`, `windows`, or `macos`. (`ubuntu-slim` is Docker-based with a different layout — see its own row.) |\n| `images/<os>/templates/` | Packer (HCL2) templates. |\n| `images/<os>/toolsets/toolset-*.json` | Declarative tool/version pinning (validated by `schemas/toolset-schema.json`). |\n| `images/<os>/scripts/build/` | Install scripts that run during image generation. |\n| `images/<os>/scripts/tests/` | [Pester v5](https://github.com/pester/pester) validation scripts (`*.Tests.ps1`). |\n| `images/<os>/scripts/helpers/` | Shared install/validation helpers (e.g. Ubuntu `install.sh`, Windows `ImageHelpers.psm1`). |\n| `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1` | Generates the image's `*-Readme.md` software list. |\n| `images/ubuntu-slim/` | Docker-based slim image: `Dockerfile`, `test.sh`, and `generate-software-report.sh`, plus `scripts/build`, `scripts/helpers`, and `toolsets/` (no Packer template or Pester `scripts/tests`). |\n| `helpers/` | Repo-level orchestration scripts (e.g. `GenerateResourcesAndImage.ps1`). |\n| `docs/` | Build and topic docs (start with `create-image-and-azure-resources.md`). |\n| `schemas/` | JSON schema for toolset files. |\n| `.github/workflows/` | CI: per-image builds, linting, tests, and schema/version checks. |\n| `.vscode/` | Recommended extensions and editor settings for contributors. |\n\n## Key workflows\n\n- **Adding or updating a tool** (the most common change) requires, together:\n  1. an install script in `images/<os>/scripts/build/` (reuse existing helpers),\n  2. a Pester validation test in `images/<os>/scripts/tests/`, registered from the install script — `invoke_tests \"<TestFile>\" \"<TestName>\"` in Bash scripts (Ubuntu/macOS) or `Invoke-PesterTests -TestFile \"<name>\"` in PowerShell scripts (Windows),\n  3. an update to `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1`, and\n  4. version entries in the relevant `toolsets/toolset-*.json` when the tool is versioned.\n\n  Open an issue and get approval before adding a new tool. Full guide: [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-new-tool-to-an-image).\n- **Building or testing an image:** follow [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md); validation runs through Pester.\n- **CI:** workflows in `.github/workflows/` (per-image builds, `linter.yml`, `powershell-tests.yml`, `check-pinned-versions.yml`, `validate-json-schema.yml`).\n- **Submitting changes:** fork, branch, make the change, validate, then open a focused pull request. See [CONTRIBUTING.md](../CONTRIBUTING.md#submitting-a-pull-request) and `.github/pull_request_template.md`.\n- **Good practices from real contributions:** keep install scripts thin and reuse existing helpers instead of re-implementing version resolution or download logic; prefer surgical compatibility fixes over broader runtime changes; register validation tests from the install script so the build proves the change on a real VM; fail fast when versions or assets cannot be resolved; and only add software-report or toolset entries when they are truly applicable to the tool's packaging and versioning model.\n\n## Onboarding new contributors\n\n- For a guided, interactive introduction to this repository, use the **`onboarding` skill** (`.github/skills/onboarding/`). Trigger it with phrases like \"Start onboarding\", \"give me a tour\", or \"help me get started\".\n- The skill walks newcomers through the architecture, repository map, and the add-a-tool workflow step by step (pausing for checkpoints), and also supports free exploration.\n\n## Code and command instructions\n\n- Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules.\n- Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation.\n- Keep tests simple, non-mutating, and aligned with the real install behavior; they should verify the tool works on the VM instead of asserting on mocks or synthetic state.\n- Always confirm versions and installation paths against existing toolset files and installation scripts.\n- When a change is non-obvious, leave a short comment or link to the issue explaining the compatibility rationale, especially for temporary pins or platform-specific workarounds.\n\n## Output format\n\n- Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary.\n- One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …).\n- Use fenced code blocks with language identifiers (` ```bash `, ` ```json `, ` ```yaml `, etc.).\n- Use blockquote callouts for notes:\n  > [!NOTE] Context or nuance  \n  > [!TIP] Helpful hint  \n  > [!WARNING] Risks or breaking changes  \n  > [!IMPORTANT] Critical requirement for functionality\n\n## Style and tone\n\n- Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant.\n- Voice: Second person (\"you\"), active voice, imperative for operational steps.\n- Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting.\n- Use inclusive, accessible language. Avoid idioms, sarcasm, and culturally specific references.\n- English: en-US (spelling, punctuation, and units).\n\n## Safety and integrity\n\n- Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples.\n- Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts.\n- Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability.\n- If ambiguous requests are made about image modifications, ask clarifying questions about target OS, tool versions, and compatibility requirements before proceeding.\n"},"files":{".github/copilot-instructions.md":"# GitHub Copilot Instructions for Actions Runner Images Repository\n\n## Scope and goals\n\n- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [Available Images](../README.md#available-images) section of README.md. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization.\n- Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette.\n- Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing.\n\n## Architecture overview\n\n- **What this repo builds:** the source used to generate the VM images for [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) (Actions) and Microsoft-hosted agents (Azure Pipelines). See [README.md](../README.md#about).\n- **Platforms and labels:** Ubuntu, Windows, and macOS across multiple versions and architectures (x64/arm64). See [Available Images](../README.md#available-images) for the supported YAML labels.\n- **Build systems:**\n  - Windows and Ubuntu images are built with [Packer](https://www.packer.io/) (HCL2 templates) on **Azure**.\n  - macOS images are also Packer (HCL2), but use the **Anka** builder (`*.anka.pkr.hcl`) for virtualization instead of Azure; macOS CI does not accept external contributions yet (see [CONTRIBUTING.md](../CONTRIBUTING.md#macos)).\n- **Build flow:** a Packer template provisions a temporary Azure VM, runs install scripts in order, runs validation tests, captures a managed image, then generates the image's software report. A failed step aborts the build and cleans up resources. Details: [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md).\n\n## Repository map\n\n| Path | What lives here |\n| --- | --- |\n| `images/<os>/` | Per-image sources, where `<os>` is a Packer-built VM image: `ubuntu`, `windows`, or `macos`. (`ubuntu-slim` is Docker-based with a different layout — see its own row.) |\n| `images/<os>/templates/` | Packer (HCL2) templates. |\n| `images/<os>/toolsets/toolset-*.json` | Declarative tool/version pinning (validated by `schemas/toolset-schema.json`). |\n| `images/<os>/scripts/build/` | Install scripts that run during image generation. |\n| `images/<os>/scripts/tests/` | [Pester v5](https://github.com/pester/pester) validation scripts (`*.Tests.ps1`). |\n| `images/<os>/scripts/helpers/` | Shared install/validation helpers (e.g. Ubuntu `install.sh`, Windows `ImageHelpers.psm1`). |\n| `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1` | Generates the image's `*-Readme.md` software list. |\n| `images/ubuntu-slim/` | Docker-based slim image: `Dockerfile`, `test.sh`, and `generate-software-report.sh`, plus `scripts/build`, `scripts/helpers`, and `toolsets/` (no Packer template or Pester `scripts/tests`). |\n| `helpers/` | Repo-level orchestration scripts (e.g. `GenerateResourcesAndImage.ps1`). |\n| `docs/` | Build and topic docs (start with `create-image-and-azure-resources.md`). |\n| `schemas/` | JSON schema for toolset files. |\n| `.github/workflows/` | CI: per-image builds, linting, tests, and schema/version checks. |\n| `.vscode/` | Recommended extensions and editor settings for contributors. |\n\n## Key workflows\n\n- **Adding or updating a tool** (the most common change) requires, together:\n  1. an install script in `images/<os>/scripts/build/` (reuse existing helpers),\n  2. a Pester validation test in `images/<os>/scripts/tests/`, registered from the install script — `invoke_tests \"<TestFile>\" \"<TestName>\"` in Bash scripts (Ubuntu/macOS) or `Invoke-PesterTests -TestFile \"<name>\"` in PowerShell scripts (Windows),\n  3. an update to `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1`, and\n  4. version entries in the relevant `toolsets/toolset-*.json` when the tool is versioned.\n\n  Open an issue and get approval before adding a new tool. Full guide: [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-new-tool-to-an-image).\n- **Building or testing an image:** follow [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md); validation runs through Pester.\n- **CI:** workflows in `.github/workflows/` (per-image builds, `linter.yml`, `powershell-tests.yml`, `check-pinned-versions.yml`, `validate-json-schema.yml`).\n- **Submitting changes:** fork, branch, make the change, validate, then open a focused pull request. See [CONTRIBUTING.md](../CONTRIBUTING.md#submitting-a-pull-request) and `.github/pull_request_template.md`.\n- **Good practices from real contributions:** keep install scripts thin and reuse existing helpers instead of re-implementing version resolution or download logic; prefer surgical compatibility fixes over broader runtime changes; register validation tests from the install script so the build proves the change on a real VM; fail fast when versions or assets cannot be resolved; and only add software-report or toolset entries when they are truly applicable to the tool's packaging and versioning model.\n\n## Onboarding new contributors\n\n- For a guided, interactive introduction to this repository, use the **`onboarding` skill** (`.github/skills/onboarding/`). Trigger it with phrases like \"Start onboarding\", \"give me a tour\", or \"help me get started\".\n- The skill walks newcomers through the architecture, repository map, and the add-a-tool workflow step by step (pausing for checkpoints), and also supports free exploration.\n\n## Code and command instructions\n\n- Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules.\n- Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation.\n- Keep tests simple, non-mutating, and aligned with the real install behavior; they should verify the tool works on the VM instead of asserting on mocks or synthetic state.\n- Always confirm versions and installation paths against existing toolset files and installation scripts.\n- When a change is non-obvious, leave a short comment or link to the issue explaining the compatibility rationale, especially for temporary pins or platform-specific workarounds.\n\n## Output format\n\n- Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary.\n- One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …).\n- Use fenced code blocks with language identifiers (` ```bash `, ` ```json `, ` ```yaml `, etc.).\n- Use blockquote callouts for notes:\n  > [!NOTE] Context or nuance  \n  > [!TIP] Helpful hint  \n  > [!WARNING] Risks or breaking changes  \n  > [!IMPORTANT] Critical requirement for functionality\n\n## Style and tone\n\n- Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant.\n- Voice: Second person (\"you\"), active voice, imperative for operational steps.\n- Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting.\n- Use inclusive, accessible language. Avoid idioms, sarcasm, and culturally specific references.\n- English: en-US (spelling, punctuation, and units).\n\n## Safety and integrity\n\n- Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples.\n- Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts.\n- Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability.\n- If ambiguous requests are made about image modifications, ask clarifying questions about target OS, tool versions, and compatibility requirements before proceeding.\n"},"items":[{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","rawUrl":"https://raw.githubusercontent.com/actions/runner-images/HEAD/.github/copilot-instructions.md","title":"GitHub Copilot Instructions","category":"copilot-instructions","format":"markdown","content":"# GitHub Copilot Instructions for Actions Runner Images Repository\n\n## Scope and goals\n\n- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [Available Images](../README.md#available-images) section of README.md. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization.\n- Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette.\n- Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing.\n\n## Architecture overview\n\n- **What this repo builds:** the source used to generate the VM images for [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) (Actions) and Microsoft-hosted agents (Azure Pipelines). See [README.md](../README.md#about).\n- **Platforms and labels:** Ubuntu, Windows, and macOS across multiple versions and architectures (x64/arm64). See [Available Images](../README.md#available-images) for the supported YAML labels.\n- **Build systems:**\n  - Windows and Ubuntu images are built with [Packer](https://www.packer.io/) (HCL2 templates) on **Azure**.\n  - macOS images are also Packer (HCL2), but use the **Anka** builder (`*.anka.pkr.hcl`) for virtualization instead of Azure; macOS CI does not accept external contributions yet (see [CONTRIBUTING.md](../CONTRIBUTING.md#macos)).\n- **Build flow:** a Packer template provisions a temporary Azure VM, runs install scripts in order, runs validation tests, captures a managed image, then generates the image's software report. A failed step aborts the build and cleans up resources. Details: [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md).\n\n## Repository map\n\n| Path | What lives here |\n| --- | --- |\n| `images/<os>/` | Per-image sources, where `<os>` is a Packer-built VM image: `ubuntu`, `windows`, or `macos`. (`ubuntu-slim` is Docker-based with a different layout — see its own row.) |\n| `images/<os>/templates/` | Packer (HCL2) templates. |\n| `images/<os>/toolsets/toolset-*.json` | Declarative tool/version pinning (validated by `schemas/toolset-schema.json`). |\n| `images/<os>/scripts/build/` | Install scripts that run during image generation. |\n| `images/<os>/scripts/tests/` | [Pester v5](https://github.com/pester/pester) validation scripts (`*.Tests.ps1`). |\n| `images/<os>/scripts/helpers/` | Shared install/validation helpers (e.g. Ubuntu `install.sh`, Windows `ImageHelpers.psm1`). |\n| `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1` | Generates the image's `*-Readme.md` software list. |\n| `images/ubuntu-slim/` | Docker-based slim image: `Dockerfile`, `test.sh`, and `generate-software-report.sh`, plus `scripts/build`, `scripts/helpers`, and `toolsets/` (no Packer template or Pester `scripts/tests`). |\n| `helpers/` | Repo-level orchestration scripts (e.g. `GenerateResourcesAndImage.ps1`). |\n| `docs/` | Build and topic docs (start with `create-image-and-azure-resources.md`). |\n| `schemas/` | JSON schema for toolset files. |\n| `.github/workflows/` | CI: per-image builds, linting, tests, and schema/version checks. |\n| `.vscode/` | Recommended extensions and editor settings for contributors. |\n\n## Key workflows\n\n- **Adding or updating a tool** (the most common change) requires, together:\n  1. an install script in `images/<os>/scripts/build/` (reuse existing helpers),\n  2. a Pester validation test in `images/<os>/scripts/tests/`, registered from the install script — `invoke_tests \"<TestFile>\" \"<TestName>\"` in Bash scripts (Ubuntu/macOS) or `Invoke-PesterTests -TestFile \"<name>\"` in PowerShell scripts (Windows),\n  3. an update to `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1`, and\n  4. version entries in the relevant `toolsets/toolset-*.json` when the tool is versioned.\n\n  Open an issue and get approval before adding a new tool. Full guide: [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-new-tool-to-an-image).\n- **Building or testing an image:** follow [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md); validation runs through Pester.\n- **CI:** workflows in `.github/workflows/` (per-image builds, `linter.yml`, `powershell-tests.yml`, `check-pinned-versions.yml`, `validate-json-schema.yml`).\n- **Submitting changes:** fork, branch, make the change, validate, then open a focused pull request. See [CONTRIBUTING.md](../CONTRIBUTING.md#submitting-a-pull-request) and `.github/pull_request_template.md`.\n- **Good practices from real contributions:** keep install scripts thin and reuse existing helpers instead of re-implementing version resolution or download logic; prefer surgical compatibility fixes over broader runtime changes; register validation tests from the install script so the build proves the change on a real VM; fail fast when versions or assets cannot be resolved; and only add software-report or toolset entries when they are truly applicable to the tool's packaging and versioning model.\n\n## Onboarding new contributors\n\n- For a guided, interactive introduction to this repository, use the **`onboarding` skill** (`.github/skills/onboarding/`). Trigger it with phrases like \"Start onboarding\", \"give me a tour\", or \"help me get started\".\n- The skill walks newcomers through the architecture, repository map, and the add-a-tool workflow step by step (pausing for checkpoints), and also supports free exploration.\n\n## Code and command instructions\n\n- Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules.\n- Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation.\n- Keep tests simple, non-mutating, and aligned with the real install behavior; they should verify the tool works on the VM instead of asserting on mocks or synthetic state.\n- Always confirm versions and installation paths against existing toolset files and installation scripts.\n- When a change is non-obvious, leave a short comment or link to the issue explaining the compatibility rationale, especially for temporary pins or platform-specific workarounds.\n\n## Output format\n\n- Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary.\n- One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …).\n- Use fenced code blocks with language identifiers (` ```bash `, ` ```json `, ` ```yaml `, etc.).\n- Use blockquote callouts for notes:\n  > [!NOTE] Context or nuance  \n  > [!TIP] Helpful hint  \n  > [!WARNING] Risks or breaking changes  \n  > [!IMPORTANT] Critical requirement for functionality\n\n## Style and tone\n\n- Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant.\n- Voice: Second person (\"you\"), active voice, imperative for operational steps.\n- Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting.\n- Use inclusive, accessible language. Avoid idioms, sarcasm, and culturally specific references.\n- English: en-US (spelling, punctuation, and units).\n\n## Safety and integrity\n\n- Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples.\n- Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts.\n- Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability.\n- If ambiguous requests are made about image modifications, ask clarifying questions about target OS, tool versions, and compatibility requirements before proceeding.\n","isInternal":false,"tokens":1842,"sizeBytes":8190}],"systemPromptSnippet":"<yakaai_skills repo=\"actions/runner-images\">\n<!-- File: .github/copilot-instructions.md (Tokens: ~1842 | Category: copilot-instructions) -->\n# GitHub Copilot Instructions for Actions Runner Images Repository\n\n## Scope and goals\n\n- This repository serves as the source for building GitHub Actions runner and Azure DevOps agent images for Windows, Ubuntu, and macOS. You can find exact versions in the [Available Images](../README.md#available-images) section of README.md. Windows and Ubuntu images build on Azure infrastructure using Packer; macOS images use Anka virtualization.\n- Emphasize best practices for contributing to open-source projects, including code style, commit messages, and pull request etiquette.\n- Prefer clarity and correctness over creativity. If information is missing, ask clarifying questions or insert TODOs instead of guessing.\n\n## Architecture overview\n\n- **What this repo builds:** the source used to generate the VM images for [GitHub-hosted runners](https://docs.github.com/en/actions/using-github-hosted-runners/about-github-hosted-runners) (Actions) and Microsoft-hosted agents (Azure Pipelines). See [README.md](../README.md#about).\n- **Platforms and labels:** Ubuntu, Windows, and macOS across multiple versions and architectures (x64/arm64). See [Available Images](../README.md#available-images) for the supported YAML labels.\n- **Build systems:**\n  - Windows and Ubuntu images are built with [Packer](https://www.packer.io/) (HCL2 templates) on **Azure**.\n  - macOS images are also Packer (HCL2), but use the **Anka** builder (`*.anka.pkr.hcl`) for virtualization instead of Azure; macOS CI does not accept external contributions yet (see [CONTRIBUTING.md](../CONTRIBUTING.md#macos)).\n- **Build flow:** a Packer template provisions a temporary Azure VM, runs install scripts in order, runs validation tests, captures a managed image, then generates the image's software report. A failed step aborts the build and cleans up resources. Details: [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md).\n\n## Repository map\n\n| Path | What lives here |\n| --- | --- |\n| `images/<os>/` | Per-image sources, where `<os>` is a Packer-built VM image: `ubuntu`, `windows`, or `macos`. (`ubuntu-slim` is Docker-based with a different layout — see its own row.) |\n| `images/<os>/templates/` | Packer (HCL2) templates. |\n| `images/<os>/toolsets/toolset-*.json` | Declarative tool/version pinning (validated by `schemas/toolset-schema.json`). |\n| `images/<os>/scripts/build/` | Install scripts that run during image generation. |\n| `images/<os>/scripts/tests/` | [Pester v5](https://github.com/pester/pester) validation scripts (`*.Tests.ps1`). |\n| `images/<os>/scripts/helpers/` | Shared install/validation helpers (e.g. Ubuntu `install.sh`, Windows `ImageHelpers.psm1`). |\n| `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1` | Generates the image's `*-Readme.md` software list. |\n| `images/ubuntu-slim/` | Docker-based slim image: `Dockerfile`, `test.sh`, and `generate-software-report.sh`, plus `scripts/build`, `scripts/helpers`, and `toolsets/` (no Packer template or Pester `scripts/tests`). |\n| `helpers/` | Repo-level orchestration scripts (e.g. `GenerateResourcesAndImage.ps1`). |\n| `docs/` | Build and topic docs (start with `create-image-and-azure-resources.md`). |\n| `schemas/` | JSON schema for toolset files. |\n| `.github/workflows/` | CI: per-image builds, linting, tests, and schema/version checks. |\n| `.vscode/` | Recommended extensions and editor settings for contributors. |\n\n## Key workflows\n\n- **Adding or updating a tool** (the most common change) requires, together:\n  1. an install script in `images/<os>/scripts/build/` (reuse existing helpers),\n  2. a Pester validation test in `images/<os>/scripts/tests/`, registered from the install script — `invoke_tests \"<TestFile>\" \"<TestName>\"` in Bash scripts (Ubuntu/macOS) or `Invoke-PesterTests -TestFile \"<name>\"` in PowerShell scripts (Windows),\n  3. an update to `images/<os>/scripts/docs-gen/Generate-SoftwareReport.ps1`, and\n  4. version entries in the relevant `toolsets/toolset-*.json` when the tool is versioned.\n\n  Open an issue and get approval before adding a new tool. Full guide: [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-new-tool-to-an-image).\n- **Building or testing an image:** follow [docs/create-image-and-azure-resources.md](../docs/create-image-and-azure-resources.md); validation runs through Pester.\n- **CI:** workflows in `.github/workflows/` (per-image builds, `linter.yml`, `powershell-tests.yml`, `check-pinned-versions.yml`, `validate-json-schema.yml`).\n- **Submitting changes:** fork, branch, make the change, validate, then open a focused pull request. See [CONTRIBUTING.md](../CONTRIBUTING.md#submitting-a-pull-request) and `.github/pull_request_template.md`.\n- **Good practices from real contributions:** keep install scripts thin and reuse existing helpers instead of re-implementing version resolution or download logic; prefer surgical compatibility fixes over broader runtime changes; register validation tests from the install script so the build proves the change on a real VM; fail fast when versions or assets cannot be resolved; and only add software-report or toolset entries when they are truly applicable to the tool's packaging and versioning model.\n\n## Onboarding new contributors\n\n- For a guided, interactive introduction to this repository, use the **`onboarding` skill** (`.github/skills/onboarding/`). Trigger it with phrases like \"Start onboarding\", \"give me a tour\", or \"help me get started\".\n- The skill walks newcomers through the architecture, repository map, and the add-a-tool workflow step by step (pausing for checkpoints), and also supports free exploration.\n\n## Code and command instructions\n\n- Follow the code style guide in [CONTRIBUTING.md](../CONTRIBUTING.md#code-style-guide) for Bash and PowerShell scripts, including naming conventions, file structure, and indentation rules.\n- Focus on re-using helpers when writing scripts. Windows, Linux and Ubuntu scripts have helper functions available to simplify installation and validation.\n- Keep tests simple, non-mutating, and aligned with the real install behavior; they should verify the tool works on the VM instead of asserting on mocks or synthetic state.\n- Always confirm versions and installation paths against existing toolset files and installation scripts.\n- When a change is non-obvious, leave a short comment or link to the issue explaining the compatibility rationale, especially for temporary pins or platform-specific workarounds.\n\n## Output format\n\n- Use GitHub Flavored Markdown only. Avoid raw HTML unless necessary.\n- One H1 (`#`) per page, followed by logical, sequential headings (`##`, `###`, …).\n- Use fenced code blocks with language identifiers (` ```bash `, ` ```json `, ` ```yaml `, etc.).\n- Use blockquote callouts for notes:\n  > [!NOTE] Context or nuance  \n  > [!TIP] Helpful hint  \n  > [!WARNING] Risks or breaking changes  \n  > [!IMPORTANT] Critical requirement for functionality\n\n## Style and tone\n\n- Audience: Open-source contributors, GitHub Actions maintainers, and developers building custom runner images. Assume familiarity with CI/CD concepts, Packer, and basic infrastructure provisioning, but explain platform-specific details (Azure for Windows/Ubuntu, Anka for macOS) when relevant.\n- Voice: Second person (\"you\"), active voice, imperative for operational steps.\n- Be concise: short paragraphs and sentences. Prefer lists and step-by-steps, especially for operational procedures and troubleshooting.\n- Use inclusive, accessible language. Avoid idioms, sarcasm, and culturally specific references.\n- English: en-US (spelling, punctuation, and units).\n\n## Safety and integrity\n\n- Do not expose sensitive credentials (API tokens, Azure subscription IDs, etc.) in code examples.\n- Do not fabricate tool versions, installation paths, or software availability without verifying against toolset files or actual installation scripts.\n- Always call out assumptions and limitations explicitly, especially for changes affecting runner image behavior or software availability.\n- If ambiguous requests are made about image modifications, ask clarifying questions about target OS, tool versions, and compatibility requirements before proceeding.\n</yakaai_skills>"}