[skills] Improve macios-binding-creator skill by dalexsoto · Pull Request #25133 · dotnet/macios

dalexsoto · 2026-04-09T18:00:01Z

No description provided.

…member availability Training session evidence: sessions d8792953 (SystemConfiguration), 91f91750 (MediaSetup), 28911011 (Photos). User corrections showed two skill gaps: 1. Availability version determination: The skill previously directed agents to use SdkVersions.cs for ALL availability versions, which is only correct for brand-new APIs. When introducing a framework on a new platform (e.g., MediaSetup → MacCatalyst), the actual introduction version differs from the current SDK version. Now directs agents to use generated reference bindings as the primary source of truth for introduction versions. 2. Per-member enum availability: When adding new members to existing enums, each member needs its own availability attribute with the member's introduction version. Added explicit guidance and code example. Multi-model validation (Sonnet 4, GPT-5.1, Haiku 4.5): Before: Accuracy 2/5, Completeness 2/5, Clarity 2/5 After: Accuracy 5/5, Completeness 5/5, Clarity 5/5 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

…g-creator Add documentation for registering NativeObject subclasses as bgen marshal types, addressing a critical knowledge gap discovered during PrintCore binding work (session 1a7e421e). Without this guidance, agents default to IntPtr returns for protocol methods even when concrete managed wrappers exist, requiring extensive user intervention to discover the TypeCache + MarshalTypeList registration pattern. Changes: - New section 'NativeObject Return Types in Protocol Methods' in binding-patterns.md with full 5-step workflow: CORE_SOURCES → #if !COREBUILD guards → TypeCache registration → MarshalTypeList registration → use concrete types in API definitions - Enhanced frameworks.sources docs to explain FRAMEWORKNAME_CORE_SOURCES for making types visible to bgen's core assembly - Extended #if !COREBUILD guidance from struct-only to include NativeObject class shells (referencing StoreProductParameters.cs, CGColor.cs patterns) - Added cross-reference in SKILL.md Step 4 warning against IntPtr when managed NativeObject wrappers exist Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Train the macios-binding-creator skill based on ARKit binding session (62c564f6) where the agent needed user corrections for three issues: 1. Named types Ar* instead of AR* — the naming guidance was ambiguous about ObjC class prefixes vs .NET acronym rules. Added explicit rule that C# type names preserve ObjC prefix casing exactly (AR*, AV*, CG*) while .NET acronym rules only apply to property/method names. 2. Used MACOS_DOTNET_SOURCES instead of #if MONOMAC — added guidance and anti-pattern clarifying that preprocessor directives are preferred over platform-specific source file lists, with a table of available symbols. 3. Implemented callback handler with null safety issues — added new 'C Callback Handler Binding' section covering BlockLiteral trampoline and GCHandle patterns, with rules for null safety on nullable parameters and memory management ordering when replacing handlers. Also adds the training log documenting both training sessions (PrintCore and ARKit) with assessment, changes, and patterns learned. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

rolfbjarne · 2026-04-13T07:35:06Z

+**Outcome:** ✅ Changes kept. All five edits address direct user corrections or code review findings from the session.
+
+### Patterns Learned
+- **Type name prefix ≠ acronym** — The .NET "don't use all-caps acronyms" rule only applies within property/method names. ObjC type prefixes (AR*, AV*, CG*, CK*) are preserved exactly. The existing skill guidance was ambiguous enough for the agent to misapply it.


There can be acronyms within type names as well (NSURLSessionHandler); the prefix (NS) is kept upper-case, while the acronym inside the type name (URL) is not.

rolfbjarne · 2026-04-13T07:38:26Z

+
+#### Key Rules for Callback Handlers
+
+> ❌ **NEVER** access a nullable parameter (e.g., `DispatchQueue? queue`) without null-checking it first. If `handler` is null and `queue` is also null, calling `queue.GetHandle()` throws `NullReferenceException`. Check all nullable parameters before use on every code path.


This is wrong: calling .GetHandle() is safe (from a NullReferenceException perspective) - it'll return NativeHandle.Zero on a null instance.

rolfbjarne · 2026-04-13T07:40:38Z

