Content
77%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, highly actionable orchestrator document with excellent sequencing, validation checkpoints, and error-recovery loops, and virtually no filler. Its weaknesses are token efficiency (systematic repetition of prerequisite prefixes and an over-long inline context-resolution section) and progressive disclosure (25 of 28 linked sub-skill documents are absent from the bundle, leaving most routing links unresolved).
Suggestions
State the "dependency check and setup → azd-guidance" prerequisite once above the lifecycle table and drop it from every row — the ~12 repeated link chains are the single largest avoidable token cost in the body.
Move the seven-step Common Project Context Resolution into a reference file (e.g. references/agent-context-resolution.md) and keep a short summary plus link in SKILL.md, mirroring the existing agent-metadata-contract.md pattern.
Ensure the referenced sub-skill files ship with the skill bundle — 25 of 28 .md links (deploy, invoke, observe, finetuning, rbac, etc.) currently point to files that do not exist, breaking the router's navigation; also consider flattening the two-level-deep voice-agent/subtypes.md reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is almost entirely Foundry-specific operational knowledge Claude would not already know (no concept-explanation padding), but it could be meaningfully tightened: the ~12 rows of the Agent Development Lifecycle table each repeat the identical "[dependency check and setup](#dependency-check-and-setup) → [azd-guidance](...) →" prefix, the MANDATORY prerequisite rules are restated across three Pre-Execution subsections, and the ~100-line seven-step context resolution runs long. This fits level 3's "mostly efficient but ... could be tightened" rather than level 4's "minor instances" — the repetition is systematic, not incidental — while level 2's "several unnecessary explanations" overstates it since nothing explains known concepts. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: copy-paste-ready commands ("./scripts/check-and-setup-dependencies.sh", the full "az cognitiveservices account show --query ..." diagnostic), exact environment-variable tables (AZURE_AI_PROJECT_ENDPOINT, AGENT_<SERVICE>_NAME), exact tool names (ask_user, evaluator_catalog_get, prompt_optimize), and precise ordered decision rules (metadata file selection order, agent-type classification order). This matches level 5's "fully executable ... specific examples cover the common cases" — for an orchestrator/instruction skill there are no pseudocode substitutes, satisfying the code_vs_instruction scoring note. | 5 / 5 |
Workflow Clarity | Multi-step processes are explicitly sequenced with validation checkpoints and feedback loops: Steps 1–7 each define fallback ordering with "verify with evaluator_catalog_get before treating them as remote evaluators", "Persist synced ... references ... only after remote lookup or registration succeeds", and "If azd and metadata both provide the same value and they differ, stop and ask"; the Network Isolation Errors section is a full diagnose → confirm with management-plane call → interpret branches → remediate loop; and metadata writes (a batch/overwrite-risky operation) carry guardrails ("ask before refreshing or overwriting them", "Never copy or merge environments across sibling metadata files"). This matches level 5; level 4's "minor validation gaps" understates the pervasive checkpointing. | 5 / 5 |
Progressive Disclosure | The router design is well-signaled (a When-to-Use table plus lifecycle tables with markdown links), but scoring against the actual bundle reveals 25 of the 28 referenced .md files are missing (e.g. foundry-agent/deploy/deploy.md, models/deploy-model/SKILL.md, quota/quota.md) — only the 3 references/ files exist — so most navigation dead-ends. Additionally, one referenced path sits two levels deep (foundry-agent/create/references/voice-agent/subtypes.md is linked directly from SKILL.md) and ~100 lines of context-resolution detail (Steps 1–7) are inlined in SKILL.md where the skill already uses reference files for comparable material. This lands at level 3's "some structure but could be better organized" — above level 2 ("minimal structure ... references are buried" does not hold; structure and signaling are good) but below level 4 ("minor organization gaps" — broken reference targets are not minor). | 3 / 5 |
Total | 16 / 20 Passed |