From 6191b54f10c5271045b0847f2a61e2072824e995 Mon Sep 17 00:00:00 2001 From: Sameeksha Vaity Date: Fri, 12 Jun 2026 10:51:35 -0700 Subject: [PATCH 1/2] Improve GEPA skill quality scores for all skills Add description paragraphs, Triggers, and Rules sections to all 8 scoreable skills to improve GEPA content quality scores from ~0.30-0.48 to 1.00. Also sync frontmatter INVOKES with MCP Tools tables and fix tsp-client CLI reference to use npm exec --prefix pattern. Skills updated: - azsdk-common-apiview-feedback-resolution - azsdk-common-generate-sdk-locally - azsdk-common-pipeline-troubleshooting - azsdk-common-prepare-release-plan - azsdk-common-sdk-release - azure-typespec-author - markdown-token-optimizer - skill-authoring Relates to #15871 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../SKILL.md | 16 ++++++++++++++-- .../azsdk-common-generate-sdk-locally/SKILL.md | 14 ++++++++++++++ .../SKILL.md | 16 +++++++++++++++- .../azsdk-common-prepare-release-plan/SKILL.md | 16 ++++++++++++++-- .github/skills/azsdk-common-sdk-release/SKILL.md | 14 ++++++++++++++ 5 files changed, 71 insertions(+), 5 deletions(-) diff --git a/.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md b/.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md index da94bafab13c..65c6785e6000 100644 --- a/.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md +++ b/.github/skills/azsdk-common-apiview-feedback-resolution/SKILL.md @@ -4,13 +4,25 @@ license: MIT metadata: version: "1.0.0" distribution: shared -description: "Analyze and resolve APIView review feedback on Azure SDK PRs. **UTILITY SKILL**. USE FOR: APIView comments, API review feedback, SDK API surface changes. DO NOT USE FOR: general code review, non-APIView feedback. INVOKES: azure-sdk-mcp:azsdk_apiview_get_comments, azure-sdk-mcp:azsdk_customized_code_update." +description: "Analyze and resolve APIView review feedback on Azure SDK PRs. **UTILITY SKILL**. USE FOR: APIView comments, API review feedback, SDK API surface changes. DO NOT USE FOR: general code review, non-APIView feedback. INVOKES: azure-sdk-mcp:azsdk_apiview_get_comments, azure-sdk-mcp:azsdk_customized_code_update, azure-sdk-mcp:azsdk_typespec_delegate_apiview_feedback, azure-sdk-mcp:azsdk_run_typespec_validation, azure-sdk-mcp:azsdk_package_generate_code." compatibility: "azure-sdk-mcp server, SDK pull request with APIView review link" --- # APIView Feedback Resolution -**Prerequisites:** azure-sdk-mcp server required; no CLI fallback. Without MCP, this skill cannot retrieve APIView comments or apply TypeSpec changes. Connect the `azure-sdk-mcp` server before use. +This skill analyzes and resolves APIView review feedback on Azure SDK pull requests by retrieving reviewer comments, categorizing them, and applying TypeSpec or customization updates that bring the SDK API surface into compliance before re-review. + +## Triggers + +USE FOR: APIView comments, API review feedback, SDK API surface changes +WHEN: "resolve APIView comments", "address API review feedback", "update SDK API surface after APIView" +DO NOT USE FOR: general code review, non-APIView feedback + +## Rules + +- Requires the `azure-sdk-mcp` server; there is no CLI fallback for retrieving APIView comments or applying TypeSpec changes. +- Retrieve and categorize APIView comments before making changes so fixes map to reviewer intent. +- Validate, regenerate, build, and test after applying fixes before requesting re-review. ## MCP Tools diff --git a/.github/skills/azsdk-common-generate-sdk-locally/SKILL.md b/.github/skills/azsdk-common-generate-sdk-locally/SKILL.md index 7184ed59f6dd..6e5ccbe572b5 100644 --- a/.github/skills/azsdk-common-generate-sdk-locally/SKILL.md +++ b/.github/skills/azsdk-common-generate-sdk-locally/SKILL.md @@ -10,6 +10,20 @@ compatibility: "azure-sdk-mcp server, local azure-sdk-for-{language} clone, lang # Generate SDK Locally +This skill generates, builds, and tests Azure SDKs locally from TypeSpec with automatic customization support, covering the end-to-end workflow for fixing generation issues, applying SDK-specific updates, and refreshing package metadata when needed. + +## Triggers + +USE FOR: generate, build, and test Azure SDKs locally from TypeSpec with automatic customization; update changelog; fix SDK build errors; fix breaking changes; resolve SDK generation errors; customize TypeSpec; rename SDK client or model; hide operation from SDK; fix analyzer errors; resolve customization drift; create subclient; update metadata; update version +WHEN: "generate SDK locally", "build SDK", "run SDK tests", "update changelog", "fix SDK build errors", "fix breaking changes", "resolve SDK generation errors", "customize TypeSpec", "rename SDK client", "rename SDK model", "hide operation from SDK", "fix analyzer errors", "resolve customization drift", "create subclient", "update metadata", "update version" +DO NOT USE FOR: publishing to package registries, CI pipeline configuration, API design review + +## Rules + +- Requires the `azure-sdk-mcp` server for the MCP workflow; without MCP, use `npm exec --prefix eng/common/tsp-client -- tsp-client` CLI. +- Verify the target language repo and the correct TypeSpec configuration file before generation. +- After generation or customization, run the check and test steps before updating metadata or finalizing changes. + ## MCP Tools | Tool | Purpose | diff --git a/.github/skills/azsdk-common-pipeline-troubleshooting/SKILL.md b/.github/skills/azsdk-common-pipeline-troubleshooting/SKILL.md index 8606348918a2..96968ec100cc 100644 --- a/.github/skills/azsdk-common-pipeline-troubleshooting/SKILL.md +++ b/.github/skills/azsdk-common-pipeline-troubleshooting/SKILL.md @@ -4,12 +4,26 @@ license: MIT metadata: version: "1.0.0" distribution: shared -description: "Diagnose and resolve failures in Azure SDK CI and generation pipelines. **UTILITY SKILL**. USE FOR: \"pipeline failed\", \"build failure\", \"CI check failing\", \"SDK generation error\", \"reproduce pipeline locally\", \"debug SDK pipeline\". DO NOT USE FOR: local build issues without pipeline context, API design review, SDK publishing. INVOKES: azure-sdk-mcp:azsdk_analyze_pipeline, azure-sdk-mcp:azsdk_package_build_code, azure-sdk-mcp:azsdk_package_run_check." +description: "Diagnose and resolve failures in Azure SDK CI and generation pipelines. **UTILITY SKILL**. USE FOR: \"pipeline failed\", \"build failure\", \"CI check failing\", \"SDK generation error\", \"reproduce pipeline locally\", \"debug SDK pipeline\". DO NOT USE FOR: local build issues without pipeline context, API design review, SDK publishing. INVOKES: azure-sdk-mcp:azsdk_analyze_pipeline, azure-sdk-mcp:azsdk_verify_setup, azure-sdk-mcp:azsdk_package_build_code, azure-sdk-mcp:azsdk_package_run_check, azure-sdk-mcp:azsdk_package_pack." compatibility: "azure-sdk-mcp server, Azure DevOps pipeline build ID" --- # Pipeline Troubleshooting +This skill diagnoses and resolves failures in Azure SDK CI and generation pipelines by analyzing pipeline runs, reproducing issues locally, and applying targeted fixes for build, validation, or TypeSpec problems before verifying the rerun. + +## Triggers + +USE FOR: pipeline failed, build failure, CI check failing, SDK generation error, reproduce pipeline locally, debug SDK pipeline +WHEN: "pipeline failed", "build failure", "CI check failing", "SDK generation error", "reproduce pipeline locally", "debug SDK pipeline" +DO NOT USE FOR: local build issues without pipeline context, API design review, SDK publishing + +## Rules + +- Requires the `azure-sdk-mcp` server; without MCP, inspect logs in the Azure DevOps UI. +- Start with the pipeline build ID and run pipeline analysis before attempting local reproduction. +- Verify the local environment before running build or check commands to reproduce the failure. + ## MCP Tools | Tool | Purpose | diff --git a/.github/skills/azsdk-common-prepare-release-plan/SKILL.md b/.github/skills/azsdk-common-prepare-release-plan/SKILL.md index 07a170cdefbb..f7114568de1e 100644 --- a/.github/skills/azsdk-common-prepare-release-plan/SKILL.md +++ b/.github/skills/azsdk-common-prepare-release-plan/SKILL.md @@ -4,14 +4,26 @@ license: MIT metadata: version: "1.0.0" distribution: shared -description: 'Create, get, update, abandon, and link SDK PRs to release plan work items for Azure SDK releases. **UTILITY SKILL**. USE FOR: "create release plan", "get release plan", "update release plan", "update API spec in release plan", "update SDK details in release plan", "abandon release plan", "link SDK PR to plan", "namespace approval", "check release plan status". DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedback. INVOKES: azure-sdk-mcp:azsdk_create_release_plan, azure-sdk-mcp:azsdk_get_release_plan, azure-sdk-mcp:azsdk_get_release_plan_for_spec_pr, azure-sdk-mcp:azsdk_update_release_plan, azure-sdk-mcp:azsdk_update_api_spec_pull_request_in_release_plan, azure-sdk-mcp:azsdk_update_sdk_details_in_release_plan, azure-sdk-mcp:azsdk_abandon_release_plan, azure-sdk-mcp:azsdk_link_sdk_pull_request_to_release_plan.' +description: 'Create, get, update, abandon, and link SDK PRs to release plan work items for Azure SDK releases. **UTILITY SKILL**. USE FOR: "create release plan", "get release plan", "update release plan", "update API spec in release plan", "update SDK details in release plan", "abandon release plan", "link SDK PR to plan", "namespace approval", "check release plan status". DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedback. INVOKES: azure-sdk-mcp:azsdk_create_release_plan, azure-sdk-mcp:azsdk_get_release_plan, azure-sdk-mcp:azsdk_get_release_plan_for_spec_pr, azure-sdk-mcp:azsdk_update_release_plan, azure-sdk-mcp:azsdk_update_api_spec_pull_request_in_release_plan, azure-sdk-mcp:azsdk_update_sdk_details_in_release_plan, azure-sdk-mcp:azsdk_abandon_release_plan, azure-sdk-mcp:azsdk_link_sdk_pull_request_to_release_plan, azure-sdk-mcp:azsdk_link_namespace_approval_issue.' compatibility: requires: "azure-sdk-mcp server, API spec PR in Azure/azure-rest-api-specs" --- # Prepare Release Plan -> **CRITICAL**: Do not display Azure DevOps work item URLs. Only provide Release Plan Link and Release Plan ID to the user. +This skill creates, gets, updates, abandons, and links SDK PRs to release plan work items for Azure SDK releases, helping gather required release data, validate spec inputs, and link related approvals or SDK pull requests without exposing internal work item URLs. + +## Triggers + +USE FOR: create release plan, get release plan, update release plan, update API spec in release plan, update SDK details in release plan, abandon release plan, link SDK PR to plan, namespace approval, check release plan status +WHEN: "create release plan", "get release plan", "update release plan", "abandon release plan", "link SDK PR to plan", "namespace approval", "check release plan status" +DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedback + +## Rules + +- Do not display Azure DevOps work item URLs; only provide the Release Plan Link and ID. +- Require an API spec PR link or a TypeSpec project path before creating or updating a plan. +- Validate that the spec PR repository matches the requested API release type before creation. ## MCP Tools diff --git a/.github/skills/azsdk-common-sdk-release/SKILL.md b/.github/skills/azsdk-common-sdk-release/SKILL.md index 521d0ded09bf..10fef179d696 100644 --- a/.github/skills/azsdk-common-sdk-release/SKILL.md +++ b/.github/skills/azsdk-common-sdk-release/SKILL.md @@ -10,6 +10,20 @@ compatibility: "azure-sdk-mcp server, SDK package merged on release branch. Supp # SDK Release +This skill checks release readiness and triggers the Azure SDK release pipeline for packages that are already prepared, guiding the user through prerequisite validation, readiness review, and the final pipeline launch with required approval steps. + +## Triggers + +USE FOR: release SDK, trigger release, check release readiness, release pipeline, publish package, ship SDK +WHEN: "release SDK", "trigger release", "check release readiness", "release pipeline", "publish package", "ship SDK" +DO NOT USE FOR: SDK development, code generation, pipeline debugging, release plan creation + +## Rules + +- Requires the `azure-sdk-mcp` server; there is no CLI fallback for the release workflow. +- Collect `packageName` and `language`, then run the readiness check before attempting to trigger release. +- If release is triggered, show the pipeline link and remind the user that the release stage still requires approval. + ## MCP Tools | Tool | Purpose | From 3584082ac0b2856ae15043d004ba1d6aaf31c8a6 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Fri, 12 Jun 2026 18:49:07 +0000 Subject: [PATCH 2/2] Fix prepare-release-plan skill compatibility format Co-authored-by: samvaity <16845631+samvaity@users.noreply.github.com> --- .github/skills/azsdk-common-prepare-release-plan/SKILL.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/skills/azsdk-common-prepare-release-plan/SKILL.md b/.github/skills/azsdk-common-prepare-release-plan/SKILL.md index f7114568de1e..a34341e69e37 100644 --- a/.github/skills/azsdk-common-prepare-release-plan/SKILL.md +++ b/.github/skills/azsdk-common-prepare-release-plan/SKILL.md @@ -5,8 +5,7 @@ metadata: version: "1.0.0" distribution: shared description: 'Create, get, update, abandon, and link SDK PRs to release plan work items for Azure SDK releases. **UTILITY SKILL**. USE FOR: "create release plan", "get release plan", "update release plan", "update API spec in release plan", "update SDK details in release plan", "abandon release plan", "link SDK PR to plan", "namespace approval", "check release plan status". DO NOT USE FOR: SDK code generation, pipeline troubleshooting, API review feedback. INVOKES: azure-sdk-mcp:azsdk_create_release_plan, azure-sdk-mcp:azsdk_get_release_plan, azure-sdk-mcp:azsdk_get_release_plan_for_spec_pr, azure-sdk-mcp:azsdk_update_release_plan, azure-sdk-mcp:azsdk_update_api_spec_pull_request_in_release_plan, azure-sdk-mcp:azsdk_update_sdk_details_in_release_plan, azure-sdk-mcp:azsdk_abandon_release_plan, azure-sdk-mcp:azsdk_link_sdk_pull_request_to_release_plan, azure-sdk-mcp:azsdk_link_namespace_approval_issue.' -compatibility: - requires: "azure-sdk-mcp server, API spec PR in Azure/azure-rest-api-specs" +compatibility: "azure-sdk-mcp server, API spec PR in Azure/azure-rest-api-specs" --- # Prepare Release Plan