Add maui-coding-guardrails and maui-current-apis skills#379
Open
jfversluis wants to merge 9 commits intodotnet:mainfrom
Open
Add maui-coding-guardrails and maui-current-apis skills#379jfversluis wants to merge 9 commits intodotnet:mainfrom
jfversluis wants to merge 9 commits intodotnet:mainfrom
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two new always-on guardrail skills to the dotnet-maui plugin to steer agents away from deprecated/obsolete MAUI APIs and common layout/control pitfalls, plus eval coverage to validate the behavior.
Changes:
- Added
maui-coding-guardrailsskill documentation with MAUI “never rules” and best-practice guidance. - Added
maui-current-apisskill documentation with a version/TFM reasoning framework and a deprecated API table. - Added new eval scenarios (5 each) to validate guardrail behavior for both skills.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/dotnet-maui/maui-current-apis/eval.yaml | New eval suite for deprecated API detection/replacement and TFM-aware guidance. |
| tests/dotnet-maui/maui-coding-guardrails/eval.yaml | New eval suite for MAUI control/layout guardrails and anti-pattern prevention. |
| plugins/dotnet-maui/skills/maui-current-apis/SKILL.md | New always-on skill doc for API currency and migration guardrails. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/SKILL.md | New always-on skill doc for baseline MAUI coding/layout guardrails. |
| plugins/dotnet-maui/plugin.json | Updated plugin description to reflect new guardrail capabilities. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Member
Author
|
/evaluate |
This comment was marked as outdated.
This comment was marked as outdated.
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two always-on guardrail skills to the dotnet-maui plugin to steer agents away from deprecated MAUI APIs and common MAUI layout/control anti-patterns, backed by eval scenarios and reference tables.
Changes:
- Adds new skills
maui-coding-guardrailsandmaui-current-apiswith structured SKILL guidance and references. - Adds eval scenarios for both skills under
tests/dotnet-maui/to validate guardrail behavior. - Updates
dotnet-mauiplugin description to reflect the expanded scope.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/dotnet-maui/maui-current-apis/eval.yaml | Adds eval coverage for deprecated API detection/replacement and TFM-aware guidance. |
| tests/dotnet-maui/maui-coding-guardrails/eval.yaml | Adds eval coverage for layout/control guardrails (ListView/Frame/renderers/SVG, etc.). |
| plugins/dotnet-maui/skills/maui-current-apis/references/deprecated-apis-net10.md | Adds a categorized deprecated API reference table for MAUI 10. |
| plugins/dotnet-maui/skills/maui-current-apis/SKILL.md | Defines rules for MAUI API currency and version/package detection guidance. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md | Adds a quick reference for MAUI controls and resource conventions. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/SKILL.md | Defines always-on layout/control/navigation/handler guardrails and pitfalls. |
| plugins/dotnet-maui/plugin.json | Updates plugin description to mention guardrails and API currency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
plugins/dotnet-maui/skills/maui-current-apis/references/deprecated-apis-net10.md
Outdated
Show resolved
Hide resolved
plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md
Outdated
Show resolved
Hide resolved
Member
Author
|
/evaluate |
This comment was marked as outdated.
This comment was marked as outdated.
Member
Author
|
/evaluate |
This comment was marked as outdated.
This comment was marked as outdated.
plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md
Outdated
Show resolved
Hide resolved
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two new .NET MAUI “always-on” guardrail skills to the dotnet-maui plugin, along with evaluation scenarios to validate behavior around deprecated APIs and common MAUI architectural/layout pitfalls.
Changes:
- Added
maui-coding-guardrailsskill content + control quick-reference. - Added
maui-current-apisskill content + .NET MAUI 10 deprecated API reference + eval scenarios. - Updated
dotnet-mauiplugin description to reflect the new skill coverage.
Reviewed changes
Copilot reviewed 7 out of 7 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/dotnet-maui/maui-current-apis/eval.yaml | New eval scenarios to validate deprecated API avoidance/replacements and version-aware guidance. |
| tests/dotnet-maui/maui-coding-guardrails/eval.yaml | New eval scenarios to validate layout/control/navigation/handler guardrails. |
| plugins/dotnet-maui/skills/maui-current-apis/SKILL.md | New skill instructions and inline deprecation tables; includes version detection guidance. |
| plugins/dotnet-maui/skills/maui-current-apis/references/deprecated-apis-net10.md | Supplemental deprecated API tables/reference content for .NET MAUI 10. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/SKILL.md | New always-on guardrail rules for layout/control/navigation/handlers/compiled bindings. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md | Control quick-reference tables and resource directory conventions. |
| plugins/dotnet-maui/plugin.json | Expanded plugin description to include guardrails and API currency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
plugins/dotnet-maui/skills/maui-current-apis/references/deprecated-apis-net10.md
Outdated
Show resolved
Hide resolved
plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md
Outdated
Show resolved
Hide resolved
Member
Author
|
/evaluate |
This comment was marked as outdated.
This comment was marked as outdated.
jfversluis
force-pushed
the
dev/jfversluis/maui-guardrails-skills
branch
from
1052ec5 to
07c5642
Compare
Member
Author
|
/evaluate |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two new .NET MAUI “guardrail” skills to the dotnet-maui plugin to steer agents away from deprecated APIs and common MAUI architecture/layout pitfalls, along with eval scenarios to validate the behavior.
Changes:
- Introduces
maui-coding-guardrailsskill (layout/control/navigation/handlers/compiled bindings guidance) plus a control quick-reference. - Introduces
maui-current-apisskill (version-aware deprecated API guidance for MAUI 8/9/10, plus MauiReactor/Blazor Hybrid notes). - Adds eval coverage for both skills and updates the plugin description to reflect the new capabilities.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/dotnet-maui/maui-current-apis/eval.yaml | Adds evaluation scenarios to verify deprecated API avoidance and version-aware guidance. |
| tests/dotnet-maui/maui-coding-guardrails/eval.yaml | Adds evaluation scenarios covering common MAUI layout/control/handler guardrails. |
| plugins/dotnet-maui/skills/maui-current-apis/SKILL.md | Defines the “current APIs” skill rules and inline deprecation tables for MAUI 10. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md | Adds a control quick-reference document for the guardrails skill. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/SKILL.md | Defines the “coding guardrails” skill rules and examples (layout, controls, handlers, bindings). |
| plugins/dotnet-maui/plugin.json | Updates plugin description to include guardrails and API currency. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
plugins/dotnet-maui/skills/maui-coding-guardrails/references/control-reference.md
Outdated
Show resolved
Hide resolved
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as off-topic.
This comment was marked as off-topic.
This comment was marked as outdated.
This comment was marked as outdated.
jonathanpeppers
approved these changes
Mar 17, 2026
Member
jonathanpeppers
left a comment
jonathanpeppers
left a comment
There was a problem hiding this comment.
The general wording looks good to me, but we should try to get the eval tests green.
Member
Author
|
/evaluate |
Contributor
Skill Validation Results
[1] (Isolated) Quality improved but weighted score is -8.7% due to: tokens (11567 → 25942), tool calls (0 → 2), time (10.1s → 15.0s) Model: claude-opus-4.6 | Judge: claude-opus-4.6 |
Member
Author
|
/evaluate |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds two new .NET MAUI skills (API currency + coding guardrails) along with evaluation scenarios, and updates the dotnet-maui plugin description to reflect the expanded scope.
Changes:
- Introduces
maui-current-apisskill content and corresponding eval scenarios focused on deprecated/removed API replacements. - Introduces
maui-coding-guardrailsskill content and corresponding eval scenarios focused on preferred layout/control/handler patterns. - Updates
plugins/dotnet-maui/plugin.jsondescription to include the new skill areas.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| tests/dotnet-maui/maui-current-apis/eval.yaml | New evaluation scenarios validating guidance for replacing deprecated/removed MAUI APIs. |
| tests/dotnet-maui/maui-coding-guardrails/eval.yaml | New evaluation scenarios enforcing recommended MAUI UI/control/handler guardrails. |
| plugins/dotnet-maui/skills/maui-current-apis/SKILL.md | New skill defining rules and replacement guidance for current MAUI APIs across versions. |
| plugins/dotnet-maui/skills/maui-coding-guardrails/SKILL.md | New skill defining layout/control/handler guardrails and compiled bindings guidance. |
| plugins/dotnet-maui/plugin.json | Expands plugin description to reflect the added skills. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
You can also share your feedback on Copilot code review. Take the survey.
Contributor
Skill Validation Results
[1] (Isolated) Quality unchanged but weighted score is -8.3% due to: tokens (11581 → 25858), tool calls (0 → 2), time (13.5s → 17.6s) Model: claude-opus-4.6 | Judge: claude-opus-4.6 |
Add two always-on guardrail skills for .NET MAUI development: - maui-coding-guardrails: Prevents use of obsolete controls (ListView, TableView, Frame), deprecated patterns (renderers, BackgroundColor), and common architectural mistakes (ScrollView inside StackLayout, mixing Shell with NavigationPage). Includes control reference tables, compiled bindings guidance, and handler customization patterns. - maui-current-apis: Prevents use of deprecated APIs across .NET MAUI versions. Includes a reasoning framework for detecting project TFM and library versions, comprehensive deprecated API tables for .NET MAUI 10, and guidance for MauiReactor and Blazor Hybrid scenarios. Both skills include eval scenarios for validation. Sourced from dotnet/maui#34429 (RFC by jfversluis), which consolidates work from davidortinau/maui-skills and github/awesome-copilot. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…eferences - Add output_not_contains for Frame, TableView in product list scenario - Fix StackLayout assertion to match tags with attributes (<StackLayout vs <StackLayout>) - Tighten MainThread assertion to require full MainThread.BeginInvokeOnMainThread - Add output_not_contains for Device.BeginInvokeOnMainThread - Add output_not_contains for DisplayAlertAsync/FadeToAsync in .NET 8 TFM scenario - Remove references to maui-performance and maui-unit-testing skills (not yet added) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Applied improvements identified by Claude Sonnet 4, GPT-5.1, and Claude Opus 4.5 reviewing against the Anthropic skill-creator best practices: maui-coding-guardrails: - Explain WHY behind every rule (mechanism, not just 'obsolete') e.g. ScrollView in StackLayout: infinite height prevents scrolling - De-duplicate: removed deprecated control details that belong in maui-current-apis, added cross-reference instead - Reorganized from flat NEVER table to themed sections (Layout, Controls, Navigation, Handler Architecture, Compiled Bindings) - Moved control quick-reference to references/control-reference.md - Softened tone: 'Avoid X because Y' instead of 'NEVER use X' - Added trigger keywords to description for better agent activation maui-current-apis: - Replaced 26-line Reasoning Framework with 3-line summary (the LLM already knows how to read a csproj; it needs to know THAT it should) - Moved full deprecated API tables to references/deprecated-apis-net10.md - Kept top-10 most common mistakes inline with WHY column - Added trigger keywords (Device.RuntimePlatform, SYSLIB, etc.) - Added WHY explanations (e.g. DependencyService is service locator anti-pattern, MessagingCenter leaked subscriptions) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The previous commit moved deprecated API tables to references/, but CI evals showed the model was timing out loading reference files. Inlining the tables keeps them in direct context — the model doesn't need an extra round-trip to read them. Kept the improved descriptions, WHY column, key rules with reasoning, and trigger keywords from the rewrite. Only change is tables are back inline instead of references-only. The references/deprecated-apis-net10.md file is retained as supplementary detail. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
…me warning - Halve frontmatter descriptions for both skills to reduce token count - Add⚠️ DO NOT USE Frame heading in maui-coding-guardrails SKILL.md - Add⚠️ DO NOT USE Frame callout in control-reference.md Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
All API tables are inline in SKILL.md (required for eval performance — reference file loading caused timeouts). Remove the orphaned supplementary file to avoid drift. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Compressed both SKILL.md files per reviewer feedback to reduce token cost in eval verdicts: maui-coding-guardrails: 197→122 lines, ~1856→~1031 tokens (-44%) maui-current-apis: 154→112 lines, ~1854→~1097 tokens (-41%) Changes: - Remove When to Use/Not sections (redundant with frontmatter description) - Merge subsection headers into bold inline text - Compress prose without losing mechanism explanations - Collapse redundant table columns and merge small tables - Condense MauiReactor/Blazor sections to compact bullets All rules, code examples, and WHY explanations are preserved. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replaced scenarios where baseline already scored 5.0 (no room for skill to improve), and simplified scenarios that caused timeouts. Changes per multi-model review (Sonnet 4, GPT-5.1, Opus 4.5): maui-coding-guardrails: - REPLACED ScrollView (baseline 5.0) → AndExpand no-op detection (LLMs don't know AndExpand is silently ignored in MAUI) - MODIFIED Handler: Entry→Picker, added ExportRenderer mention in prompt, added AppendToMapping assertion - MODIFIED Image: added BackgroundColor→Background check (LLMs miss this) maui-current-apis: - REPLACED TFM detection (baseline 5.0) → SafeAreaEdges (.NET 10 API that LLMs don't know about) - MODIFIED Device APIs: simplified from 5 to 2 replacements to avoid timeouts - MODIFIED Xamarin.Forms: added concrete DependencyService code snippet, tighter DI assertions - MODIFIED MessagingCenter: changed framing to 'won't compile' not just 'deprecated', added 'internal' assertion Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Further token reduction to improve eval efficiency verdicts: - maui-coding-guardrails: 1031→881 tokens (-15%), compressed prose - maui-current-apis: 1097→1030 tokens (-6%), compressed prose - Deleted control-reference.md (-895 tokens): duplicated main skill content and added runtime overhead without eval benefit Total token savings: ~1100 tokens per skill invocation. Prose compressed per Sonnet 4 / GPT-5.1 recommendations: - Merged multi-line sentences into single lines - Cut filler words (strictly, silently, etc.) - Shortened table cells - Removed redundant reference pointer Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
jfversluis
force-pushed
the
dev/jfversluis/maui-guardrails-skills
branch
from
87fa7b3 to
868e908
Compare
jonathanpeppers
approved these changes
Mar 20, 2026
Member
jonathanpeppers
left a comment
jonathanpeppers
left a comment
There was a problem hiding this comment.
This looks good to me now, if we are OK with the eval results.
(I don't know what they mean 😄)
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.
What
Adds two always-on guardrail skills to the
dotnet-mauiplugin that prevent the most common mistakes AI coding agents make with .NET MAUI.maui-coding-guardrails
Prevents architectural mistakes and obsolete pattern usage:
references/control-reference.mdwith full control quick-reference tablesmaui-current-apis
Prevents deprecated/obsolete API usage with version-aware guidance:
references/deprecated-apis-net10.mdwith supplementary detailWhy
Without these guardrails, AI coding agents frequently suggest deprecated APIs like
ListView,Device.RuntimePlatform,BackgroundColor, renderers, and Xamarin.Forms namespaces. These two skills correct default LLM behavior and serve as the foundation for all future MAUI skills.Design Decisions
coding-guardrailsowns architecture/layout patterns,current-apisowns API deprecation tables — no overlapSources
Adapted from dotnet/maui#34429 (RFC by @jfversluis), which consolidates work from:
dotnet-maui.agent.md)Reformatted to match dotnet/skills conventions. Content reviewed against the Anthropic skill-creator guide by Claude Sonnet 4, GPT-5.1, and Claude Opus 4.5.
Eval Results
Both skills show strong quality improvements with green overfitting scores:
Zero timeouts. Failed verdicts are efficiency-only (guardrail skills add tokens when the baseline was already perfect).
This is the first of several batches porting MAUI skills from the RFC.