
azure-boards
Azure DevOps Boards integration with az boards CLI
- version
- 1.2.0
- GitHub stars
- 13
Install
/plugin install azure-boards@claude-code-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add dariuszparys/claude-code-toolkit.
Contents
Discovered from sourceSkills 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 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>tagsMicrosoft.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:
-
Go to Azure DevOps → User Settings → Personal Access Tokens
-
Click New Token
-
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)
- Name:
-
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 1MyProject\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
| Operation | Command |
|---|---|
| Fetch work item | az boards work-item show --id {id} |
| Update fields | az boards work-item update --id {id} --fields ... |
| Query work items | az boards query --wiql "..." |
| Create task | az 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