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.
An efficient, highly actionable CLI reference with excellent token economy and concrete executable examples throughout. The main defects are navigation/consistency issues: a promised query-language section for `orbit query` that never materializes, and a mismatched link path in the References table.
Suggestions
Resolve the dangling promise in "Choose the command": either include the `orbit query` language in the body, point to a reference file that contains it, or drop the "Write the query in the language below" sentence (currently no query language exists in SKILL.md or references/local/cli.md).
Fix the References table link text so it matches the actual path: [`references/local/cli.md`](references/local/cli.md) instead of `references/cli.md`.
Consider moving the detailed grep-semantics rules (kind qualifiers, `file:`/`dir:` filters, widening behavior) into a reference file to keep SKILL.md as a lean overview, consistent with the existing cli.md pattern.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense, terse, and information-rich with zero padding: it assumes Claude's competence and packs only non-obvious behavioral details (exit code 75, lock semantics, `--yes` placement rules, rg-style output format, kind qualifiers). No concept Claude already knows is explained, matching the 'lean and efficient; every token earns its place' anchor rather than the 4 anchor, which requires trimmable over-explanation. | 5 / 5 |
Actionability | Guidance is overwhelmingly executable: concrete copy-paste shell commands (`orbit grep "method:rate limit" src`, `glab orbit --yes grep "..."`, `orbit context mr:42 ...`) with specific flags and behaviors. It falls short of the 5 anchor because of a real gap: the "Choose the command" section introduces `orbit query` with "Write the query in the language below", but no query language appears anywhere in the body or in the single reference file, and the References table link text (`references/cli.md`) does not match the actual path (`references/local/cli.md`). | 4 / 5 |
Workflow Clarity | The core find-then-read workflow (grep → context) is unambiguous with worked examples, command selection is guided by the "Choose the command" section, and the "Fix inaccurate guidance" section has a clear confirm-then-act sequence. Above the 3 anchor because sequences and edge-handling (stale index, async indexing) are explicit; below the 5 anchor because one of the three advertised commands (`orbit query`) has no documented usage, leaving that branch of the decision flow undefined. | 4 / 5 |
Progressive Disclosure | Good structure overall: a focused overview, clearly signaled one-level-deep reference to a real file (`references/local/cli.md`), and a References table for navigation. Not the 5 anchor due to minor gaps: the table's link text says `references/cli.md` while the target is `references/local/cli.md`, and ~50 lines of grep-query semantics are inlined in SKILL.md where the pattern of pointing to a reference file is already established. | 4 / 5 |
Total | 17 / 20 Passed |