github-samples · GeekTrainer · Sep 14, 2026
diff --git a/docs/cloud/0-prerequisites.md b/docs/cloud/0-prerequisites.md
@@ -7,6 +7,11 @@ lastUpdated: 2026-06-30
 
 Before you start the Copilot cloud agent exercises, you need to get everything ready. You'll create your own copy of the Tailspin Toys repository and spin up a [codespace][codespaces] you can use to edit instruction files and review the work the cloud agent produces.
 
+In this exercise, you will:
+
+- create your own repository from the Tailspin Toys template.
+- open a codespace for instruction edits and review.
+
 ## Setting up the lab repository
 
 To create a copy of the repository for the code you'll create, you'll make an instance from the [template][template-repository]. The new instance will contain all of the necessary files for the lab, and you'll use it as you work through the exercises.

diff --git a/docs/cloud/1-custom-instructions.md b/docs/cloud/1-custom-instructions.md
@@ -17,9 +17,7 @@ In this exercise, you will:
 > [!NOTE]
 > Unlike the VS Code and CLI harnesses, you won't run a *before/after* prompt here — Copilot cloud agent works asynchronously on GitHub issues, so the impact is harder to demonstrate side-by-side in real time. You'll see your instruction file's influence later in this harness when you review the pull requests cloud agent produces.
 
-## Instruction files
-
-### Scenario
+## Scenario
 
 As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include:
 
@@ -30,6 +28,8 @@ As any good dev shop, Tailspin Toys has a set of guidelines and requirements for
 
 Through the use of instruction files you'll ensure Copilot has the right information to perform the tasks in alignment with the practices highlighted.
 
+## Instruction files
+
 ### Custom instructions
 
 Custom instructions allow you to provide context and preferences to Copilot, so that it can better understand your coding style and requirements. This is a powerful feature that can help you steer Copilot to get more relevant suggestions and code snippets. You can specify your preferred coding conventions, libraries, and even the types of comments you like to include in your code. You can create instructions for your entire repository, or for specific types of files for task-level context.

diff --git a/docs/cloud/2-cloud-agent.md b/docs/cloud/2-cloud-agent.md
@@ -17,7 +17,7 @@ You'll explore the following with Copilot cloud agent:
 - the importance of clearly scoped issues.
 - assigning issues to Copilot.
 
-## Scenarios
+## Scenario
 
 Tailspin Toys has some tech debt they'd like to address. The contractors initially hired to create the first version of the site left the documentation in an unideal state - and by that you'll notice it's completely lacking. As a first step, they'd like to see TSDoc doc comments added to all exported functions in the application.
 

diff --git a/docs/cloud/3-custom-agents.md b/docs/cloud/3-custom-agents.md
@@ -5,51 +5,69 @@ authors:
 lastUpdated: 2026-06-30
 ---
 
+You've assigned work to Copilot cloud agent. Now define a reusable specialist role to guide its accessibility work.
+
+In this exercise, you will:
+
+- create and review a custom-agent profile.
+- assign a task to the custom agent.
+
+## Scenario
+
+Tailspin Toys is committed to ensuring their crowdfunding platform is accessible to all users, regardless of their visual abilities or preferences. Recent user feedback has highlighted that some users find the current dark theme difficult to read due to insufficient contrast between text and background colors. To address this accessibility concern, the design team has requested the implementation of a high-contrast mode that users can toggle on and off.
+
+Because accessibility is critical, you want to ensure this is implemented as quickly as possible. You're going to utilize a custom agent to generate the functionality.
+
 ## What are custom agents?
 
 [Custom agents][custom-agents-concept] in GitHub Copilot allow you to create specialized AI assistants tailored to specific tasks or domains within your development workflow. By defining agents through markdown files in the `.github/agents` folder of your repository, you can provide Copilot with focused instructions, best practices, coding patterns, and domain-specific knowledge that guide it to perform particular types of work more effectively. Teams can codify their expertise into reusable agents — an accessibility agent that enforces [WCAG][wcag] compliance, a security agent that follows secure coding practices, or a testing agent that maintains consistent test patterns.
 
