003 Name Skill 87183b1c

---
name: azure-artifacts
description: Defines canonical artifact templates, H2 structures, and documentation styling rules for agent outputs (Steps 1-7); use for artifact generation, formatting, and template compliance.
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

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

| Rule                  | Requirement                                                    |
| --------------------- | -------------------------------------------------------------- |
| **Template skeleton** | Read `.template.md` file and replicate its structure           |
| **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

---

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

| Responsibility                                              | Agent                        |
| ----------------------------------------------------------- | ---------------------------- |
| **Create** initial README from `PROJECT-README.template.md` | Requirements (Step 1)        |
| **Update** workflow progress after saving step artifacts    | Every step agent (Steps 2-7) |

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

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

```markdown
<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:**

| Artifact Type          | Label                       |
| ---------------------- | --------------------------- |
| 01-requirements        | 📑 Requirements Overview    |
| 02-architecture        | 📑 Assessment Contents      |
| 03-des-cost-estimate   | 📑 Cost Estimate Contents   |
| 04-implementation-plan | 📑 Implementation Contents  |
| 04-governance          | 📑 Governance Contents      |
| 04-preflight-check     | 📑 Pre-Flight Contents      |
| 05-implementation-ref  | 📑 Implementation Reference |
| 06-deployment          | 📑 Deployment Contents      |
| 07-documentation-index | 📑 Documentation Contents   |
| 07-design-document     | 📑 Design Contents          |
| 07-operations-runbook  | 📑 Runbook Contents         |
| 07-resource-inventory  | 📑 Inventory Contents       |
| 07-backup-dr-plan      | 📑 DR Plan Contents         |
| 07-compliance-matrix   | 📑 Compliance Contents      |
| 07-ab-cost-estimate    | 📑 As-Built Cost Contents   |

### Attribution Header

Appears immediately after the TOC:

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

### Cross-Navigation

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

**Header** (after attribution):

```markdown
| ⬅️ 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:

```markdown
---

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

```markdown
<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)

```text
## 🎯 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)

```text
## ✅ 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)

```text
## 💵 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)

```text
## 🔍 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)

```text
## 📋 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)

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

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

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

### 06-deployment-summary.md (Deploy Agent)

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

### 07-documentation-index.md

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

### 07-design-document.md

```text
## 📝 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

```text
## ⚡ 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

```text
## 📊 Summary
## 📦 Resource Listing
## References
```

### 07-ab-cost-estimate.md

```text
## 💵 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

```text
## 📋 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

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

### PROJECT-README.md

```text
## 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/`                                        |

---

## Automated Validation

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

| Script                            | Scope                                                                                                                           | npm Command                       |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `validate-artifact-templates.mjs` | All 16 artifact types — H2 order, required headings, strictness, and required diagram/chart artifact checks (non-Mermaid-first) | `npm run lint:artifact-templates` |

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