Content
92%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 exemplary operational skill body: executable commands in every step, a contingency matrix up front, validation gates and honesty rules throughout, and deliberate version-deferral to the repository so nothing goes stale. The only blemish is the time-sensitive 'as of this writing' hook listing in Step 7, which duplicates what the skill itself says to read from lefthook.yml.
Suggestions
Trim the 'as of this writing pre-commit runs oxlint and `bun fmt`… pre-push runs the type check, `bun audit`…' sentence in Step 7 to just the instruction to read lefthook.yml and tell the user; the inline list duplicates the file and will go stale at the next hook change.
The long bootstrap-bare-root paragraph in Step 7 could be reduced to what to do and what to report, moving the rationale about worktree-subdirectory sessions into the script's own output or a wiki page it already links.
Tighten a few rationale clauses (e.g., 'which is why portless is tilde-pinned in package.json — a version bump is a change to review') to the actionable core where the reason is already obvious to an experienced agent.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Efficient and assumes Claude's competence — no explanations of Homebrew, SSH, or GPG basics, and every pinned version is deferred to the tree ("Every pinned value comes from the repository") — but Step 7 inline-lists time-sensitive hook contents ("as of this writing pre-commit runs oxlint and `bun fmt` in write mode with `stage_fixed`, and pre-push runs the type check, `bun audit --audit-level=high`…") immediately after saying "Read `lefthook.yml` for what the hooks do", which is duplicated, staled-at-bump detail that could be trimmed. This sits between the 4 and 5 anchors, closer to efficient-with-minor-trimmable-instances. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready commands throughout — `curl -fsSL https://bun.sh/install | bash -s "bun-v$(cat .bun-version)"`, the `npm install -g --before=…` soak line, a check/apply git-config table, `bash scripts/setup.sh`, `bunx portless proxy start` — with the common cases (macOS, non-macOS, no sudo, no network, non-interactive) explicitly covered, matching the score-5 anchor. | 5 / 5 |
Workflow Clarity | Nine clearly ordered steps with explicit validation checkpoints (`gh auth status`, `gh repo view`, `gh pr list`, re-verify after install, the three gates, `bunx portless doctor`, `claude plugin list`), feedback loops ("If it does not print the version… install that exact version. Verify again"; "If a gate fails, paste the shortest decisive lines into the table and keep going"), and a hard honesty rule ("Never claim a gate passed that did not run here") plus a mandated final report table — the score-5 anchor. | 5 / 5 |
Progressive Disclosure | No bundle files exist, and the body stays lean by deferring detail to clearly-signaled, one-level-deep repository files (`lefthook.yml`, `scripts/setup.sh`, `wiki/conventions/devloop-urls.md`, `wiki/conventions/agent-tooling.md`) under the rule "If any of those disagree with what is below, the tree wins" — well-organized step headers and a contingency section make navigation easy, matching the score-5 anchor. | 5 / 5 |
Total | 19 / 20 Passed |