-Custom agents are defined by markdown files in the `.github/agents` folder of your project, or globally in `~/.copilot/agents`. Each file has YAML frontmatter with at least a `name` and `description`, followed by a markdown prompt that defines the agent's behavior, expertise, and instructions.
+Repository custom agents are defined by `.agent.md` files in the `.github/agents` folder. Each file has YAML frontmatter with a required `description`, followed by a Markdown prompt that defines the agent's behavior, expertise, and instructions. This exercise also supplies an optional, readable `name` so you can recognize the agent in the picker.
 
 ### Custom agents compared with agent skills
 
-There's some logical overlap between custom agents and [agent skills][agent-skills-concept]. Both are primarily defined with markdown files and tell an AI how to perform operations. The cleanest way to separate them: a **custom agent** is the worker, and **skills** are tools.
+There's some logical overlap between custom agents and [agent skills][agent-skills-concept]. A **custom agent** defines a specialized role, instructions, and available tools. A **skill** packages task-specific instructions and can include scripts and supporting resources.
 
-Custom agents have their own context window and are built to orchestrate skills (and even other agents) as part of doing their work. In this lab, the accessibility custom agent reviews and updates the site against accessibility guidelines; as part of that work it could call skills such as a pull-request workflow skill or one that runs and manages tests.
+Agents can run scripts directly through available tools, or follow a skill when one is available. Selecting a custom agent does not inherently create a separate context window or require orchestration of other agents. In this lab, you'll create an accessibility profile and use the project's existing npm checks directly; no skill from another workshop harness is required.
 
 > [!NOTE]
 > There's no single "right" way to author a custom agent. As with anything in AI, test and iterate to find what works for your environments and scenarios.
 
 [custom-agents-concept]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents
 [agent-skills-concept]: https://docs.github.com/copilot/concepts/agents/about-agent-skills
 [wcag]: https://www.w3.org/WAI/standards-guidelines/wcag/
-You'll explore the following with custom agents:
 
-- how custom agents are defined.
-- assigning a task to a custom agent.
+## Creating and reviewing the accessibility custom agent
 
-## Scenario
+The template does not supply custom agents or skills. Before assigning the high-contrast issue, create an accessibility profile using GitHub's [custom-agent creation flow][creating-custom-agents]. The profile must reach your repository's **default branch** before you select it for an issue.
 
-Tailspin Toys is committed to ensuring their crowdfunding platform is accessible to all users, regardless of their visual abilities or preferences. Recent user feedback has highlighted that some users find the current dark theme difficult to read due to insufficient contrast between text and background colors. To address this accessibility concern, the design team has requested the implementation of a high-contrast mode that users can toggle on and off.
+1. Open the [Copilot agents page][agents-page] and select your Tailspin Toys repository in the prompt box's repository dropdown.
+2. Select your repository's default branch (`main` for this workshop).
+3. Open **Select a custom agent**, then select **Create an agent**. GitHub opens a template at `.github/agents/my-agent.agent.md` in its file editor.
+4. Rename the file to `.github/agents/accessibility.agent.md`. Replace the template with this profile:
 
-Because accessibility is critical, you want to ensure this is implemented as quickly as possible. You're going to utilize a custom agent to generate the functionality.
-## Reviewing the accessibility custom agent
+   ```markdown
+   ---
+   name: Accessibility agent
+   description: Implement and review accessible Astro UI changes, including contrast, keyboard access, and user preference controls.
+   ---
+
+   Follow the user's requirements and repository instructions. Inspect existing components, styles, package.json, and tests before making focused accessibility changes.
+
+   Use semantic HTML, keyboard-accessible controls, visible focus, accessible names and states, and WCAG contrast guidance. Preserve existing behavior and persist user preferences when requested.
 
-A custom agent has already been created for you for accessibility. Let's review the contents to understand how it will guide Copilot.
+   Add or update relevant tests. Run npm run lint, npm run test:unit, npm run test:e2e, and npm run typecheck:all directly using the existing project setup. Do not depend on supplied agents or skills.
 
-Return to your codespace, then review the accessibility custom agent file:
+   Report changes and evidence, with accurate pass/fail/blocked check results. Distinguish automated checks from browser observations and identify any accessibility checks not performed. Report missing prerequisites or access rather than claiming success.
+   ```
 
