Content
92%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 exemplary skill body: concrete syntax examples, a working query language with shape constraints per component, explicit read-back validation for live views, and a well-structured split between inline essentials and a single well-signaled reference file. The only improvement area is trimming a handful of elaborate prose passages in the snapshot and error-recovery sections.
Suggestions
Tighten the snapshot paragraph in 'Live views' — the Freeze-snapshot editor workflow could be shortened to the two rules an agent needs: label snapshot rows in prose and keep them in the chart's row grammar.
Compress the 'Unknown props preserve the original directive and data through nearby rich edits...' passage in the error section to the actionable core (never author bm-problem recovery nodes; check names and props against the reference), moving editor-repair mechanics detail to the reference file.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with genuinely non-obvious Comark rules (directive syntax, query grammar, error codes) and never explains basics Claude already knows, but a few passages could be tightened — notably the snapshot-body paragraph and the "Unknown props preserve the original directive... / reviewed agent replacement and undo" prose — placing it between the 4 and 5 anchors. | 4 / 5 |
Actionability | Guidance is fully executable: copy-paste-ready component examples, an exact query pipeline grammar ("notes | where type == decision and status == open | count"), a concrete validation tool call (bm_read(identifier="<note>", view="text", project="<project>")), and a per-code error table with specific fixes. | 5 / 5 |
Workflow Clarity | Sections form a clear sequence (pick a component → write → validate live views → edit → handle errors) with an explicit validation checkpoint ("Read it back after writing a live view and confirm the view has rows before you state a number in prose"), feedback loops (Component problems listed in bm_write/bm_edit results to fix right away with bm_edit), and a closing five-point checklist. | 5 / 5 |
Progressive Disclosure | The body inlines only the 12 most common components and clearly signals the verified, one-level-deep reference — "The full vocabulary, every prop, and every data grammar are in [references/components.md](references/components.md). Read it before using a component you have not used before" — with the 740-line bundle file confirmed present and containing no nested document references. | 5 / 5 |
Total | 19 / 20 Passed |