Draft
Conversation
- Update overview.md with 8 scenarios, VB support, new project types, four-phase workflow, upgrade strategies, flow modes, state management - Update install.md with correct VS Code extension name, VB support - Update faq.yml with new scenarios, version matrix, new Q&As - Update how-to-upgrade with upgrade options phase, flow modes - Create concepts.md covering scenarios, skills, tasks, workflow, state management, flow modes, and resumability - Create scenarios-and-skills.md with full reference of 8 scenarios and 30+ built-in migration skills organized by domain - Create best-practices.md with preparation, collaboration, pitfalls, recovery, security, and performance guidance - Create troubleshooting.md covering workflow, build, Git, performance, and customization issues - Update toc.yml and index.yml with new articles Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Create customization.md covering custom skills, custom scenarios, scenario artifact editing, chat customization, source control/branching, and skill loading priority with real-world examples - Create working-with-agent.md covering collaboration patterns, teaching preferences/corrections, flow modes, mid-session corrections, multi-session workflows, reviewing work, and quick reference phrase table - Update toc.yml and index.yml with both new articles - Update output.md with fact-check entries for both articles Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Shorten title for SEO compliance - Add periods to all scenario table 'What it does' rows - Fix 'end to end' to 'end-to-end' - Replace em-dashes with colons in section headings - Add CoreWCF GitHub link Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove assessment as a numbered phase. Assessment is now described as a preliminary step the agent performs before the three phases (upgrade options, planning, execution) begin. Updated across all 6 affected files: overview.md, concepts.md, how-to-upgrade-with-github-copilot.md, best-practices.md, troubleshooting.md, and working-with-agent.md. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add brief introductory paragraphs between H2 and H3 headings in best-practices.md (5 instances) and troubleshooting.md (4 instances) to comply with docs style requirement that consecutive headings must have content between them. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Add guidance to initialize a local Git repo for non-Git projects, with benefits list and example commands - Add note about editing plan.md directly with CAUTION about contradictory instructions - Add 'or stop the session manually' to agent-stuck-in-loop section Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR expands and restructures the GitHub Copilot modernization documentation set to make the user guide more complete, with new conceptual/reference articles and updated navigation and existing pages.
Changes:
- Adds five new documentation articles (concepts, scenarios/skills, best practices, troubleshooting, and working-with-agent).
- Updates existing overview, install, FAQ, and how-to content to align terminology (assessment + three-phase workflow) and add scenario/state details.
- Updates
toc.ymlandindex.ymlto surface the new content in navigation.
Reviewed changes
Copilot reviewed 14 out of 14 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/core/porting/github-copilot-app-modernization/working-with-agent.md | New guidance on collaborating with the agent across sessions and workflows. |
| docs/core/porting/github-copilot-app-modernization/troubleshooting.md | New troubleshooting guide organized by issue category. |
| docs/core/porting/github-copilot-app-modernization/toc.yml | Adds new articles to the TOC. |
| docs/core/porting/github-copilot-app-modernization/scenarios-and-skills.md | New reference for scenarios and built-in skills. |
| docs/core/porting/github-copilot-app-modernization/overview.md | Adds scenarios overview and expands workflow/state explanations. |
| docs/core/porting/github-copilot-app-modernization/install.md | Updates install instructions and clarifies environment setup details. |
| docs/core/porting/github-copilot-app-modernization/index.yml | Updates landing page links to include new articles. |
| docs/core/porting/github-copilot-app-modernization/how-to-upgrade-with-github-copilot.md | Updates how-to flow to include “upgrade options” and phase terminology. |
| docs/core/porting/github-copilot-app-modernization/how-to-custom-upgrade-instructions.md | Minor wording/format updates for instruction authoring and usage. |
| docs/core/porting/github-copilot-app-modernization/faq.yml | Expands FAQ answers (scenarios, versions, offline use, partial acceptance). |
| docs/core/porting/github-copilot-app-modernization/customization.md | New customization guide (skills, scenarios, artifacts, priority rules). |
| docs/core/porting/github-copilot-app-modernization/concepts.md | New core concepts article describing workflow, state, tasks, and modes. |
| docs/core/porting/github-copilot-app-modernization/best-practices.md | New best-practices guidance for successful upgrades. |
| .github/projects/ghcp/output.md | Adds an internal fact-check/decision log for the documentation update. |
docs/core/porting/github-copilot-app-modernization/troubleshooting.md
Outdated
Show resolved
Hide resolved
docs/core/porting/github-copilot-app-modernization/troubleshooting.md
Outdated
Show resolved
Hide resolved
docs/core/porting/github-copilot-app-modernization/working-with-agent.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Member
|
Will review more generally later today but wanted to point out that the instructions in |
tlmii
reviewed
Apr 8, 2026
|
|
||
| Skills are the primary extension point for the agent. A skill is a Markdown file with a metadata header that teaches the agent how to handle a specific migration, pattern, or task. | ||
|
|
||
| ### Where to place custom skills |
Member
There was a problem hiding this comment.
Should we mention skills acquired via plugin, since both Copilot CLI and VS Code support them?
Contributor
Author
There was a problem hiding this comment.
I'm not sure what you mean exactly. Do you mean the modernization agent plugin? Or plugin's in general (which would be IDE specific, right?)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Lots of updates according the new process the agent uses.
Added
best-practices.mdwith guidelines on preparing projects, collaborating with the agent, avoiding common pitfalls, and recovery.Added
concepts.mdto explain key concepts such as scenarios, skills, and tasks.Fixes #52597
Internal previews
Toggle expand/collapse