Azure · samvaity · Apr 1, 2026 · Mar 30, 2026 · Mar 31, 2026 · Mar 31, 2026
@@ -2,9 +2,9 @@
 name: generate-sdk-locally
 license: MIT
 metadata:
-  version: "1.0.0"
+  version: "1.1.0"
   distribution: shared
-description: "Generate, build, and test Azure SDKs locally from TypeSpec. **UTILITY SKILL**. USE FOR: \"generate SDK locally\", \"build SDK\", \"run SDK tests\", \"update changelog\". DO NOT USE FOR: publishing to package registries, CI pipeline configuration, API design review. INVOKES: azure-sdk-mcp:azsdk_package_generate_code, azure-sdk-mcp:azsdk_package_build_code, azure-sdk-mcp:azsdk_package_run_tests."
+description: "Generate, build, and test Azure SDKs locally from TypeSpec, with automatic customization to resolve build errors and apply SDK changes. **UTILITY SKILL**. USE FOR: \"generate SDK locally\", \"build SDK\", \"run SDK tests\", \"update changelog\", \"fix SDK build errors\", \"fix breaking changes\", \"resolve SDK generation errors\", \"customize TypeSpec\", \"apply TypeSpec customization\", \"rename SDK client\", \"rename SDK model\", \"hide operation from SDK\", \"fix analyzer errors\", \"fix compilation errors\", \"resolve customization drift\", \"create subclient\", \"apply client.tsp changes\". DO NOT USE FOR: publishing to package registries, CI pipeline configuration, API design review. INVOKES: azure-sdk-mcp:azsdk_package_generate_code, azure-sdk-mcp:azsdk_package_build_code, azure-sdk-mcp:azsdk_package_run_tests, azure-sdk-mcp:azsdk_customized_code_update."
 compatibility:
   requires: "azure-sdk-mcp server, local azure-sdk-for-{language} clone, language build tools"
 ---
@@ -19,25 +19,38 @@ compatibility:
 | `azure-sdk-mcp:azsdk_package_build_code` | Build package |
 | `azure-sdk-mcp:azsdk_package_run_check` | Validate package |
 | `azure-sdk-mcp:azsdk_package_run_tests` | Run tests |
+| `azure-sdk-mcp:azsdk_customized_code_update` | Apply TypeSpec and code customizations to resolve build errors, breaking changes, or SDK modification requests (includes regeneration and build internally) |
 
 **Prerequisites:** azure-sdk-mcp server must be running. Without MCP, use `npx tsp-client` CLI.
 
 ## Steps
 
 1. **Verify** — Run `azure-sdk-mcp:azsdk_verify_setup` to confirm environment.
 2. **Generate** — Run `azure-sdk-mcp:azsdk_package_generate_code` with `tspconfig.yaml` or `tsp-location.yaml` path.
-3. **Build** — Run `azure-sdk-mcp:azsdk_package_build_code`. On failure, use typespec-customization.
-4. **Validate** — Run `azure-sdk-mcp:azsdk_package_run_check` and `azure-sdk-mcp:azsdk_package_run_tests`.
-5. **Metadata** — Update metadata, changelog, and version. _(Note: For .NET data plane, skip this step — metadata, changelog, and version updates are per-commit tasks, not part of the generate/build/test workflow.)_
+3. **Build** — Run `azure-sdk-mcp:azsdk_package_build_code`. If the build succeeds, proceed to step 5.
+4. **Customize** — If build fails, or if the user requests SDK modifications, run `azure-sdk-mcp:azsdk_customized_code_update` with the build errors or user request. The tool handles the full workflow internally: it classifies the issue, applies TypeSpec decorators and/or code patches, regenerates the SDK, and builds — all in one call. See [customization workflow](references/customization-workflow.md).
+5. **Validate** — Run `azure-sdk-mcp:azsdk_package_run_check` and `azure-sdk-mcp:azsdk_package_run_tests`.
+6. **Metadata** — Update metadata, changelog, and version. _(Note: For .NET data plane, skip this step — metadata, changelog, and version updates are per-commit tasks, not part of the generate/build/test workflow.)_
 
 [SDK repos](references/sdk-repos.md)
