From 07545220a9cfbb7703c3e85dba0556cbf5214698 Mon Sep 17 00:00:00 2001 From: Komal Vardhan Lolugu <67476199+KomalSrinivasan@users.noreply.github.com> Date: Sat, 27 Jun 2026 03:21:40 +0530 Subject: [PATCH 1/2] azure-devops-cli: handle long comments on Windows (#2061) On Windows 'az' is a cmd.exe batch wrapper capped at ~8191 characters, so a long --discussion / --description value silently truncates or fails. Document three verified ways out so the coding agent doesn't waste 3-5 turns falling back to raw token retrieval and REST: 1. azps.ps1 in PowerShell on Windows. Same Azure CLI, invoked through the Python entry point with no cmd.exe length cap. Pair with 'Get-Content -Raw' so the body lives in a variable, not on the command line. 2. Native --file-path flags where Azure CLI offers them. Applies to 'az devops wiki page create' and 'az devops wiki page update', both documented with --encoding. 3. 'az devops invoke --in-file' as the universal escape hatch for commands with no --file-path (work-item --discussion, PR --description). Documented example posts to the work item comments REST endpoint with api-version 7.0-preview.3. The earlier draft suggested the Azure CLI '@' convention as a generic substitute for inline string args. The official docs only document it for JSON parameters and the CLI source uses 'get_file_json' specifically, so the claim is removed and replaced with an explicit warning not to rely on it for plain string args. Files touched: - skills/azure-devops-cli/SKILL.md: new 'Posting long comments on Windows' section with shell-detection table and three verified options. - skills/azure-devops-cli/references/boards-and-iterations.md: short pointer at each --discussion example back to SKILL.md, plus an inline PowerShell snippet. Closes #2061. --- skills/azure-devops-cli/SKILL.md | 55 +++++++++++++++++++ .../references/boards-and-iterations.md | 12 ++++ 2 files changed, 67 insertions(+) diff --git a/skills/azure-devops-cli/SKILL.md b/skills/azure-devops-cli/SKILL.md index c8e420fb5..b2a5298cd 100644 --- a/skills/azure-devops-cli/SKILL.md +++ b/skills/azure-devops-cli/SKILL.md @@ -79,6 +79,61 @@ az artifacts # Azure Artifacts └── universal # Universal Packages ``` +## Posting long comments on Windows + +On Windows the `az` command resolves to `az.cmd`, a batch wrapper invoked by `cmd.exe`. The whole command line is capped at ~8191 characters, so a long `--discussion`, `--description`, or `--content` value can be silently truncated or fail. Detect the shell before composing a long argument and route accordingly. Skipping this is the most common reason the agent burns 3-5 turns falling back to raw token retrieval and REST calls. + +### Detect the shell first + +| Environment | Signal | Action | +|---|---|---| +| PowerShell on Windows | `$IsWindows -eq $true` and `$PSVersionTable.PSVersion` is set | Use `azps.ps1` (see below) | +| PowerShell on macOS / Linux | `$IsWindows -eq $false` | Plain `az` is fine, no cmd.exe wrapper | +| bash / zsh / sh | `$BASH_VERSION` or `$ZSH_VERSION` set, or `uname` works | Plain `az` is fine, no cmd.exe wrapper | +| Windows `cmd.exe` | `%ComSpec%` ends in `cmd.exe`, no `$PSVersionTable` | Use `azps.ps1` if PowerShell is installed, otherwise see `az devops invoke` fallback below | + +### Option 1: `azps.ps1` (PowerShell on Windows) + +`azps.ps1` ships with the Azure CLI installer and invokes the Python entry point directly. No `cmd.exe` length cap. + +```powershell +# Read the long body into a variable and pass it through. No quoting headaches. +$body = Get-Content -Raw .\comment.md +azps.ps1 boards work-item update --id 1234 --discussion $body +``` + +### Option 2: dedicated `--file-path` flag where Azure CLI offers one + +Some commands have a native file flag and you should prefer it over any inline body: + +- `az devops wiki page create` and `az devops wiki page update` take `--file-path` (with optional `--encoding`). +- Use it on any shell, including Windows. + +```bash +az devops wiki page create --path 'My page' --wiki myproject --file-path ./page.md --encoding utf-8 +``` + +### Option 3: `az devops invoke` fallback + +When no `--file-path` exists (work-item `--discussion`, PR `--description`) and you're not in PowerShell, post the body via the underlying REST API. `az devops invoke` runs inside the Python entry point, so it isn't subject to the `cmd.exe` cap either, and it takes the request body from a file with `--in-file`: + +```bash +# Post a long discussion comment to work item 1234. +# REST: POST /{project}/_apis/wit/workItems/{id}/comments?api-version=7.0-preview.3 +az devops invoke \ + --area wit --resource comments \ + --route-parameters project={project} workItemId=1234 \ + --api-version 7.0-preview.3 \ + --http-method POST \ + --in-file ./comment.json +``` + +Where `comment.json` is `{ "text": "" }`. This is the universal escape hatch when neither `azps.ps1` nor `--file-path` is available. `az devops invoke` itself accepts `--in-file` natively. + +### Don't rely on `@` for plain string args + +The Azure CLI `@` convention is documented for JSON parameters (see [the official quoting guide](https://learn.microsoft.com/en-us/cli/azure/use-azure-cli-successfully-quoting)). It is not guaranteed to expand plain string args like `--discussion` or `--description`, so don't reach for it as a substitute for the three options above. + ## Reference Files Read the relevant reference file based on the user's task. Each file contains complete command syntax and examples for its domain. diff --git a/skills/azure-devops-cli/references/boards-and-iterations.md b/skills/azure-devops-cli/references/boards-and-iterations.md index b1c99a71a..7de6486e8 100644 --- a/skills/azure-devops-cli/references/boards-and-iterations.md +++ b/skills/azure-devops-cli/references/boards-and-iterations.md @@ -56,6 +56,10 @@ az boards work-item create \ --type Bug \ --discussion "Initial investigation completed" +# For a long --discussion body on Windows, see "Posting long comments on Windows" +# in SKILL.md. Short version: use azps.ps1 in PowerShell, or fall back to +# 'az devops invoke' with --in-file when no native --file-path flag is available. + # Open in browser after creation az boards work-item create --title "Bug" --type Bug --open ``` @@ -85,6 +89,14 @@ az boards work-item update \ --id {work-item-id} \ --discussion "Work in progress" +# Long comment on Windows: read the body into a PowerShell variable and call +# azps.ps1 instead of az.cmd, or fall back to 'az devops invoke' with --in-file. +# Full guidance in SKILL.md under "Posting long comments on Windows". +# +# PowerShell example: +# $body = Get-Content -Raw .\comment.md +# azps.ps1 boards work-item update --id 1234 --discussion $body + # Update with custom fields az boards work-item update \ --id {work-item-id} \ From 9c197cd42c44e76ed109ebd13d3e298bd087bc5c Mon Sep 17 00:00:00 2001 From: Komal Vardhan Lolugu <67476199+KomalSrinivasan@users.noreply.github.com> Date: Mon, 29 Jun 2026 09:19:18 +0530 Subject: [PATCH 2/2] azure-devops-cli: move long-comments guidance to reference file (#2061 review) aaronpowell asked for the Windows long-comments section to live as a reference file rather than inline in SKILL.md, so the token weight isn't always loaded into the agent's context. - Move the "Posting long comments on Windows" section to a new references/long-comments-on-windows.md verbatim. - Strip the section from SKILL.md (56 fewer lines in the always-loaded surface). - Add the new file to the Reference Files table in SKILL.md with a one-line "when to read" hint covering --discussion, --description, and --content failures on Windows. - Update the two pointer comments in references/boards-and-iterations.md to point at the new reference file instead of the SKILL.md section. docs/README.skills.md regenerated by 'npm run build' to pick up the new reference file in the skill's bundled assets column. --- docs/README.skills.md | 2 +- skills/azure-devops-cli/SKILL.md | 56 +------------------ .../references/boards-and-iterations.md | 8 +-- .../references/long-comments-on-windows.md | 54 ++++++++++++++++++ 4 files changed, 60 insertions(+), 60 deletions(-) create mode 100644 skills/azure-devops-cli/references/long-comments-on-windows.md diff --git a/docs/README.skills.md b/docs/README.skills.md index 361c6be64..2c5ee0a28 100644 --- a/docs/README.skills.md +++ b/docs/README.skills.md @@ -68,7 +68,7 @@ See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-skills) for guidelines on how to | [az-cost-optimize](../skills/az-cost-optimize/SKILL.md)
`gh skills install github/awesome-copilot az-cost-optimize` | Analyze Azure resources used in the app (IaC files and/or resources in a target rg) and optimize costs - creating GitHub issues for identified optimizations. | None | | [azure-architecture-autopilot](../skills/azure-architecture-autopilot/SKILL.md)
`gh skills install github/awesome-copilot azure-architecture-autopilot` | Design Azure infrastructure using natural language, or analyze existing Azure resources to auto-generate architecture diagrams, refine them through conversation, and deploy with Bicep.
When to use this skill: - "Create X on Azure", "Set up a RAG architecture" (new design) - "Analyze my current Azure infrastructure", "Draw a diagram for rg-xxx" (existing analysis) - "Foundry is slow", "I want to reduce costs", "Strengthen security" (natural language modification) - Azure resource deployment, Bicep template generation, IaC code generation - Microsoft Foundry, AI Search, OpenAI, Fabric, ADLS Gen2, Databricks, and all Azure services | `.gitignore`
`assets/06-architecture-diagram.png`
`assets/07-azure-portal-resources.png`
`assets/08-deployment-succeeded.png`
`references/ai-data.md`
`references/architecture-guidance-sources.md`
`references/azure-common-patterns.md`
`references/azure-dynamic-sources.md`
`references/bicep-generator.md`
`references/bicep-reviewer.md`
`references/phase0-scanner.md`
`references/phase1-advisor.md`
`references/phase4-deployer.md`
`references/service-gotchas.md`
`scripts/cli.py`
`scripts/generator.py`
`scripts/icons.py` | | [azure-deployment-preflight](../skills/azure-deployment-preflight/SKILL.md)
`gh skills install github/awesome-copilot azure-deployment-preflight` | Performs comprehensive preflight validation of Bicep deployments to Azure, including template syntax validation, what-if analysis, and permission checks. Use this skill before any deployment to Azure to preview changes, identify potential issues, and ensure the deployment will succeed. Activate when users mention deploying to Azure, validating Bicep files, checking deployment permissions, previewing infrastructure changes, running what-if, or preparing for azd provision. | `references/ERROR-HANDLING.md`
`references/REPORT-TEMPLATE.md`
`references/VALIDATION-COMMANDS.md` | -| [azure-devops-cli](../skills/azure-devops-cli/SKILL.md)
`gh skills install github/awesome-copilot azure-devops-cli` | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | `references/advanced-usage.md`
`references/boards-and-iterations.md`
`references/org-and-security.md`
`references/pipelines-and-builds.md`
`references/repos-and-prs.md`
`references/variables-and-agents.md`
`references/workflows-and-patterns.md` | +| [azure-devops-cli](../skills/azure-devops-cli/SKILL.md)
`gh skills install github/awesome-copilot azure-devops-cli` | Manage Azure DevOps resources via CLI including projects, repos, pipelines, builds, pull requests, work items, artifacts, and service endpoints. Use when working with Azure DevOps, az commands, devops automation, CI/CD, or when user mentions Azure DevOps CLI. | `references/advanced-usage.md`
`references/boards-and-iterations.md`
`references/long-comments-on-windows.md`
`references/org-and-security.md`
`references/pipelines-and-builds.md`
`references/repos-and-prs.md`
`references/variables-and-agents.md`
`references/workflows-and-patterns.md` | | [azure-pricing](../skills/azure-pricing/SKILL.md)
`gh skills install github/awesome-copilot azure-pricing` | Fetches real-time Azure retail pricing using the Azure Retail Prices API (prices.azure.com) and estimates Copilot Studio agent credit consumption. Use when the user asks about the cost of any Azure service, wants to compare SKU prices, needs pricing data for a cost estimate, mentions Azure pricing, Azure costs, Azure billing, or asks about Copilot Studio pricing, Copilot Credits, or agent usage estimation. Covers compute, storage, networking, databases, AI, Copilot Studio, and all other Azure service families. | `references/COPILOT-STUDIO-RATES.md`
`references/COST-ESTIMATOR.md`
`references/REGIONS.md`
`references/SERVICE-NAMES.md` | | [azure-resource-health-diagnose](../skills/azure-resource-health-diagnose/SKILL.md)
`gh skills install github/awesome-copilot azure-resource-health-diagnose` | Analyze Azure resource health, diagnose issues from logs and telemetry, and create a remediation plan for identified problems. | None | | [azure-resource-visualizer](../skills/azure-resource-visualizer/SKILL.md)
`gh skills install github/awesome-copilot azure-resource-visualizer` | Analyze Azure resource groups and generate detailed Mermaid architecture diagrams showing the relationships between individual resources. Use this skill when the user asks for a diagram of their Azure resources or help in understanding how the resources relate to each other. | `LICENSE.txt`
`assets/template-architecture.md` | diff --git a/skills/azure-devops-cli/SKILL.md b/skills/azure-devops-cli/SKILL.md index b2a5298cd..c34f2c40f 100644 --- a/skills/azure-devops-cli/SKILL.md +++ b/skills/azure-devops-cli/SKILL.md @@ -79,61 +79,6 @@ az artifacts # Azure Artifacts └── universal # Universal Packages ``` -## Posting long comments on Windows - -On Windows the `az` command resolves to `az.cmd`, a batch wrapper invoked by `cmd.exe`. The whole command line is capped at ~8191 characters, so a long `--discussion`, `--description`, or `--content` value can be silently truncated or fail. Detect the shell before composing a long argument and route accordingly. Skipping this is the most common reason the agent burns 3-5 turns falling back to raw token retrieval and REST calls. - -### Detect the shell first - -| Environment | Signal | Action | -|---|---|---| -| PowerShell on Windows | `$IsWindows -eq $true` and `$PSVersionTable.PSVersion` is set | Use `azps.ps1` (see below) | -| PowerShell on macOS / Linux | `$IsWindows -eq $false` | Plain `az` is fine, no cmd.exe wrapper | -| bash / zsh / sh | `$BASH_VERSION` or `$ZSH_VERSION` set, or `uname` works | Plain `az` is fine, no cmd.exe wrapper | -| Windows `cmd.exe` | `%ComSpec%` ends in `cmd.exe`, no `$PSVersionTable` | Use `azps.ps1` if PowerShell is installed, otherwise see `az devops invoke` fallback below | - -### Option 1: `azps.ps1` (PowerShell on Windows) - -`azps.ps1` ships with the Azure CLI installer and invokes the Python entry point directly. No `cmd.exe` length cap. - -```powershell -# Read the long body into a variable and pass it through. No quoting headaches. -$body = Get-Content -Raw .\comment.md -azps.ps1 boards work-item update --id 1234 --discussion $body -``` - -### Option 2: dedicated `--file-path` flag where Azure CLI offers one - -Some commands have a native file flag and you should prefer it over any inline body: - -- `az devops wiki page create` and `az devops wiki page update` take `--file-path` (with optional `--encoding`). -- Use it on any shell, including Windows. - -```bash -az devops wiki page create --path 'My page' --wiki myproject --file-path ./page.md --encoding utf-8 -``` - -### Option 3: `az devops invoke` fallback - -When no `--file-path` exists (work-item `--discussion`, PR `--description`) and you're not in PowerShell, post the body via the underlying REST API. `az devops invoke` runs inside the Python entry point, so it isn't subject to the `cmd.exe` cap either, and it takes the request body from a file with `--in-file`: - -```bash -# Post a long discussion comment to work item 1234. -# REST: POST /{project}/_apis/wit/workItems/{id}/comments?api-version=7.0-preview.3 -az devops invoke \ - --area wit --resource comments \ - --route-parameters project={project} workItemId=1234 \ - --api-version 7.0-preview.3 \ - --http-method POST \ - --in-file ./comment.json -``` - -Where `comment.json` is `{ "text": "" }`. This is the universal escape hatch when neither `azps.ps1` nor `--file-path` is available. `az devops invoke` itself accepts `--in-file` natively. - -### Don't rely on `@` for plain string args - -The Azure CLI `@` convention is documented for JSON parameters (see [the official quoting guide](https://learn.microsoft.com/en-us/cli/azure/use-azure-cli-successfully-quoting)). It is not guaranteed to expand plain string args like `--discussion` or `--description`, so don't reach for it as a substitute for the three options above. - ## Reference Files Read the relevant reference file based on the user's task. Each file contains complete command syntax and examples for its domain. @@ -147,3 +92,4 @@ Read the relevant reference file based on the user's task. Each file contains co | `references/org-and-security.md` | Projects, teams, users, permissions, wikis | Projects, Extensions, Teams, Users, Security groups/permissions, Service endpoints, Wikis, Admin | | `references/advanced-usage.md` | Output formatting, JMESPath queries | Output formats, JMESPath queries (basic + advanced), Global args, Common params, Git aliases | | `references/workflows-and-patterns.md` | Automation scripts, best practices, error handling | Common workflows, Best practices, Error handling, Scripting patterns, Real-world examples | +| `references/long-comments-on-windows.md` | Long `--discussion`, `--description`, or `--content` values failing on Windows | The `cmd.exe` 8191 char cap on `az.cmd`, shell detection, and three verified workarounds (`azps.ps1`, native `--file-path`, `az devops invoke --in-file`) | diff --git a/skills/azure-devops-cli/references/boards-and-iterations.md b/skills/azure-devops-cli/references/boards-and-iterations.md index 7de6486e8..dc884ba49 100644 --- a/skills/azure-devops-cli/references/boards-and-iterations.md +++ b/skills/azure-devops-cli/references/boards-and-iterations.md @@ -56,9 +56,9 @@ az boards work-item create \ --type Bug \ --discussion "Initial investigation completed" -# For a long --discussion body on Windows, see "Posting long comments on Windows" -# in SKILL.md. Short version: use azps.ps1 in PowerShell, or fall back to -# 'az devops invoke' with --in-file when no native --file-path flag is available. +# For a long --discussion body on Windows, see references/long-comments-on-windows.md. +# Short version: use azps.ps1 in PowerShell, or fall back to 'az devops invoke' +# with --in-file when no native --file-path flag is available. # Open in browser after creation az boards work-item create --title "Bug" --type Bug --open @@ -91,7 +91,7 @@ az boards work-item update \ # Long comment on Windows: read the body into a PowerShell variable and call # azps.ps1 instead of az.cmd, or fall back to 'az devops invoke' with --in-file. -# Full guidance in SKILL.md under "Posting long comments on Windows". +# Full guidance in references/long-comments-on-windows.md. # # PowerShell example: # $body = Get-Content -Raw .\comment.md diff --git a/skills/azure-devops-cli/references/long-comments-on-windows.md b/skills/azure-devops-cli/references/long-comments-on-windows.md new file mode 100644 index 000000000..5fdcd6a8f --- /dev/null +++ b/skills/azure-devops-cli/references/long-comments-on-windows.md @@ -0,0 +1,54 @@ +# Posting Long Comments and Bodies on Windows + +On Windows the `az` command resolves to `az.cmd`, a batch wrapper invoked by `cmd.exe`. The whole command line is capped at ~8191 characters, so a long `--discussion`, `--description`, or `--content` value can be silently truncated or fail. Detect the shell before composing a long argument and route accordingly. Skipping this is the most common reason the agent burns 3-5 turns falling back to raw token retrieval and REST calls. + +## Detect the shell first + +| Environment | Signal | Action | +|---|---|---| +| PowerShell on Windows | `$IsWindows -eq $true` and `$PSVersionTable.PSVersion` is set | Use `azps.ps1` (see below) | +| PowerShell on macOS / Linux | `$IsWindows -eq $false` | Plain `az` is fine, no cmd.exe wrapper | +| bash / zsh / sh | `$BASH_VERSION` or `$ZSH_VERSION` set, or `uname` works | Plain `az` is fine, no cmd.exe wrapper | +| Windows `cmd.exe` | `%ComSpec%` ends in `cmd.exe`, no `$PSVersionTable` | Use `azps.ps1` if PowerShell is installed, otherwise see `az devops invoke` fallback below | + +## Option 1: `azps.ps1` (PowerShell on Windows) + +`azps.ps1` ships with the Azure CLI installer and invokes the Python entry point directly. No `cmd.exe` length cap. + +```powershell +# Read the long body into a variable and pass it through. No quoting headaches. +$body = Get-Content -Raw .\comment.md +azps.ps1 boards work-item update --id 1234 --discussion $body +``` + +## Option 2: dedicated `--file-path` flag where Azure CLI offers one + +Some commands have a native file flag and you should prefer it over any inline body: + +- `az devops wiki page create` and `az devops wiki page update` take `--file-path` (with optional `--encoding`). +- Use it on any shell, including Windows. + +```bash +az devops wiki page create --path 'My page' --wiki myproject --file-path ./page.md --encoding utf-8 +``` + +## Option 3: `az devops invoke` fallback + +When no `--file-path` exists (work-item `--discussion`, PR `--description`) and you're not in PowerShell, post the body via the underlying REST API. `az devops invoke` runs inside the Python entry point, so it isn't subject to the `cmd.exe` cap either, and it takes the request body from a file with `--in-file`: + +```bash +# Post a long discussion comment to work item 1234. +# REST: POST /{project}/_apis/wit/workItems/{id}/comments?api-version=7.0-preview.3 +az devops invoke \ + --area wit --resource comments \ + --route-parameters project={project} workItemId=1234 \ + --api-version 7.0-preview.3 \ + --http-method POST \ + --in-file ./comment.json +``` + +Where `comment.json` is `{ "text": "" }`. This is the universal escape hatch when neither `azps.ps1` nor `--file-path` is available. `az devops invoke` itself accepts `--in-file` natively. + +## Don't rely on `@` for plain string args + +The Azure CLI `@` convention is documented for JSON parameters (see [the official quoting guide](https://learn.microsoft.com/en-us/cli/azure/use-azure-cli-successfully-quoting)). It is not guaranteed to expand plain string args like `--discussion` or `--description`, so don't reach for it as a substitute for the three options above.