Content
71%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 well-structured, highly actionable skill with an exemplary progressive-disclosure bundle (one reference + two assets, all real, relevant, and linked at point of use). The main weaknesses are redundancy — the same requirements are restated across four checklist-style sections — and a soft 'test syntax mentally' validation step where an explicit validate-and-fix loop would be stronger.
Suggestions
Collapse 'Core Responsibilities', 'Quality Standards', 'Always Do / Never Do', and 'Success Criteria' into a single requirements section — they restate the same guidance three to four times and account for most of the excess length.
Replace 'Ensure Mermaid syntax is valid (test syntax mentally before output)' with an explicit validation step, e.g. re-render or lint the diagram and fix/re-check on failure, to create a real feedback loop in Step 3→4.
Name the exact Azure MCP tool invocations in the Tool Usage Patterns section (as azure-resource-graph.md already does for `az graph query`) so the main body's tool guidance is copy-paste ready without loading the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body never teaches concepts Claude already knows and each section is individually tight, but requirements are restated three-plus times across "Core Responsibilities", "Quality Standards", "Always Do / Never Do", and "Success Criteria" (e.g., 'Analyze ALL resources' appears as both a workflow step, a ✅ item, and a success criterion), so it could be cut substantially — matching 'mostly efficient but could be tightened'. Not a 2 because there is no fluff prose or unnecessary explanation, only repetition of genuinely task-specific guidance. | 3 / 5 |
Actionability | Provides concrete commands ("az resource list --resource-group <name> --output json"), exact Mermaid syntax ("SOURCE -->|\"Label\"| TARGET", "ID[\"Display Name<br/>Details\"]"), concrete resource-detail examples ("B1, S1, P1v2", "LRS, GRS, ZRS"), and a linked template plus example diagram — mostly executable guidance. Not a 5 because the MCP tool invocations in the body are given only as intent strings ("intent=\"list resource groups\"") without the actual tool names, which live only in the reference file, leaving a minor gap. | 4 / 5 |
Workflow Clarity | A clear four-step sequence with most checkpoints present: wait-for-user-selection and validate-group-exists before proceeding, "Verify all resource details before including in diagram", an Edge Cases & Error Handling section (empty groups, permission issues, 50+ resources), and a read-only boundary. Not a 5 because the Mermaid validation step is only "test syntax mentally before output" — there is no explicit validate-and-retry loop or concrete validation mechanism, which the top anchor expects. | 4 / 5 |
Progressive Disclosure | The body is a workflow overview with details appropriately split one level deep and clearly signaled at point of use: "See [Azure Resource Graph Queries](references/azure-resource-graph.md)" for bulk querying, "[example-diagram.md](./assets/example-diagram.md)" for a complete sample, and "[template-architecture.md](./assets/template-architecture.md)" for output structure — all three files exist and contain the promised material. Navigation is easy and nothing bulk (API reference, examples) is inlined that should be external, matching the top anchor. | 5 / 5 |
Total | 16 / 20 Passed |