Azure DevOps Boards integration with az boards CLI

version
1.2.0
GitHub stars
13

Install

/plugin install azure-boards@claude-code-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add dariuszparys/claude-code-toolkit.

Contents

Discovered from source

Skills 1

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 FieldYAML PathNotes
Titlefields.System.TitlePlain text
Descriptionfields.System.DescriptionHTML-formatted, strip tags
Acceptance Criteriafields.Microsoft.VSTS.Common.AcceptanceCriteriaHTML-formatted
Statefields.System.StateNew, Active, Resolved, Closed
Assigned Tofields.System.AssignedToUser object
Iteration Pathfields.System.IterationPathSprint path
Priorityfields.Microsoft.VSTS.Common.Priority1-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"

Agents 1

Azure Boards Plugin

Azure DevOps Boards integration for Claude Code. Provides an auto-invoked skill for working with Product Backlog Items (PBIs), Bugs, and Tasks using the az boards CLI.

Prerequisites

1. Azure CLI

Install the Azure CLI:

# macOS
brew install azure-cli

# Windows
winget install Microsoft.AzureCLI

# Linux (Ubuntu/Debian)
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

2. Azure DevOps CLI Extension

Install the Azure DevOps extension:

az extension add --name azure-devops

3. Personal Access Token (PAT)

Create a PAT with the required permissions:

  1. Go to Azure DevOps → User Settings → Personal Access Tokens

  2. Click New Token

  3. Set the following:

    • Name: claude-code-boards (or any name)
    • Organization: Select your organization
    • Expiration: Set appropriate expiration
    • Scopes: Select Custom defined, then:
      • Work Items: Read & Write
      • Project and Team: Read (optional, for iteration paths)
  4. Copy the token and store it securely

4. Authentication

Authenticate with your PAT:

# Option A: Environment variable (recommended)
export AZURE_DEVOPS_EXT_PAT=<your-pat>

# Option B: Login interactively
az login

# Option C: Login with PAT directly
az devops login --token <your-pat>

Configuration

Set your default organization and project:

az devops configure --defaults \
  organization=https://dev.azure.com/<your-org> \
  project=<your-project>

Verify Configuration

# Test the connection
az boards work-item show --id 1

# List your assigned work items
az boards query --wiql "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.AssignedTo] = @Me" --output table

Customization

Iteration Path

The skill uses iteration paths for sprint queries. Update the SKILL.md if your organization uses a different iteration path structure:

Default pattern: {Project}\{Sprint} Example: MyProject\Sprint 1

Some organizations use deeper paths:

  • MyProject\Release 1\Sprint 1
  • MyProject\2024\Q1\Sprint 1

Work Item Types

The skill is configured for common work item types:

  • Product Backlog Item
  • Bug
  • Task

If your organization uses custom work item types, you may need to update the WIQL queries in the skill.

What This Plugin Provides

Auto-Invoked Skill

The azure-boards skill is automatically invoked by Claude when you:

  • Mention Azure DevOps, Azure Boards, or PBI
  • Provide a work item ID to fetch or update
  • Ask about sprint work or iteration paths
  • Need WIQL queries

Capabilities

OperationCommand
Fetch work itemaz boards work-item show --id {id}
Update fieldsaz boards work-item update --id {id} --fields ...
Query work itemsaz boards query --wiql "..."
Create taskaz boards work-item create --type Task ...

Usage Examples

Once the plugin is installed and configured, Claude will automatically use Azure Boards commands when relevant:

User: "Show me PBI 12345"
Claude: [Uses az boards work-item show --id 12345]

User: "What work items are assigned to me in Sprint 3?"
Claude: [Uses az boards query with WIQL for your sprint]

User: "Update the description of work item 12345"
Claude: [Uses az boards work-item update]

Troubleshooting

"az: command not found"

Azure CLI is not installed or not in PATH. Install it following the prerequisites above.

"The following extension is not installed: azure-devops"

Run: az extension add --name azure-devops

"TF401019: The Git repository with name or identifier does not exist"

Your default project is not set correctly:

az devops configure --defaults project=<correct-project-name>

"VS403392: Personal access token is invalid"

Your PAT may have expired or lacks the required permissions. Create a new token with Work Items: Read & Write scope.

"The iteration path does not exist"

Your iteration path format may differ. Check your organization's iteration structure:

az boards iteration project list --output table

Sponsors

Details

Marketplace
dariuszparys/claude-code-toolkit
Source
plugins/azure-boards
Category
Community

More from dariuszparys/claude-code-toolkit

All 6