Azure Artifacts

Azure Artifacts Skill

Single source of truth for all artifact template structures and documentation styling. Replaces individual template file lookups with embedded H2 definitions.

Artifact Generation Rules

[!NOTE] This skill is the SINGLE SOURCE OF TRUTH for artifact H2 headings and templates. The similar section in azure-defaults/SKILL.md defers to this skill for template compliance.

Mandatory Compliance

DO / DON'T

• DO: Read this skill BEFORE generating any artifact
• DO: Copy H2 text character-for-character (including emoji prefixes)
• DO: Include ## References section at bottom when listed
• DO: Use callout styles from the Styling section below
• DO: Save all output to agent-output/{project}/
• DON'T: Generate artifacts without checking H2 structure first
• DON'T: Reorder H2 headings from the listed sequence
• DON'T: Use placeholder text like "TBD" or "Insert here"
• DON'T: Skip sections — empty sections are better than missing ones
• DON'T: Add custom H2 sections BEFORE the last required H2

Mandatory: Project README

Every project in agent-output/{project}/ MUST have a README.md. This is a cross-agent requirement — not owned by a single step.

README Update Rules (All Agents)

After saving your step artifact(s), update agent-output/{project}/README.md:

1. Mark your step as complete in the ## ✅ Workflow Progress table
2. Add your artifact files to the ## 📄 Generated Artifacts section
3. Update the Last Updated date in ## 📋 Project Summary
4. Update the progress bar percentage (each of the 7 steps = ~14%)
5. If README doesn't exist (e.g., resuming a mid-workflow project), create it from PROJECT-README.template.md and backfill completed steps

Template: .github/skills/azure-artifacts/templates/PROJECT-README.template.md

Standard Components

Reusable building blocks that templates embed. Agents copy these patterns verbatim, replacing only {placeholder} values.

Badge Row

Every artifact opens with a badge row immediately after the title. Use Shields.io static badges with ?style=for-the-badge for visual scanning:

