Merge pull request #90 from github-samples/content-refresh

Small updates for clarity and new functionality

Author: peckjon

README.md

@@ -2,7 +2,9 @@
 
 This repository contains the project for a 1 hour guided workshop to explore GitHub Copilot Agent Mode and related features in Visual Studio Code. The project is a website for a fictional game crowd-funding company, with a [Flask](https://flask.palletsprojects.com/en/stable/) backend using [SQLAlchemy](https://www.sqlalchemy.org/) and [Astro](https://astro.build/) frontend using [Svelte](https://svelte.dev/) for dynamic pages.
 
-To begin the workshop, start at [docs/README.md](./docs/README.md)
+## Start the workshop
+
+**To begin the workshop, start at [docs/README.md](./docs/README.md)**
 
 Or, if just want to run the app...
 

docs/0-prereqs.md

@@ -1,19 +1,16 @@
 # Exercise 0: Prerequisites
 
-Before we get started on the lab, there's a few tasks we need to complete to get everything ready. We need to get a copy of the repository which includes the code, then spin up a [codespace](https://github.com/features/codespaces) to use to create our code.
+Before we get started on the lab, there's a few tasks we need to complete to get everything ready. We need to get a copy of the repository which includes the code, then spin up a [codespace][codespaces] to use to create our code.
 
 ## Setting up the Lab Repository
 
-To create a copy of the repository for the code you'll create an instance from the [template](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-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. 
+To create a copy of the repository for the code you'll create 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. 
 
 1. In a new browser window, navigate to the GitHub repository for this lab: `https://github.com/github-samples/agents-in-sdlc`.
 2. Create your own copy of the repository by selecting the **Use this template** button on the lab repository page. Then select **Create a new repository**.
 
     ![Use this template button](images/use-template.png)
 
-> [!IMPORTANT]
-> If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors for naming the repository.
-
 3. If you are completing the workshop as part of an event being led by GitHub or Microsoft, follow the instructions provided by the mentors. Otherwise, you can create the new repository in an organization where you have access to Copilot coding agent and can assign issues to Copilot.
 
     ![Input the repository template settings](images/repository-template-settings.png)
@@ -22,7 +19,7 @@ To create a copy of the repository for the code you'll create an instance from t
 
 ## Creating a codespace
 
-Next up, we will be using a codespace to complete the lab exercises. [GitHub Codespaces](https://github.com/features/codespaces) are a cloud-based development environment that allows you to write, run, and debug code directly in your browser. It provides a fully-featured IDE with support for multiple programming languages, extensions, and tools.
+Next up, we will be using a codespace to complete the lab exercises. [GitHub Codespaces][codespaces] are a cloud-based development environment that allows you to write, run, and debug code directly in your browser. It provides a fully-featured IDE with support for multiple programming languages, extensions, and tools.
 
 1. Navigate to your newly created repository.
 2. Select the green **Code** button.
@@ -45,3 +42,6 @@ Congratulations, you have created a copy of the lab repository! You also began t
 ## Next step
 
 Since we've got a few minutes, let's get Copilot working on some tasks asynchronously for us! We can do this by [creating issues and assigning them to Copilot coding agent](./1-copilot-coding-agent.md).
+
+[codespaces]: https://github.com/features/codespaces
+[template-repository]: https://docs.github.com/repositories/creating-and-managing-repositories/creating-a-template-repository

docs/1-copilot-coding-agent.md

@@ -149,7 +149,7 @@ As has been highlighted, one of the great advantages of GitHub Copilot coding ag
    - Before creating the PR, ensure all tests pass
    ```
 
-7. Note the level of guidance being provided to Copilot to help set everyone up for success.
+7. Note the level of guidance being provided to Copilot to help set everyone up for success. While Copilot could infer many of the points we added to the request, it helps to add them in explicitly. This limits the assumptions which need to be made, driving better code generation.
 8. Scroll towards the bottom of the dialog box to locate the **Assignee** button.
 9. Select **Assignee** to open the dialog box to select assignees.
 10. Select **Copilot** from the list.

docs/2-mcp.md

@@ -31,7 +31,7 @@ Popular existing MCP servers include:
 
 - **[GitHub MCP Server][github-mcp-server]**: This server provides access to a set of APIs for managing your GitHub repositories. It allows the AI agent to perform actions such as creating new repositories, updating existing ones, and managing issues and pull requests.
 - **[Playwright MCP Server][playwright-mcp-server]**: This server provides browser automation capabilities using Playwright. It allows the AI agent to perform actions such as navigating to web pages, filling out forms, and clicking buttons.
-- **Additional reference servers**: There are many other MCP servers available that provide access to different tools and resources. Anthropic has [a list of MCP servers][anthropic-mcp-servers], including reference, third-party, and community implementations. 
+- **Additional reference servers**: There are many other MCP servers available that provide access to different tools and resources. GitHub hosts an [MCP registry][mcp-registry], listing including reference, third-party, and community implementations. 
 
 > [!IMPORTANT]
 > With regard to security, treat MCP servers as you would any other dependency in your project. Before using an MCP server, carefully review its source code, verify the publisher, and consider the security implications. Only use MCP servers that you trust and be cautious about granting access to sensitive resources or operations.
@@ -209,10 +209,9 @@ Notice that the setup process is similar to the GitHub MCP server, but you do no
 - [What the heck is MCP and why is everyone talking about it?][mcp-blog-post]
 - [GitHub MCP Server][github-mcp-server]
 - [Microsoft Playwright MCP Server][playwright-mcp-server]
-- [Anthropic MCP Servers][anthropic-mcp-servers]
+- [GitHub MCP Registry][mcp-registry]
 - [VS Code Extensions][vscode-extensions]
 - [GitHub Copilot Chat Extension][copilot-chat-extension]
-- [Creating a fine-grained personal access token][github-pat-docs]
 
 ---
 
@@ -225,9 +224,8 @@ Notice that the setup process is similar to the GitHub MCP server, but you do no
 [mcp-blog-post]: https://github.blog/ai-and-ml/llms/what-the-heck-is-mcp-and-why-is-everyone-talking-about-it/
 [github-mcp-server]: https://github.com/github/github-mcp-server
 [playwright-mcp-server]: https://github.com/microsoft/playwright-mcp
-[anthropic-mcp-servers]: https://github.com/modelcontextprotocol/servers
+[mcp-registry]: https://github.com/mcp
 [vscode-extensions]: https://code.visualstudio.com/docs/configure/extensions/extension-marketplace
 [copilot-chat-extension]: https://marketplace.visualstudio.com/items?itemName=GitHub.copilot
-[github-pat-docs]: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token
 [remote-github-mcp-server]: https://github.blog/changelog/2025-06-12-remote-github-mcp-server-is-now-available-in-public-preview/
 [vscode-mcp-config]: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_configuration-format

docs/3-custom-instructions.md

@@ -7,10 +7,13 @@ Context is key across many aspects of life, and when working with generative AI.
 
 In this exercise, you will learn how to:
 
-- provide Copilot with project-specific context, coding guidelines and documentation standards using custom instructions **.github/copilot-instructions.md**.
-- use instruction files to guide Copilot for repetitive or templated tasks.
+- provide Copilot with project-specific context, coding guidelines and documentation standards using [repository custom instructions][repository-custom-instructions] **.github/copilot-instructions.md**.
+- provide path instruction files to guide Copilot for repetitive or templated tasks on specific types of files.
 - implement both repository-wide instructions and task-specific instructions.
 
+> [!NOTE]
+> There are other types of files which can be used to provide context or guidance to Copilot currently in preview. This workshop currently focused on generally available features.
+
 ## Scenario
 
 As any good dev shop, Tailspin Toys has a set of guidelines and requirements for development practices. These include:
@@ -40,11 +43,13 @@ Custom instructions allow you to provide context and preferences to Copilot chat
 
 There are two types of instructions files:
 
-- **.github/copilot-instructions.md**, a single instruction file sent to Copilot for **every** chat prompt. This file should contain project-level information, context which is relevant for every message. This could include the tech stack being used, an overview of what's being built, or global guidance for Copilot.
+- **.github/copilot-instructions.md**, a single instruction file sent to Copilot for **every** chat prompt for the repository. This file should contain project-level information, context which is relevant for most chat requests sent to Copilot. This could include the tech stack being used, an overview of what's being built and best practices, and other global guidance for Copilot.
 - **\*.instructions.md** files can be created for specific tasks or file types. You can use **.instructions.md** files to provide guidelines for particular languages (like Python or TypeScript), or for tasks like creating a React component or a new instance of a repository pattern.
 
 > [!NOTE]
 > When working in your IDE, instructions files are only used for code generation in Copilot Chat, and not used for code completions or next edit suggestions.
+>
+> Copilot coding agent will utilize both repository and path instructions files when generating code.
 
 ## Use GitHub Copilot Chat before updating custom instructions
 
@@ -69,9 +74,9 @@ To see the impact of custom instructions, we will start by sending a prompt with
 > [!IMPORTANT]
 > As highlighted previously, GitHub Copilot and LLM tools are probabilistic, not deterministic. As a result, the exact code generated may vary, and there's even a chance it'll abide by our rules without us spelling it out! But to aid consistency in code we should always document anything we want to ensure Copilot should understand about how we want our code generated.
 
-## Add global standards to copilot-instructions.md
+## Add repository standards to copilot-instructions.md
 
-As highlighted previously, `copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure global coding standards are documented to improve code suggestions from Copilot chat.
+As highlighted previously, `copilot-instructions.md` is designed to provide project-level information to Copilot. Let's ensure repository coding standards are documented to improve code suggestions from Copilot chat.
 
 1. Return to your codespace.
 2. Open `.github/copilot-instructions.md`.
@@ -155,68 +160,4 @@ We want to create a new endpoint to list all publishers, and to follow the same
 
    ![Screenshot showing the instruction file being added into Copilot Chat](images/copilot-add-instructions-file.png)
 
-13. Send the same prompt as before to generate the desired endpoint:
-
-   ```plaintext
-   Create a new endpoint to return a list of all publishers. It should return the name and id for all publishers.
-   ```
-
-14. Note the **References** section and how it uses the **flask-endpoint.instructions.md** file to provide context. If you use instructions files with Copilot agent mode, you will notice that Copilot explores and reads the files referenced in the instructions file.
-
-   ![Screenshot of the references section, showing the included instructions file](./images/copilot-instructions-references.png)
-
-15. Copilot generates the files. Notice how it generates updates across multiple files, like **publishers.py** and **test_publishers.py**
-
-> [!NOTE]
-> Note that the code generated may diverge from some of the standards we set. AI tools like Copilot are non-deterministic, and may not always provide the same result. The other files in our codebase do not contain docstrings or comment headers, which could lead Copilot in another direction. Consistency is key, so making sure that your code follows the established patterns is important. You can always follow-up in chat and ask Copilot to follow your coding standards, which will help guide it in the right direction.
-
-16. After reviewing the code, select **Keep** in Copilot Chat to accept the changes.
-17. If you are prompted to run tests select **Cancel**; we'll perform this task later.
-18. Open a terminal window by selecting <kbd>Ctl</kbd> + <kbd>\`</kbd>.
-19. Run the tests by running the script with the following command:
-
-   ```sh
-   ./scripts/run-server-tests.sh
-   ```
-
-20. Once the code is correct, and all tests pass, open the **Source Control** panel on the left of the Codespace and review the changes made by Copilot.
-
-> [!NOTE]
-> If any tests fail, ask Copilot to suggest a fix. You can use `@terminal /explain` to give Copilot the context of your terminal window.
-
-21.  Stage the changes by selecting the **+** icon in the **Source Control** panel.
-22.  Generate a commit message using the **Sparkle** button.
-
-    ![Screenshot of the Source Control panel showing the changes made](images/source-control-changes.png)
-
-23.  Commit the changes to your repository by selecting **Commit**.
-
-## Summary and next steps
-
-Congratulations! You explored how to ensure Copilot has the right context to generate code following the practices your organization has set forth. This can be done at a repository level with the **.github/copilot-instructions.md** file, or on a task basis with instruction files. You explored how to:
-
-- provide Copilot with project-specific context, coding guidelines and documentation standards using custom instructions (.github/copilot-instructions.md).
-- use instruction files to guide Copilot for repetitive or templated tasks.
-- implement both repository-wide instructions and task-specific instructions.
-
-Next we'll use [agent mode to add functionality to the site][next-lesson].
-
-## Resources
-
-- [Instruction files for GitHub Copilot customization][instruction-files]
-- [Best practices for creating custom instructions][instructions-best-practices]
-- [Personal custom instructions for GitHub Copilot][personal-instructions]
-
----
-
-| [← Previous lesson: Model Context Protocol (MCP)][previous-lesson] | [Next lesson: Copilot agent mode →][next-lesson] |
-|:--|--:|
-
-[previous-lesson]: ./2-mcp.md
-[next-lesson]: ./4-copilot-agent-mode-vscode.md
-[instruction-files]: https://code.visualstudio.com/docs/copilot/copilot-customization
-[python-type-hints]: https://docs.python.org/3/library/typing.html
-[games-endpoints]: ../server/routes/games.py
-[games-tests]: ../server/tests/test_routes/test_games.py
-[instructions-best-practices]: https://docs.github.com/en/enterprise-cloud@latest/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#adding-custom-instructions-to-your-repository
-[personal-instructions]: https://docs.github.com/en/copilot/customizing-copilot/adding-personal-custom-instructions-for-github-copilot
+13. Send the same

docs/4-copilot-agent-mode-vscode.md

@@ -189,8 +189,7 @@ As the list of games grows there will be a need for paging to be enabled. Using
 ## Resources
 
 - [Coding agent 101][coding-agent-101]
-- [Copilot ask, edit, and agent modes: What they do and when to use them
-][choose-mode]
+- [Copilot ask, edit, and agent modes: What they do and when to use them][choose-mode]
 - [Agent mode in VS Code][vs-code-agent-mode]
 
 ---

docs/5-reviewing-coding-agent.md

@@ -126,11 +126,11 @@ This is just the beginning, and we can't wait to see how you use Copilot to help
 |:----:|
 
 [github-copilot]: https://github.com/features/copilot
-[coding-agent-overview]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot#overview-of-copilot-coding-agent
-[assign-issue]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue
-[setup-workflow]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#pre-installing-dependencies-in-github-copilots-environment
-[copilot-agents]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot
-[coding-agent-best-practices]: https://docs.github.com/en/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks
-[agent-firewall]: https://docs.github.com/en/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent
+[coding-agent-overview]: https://docs.github.com/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot#overview-of-copilot-coding-agent
+[assign-issue]: https://docs.github.com/copilot/using-github-copilot/coding-agent/using-copilot-to-work-on-an-issue
+[setup-workflow]: https://docs.github.com/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks#pre-installing-dependencies-in-github-copilots-environment
+[copilot-agents]: https://docs.github.com/copilot/using-github-copilot/coding-agent/about-assigning-tasks-to-copilot
+[coding-agent-best-practices]: https://docs.github.com/copilot/using-github-copilot/coding-agent/best-practices-for-using-copilot-to-work-on-tasks
+[agent-firewall]: https://docs.github.com/copilot/customizing-copilot/customizing-or-disabling-the-firewall-for-copilot-coding-agent
 
 [previous-lesson]: ./4-copilot-agent-mode-vscode.md