Content
57%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 delivers exceptional actionability — dense, executable TypeScript patterns with exact option names, error classes, and model IDs — but it is a ~1,267-line monolithic reference that buries per-provider minutiae, pricing, and duplicated rules in SKILL.md instead of splitting them into the nearly empty references/ directory. Organization is by topic with no task-oriented workflow or validation checkpoint for the codegen task it supports.
Suggestions
Split per-provider reference detail (Sampling Parameters, DeepSeek Notes, Meta Muse, AWS Bedrock, GPT-6 Astra/sessions, OpenAI Decisions) into files under references/ and keep short decision-oriented summaries with clearly signaled links in SKILL.md, mirroring the existing ax-typesafe.md pattern.
Deduplicate the Bedrock/GPT-6 rules that currently appear in three sections (Quick Setup, AWS Bedrock, GPT-6 Astra) and move time-sensitive pricing and model-generation details (Haiku 5.5 and GPT-6.1 Sol token rates) out of the always-loaded body into a versioned reference file.
Add a brief task-oriented workflow at the top (identify the provider and capability → confirm the profile name via axAIProfiles()/axGetAIProfile() → generate the ai() setup → check the result against 'Critical Rules' and 'Do Not Generate') so the codegen task has an explicit sequence with a validation checkpoint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~1,267-line body inlines per-model minutiae (Haiku 5.5 pricing "$0.10/$0.50 through 100K input tokens", GPT-6.1 Sol token rates), repeats Bedrock/GPT-6 rules across the "Quick Setup", "AWS Bedrock", and "GPT-6 Astra" sections, and restates generated-package parity notes many times. It is not a 1 because it never explains concepts Claude already knows and the prose is dense rather than padded, but 'noticeably verbose; several unnecessary ... padded sections' fits better than 'mostly efficient'. | 2 / 5 |
Actionability | Code is copy-paste ready with imports for the common cases ("import { ai } from '@ax-llm/ax'; const openai = ai({ name: 'openai', apiKey: 'sk-...' })" plus complete presets, chat, transcribe/speak, balancer, caching, and decisions examples), and guidance names exact options, error classes ("AxMediaNotSupportedError", "AxAIServiceAbortedError"), and model IDs. A few advanced snippets build on variables from earlier sections, but coverage of common cases is comprehensive, matching the fully-executable anchor. | 5 / 5 |
Workflow Clarity | The body is organized by topic rather than by task: there is no explicit sequence for the codegen workflow and no validation checkpoint (e.g., nothing instructs verifying generated code against "Critical Rules" or "Do Not Generate" after drafting). Decision guidance like "Choose the primitive by responsibility" and the "Do Not Generate" checklist exist but serve as implicit rather than explicit checkpoints, matching the 'sequence present but checkpoints missing or implicit' anchor. | 3 / 5 |
Progressive Disclosure | Section headers are clear and the one bundle reference is valid and clearly signaled ("See the [decision evidence guide](references/ax-typesafe.md#decision-evidence-and-reranking)" — the file and the 'Decision evidence and reranking' heading both exist in references/), but ~1,200 lines of per-provider/per-model reference detail (sampling rules, reasoning-effort mappings, pricing) are inlined in SKILL.md while references/ contains only a single file. This matches 'some structure ... content that should be separate is inline'. | 3 / 5 |
Total | 13 / 20 Passed |