+[Customization workflow](references/customization-workflow.md)
 
 ## Examples
 
 - "Generate the SDK locally for my TypeSpec service"
 - "Build and test the Python SDK package"
+- "Fix the SDK build errors on this PR"
+- "The SDK generation has breaking changes, resolve them"
+- "Rename FooClient to BarClient for .NET"
+- "Hide the internal polling operation from the Python SDK"
+- "Fix .NET analyzer errors AZC0030 and AZC0012"
+- "The build is failing because a customization references a renamed property"
+- "Create a subclient architecture for the Python SDK"
+- "Apply TypeSpec customizations to fix compilation errors"
 
 ## Troubleshooting
 
 - Run `azure-sdk-mcp:azsdk_verify_setup` to confirm MCP and tools.
+- If build fails with type conflicts, breaking changes, analyzer errors, or customization drift, use `azure-sdk-mcp:azsdk_customized_code_update` to apply customizations.
+- The customization tool uses a two-phase approach: TypeSpec decorators first (Phase A), then code repairs if needed (Phase B).
 - Without MCP, use `npx tsp-client` CLI.
@@ -0,0 +1,76 @@
+# TypeSpec Customization Workflow
+
+The customization workflow is an AI-assisted process that applies TypeSpec decorators and code repairs to ensure SDK functionality. It uses a two-phase approach: **Phase A** applies `client.tsp` decorators (~80% of issues), **Phase B** applies code-level repairs when builds still fail (~10%), and the remaining ~10% receive manual guidance.
+
+## Entry Points
+
+The customization tool (`azure-sdk-mcp:azsdk_customized_code_update`) can be triggered from multiple sources:
+
+| Entry Point | Description | Example |
+|-------------|-------------|---------|
+| **Build failures** | Compilation errors, analyzer violations, linting failures after SDK generation | `error CS0246: The type or namespace name 'FooModel' could not be found` |
+| **Breaking changes** | Output from breaking changes analysis tools detecting renamed/removed properties, changed types | `Breaking changes detected: FooOptions.timeout property type changed from int to Duration` |
+| **User prompts** | Natural language requests to modify SDK behavior | "Rename FooClient to BarClient for .NET" |
+| **API review feedback** | Feedback from APIView or PR comments on SDK naming/structure | "Model name doesn't follow .NET casing conventions" |
+| **.NET analyzer errors** | AZC0030 (naming violations), AZC0012 (generic type names), etc. | `AZC0030: Model name ends with 'Parameters'` |
+| **Customization drift** | Existing customization code references renamed/removed TypeSpec entities | `cannot find symbol: method getField(String)` |
+| **Duplicate field conflicts** | TypeSpec adds a property that already exists in manual customization code | `variable operationId is already defined in class AnalyzeOperationDetails` |
+
+## When to Use
+
+- Build fails after `azure-sdk-mcp:azsdk_package_build_code` with compilation errors
+- Type name conflicts with reserved keywords or existing types
+- Breaking changes from spec updates (renamed/removed properties, changed types)
+- API surface changes that require `client.tsp` customizations
+- .NET analyzer violations (AZC0030, AZC0012, etc.)
+- Renaming clients, models, or operations for specific language SDKs
+- Hiding internal operations from public SDK APIs
+- Restructuring client architecture (e.g., creating subclients)
+- Customization files reference entities that no longer exist after TypeSpec regeneration
+- Duplicate fields between generated code and manual customization code
+
+## Customization Steps
+
+1. **Capture context** — Collect the build error output, user request, or API review feedback.
+2. **Apply customization** — Run `azure-sdk-mcp:azsdk_customized_code_update` with the error/request context. The tool handles the full workflow internally:
+   - Classifies the request (TypeSpec fix, code patch, or manual guidance)
+   - Applies `client.tsp` decorators (Phase A)
+   - Regenerates the SDK automatically
+   - Builds to validate
+   - If build still fails and customization files exist, applies code patches (Phase B)
+   - Regenerates again (Java) and rebuilds
+3. **Validate** — Run `azure-sdk-mcp:azsdk_package_run_check` and `azure-sdk-mcp:azsdk_package_run_tests` to verify no regressions.
+4. **Review changes** — The tool leaves all changes uncommitted. Review with `git status`/`git diff` across both repos.
+
+## Common Scenarios
+
+| Scenario | Phase | Customization |
+|----------|-------|--------------|
+| Type name conflict with reserved keyword | A | Rename via `@@clientName` in `client.tsp` |
+| Property renamed in new API version | A | Add `@@clientName` to preserve backward compatibility |
+| .NET analyzer error (AZC0030, AZC0012) | A | Apply scoped `@@clientName` decorators to fix naming violations |
+| Hide internal operation from SDK | A | Apply `@@access` decorator with language scope |
+| Create subclient architecture | A | Use `@client` and `@clientInitialization` decorators |
+| API review naming feedback | A | Apply scoped `@@clientName` for specific language |
+| Duplicate field from customization conflict | B | Remove duplicate `addField()` from customization class |
+| Customization references renamed property | B | Update references in `_patch.py`, `*Customization.java`, or partial classes |
+| Feature request with no TypeSpec solution | Manual | Tool provides guidance to create customization infrastructure |
+
+## Two-Phase Workflow
+
+**Phase A — TypeSpec Customizations:**
+Apply `client.tsp` decorators (e.g., `@@clientName`, `@@access`, `@client`), regenerate SDK, validate build. Handles ~80% of issues.
+
+**Phase B — Code Customizations:**
+Activates automatically when Phase A build fails AND customization files exist (Java: `*Customization.java`, Python: `*_patch.py`, .NET: partial classes). Applies mechanical code repairs: duplicate removal, reference updates, import fixes. Handles ~10% of issues.
+
+**Manual Guidance:**
+When neither phase resolves the issue, or no customization files exist, the tool returns structured guidance for manual implementation.
+
+## Retry Logic
+
+The tool handles retries internally with a two-pass classification approach:
+1. First pass: classify feedback → apply TypeSpec fixes → regenerate → build
+2. Second pass: re-classify remaining items with build error context → apply code patches → rebuild
+3. If the tool response indicates build still failing, you can re-run `azure-sdk-mcp:azsdk_customized_code_update` with the updated error output
+4. Max 2 attempts per phase (4 total iterations within the tool)
@@ -19,5 +19,5 @@
 
 If build fails:
 
