Enhance documentation clarity and structure across multiple files, including README and prerequisites, by refining headings, links, and instructions for better user guidance.

GeekTrainer · web-flow · commit 849a3866aff1 · 2025-10-09T17:09:03.000Z
diff --git a/README.md b/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...
 
diff --git a/docs/0-prereqs.md b/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/en/repositories/creating-and-managing-repositories/creating-a-template-repository
diff --git a/docs/1-copilot-coding-agent.md b/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, adding them in 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.
diff --git a/docs/2-mcp.md b/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
diff --git a/docs/3-custom-instructions.md b/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 **.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,7 +43,7 @@ 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]
@@ -69,9 +72,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`.
diff --git a/docs/4-copilot-agent-mode-vscode.md b/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]
 
 ---
