003 Name Skill B489b52d

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

### 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 for visual scanning:

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

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)`)
when generating final artifacts.

### Collapsible Table of Contents

Include in every artifact after the badge row:

```markdown
<details>
<summary><strong>📑 Table of Contents</strong></summary>

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

</details>
```

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

```markdown
---

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

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