-- Check for TypeSpec customization needs → use `typespec-customization` skill
-- Regenerate SDK after fixing issues
+- Run `azure-sdk-mcp:azsdk_customized_code_update` — it handles classification, TypeSpec fixes, regeneration, and build internally
+- See [customization workflow](customization-workflow.md) for full details
@@ -0,0 +1,24 @@
+id: sdk-local-analyzer-errors-001
+name: Fix .NET Analyzer Errors via Customization
+description: |
+  Test that the skill triggers customization when .NET build fails
+  with analyzer errors like AZC0030 (naming violations) or AZC0012
+  (generic type names).
+tags:
+  - customization
+  - analyzer
+  - dotnet
+inputs:
+  prompt: "The .NET SDK build is failing with analyzer errors: AZC0030 says the model name ends with 'Parameters' and AZC0012 says type name 'Tasks' is too generic. Can you fix these?"
+expected:
+  output_contains:
+    - "customiz"
+    - "clientName"
+  output_excludes:
+    - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
+  behavior:
+    max_tool_calls: 10
+    max_response_time_ms: 60000
@@ -0,0 +1,26 @@
+id: sdk-local-breaking-changes-001
+name: Resolve Breaking Changes After Spec Update
+description: |
+  Test that the skill triggers customization when breaking changes
+  are detected after a TypeSpec specification update — properties
+  renamed, types changed, or customization code drifts.
+tags:
+  - customization
+  - breaking-changes
+  - full-workflow
+inputs:
+  prompt: "After regenerating the Java SDK, the build is failing because the service team renamed 'displayName' to 'name' in the TypeSpec. Our customization class still references getField('displayName') and it can't find the symbol. Can you fix this?"
+expected:
+  output_contains:
+    - "customiz"
+    - "TypeSpec"
+  output_excludes:
+    - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
+    - type: tool_called
+      tool_name: azsdk_package_build_code
+  behavior:
+    max_tool_calls: 12
+    max_response_time_ms: 120000
@@ -0,0 +1,26 @@
+id: sdk-local-customization-001
+name: Duplicate Field Conflict After TypeSpec Addition
+description: |
+  Test that the skill triggers TypeSpec customization when SDK build
+  fails because TypeSpec now generates a field that already exists
+  in manual customization code, causing a duplicate field error.
+tags:
+  - customization
+  - error-handling
+  - full-workflow
+inputs:
+  prompt: "The Java SDK build is failing after regeneration. The error says 'variable operationId is already defined in class AnalyzeOperationDetails'. It looks like the service team added operationId to the TypeSpec, but our DocumentIntelligenceCustomizations.java already injects that field manually. Can you fix this?"
+expected:
+  output_contains:
+    - "customiz"
+    - "duplicate"
+  output_excludes:
+    - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
+    - type: tool_called
+      tool_name: azsdk_package_build_code
+  behavior:
+    max_tool_calls: 12
+    max_response_time_ms: 120000
@@ -2,7 +2,7 @@ id: sdk-local-edge-001
 name: Build Failure Recovery
 description: |
   Test that the skill handles SDK build failures gracefully
