context-engineering: Skill for Claude Code

Azure IaC: Bicep + ARM

Production-grade Azure infrastructure as code. Bicep is the default authoring language; ARM JSON is the compile target and the fallback for tooling that has not adopted Bicep. Decompile legacy ARM to Bicep, never hand-author new ARM JSON.

When to load reference files

This file is the index. Load the deeper material only when the task needs it:

You are...	Read
Authoring a module, picking a scope, choosing decorators, wiring outputs	references/module-patterns.md
Migrating ARM JSON to Bicep, or deciding Bicep vs ARM vs Terraform	references/arm-vs-bicep.md
Running lint / what-if / deploy / deployment stacks, or building a CI pipeline	references/deploy-runbook.md

Documentation-first mandate

Resource API shapes drift. Before emitting any resource declaration, confirm the type, apiVersion, and required properties against the live schema rather than memory:

• Call the mcp__azure__bicepschema tool for the exact resource type (for example Microsoft.Storage/storageAccounts) to get current apiVersion and property names.
• For Terraform-adjacent questions, call mcp__azure__azureterraformbestpractices.
• For broader service guidance, call mcp__azure__get_azure_bestpractices and mcp__ms-learn__microsoft_docs_search.

If those tools are unavailable, state plainly that you are reasoning from training knowledge and flag that the user must validate the apiVersion against the current provider schema. Never invent an apiVersion or a property name. A template that fails at deploy time on a bad property is a sprint blocker.

Non-negotiable authoring rules

1. No secrets in templates or parameter files. Reference Key Vault with the getSecret() function from a .bicepparam file or a Microsoft.KeyVault/vaults existing reference. Never a literal password, key, or connection string. Mark sensitive parameters @secure().
2. Identity over keys. Default to system-assigned managed identity and RBAC role assignments. Reach for shared keys or SAS only when a service genuinely lacks managed-identity support, and say so.
3. Parameterize environment, not structure. Parameters carry what changes per environment (name prefixes, SKUs, region, scale). The resource graph stays declarative and identical across environments.
4. Idempotent by construction. Bicep deployments are incremental and re-runnable. Use deterministic names (uniqueString(resourceGroup().id) patterns) so re-runs converge rather than duplicate.
5. Every parameter is decorated. @description() on every parameter and output. @allowed(), @minLength(), @maxLength(), @minValue(), @maxValue() wherever a constraint exists.
6. Comments justify design, not syntax. Explain why a SKU, a scope, or a dependency exists. The Bicep already shows what.
7. Modules for reuse, not for everything. Extract a module when a unit is reused or independently testable. Do not shred a single-purpose template into ceremony.