![Step](https://img.shields.io/badge/Step-{n}-blue?style=for-the-badge)
![Status](https://img.shields.io/badge/Status-{Draft|Complete}-{orange|brightgreen}?style=for-the-badge)
![Agent](https://img.shields.io/badge/Agent-{agent--name}-purple?style=for-the-badge)

Badge values use -- for hyphens (Shields.io escaping). The Status badge is Draft|orange on first generation and Complete|brightgreen after review. Agents may optionally add a fourth Date badge (![Date](https://img.shields.io/badge/Generated-{YYYY--MM--DD}-grey?style=for-the-badge)) when generating final artifacts.

Collapsible Table of Contents

Include in every artifact after the badge row using <details open> so the TOC is expanded by default. Use a contextual label that matches the artifact type (not a generic "Table of Contents"):

<details open>
<summary><strong>📑 {Contextual Label}</strong></summary>

- Section Name (#section-name)
- Section Name (#section-name)
<!-- auto-generate from H2 headings -->

</details>

Contextual label examples:

Attribution Header

Appears immediately after the TOC:

> Generated by {agent} agent | {YYYY-MM-DD}

Cross-Navigation

Every artifact includes header and footer navigation links to adjacent workflow steps:

Header (after attribution):

| ⬅️ Previous     | 📑 Index  | Next ➡️         |
| --------------- | --------- | --------------- |
| {prev-filename} | README.md | {next-filename} |

Footer (before References or at document end):

Wrap the footer navigation in a centered <div> for consistent alignment:

---

<div align="center">

| ⬅️ {prev-step-name} ({prev-filename}) | 🏠 Project Index (README.md) | ➡️ {next-step-name} ({next-filename}) |
| ------------------------------------- | ---------------------------- | ------------------------------------- |

</div>

For the first artifact (01), omit the Previous link. For the last artifact (07), omit the Next link.

Placeholder Syntax

All templates use single-brace {placeholder-name} syntax:

• Lowercase, hyphen-separated: {project-name}, {monthly-cost}
• No Mustache/Handlebars {{double-braces}}
• No conditional blocks — use HTML comments for optional sections: <!-- If {condition} -->...<!-- End {condition} -->

Collapsible Detail Blocks

Use for content exceeding 10 table rows, lengthy code, or reference material:

<details>
<summary>📋 {Section Title}</summary>

| Column | Column |
| ------ | ------ |
| ...    | ...    |

</details>

Always include a blank line after <summary> and before </details>.

Template H2 Structures

01-requirements.md (Requirements Agent)

## 🎯 Project Overview
## 🚀 Functional Requirements
## ⚡ Non-Functional Requirements (NFRs)
## 🔒 Compliance & Security Requirements
## 💰 Budget
## 🔧 Operational Requirements
## 🌍 Regional Preferences
## 📋 Summary for Architecture Assessment
## References

02-architecture-assessment.md (Architect Agent)

## ✅ Requirements Validation
## 💎 Executive Summary
## 🏛️ WAF Pillar Assessment
## 📦 Resource SKU Recommendations
## 🎯 Architecture Decision Summary
## 🚀 Implementation Handoff
## 🔒 Approval Gate
## References

03-des-cost-estimate.md (Architect Agent)

## 💵 Cost At-a-Glance
## ✅ Decision Summary
## 🔁 Requirements → Cost Mapping
## 📊 Top 5 Cost Drivers
## 🏛️ Architecture Overview
## 🧾 What We Are Not Paying For (Yet)
## ⚠️ Cost Risk Indicators
## 🎯 Quick Decision Matrix
## 💰 Savings Opportunities
## 🧾 Detailed Cost Breakdown
## References

04-governance-constraints.md (Bicep Plan Agent)

## 🔍 Discovery Source
## 📋 Azure Policy Compliance
## 🔄 Plan Adaptations Based on Policies
## 🚫 Deployment Blockers
## 🏷️ Required Tags
## 🔐 Security Policies
## 💰 Cost Policies
## 🌐 Network Policies
## References

04-implementation-plan.md (Bicep Plan Agent)

## 📋 Overview
## 📦 Resource Inventory
## 🗂️ Module Structure
## 🔨 Implementation Tasks
## 🚀 Deployment Phases
## 🔗 Dependency Graph
## 🔄 Runtime Flow Diagram
## 🏷️ Naming Conventions
## 🔐 Security Configuration
## ⏱️ Estimated Implementation Time
## 🔒 Approval Gate
## References

04-preflight-check.md (Bicep Code Agent)

## 🎯 Purpose
## ✅ AVM Schema Validation Results
## 🔎 Parameter Type Analysis
## 🌍 Region Limitations Identified
## ⚠️ Pitfalls Checklist
## 🚀 Ready for Implementation

05-implementation-reference.md (Bicep Code Agent)

## 📁 IaC Templates Location
## 🗂️ File Structure
## ✅ Validation Status
## 🏗️ Resources Created
## 🚀 Deployment Instructions
## 📝 Key Implementation Notes

06-deployment-summary.md (Deploy Agent)

## ✅ Preflight Validation
## 📋 Deployment Details
## 🏗️ Deployed Resources
## 📤 Outputs (Expected)
## 🚀 To Actually Deploy
## 📝 Post-Deployment Tasks
## References

07-documentation-index.md

## 📦 1. Document Package Contents
## 📚 2. Source Artifacts
## 📋 3. Project Summary
## 🔗 4. Related Resources
## ⚡ 5. Quick Links

07-design-document.md

## 📝 1. Introduction
## 🏛️ 2. Azure Architecture Overview
## 🌐 3. Networking
## 💾 4. Storage
## 💻 5. Compute
## 👤 6. Identity & Access
## 🔐 7. Security & Compliance
## 🔄 8. Backup & Disaster Recovery
## 📊 9. Management & Monitoring
## 📎 10. Appendix
## References

07-operations-runbook.md

## ⚡ Quick Reference
## 📋 1. Daily Operations
## 🚨 2. Incident Response
## 🔧 3. Common Procedures
## 🕐 4. Maintenance Windows
## 📞 5. Contacts & Escalation
## 📝 6. Change Log
## References

07-resource-inventory.md

## 📊 Summary
## 📦 Resource Listing
## References

07-ab-cost-estimate.md

## 💵 Cost At-a-Glance
## ✅ Decision Summary
## 🔁 Requirements → Cost Mapping
## 📊 Top 5 Cost Drivers
## 🏛️ Architecture Overview
## 🧾 What We Are Not Paying For (Yet)
## ⚠️ Cost Risk Indicators
## 🎯 Quick Decision Matrix
## 💰 Savings Opportunities
## 🧾 Detailed Cost Breakdown
## References

07-backup-dr-plan.md

## 📋 Executive Summary
## 🎯 1. Recovery Objectives
## 💾 2. Backup Strategy
## 🌍 3. Disaster Recovery Procedures
## 🧪 4. Testing Schedule
## 📢 5. Communication Plan
## 👥 6. Roles and Responsibilities
## 🔗 7. Dependencies
## 📖 8. Recovery Runbooks
## 📎 9. Appendix
## References

07-compliance-matrix.md

## 📋 Executive Summary
## 🗺️ 1. Control Mapping
## 🔍 2. Gap Analysis
## 📁 3. Evidence Collection
## 📝 4. Audit Trail
## 🔧 5. Remediation Tracker
## 📎 6. Appendix
## References

PROJECT-README.md

## Template Instructions
## Required Structure
## 📋 Project Summary
## ✅ Workflow Progress
## 🏛️ Architecture
## 📄 Generated Artifacts
## 🔗 Related Resources

Step 7: Workload Documentation Generation

When to Generate

Output Files (Step 7)

Source Artifacts for Step 7

Generation Workflow

1. Gather Context — Read project artifacts (01-06) and Bicep templates
2. Check H2 Structures — Reference the template sections above
3. Extract Resources — Parse deployed resources from 06-deployment-summary.md
4. Query Pricing — Use Azure Pricing MCP for cost estimates (if available)
5. Generate Documents — Create each document following H2 structure exactly
6. Cross-Reference — Ensure consistency across all documents
7. Create Index — Generate 07-documentation-index.md linking all documents

Step 7 DO / DON'T

• DO: Read ALL source artifacts before generating
• DO: Use actual SKU names and config from Bicep, not placeholders
• DO: Include specific Azure CLI/PowerShell commands in runbooks
• DO: Map compliance controls to actual resource configurations
• DO: Calculate costs from deployed SKUs, not estimates
• DON'T: Generate docs without reading source artifacts
• DON'T: Create generic runbooks without project-specific commands
• DON'T: Skip required documents (index, design, runbook, inventory, cost)
• DON'T: Generate cost estimates without checking actual SKUs

What This Skill Does NOT Do

• Generate Bicep or Terraform code (use bicep-code agent)
• Create architecture diagrams (use azure-diagrams skill)
• Deploy resources (use deploy agent)
• Create ADRs (use azure-adr skill)
• Perform WAF assessments (use architect agent)

Documentation Styling Standards

Callout Styles

> [!NOTE]
> Informational — background context, tips, FYI

> [!TIP]
> Best practice recommendation or optimization

> [!IMPORTANT]
> Critical configuration that must not be overlooked

> [!WARNING]
> Security concern, reliability risk, potential issue

> [!CAUTION]
> Data loss risk, breaking change, irreversible action

Status Emoji

Category Icons

WAF Pillar Icons

Collapsible Sections

Use for lengthy content (>10 rows, reference material, code examples):

<details>
<summary>📋 Detailed Configuration</summary>

| Setting | Value |
| ------- | ----- |
| ...     | ...   |

</details>

References Section (Required on Most Artifacts)

---

## References

> [!NOTE]
> 📚 The following Microsoft Learn resources provide additional guidance.

| Topic      | Link                                            |
| ---------- | ----------------------------------------------- |
| Topic Name | [Display Text](https://learn.microsoft.com/...) |

Common Reference Links

Automated Validation

Templates and generated artifacts are validated by the unified validator in scripts/:

Run npm run validate:all to execute all validators together.

Quality Checklist

Before finalizing any artifact:

• H2 headings match this skill's template exactly (text + order)
• Attribution header present with agent name and date
• No placeholder text ("TBD", "Insert here", "TODO")
• Callout styles used for emphasis (not bold text alone)
• Status emoji consistent with the table above
• References section included (when template specifies it)
• Collapsible sections used for tables >10 rows
• File saved to agent-output/{project}/ with correct filename