Content
63%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 delivers strong executable guidance with clear MUST/MUST NOT rules, a precise reference syntax, and thorough troubleshooting with real feedback loops. Its weaknesses are inlined implementation details (SigV4 mechanics, re.sub internals) that pad token cost, and a progressive-disclosure failure: the asm-exec script exists in references/ but the body never points to it, so an agent cannot discover how to actually run the wrapper.
Suggestions
Link the script explicitly, e.g. "The wrapper lives at [references/asm-exec](references/asm-exec); run it as `python3 references/asm-exec -- <command>` or install it on PATH", so the examples are genuinely executable.
Move the SigV4 signing internals and the re.sub/subprocess implementation notes out of SKILL.md into a reference file, keeping only the credential-resolution order that Prerequisites actually needs.
Add a quick verification step to the usage patterns (e.g. check the command's exit status or stderr for "asm-exec:" lines before treating output as trusted).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The rules, syntax table, and examples are tight, but the body inlines implementation internals the agent does not need to use the skill: "Substitutes resolved values using re.sub with a callable", "signs requests itself using only the Python standard library (hashlib/hmac)", and "The signing service and region are inferred from the endpoint hostname". This is mostly efficient with some unnecessary explanation that could be tightened or moved to a reference file, matching anchor 3 rather than 4, where over-explanation would be only minor. | 3 / 5 |
Actionability | Guidance is largely copy-paste ready: three complete asm-exec examples (psql, curl, mysql), common patterns for docker and config templating, a syntax table with defaults, and concrete diagnostics ("aws sts get-caller-identity", "ASM_EXEC_MCP_TIMEOUT"). It falls short of 5 because the body never says where the asm-exec script lives or how to install/invoke it (the script sits at references/asm-exec but is never linked), leaving a gap between the examples and an actually runnable command. | 4 / 5 |
Workflow Clarity | The sequence is clear (rules, then syntax, then usage, then patterns) and the Troubleshooting section provides a genuine error-recovery feedback loop ("read that line first", check credentials, check region, 401 means signing problem, raise ASM_EXEC_MCP_TIMEOUT). It does not reach 5 because the usage patterns lack an explicit verification checkpoint before proceeding (e.g. the config-templating example writes /tmp/app.conf with no check that resolution succeeded); recovery guidance is reactive rather than a workflow checkpoint. | 4 / 5 |
Progressive Disclosure | Section structure is good, but the one bundle file — references/asm-exec, the very script the entire skill revolves around — is never referenced or linked anywhere in the body, and the only path mentioned ("plugins/aws-core/com.anthropic.claude-code/hooks/hooks.json") points outside the bundle. This matches anchor 3 (references present but not clearly signaled; inlined content such as the SigV4 signing internals that could live in a separate file) rather than 4, which requires references to be mostly clear. | 3 / 5 |
Total | 14 / 20 Passed |