Guide for creating Azure DevOps work items (Features, User Stories, Tasks). This skill should be used when working with ADO MCP tools to create work items with proper hierarchy and formatting.
Instrucciones de origen · Vista previa de solo lectura
name
ado-work-items
description
Guide for creating Azure DevOps work items (Features, User Stories, Tasks). This skill should be used when working with ADO MCP tools to create work items with proper hierarchy and formatting.
dependencies
Azure DevOps MCP Server (@azure-devops/mcp)
disable-model-invocation
true
Azure DevOps Work Items Skill
This skill provides guidance on creating and managing Azure DevOps work items when using the Azure DevOps MCP server tools. It ensures work items follow organizational best practices for hierarchy, formatting, naming conventions, and hour estimation.
When to Use This Skill
This skill should be used when:
Creating Features, User Stories, or Tasks in Azure DevOps
Planning work item hierarchies for a feature or epic
Structuring acceptance criteria or task descriptions
Applying naming conventions to work items
Estimating hours or story points for work items
Using the @azure-devops/mcp MCP server tools
Work Item Hierarchy
Azure DevOps uses a three-level structure for Agile projects:
Features (top level) - High-level capabilities or business objectives
User Stories (child of Features) - Specific functionality from a user perspective
Tasks (child of User Stories) - Individual work items for implementation
Key Rules:
Every User Story must belong to a Feature (parent-child relationship)
Every Task must belong to a User Story (parent-child relationship)
Features contain one or more User Stories
User Stories contain one or more Tasks
HTML Formatting Requirement
CRITICAL: All text fields (Description, Acceptance Criteria) must use proper HTML formatting for correct rendering in Azure DevOps.
Examples:
<!-- Good: Proper HTML --><p>As a developer, I need to implement user authentication.</p><p><strong>Background:</strong></p><ul><li>Current system has no authentication</li><li>Users need secure login</li></ul><!-- Bad: Plain text -->
As a developer, I need to implement user authentication.
Background:
- Current system has no authentication
- Users need secure login
HTML Formatting Guidelines:
Use <p> tags for paragraphs
Use <ul> and <li> for bullet lists
Use <ol> and <li> for numbered lists
Use <strong> for bold text
Use <em> for italic text
Use <h3>, <h4> for section headers (if needed)
Feature Requirements
Purpose: High-level business capability or objective containing related User Stories.
Description Field:
Provide a simple, high-level summary of the feature
Explain the business value or objective
Avoid fine implementation details (those belong in User Stories)
Use HTML formatting with <p> tags and lists
Example Feature:
Title: 1: User Authentication System
Description:
<p>Implement a complete user authentication system with login, registration, and password reset capabilities.</p>
<p><strong>Business Value:</strong></p>
<ul>
<li>Enable secure access to the application</li>
<li>Support personalized user experiences</li>
<li>Meet security compliance requirements</li>
</ul>
Field Settings:
Area Path: Set to appropriate team area
Iteration Path: Set to target sprint/iteration
State: "New" (default for new work items)
Assigned To: Leave unassigned (team members assign themselves)
User Story Requirements
Purpose: Specific functionality described from a user perspective, containing implementation Tasks.
Structure
Each User Story belongs to exactly one parent Feature
Each User Story contains one or more child Tasks
User Stories remain unassigned until team members pick them up
Description Field Format
Use HTML formatting with this structure:
<p><strong>As a</strong> [user persona], <strong>I want to</strong> [capability], <strong>so that</strong> [benefit].</p><p><strong>Background:</strong></p><ul><li>[Context point 1]</li><li>[Context point 2]</li><li>[Context point 3]</li></ul><p><strong>Additional Information:</strong></p><ul><li>[Implementation detail 1]</li><li>[Implementation detail 2]</li></ul>
Example:
<p><strong>As a</strong> website visitor, <strong>I want to</strong> register for an account, <strong>so that</strong> I can access personalized features.</p><p><strong>Background:</strong></p><ul><li>Current system has no user accounts</li><li>Marketing team requires user tracking</li><li>Future features depend on user identity</li></ul><p><strong>Additional Information:</strong></p><ul><li>Email should be the unique identifier</li><li>Password strength validation required</li><li>Email verification recommended but not required for MVP</li></ul>
Acceptance Criteria Format
Use the "Given, When, Then" format with HTML:
<p><strong>Scenario 1: Successful Registration</strong></p><ul><li><strong>Given</strong> I am on the registration page</li><li><strong>When</strong> I enter valid email and password</li><li><strong>Then</strong> my account is created and I am logged in</li></ul><p><strong>Scenario 2: Invalid Email</strong></p><ul><li><strong>Given</strong> I am on the registration page</li><li><strong>When</strong> I enter an invalid email format</li><li><strong>Then</strong> I see an error message and cannot submit</li></ul>
Guidelines:
Keep criteria concise and testable
Focus on observable behavior, not implementation
Use bullet points for readability
Structure for QA testers to execute
Story Points
Apply Fibonacci sequence values to the "Story Points" field to estimate relative complexity:
1 - Trivial change, very well understood
2 - Simple change, clear requirements
3 - Moderate complexity, some uncertainty
5 - Complex change, multiple components
8 - Very complex, significant uncertainty
13 - Epic-level work (consider breaking down)
Field Settings:
Area Path: Set to appropriate team area
Iteration Path: Set to target sprint/iteration
State: "New"
Assigned To: Leave unassigned
Story Points: Fibonacci value (1, 2, 3, 5, 8, 13)
Task Requirements
Purpose: Lightweight work tracking items representing individual implementation activities.
Structure
Each Task belongs to exactly one parent User Story
Tasks do NOT have Description or Acceptance Criteria fields
Tasks reference the parent User Story for all context
Tasks remain unassigned until developers pick them up
Title Format
Keep Task titles simple and descriptive, focused on the work activity:
Good Task Titles:
"Implement registration API endpoint"
"Create registration form UI"
"Write unit tests for registration flow"
"Add email validation logic"
"Update database schema for users table"
Bad Task Titles:
"Do the registration stuff" (too vague)
"As a user I want to register..." (that's the User Story, not a Task)
"Registration" (not specific enough)
Hour Estimation
Tasks are the primary container for hour tracking. Set both fields to the same estimated value:
Original Estimate: Total hours estimated to complete the work
Remaining Work: Same value as Original Estimate (initially)
Completed Work: Leave empty (will be filled during work)
Example:
Original Estimate: 4
Remaining Work: 4
Completed Work: (empty)
Estimation Guidelines:
Break tasks into 2-8 hour chunks when possible
Tasks over 16 hours should be split into smaller tasks
Be realistic and include testing/debugging time
Consider code review and documentation time
Field Settings:
Area Path: Inherited from parent User Story (or set explicitly)
Iteration Path: Inherited from parent User Story (or set explicitly)
State: "New"
Assigned To: Leave unassigned
Original Estimate: Hours (e.g., 4)
Remaining Work: Same as Original Estimate
Naming Convention Standards
Azure DevOps lacks robust priority sorting, so naming conventions ensure proper organization in the backlog.
Features Naming
Format:[NUMBER]: [DESCRIPTION]
Prefix with a single digit from 1-99
Use the number to indicate priority/sequence
Keep description concise and business-focused
Examples:
"1: User Authentication System"
"2: Product Catalog Management"
"3: Shopping Cart and Checkout"
User Stories Naming
There are two supported naming conventions. Check the project's CLAUDE.md file for the configured convention, or ask which convention to use before creating User Stories.
Check Configuration First: Before creating work items, check if the project has Azure DevOps configuration in CLAUDE.md that specifies organization, project, team, area path, iteration path, and naming convention preferences.
Always Use HTML: Never use plain text or markdown in Description or Acceptance Criteria fields - always use proper HTML formatting.
Maintain Hierarchy: Never create orphaned work items. Every User Story needs a parent Feature, every Task needs a parent User Story.
Check Naming Convention: If not specified in CLAUDE.md, ask which naming convention is preferred (decimal notation like 1.1, 1.2 or simple descriptive names) before creating User Stories.
Keep Tasks Lightweight: Tasks should not duplicate the User Story's description or acceptance criteria. They should be simple work containers with just a title and hour estimates.
Leave Assignments Blank: Let team members assign themselves to work items during sprint planning or daily standups.
Estimate Realistically: Include time for testing, code review, documentation, and debugging in task hour estimates.
Use Story Points Consistently: Apply Fibonacci sequence values to User Stories based on relative complexity, not absolute time.
Progressive Disclosure: Create Features first, then User Stories, then Tasks. This allows for iterative refinement of scope and estimation.
Validate Before Creating: Review the work item hierarchy and ensure all required fields are populated before calling MCP tools to create items.
Common Patterns
Pattern: Creating a Complete Feature with Stories and Tasks
When asked to create a new feature with full breakdown:
Create the Feature with high-level description
Create User Stories as children of the Feature with proper descriptions and acceptance criteria
Create Tasks as children of each User Story with hour estimates
Review the hierarchy to ensure proper parent-child relationships
Confirm total estimated hours across all tasks align with story points
Pattern: Adding Tasks to Existing User Story
When asked to add tasks to an existing story:
Fetch the User Story to understand context
Review existing tasks to avoid duplication
Create new Tasks with appropriate titles and hour estimates
Link Tasks to the User Story as parent
Pattern: Breaking Down a Large User Story
When a User Story is too large (Story Points 13+):
Review the original User Story description and acceptance criteria
Identify natural breakpoints in functionality
Create multiple smaller User Stories under the same Feature
Distribute acceptance criteria across the new stories
Update or close the original story as appropriate
Create Tasks for each new User Story
Example Work Item Hierarchy
Feature: 1: User Authentication System
Description: <p>Implement complete user authentication...</p>
User Story: 1.1: User Registration
Description: <p><strong>As a</strong> website visitor...</p>
Acceptance Criteria: <p><strong>Scenario 1...</strong></p>
Story Points: 5
Task: Implement registration API endpoint
Original Estimate: 4
Remaining Work: 4
Task: Create registration form UI
Original Estimate: 3
Remaining Work: 3
Task: Write unit tests for registration
Original Estimate: 2
Remaining Work: 2
User Story: 1.2: User Login
Description: <p><strong>As a</strong> registered user...</p>
Acceptance Criteria: <p><strong>Scenario 1...</strong></p>
Story Points: 3
Task: Implement login API endpoint
Original Estimate: 3
Remaining Work: 3
Task: Create login form UI
Original Estimate: 2
Remaining Work: 2
Troubleshooting
Problem: Work items not appearing in the correct order in backlog
Solution: Ensure Features are numbered 1-99, and User Stories follow the configured naming convention (decimal notation or descriptive names).
Problem: Acceptance criteria rendering incorrectly in Azure DevOps
Solution: Verify all text fields use proper HTML formatting with <p>, <ul>, <li> tags.
Problem: Tasks showing as orphaned in queries
Solution: Verify each Task has a parent User Story link set correctly when created.
Problem: Story Points not summing correctly at Feature level
Solution: Ensure Story Points are only set on User Stories, not on Features or Tasks.
