Content
70%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.
This is a strong operational runbook: exact commands, an explicitly sequenced eval loop with validation gates, and a built-in feedback cycle for fixing skills. Its main weaknesses are duplication and time-sensitive version history inlined in the main file, plus scenario prompts given only as summaries rather than ready-to-use text. Moving the scenario table and issue history into reference files would improve both conciseness and progressive disclosure.
Suggestions
Move the 12-scenario table and the 'Common Issues Found in Evals' version-history table into a references/ file (e.g. references/scenarios.md and references/issue-history.md), keeping only the tier summary and current canonical patterns in SKILL.md.
Provide the full literal prompt text for at least the Tier 1 scenarios so evals are copy-paste ready, rather than only prompt summaries plus the standard closing sentence.
Deduplicate the `claude --print` / eval-scripts prohibition (stated in both 'How Evals Work' and the DO NOT list) and replace the hardcoded `/Users/johnlindquist/dev/...` path with the `~/dev/...` variable used elsewhere.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and command-heavy with essentially no re-teaching of known concepts, but it can be tightened: the `claude --print` prohibition is stated twice (in 'How Evals Work' and again in the DO NOT list), and the 14-row 'Common Issues Found in Evals' table embeds plugin version numbers (v0.8.0–v0.9.9) — time-sensitive data outside any deprecated/old-patterns section. This is 'mostly efficient but includes some unnecessary content or could be tightened', not score 2, since the padding is localized rather than pervasive. | 3 / 5 |
Actionability | Setup, monitoring, and verification sections give exact copy-paste commands (`npx add-plugin https://github.com/vercel/vercel-plugin -s project -y`, `wezterm cli spawn --cwd … -- /bin/zsh -ic …`, grep one-liners with YES/NO echoes). It falls short of fully copy-paste ready, though: the 12 scenarios provide only prompt summaries ('PDF Q&A with embeddings, citations, multi-step reasoning') rather than usable prompts, and the parallel-launch block abbreviates paths (`--cwd .../tarot-deck-$TS`). | 4 / 5 |
Workflow Clarity | The full eval loop is explicitly sequenced (setup → launch → monitor → verify → fix → release → repeat) with concrete checkpoints: 'wait ~25s for SessionStart hooks', YES/NO structure checks, and release gates `bun run typecheck && bun test && bun run validate`. A feedback loop is present — issues found feed back into skill fixes and re-running evals — matching the anchor for clear sequence with explicit validation and error-recovery loops. | 5 / 5 |
Progressive Disclosure | Section headers make the ~310-line document navigable, but there are no bundle files at all — the 12-scenario table, the version-history issue table, and the verification grep catalog are reference material inlined in the main file. This matches 'Some structure but could be better organized; content that should be separate is inline'; it is not score 4 because there are no one-level-deep references despite the length. | 3 / 5 |
Total | 15 / 20 Passed |