Marco Weber (qxsch) · Nov 5, 2026 · Nov 5, 2026
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/.gitignore b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/.gitignore
@@ -123,3 +123,9 @@ build/
 .project
 .settings/
 .factorypath
+
+# Sample application clones (created by docs/environment-setup.md)
+repos/
+
+# modernize CLI artifacts (repos.json, assessment reports, plans)
+.github/modernize/
diff --git a/03-Azure/01-01-App Innovation/03_GHCPAppModernization/Readme.md b/03-Azure/01-01-App Innovation/03_GHCPAppModernization/Readme.md
@@ -5,7 +5,6 @@
 - [**Objectives**](#objectives)
 - [**Environment setup**](#environment-setup)
 - [**MicroHack challenges**](#microhack-challenges)
-- [**Contributors**](#contributors)
 
 # MicroHack introduction
 
@@ -23,7 +22,7 @@ Across the challenges you will work with **PhotoAlbum** and **PhotoAlbum-Java**
 
 After completing this MicroHack you will:
 
-- Know how to author a **Custom Agent** (`.agent.md`), package a reusable **Skill** (`SKILL.md`), and configure **MCP** (`mcp.json`), and understand the gated assess → plan → execute → validate loop.
+- Know how to author a **Custom Agent** (`.agent.md`), package a reusable **Skill** (`SKILL.md`), and configure **MCP** (`.github/mcp.json` for GitHub Copilot CLI), and understand the gated assess → plan → execute → validate loop.
 - Understand how to use the GitHub Copilot App Modernization agent (modernize CLI).
 - Know how to assess applications for cloud readiness and framework upgrade opportunities.
 - Be able to upgrade .NET and Java applications to their latest framework versions.
@@ -40,19 +39,19 @@ This MicroHack has a few but important prerequisites.
 In order to use the MicroHack time most effectively, the following should be in place before you start:
 
 - An **Azure Subscription** with permission to create resource groups and resources (Contributor or Owner).
-- A **GitHub account** to fork the sample repositories.
+- A **GitHub account** to sign in to GitHub Copilot and clone the sample repositories.
 - An active **GitHub Copilot** subscription.
-- For the recommended Codespaces setup: permission to create a Codespace from your MicroHack fork.
-- For a local setup: **Visual Studio Code**, the **GitHub Copilot App Modernization agent (modernize CLI)**, **GitHub CLI**, **Azure CLI**, **Docker Desktop**, **Git**, and the relevant SDKs (.NET and Java).
+- For the recommended Codespaces setup: permission to create a Codespace from the MicroHack repository (or a fork of it).
+- For a local setup: **Visual Studio Code**, the **GitHub Copilot App Modernization agent (modernize CLI)**, **GitHub Copilot CLI**, **GitHub CLI**, **Azure CLI**, **Docker Desktop**, **Git**, and the relevant SDKs (.NET and Java).
 
-GitHub Codespaces is the recommended environment for this MicroHack. The dedicated **Azure / App Innovation / GHCP App Modernization** development container installs the required tools consistently for all participants.
+GitHub Codespaces is the **supported environment** for this MicroHack — local setups are best-effort. The dedicated **Azure / App Innovation / GHCP App Modernization** development container installs the required tools consistently for all participants.
 
 Complete the [environment setup guide](docs/environment-setup.md) before starting the challenges. It covers:
 
 - creating a Codespace with the correct development container,
 - verifying the modernization and platform tools,
 - signing in to GitHub for GitHub Copilot and signing in to Azure,
-- forking and cloning both sample applications, and
+- cloning both sample applications, and
 - troubleshooting installation, authentication, SSO, and repository access.
 
 # MicroHack challenges

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,42 +1,52 @@
-# Fundamentals — Custom Agents, Skills & MCP for App Modernization
+# 1. Fundamentals — Custom Agents, Skills & MCP for App Modernization
 
 **[Home](../Readme.md)** - [Next Challenge](challenge-02.md)
 
 ## Goal
 
-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.
+Build the AI foundation you will reuse in the next challenges. Learn how **Custom Agents**, **Skills**, and **MCP (Model Context Protocol)** servers fit together, then author your own modernization Custom Agent, package a reusable Skill, and configure MCP for **GitHub Copilot CLI** — all inside the target repository, where both Copilot CLI and the **modernize CLI** pick them up.
+
+> ⚙️ Complete the [environment setup](../docs/environment-setup.md) first. It creates the recommended Codespace (Copilot CLI and modernize CLI preinstalled) and clones the two sample apps into `repos/`.
 
 ## Scenario
 
-Before pointing AI at a real .NET or Java application (challenges 2 and 3), you assemble a reusable, gated modernization playbook:
+Before pointing AI at a real .NET or Java application (challenges 2 and 3), you assemble a reusable, gated modernization playbook. Everything is authored once in the target repository under `.github/`, so it travels with the code and works across surfaces:
+
+- an **Agent** (`.github/agents/`) that defines *who* is working and *how* the assess → plan → execute → validate loop runs (with approval gates),
+- a **Skill** (`.github/skills/`) that packages the *domain knowledge* (migration rules, breaking-changes checklist) — the modernize CLI auto-detects these skills when it creates a plan,
+- an **MCP** configuration (`.github/mcp.json`) that gives the agent extra *tools* to act (Azure resource queries, quotas, deployments, diagnostics).
 
-- 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).
+Use **`repos/PhotoAlbum-Java`** (cloned during environment setup) as the target repository — it is the same app you upgrade in Challenge 2.
 
 > 📖 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
 
 * 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.
+* **Author a Custom Agent** — copy [templates/agents/modernization.agent.md](../templates/agents/modernization.agent.md) to `.github/agents/<name>.agent.md` in the target repo, replace every `{{PLACEHOLDER}}`, and keep the tool allow-list least-privilege. Verify it: run `copilot` inside the repo (confirm folder trust when prompted — you are asked once per folder) and pick your agent with `/agent`.
+* **Author a Skill** — copy [templates/skills/modernization-skill/SKILL.md](../templates/skills/modernization-skill/SKILL.md) to `.github/skills/<skill-name>/SKILL.md` (lowercase, hyphenated folder name), set the frontmatter `name:` to match the folder, and write an explicit `WHEN:` trigger description plus at least one transformation-rules table. The `description` is what both Copilot CLI and the modernize CLI match against your prompt. Verify it: `/skills list` in Copilot CLI. Optionally use the [skill-creator](../templates/skills/skill-creator/SKILL.md) meta-skill to iterate.
+* **Configure MCP for Copilot CLI** — copy [templates/mcp/copilot-cli-mcp.json](../templates/mcp/copilot-cli-mcp.json) to `.github/mcp.json` in the target repo. Verify it: inside `copilot`, run `/mcp list` — the `azure` server appears (project MCP servers load only in trusted folders; the GitHub MCP server is built in and needs no entry).
+* **Dry-run skill detection** — from the target repo, run `modernize plan create "<a prompt that matches your skill's description>"` and confirm the generated plan under `.github/modernize/` references your skill with `"location": "project"` in its `tasks.json`. Create the plan only — execution happens in challenges 2 and 3. Finally, commit your authored `.github/` files on the `modernize` branch so the repository is clean for Challenge 2.
 * 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
 
 * 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.
+* A valid Custom Agent (`.agent.md` with YAML frontmatter) exists in `.github/agents/`, has a phased, gated workflow and a least-privilege tool list, and shows up in Copilot CLI's `/agent` picker.
+* A valid Skill (`SKILL.md`) exists in `.github/skills/<skill-name>/` with an explicit `WHEN:` trigger description and at least one rules table, and `/skills list` shows it.
+* `.github/mcp.json` resolves in Copilot CLI: `/mcp list` shows the `azure` server.
+* A modernize CLI plan created from your prompt references your custom skill in its `tasks.json` — and you have **not** executed the plan.
+
+> 💻 **Using VS Code instead of the CLI?** The same `.github/agents/` files are picked up by VS Code's agent picker. MCP is configured differently there: copy [templates/mcp/mcp.json](../templates/mcp/mcp.json) to `.vscode/mcp.json` and run **MCP: List Servers** — the formats are not interchangeable, and Copilot CLI does not read `.vscode/mcp.json`. The `appmod-*` tool families come from the GitHub Copilot app modernization VS Code extensions; install the one for your stack if you work in the IDE.
 
 > Need the detailed, step-by-step walkthrough? See the [Challenge 1 Solution](../walkthrough/challenge-01/solution-01.md).
 
 ## Learning resources
 
-* [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)
+* [About custom agents](https://docs.github.com/en/copilot/concepts/agents/about-custom-agents) and the [custom agents configuration reference](https://docs.github.com/en/copilot/reference/custom-agents-configuration)
+* [Add agent skills to Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills) · [Agent skills specification](https://agentskills.io/specification)
+* [Add MCP servers to Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)
+* [Customize the modernization agent with your own skills](https://learn.microsoft.com/azure/developer/github-copilot-app-modernization/modernization-agent/customization)
+* [GitHub Copilot app modernization for .NET](https://learn.microsoft.com/dotnet/azure/migration/appmod/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
@@ -9,30 +9,29 @@ Use the GitHub Copilot App Modernization agent (modernize CLI) to assess and upg
 ## Actions
 
 * Complete the [environment setup guide](../docs/environment-setup.md), including GitHub and Azure authentication and the tool verification steps.
-* Fork the two sample repositories into your own GitHub account:
+* Make sure the two sample repositories are cloned into the `repos/` working directory (done during environment setup — no forking needed) and that each is on its local `modernize` branch:
   * PhotoAlbum-Java (Spring Boot): `https://github.com/Azure-Samples/PhotoAlbum-Java`
   * PhotoAlbum (.NET): `https://github.com/Azure-Samples/PhotoAlbum`
-* Clone both forks into the `repos/` working directory created by the environment setup. Confirm that each `origin` points to your fork.
 * Use the preinstalled GitHub Copilot App Modernization agent (modernize CLI) in the recommended Codespace, or install it as described in the environment setup for a local workstation. You will use it end-to-end for assessment, upgrade, planning, and execution.
-* Create a repositories config file so the CLI can operate on both apps in a single batch run.
-* Run a **batch assessment** across both repositories, selecting the *Upgrade* and *Cloud readiness* analyses with full analysis coverage. Let the assessment run locally and wait for it to complete.
-* Explore the assessment output: the **aggregated report** (overall recommendations, target platforms, upgrade paths, and migration waves) and the **per-repository reports** (detailed findings per app).
+* Create the repositories config file at `.github/modernize/repos.json` in the hack working directory, using local `path` entries that point at the two clones in `repos/` — the CLI then operates on your local working copies in a single batch run instead of cloning fresh ones.
+* Run a **batch assessment** across both repositories, selecting the *Upgrade* and *Cloud readiness* analyses with full analysis coverage, and verify the upgrade targets on the configuration page (**.NET 10** and **OpenJDK 25**). Let the assessment run locally and wait for it to complete.
+* Explore the assessment output in `.github/modernize/assessment/`: the **aggregated report** (overall recommendations, target platforms, upgrade paths, and migration waves) and the **per-repository reports** (detailed findings per app).
 * Because a batch upgrade requires both repositories to share the same language, **upgrade each app individually**:
   * Upgrade the .NET app to the version recommended in the assessment (.NET 10).
   * Upgrade the Java app to the versions recommended in the assessment (Java 25 and Spring Boot 4.0).
-* Confirm each upgrade reports success, then commit and push the changes to each respective forked repository.
+* Confirm each upgrade reports success, then commit the changes on each repository's `modernize` branch. (Optional) Publish a repository to your own GitHub account with `gh repo create` if you want a remote copy — the upstream `Azure-Samples` repositories are read-only.
 
 > [!TIP]
-> The assessment and each upgrade can take several minutes to run. Review the generated reports while you wait — they explain *why* each recommendation was made.
+> With full analysis coverage, the batch assessment takes roughly 10-20 minutes for the two repositories, and each upgrade can take 15-45 minutes. Review the generated reports while you wait — they explain *why* each recommendation was made.
 
 ## Success criteria
 
-* Both PhotoAlbum-Java and PhotoAlbum are forked and available in your working directory.
-* GitHub CLI is authenticated with the GitHub account that has Copilot access, and both application remotes point to forks where you can push.
+* Both PhotoAlbum-Java and PhotoAlbum are cloned into `repos/` and checked out on their local `modernize` branch.
+* GitHub CLI is authenticated with the GitHub account that has Copilot access.
 * The modernize CLI is installed and configured to target both repositories from a config file.
 * A batch assessment completes and produces both an aggregated report and per-repository reports.
 * The .NET app is upgraded to .NET 10 and the Java app is upgraded to Java 25 / Spring Boot 4.0, each reporting a successful upgrade.
-* All upgrade changes are committed and pushed to the respective remote repositories.
+* All upgrade changes are committed on the `modernize` branch of each repository.
 
 > Need the detailed, step-by-step walkthrough? See the [Challenge 2 Solution](../walkthrough/challenge-02/solution-02.md).