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.
A dense, highly actionable body: executable commands with concrete output semantics, an explicit grep-then-context workflow, and a real, clearly linked reference file. The main gaps are upfront density of index-lifecycle detail and inlining of query-language specifics that could live in references.
Suggestions
Move the index-lifecycle minutiae (10-minute read wait, exit code 75, lock behavior for `workspace index --async`/`--wait`) into a reference file, keeping only the one-line 'the index refreshes automatically' summary in SKILL.md.
Split the grep query-language and output-format rules (GitLab kinds, `»` markers, scoping/widening) into a one-level-deep reference like `references/query-language.md`, linked from a short 'Choose the command' overview.
Make the grep→context workflow's error handling explicit, e.g. a one-line note: 'If grep exits 1 (no match), widen the scope or drop a kind qualifier before giving up.'
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | No space is spent on concepts Claude already knows; nearly every sentence carries tool-specific behavior (exit code 75, 30s lock waits, `»` marker lines, glab `--yes` flag ordering). Not 5 because the opening paragraphs densely front-load index-lifecycle, timeout, and exit-code detail that could be trimmed or deferred to the reference, slightly hurting clarity-per-token. | 4 / 5 |
Actionability | Copy-paste-ready shell commands throughout — `orbit grep "method:rate limit" src`, `orbit context duckdb_client::search::DuckDbSearch::grep src/lib.rs:120-180`, `orbit grep "mr:rate limit repo:gitlab-org/gitlab"`, `glab orbit --yes grep "..."` — covering local search, context reads, and GitLab targets, with concrete output-interpretation rules. Fully executable guidance covering the common cases. | 5 / 5 |
Workflow Clarity | An explicit sequence is stated — "Run `grep` first, then `context` on the symbol you will change to get its callers, callees, and covering tests" — with exit-code feedback documented ("Exit 1 means no match"). The tool is read-only, so the destructive/batch validation cap does not apply. Not 5 because validation/error-recovery checkpoints remain implicit rather than spelled out as a feedback loop. | 4 / 5 |
Progressive Disclosure | The bundle reference `references/local/cli.md` exists, is one level deep, and is clearly signaled twice (inline "Wrapper details" pointer and the References table), matching the actual bundle structure. Not 5 because substantial query-language and output-format detail (GitLab kinds, rg-style output rules, scoping/widening behavior) is inlined in SKILL.md rather than split into additional one-level-deep reference files. | 4 / 5 |
Total | 17 / 20 Passed |