Content
75%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 an efficient, actionable project brief: concrete commands, hard constraints, ADR-driven checkpoints, and no filler. Its main weaknesses are the absent error-recovery loop around crash debugging and slight redundancy between the opening line and the description.
Suggestions
Add a short crash-recovery loop for the supervision-tree debugging use case (e.g., reproduce in iex, check supervisor restarts via Observer or logger output, fix the child spec, re-run mix test).
Remove the opening sentence that restates the description, or replace it with the single highest-value fact not already known.
Consider moving the ADR table and four-phase roadmap into a references/ file (e.g. references/ADRS.md) with a one-line pointer, keeping SKILL.md focused on commands, constraints, and patterns.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence — no OTP/BEAM primers, no padded explanations — with every section carrying project-specific facts (Redis location, key names, ssh target). It falls short of 5 because the opening line ('Use this skill when working on the Koko Elixir project — the BEAM co-resident agent alongside joelclaw') duplicates the description, and Phase 4 graduation criteria ('DX is enjoyable') are roadmap content with marginal operational value. | 4 / 5 |
Actionability | Concrete, copy-paste-ready commands ('mix deps.get', 'mix run --no-halt', 'iex -S mix', 'ssh joel@panda "cd ~/Code/joelhooks/koko && mix run --no-halt"'), exact resource names ('joelclaw:gateway:events', 'joelclaw:koko:shadow:<function>', 'localhost:6379'), and specific OTP directives ('Logger.info("[koko]")', 'one_for_one unless processes are coupled'). Minor gaps keep it from 5: no example GenServer skeleton or handle_info pattern to copy when adding a workload. | 4 / 5 |
Workflow Clarity | Conditional checkpoints are explicit ('Before adding a new workload: Check ADR-0117... and ADR-0118', 'Before changing Redis integration: Check ADR-0116', 'Before any architectural change: Propose or update an ADR'), and development commands form a runnable sequence with 'mix test' as validation. It is not 5 because there is no explicit validate/fix/retry loop for the riskiest operation — debugging supervision-tree crashes is listed as a use case but the workflow stops at 'mix test' with no error-recovery guidance. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the ~95-line body is well-organized with clear one-level-deep pointers: the ADR table links each decision by URL, 'AGENTS.md: Full context in repo root' signals where depth lives. Not 5 because the four-phase roadmap and the ADR table (five external links) are content that could live in a single reference file, and there is no explicit mapping of which sections to consult for which task beyond the three 'Before...' lines. | 4 / 5 |
Total | 16 / 20 Passed |