Content
86%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 high quality: executable scaffolds, well-sequenced workflows with validation checkpoints, and clean progressive disclosure into six real reference files. The only weak spot is mild verbosity in a few explanatory sections.
Suggestions
Tighten the Architecture section's ASCII diagram and the additive-UI lead-in — the deployment shapes can be conveyed in a sentence each since the code already shows the mechanism.
Add a short explicit 'verify the widget renders (non-blank iframe, no CSP violation in iframe devtools)' checkpoint to the main scaffold-then-test flow so the validate→fix→retry loop is as explicit as the testing section's loops.
Consider moving the Widget runtime App-class method table (a long API surface) to references/apps-sdk-messages.md and keeping only the 3-4 most-used methods inline, further trimming the in-body token budget.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly lean and assumes Claude's competence (code, constraints, concrete gotchas like the esm.sh CSP warning), with only minor padding in the ASCII diagram and a few explanatory lead-ins; not 5 because a few sentences could be trimmed, not 3 because it avoids explaining basics Claude already knows. | 4 / 5 |
Actionability | Fully copy-paste-ready executable guidance — the complete src/server.ts scaffold, picker.html widget, npm install line, JSON-RPC test loop, and dev shim — covering the common cases with specific values; matches the fully-executable anchor. | 5 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced with real checkpoints ("Set handlers BEFORE connecting", fully-quit-and-relaunch for cache, CSP-debug feedback loop); not 5 because the main build path lacks a single explicit validate→fix→retry checklist, not 3 because checkpoints are present and explicit rather than implicit. | 4 / 5 |
Progressive Disclosure | Body is a clear overview with bulk detail split into six well-signaled one-level-deep reference files (iframe-sandbox, widget-templates, apps-sdk-messages, payload-budgeting, abuse-protection, directory-checklist — all verified to exist) summarized in a final Reference files section; matches the clear-overview-one-level-deep anchor. | 5 / 5 |
Total | 18 / 20 Passed |