Content
77%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, safety-conscious jj guide: commands are concrete and executable, workflows have explicit verification and undo loops, and agent-environment pitfalls (pagers, editors, interactive flags) are consistently called out. Its weaknesses are structural and editorial — a long single file that could split advanced topics into reference files, plus repeated reminders and one malformed example block that cost token efficiency.
Suggestions
Move the Workspaces deep-dive and colocated-git switching sections into a references/ file (e.g. WORKSPACES.md, GIT-COLOCATED.md), keeping a short summary plus a clearly signaled link in SKILL.md.
State the `--no-pager` / inline `-m` rules once in the agent-environment section and drop the repeated inline reminders and 'NOT:' comments.
Replace the non-command 'Examples:' code block under 'Creating Atomic Commits' with plain example messages (the same list already appears correctly under 'Preserving Commit Quality').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient, command-first content covering genuinely non-obvious jj semantics (working-copy-as-commit, change IDs, fileset quoting), but there is noticeable tightening to do: the `--no-pager` and `-m` guidance is repeated across the intro, individual commands, and the Quick Reference; the 'Creating Atomic Commits' section contains a pseudo-code block of 'Examples:' that is not a command; and the ~35-line Workspaces deep-dive is inlined for a self-described 'rarely-needed feature'. This fits anchor 3 (mostly efficient, some unnecessary explanation or could be tightened) better than anchor 4, where such instances would be minor. | 3 / 5 |
Actionability | Nearly every section gives copy-paste-ready commands with concrete arguments: `jj desc -m "Add user authentication to login endpoint"`, `jj split -m "Add search" src/search.txt`, `jj revert -r <change-id> -B @`, `jj restore 'file:"docs/notes (draft).md"'`, plus a Quick Reference table covering the common cases. It also flags non-executable variants to avoid (`squash -i`, bare `split`), matching anchor 5's fully executable, common-case-covering standard. | 5 / 5 |
Workflow Clarity | Multi-step workflows are clearly sequenced with explicit validation and recovery: 'Describe First, Then Code' (jj st → jj new → jj desc → edit → jj st), 'Verify operations with `jj st` after mutations', a pre-push checklist with bookmark-advance gotchas and `jj undo` recovery, and a 'Preserving Commit Quality' checklist. Destructive operations (squash, abandon, rebase) all carry verification or undo feedback loops, matching anchor 5's explicit validation, error-recovery loops, and checklists. | 5 / 5 |
Progressive Disclosure | Section headers and the Quick Reference give good in-file navigation, and the Workspaces section appropriately defers depth to the official docs, but this ~460-line skill inlines substantial content that would fit reference files (Workspace semantics, colocated git switching, bookmark push workflows) with no bundle files at all. Anchor 3 (some structure, content that should be separate is inline) fits; it is above anchor 2 because structure is not minimal, and below anchor 4 because no well-signaled one-level-deep references exist. | 3 / 5 |
Total | 16 / 20 Passed |