azure-artifacts

name	azure-artifacts
description	Template H2 structures, documentation styling standards, and generation rules for all agent output artifacts (Steps 1-7). Defines exact H2 headings for 16 artifact types, callout styles, emoji conventions, collapsible sections, and compliance rules. **Triggers**: "generate artifact", "template structure", "H2 headings", "documentation styling", "create workload docs", "document the deployment", "generate documentation", "operations runbook", "resource inventory", "design document", "compliance matrix", "backup plan", "cost estimate", "documentation index", "deployment summary"
compatibility	Works with Claude Code, GitHub Copilot, VS Code, and any Agent Skills compatible tool.
license	MIT
metadata	{"author":"jonathan-vella","version":"1.0","category":"workflow-automation"}

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

Mandatory Compliance

Rule	Requirement
Exact text	Use H2 text from this skill verbatim
Exact order	Required H2s appear in the order listed below
Anchor rule	Extra sections allowed ONLY after last required H2
No omissions	Every H2 listed must appear in output
Attribution	Include header: > Generated by {agent} agent | {YYYY-MM-DD}

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

---

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
## Dependency Graph
## 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)

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

Trigger	Action
After Step 6 (Deploy)	Generate full documentation package
"Generate workload documentation"	Create all 7 document types
"Document the deployment"	Synthesize from deployment artifacts
"Create operations runbook"	Generate specific document
Conductor handoff	Auto-generate post-deployment docs

Output Files (Step 7)

File	Purpose	Required
07-documentation-index.md	Master index linking all docs	Yes
07-design-document.md	10-section technical design	Yes
07-operations-runbook.md	Day-2 operational procedures	Yes
07-resource-inventory.md	Complete resource listing	Yes
07-ab-cost-estimate.md	As-built cost analysis	Yes
07-compliance-matrix.md	Security control mapping	Optional
07-backup-dr-plan.md	Disaster recovery procedures	Optional

Source Artifacts for Step 7

Source	Information Extracted
01-requirements.md	Business context, NFRs, compliance
02-architecture-assessment.md	WAF scores, SKU recommendations
04-implementation-plan.md	Resource inventory, dependencies
06-deployment-summary.md	Deployed resources, outputs
infra/bicep/{project}/	Actual Bicep configuration values

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

Purpose	Emoji	Example
Success/Complete	✅	✅ Health check passed
Warning/Attention	⚠️	⚠️ Requires manual config
Error/Critical	❌	❌ Validation failed
Info/Tip	💡	💡 Consider Premium tier
Security	🔐	🔐 Requires Key Vault
Cost	💰	💰 Estimated: $50/month
Reference	📚	📚 See: Microsoft Learn
Time	⏰	⏰ Runs daily at 02:00 UTC
Pending	⏳	⏳ Awaiting approval

Category Icons

Category	Icon	Usage
Compute	💻	### 💻 Compute Resources
Data	💾	### 💾 Data Services
Networking	🌐	### 🌐 Networking Resources
Messaging	📨	### 📨 Messaging Resources
Security	🔐	### 🔐 Security Resources
Monitoring	📊	### 📊 Monitoring Resources
Identity	👤	### 👤 Identity & Access
Storage	📦	### 📦 Storage Resources

WAF Pillar Icons

Pillar	Icon
Security	🔒
Reliability	🔄
Performance	⚡
Cost	💰
Operations	🔧

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

Topic	URL
WAF Overview	https://learn.microsoft.com/azure/well-architected/
Security Checklist	https://learn.microsoft.com/azure/well-architected/security/checklist
Reliability Checklist	https://learn.microsoft.com/azure/well-architected/reliability/checklist
Cost Optimization	https://learn.microsoft.com/azure/well-architected/cost-optimization/checklist
Azure Backup	https://learn.microsoft.com/azure/backup/backup-best-practices
Azure Monitor	https://learn.microsoft.com/azure/azure-monitor/overview
Managed Identities	https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview
Key Vault Practices	https://learn.microsoft.com/azure/key-vault/general/best-practices
Azure Pricing Calculator	https://azure.microsoft.com/pricing/calculator/

---

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