Content
70%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 exceptional actionability and clearly sequenced, well-validated workflows with thorough error-recovery guidance. Its main weaknesses are token efficiency and progressive disclosure: a 58 KB monolithic SKILL.md inlines extensive rare-path operational detail that should live in per-topic reference files loaded on demand.
Suggestions
Split the deep edge-case material (UpdateSandbox RPC contract, credential placement metadata, stable_placeholder lifecycle, refresh backend migration and recovery markers, stdin reattachment semantics) into per-topic files under references/, keeping SKILL.md to the core command workflows with one-level-deep pointers.
Tighten the long multi-clause conditional paragraphs into scannable bullets or tables (e.g., a table mapping refresh RECOVERY/FAILURE_CODE values to remedies) to cut context tokens while preserving the information.
Move version- and time-sensitive compatibility details (e.g., 'Before OpenShell 0.1.0, the gateway does not migrate legacy inline refresh material', supervisor upgrade ordering) into a dedicated compatibility or deprecated section in a reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~1090-line (58 KB) body never pads with concepts Claude already knows, but it pervasively inlines rare edge-case minutiae as long dense paragraphs (sandbox UpdateSandbox RPC contract and retry backoff, credential placement metadata rules, stable_placeholder lifecycle, Vault backend migration, stdin reattachment semantics) that most invocations never need and that belong in reference files. This is 'noticeably verbose' with several sections that could be tightened or deferred; it is not a 1 because every sentence is product-specific rather than filler, and not a 3 because the deferrable detail is pervasive rather than isolated. | 2 / 5 |
Actionability | Commands throughout are copy-paste ready with realistic flags and arguments (e.g., the 'policy get --base | sed' pipeline, 'provider refresh configure' with all flags, 'sandbox create --expose' variants), and specific examples cover the common cases for every workflow. This fully matches the top anchor for executable, copy-paste-ready guidance. | 5 / 5 |
Workflow Clarity | Each of the ten workflows is clearly sequenced, and Workflow 4 includes a flowchart, numbered steps, explicit validation checkpoints ('--wait' with documented exit codes 0/1/124, 'policy list' revision status), and a feedback loop back to log monitoring. Destructive and batch operations do carry verification guidance (e.g., "'deletion accepted' means cleanup is still pending. Inspect the sandbox until it disappears"), so the destructive-operation cap is not triggered; error-recovery guidance for named failure codes is extensive. | 5 / 5 |
Progressive Disclosure | The body has clear structure and navigation (ten labeled workflows, companion-skill table, self-teaching --help section), so it is above the 'minimal structure / no headers' level, but no bundle files exist at all — the deep-dive edge-case material that clearly belongs in separate per-topic reference files is inlined in a single monolithic file. This matches 'some structure but content that should be separate is inline'; a 4 would require most content to be appropriately split across files. | 3 / 5 |
Total | 15 / 20 Passed |