# Azure Devops

> Complete Azure DevOps automation - boards, repos, pipelines, artifacts

- Skill: `rysweet/azure-devops-3` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add rysweet/azure-devops-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/rysweet/azure-devops-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: rysweet (https://skillmd.com/u/rysweet)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/rysweet/azure-devops-3

---


# 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:**

```bash
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
```bash
python .claude/scenarios/az-devops-tools/create_work_item.py \
  --type "User Story" \
  --title "Implement feature" \
  --description @story.md
```

#### Query Work Items
```bash
python .claude/scenarios/az-devops-tools/list_work_items.py --query mine
```

#### Create Pull Request
```bash
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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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):

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

**Option B:** Link separately:

```bash
# 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 `.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](.claude/scenarios/az-devops-tools/README.md)

## 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

```bash
# 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
```