Menu
Create a GitHub PR for API review by comparing a baseline API surface against a target tag or branch. Use this when the user wants to create an API review PR, compare API changes between versions, or review API surface differences for a package.
| name | create-api-review-pr |
| description | Create a GitHub PR for API review by comparing a baseline API surface against a target tag or branch. Use this when the user wants to create an API review PR, compare API changes between versions, or review API surface differences for a package. |
Creates a dedicated API review PR that shows the diff between a baseline release and a target tag or branch's API surface using scripts/api_md_workflow/create_api_review_pr.py.
If the user asks to create an API review PR for a new package, explain that new packages do not use API review PRs and stop. Do not gather script inputs or run create_api_review_pr.py for new packages.
gh CLI installed and authenticated (gh auth login), or GITHUB_TOKEN/GH_TOKEN set with permission to create and update pull requests in this repository.azpysdk must be installed (pip install -e ./eng/tools/azure-sdk-tools).pip install -r ./eng/apiview_reqs.txt).Ask the user for the following using vscode_askQuestions:
The Azure SDK package name (e.g. azure-storage-blob, azure-ai-projects, azure-servicebus, azure-planetarycomputer).
The release tag to use as the baseline for comparison. Tags follow the format <package-name>_<version> (e.g. azure-storage-blob_12.29.0).
<package-name>_<version>.The branch or PR to generate the "current" API surface from. Can be:
azure-storage-blob_12.30.0) — used directly as a tag refmain, feature-branch) — fetched from originowner:branch reference (e.g. someone:their-branch) — fetched from the forkorigin/mainBefore running the script:
sdk/*/<package-name> exists with a pyproject.toml or setup.py.git tag -l "<tag>" to confirm the tag exists. If the user provided a version like 12.29.0, construct the full tag as <package-name>_<version> and validate that.<package-name>_<version> and run git tag -l "<tag>".git status --porcelain and warn if there are uncommitted changes.This is a long-running operation. The script may take several minutes because it generates API surfaces for both the baseline and target, creates or reuses review branches, pushes branches, and then opens the draft PR. Do not treat quiet terminal periods during apistub generation as failure unless the command exits, prints an error, or waits for input.
If create_api_review_pr.py fails while running this skill, do not patch the script, modify package files, retry with workaround edits, or try to manually complete branch/PR creation. Stop the workflow, report the failure clearly, include the relevant error details, and suggest practical next steps.
If the script reports that there are no API differences, relay that message to the user and stop. Do not create branches or a PR manually.
Run the following command from the repository root:
python scripts/api_md_workflow/create_api_review_pr.py --package-name <package-name> --base <tag> [--target <target>]
Standard review (comparing a release tag to a PR branch):
python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-storage-blob --base azure-storage-blob_12.29.0 --target someone:feature-branch
Release-to-release review (comparing two package tags):
python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
Review against main (no target specified):
python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-cosmos --base azure-cosmos_4.14.0
The script will:
api.md for both baseline and targetapireview/base_<package>_<version> and apireview/review_<package>_<version> branchesgh pr create fails)During execution, report progress at major phases: baseline generation, target generation, branch creation or reuse, branch push, and PR creation. If the terminal is quiet, check whether the process is still running before assuming it is hung.
When the target is a tag, the PR body labels it as Target tag. Branch and fork targets are labeled as Working branch.
Report the PR URL to the user when complete.
Interactive wizard that walks service teams through creating a package-specific skill for their Azure SDK package. Scans the package, detects customization patterns, scaffolds a SKILL.md with references, and validates with vally lint. The skill is placed inside the package's .github/skills/ directory so find-package-skill discovers it automatically. WHEN: create package skill; add service skill; bootstrap skill for package; new package skill; skill for my SDK package; write skill for search; write skill for cosmos.
**UTILITY SKILL** — Must be consulted before making any changes to packages under sdk/. Discovers and loads package-specific domain knowledge that prevents common mistakes. WHEN: "add feature to package", "fix bug in package", "modify package code", "regenerate from typespec", "change client library".
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.
Generate an API markdown file and token file using ApiView. Use this when the user wants to generate an API markdown file and review API changes.
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.
Generate, build, and test Azure SDKs locally from TypeSpec with automatic customization. WHEN: "generate SDK locally", "build SDK", "run SDK tests", "run CI checks", "validate package", "run checks", "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. INVOKES: azsdk_verify_setup, azsdk_package_generate_code, azsdk_package_build_code, azsdk_package_run_check, azsdk_package_run_tests, azsdk_customized_code_update, azsdk_package_update_changelog_content, azsdk_package_update_metadata, azsdk_package_update_version.