name: azure-boards description: Work with Azure DevOps Product Backlog Items using az boards CLI user-invocable: false when_to_use: | Use this skill when:

• Fetching a work item by ID (e.g., "get PBI 12345", "show me work item #6789")
• Updating Azure DevOps fields like Description, Acceptance Criteria, or State
• Querying work items with WIQL (e.g., "what's assigned to me", "sprint items")
• Creating tasks under a Product Backlog Item or Bug
• Parsing HTML-formatted fields from Azure DevOps responses
• Working with iteration paths, area paths, or sprint planning
• Using az boards CLI commands for any Azure DevOps operation

Azure Boards Skill

Use the Azure CLI (az boards) to interact with Azure DevOps work items.

Prerequisites

Ensure Azure CLI is authenticated:

az login
az devops configure --defaults organization=https://dev.azure.com/{org} project={project}

Fetching Work Items

Single Work Item

az boards work-item show --id {id} --output yaml

Field Mapping

HTML Parsing Notes

• Description and Acceptance Criteria are HTML-formatted
• Strip <div>, <p>, <ul>, <li>, <code> tags before processing
• Look for embedded sections as <h3> or <b> headers:
  • "Files to modify" -> extract file paths
  • "Scope" or "Architecture" -> extract context
  • Numbered/bulleted lists -> extract changes

Updating Work Items

Update Fields

az boards work-item update --id {id} \
  --fields \
    "System.Description={description_html}" \
    "Microsoft.VSTS.Common.AcceptanceCriteria={criteria_markdown}"

Field Formats

• System.Description: HTML with <h3>, <p>, <ul>, <ol>, <li>, <code> tags
• Microsoft.VSTS.Common.AcceptanceCriteria: Markdown bullet list (no checkboxes)

Example Update

az boards work-item update --id 12345 \
  --fields \
    "System.Description=<h3>Context</h3><p>Switch to internal ingress.</p><h3>Files</h3><ul><li><code>container-app.bicep</code></li></ul>" \
    "Microsoft.VSTS.Common.AcceptanceCriteria=- Direct URL returns 403\n- Front Door URL returns 200"

WIQL Queries

My Active Work Items

SELECT [System.Id], [System.Title], [System.State], [System.WorkItemType], [Microsoft.VSTS.Common.Priority]
FROM WorkItems
WHERE [System.AssignedTo] = @Me
  AND [System.WorkItemType] IN ('Product Backlog Item', 'Bug')
  AND [System.State] NOT IN ('Closed', 'Removed', 'Resolved')
ORDER BY [Microsoft.VSTS.Common.Priority] ASC, [System.WorkItemType] ASC

Sprint Work Items

SELECT [System.Id], [System.Title], [System.State]
FROM WorkItems
WHERE [System.AssignedTo] = @Me
  AND [System.IterationPath] = '{iteration_path}'
  AND [System.State] NOT IN ('Closed', 'Removed')

Execute WIQL

az boards query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.AssignedTo] = @Me" --output table

Creating Tasks Under a PBI

az boards work-item create \
  --type Task \
  --title "Task title" \
  --description "Task description" \
  --fields "System.Parent={pbi_id}"

Common Operations

List Work Item Types

az boards work-item type list --output table

Show Work Item Relations

az boards work-item show --id {id} --expand relations

Add Comment

az boards work-item update --id {id} --discussion "Comment text"