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
| - _"We have a release deadline in two weeks—prioritize the web projects."_ | ||
| - _"The legacy reporting module should be excluded from this upgrade."_ | ||
|
|
||
| ### Explain your architecture |
Member
There was a problem hiding this comment.
Perhaps a note about having architecture documentation in the repo already (I bet there's some best practices guidance we could point to somewhere) would be useful here as well.
|
|
||
| ## Skills | ||
|
|
||
| _Skills_ are focused modernization capabilities—smaller, targeted upgrade operations. When the agent encounters EF6 code during an upgrade, it loads the EF6-to-EF-Core skill with detailed, step-by-step migration instructions. You can also invoke a skill directly: _"migrate the WCF services in my project to CoreWCF."_ |
Member
There was a problem hiding this comment.
There's an implication here that the skills can be invoked directly outside of the normal agent flow and I don't think that's really true right now since the embedded skills are only injected into the context as needed. That might cause more confusion for the user if they think they can cherry pick like that outside of the normal custom agent flow
|
|
||
| ### Cross-IDE continuity | ||
|
|
||
| Because state lives in Git, you can switch between VS Code and Visual Studio mid-upgrade. The `.github/upgrades/` folder is the shared state that both IDEs understand. |
|
|
||
| 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?
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