| 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":"2.0","category":"workflow-automation"} |
Azure Artifacts Skill
Single source of truth for all artifact template structures and documentation styling.
Load this SKILL.md first — then load references/ files on demand for the current task.
Reference Files (Load on Demand)
| File | When to Load |
|---|
references/h2-templates.md | Generating a specific artifact — get exact H2 heading sequence |
references/standard-components.md | Building artifact structure (badges, TOC, navigation, placeholders) |
references/styling-standards.md | Formatting content (callouts, emoji, icons, reference links) |
Templates directory: templates/ contains .template.md skeleton files.
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 references/h2-templates.md verbatim |
| Exact order | Required H2s appear in the order listed |
| 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
references/h2-templates.md 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
references/styling-standards.md
- 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, create from
PROJECT-README.template.md and backfill
Template: .github/skills/azure-artifacts/templates/PROJECT-README.template.md
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 — Read
references/h2-templates.md for the target artifact
- 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
- 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)
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)
Automated Validation
| Script | Scope | npm Command |
|---|
validate-artifact-templates.mjs | All 16 artifact types — H2 order, required H2s | npm run lint:artifact-templates |
Run npm run validate:all to execute all validators together.
Quality Checklist
Before finalizing any artifact:
