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.
An excellent diagnostic skill body: fully executable commands, a diagnosis-to-fix lookup table, a clear escalation workflow with verification, and a system-specific event-chain map that assumes Claude's competence. The main issues are two sections describing future/planned infrastructure rather than actionable diagnosis, and cross-references using non-portable absolute paths.
Suggestions
Trim the "Observability Patterns" (Future watchdog) and "Making Loops More Resilient" sections to one or two lines of context, or move them to a separate reference doc — they describe planned infrastructure, not diagnosis steps.
Replace absolute machine-specific cross-reference paths (/Users/joel/..., /Users/joel/Vault/...) with portable relative paths so the links resolve wherever the skill bundle is installed.
Optionally state explicitly that `--fix` and `loop restart` mutate state (clear claims, re-fire events, restart deployments) before the Quick Commands block, so the destructive nature of the auto-fix flag is visible up front.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean overall — tables, terse bullets, and executable commands with no explanation of concepts Claude already knows. However, the "Observability Patterns" section (watchdog marked "Future") and "Making Loops More Resilient" ("Solutions being implemented") describe planned infrastructure the diagnosing agent cannot act on. This matches anchor 4 (efficient with minor instances that could be trimmed); it is above anchor 3 because padding is limited to those two sections, and below anchor 5 because those sections do not earn their tokens for the diagnosis task. | 4 / 5 |
Actionability | Quick Commands gives copy-paste-ready invocations ("joelclaw loop diagnose all -c", "--fix", JSON mode), the failure-modes table maps every diagnosis to root cause and specific auto-fix, and the manual session includes an executable curl+python one-liner for worker health. This matches anchor 5 (fully executable, copy-paste ready, covers common cases); no gaps found. | 5 / 5 |
Workflow Clarity | The "Manual: The Diagnostic Session" section is a numbered 1-5 sequence with an explicit validation checkpoint ("Verify fix worked (wait ~30s for plan to fire)"), conditional escalation ("If still stuck, check worker"), and a final fallback (full restart). Feedback loops are present even though --fix/restart are risky operations, so the destructive-operation cap does not apply. This matches anchor 5; not anchor 4 because validation and error-recovery steps are explicit rather than minor-gapped. | 5 / 5 |
Progressive Disclosure | No bundle files exist; the single ~120-line document is well-sectioned with clear headers, appropriate for a skill of this scope. However, the Cross-References section points to machine-specific absolute paths (/Users/joel/.pi/agent/skills/..., /Users/joel/Vault/docs/...) that will not resolve outside the author's machine. This matches anchor 4 (good structure, minor organization gaps); it is above anchor 3 because structure and sectioning are solid, and below anchor 5 because the cross-references are broken as written. | 4 / 5 |
Total | 18 / 20 Passed |