--- name: azure-artifacts description: '**UTILITY SKILL** — Artifact template structures, H2 compliance rules, and documentation styling for agent outputs (Steps 1-7). WHEN: "generate artifact", "check H2 structure", "artifact template", "step 7 as-built". USE FOR: generating any agent artifact, checking H2 structure compliance. DO NOT USE FOR: Azure resource configuration (use azure-defaults), Bicep/Terraform patterns (use azure-bicep-patterns or terraform-patterns).' 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 artifact template structures and styling. Per-step H2 definitions live in `references/` — load only the step you are generating. ## Rules ### Mandatory Compliance | Rule | Requirement | | --------------------- | --------------------------------------------------- | | **Template skeleton** | Read step template from `references/` and replicate | | **Exact text** | Use H2 text from templates 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** | `> Generated by {agent} agent \| {YYYY-MM-DD}` | ### DO / DON'T - **DO**: Read the step-specific template before generating - **DO**: Copy H2 text character-for-character (including emoji) - **DO**: Save all output to `agent-output/{project}/` - **DON'T**: Reorder H2 headings from the listed sequence - **DON'T**: Use placeholder text like "TBD" or "Insert here" - **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`. After saving step artifact(s), update the README: 1. Mark your step as **complete** in `## ✅ Workflow Progress` 2. Add artifact files to `## 📄 Generated Artifacts` 3. Update `Last Updated` date and progress bar percentage ## Steps Artifact generation flow (per Step N): 1. **Read template** — load the matching `references/0N-*-template.md` for the step you are generating 2. **Copy H2 skeleton** — replicate every required H2 in the listed order, character-for-character 3. **Fill content** — replace `{placeholder}` tokens; never use "TBD" or "Insert here" 4. **Add attribution** — `> Generated by {agent} agent | {YYYY-MM-DD}` 5. **Save** to `agent-output/{project}/` with the prescribed filename 6. **Update README** — mark step complete, list artifacts, refresh `Last Updated` date 7. **Delegate validation** — do **not** invoke `npm run lint:artifact-templates`, `npm run lint:h2-sync`, or `markdownlint-cli2` directly against `agent-output/**`. The lefthook `artifact-validation` pre-commit hook (which wraps these scripts) and the `10-Challenger` review own the artifact contract. See [`agent-authoring.instructions.md`](../../instructions/agent-authoring.instructions.md#no-direct-markdownlint-on-agent-output-rule). For revisions (challenger findings, user-decision Apply/Skip/Defer, approval-gate fixes), see [`references/revision-workflow.md`](./references/revision-workflow.md) — bundle all fixes into a single `multi_replace_string_in_file` call. ## Post-write validation Run a one-line shape check **immediately after writing any non-markdown artifact**, before moving to the next step. Catches malformed output at source instead of at deploy time. Markdown artifacts are owned by the lefthook `artifact-validation` hook — do not duplicate that check here. | Artifact type | Validation command (run after write) | | ------------------------------------------ | ------------------------------------------------------------------- | | `*.json` | `python -m json.tool >/dev/null` | | `*.bicep` | `bicep build --stdout >/dev/null` | | `*.tf` | `terraform fmt -check ` + `terraform validate` (in module dir) | | `challenge-findings-*.json` (sidecar JSON) | `node tools/scripts/validate-challenger-findings.mjs ` | | `challenge-findings-*-decisions.json` (per-finding sidecar) | `node tools/scripts/validate-challenge-findings-decisions.mjs ` | | `*.md` | _delegated to lefthook `artifact-validation` — do not run inline_ | Fail closed: if the validator exits non-zero, fix the artifact and re-validate before continuing. Do **not** record the artifact in the project README or hand off to the next step until it passes. ## Placeholder Syntax All templates use single-brace `{placeholder-name}` syntax: - Lowercase, hyphen-separated: `{project-name}`, `{monthly-cost}` - No Mustache/Handlebars `{{double-braces}}` ## Automated Validation These npm scripts are invoked by the lefthook `artifact-validation` pre-commit hook and by CI — **not by agents directly** (see [`agent-authoring.instructions.md`](../../instructions/agent-authoring.instructions.md#no-direct-markdownlint-on-agent-output-rule)). ```bash npm run lint:artifact-templates # H2 order and required headings (pre-commit + CI only) npm run lint:h2-sync # Template ↔ artifact sync (pre-commit + CI only) npm run validate:all # All validators together (humans / CI only) ``` ### Fast H2-order sanity check (agent-safe) When an agent needs a quick "did I get the H2 structure right?" check *before* invoking the challenger, use the dedicated helper instead of improvising `node -e '…'` one-liners (which trip shell quoting and waste context on retries): ```bash npm run check:h2-order -- # defaults to 01-requirements.md npm run check:h2-order -- 04-implementation-plan.md node tools/scripts/check-h2-order.mjs agent-output//02-architecture-assessment.md ``` Exit 0 = match (prints `OK: …`). Exit 1 = mismatch (prints structured JSON with `expected`/`got`/`missingAt`). Exit 2 = bad arguments or unknown artifact filename. The helper reads the canonical heading registry from [`tools/scripts/_lib/artifact-headings.mjs`](../../../tools/scripts/_lib/artifact-headings.mjs) so it never drifts from the template source of truth. ## Quality Checklist Critical (always check): - [ ] H2 headings match template exactly (text + order) - [ ] Attribution header present with agent name and date - [ ] No placeholder text (e.g. "TBD", "Insert here", task markers) - [ ] File saved to `agent-output/{project}/` with correct name For the full structural / styling checklist (TOC, cross-nav table, traffic lights, Mermaid, collapsible blocks) read [`references/styling-standards.md`](references/styling-standards.md). ## Reference Index When generating a Step N artifact, read the corresponding template: | Reference | When to Load | | ---------------------------------------- | ---------------------------------------------------- | | `references/01-requirements-template.md` | Generating Step 1 requirements | | `references/02-architecture-template.md` | Generating Step 2 assessment or Step 3 cost estimate | | `references/04-plan-template.md` | Generating Step 4 plan, governance, or preflight | | `references/05-code-template.md` | Generating Step 5 implementation reference | | `references/06-deploy-template.md` | Generating Step 6 deployment summary | | `references/07-docs-template.md` | Generating Step 7 workload documentation | | `references/styling-standards.md` | Applying callouts, badges, emoji, navigation | | `references/cost-estimate-sections.md` | Cost estimate H2 structure and formatting rules | | `references/revision-workflow.md` | Detailed targeted-edit revision procedure (Step 7+) |