Content
88%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 high-quality, highly actionable migration guide: copy-paste-ready commands, an exact construct-to-GQL mapping, worked examples, and an unusually rigorous validation workflow with control queries and cross-source comparison. The only weaknesses are minor — a few duplicated points across the Traps, Mapping, and Rejected constructs sections, and a single-file layout that is starting to outgrow SKILL.md.
Suggestions
Consolidate the duplicated guidance: reserved-word alias renaming appears in both Traps and the `nodes[].id` mapping row, and the postfix `NOT IN` rewrite and `direction: both` behavior each appear in both the Mapping and Rejected constructs tables — state each once and cross-reference it.
If the skill grows further, move the Mapping table and worked examples into a one-level-deep reference file (e.g. references/mapping.md) and keep SKILL.md as the workflow and validation overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and purposeful — no explanations of concepts Claude already knows, and the mapping table is core reference rather than padding — but a few points are stated twice: reserved-word alias renaming appears in both the Traps section and the Mapping rows, and postfix `NOT IN` plus `direction: both` each appear in both the Mapping and Rejected constructs tables. These minor duplications could be consolidated, which fits 'efficient; minor instances that could be trimmed' better than the fully lean anchor. | 4 / 5 |
Actionability | Everything is executable: `rg -l '"query_type"\s*:'` for discovery, `glab orbit query --response-format raw` with jq pipelines for validation, a REST cross-check command, exact GQL syntax for every legacy construct in the mapping table, and two complete worked examples pairing full legacy JSON with full GQL. Nothing is pseudocode or abstract. | 5 / 5 |
Workflow Clarity | The workflow has explicit sequencing with strong validation checkpoints and feedback loops: Step 0 branches on version/auth/network errors, the validation section runs the query, compares against old output or the REST API/`X-Total` header, checks pagination, runs a nonsense-value control query, and probes empty results with a known row, with 'Fix it and rerun' closing the compile-error loop. All steps are explicitly read-only, so the destructive/batch cap does not apply. | 5 / 5 |
Progressive Disclosure | Sections are well-organized with clear headers and inlined core content that is defensible for a temporary migration aid, but at roughly 190 lines it exceeds the under-50-line simple-skill exception: the mapping table and worked examples could be split into a one-level-deep reference file if the skill grows. 'Good structure; most content appropriately placed; minor organization gaps' is the best fit. | 4 / 5 |
Total | 18 / 20 Passed |