bicep-best-practices

Reviews and refactors Azure Bicep modules for minimal parameters, stable resource IDs, and safe deployments.

Updated Aug 2, 2026
One-click install
npx skills add https://github.com/leonardoacosta/skills --skill bicep-best-practices-leonardoacosta
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bicep-best-practices
Source: https://github.com/leonardoacosta/skills/tree/main/azure-kit/skills/bicep-best-practices
Command: npx skills add https://github.com/leonardoacosta/skills --skill bicep-best-practices-leonardoacosta

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Bicep templates often accumulate redundant parameters, scattered environment configuration, broken tag unions, and role-assignment names that fail with BCP120 because they depend on deployment-time module outputs. This Skill applies a consistent set of Azure Bicep practices when authoring or reviewing modules so interfaces stay small, resource references stay derivable, and every change is proven with compiler and what-if evidence. ## Core Features & Use Cases - Parameter and configuration hygiene: Minimizes parameter surfaces, centralizes shared environment facts in one typed configuration object, and derives stable names instead of threading values through module layers. - Resource reference correctness: Derives ARM resource IDs with existing symbolic resources or correctly scoped resourceId(), preserves resource-specific tags with union(), and keeps guid() naming inputs compile-time resolvable to avoid BCP120. - Validation gates: Treats the Bicep linter, az bicep build, and scoped deployment what-if previews as required review evidence, including zero unexplained drift for refactors. - Use Case: A reviewer finds a role assignment named with guid(module.outputs.principalId, ...) triggering BCP120; the Skill guides moving the naming expression to a boundary where principalId is a compile-time parameter. ## Quick Start Review my Bicep module for redundant parameters, tag handling, and role-assignment naming, then tell me what build and what-if validation I still need before merging.

Frequently Asked Questions about bicep-best-practices

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix Bicep error BCP120 on role assignment names?

BCP120 occurs when a resource name uses deployment-time values like module outputs. Move the naming expression to a boundary where the value, such as principalId, is passed in as a parameter, keeping all guid() inputs compile-time resolvable.

How do I reduce parameters in a Bicep module?

Inspect every caller and keep a parameter only when callers legitimately supply different values. Derive predictable names from small identities like workload and environment, and read shared environment facts from one typed configuration object instead of forwarding parameters through layers.

Should I use existing resources or resourceId() in Bicep?

Prefer an existing symbolic resource when Bicep can express the owning scope clearly. Use resourceId() when a cross-resource-group or cross-subscription ID is easier and unambiguous to derive, and always pass the ARM resource ID rather than a service-specific customer identifier.

Is a successful az bicep build enough before merging?

No. A successful build proves syntax and type validity but not safe deployment behavior. Also review linter diagnostics and run a scoped deployment what-if at the real target, requiring zero unexplained property drift for behavior-neutral refactors.

Why did my Bicep refactor drop resource-specific tags?

Tag loss happens when union(sharedTags, {...}) is replaced with the base tag object during parameter cleanup. Preserve both sets with union() and change only the source of the shared tags, since the added keys are deployment data.