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.
The body is a highly actionable, well-sequenced onboarding script: exact commands, copy-paste prompts, and validation with error-recovery loops throughout, with no padding or basic-concept explanations. Its main weakness is progressive disclosure — a ~390-line monolith that inlines static prompt templates, diagrams, and a Python script that belong in separate reference or script files.
Suggestions
Move the transcript-counting Python script from step 4 into a bundled scripts/ file (e.g. scripts/count_usage.py) and invoke it with the start/end/path arguments, trimming ~35 lines from the always-loaded body.
Move the six fixed prompt-example blocks in step 3 into a one-level-deep references/prompts.md, loading them only when the user reaches step 3 and keeping only the bold labels and one-line summaries inline.
Move the five static "how Orbit works" parts (diagrams, explanations, and Read more links) in step 5 into a references/how-it-works.md so the main body stays a navigable session flow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is written as lean, imperative instructions with no explanations of concepts Claude already knows (no "what GitLab is", no "what a merge request is"), matching the 4-anchor ("Efficient; minor instances of over-explanation that could be trimmed"). It is not 5 because at ~390 lines it includes rationale sentences ("Shows that Orbit indexes your code, not only merge requests and pipelines"), a ~35-line inline Python script, and repeated option menus that could be tightened or externalized; it is not 3 because the prose itself is tight and every section is operational. | 4 / 5 |
Actionability | Guidance is fully executable throughout: exact commands (`glab orbit status`, `glab orbit schema Project MergeRequest MergeRequestDiffFile Pipeline Job Vulnerability File Definition User`, `date -u +%Y-%m-%dT%H:%M:%SZ`), six copy-paste prompt templates with `<placeholder>` substitution rules, a runnable Python script for counting tool calls and tokens, and a concrete comparison-table template with worked examples ("14 callers in 6 projects"). This matches the 5-anchor: copy-paste ready commands covering the common cases. | 5 / 5 |
Workflow Clarity | The session is sequenced as six numbered steps with numbered sub-steps, and validation with error-recovery loops is explicit: "If it fails, follow the entry for its exit code... and run `glab orbit status` again. If it still fails, tell the user what failed and stop", "If no project in the scope is indexed yet, tell the user, and ask for another scope", and "If a query returns no rows, say so". This matches the 5-anchor (clear sequence, explicit validation, feedback loops); the session is read-only and per-session scoped, so the destructive/batch cap does not apply, and the 4-anchor's "minor validation gaps" are not present. | 5 / 5 |
Progressive Disclosure | Section structure is good (## per step, ### per part, working internal links like [Answer with Orbit](#answer-with-orbit)) and no bundle files are referenced (verified: references/, scripts/, assets/ do not exist). But roughly 200 lines of static content are inlined in the always-loaded SKILL.md — the six fixed prompt-example blocks in step 3, the five static "how Orbit works" walkthrough parts in step 5, and the transcript-counting Python script — which clearly belong in one-level-deep reference or script files. This matches the 3-anchor ("content that should be separate is inline"); it is not 4 because that bulk is more than a minor organization gap, and not 2 because the internal structure and navigation are solid. | 3 / 5 |
Total | 17 / 20 Passed |