Azure DevOps PBI Skill

Status: Production Ready

This skill helps an agent turn active work into a clear Azure DevOps Product Backlog Item with linked child tasks. It is meant for prompts like "create the PBI", "add tasks to this PBI", or "clean up the acceptance criteria" after the agent has enough project context. By default, "create the PBI" includes creating linked child tasks unless the user asks for PBI-only or draft-only output, Azure access blocks writes, or the scope is too unclear to ticket responsibly.

Setup

From the repository root, most team members should install it for GitHub Copilot:

scripts/setup-azure-devops-pbi-skill.sh copilot /path/to/project-repo

For Codex:

scripts/setup-azure-devops-pbi-skill.sh codex

For Cursor:

scripts/setup-azure-devops-pbi-skill.sh cursor /path/to/project-repo

The setup command reads the Azure DevOps project from references/project-profile.md, installs the skill, checks Azure DevOps access, and runs a read-only preflight for that project only. See New User Setup if setup cannot finish.

Setup uses normal az login with the user's own work account. It does not require a shared PAT. If installing the Azure DevOps CLI extension fails with SSLCertVerificationError, see New User Setup for corporate TLS inspection and certificate bundle guidance.

Parent Feature Or Epic

The safest prompt includes the parent Feature or Epic:

Create the PBI for this work under Feature 12345.

If the parent is not provided, the agent tries to infer it from the current conversation, product repo, branch, docs, or related Azure work item links. If it infers the parent, it must confirm before writing to Azure.

If there is no good Feature but the Epic is clear, the agent should propose a new Feature under that Epic and wait for approval. If neither the Epic nor Feature is clear, it should ask for the parent work item ID or URL and can provide a ready-to-paste draft while waiting.

What It Does

• Finds or confirms the target Azure DevOps project and parent Feature/Epic.
• Uses current work context so the PBI reflects the real requirement.
• Checks nearby PBIs before choosing the title style, task structure, estimates, and testing pattern.
• Creates linked child tasks by default for new PBIs; the user does not need to separately say "and add tasks."
• Adds blocked testing tasks when similar PBIs show that pattern and a qualified tester has capacity.
• Checks that the parent PBI is Committed before starting child task execution.
• Requires explicit Scrum Master or authorized approver approval before moving a PBI to Committed.
• Writes safe dashboard metadata into Azure Boards discussion comments for PBI/task creation, human-vs-agent attribution, agent host/model, workflow outcome, and token usage estimates.
• Creates or updates the PBI, links child tasks, and verifies the final board state.

PBI Lifecycle Rules

The skill can draft or prepare backlog items before commitment, but task execution cannot start until the parent PBI is in Committed status. Before moving a child task to In Progress or recording task burn-down, the agent must verify the parent PBI state.

Creating child tasks in a non-started state is backlog preparation, not task execution. The agent should not skip child task creation merely because the PBI has not been committed yet.

The agent must not move a PBI to Committed unless the user provides explicit approval from the Scrum Master or another authorized approver. If approval is not clear, it should stop and ask for the approval source or provide ready-to-paste approval next steps.

Analytics Metadata And Token Estimates

The skill writes a small agent-analytics:v1 metadata block to Azure Boards discussion comments on PBIs and tasks it touches. A central collector can read those comments later and build the dashboard. This avoids per-developer dashboard API calls, local services, OS-specific setup, and dashboard credentials on team member machines.

When cumulative token counters are available, the estimate is computed from the difference between the start and end counters and labeled as an agent/session-log estimate rather than an official billing report. If counters are unavailable or the interval cannot be separated from unrelated work, the agent should skip the metric rather than inventing one.

Metadata can include PBI and task IDs, safe summaries, agent host, model, skill version, human-vs-agent attribution, workflow outcome, and token usage estimates. Metadata write failures should not block safe Azure Boards work.

Typical Output

• A linked PBI with a clear title, description, acceptance criteria, and linked child tasks.
• Child tasks that match nearby work, including blocked testing work when the pattern exists.
• A final verification summary with the PBI URL, PBI state, task IDs, states, estimates, and open questions.
• Analytics metadata status and a token usage estimate when the runtime exposed a reliable counter interval.

Testing

Use Azure DevOps PBI Skill Test Scenarios to dry-run common roadblocks before relying on the skill for live Azure writes. Run the controlled live test only with an approved test Feature or real parent work item.

Example Prompts

Create the PBI for this work under Feature 12345.

Create the PBI for this work. If there is no good Feature, propose one under Epic 67890 first.

Add tasks to the PBI and use similar PBIs for the estimates.

Shorten the PBI description and acceptance criteria now that tasks exist.

Requirements

• Azure CLI with the Azure DevOps extension available.
• Access to this skill's configured Azure DevOps organization/project. Access to other projects is not required.
• Local Azure DevOps authentication using normal az login with the developer's own account. A user-owned PAT is only a fallback when browser login is not available.
• A parent work item URL, a clear parent in the existing work context, or user approval for a proposed parent/new Feature.
• A Committed parent PBI before task execution starts, or explicit Scrum Master/authorized approver approval before committing the PBI.
• Permission to add discussion comments to the affected Azure Boards PBIs and tasks.

If Azure access fails, the skill should still produce ready-to-paste PBI details and task breakdowns.

See PBI Agent Analytics Dashboard Proposal, Skills Architecture, and Agent Analytics Metadata Contract for the dashboard architecture, event model, and parser contract.