Add Copilot instructions and skills for CsWinRT 3.0#2356
Merged
Sergio0694 merged 32 commits intostaging/3.0from Mar 21, 2026
Merged
Add Copilot instructions and skills for CsWinRT 3.0#2356Sergio0694 merged 32 commits intostaging/3.0from
Sergio0694 merged 32 commits intostaging/3.0from
Conversation
Add comprehensive Copilot instructions documenting the CsWinRT 3.0 architecture, project structure, build pipeline, and conventions. The instructions cover: - Project overview and core design principles - Architecture diagram (Mermaid) showing component relationships - Build pipeline flow from .winmd to final assemblies - Detailed descriptions of all 7 active projects - Code style conventions and naming patterns - Key technical concepts (COM interop model, type maps, vtables) - MSBuild property reference - Error ID ranges - Projection updates from CsWinRT 2.x Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Rename .github/instructions/copilot-instructions.md to .github/copilot-instructions.md without content changes. Reorganizes repository layout to place Copilot instructions directly under the .github directory for easier discovery.
Add comprehensive guidance for creating and maintaining GitHub Copilot CLI skills. The new SKILL.md defines the required folder structure, SKILL.md frontmatter rules (name must match folder), description best practices, body/workflow templates, optional metadata.json/references/scripts, troubleshooting steps for skills not appearing or triggering, and example minimal/full skills with a creation checklist.
Apply style and wording updates to .github/copilot-instructions.md: convert headings and list items to sentence case, standardize capitalization and punctuation, expand 'WinRT' to 'Windows Runtime' in explanatory contexts, and normalize formatting for consistency across the document.
Explain the motivation behind the reference projection architecture: - The CsWinRT 2.x bottleneck where all libraries had to update in lockstep with the CsWinRT version - How CsWinRT 3.0 solves this by shipping lightweight reference/forwarder DLLs and generating actual implementations at app build time - Why this matters for the ecosystem (independent updates, no friction, evolvable APIs) Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Replace terse bullets with a detailed two-point explanation: IL emission is required so the interop generator can access non-public types via [IgnoresAccessChecksTo] (not expressible in C#), enabling automatic marshalling without requiring developers to modify types. Also note that a source-generator approach would be both incomplete (missing IL-level metadata) and extremely expensive, causing IDE/IntelliSense slowdowns as seen in CsWinRT 2.x.
Explain the architectural motivation for the interop generator tool: - Full AOT compatibility requires discovering all marshallable types and pre-generating all vtables and COM interface data - A source generator could only analyze one project at a time, causing code duplication across assemblies (a known CsWinRT 2.x problem) and type map key conflicts with .NET 10 interop APIs - Running at the end of the build allows whole-application analysis, producing deduplicated, optimized marshalling code Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Replace the two separate diagrams (architecture + build pipeline) with a single unified diagram showing both flows: - WinRT Component NuGet Package: .winmd → cswinrt.exe → C# sources → csc.exe → reference assembly → cswinrtimplgen → forwarder impl .dll - Application Publishing: MyProject.dll → cswinrtprojectiongen (×3 for SDK, XAML, 3rd party) → cswinrtinteropgen → WinRT.Interop.dll Also add a note about precompiled SDK projection .dll-s that skip regeneration when the CsWinRT version matches the Windows SDK version. Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The IID optimizer was a legacy CsWinRT 2.x tool that no longer exists. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add an 'update-copilot-instructions' skill that performs an extensive analysis of all 7 CsWinRT 3.0 projects, the build pipeline, and code conventions, then updates .github/copilot-instructions.md to reflect any differences found (e.g. new files, changed diagnostics, updated MSBuild properties, etc.). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Normalize capitalization for Step headings (Steps 1–6) in .github/skills/update-copilot-instructions/SKILL.md by converting initial verbs to lowercase. This aligns the file with the repository style guidance that discourages unnecessary capitalization in headings and improves consistency.
The skill now includes a step to validate and update itself whenever significant codebase changes are discovered. This keeps the project list, per-project validation steps, and build pipeline checks in sync with the actual solution structure. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add project (8) WinRT.Sdk.Projection to the repository structure and project details sections. This project produces precompiled WinRT.Sdk.Projection.dll and WinRT.Sdk.Xaml.Projection.dll for each supported Windows SDK version, bundled in the CsWinRT NuGet package to speed up consumer builds. Also update the update-copilot-instructions skill to include this project in its validation checklist. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a 'testing' skill that helps add, update, or find tests across the 5 CsWinRT test project areas: 1. UnitTest - MSTest-based interop/marshalling/COM tests 2. FunctionalTests - standalone console apps testing trimming/AOT 3. SourceGenerator2Test - generator and analyzer tests with Roslyn 4. ObjectLifetimeTests - GC/reference tracking/XAML lifetime tests 5. AuthoringTest - WinRT component authoring validation (WIP) Includes decision table for test placement, code patterns for each project type, and style conventions. Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Add a 'diagnostic-analyzer' skill that guides creating new Roslyn diagnostic analyzers for the CsWinRT source generator project: 1. Add diagnostic descriptor in DiagnosticDescriptors.cs 2. Register in AnalyzerReleases.Shipped.md 3. Create analyzer class following established patterns 4. Add tests with both positive and negative cases Includes code templates, conventions, extension method reference, and commit grouping guidelines. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Add a 'pull-request' skill that handles creating well-structured PRs: - Target branch selection (master, staging/3.0, or explicit) - Diff analysis to generate title and description - Structured description with Summary, Motivation, and Changes sections - Automatic label selection from available repository labels - Always adds ManodasanW and Sergio0694 as reviewers (unless author) Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Passing markdown with backticks via --body causes the shell to mangle them (e.g. backtick-wrapped paths render with backslashes). Fix by writing the body to a temp file and using gh pr create --body-file. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The existing analyzers in the Diagnostics/Analyzers/ folder already serve as comprehensive references for code structure and patterns, making the inline example unnecessary. Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
Pull request overview
Adds a repository-wide Copilot context document for the CsWinRT 3.0 architecture and introduces several Copilot CLI skills to standardize common workflows (updating instructions, testing, analyzer authoring, and PR creation).
Changes:
- Add/refresh
.github/copilot-instructions.mddescribing CsWinRT 3.0 architecture, projects, build pipeline, and conventions. - Add new Copilot CLI skills under
.github/skills/for instructions maintenance, testing guidance, analyzer creation, PR creation, and skill development.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
.github/copilot-instructions.md |
Adds an architecture/conventions overview intended to be the authoritative Copilot context document. |
.github/skills/update-copilot-instructions/SKILL.md |
Defines a workflow for validating and refreshing the Copilot instructions against the actual repo state. |
.github/skills/testing/SKILL.md |
Documents where and how to add tests across the repo’s test suites. |
.github/skills/diagnostic-analyzer/SKILL.md |
Documents a workflow for adding new Roslyn analyzers/diagnostics to WinRT.SourceGenerator2. |
.github/skills/pull-request/SKILL.md |
Provides a repeatable process/template for authoring PRs (branch/labels/reviewers/body creation). |
.github/skills/skill-development/SKILL.md |
Documents how to structure and troubleshoot Copilot CLI skills. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Add a 'Feature switches' entry to the Key patterns section, explaining how WindowsRuntimeFeatureSwitches uses [FeatureSwitchDefinition] properties backed by AppContext switches and MSBuild RuntimeHostConfigurationOption items, enabling ILLink and ILC to treat them as constants and trim away code behind disabled switches. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Guides through adding a new [FeatureSwitchDefinition]-based switch in WindowsRuntimeFeatureSwitches.cs and the corresponding MSBuild property and RuntimeHostConfigurationOption in Microsoft.Windows.CsWinRT.targets. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Instead of always targeting the Release 3.0.0 section, the skill now instructs to add to the latest release by default, or create a new release section when the user specifies a version. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document Benchmarks, Projections (local testing only), Samples, TestWinRT submodule, build (Azure DevOps/Maestro), and eng directories. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document the WinRT test component for validating generated projection code patterns and cross-ABI control flow scenarios. Add it to the test placement table and as its own section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- Fix CsWinRTGenerateInteropAssembly2 default description to include Library+PublishAot condition - Add missing directories to WinRT.Runtime2 listing (Windows.Storage.Streams, Windows.UI.Xaml.Interop, Xaml.Attributes) - Fix analyzer count: 4 analyzers producing 9 diagnostics (not 8 analyzers) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- skill-development: fix missing space in 'pull request,or' typo - pull-request: clarify backtick rule to allow fenced code blocks - update-copilot-instructions: fix project count from 7 to 8 - testing: clarify '5 primary test areas' and note additional test projects Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove the trailing "otherwise `false`" clause from the CsWinRTGenerateInteropAssembly2 column in .github/copilot-instructions.md. This makes the auto condition wording clearer (now: "auto (`true` for Exe/WinExe, or Library with `PublishAot=true`)") and is a documentation-only change.
…tion Explain the WindowsRuntime.Internal.idl file that defines COM interop interfaces missing from Windows SDK metadata, the [ProjectionInternal] attribute that makes generated code internal, and the user-friendly extension methods in ComInteropExtensions.cs that wrap them. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Do not capitalize words after ':' unless they are proper nouns. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Lowercase words after ':' that are not proper nouns, in both copilot-instructions.md and the pull-request skill. Update copilot-instructions.md Co-Authored-By: Copilot <223556219+Copilot@users.noreply.github.com>
Sergio0694
force-pushed
the
copilot/add-instructions
branch
from
251c37e to
3908387
Compare
Add a new section to the WinRT.Runtime project documentation describing the two categories of types that are projected in this assembly rather than being auto-generated by cswinrt.exe: - Custom-mapped types: built-in .NET/BCL types mapped to WinRT types, with a complete table of all differently-named mappings. - Manually-projected types: WinRT types defined directly in WinRT.Runtime for customized marshalling or infrastructure code dependencies. Also documents the XAML namespace duality (Windows.UI.Xaml vs Microsoft.UI.Xaml) that affects IIDs and runtime class names. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
manodasanW
approved these changes
Mar 21, 2026
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
Add comprehensive Copilot instructions documenting the CsWinRT 3.0 architecture, and a set of Copilot skills to automate common development workflows.
Motivation
The CsWinRT 3.0 codebase is complex, with 8 interrelated projects, multiple build tools, and a multi-phase build pipeline. New contributors and AI assistants need detailed context to understand how the components fit together, where to make changes, and what patterns to follow. Without this documentation, every task requires extensive codebase exploration before any work can begin.
This PR provides:
Changes
.github/copilot-instructions.md: Comprehensive instructions file covering project overview, architecture diagram, design motivation (reference projections, interop generator), MSBuild properties, all 8 projects in detail, NuGet build pipeline, code style conventions, and key technical concepts.github/skills/update-copilot-instructions/SKILL.md: Skill to refresh the instructions file by analyzing all projects and updating stale information (includes self-maintenance step).github/skills/testing/SKILL.md: Skill for adding tests to the correct test project, covering all 5 test areas with patterns, conventions, and a decision table.github/skills/diagnostic-analyzer/SKILL.md: Skill for creating new Roslyn diagnostic analyzers with the established 4-step workflow.github/skills/pull-request/SKILL.md: Skill for creating well-structured pull requests with proper target branch, title, description, labels, and reviewers.github/skills/skill-development/SKILL.md: Skill for creating and improving Copilot CLI skills