From eba6b6950e1df1225e3ef137b80e2e4595f604c4 Mon Sep 17 00:00:00 2001 From: audreyttt Date: Thu, 11 Jun 2026 13:17:50 -0400 Subject: [PATCH 1/3] Initial skill --- .../skills/azure-ps-design-review/SKILL.md | 435 ++++++++++++++++++ .../references/design-guidelines-summary.md | 96 ++++ .../references/issue-template.md | 159 +++++++ .../azure-ps-design-review/scratch/.gitignore | 3 + 4 files changed, 693 insertions(+) create mode 100644 .github/skills/azure-ps-design-review/SKILL.md create mode 100644 .github/skills/azure-ps-design-review/references/design-guidelines-summary.md create mode 100644 .github/skills/azure-ps-design-review/references/issue-template.md create mode 100644 .github/skills/azure-ps-design-review/scratch/.gitignore diff --git a/.github/skills/azure-ps-design-review/SKILL.md b/.github/skills/azure-ps-design-review/SKILL.md new file mode 100644 index 000000000000..86f0cca7eaab --- /dev/null +++ b/.github/skills/azure-ps-design-review/SKILL.md @@ -0,0 +1,435 @@ +--- +name: azure-ps-design-review +license: MIT +metadata: + version: "1.0.0" +description: "Conversational agent that guides developers through creating complete Azure PowerShell cmdlet design specifications. Walks through an interactive interview covering service release details, contacts, scenarios, cmdlet syntax, parameter sets, piping, test cases, and spec links. Validates against PowerShell design guidelines, pre-populates fields from TypeSpec, and files the design as a GitHub Issue in Azure/azure-powershell-cmdlet-review-pr. USE FOR: 'create PowerShell design', 'PS design review', 'cmdlet design', 'PowerShell cmdlet review', 'submit PS design'. DO NOT USE FOR: SDK generation, TypeSpec authoring, releasing packages." +compatibility: + requires: "GitHub MCP Server for issue creation in Azure/azure-powershell-cmdlet-review-pr; TypeSpec files in the current repo for pre-population" +--- + +# Azure PowerShell Cmdlet Design Review + +A conversational skill that guides developers through building a complete PowerShell cmdlet design specification and submitting it for review. + +## MCP Tools + +**Prerequisite:** The GitHub MCP server must be configured and running. If any MCP tool call fails with a connection or server error, instruct the developer to add the following to their VS Code MCP configuration file (`.vscode/mcp.json` or the workspace `.mcp.json`): + +```json +{ + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/" + } + } +} +``` + +Then reload the VS Code window and retry. + +| Tool | Purpose | +| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `github-mcp-server:get_file_contents` | **Primary tool for reading PR changes.** Read TypeSpec files from the PR branch (`refs/pull/{number}/head`) and base branch to diff and identify new/changed resources. | +| `github-mcp-server:create_issue` | Create the design review issue in `Azure/azure-powershell-cmdlet-review-pr` | +| `github-mcp-server:search_code` | Search for existing cmdlet patterns in `Azure/azure-powershell` for consistency | +| `github-mcp-server:list_issues` | Check for existing design reviews to avoid duplicates | + +## Constraints + +- **Always follow the full interview workflow** — do not skip sections even if the developer says "just file it." +- **Validate every section** against the [design guidelines](references/design-guidelines-summary.md) before moving on. +- **Pre-populate from TypeSpec when possible** — read the developer's TypeSpec to extract resource models, operations, and parameter types. +- **Never file an incomplete issue** — all required fields must be populated before creating the GitHub Issue. +- **Label issues correctly** — apply the `needs-review` label and use the `{MODULE} - {FEATURE}` title format. +- **Always append the telemetry tag** — every issue body must end with `> _Created with help from PS design skill_` for tracking. Never omit this line. +- **Compute module focus** — this skill is initially scoped to Compute but the workflow generalizes to any module. +- **Use scratch files for multi-line input** — never ask for cmdlet syntax, piping examples, sample usage, feature descriptions, or business logic in the chat box. Always create a scratch `.md` file and open it in the editor. See [Scratch File Pattern](#scratch-file-pattern-for-long-form-input). +- **Use GitHub MCP Server for ALL GitHub operations** — do NOT use `gh` CLI, `git` commands, `curl`, PowerShell, shell commands, or any other workaround to read PR data, fetch file contents, list files, or create issues. The **only** way to interact with GitHub is through `github-mcp-server` tools. If a tool call fails, do NOT fall back to shell commands — instead display the MCP setup instructions above and ask the developer to configure the server. + +--- + +## Scratch File Pattern for Long-Form Input + +Several interview steps require multi-line input (cmdlet syntax blocks, piping examples, end-to-end samples) that is difficult to type in the Copilot Chat input box. For these steps, the agent **must** use a scratch file instead of asking the developer to paste into chat. + +**How it works**: + +1. The agent creates a temporary Markdown file at `.github/skills/azure-ps-design-review/scratch/design-input.md` (or a step-specific name like `cmdlet-syntax.md`). +2. The file is pre-populated with a template containing headings, placeholder text, and commented instructions so the developer knows exactly what to fill in. +3. The agent tells the developer: **"I've opened `design-input.md` in your editor. Please fill in the sections and let me know when you're done."** +4. Once the developer confirms, the agent reads the file back and extracts the responses. +5. After the design is submitted, the agent deletes the scratch files. + +**When to use scratch files** (vs. chat input): + +| Input type | Method | +| ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | +| Short answers (release type, date, module name, contacts) | Chat input — ask directly | +| Multi-line content (cmdlet syntax, piping examples, sample usage, business logic, test scenarios, feature descriptions) | **Scratch file** — create and open in editor | + +**IMPORTANT**: Do **NOT** ask for multi-line content in the chat input box. Always create a scratch file for any response that would reasonably span more than 2–3 lines. This includes feature descriptions, piping scenarios, sample usage, cmdlet syntax blocks, business logic, and test scenarios. The chat input box is too small for formatted content. + +**Scratch file conventions**: + +- Location: `.github/skills/azure-ps-design-review/scratch/` (gitignored) +- Format: Markdown with `` comments guiding the developer +- One file per step that needs it, or a single combined file — agent decides based on complexity +- Always delete scratch files after the design issue is created + +--- + +## Workflow + +> **PR Link First** → Ingest Changes → Interview → Validate → Generate → Submit + +**CRITICAL**: The very first action when this skill is invoked is to ask the developer for their TypeSpec PR link. Do **not** ask about module names, release details, contacts, or anything else until the PR link has been provided and the changes have been ingested. The PR diff is used to pre-populate as much of the template as possible before starting the interview. + +### Progress Checklist + +Copy and update as you progress: + +- [ ] Step 1: Collected TypeSpec PR link and ingested changes +- [ ] Step 2: Collected short answers (release details, contacts, links) via chat +- [ ] Step 3: Created pre-filled design draft — developer filling in long-form sections +- [ ] Step 4: Validated design against guidelines +- [ ] Step 5: Generated final design spec and presented for review +- [ ] Step 6: Created GitHub Issue in Azure/azure-powershell-cmdlet-review-pr + +--- + +### Step 1: Collect TypeSpec PR Link & Ingest (Chat Follow-up) + +> **This step MUST execute first.** Do not proceed to any other step until this is complete. + +**Goal**: Get the TypeSpec PR link in a follow-up popup and ingest the diff to extract as much design data as possible. + +**Initial message**: When the skill is first invoked, respond with a brief introduction and the workflow overview, with a popup PR link input request. Example: + +> 👋 I'll help you create a PowerShell cmdlet design spec. Here's how this works: +> +> 1. You give me your TypeSpec PR link +> 2. I'll ask a few quick questions (release type, contacts, etc.) +> 3. I'll create a pre-filled design draft — you just fill in the long-form sections +> 4. I validate against design guidelines and file the review issue +> In a follow-up popup, ask for the TypeSpec PR link with clear instructions. Example: +> To get started, paste the link to your TypeSpec PR (e.g., `https://github.com/Azure/azure-rest-api-specs/pull/12345`). + +**If the developer already provided the PR link in their initial message**, skip the introduction and proceed directly to ingesting the PR. + +**Actions** (after receiving the PR link): + +1. Extract the PR number from the link. +2. Use `github-mcp-server:get_file_contents` with `refs/pull/{number}/head` to read the TypeSpec files on the PR branch, and again with the base branch to read the prior versions. +3. Diff the PR branch against the base to extract: + - PR title and description (use for feature description) + - Which TypeSpec project / service namespace changed (use to infer PowerShell module, e.g., `Microsoft.Compute` → `Az.Compute`) + - New resource models and properties + - New or modified operations (GET, PUT, PATCH, DELETE, POST actions) + - New parameters and constraints + - Changed properties on existing resources +4. From the extracted operations, generate candidate cmdlet nouns (e.g., `Snapshot`, `VirtualMachine`). +5. **Look up existing cmdlets** — for each candidate noun, use `github-mcp-server:search_code` to search `Azure/azure-powershell` for existing cmdlets matching that noun. For example: + - Search: `"AzSnapshot" language:cs path:src/Compute` in `repo:Azure/azure-powershell` + - Search: `"AzSnapshot" language:ps1 path:src/Compute` in `repo:Azure/azure-powershell` + - This returns existing cmdlet classes and scripts (e.g., `NewAzSnapshotCommand.cs`, `Get-AzSnapshot.ps1`) +6. **Inspect existing cmdlet details** — for each existing cmdlet found, use `github-mcp-server:get_file_contents` to read the cmdlet source file and extract: + - Current parameter names, types, and whether they are mandatory + - Current parameter sets (Interactive, ResourceId, InputObject, etc.) + - Output type (`OutputType` attribute) + - Whether `ShouldProcess`, `AsJob`, or `PassThru` are already implemented + This gives the agent a baseline of what the cmdlet already supports. +7. **Classify each cmdlet as New, Changed, or Unchanged**: + - **New Cmdlet**: No existing cmdlet matches the verb+noun combination (e.g., `Update-AzSnapshot` doesn't exist yet) + - **Changed Cmdlet**: An existing cmdlet matches, AND the TypeSpec PR introduces parameters, properties, or operations that are **not already present** in the existing cmdlet source. Only include changes that are actually new — do not flag parameters or behaviors that the cmdlet already supports. + - **Unchanged**: An existing cmdlet matches, and the TypeSpec PR changes do not introduce anything beyond what the cmdlet already has. **Exclude these from the design** — they do not need review. + - Present the classification to the developer for confirmation: "I found these existing cmdlets and checked their current parameters: `Get-AzSnapshot` (has -ResourceGroupName, -Name, -ResourceId), `New-AzSnapshot` (has -Location, -Sku, ...). Based on your PR, `Update-AzSnapshot` is new, and `New-AzSnapshot` needs a new `-EncryptionType` parameter. Does that look right?" +8. Generate parameter tables and output types for each new/changed cmdlet. +9. Determine the spec link (the PR URL itself). + +**Important**: Do **not** scan the local working tree for changes. All change detection must come from the PR. The developer may invoke this skill long after the TypeSpec changes were made. + +**Output**: A structured set of pre-populated fields. Do NOT present this raw or create the scratch file yet — first collect the short answers in Step 2. + +--- + +### Step 2: Collect Short Answers (Chat Follow-Ups) + +**Goal**: Ask the developer for all short-form information in a the follow-up popup questionnaire. These are quick answers that don't need the editor. + +**Present all questions together** in one message after ingesting the PR. Skip any the agent can already infer from the PR (and show the inferred values for confirmation). Example: + +> I've read your PR and found 3 new operations. Before I create the design draft, I need a few details: +> +> 1. **Release type**: Embargoed Preview, Public Preview, or General Release? +> 2. **Expected release date**: +> 3. **PowerShell module**: (I'm guessing `Az.Compute` — correct?) +> 4. **Developer contacts**: (email + GitHub alias) +> 5. **PM contact**: (email + GitHub alias) +> 6. **Additional reviewers**: (optional) +> 7. **Related GitHub issues/PRs**: (optional) +> 8. **Feature flags or restrictions**: (optional) + +**Rules**: + +- Ask all questions in a list of follow-ups in the follow-up popup window so the developer can answer them all at once. +- Pre-fill any values the agent can infer from the PR and ask the developer to confirm or correct. +- The developer can answer in any format — numbered list, paragraph, etc. The agent parses the response. + +--- + +### Step 3: Create Pre-Filled Design Draft (Scratch File) + +**Goal**: Combine everything from the PR (Step 1) and the chat answers (Step 2) into a single scratch file. The developer only needs to fill in the **long-form sections** — everything else is already done. + +**Input method**: **MUST use scratch file.** Create `scratch/design-draft.md` with all short answers and TypeSpec data already filled in. Only long-form sections that require multi-line formatted input should have `` markers. + +Use this template — `{...}` values are filled from Steps 1 and 2: + +````markdown +# PowerShell Design Review Draft + + + +--- + +## Service Release Details + +- **Release type**: {RELEASE_TYPE} +- **Expected release date**: {RELEASE_DATE} +- **PowerShell module**: {MODULE} + +## Contact Information + +- **Main developer contacts**: {DEV_CONTACTS} +- **PM contact**: {PM_CONTACT} +- **Additional reviewers**: {ADDITIONAL_CONTACTS} + +## High-Level Scenarios + +### Feature Description + +{PR_DESCRIPTION_OR_TITLE} + + + +### Piping Scenarios + + + +### End-to-End Sample Usage + + + +```powershell + +``` +```` + +## New Cmdlets + + + +{FOR_EACH_NEW_CMDLET} + +### {CMDLET_NAME} + +**Parameters:** + +| Parameter | Type | Mandatory | Description | +| --------- | ---- | --------- | ----------- | + +{PARAMETER_ROWS} + +**Business Logic:** + + + +**Sample Syntax and Output:** + + + +```powershell +PS C:\> {CMDLET_NAME} -ResourceGroupName "rg1" -Name "example" + +``` + +{END_FOR_EACH} + +## Changed Cmdlets + + + +{FOR_EACH_CHANGED_CMDLET} + +### {CMDLET_NAME} + +**New/Changed Parameters:** + + + +| Parameter | Type | Mandatory | Description | +| --------- | ---- | --------- | ----------- | +| | | | | + +**Business Logic Changes:** + + + +**Sample Syntax or Diff:** + + + +```powershell + +``` + +**Affected Parameter Sets:** + + + +{END_FOR_EACH} + +## Test Cases + + + +1. +2. +3. + +## Additional Information + +- **Link to TypeSpec / OpenAPI spec**: {PR_URL} +- **Related GitHub work**: {RELATED_LINKS} +- **Feature flags or restrictions**: {RESTRICTIONS} + +--- + +> _Created with help from PS design skill_ + +```` + +**What should be pre-filled** (not TODO): +- All service release details (from Step 2 chat) +- All contact information (from Step 2 chat) +- Feature description seed text (from PR title/description) +- Cmdlet names and parameter tables (from TypeSpec diff) +- Related links, restrictions (from Step 2 chat) +- Spec link (the PR URL) + +**What should be TODO** (long-form only): +- Expanded feature description (developer may want to add more detail) +- Piping scenarios (requires formatted PowerShell examples) +- End-to-end sample usage (requires formatted PowerShell code blocks) +- Business logic for each cmdlet (requires prose) +- Sample syntax and output for each cmdlet (requires formatted code blocks) +- Test cases (full list of every scenario to test — positive, negative, edge cases) + +**Pre-population rules for cmdlets**: +- Cmdlet names: Derive from operations (PUT → `New-`/`Set-`, PATCH → `Update-`, DELETE → `Remove-`, GET → `Get-`, POST actions → approved verb). Mark each with ``. +- Parameters: Extract from resource model properties. Include type and mark as ``. + +Tell the developer: **"I've created `design-draft.md` in your editor. All the info from your PR and our chat is already filled in — you just need to write the long-form sections (piping scenarios, sample usage, business logic, and test cases). Let me know when you're done."** + +--- + +### Step 4: Validate Against Design Guidelines + +**Goal**: Run a final validation pass over the complete design. + +**Validation checks**: +- Verb is from the [approved PowerShell verbs list](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands) +- Noun uses `Az` prefix and Pascal case +- PATCH operations use `Update-`, PUT operations use `Set-` +- Cmdlets that modify resources implement `ShouldProcess` (`-WhatIf` / `-Confirm`) +- Cmdlets returning no output implement `-PassThru` +- Long-running operations implement `-AsJob` +- Required parameter sets present: Interactive, ResourceId, InputObject +- Output types are specific (never `object`, `PSObject`, `PSCustomObject`, or `string`) +- Two-char acronyms fully capitalized; 3+ char acronyms Pascal-cased +- Piping examples use `-InputObject` or `-ResourceId` parameter sets + +**Actions**: + +1. Re-check all cmdlet names, parameters, output types, and piping scenarios against the [design guidelines summary](references/design-guidelines-summary.md). +2. Flag any issues found and present them to the developer with suggested fixes. +3. If issues exist, update the scratch file with corrections and re-open for the developer. +4. Once all validations pass, proceed to generation. + +For edge cases or when the developer requests detailed rationale, fetch the full guidelines from `Azure/azure-powershell/documentation/development-docs/design-guidelines/` via the GitHub MCP Server. + +--- + +### Step 5: Generate Design Spec + +**Goal**: Produce the complete design document. + +**Actions**: + +1. Assemble all collected information into the [design review template format](references/issue-template.md). +2. Present the full Markdown document to the developer for review. +3. Ask: "Does this look correct? Would you like to make any changes before I submit it?" +4. If changes requested, apply them and re-present. + +--- + +### Step 6: Create GitHub Issue + +**Goal**: File the design as a GitHub Issue. + +**Actions**: + +1. Create an issue in `Azure/azure-powershell-cmdlet-review-pr` using `github-mcp-server:create_issue` with: + - **Title**: `{MODULE} - {FEATURE}` (e.g., `Az.Compute - ManagedDisk Snapshot`) + - **Body**: The generated design spec from Step 5 + - **Labels**: `needs-review`. If the module is `Az.Compute`, also apply the `Compute` label. +2. Display the created issue URL to the developer. +3. **Clean up scratch files** — delete all files in `.github/skills/azure-ps-design-review/scratch/` (except `.gitignore`). +4. Inform: "The Azure PowerShell team's SLA for initial reviews is 3 business days. Ping the team for urgent requests." + +--- + +## Examples + +- "Help me create a PowerShell design for my new Compute feature" +- "I need to submit a cmdlet design review for Az.Compute" +- "Create a PS design spec from my TypeSpec" +- "Guide me through a PowerShell design review submission" + +## Troubleshooting + +- **GitHub MCP Server not connected / tool calls fail**: The GitHub MCP server is required for this skill. If any `github-mcp-server` tool call fails, instruct the developer to add the following to their `.vscode/mcp.json` (or workspace `.mcp.json`), then reload VS Code: + ```json + { + "servers": { + "github": { + "url": "https://api.githubcopilot.com/mcp/" + } + } + } +```` + +Do NOT fall back to `gh` CLI, `git`, `curl`, or PowerShell commands. Wait for the developer to fix the MCP configuration and retry. + +- **No TypeSpec PR available**: The PR link is required. If the developer doesn't have one yet, advise them to create and submit their TypeSpec PR first, then return to this skill. +- **GitHub issue creation fails**: Verify the developer has write access to `Azure/azure-powershell-cmdlet-review-pr`. If not, output the Markdown spec so they can file it manually. +- **Design guideline questions**: Fetch the full guideline document from `Azure/azure-powershell/documentation/development-docs/design-guidelines/` for detailed rationale. diff --git a/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md b/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md new file mode 100644 index 000000000000..b48106d5db55 --- /dev/null +++ b/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md @@ -0,0 +1,96 @@ +# PowerShell Design Guidelines Summary + +Condensed validation rules extracted from the [Azure PowerShell Design Guidelines](https://github.com/Azure/azure-powershell/tree/master/documentation/development-docs/design-guidelines). The agent checks these at each step. For full details or edge-case rationale, fetch the source docs via GitHub MCP Server. + +--- + +## Naming Conventions {#naming} + +| Rule | Description | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **Verb-Noun format** | Use an [approved PowerShell verb](https://learn.microsoft.com/en-us/powershell/scripting/developer/cmdlet/approved-verbs-for-windows-powershell-commands) + specific noun. | +| **Az prefix** | ARM cmdlet nouns must start with `Az` (e.g., `Get-AzVM`). | +| **Pascal case** | Capitalize the first letter of the verb and every term in the noun. | +| **Two-char acronyms** | Fully capitalize (e.g., `VM`, `DB`). | +| **3+ char acronyms** | Only capitalize the first letter (e.g., `Sql`, `Vmss`). | +| **Singular nouns** | Use singular form (e.g., `Get-AzVM` not `Get-AzVMs`). | +| **Set vs. Update** | `Set-` for PUT (full replace); `Update-` for PATCH (partial update). | + +--- + +## Parameter Best Practices {#parameters} + +| Rule | Description | +| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| **Three required parameter sets** | Interactive (`-Name` + `-ResourceGroupName`), ResourceId (`-ResourceId`), InputObject (`-InputObject`). | +| **Pascal case** | Parameter names use Pascal case. | +| **Specific types** | Never use `object`, `PSObject`, `PSCustomObject`, or `string` as output type. | +| **-PassThru** | Cmdlets that return no output must implement `-PassThru` (returns `bool`). | +| **-AsJob** | All long-running operations must support `-AsJob`. | +| **ShouldProcess** | Cmdlets that create, delete, update, start, or stop resources must implement `SupportsShouldProcess` (adds `-WhatIf` and `-Confirm`). | +| **-Force** | Only for scenarios requiring extra confirmation (e.g., overwriting existing resources, deleting containers with children). | +| **Mandatory parameters** | Mark as `Mandatory = true` only when the cmdlet cannot function without the value. | + +--- + +## Output Type Rules + +| Rule | Description | +| ------------------------- | ------------------------------------------------------------------------------------ | +| **Specific OutputType** | Always declare `[OutputType(typeof(...))]` with a concrete type. | +| **Wrap SDK types** | Return `PS*` wrapper types (e.g., `PSVirtualMachine`) instead of raw .NET SDK types. | +| **Enumerate collections** | Use `WriteObject(collection, true)` to enumerate — never return a raw `List`. | +| **No string returns** | If you need to return string data, wrap it in a typed object. | + +--- + +## Piping Best Practices {#piping} + +| Rule | Description | +| ----------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------- | +| **InputObject piping** | Support `Get-Az\* | Update-Az\*` by accepting the output type of the source cmdlet. | +| **ResourceId piping** | Support `Get-AzResource | Remove-Az\*`via the`-ResourceId` parameter set. | +| **ValueFromPipeline** | Mark `-InputObject` with `ValueFromPipeline = true`. | +| **ValueFromPipelineByPropertyName** | Mark `-ResourceId` with `ValueFromPipelineByPropertyName = true`. | + +--- + +## ShouldProcess & Confirm Impact + +| Scenario | ConfirmImpact | Behavior | +| ------------------------------------ | ------------- | -------------------------------------- | +| Read-only (Get) | None | No confirmation | +| Low-risk change | Low | Confirms only with `-Confirm` | +| Standard mutation (New, Set, Update) | Medium | Confirms only with `-Confirm` | +| Destructive action (Remove, Stop) | High | Always prompts unless `-Force` is used | + +--- + +## Module Best Practices + +- One module per Azure service (e.g., `Az.Compute`). +- Module manifest must declare all exported cmdlets. +- Help content must be generated via platyPS. +- Breaking changes require a breaking change attribute annotation and a deprecation period. + +--- + +## Managed Identity Best Practices + +- Support system-assigned and user-assigned managed identities. +- Use `-IdentityType` parameter with values: `SystemAssigned`, `UserAssigned`, `SystemAssignedUserAssigned`, `None`. +- `-IdentityId` accepts an array of user-assigned identity resource IDs. + +--- + +## Source Documents + +For the full, authoritative guidelines, see: + +- [Cmdlet Best Practices](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/cmdlet-best-practices.md) +- [Parameter Best Practices](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/parameter-best-practices.md) +- [Piping Best Practices](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/piping-best-practices.md) +- [ShouldProcess and Confirm Impact](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/should-process-confirm-impact.md) +- [Module Best Practices](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/module-best-practices.md) +- [Managed Identity Best Practices](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/managed-identity-best-practices.md) +- [Azure PowerShell Exceptions](https://github.com/Azure/azure-powershell/blob/main/documentation/development-docs/design-guidelines/azure-powershell-exceptions.md) diff --git a/.github/skills/azure-ps-design-review/references/issue-template.md b/.github/skills/azure-ps-design-review/references/issue-template.md new file mode 100644 index 000000000000..7037b6f50945 --- /dev/null +++ b/.github/skills/azure-ps-design-review/references/issue-template.md @@ -0,0 +1,159 @@ +# Design Review Issue Template + +This is the target format for the GitHub Issue created in [`Azure/azure-powershell-cmdlet-review-pr`](https://github.com/Azure/azure-powershell-cmdlet-review-pr). The agent populates every field during the guided interview. + +--- + +## Template + +```markdown + + +## Guidelines + +The purpose of the Azure PowerShell design review is to ensure that the cmdlets follow the same pattern across the Azure modules. An early design review reduces the risk of unnecessary implementation changes caused by a cmdlet syntax design change. + +Please ensure your cmdlets comply with the design guidelines outlined in the [PowerShell Design Guidelines document](https://github.com/Azure/azure-powershell/tree/master/documentation/development-docs/design-guidelines). + +- Have you read above statement? + - Yes + +## Service Release Details + +- Is this an Embargoed Preview, A Public Preview, or a General Release? + - {RELEASE_TYPE} + +- What is the expected service release date? + - {RELEASE_DATE} + +- Which [Powershell module](https://github.com/Azure/azure-powershell/blob/main/documentation/azure-powershell-modules.md) are these changes being made in? + - {MODULE} + +## Contact Information + +- Main developer contacts (emails + github aliases) + - {DEV_CONTACTS} + +- PM contact (email + github alias) + - {PM_CONTACT} + +- Other people who should attend a design review (email) + - {ADDITIONAL_CONTACTS} + +## High Level Scenarios + +- Describe how your feature is intended to be used by customers. + - {FEATURE_DESCRIPTION} + +- Piping scenarios / how these cmdlets are used with existing cmdlets + - {PIPING_SCENARIOS} + +- Sample of end-to-end usage + - {SAMPLE_USAGE} + +## Syntax changes + +### New Cmdlets + + + +{FOR_EACH_NEW_CMDLET} + +#### {NEW_CMDLET_NAME} + +**Parameters:** + +{NEW_CMDLET_PARAMETERS} + +**Business Logic:** + +{NEW_CMDLET_LOGIC} + +**Sample Syntax:** + +{NEW_CMDLET_SYNTAX_BLOCK} +{END_FOR_EACH} + +### Changed Cmdlets + + + +{FOR_EACH_CHANGED_CMDLET} + +#### {CHANGED_CMDLET_NAME} + +**New/Changed Parameters:** + +{CHANGED_CMDLET_PARAMETERS} + +**Business Logic Changes:** + +{CHANGED_CMDLET_LOGIC} + +**Sample Syntax or Diff:** + +{CHANGED_CMDLET_SYNTAX} + +**Affected Parameter Sets:** + +{AFFECTED_PARAMETER_SETS} +{END_FOR_EACH} + +## Specific test cases + +Please list every test scenario that should be tested for this feature, including positive cases, negative/error cases, and edge cases. + +{TEST_SCENARIOS} + +## Additional information + +- Link to the OpenAPI (swagger) spec + - {SPEC_LINK} + +- Link to any other Github work related to this request + - {RELATED_LINKS} + +- Indicate any feature flags or restrictions on the changes provided in this design specification. + - {RESTRICTIONS} + +--- + +> _Created with help from PS design skill_ +``` + +--- + +## Field Reference + +| Placeholder | Interview Step | Source | +| ----------------------------- | --------------------- | -------------------------------------------- | +| `{RELEASE_TYPE}` | Step 2 | Developer input | +| `{RELEASE_DATE}` | Step 2 | Developer input | +| `{MODULE}` | Step 2 | Developer input / TypeSpec path | +| `{DEV_CONTACTS}` | Step 3 | Developer input | +| `{PM_CONTACT}` | Step 3 | Developer input | +| `{ADDITIONAL_CONTACTS}` | Step 3 | Developer input (optional) | +| `{FEATURE_DESCRIPTION}` | Step 4 | Developer input | +| `{PIPING_SCENARIOS}` | Step 4 | Developer input | +| `{SAMPLE_USAGE}` | Step 4 | Developer input | +| `{CHANGE_TYPE}` | Step 5 | Developer input | +| `{NEW_CMDLET_NAMES}` | Step 5 | Developer input + TypeSpec pre-population | +| `{NEW_CMDLET_PARAMETERS}` | Step 5 | Developer input + TypeSpec pre-population | +| `{NEW_CMDLET_LOGIC}` | Step 5 | Developer input | +| `{NEW_CMDLET_SYNTAX_BLOCK}` | Step 5 | Developer input (PowerShell code block) | +| `{CHANGED_CMDLET_NAMES}` | Step 5 | Developer input | +| `{CHANGED_CMDLET_PARAMETERS}` | Step 5 | Developer input | +| `{CHANGED_CMDLET_LOGIC}` | Step 5 | Developer input | +| `{CHANGED_CMDLET_SYNTAX}` | Step 5 | Developer input | +| `{AFFECTED_PARAMETER_SETS}` | Step 5 | Developer input | +| `{TEST_SCENARIOS}` | Step 3 (scratch file) | Developer input — list of all test scenarios | +| `{SPEC_LINK}` | Step 6 | Developer input / TypeSpec PR link | +| `{RELATED_LINKS}` | Step 6 | Developer input | +| `{RESTRICTIONS}` | Step 6 | Developer input | + +## Issue Metadata + +- **Repository**: `Azure/azure-powershell-cmdlet-review-pr` +- **Title format**: `{MODULE} - {FEATURE}` (e.g., `Az.Compute - ManagedDisk Snapshot`) +- **Labels**: `needs-review` +- **Assignees**: Leave empty (the PS team triages) diff --git a/.github/skills/azure-ps-design-review/scratch/.gitignore b/.github/skills/azure-ps-design-review/scratch/.gitignore new file mode 100644 index 000000000000..de58dca045fd --- /dev/null +++ b/.github/skills/azure-ps-design-review/scratch/.gitignore @@ -0,0 +1,3 @@ +# Keep this directory but ignore scratch files created during design interviews +* +!.gitignore From 2e37d2b1af5d7f7850161bef8e6226b3ddda2c32 Mon Sep 17 00:00:00 2001 From: Audrey Toney Date: Thu, 11 Jun 2026 14:20:36 -0400 Subject: [PATCH 2/3] Clarify prereqs Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .github/skills/azure-ps-design-review/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/skills/azure-ps-design-review/SKILL.md b/.github/skills/azure-ps-design-review/SKILL.md index 86f0cca7eaab..8a5fac4da10e 100644 --- a/.github/skills/azure-ps-design-review/SKILL.md +++ b/.github/skills/azure-ps-design-review/SKILL.md @@ -5,7 +5,7 @@ metadata: version: "1.0.0" description: "Conversational agent that guides developers through creating complete Azure PowerShell cmdlet design specifications. Walks through an interactive interview covering service release details, contacts, scenarios, cmdlet syntax, parameter sets, piping, test cases, and spec links. Validates against PowerShell design guidelines, pre-populates fields from TypeSpec, and files the design as a GitHub Issue in Azure/azure-powershell-cmdlet-review-pr. USE FOR: 'create PowerShell design', 'PS design review', 'cmdlet design', 'PowerShell cmdlet review', 'submit PS design'. DO NOT USE FOR: SDK generation, TypeSpec authoring, releasing packages." compatibility: - requires: "GitHub MCP Server for issue creation in Azure/azure-powershell-cmdlet-review-pr; TypeSpec files in the current repo for pre-population" + requires: "GitHub MCP Server access to the TypeSpec PR (e.g., Azure/azure-rest-api-specs) for pre-population; write access to Azure/azure-powershell-cmdlet-review-pr for issue creation" --- # Azure PowerShell Cmdlet Design Review From aaf70c15e7ecd674f6a5f3522617cf05fe146bc3 Mon Sep 17 00:00:00 2001 From: audreyttt Date: Fri, 12 Jun 2026 10:05:00 -0400 Subject: [PATCH 3/3] Fix copilot comments --- .github/skills/azure-ps-design-review/SKILL.md | 5 ++--- .../references/design-guidelines-summary.md | 6 +++--- .../azure-ps-design-review/references/issue-template.md | 8 ++++---- 3 files changed, 9 insertions(+), 10 deletions(-) diff --git a/.github/skills/azure-ps-design-review/SKILL.md b/.github/skills/azure-ps-design-review/SKILL.md index 86f0cca7eaab..93fffbca3b54 100644 --- a/.github/skills/azure-ps-design-review/SKILL.md +++ b/.github/skills/azure-ps-design-review/SKILL.md @@ -228,7 +228,6 @@ Use this template — `{...}` values are filled from Steps 1 and 2: ```powershell ``` -```` ## New Cmdlets @@ -345,7 +344,7 @@ PS C:\> {CMDLET_NAME} -ResourceGroupName "rg1" -Name "example" - Test cases (full list of every scenario to test — positive, negative, edge cases) **Pre-population rules for cmdlets**: -- Cmdlet names: Derive from operations (PUT → `New-`/`Set-`, PATCH → `Update-`, DELETE → `Remove-`, GET → `Get-`, POST actions → approved verb). Mark each with ``. +- Cmdlet names: Derive from operations (PUT → `Set-`, PATCH → `Update-`, DELETE → `Remove-`, GET → `Get-`, POST actions → `New-`). Mark each with ``. - Parameters: Extract from resource model properties. Include type and mark as ``. Tell the developer: **"I've created `design-draft.md` in your editor. All the info from your PR and our chat is already filled in — you just need to write the long-form sections (piping scenarios, sample usage, business logic, and test cases). Let me know when you're done."** @@ -426,7 +425,7 @@ For edge cases or when the developer requests detailed rationale, fetch the full } } } -```` + ``` Do NOT fall back to `gh` CLI, `git`, `curl`, or PowerShell commands. Wait for the developer to fix the MCP configuration and retry. diff --git a/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md b/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md index b48106d5db55..4288faebcb60 100644 --- a/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md +++ b/.github/skills/azure-ps-design-review/references/design-guidelines-summary.md @@ -47,9 +47,9 @@ Condensed validation rules extracted from the [Azure PowerShell Design Guideline ## Piping Best Practices {#piping} | Rule | Description | -| ----------------------------------- | ----------------------------------------------------------------- | --------------------------------------------------------------- | -| **InputObject piping** | Support `Get-Az\* | Update-Az\*` by accepting the output type of the source cmdlet. | -| **ResourceId piping** | Support `Get-AzResource | Remove-Az\*`via the`-ResourceId` parameter set. | +| ----------------------------------- | ----------------------------------------------------------------- | +| **InputObject piping** | Support `Get-Az | Update-Az` by accepting the output type of the source cmdlet. | +| **ResourceId piping** | Support `Get-AzResource | Remove-Az`via the`-ResourceId` parameter set. | | **ValueFromPipeline** | Mark `-InputObject` with `ValueFromPipeline = true`. | | **ValueFromPipelineByPropertyName** | Mark `-ResourceId` with `ValueFromPipelineByPropertyName = true`. | diff --git a/.github/skills/azure-ps-design-review/references/issue-template.md b/.github/skills/azure-ps-design-review/references/issue-template.md index 7037b6f50945..2ac03418be23 100644 --- a/.github/skills/azure-ps-design-review/references/issue-template.md +++ b/.github/skills/azure-ps-design-review/references/issue-template.md @@ -26,15 +26,15 @@ Please ensure your cmdlets comply with the design guidelines outlined in the [Po - What is the expected service release date? - {RELEASE_DATE} -- Which [Powershell module](https://github.com/Azure/azure-powershell/blob/main/documentation/azure-powershell-modules.md) are these changes being made in? +- Which [PowerShell module](https://github.com/Azure/azure-powershell/blob/main/documentation/azure-powershell-modules.md) are these changes being made in? - {MODULE} ## Contact Information -- Main developer contacts (emails + github aliases) +- Main developer contacts (emails + GitHub aliases) - {DEV_CONTACTS} -- PM contact (email + github alias) +- PM contact (email + GitHub alias) - {PM_CONTACT} - Other people who should attend a design review (email) @@ -110,7 +110,7 @@ Please list every test scenario that should be tested for this feature, includin - Link to the OpenAPI (swagger) spec - {SPEC_LINK} -- Link to any other Github work related to this request +- Link to any other GitHub work related to this request - {RELATED_LINKS} - Indicate any feature flags or restrictions on the changes provided in this design specification.