003 Name Skill 5da5923c

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

```markdown
> [!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):

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

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

</details>
```

### References Section (Required on Most Artifacts)

```markdown
---

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