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.
An exceptionally actionable, rigorously validated workflow — every step has executable commands, explicit fallbacks, and stop-gates, which is rare. The costs are token efficiency and structure: the same environment traps are restated up to four times, dated incident logs are woven into the instructions, and everything (routing table, template, gotchas) is packed into one monolithic SKILL.md instead of one-level-deep reference files.
Suggestions
Split environment gotchas (Windows cp1252/UTF-16LE, PowerShell `$` interpolation, heredoc rules, filename emoji traps) into references/windows-gotchas.md and keep one canonical statement plus a pointer in SKILL.md, eliminating the 3-4x repetition of the LIVE/DEGRADED read() trap.
Move the dated incident log ("observed 2026-09-17 → 09-19", "Measured 2026-09-22", "caught 2026-10-02") into a short 'Why these rules exist' changelog section or file so time-sensitive detail stops padding the live instructions.
Extract the note template and the 13-bucket routing table into references/note-template.md and references/routing.md, leaving SKILL.md a lean overview with clearly signaled one-level-deep links.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | At ~1,190 lines the body repeats the same traps multiple times: the LIVE-vs-DEGRADED `ob.read()` semantics are explained in the Step 0 trap box, again in Step 2.5a, again in the Step 4 slug-check warning, and again as Rule 19; the heredoc prohibition appears in Step 4 and Rules 4-5. Dated incident notes ("Measured 2026-09-22", "observed 2026-09-17 → 09-19", "caught 2026-10-02") are time-sensitive and inline rather than in a changelog/deprecated section. This matches "noticeably verbose; several unnecessary explanations or padded sections". Not 1 because none of it explains concepts Claude already knows — every trap is genuinely environment-specific; not 3 because the repetition and incident-log padding could realistically halve the token count. | 2 / 5 |
Actionability | Every step has copy-paste-ready commands: the preflight probe one-liner, `python .github/skills/obsidian-linked-research/scripts/fetch.py "<url>"`, the executable `prune_recently_added()` function, the exact image-filter token list (`w_150`, `profile_images`, `default-light`), and the exact `chr(0x1F5FA) + chr(0xFE0F)` filename construction. Fully executable with specific examples covering tweets, web pages, threads, and degraded mode. | 5 / 5 |
Workflow Clarity | Steps 0-8 are clearly sequenced with explicit validation checkpoints and feedback loops: the preflight probe ("run this first, every time"), the mandatory URL-dedup stop gate ("If a match is found, stop"), the `note_text()` assert on the MOC, the explicit truncation check `len(result.get('content', '')) >= 8000`, the transient retry ("retry once... if it fails twice, report"), post-write read-back verification, and the Substack archive-API fallback. This matches the anchor's validate-fix-retry pattern. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned with clear step headers, and the one bundle file (scripts/fetch.py, 767 lines) is real and correctly referenced. But there are no reference files at all: content that clearly belongs in separate files is inlined — the 13-row routing table, the full note template, the Windows/PowerShell gotcha compendium, and the pruning code all live inside a monolithic ~1,200-line SKILL.md. This matches "some structure but could be better organized; content that should be separate is inline". Not 2 because the structure and navigation within the file are strong; not 4 because essentially all reference-worthy material is inlined rather than split out one level deep. | 3 / 5 |
Total | 15 / 20 Passed |