| 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:
- Mark your step as complete in the
## ✅ Workflow Progress table
- Add your artifact files to the
## 📄 Generated Artifacts section
- Update the
Last Updated date in ## 📋 Project Summary
- Update the progress bar percentage (each of the 7 steps = ~14%)
- 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:
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
()
when generating final artifacts.
Collapsible Table of Contents
Include in every artifact after the badge row:
<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:
> 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):
---
| ⬅️ {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:
<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)
## 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
- Gather Context — Read project artifacts (01-06) and Bicep templates
- Check H2 Structures — Reference the template sections above
- Extract Resources — Parse deployed resources from
06-deployment-summary.md
- Query Pricing — Use Azure Pricing MCP for cost estimates (if available)
- Generate Documents — Create each document following H2 structure exactly
- Cross-Reference — Ensure consistency across all documents
- 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/ |
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:
