microsoft · crgarcia12 · Jul 8, 2026 · Jul 7, 2026
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/Readme.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/Readme.md
@@ -1,67 +1,82 @@
-# **Master Template MicroHack**
-# **MicroHack Template**
+# **App Modernization with GitHub Copilot**
 
-- [**MicroHack introduction**](#MicroHack-introduction)
+- [**MicroHack introduction**](#microhack-introduction)
 - [**MicroHack context**](#microhack-context)
 - [**Objectives**](#objectives)
-- [**MicroHack Challenges**](#microhack-challenges)
+- [**MicroHack challenges**](#microhack-challenges)
 - [**Contributors**](#contributors)
-# MicroHack introduction
 
-This MicroHack scenario walks through the use of ... with a focus on the best practices and the design principles. Specifically, this builds up to include working with an existing infrastructure.
+# MicroHack introduction
 
-![image](Path to the high level architecture )
+This MicroHack teaches you to **drive application modernization with AI tooling**. You will use GitHub Copilot **Custom Agents**, **Skills**, and **MCP (Model Context Protocol)** servers, together with the GitHub Copilot **App Modernization** extensions, to modernize a legacy **.NET Framework** application and a legacy **Java / Spring Boot** application and move them to Azure.
 
-This lab is not a full explanation of .... as a technology, please consider the following articles required pre-reading to build foundational knowledge.
+You start by building the AI foundation (agents, skills, MCP), then apply it to two real applications shipped in [`src/`](src/): **Contoso University** (.NET) and **Asset Manager** (Java).
 
-Optional (read this after completing this lab to take your learning even deeper!)
+This lab is not a full explanation of app modernization as a discipline. The following are recommended pre-reading:
 
-Describe the scenario here...
+- [GitHub Copilot app modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization-overview)
+- [GitHub Copilot app modernization for Java](https://learn.microsoft.com/azure/developer/java/migration/migrate-github-copilot-app-modernization-for-java)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
 
 # MicroHack context
-This MicroHack scenario walks through the use of....
+
+Modernization is a **multi-step, knowledge-heavy workflow**: assess → plan → execute → validate. AI coding agents are good at executing steps, but out of the box they lack a defined role and guardrails (Custom Agent), reusable domain knowledge (Skills), and tools to act on the real world (MCP servers). This MicroHack shows how those three pieces combine into a repeatable, gated modernization playbook — and then applies it to a .NET and a Java workload.
+
+> 📖 Concept primer: [docs/00-fundamentals.md](docs/00-fundamentals.md)
 
 # Objectives
 
 After completing this MicroHack you will:
 
-- Know how to build a ...
-- Understand default ..
-- Understand how ..
+- Explain how Custom Agents, Skills, and MCP fit together in an AI-assisted modernization workflow.
+- Author a **Custom Agent** (`.agent.md`) with a phased, gated workflow and a least-privilege tool allow-list.
+- Author a **Skill** (`SKILL.md`) that packages modernization domain knowledge with explicit `WHEN:` triggers.
+- Configure **MCP servers** (`mcp.json`) that give the agent modernization tools (assessment, build, CVE checks, deployment).
+- Run an end-to-end **assess → plan → execute → validate** loop to upgrade a .NET Framework app to **.NET 9** and a Java 8 / Spring Boot 2.x app to **Java 21 / Spring Boot 3.x**, and deploy to Azure.
 
 # MicroHack challenges
 
 ## General prerequisites
 
-This MicroHack has a few but important prerequisites
-
-In order to use the MicroHack time most effectively, the following tasks should be completed prior to starting the session.
-
-With these pre-requisites in place, we can focus on building the differentiated knowledge in ... that is required when working with the product, rather than spending hours repeating relatively simple tasks such as setting up....
-
-In summary:
-
-- Azure Subscription 
-- Resource Group 
-- Service 1
-- Service 2  
-
-Permissions for the deployment: 
-- Contributor on your Resource Group
-- Other necessary permissions
-
+This MicroHack has a few but important prerequisites.
+
+In order to use the MicroHack time most effectively, the following should be completed prior to the session:
+
+- **VS Code** (latest) with **GitHub Copilot** + **GitHub Copilot Chat** extensions, agent mode enabled
+- **Visual Studio 2022** (latest) for the .NET challenge
+- GitHub Copilot **App Modernization** extensions:
+  - *App Modernization for Java* (`vscjava.migrate-java-to-azure`)
+  - GitHub Copilot **app modernization for .NET** (Visual Studio "Modernize" flow)
+- **Azure subscription** with **Contributor** on your resource group (for the deploy steps)
+- **.NET SDK 9**, **Java 17/21 + Maven**, **Docker Desktop**
+
+## Repository layout
+
+```
+03_GHCPAppModernization/
+├── docs/
+│   └── 00-fundamentals.md          # Concepts: Custom Agents, Skills, MCP
+├── templates/                      # Generic + pre-tailored templates
+│   ├── agents/                     # Custom Agent templates (generic, .NET, Java)
+│   ├── skills/                     # Skill templates (generic, skill-creator, .NET, Java)
+│   └── mcp/                        # MCP server configuration template
+├── challenges/                     # Challenge instructions
+├── walkthrough/                    # Step-by-step solutions
+└── src/                            # Sample apps: ContosoUniversity (.NET), AssetManager (Java)
+```
 
 ## Challenges
 
-* [Challenge 1 - title](challenges/challenge-01.md)  **<- Start here**
-* [Challenge 2 - title](challenges/challenge-02.md)
+* [Challenge 1 - Fundamentals: Custom Agents, Skills & MCP](challenges/challenge-01.md)  **<- Start here**
+* [Challenge 2 - Modernize a .NET Application](challenges/challenge-02.md)
+* [Challenge 3 - Modernize a Java Application](challenges/challenge-03.md)
+* [Finish](challenges/finish.md)
 
 ## Solutions - Spoilerwarning
 
-* [Solution 1 - title](./walkthrough/challenge-01/solution-01.md)
-* [Solution 2 - title](./walkthrough/challenge-02/solution-02.md)
-
-
+* [Solution 1 - Fundamentals](./walkthrough/challenge-01/solution-01.md)
+* [Solution 2 - .NET Application](./walkthrough/challenge-02/solution-02.md)
+* [Solution 3 - Java Application](./walkthrough/challenge-03/solution-03.md)
 
-## Contributors
+# Contributors
 * Nils Bankert [GitHub](https://github.com/nilsbankert); [LinkedIn](https://www.linkedin.com/in/nilsbankert/)
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-01.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-01.md
@@ -1,29 +1,42 @@
-# Modernize a .NET Application
+# Fundamentals — Custom Agents, Skills & MCP for App Modernization
 
-**[Home](../Readme.md)** - [Next Challenge Solution](challenge-02.md)
+**[Home](../Readme.md)** - [Next Challenge](challenge-02.md)
 
 ## Goal
 
-Modernize the Contoso University .NET Framework application to .NET 9 and deploy it to Azure App Service using GitHub Copilot’s AI-assisted tooling.
+Build the AI foundation you will reuse in the next challenges. Learn how **GitHub Copilot Custom Agents**, **Skills**, and **MCP (Model Context Protocol)** servers fit together, then author your own modernization Custom Agent, package a reusable Skill, and configure the MCP tools that let the agent assess, build, and validate a legacy application.
+
+## Scenario
+
+Before pointing AI at a real .NET or Java application (challenges 2 and 3), you assemble a reusable, gated modernization playbook:
+
+- an **Agent** that defines *who* is working and *how* the assess → plan → execute → validate loop runs (with approval gates),
+- a **Skill** that packages the *domain knowledge* (migration rules, breaking-changes checklist) the agent pulls in on demand,
+- an **MCP** configuration that gives the agent the *tools* to act (assessment, build, CVE scan, deployment).
+
+> 📖 Read [docs/00-fundamentals.md](../docs/00-fundamentals.md) first (~15 min). It gives you the mental model: *Agent = who/how*, *Skill = what it knows*, *MCP = what it can do*.
 
 ## Actions
 
-* Fork `https://github.com/crgarcia12/migrate-modernize-lab`, clone your fork in Visual Studio 2022, and confirm the ContosoUniversity project builds.
-* Use the Visual Studio “Modernize” flow to sign in to GitHub Copilot, select Claude Sonnet 4.5, and run the guided upgrade to .NET 9 until `dotnet-upgrade-report.md` is produced.
-* Rerun “Modernize” to start “Migrate to Azure,” review the cloud readiness assessment, and resolve authentication findings by migrating from Windows AD to Microsoft Entra ID.
-* Approve Copilot’s Azure App Service deployment workflow, wait for completion, and validate the site in Azure.
+* Read [docs/00-fundamentals.md](../docs/00-fundamentals.md) and review the base templates in [templates/](../templates/).
+* **Author a Custom Agent** — copy [templates/agents/modernization.agent.md](../templates/agents/modernization.agent.md) to `.github/agents/<name>.agent.md` in a target repo, replace every `{{PLACEHOLDER}}`, and tighten the tool allow-list so the assessment phase stays read-only (least privilege).
+* **Author a Skill** — copy [templates/skills/modernization-skill/SKILL.md](../templates/skills/modernization-skill/SKILL.md) to `.github/skills/<skill-name>/SKILL.md`, and write an explicit `WHEN:` trigger description plus at least one transformation-rules table. Optionally use the [skill-creator](../templates/skills/skill-creator/SKILL.md) meta-skill to iterate.
+* **Configure MCP** — copy [templates/mcp/mcp.json](../templates/mcp/mcp.json) to `.vscode/mcp.json`, then run **MCP: List Servers** and confirm the `appmod-*` tools (registered by the App Modernization extensions) appear in the agent's tool picker.
+* **Dry-run the loop** — select your Custom Agent in Copilot Chat and prompt it to modernize a sample. Confirm it **stops at Gate 1 (assessment)** and **Gate 2 (plan)** before editing any code.
+* Compare your work against the pre-tailored references shipped in [templates/](../templates/) (`dotnet-modernization.agent.md`, `dotnet-upgrade`, `java-modernization.agent.md`, `java-upgrade`).
 
 ## Success criteria
 
-* ContosoUniversity solution is forked, cloned, and builds locally.
-* The application is upgraded from .NET Framework to .NET 9 with a generated upgrade report.
-* Mandatory cloud readiness issues, including authentication migration to Microsoft Entra ID, are fully resolved.
-* Azure App Service deployment completes successfully and the modernized app runs in Azure.
+* You can explain, in one sentence each, what an Agent, a Skill, and an MCP server contribute to a modernization workflow.
+* A valid Custom Agent (`.agent.md` with YAML frontmatter) exists, with a phased, gated workflow and a least-privilege tool list.
+* A valid Skill (`SKILL.md`) exists with an explicit `WHEN:` trigger description and at least one rules table.
+* `.vscode/mcp.json` is configured and **MCP: List Servers** resolves the servers; the `appmod-*` tools are visible to the agent.
+* When run, the agent respects the gates — it does **not** modify code before the assessment and plan are approved.
 
 ## Learning resources
 
-* https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-extension
-* https://learn.microsoft.com/dotnet/architecture/modernize-with-azure-containers/
-* https://learn.microsoft.com/dotnet/core/migration/
-* https://learn.microsoft.com/azure/app-service/quickstart-dotnetcore
-* https://learn.microsoft.com/azure/active-directory/develop/quickstart-v2-aspnet-core-webapp
+* [Custom chat modes / agents in VS Code](https://code.visualstudio.com/docs/copilot/chat/chat-modes)
+* [MCP servers in VS Code](https://code.visualstudio.com/docs/copilot/chat/mcp-servers)
+* [GitHub Copilot app modernization for .NET](https://learn.microsoft.com/dotnet/core/porting/github-copilot-app-modernization-overview)
+* [GitHub Copilot app modernization for Java](https://learn.microsoft.com/azure/developer/java/migration/migrate-github-copilot-app-modernization-for-java)
+* [Model Context Protocol](https://modelcontextprotocol.io/)
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-02.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-02.md
@@ -1,38 +1,29 @@
-# Modernize the Asset Manager Java Application
+# Modernize a .NET Application
 
-[Previous Challenge Solution](challenge-01.md) - **[Home](../Readme.md)** - [Next Challenge Solution](finish.md)
+[Previous Challenge](challenge-01.md) - **[Home](../Readme.md)** - [Next Challenge](challenge-03.md)
 
 ## Goal
 
-Modernize the Asset Manager Spring Boot application for Azure by replacing AWS S3 dependencies with Azure services through the GitHub Copilot App Modernization workflow.
+Modernize the Contoso University .NET Framework application to .NET 9 and deploy it to Azure App Service using GitHub Copilot’s AI-assisted tooling.
 
 ## Actions
 
-* Prepare the workstation by launching Docker Desktop, cloning the `migrate-modernize-lab` repo, and opening `src/AssetManager` in VS Code.
-* Authenticate to GitHub, ensure the GitHub Copilot App Modernization extension (Claude Sonnet 4.5) is installed, and review prerequisite setup.
-* Run `scripts\startapp.cmd` to validate the existing containers (RabbitMQ, Postgres) and confirm the app is reachable at `http://localhost:8080`.
-* Launch the AppCAT assessment from the extension, track CLI installation, and wait for the identified cloud readiness issues and Java upgrade opportunities.
-* Review the assessment insights, focusing on the AWS S3 to Azure Blob Storage migration recommendation and understanding the priority levels.
-* Execute the guided migration task, inspect the generated `plan.md`, and continue the conversation to apply the proposed code refactoring.
-* Monitor `progress.md`, Maven/Gradle changes, configuration updates, and Spring Cloud Azure versions as the migration proceeds.
-* Allow the automated validation stages (CVE scans, builds, consistency checks, tests) to complete and remediate any issues flagged.
-* Re-run `scripts\startapp.cmd`, verify Blob Storage integration locally, and test application functionality end-to-end.
-* Optionally proceed with additional modernization tasks surfaced in the assessment to continue improving the workload.
+* Fork `https://github.com/crgarcia12/migrate-modernize-lab`, clone your fork in Visual Studio 2022, and confirm the ContosoUniversity project builds.
+* Use the Visual Studio “Modernize” flow to sign in to GitHub Copilot, select Claude Sonnet 4.5, and run the guided upgrade to .NET 9 until `dotnet-upgrade-report.md` is produced.
+* Rerun “Modernize” to start “Migrate to Azure,” review the cloud readiness assessment, and resolve authentication findings by migrating from Windows AD to Microsoft Entra ID.
+* Approve Copilot’s Azure App Service deployment workflow, wait for completion, and validate the site in Azure.
 
 ## Success criteria
 
-* Docker containers start successfully and the legacy app runs locally before changes.
-* AppCAT completes with nine cloud readiness issues and four Java upgrade opportunities identified.
-* The AWS S3 to Azure Blob Storage migration task executes with updated dependencies and configuration.
-* All automated validation stages pass without unresolved issues.
-* The modernized application starts locally using Azure Blob Storage with no storage errors.
-* Migration activities are traceable through dedicated plan and progress artifacts for rollback readiness.
+* ContosoUniversity solution is forked, cloned, and builds locally.
+* The application is upgraded from .NET Framework to .NET 9 with a generated upgrade report.
+* Mandatory cloud readiness issues, including authentication migration to Microsoft Entra ID, are fully resolved.
+* Azure App Service deployment completes successfully and the modernized app runs in Azure.
 
 ## Learning resources
 
-* [GitHub Copilot for VS Code](https://code.visualstudio.com/docs/copilot/overview)
-* [Azure SDK for Java](https://learn.microsoft.com/azure/developer/java/sdk/)
-* [Migrate from AWS to Azure](https://learn.microsoft.com/azure/architecture/aws-professional/)
-* [Azure Blob Storage for Java](https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-java)
-* [Spring Cloud Azure](https://learn.microsoft.com/azure/developer/java/spring-framework/)
-* [AppCAT Assessment Tool](https://learn.microsoft.com/azure/developer/java/migration/migration-toolkit-intro)
+* https://learn.microsoft.com/visualstudio/ide/visual-studio-github-copilot-extension
+* https://learn.microsoft.com/dotnet/architecture/modernize-with-azure-containers/
+* https://learn.microsoft.com/dotnet/core/migration/
+* https://learn.microsoft.com/azure/app-service/quickstart-dotnetcore
+* https://learn.microsoft.com/azure/active-directory/develop/quickstart-v2-aspnet-core-webapp
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-03.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/challenges/challenge-03.md
@@ -0,0 +1,38 @@
+# Modernize the Asset Manager Java Application
+
+[Previous Challenge](challenge-02.md) - **[Home](../Readme.md)** - [Finish](finish.md)
+
+## Goal
+
+Modernize the Asset Manager Spring Boot application for Azure by replacing AWS S3 dependencies with Azure services through the GitHub Copilot App Modernization workflow.
+
+## Actions
+
+* Prepare the workstation by launching Docker Desktop, cloning the `migrate-modernize-lab` repo, and opening `src/AssetManager` in VS Code.
+* Authenticate to GitHub, ensure the GitHub Copilot App Modernization extension (Claude Sonnet 4.5) is installed, and review prerequisite setup.
+* Run `scripts\startapp.cmd` to validate the existing containers (RabbitMQ, Postgres) and confirm the app is reachable at `http://localhost:8080`.
+* Launch the AppCAT assessment from the extension, track CLI installation, and wait for the identified cloud readiness issues and Java upgrade opportunities.
+* Review the assessment insights, focusing on the AWS S3 to Azure Blob Storage migration recommendation and understanding the priority levels.
+* Execute the guided migration task, inspect the generated `plan.md`, and continue the conversation to apply the proposed code refactoring.
+* Monitor `progress.md`, Maven/Gradle changes, configuration updates, and Spring Cloud Azure versions as the migration proceeds.
+* Allow the automated validation stages (CVE scans, builds, consistency checks, tests) to complete and remediate any issues flagged.
+* Re-run `scripts\startapp.cmd`, verify Blob Storage integration locally, and test application functionality end-to-end.
+* Optionally proceed with additional modernization tasks surfaced in the assessment to continue improving the workload.
+
+## Success criteria
+
+* Docker containers start successfully and the legacy app runs locally before changes.
+* AppCAT completes with nine cloud readiness issues and four Java upgrade opportunities identified.
+* The AWS S3 to Azure Blob Storage migration task executes with updated dependencies and configuration.
+* All automated validation stages pass without unresolved issues.
+* The modernized application starts locally using Azure Blob Storage with no storage errors.
+* Migration activities are traceable through dedicated plan and progress artifacts for rollback readiness.
+
+## Learning resources
+
+* [GitHub Copilot for VS Code](https://code.visualstudio.com/docs/copilot/overview)
+* [Azure SDK for Java](https://learn.microsoft.com/azure/developer/java/sdk/)
+* [Migrate from AWS to Azure](https://learn.microsoft.com/azure/architecture/aws-professional/)
+* [Azure Blob Storage for Java](https://learn.microsoft.com/azure/storage/blobs/storage-quickstart-blobs-java)
+* [Spring Cloud Azure](https://learn.microsoft.com/azure/developer/java/spring-framework/)
+* [AppCAT Assessment Tool](https://learn.microsoft.com/azure/developer/java/migration/migration-toolkit-intro)