Azure DevOps Skill

Complete Azure DevOps integration covering boards, repositories, pipelines, and artifacts.

Auto-activates when: User mentions Azure DevOps, ADO, work items, boards, repos, pipelines, artifacts, or Azure DevOps URLs.

Purpose

This skill provides comprehensive guidance for Azure DevOps automation through purpose-built Python CLI tools that handle:

Work Items (Boards)

• Work item creation with HTML-formatted descriptions

• Work item updates (state, assignments, fields)

• Work item deletion with confirmation

• Parent-child relationship linking

• WIQL query execution

• Work item type and field discovery

Repositories

• Repository listing with details

• Pull request creation with reviewers and work items

• Branch validation

• Clone URL access

Pipelines

• Pipeline listing and execution

• Build monitoring and logs

• Deployment management

Artifacts

• Package feed management

• Package publishing and downloading

• Version management

Quick Start

1. Authentication First

ALWAYS start by checking authentication:

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

This verifies Azure CLI is installed, you're logged in, org/project are configured, and you have access.

See: [@authentication.md]

2. Common Operations

Create Work Item

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "User Story"
--title "Implement feature"
--description @story.md

Query Work Items

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

Create Pull Request

python .claude/scenarios/az-devops-tools/create_pr.py
--source feature/branch
--target main
--title "Add feature"

Progressive Loading References

For detailed guidance on specific operations, see:

• [@authentication.md] - Authentication methods (PAT, OAuth, environment variables)

• [@work-items.md] - Work item CRUD operations, field updates, state transitions

• [@queries.md] - WIQL query patterns, filtering, sorting

• [@html-formatting.md] - HTML formatting in work item descriptions/comments

• [@repos.md] - Repository operations, pull request workflows

• [@pipelines.md] - Pipeline triggers, build monitoring, deployment

• [@artifacts.md] - Package management, artifact publishing

• [@HOW_TO_CREATE_YOUR_OWN.md] - Template for creating similar integration tools

Available Tools

Tool Purpose When to Use

auth_check.py

Verify authentication Before any operations

create_work_item.py

Create work items Add User Stories, Tasks, Bugs, etc.

update_work_item.py

Update work items Change state, assignee, fields

delete_work_item.py

Delete work items Remove work items (with confirmation)

get_work_item.py

Get work item details View complete work item info

list_work_items.py

Query work items Find, filter, and list work items

link_parent.py

Link parent-child Create Epic → Feature → Story hierarchies

query_wiql.py

Execute WIQL queries Complex filtering with WIQL

format_html.py

Convert to HTML Format rich descriptions

list_types.py

Discover types/fields Explore available options

list_repos.py

List repositories View all repositories in project

create_pr.py

Create pull request Submit code for review

Common Patterns

Pattern 1: Create Work Item with Parent

Create parent work item

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Epic"
--title "Q1 Planning Initiative"
--description @epic_desc.md

Output: Created work item #12345

Create child and link to parent

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Feature"
--title "Authentication System"
--description @feature_desc.md
--parent-id 12345

Output: Created work item #12346 and linked to parent #12345

Pattern 2: Query and Update Work Items

Find your active work items

python .claude/scenarios/az-devops-tools/list_work_items.py
--query mine
--format ids-only

Update work item state

python .claude/scenarios/az-devops-tools/update_work_item.py
--id 12345
--state "Active"
--comment "Starting work on this"

Pattern 3: Feature Branch to Pull Request

List repositories

python .claude/scenarios/az-devops-tools/list_repos.py

Create pull request

python .claude/scenarios/az-devops-tools/create_pr.py
--source feature/auth
--target main
--title "Add authentication"
--description @pr_desc.md
--reviewers "user1@domain.com,user2@domain.com"
--work-items "12345,12346"

Pattern 4: Discover Available Types

List all work item types in your project

python .claude/scenarios/az-devops-tools/list_types.py

Show fields for specific type

python .claude/scenarios/az-devops-tools/list_types.py
--type "User Story"
--fields

Critical Learnings

HTML Formatting Required

Azure DevOps work item descriptions use HTML, not Markdown or plain text.

The tools handle this automatically:

• create_work_item.py converts markdown to HTML by default

• Use --no-html to disable conversion

• Or use format_html.py directly for custom formatting

See: [@html-formatting.md]

Two-Step Parent Linking

You cannot specify a parent during work item creation via CLI (Azure limitation).

The tools provide two approaches:

Option A: Use --parent-id flag (recommended):

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Task"
--title "My Task"
--parent-id 12345

Option B: Link separately:

Step 1: Create

TASK_ID=$(python .claude/scenarios/az-devops-tools/create_work_item.py
--type "Task"
--title "My Task"
--json | jq -r '.id')

Step 2: Link

python .claude/scenarios/az-devops-tools/link_parent.py
--child $TASK_ID
--parent 12345

Area Path and Work Item Types

• Area path format: ProjectName\TeamName\SubArea

• Work item types vary by project (standard + custom types)

• Use list_types.py to discover what's available in your project

Error Recovery

Error Tool to Use Example

Authentication failed auth_check.py --auto-fix

Auto-login and configure

Invalid work item type list_types.py

See available types

Field validation error list_types.py --type "Type" --fields

See valid fields

Parent link failed Check IDs exist, verify hierarchy rules Epic → Feature → Story → Task

Branch does not exist Verify with git branch -a

Push branch first

Tool Implementation

All tools are in ~/.amplihack/.claude/scenarios/az-devops-tools/ :

• Standalone Python programs (can run independently)

• Importable modules (can use in other scripts)

• Comprehensive error handling

• Tests in tests/ directory

See: Tool README

Philosophy

These tools follow amplihack principles:

• Ruthless Simplicity: Each tool does one thing well

• Zero-BS: Every function works, no stubs or TODOs

• Reusable: Importable and composable

• Fail-Fast: Clear errors with actionable guidance

• Self-Contained: Standard library + azure CLI wrapper only

Quick Reference

Setup (first time)

python .claude/scenarios/az-devops-tools/auth_check.py --auto-fix

Create work item

python .claude/scenarios/az-devops-tools/create_work_item.py
--type "User Story"
--title "Title"
--description @desc.md

Update work item

python .claude/scenarios/az-devops-tools/update_work_item.py
--id 12345
--state "Active"

Query work items

python .claude/scenarios/az-devops-tools/list_work_items.py --query mine

Create pull request

python .claude/scenarios/az-devops-tools/create_pr.py
--source feature/branch
--target main
--title "Add feature"

Discover types

python .claude/scenarios/az-devops-tools/list_types.py