Content
78%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, information-dense codegen rulebook: executable examples cover every major feature and feedback/retry semantics are documented precisely. The main weakness is structure — nearly all reference-grade detail lives inline in a 650-line SKILL.md while the one bundled reference file is under-used and linked inconsistently.
Suggestions
Move the detailed Structured Outputs rule list and Chat Log/usage type definitions into a bundled reference file (or the existing references/ax-typesafe.md), keeping only a few key inline examples in SKILL.md.
Replace the GitHub URL for the ax-typesafe document in the Structured Outputs section with a link to the local references/ax-typesafe.md so the bundled file is the single consistent navigation target.
Consider bundling the remotely-linked example files (streaming.ts, best-of-n.ts, etc.) into a local examples/ directory so example navigation does not depend on external URLs.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and rule-dense ("Prefer short, modern, copyable patterns. Do not write tutorial prose unless the user explicitly asks") with virtually no explanation of concepts Claude already knows — everything is library-specific @ax-llm/ax behavior. It is not a 5 because exhaustive enumerations (the forward-option precedence lists in Caching, the generated-language status notes) and niche sections (Novel F1 evaluation, Event Targets) could be trimmed or delegated to references. | 4 / 5 |
Actionability | The Canonical Pattern and per-feature sections provide fully executable, copy-paste-ready TypeScript covering the common cases: forward, streamingForward, schema validation with zod, addAssert/addStreamingAssert, field processors, tool definitions via fn(), caching, step hooks, self-tuning, and error handling with named error classes. Remaining placeholders (bestIndex, { ... }) only mark user-supplied values, which is standard practice. | 5 / 5 |
Workflow Clarity | "Use These Defaults" followed by the "Canonical Pattern" makes the single action (generate correct AxGen code) unambiguous, and validation/retry feedback loops (schema retries, assertion correction retries, error handling rules) are documented throughout. It is not a 5 because there is no explicit guidance sequencing when to choose among addAssert, addStreamingAssert, field processors, bestOfN, and refine — the reader must infer the selection. | 4 / 5 |
Progressive Disclosure | Section headers are clear and one real bundle reference exists (references/ax-typesafe.md with a valid anchor), but it is linked only once and inconsistently — the Structured Outputs section points to the remote GitHub copy of the same document instead of the local file. Meanwhile ~600 lines of reference-grade material (18 Structured Outputs rules, Chat Log type definitions, Event Targets, session internals) are inlined in SKILL.md rather than split out, matching the "content that should be separate is inline" anchor. | 3 / 5 |
Total | 16 / 20 Passed |