Content
85%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.
An unusually strong reference body: fully executable examples with explicit validation checkpoints and checklists, packed with non-obvious operational gotchas and no filler. The one structural weakness is progressive disclosure — everything lives inline in SKILL.md with no bundled references, leaving reference-grade material (images, CLI, drives, limits) in the always-loaded file.
Suggestions
Split reference-grade sections (Images, Drives, CLI, Limits and cost) into bundled files under references/ and keep one-line pointers in SKILL.md, e.g. 'See [images.md](references/images.md) for the managed-image table and custom-image builds'.
Trim the duplication between the Best-practice checklist and the body — keep the checklist as terse one-liners and drop the re-explanations (e.g. the full bash -c / exitCode rationale appears in both).
Consolidate the credential-brokering explanation (currently detailed in both Network policy and Running AI agents) into one section and cross-link the applied AI-gateway case to it.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious, API-specific gotchas ("runCommand runs a binary directly — there is no shell", "it does not throw on a non-zero exit", "package lists ship empty, so install fails without it", "listening on 0.0.0.0 (not 127.0.0.1)", "Hooks are per call... a different process resuming via Sandbox.get won't run them") and assumes Claude's competence rather than explaining background concepts. It misses the top anchor only because of minor padding: the Best-practice checklist restates body content nearly verbatim, and credential brokering is explained in both the Network policy and Running AI agents sections. | 4 / 5 |
Actionability | Every section carries copy-paste-ready, executable code covering the common cases: the create/run/stop loop with try/finally, bash -c shell wrapping with an exit-code check, sudo apt-get install, the writeFiles/readFileToBuffer buffer handling with a null guard, the port-poll readiness loop, the snapshot workflow, concrete networkPolicy objects, and CLI commands. Phrases evaluated: "const sandbox = await Sandbox.create(); try { ... } finally { await sandbox.stop(); }", "if (r.exitCode !== 0) throw new Error(await r.stderr())", "sandbox create --name my-box", "sandbox run --rm -- node --version". | 5 / 5 |
Workflow Clarity | The core workflow is explicitly sequenced (create → run → stop, with stop in a finally so a thrown error can't leak a running VM) and includes explicit validation checkpoints: exit-code checks that throw with stderr, a poll-until-the-port-answers loop with retry, a null guard on readFileToBuffer, and a best-practice checklist for the complex cases (untrusted code gets deny-all, short timeout, vcpus: 1, persistent: false). Phrases evaluated: "stop in a finally so a thrown error can't leak a running VM", "if (install.exitCode !== 0) throw new Error(await install.stderr())", "for (let i = 0; i < 30; i++) { ... if ((await ping.stdout()).includes(\"up\")) break; }". | 5 / 5 |
Progressive Disclosure | The body is well-sectioned with clear, navigable headers and working intra-document links, but it is a monolithic ~330-line document with no bundle files at all — reference-style material that would naturally live one level deep (the Images table, Drives details, CLI command list, Limits and cost tables) is fully inlined. This matches the 'content that should be separate is inline' anchor; it avoids a 2 because the sections are well-organized and clearly signaled rather than a wall of text. | 3 / 5 |
Total | 17 / 20 Passed |