-1. Open `.github/agents/accessibility.md`.
-2. Note the YAML frontmatter with the `name` and `description` fields.
+5. Review the profile against the repository's instructions and existing npm scripts. Confirm it guides accessibility work without prescribing an unrelated feature. `description` is required; `name` is optional but intentionally supplied here. Omitting `tools` makes the available tools accessible within the cloud agent's normal permissions.
+6. Save the reviewed profile to the default branch. Commit directly **only if** your permissions and branch rules allow it. Otherwise commit on a setup branch, open a pull request, review it, and merge it into the default branch before continuing.
+7. Open `.github/agents/accessibility.agent.md` on the default branch and confirm the reviewed contents are present. Return to the agents page, refresh it if needed, and confirm **Accessibility agent** appears in the custom-agent dropdown.
 
-> [!CAUTION]
-> The frontmatter with `name` and `description` is required for custom agents.
+> [!IMPORTANT]
+> A profile that exists only in an unmerged branch is not ready for this issue-assignment flow. If you cannot merge it or select it, resolve that access or discovery blocker before assigning the issue. Asking the default agent to read the profile is not a substitute for selecting the custom agent.
 
-3. From there, scan and review the next sections which highlight:
-   - Core responsibilities when generating code for an accessible website.
-   - Best practices for accessibility.
-   - Code examples for HTML, CSS, and JavaScript.
-   - A list of common pitfalls and mistakes.
 ## Create and assign an issue
 
 Mission control is the central location for working with all agents for your environment. You can assign tasks to Copilot cloud agent, monitor tasks, and even redirect and provide additional guidance. Let's start by assigning a task to create the high contrast mode to Copilot.
@@ -67,27 +85,29 @@ Mission control is the central location for working with all agents for your env
 
 7. Select **Create** to create the issue.
 8. On the right side, select **Assign to Copilot** to open the assignment dialog.
-9. Select **Accessibility agent** from the list of custom agents.
+9. Select **Accessibility agent** from the custom-agent dropdown and confirm that it is the selected agent in the assignment dialog before proceeding.
 
     ![Screenshot of cloud agent assignment, with custom agent and accessibility highlighted](../_images/ex5-select-custom-agent.png)
 
 10. Select **Assign**.
-11. Copilot gets to work on the task in the background!
+11. Copilot gets to work on the task in the background! When its pull request appears, check the description for the custom agent used and confirm it names your accessibility agent.
 
 ## Summary and next steps
 
 This lesson explored [custom agents][custom-agents] in GitHub Copilot, specialized AI assistants tailored to specific tasks and domains. With custom agents you can codify your team's expertise and standards into reusable agents that guide Copilot to perform particular types of work more effectively.
 
 You explored these concepts:
 
-- how custom agents are defined.
+- creating, reviewing, and publishing a custom-agent profile to the default branch before assignment.
 - assigning a task to a custom agent.
 
 With Copilot working on implementing the high contrast mode, we can now turn our attention to [monitoring and steering the agent session][next-lesson] from mission control.
 
 ## Resources
 
 - [About custom agents][custom-agents]
+- [Creating custom agents for Copilot cloud agent][creating-custom-agents]
+- [Custom agents configuration][custom-agents-config]
 - [Preparing to use custom agents in your organization][org-custom-agents]
 - [Preparing to use custom agents in your enterprise][enterprise-custom-agents]
 
