Content
82%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.
The body is a dense, high-signal reference: every fact is project-specific and actionable, with exact commands, verbatim error messages, and clearly sequenced fallback behavior. Its main weaknesses are the absence of a concrete usage example for the AuthResolver key rule and inline diagnostic detail that could be split into a bundled reference file.
Suggestions
Add a 3-5 line code example showing correct AuthResolver usage vs. the forbidden os.getenv() pattern, since the key rule is the skill's central instruction.
Move the six diagnostic cases into a references/ file (e.g., references/ado-diagnostics.md) and keep a one-line summary plus the link in SKILL.md.
State explicitly what Claude should do when the skill activates (e.g., 'check changes against the canonical flowchart and fix the diagram in the same PR if behavior diverges') as a short workflow step list.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and entirely project-specific: fallback chains, exact env var names, the AAD resource GUID, and verbatim diagnostic message text. It assumes Claude's competence — no general auth concepts are explained — and every line carries information Claude could not know otherwise. | 5 / 5 |
Actionability | Concrete, executable guidance throughout: a copy-paste-ready command ('az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798'), exact file paths and class names ('src/apm_cli/core/auth.py', 'GitHubTokenManager.ADO_BEARER_SOURCE'), and per-case remediation steps. Minor gaps: the key rule ('all auth flows MUST go through AuthResolver') is stated without a short usage example. | 4 / 5 |
Workflow Clarity | The ADO chain is a clearly numbered sequence with explicit fallback conditions ('after HTTP 401/403 or a recognized Git authentication failure') and enumerated failure cases with remediation. It stops short of anchor 5 because there are no explicit validation checkpoints or fix-retry loops for Claude's own edits — the content describes the system's behavior more than a step-by-step editing workflow. | 4 / 5 |
Progressive Disclosure | Well-organized sections (activation triggers, key rule, canonical reference, ADO chain, diagnostics) with external references clearly signaled and one level deep: the persona link and the canonical authentication doc with its mermaid flowchart. Not a 5 because the six diagnostic cases are moderately detailed inline material that could live in a reference file, and the referenced paths point outside the skill bundle rather than to bundled references. | 4 / 5 |
Total | 17 / 20 Passed |