From 7a1715c1e5413ffe1b42ec3194c7eb2f3390ac1c Mon Sep 17 00:00:00 2001 From: Christopher Harrison Date: Mon, 14 Sep 2026 13:45:27 -0700 Subject: [PATCH] docs: align VS Code and Cloud workshop lesson structure Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/cloud/0-prerequisites.md | 5 ++ docs/cloud/1-custom-instructions.md | 6 +-- docs/cloud/2-cloud-agent.md | 2 +- docs/cloud/3-custom-agents.md | 71 +++++++++++++++++--------- docs/cloud/5-iterating.md | 13 +++-- docs/cloud/README.md | 4 +- docs/vscode/0-prerequisites.md | 5 ++ docs/vscode/1-custom-instructions.md | 6 +-- docs/vscode/3-mcp.md | 4 ++ docs/vscode/4-custom-agents.md | 75 ++++++++++++++++------------ docs/vscode/5-managing-agents.md | 5 +- docs/vscode/6-iterating.md | 15 ++++-- docs/vscode/README.md | 4 +- 13 files changed, 138 insertions(+), 77 deletions(-) diff --git a/docs/cloud/0-prerequisites.md b/docs/cloud/0-prerequisites.md index 4abd67cd..c00cb22e 100644 --- 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 index efc5dac9..bccc8935 100644 --- 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 index 581dfbb8..bb99ccfb 100644 --- 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 index cda3be2a..a177ecdf 100644 --- a/docs/cloud/3-custom-agents.md +++ b/docs/cloud/3-custom-agents.md @@ -5,17 +5,30 @@ 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. @@ -23,33 +36,38 @@ Custom agents have their own context window and are built to orchestrate skills [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,12 +85,12 @@ 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 @@ -80,7 +98,7 @@ This lesson explored [custom agents][custom-agents] in GitHub Copilot, specializ 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. @@ -88,6 +106,8 @@ With Copilot working on implementing the high contrast mode, we can now turn our ## 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 index d2793824..364e0d72 100644 --- 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 index faeea7f4..c9d77e28 100644 --- 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 index f874d605..19ce3cc1 100644 --- 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. diff --git a/docs/vscode/1-custom-instructions.md b/docs/vscode/1-custom-instructions.md index dbe1939e..e4fc3715 100644 --- a/docs/vscode/1-custom-instructions.md +++ b/docs/vscode/1-custom-instructions.md @@ -20,9 +20,7 @@ In this exercise, you will: > [!CAUTION] > Generated code may diverge from some of the standards you set. Copilot is non-deterministic. The point of this exercise is to see the *trend* in behavior change after updating the instructions, not to match output character-for-character. -## Instruction files - -### Scenario +## Scenario As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include: @@ -33,6 +31,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/vscode/3-mcp.md b/docs/vscode/3-mcp.md index 2f97efbb..1737728f 100644 --- a/docs/vscode/3-mcp.md +++ b/docs/vscode/3-mcp.md @@ -16,6 +16,10 @@ In this exercise, you will: - ask Copilot to use it to manually test your filtering feature in a browser, - publish your branch and open a pull request for the filtering work. +## Scenario + +Tailspin Toys' filtering feature is ready for browser review. The team needs to see whether selecting categories and publishers produces the expected games, not just whether the code compiles. You'll use Playwright MCP to gather browser observations before handing the feature to reviewers in a PR. + ## What is Model Context Protocol (MCP)? Agent mode becomes far more powerful when it can reach beyond your editor. Model Context Protocol (MCP) is how Copilot does that — it's a standard way for the agent to talk to external tools and services. diff --git a/docs/vscode/4-custom-agents.md b/docs/vscode/4-custom-agents.md index 7a762452..b69301f7 100644 --- a/docs/vscode/4-custom-agents.md +++ b/docs/vscode/4-custom-agents.md @@ -5,17 +5,30 @@ authors: lastUpdated: 2026-06-30 --- +You've built and tested filtering with Copilot Chat. Now define a reusable specialist role to guide accessibility work. + +In this exercise, you will: + +- create and review an accessibility custom agent. +- use the accessibility agent in Copilot Chat to implement a high-contrast mode. + +## 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. +Custom agents are defined by `.agent.md` files in the `.github/agents` folder of your project. 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. @@ -23,19 +36,9 @@ Custom agents have their own context window and are built to orchestrate skills [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/ -## Scenario +## Creating and reviewing the accessibility custom agent -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. -In this exercise, you will: - -- review an existing accessibility custom agent. -- use the accessibility agent in Copilot Chat to implement a high-contrast mode. - -## Reviewing the accessibility custom agent - -A custom agent has already been created for you for accessibility. Let's review the contents to understand how it will guide Copilot. +The template does not supply custom agents or skills. You'll generate an accessibility profile, review its instructions, then select it for the implementation task. Return to your codespace, then open a terminal and switch to a fresh branch off `main` for the accessibility work (you'll keep the filtering PR from Exercise 3 separate): @@ -45,34 +48,44 @@ git pull git checkout -b accessibility-vscode ``` -1. Open `.github/agents/accessibility.md`. -2. Note the YAML frontmatter with the `name` and `description` fields. +1. Open Copilot Chat and select the built-in **Agent** from the agents dropdown. +2. Send this creation prompt: + + ```plaintext + Create an accessibility custom agent at .github/agents/accessibility.agent.md. Inspect the repository instructions, package.json, existing components, styles, and tests first. Give it valid YAML frontmatter with name: Accessibility agent and a description explaining when to use it. Omit model and tools so it uses the selected model and available tools. + + Write reusable instructions for implementing and reviewing accessible Astro UI changes: semantic HTML, keyboard access, visible focus, accessible control names and states, and WCAG contrast guidance. Follow the user's requirements and repository conventions, make focused changes, and add or update relevant tests. Require direct execution of npm run lint, npm run test:unit, npm run test:e2e, and npm run typecheck:all, with accurate pass/fail/blocked results and explicit reporting of any browser checks not performed. Do not depend on supplied agents or skills. Ask before installing dependencies or stopping an existing server. -> [!CAUTION] -> The frontmatter with `name` and `description` is required for custom agents. + Create only this profile and stop for my review. Do not implement high-contrast mode yet, change branches, commit, push, or create a pull request. + ``` + +3. Open `.github/agents/accessibility.agent.md` and review its YAML and instructions. Confirm the `description` explains its purpose and the `name` is `Accessibility agent`. Check that it covers the accessibility practices and direct npm checks requested above, without adding unrelated workflows. +4. Review and save any necessary corrections before continuing. Keep this profile and the upcoming feature changes on `accessibility-vscode`. + +> [!NOTE] +> `description` is required; `name` is optional, but intentionally provided here. Omitting `tools` allows the available tools rather than restricting them; your normal tool permissions still apply. -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. ## Using the custom agent in Copilot Chat -VS Code surfaces every custom agent defined in `.github/agents` in the agents dropdown at the bottom of the Copilot Chat view. You can select a custom agent to scope a chat session to that agent's instructions and tooling. +VS Code discovers workspace custom agents in `.github/agents`. Use the agents dropdown in Copilot Chat to select the saved profile, as described in the [VS Code custom-agent documentation][custom-agents-vscode]. > [!TIP] > **Open Copilot Chat** > > Before you start the exercises below, return to your codespace, open the Copilot Chat panel, and select **New Chat** to start a clean conversation. Mode and model selection vary per exercise — each step calls those out where it matters. -1. Select **Agent** from the agents dropdown in the Chat view if it isn't already selected. + +1. Stay in the same codespace and on `accessibility-vscode`; do not create another branch for agent selection. ![Screenshot showing the agent picker in the Chat view.](../_images/shared-chat-mode-selector.png) -2. Select the agents dropdown at the bottom of the chat view (it shows the active agent — by default, this is **default**). -3. Select **Accessibility agent** from the list of available agents. +2. Open the agents dropdown in the Chat view. +3. Select **Accessibility agent** and confirm that the picker now shows it as the active agent before sending the task. + + If it is missing, confirm the file is saved in this workspace at `.github/agents/accessibility.agent.md`, review its frontmatter, and check **Configure Custom Agents** in the dropdown. Do not continue until you can select it. Asking the default agent to read the file does not activate the custom agent. + 4. Send the following prompt to the accessibility agent: - ``` + ```plaintext Add a high-contrast mode to the site. There should be a toggle for high contrast which the user can set, and the setting should persist across page reloads using local storage on the browser. ``` @@ -90,7 +103,7 @@ This lesson explored [custom agents][custom-agents] in GitHub Copilot, specializ You explored these concepts: -- how custom agents are defined. +- creating and reviewing a custom-agent profile. - using a custom agent in Copilot Chat agent mode. Next, you'll [monitor and steer the agent's work][next-lesson] — reviewing the changes as they happen and adding a light-mode toggle to the same session. @@ -112,6 +125,6 @@ Next, you'll [monitor and steer the agent's work][next-lesson] — reviewing the [next-lesson]: ../5-managing-agents/ [custom-agents]: https://docs.github.com/copilot/concepts/agents/cloud-agent/about-custom-agents [creating-custom-agents-ide]: https://docs.github.com/copilot/how-tos/use-copilot-agents/cloud-agent/create-custom-agents-in-your-ide -[custom-agents-vscode]: https://code.visualstudio.com/docs/copilot/customization/custom-agents +[custom-agents-vscode]: https://code.visualstudio.com/docs/agent-customization/custom-agents [custom-agents-config]: https://docs.github.com/copilot/reference/custom-agents-configuration [awesome-copilot-agents]: https://github.com/github/awesome-copilot/tree/main/agents diff --git a/docs/vscode/5-managing-agents.md b/docs/vscode/5-managing-agents.md index 0af014e6..616a4430 100644 --- a/docs/vscode/5-managing-agents.md +++ b/docs/vscode/5-managing-agents.md @@ -55,9 +55,10 @@ Now that high-contrast mode is in place, you'll extend the same conversation to Before committing the work, take a quick pass over everything the agent touched. 1. Open the **Source Control** view in VS Code. -2. Review the full list of changed files. You should see updates to the Astro components, styles, and any related tests. +2. Review the full list of changed files. You should see the new `.github/agents/accessibility.agent.md` profile alongside updates to the Astro components, styles, and any related tests. 3. Open a couple of the changed files and walk through the diffs. Confirm the accessibility patterns from the custom agent are reflected — ARIA attributes, keyboard navigation, semantic HTML, and persistence via local storage. -4. When you're satisfied, stage and commit the changes from the Source Control panel. You'll publish them in [the next lesson][next-lesson]. +4. Have the agent run `npm run lint`, `npm run test:unit`, `npm run test:e2e`, and `npm run typecheck:all` directly, then review the tool output and resolve failures or missing prerequisites. No skill from the CLI or App harness is required. +5. When you're satisfied with the changes and verification, stage and commit the profile and feature changes on the same `accessibility-vscode` branch from the Source Control panel. You'll publish them in [the next lesson][next-lesson]. ## Summary and next steps diff --git a/docs/vscode/6-iterating.md b/docs/vscode/6-iterating.md index edb501d4..94403104 100644 --- a/docs/vscode/6-iterating.md +++ b/docs/vscode/6-iterating.md @@ -8,20 +8,25 @@ lastUpdated: 2026-06-30 | [← Previous lesson: Monitoring and 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. You used agent mode to add filtering across the client and server, the Playwright MCP server to manually test that work in a browser, then a custom agent to implement accessibility features — high-contrast and light-mode toggles — and steered the session mid-flight to extend the work. Now it's time to publish that local work and review it the same way your team would. -### Scenario +In this exercise, you will: + +- publish the reviewed accessibility changes in a pull request. +- inspect the complete diff and workflow results. +- reflect on the workflow and choose what to explore next. + +## Scenario The fundamentals of software design and DevOps don't change with the addition of generative AI. You still want a real review cycle on anything Copilot produces. With that in mind, let's push the accessibility changes from your codespace, open a pull request, and walk through the diff before bringing the rest of the team in. + ## Publish the accessibility features The high-contrast and light-mode toggles you implemented with the accessibility custom agent in [Exercise 4][exercise-4] and [Exercise 5][exercise-5] are sitting in your codespace as committed changes. Let's push them to a branch and open a pull request so the rest of your team can review. 1. Return to your codespace. 2. Open the **Source Control** view in VS Code. -3. Confirm your accessibility changes are committed. If you have uncommitted changes from Exercise 5, stage and commit them now with a descriptive message such as `Add high-contrast and light-mode toggles`. +3. Confirm your accessibility changes and `.github/agents/accessibility.agent.md` are committed on `accessibility-vscode`. If you have uncommitted changes from Exercise 5, verify them with the existing npm checks, then stage and commit them with a descriptive message such as `Add high-contrast and light-mode toggles`. 4. Publish the branch by selecting **Publish Branch** (or use the **...** menu → **Push**). 5. VS Code will offer to open the new branch on github.com. Accept the prompt, or navigate to your repository manually and select **Compare & pull request** on the branch banner. 6. Set a clear title (for example, `Add high-contrast and light-mode toggles`) and a short description summarizing what was done and why. @@ -57,7 +62,7 @@ Congratulations — you've completed the VS Code harness! Through this lab you: - **Used Playwright MCP to manually test your feature.** You added the Playwright MCP server and let Copilot drive a browser to verify your filtering feature before opening a pull request. - **Drove agent mode through coordinated changes across the stack.** You added a filter feature that touched the client, the server, and the tests in a single session. -- **Used a custom agent.** You selected the accessibility-focused custom agent from the agent picker and watched it implement high-contrast mode against the repository. +- **Created and used a custom agent.** You generated and reviewed the accessibility profile, selected it from the agent picker, and watched it implement high-contrast mode against the repository. - **Managed and steered an agent session.** You reviewed proposed changes inline, accepted what you wanted, and extended the session with a light-mode follow-up. - **Closed the loop with a pull request.** You published your local work and reviewed it end-to-end the way your team would. diff --git a/docs/vscode/README.md b/docs/vscode/README.md index 911eb0a1..a192fac9 100644 --- a/docs/vscode/README.md +++ b/docs/vscode/README.md @@ -8,7 +8,7 @@ lastUpdated: 2026-06-30 **[GitHub Copilot Chat](https://code.visualstudio.com/docs/copilot/chat/copilot-chat)** in VS Code brings GitHub Copilot into the code editor you already use. Working in Visual Studio Code (and GitHub Codespaces), you'll drive Copilot Chat in agent mode, connect external tools through MCP, and rely on custom agents — all without leaving your IDE, where Copilot has full view of your files, terminal, and problems. -You'll start by adding custom instructions and watching Copilot follow them, then use agent mode to build a filtering feature across the UI, data layer, and tests. Next you'll connect the Playwright MCP server and let Copilot drive a browser to test your feature before opening a pull request. Finally, you'll review and use a custom agent for accessibility work, then monitor, steer, and iterate on Copilot's changes — all without leaving the editor. +You'll start by adding custom instructions and watching Copilot follow them, then use agent mode to build a filtering feature across the UI, data layer, and tests. Next you'll connect the Playwright MCP server and let Copilot drive a browser to test your feature before opening a pull request. Finally, you'll create, review, and use a custom agent for accessibility work, then monitor, steer, and iterate on Copilot's changes — all without leaving the editor. ## Exercises @@ -18,7 +18,7 @@ You'll start by adding custom instructions and watching Copilot follow them, the | [1. Custom instructions][ex1] | Context | Add and verify custom instructions in VS Code | | [2. Agent Mode][ex2] | Code Generation | Build a filtering feature with agent mode | | [3. MCP with Playwright][ex3] | External Tools | Test your feature in a browser with the Playwright MCP server | -| [4. Custom Agents][ex4] | Specialized Agents | Review and use custom agents | +| [4. Custom Agents][ex4] | Specialized Agents | Create, review, and use a custom agent | | [5. Managing Agents][ex5] | Monitoring | Monitor and steer agent sessions | | [6. Iterating][ex6] | Review | Review Copilot's work locally and choose next steps |