@@ -99,5 +119,8 @@ With Copilot working on implementing the high contrast mode, we can now turn our
 [previous-lesson]: ../2-cloud-agent/
 [next-lesson]: ../4-managing-agents/
 [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents
+[creating-custom-agents]: https://docs.github.com/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents
+[custom-agents-config]: https://docs.github.com/copilot/reference/custom-agents-configuration
+[agents-page]: https://github.com/copilot/agents
 [org-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents
 [enterprise-custom-agents]: https://docs.github.com/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents
diff --git a/docs/cloud/5-iterating.md b/docs/cloud/5-iterating.md
@@ -8,13 +8,18 @@ lastUpdated: 2026-06-30
 | [← Previous lesson: Managing agents][previous-lesson] |
 |:--|
 
-## Reviewing the work
-
 Throughout this lab you've worked with GitHub Copilot on several tasks focused on improving the user experience and adding functionality. You asked Copilot to add documentation to your code, build a related games feature for the design team to iterate on, and implement accessibility features including high-contrast and light mode toggles. Let's explore the code changes and, if necessary, provide feedback to Copilot to improve its work.
 
-### Scenario
+In this exercise, you will:
+
+- review the documentation, related-games, and accessibility pull requests.
+- request focused changes and inspect updated diffs and checks.
+- prepare reviewed work for the team's normal review and merge process.
+
+## Scenario
 
 As has been highlighted numerous times, the fundamentals of software design and DevOps do not change with the addition of generative AI. We always want to review the code generated, and work through our normal DevOps process. With that in mind, let's review the suggestions from GitHub Copilot for creating the documentation, the related games feature, and accessibility features before we turn on review for the rest of our team.
+
 ## Security and GitHub Copilot cloud agent
 
 Because Copilot cloud agent performs its tasks asynchronously and without supervision, certain security constraints have been put in place to ensure everything remains safe. These include:
@@ -98,7 +103,7 @@ Copilot has built the related games feature! Just as before, you can work iterat
 
 ## Review the accessibility features
 
-Finally, let's review the accessibility features that were implemented using the custom accessibility agent. This PR should include both the high-contrast mode you assigned in Exercise 3, and the light mode that was requested in mission control in Exercise 4.
+Finally, let's review the accessibility features that were implemented using the custom accessibility agent. The profile was added to the default branch before assignment in Exercise 3; this feature PR should include both the high-contrast mode assigned there and the light mode requested in mission control in Exercise 4. Confirm the PR description identifies the accessibility agent, and review its reported npm check results rather than treating agent selection alone as verification.
 
 1. Return to your repository in GitHub.com.
 2. Select the **Pull Requests** tab.

diff --git a/docs/cloud/README.md b/docs/cloud/README.md
@@ -8,7 +8,7 @@ lastUpdated: 2026-06-30
 
 **[GitHub Copilot cloud agent](https://docs.github.com/copilot/concepts/agents/cloud-agent/about-cloud-agent)** lets GitHub Copilot work asynchronously in the cloud. You assign work on GitHub, and the cloud agent picks it up in the background — exploring the repository, making changes, and opening a pull request — while you stay free to do other things.
 
-Across these exercises you'll add custom instructions the cloud agent will follow, then assign a GitHub issue and let it implement the work. You'll review and use custom agents to shape its approach, monitor and steer sessions from the agents dashboard, and finish by reviewing its pull requests and iterating on the results.
+Across these exercises you'll add custom instructions the cloud agent will follow, then assign a GitHub issue and let it implement the work. You'll create and review an accessibility custom agent, publish its profile to the default branch before assignment, monitor and steer sessions from the agents dashboard, and finish by reviewing its pull requests and iterating on the results.
 
 ## Exercises
 
@@ -17,7 +17,7 @@ Across these exercises you'll add custom instructions the cloud agent will follo
 | [0. Prerequisites][ex0] | Setup | Create your repository and codespace |
 | [1. Custom instructions][ex1] | Context | Add custom instructions cloud agent will follow |
 | [2. Cloud Agent][ex2] | Async Agent | Assign issues to Copilot cloud agent |
-| [3. Custom Agents][ex3] | Specialized Agents | Review and use custom agents |
+| [3. Custom Agents][ex3] | Specialized Agents | Create, review, and use a custom agent |
 | [4. Managing Agents][ex4] | Monitoring | Monitor and steer agent sessions |
 | [5. Iterating][ex5] | Review | Review PRs, iterate on Copilot's work, and choose next steps |
 

diff --git a/docs/vscode/0-prerequisites.md b/docs/vscode/0-prerequisites.md
@@ -7,6 +7,11 @@ lastUpdated: 2026-06-30
 
 Before you start the VS Code exercises, you need to get everything ready. You'll create your own copy of the Tailspin Toys repository, spin up a [codespace][codespaces] to work in, and confirm GitHub Copilot Chat is up and running in your editor.
 
+In this exercise, you will:
+
+- create your own repository from the Tailspin Toys template.
+- open a codespace and confirm Copilot Chat is ready.
+
 ## Setting up the lab repository
 
 To create a copy of the repository for the code you'll create, you'll make an instance from the [template][template-repository]. The new instance will contain all of the necessary files for the lab, and you'll use it as you work through the exercises.