Content
67%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 well-structured, code-heavy reference with strong actionability and a genuinely good conditional-reference mechanism. The main costs are token bloat from redundant and trivial examples that belong in reference files, and a progressive-disclosure section that points at bundle files that are not actually present.
Suggestions
Trim the six overlapping use-case examples down to two or three representative ones and move the rest (plus the trivial "Return Types" section) into `references/advanced-patterns.md` to cut the body's token footprint.
Ship the two referenced files (`references/advanced-patterns.md`, `references/debugging.md`) or remove the "When to Load References" section — the load triggers currently point at files that don't exist in the bundle.
Replace the undefined `parseSchemaToTypes(schema)` call in the Code Generation example with a complete, runnable implementation, and add a short post-build verification step (e.g. inspecting the inlined output in `dist/`).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Sections are individually lean and code-first, but the ~310-line body carries redundancy: six similar use-case examples (env, git, embed, constants, files, codegen), a trivial "Return Types" section demonstrating `getString()`/`getNumber()`, and an `isDev()`/`randomId()` block showing concepts Claude already knows. Not anchor 2 (not padded prose), but clearly tightenable toward references. | 3 / 5 |
Actionability | Mostly executable, copy-paste-ready guidance: complete macro files, the exact import attribute syntax, and the `bun build src/index.ts --outdir=dist` command. Below 5 due to minor gaps — the codegen example calls an undefined `parseSchemaToTypes(schema)` and `formatDate` relies on an unshown `as any` cast — making some examples pseudocode-adjacent. | 4 / 5 |
Workflow Clarity | Quick Start gives an unambiguous path (write macro file, import with `{ type: "macro" }`, run `bun build`), and the "Common Errors" table plus "Error Handling" and "Debugging Macros" sections provide recovery guidance for failures. Macros are not destructive/batch operations, so no validation cap applies; below 5 because there is no explicit verify-the-inlined-output step after a build. | 4 / 5 |
Progressive Disclosure | Good structure: clear section headers throughout, and a dedicated "When to Load References" section giving explicit load triggers for two one-level-deep references. Below 5 because the referenced files (`references/advanced-patterns.md`, `references/debugging.md`) do not exist in the bundle, and the long inline use-case catalog is content that could itself be split into those references. | 4 / 5 |
Total | 15 / 20 Passed |