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

Azure DevOps Field	YAML Path	Notes
Title	fields.System.Title	Plain text
Description	fields.System.Description	HTML-formatted, strip tags
Acceptance Criteria	fields.Microsoft.VSTS.Common.AcceptanceCriteria	HTML-formatted
State	fields.System.State	New, Active, Resolved, Closed
Assigned To	fields.System.AssignedTo	User object
Iteration Path	fields.System.IterationPath	Sprint path
Priority	fields.Microsoft.VSTS.Common.Priority	1-4

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"