Content
82%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.
A highly actionable, well-structured skill document whose commands and examples are copy-paste ready, backed by a genuinely useful debugging section. The main improvements are trimming minor conversational padding and adding an explicit post-present verification step to the workflow.
Suggestions
Add a verification checkpoint to the workflow after step 4 (e.g., '5. Verify: capture a snapshot with canvas action:snapshot node:<node-id> and confirm the content rendered') so the happy path includes its own validation instead of deferring all checks to the Debugging section.
Trim conversational filler such as 'Great for development!', 'Live reload makes development fast - just save and it updates!', and the 'Great for:' bullet list that duplicates the frontmatter description, to raise token efficiency.
Consider moving the architecture internals (bridge/Tailscale derivation details) or the debugging recipes into a single reference file to keep SKILL.md as a leaner overview, which would also improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by useful artifacts (ASCII architecture diagram, bind-mode table, config JSON, bash commands, real example invocations) rather than explanations of known concepts. It is not 5 because of a few conversational tokens that earn no place ('Great for development!', 'Live reload makes development fast - just save and it updates!', 'Great for:' list that restates the description). | 4 / 5 |
Actionability | Every step ships copy-paste-ready commands: the heredoc for creating HTML, 'cat ~/.bitterbot/bitterbot.json | jq', 'tailscale status --json | jq -r', 'bitterbot nodes list', 'lsof -i :18793', a curl test, and a fully concrete 'canvas action:present node:... target:...' example with a realistic hostname. This matches the fully-executable anchor covering the common cases. | 5 / 5 |
Workflow Clarity | The numbered workflow (create content → find host URL → find nodes → present → navigate/snapshot/hide) is clearly sequenced with concrete commands, and the Debugging section provides error-recovery paths for white-screen, node-required, and stale-content failures. It is not 5 because the happy-path workflow lacks an explicit validation checkpoint after 'present' (e.g., verify the canvas rendered or check the snapshot) — checkpoints live only in the troubleshooting section. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent) and the body makes no dangling file references, so all content is inline and self-contained. Section organization (How It Works, Actions, Configuration, Workflow, Debugging, URL Path Structure, Tips) is clear, but at ~205 lines with separable material (architecture internals, debugging recipes) it matches the 'good structure, minor organization gaps' anchor rather than the well-split 5 anchor. | 4 / 5 |
Total | 17 / 20 Passed |