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.
This is a strong, executable CLI skill: concrete commands throughout, a golden path with validation and recovery steps, and no filler. The main weakness is structural — everything, including advanced debugging and provider-routing details, is inlined in one long file instead of being split into one-level-deep references.
Suggestions
Move advanced troubleshooting (perf-trace, remote browser host, 1Password key injection, local-checkout debugging) into a references/ file and link to it from a short 'Advanced' section, keeping SKILL.md to the golden path and core commands.
Deduplicate the repeated 'API runs require explicit user consent' note so it appears once.
Consider moving the flag-level details of `--file` include/exclude/defaults into a reference, keeping only a few illustrative examples inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with tool-specific facts (flag behavior, default-ignored dirs, token caps, exit codes) and explains nothing Claude already knows. Minor trim opportunities remain: API-consent is stated twice ("API runs require explicit user consent" appears in both Engines and API preflight) and the 1Password/local-checkout debugging steps are peripheral to the main workflow. Not 5: those small redundancies keep it short of 'every token earns its place'. | 4 / 5 |
Actionability | Every section gives copy-paste-ready commands with concrete flags and arguments, e.g. `npx -y @steipete/oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`, `oracle status --hours 72`, and the exact `op item get` injection. The common cases (preview, browser run, reattach, preflight) are all covered by specific examples. | 5 / 5 |
Workflow Clarity | The 'Golden path' section gives a clear 4-step sequence (pick tight file set → preview with `--dry-run` + `--files-report` → run → reattach on detach/timeout) with an explicit pre-send validation checkpoint and an error-recovery loop ('don't re-run; reattach' with `oracle status` / `oracle session <id>`). Guardrails (duplicate-prompt guard, exit codes, conflicting flags) add explicit failure handling. | 5 / 5 |
Progressive Disclosure | Sections are well-organized with clear headers, but the entire ~135-line reference lives inline in SKILL.md with no bundle files at all; advanced troubleshooting (perf-trace, remote browser host, 1Password key injection, building the local checkout) is material that clearly belongs in a separate reference file. Not 4: no references exist to be 'mostly clear', and the one-file layout means content that should be separate is inline. | 3 / 5 |
Total | 17 / 20 Passed |