-  and suggests TypeSpec customization if needed.
+  and uses TypeSpec customization to resolve errors.
 tags:
   - edge-case
   - error-handling
@@ -14,6 +14,9 @@ expected:
     - "client.tsp"
   output_excludes:
     - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
   behavior:
-    max_tool_calls: 5
-    max_response_time_ms: 30000
+    max_tool_calls: 8
+    max_response_time_ms: 60000
@@ -0,0 +1,23 @@
+id: sdk-local-hide-operation-001
+name: Hide Internal Operation from SDK
+description: |
+  Test that the skill triggers customization when user requests
+  hiding an internal operation from a specific language SDK.
+tags:
+  - customization
+  - user-prompt
+  - access-control
+inputs:
+  prompt: "Remove the get_create_project_status polling operation from the Python SDK public API. It's an internal operation that shouldn't be exposed to users."
+expected:
+  output_contains:
+    - "access"
+    - "client.tsp"
+  output_excludes:
+    - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
+  behavior:
+    max_tool_calls: 10
+    max_response_time_ms: 60000
@@ -0,0 +1,23 @@
+id: sdk-local-rename-client-001
+name: Rename SDK Client via TypeSpec Customization
+description: |
+  Test that the skill triggers TypeSpec customization when user
+  requests renaming a client or model for a specific language SDK.
+tags:
+  - customization
+  - user-prompt
+  - typespec
+inputs:
+  prompt: "Rename the AIProjectConnectionEntraIDCredential model to use 'Id' instead of 'ID' in the .NET SDK. This was flagged in API review."
+expected:
+  output_contains:
+    - "clientName"
+    - "client.tsp"
+  output_excludes:
+    - "cannot help"
+  outcomes:
+    - type: tool_called
+      tool_name: azsdk_customized_code_update
+  behavior:
+    max_tool_calls: 10
+    max_response_time_ms: 60000