Content
65%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
A dense, largely executable reference with good code coverage, held back by missing verification/recovery steps in the deployment workflow and by a broken progressive-disclosure structure that cites three reference files absent from the bundle. Undefined hook variables also weaken copy-paste reliability.
Suggestions
Add explicit post-deploy validation and recovery steps (e.g., check azd up output / az containerapp logs, verify service URIs respond, and re-apply custom domains after redeploy) so the destructive-redeploy risk is actually handled rather than just flagged.
Create the referenced files (references/bicep-patterns.md, references/troubleshooting.md, references/azure-yaml-schema.md) or remove the dead "Reference Files" links, and move the full azure.yaml options table and Bicep module patterns into them to slim the body.
Define how the hook variables ($FRONTEND_NAME, $RG, $OPENAI_RESOURCE_ID, $SEARCH_RESOURCE_ID) get populated — e.g., add corresponding Bicep outputs and azd env set examples — so the hook scripts run as written.
Replace the filler "When to Use" section with concrete applicability guidance (when to use azd vs. manual Bicep/portal deployment).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and code-first — azure.yaml configs, Bicep snippets, command tables, and hook scripts earn their tokens, with almost no conceptual padding. Two spots could be trimmed ("Bicep is declarative - Resources reconcile to desired state" explains something Claude knows, and the closing "When to Use" section — "This skill is applicable to execute the workflow or actions described in the overview" — is pure filler), which matches the 4 anchor (efficient, minor over-explanation) rather than the lean 5 anchor. | 4 / 5 |
Actionability | Mostly executable guidance: the Quick Start commands, azd env commands, role-assignment hook, and azure.yaml examples are copy-paste ready. It falls short of 5 because several hook scripts depend on variables that are never defined or populated ("$FRONTEND_NAME", "$RG", "$OPENAI_RESOURCE_ID", "$SEARCH_RESOURCE_ID" appear in hooks without any preceding azd env set or Bicep output for them), and a couple of Bicep fragments (the customDomains ternary, the env array) lack surrounding context. | 4 / 5 |
Workflow Clarity | A rough sequence exists (auth login → init → env new → up) plus a debugging command section, but there are no validation checkpoints or feedback loops: nothing verifies a deploy succeeded before proceeding, and no recovery guidance for the failure modes the skill itself flags — notably that redeployment can destroy Portal-added custom domains, a destructive risk the preserve/restore hook only half-addresses (it saves domains to /tmp but the restore branch just echoes the file). Per the guideline on destructive/batch operations without validation, workflow clarity is capped at 3. | 3 / 5 |
Progressive Disclosure | The body has clear section headers and a dedicated "Reference Files" section clearly signaling one-level-deep references, but the referenced files (references/bicep-patterns.md, references/troubleshooting.md, references/azure-yaml-schema.md) do not exist in the bundle — no references/ directory is present at all. Because the promised split targets are missing, the full azure.yaml schema and Bicep patterns remain inlined in a ~295-line body, which is the organization gap the 3 anchor describes; it is not a 2 because structure and reference signaling are present and clearly labeled rather than buried or headerless. | 3 / 5 |
Total | 14 / 20 Passed |