+
+```csharp
+// macOS-only type or member
+#if MONOMAC


We should ideally use __MACOS__ over MONOMAC (eventually I'd like to remove the MONOMAC symbol completely, it's redundant to have two symbols with the same meaning).

rolfbjarne · 2026-04-13T07:41:02Z

+|--------|----------|
+| `MONOMAC` / `__MACOS__` | macOS |
+| `__IOS__` | iOS |
+| `TVOS` / `__TVOS__` | tvOS |


Same, prefer __TVOS__ over TVOS.

vs-mobiletools-engineering-service2 · 2026-04-17T15:21:22Z

✅ [CI Build #d10c652] Build passed (Build packages) ✅

Pipeline on Agent
Hash: d10c652faa37b5e29330a8fd5c83191c91362fd8 [PR build]

vs-mobiletools-engineering-service2 · 2026-04-17T15:27:31Z

✅ [PR Build #d10c652] Build passed (Detect API changes) ✅

Pipeline on Agent
Hash: d10c652faa37b5e29330a8fd5c83191c91362fd8 [PR build]

vs-mobiletools-engineering-service2 · 2026-04-17T15:39:52Z

✅ API diff for current PR / commit

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

✅ API diff vs stable

NET (empty diffs)

iOS: vsdrops gist ( No breaking changes )
tvOS: vsdrops gist ( No breaking changes )
MacCatalyst: vsdrops gist ( No breaking changes )
macOS: vsdrops gist ( No breaking changes )

ℹ️ Generator diff

Generator Diff: vsdrops (html) vsdrops (raw diff) gist (raw diff) - Please review changes)

Pipeline on Agent
Hash: d10c652faa37b5e29330a8fd5c83191c91362fd8 [PR build]

vs-mobiletools-engineering-service2 · 2026-04-17T15:48:20Z

✅ [CI Build #d10c652] Build passed (Build macOS tests) ✅

Pipeline on Agent
Hash: d10c652faa37b5e29330a8fd5c83191c91362fd8 [PR build]

vs-mobiletools-engineering-service2 · 2026-04-17T21:27:00Z

🔥 [CI Build #d10c652] Test results 🔥

Test results

❌ Tests failed on VSTS: test results

1 tests crashed, 0 tests failed, 153 tests passed.

Failures

❌ windows tests

🔥 Failed catastrophically on VSTS: test results - windows (no summary found).

Html Report (VSDrops) Download

Successes

✅ cecil: All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (iOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (MacCatalyst): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (macOS): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (Multiple platforms): All 1 tests passed. Html Report (VSDrops) Download
✅ dotnettests (tvOS): All 1 tests passed. Html Report (VSDrops) Download
✅ framework: All 2 tests passed. Html Report (VSDrops) Download
✅ fsharp: All 4 tests passed. Html Report (VSDrops) Download
✅ generator: All 5 tests passed. Html Report (VSDrops) Download
✅ interdependent-binding-projects: All 4 tests passed. Html Report (VSDrops) Download
✅ introspection: All 6 tests passed. Html Report (VSDrops) Download
✅ linker: All 44 tests passed. Html Report (VSDrops) Download
✅ monotouch (iOS): All 11 tests passed. Html Report (VSDrops) Download
✅ monotouch (MacCatalyst): All 15 tests passed. Html Report (VSDrops) Download
✅ monotouch (macOS): All 12 tests passed. Html Report (VSDrops) Download
✅ monotouch (tvOS): All 11 tests passed. Html Report (VSDrops) Download
✅ msbuild: All 2 tests passed. Html Report (VSDrops) Download
✅ sharpie: All 1 tests passed. Html Report (VSDrops) Download
✅ xcframework: All 4 tests passed. Html Report (VSDrops) Download
✅ xtro: All 1 tests passed. Html Report (VSDrops) Download

macOS tests

✅ Tests on macOS Monterey (12): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Ventura (13): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sonoma (14): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Sequoia (15): All 5 tests passed. Html Report (VSDrops) Download
✅ Tests on macOS Tahoe (26): All 5 tests passed. Html Report (VSDrops) Download

Linux Build Verification

✅ Linux build succeeded

Pipeline on Agent
Hash: d10c652faa37b5e29330a8fd5c83191c91362fd8 [PR build]

dalexsoto and others added 2 commits April 9, 2026 13:38

dalexsoto requested a review from rolfbjarne April 9, 2026 18:00

This comment has been minimized.

Sign in to view

dalexsoto force-pushed the dev/alex/moarskillz branch from 5704c2e to 6e8e111 Compare April 9, 2026 23:06

This comment has been minimized.

Sign in to view

More updates

bd8d5d8

This comment has been minimized.

Sign in to view

dalexsoto enabled auto-merge (squash) April 10, 2026 04:23

rolfbjarne requested changes Apr 13, 2026

View reviewed changes

Merge branch 'main' into dev/alex/moarskillz

d10c652

This comment has been minimized.

Sign in to view


		#### Key Rules for Callback Handlers

		> ❌ NEVER access a nullable parameter (e.g., `DispatchQueue? queue`) without null-checking it first. If `handler` is null and `queue` is also null, calling `queue.GetHandle()` throws `NullReferenceException`. Check all nullable parameters before use on every code path.

Conversation

dalexsoto commented Apr 9, 2026

Uh oh!

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

This comment has been minimized.

rolfbjarne Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rolfbjarne Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rolfbjarne Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

rolfbjarne Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Apr 17, 2026

✅ [CI Build #d10c652] Build passed (Build packages) ✅

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Apr 17, 2026

✅ [PR Build #d10c652] Build passed (Detect API changes) ✅

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Apr 17, 2026

✅ API diff for current PR / commit

✅ API diff vs stable

ℹ️ Generator diff

Uh oh!

This comment has been minimized.

vs-mobiletools-engineering-service2 commented Apr 17, 2026

✅ [CI Build #d10c652] Build passed (Build macOS tests) ✅

Uh oh!

vs-mobiletools-engineering-service2 commented Apr 17, 2026

🔥 [CI Build #d10c652] Test results 🔥

Test results

Failures

❌ windows tests

Successes

macOS tests

Linux Build Verification

Uh oh!

This comment has been minimized.

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants