Content
71%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 instructional skill body with a strong reference-routing table, concrete commands, and clear decision sequences. The main cost is redundancy — the doc-lookup workflow is explained three times across sections and repeated links inflate token usage without adding guidance.
Suggestions
Merge 'Development workflow' into 'Priority order for writing code' — they cover the same lookup sequence; keep one canonical numbered workflow.
Consolidate the three 'don't trust your knowledge' sections (Critical, Priority order preamble, When you see errors) into one, and link embedded-docs.md once from the routing table plus one workflow step instead of five times.
Give the concrete invocation for `scripts/provider-registry.mjs` (e.g., `node scripts/provider-registry.mjs <args>`) instead of 'run this'.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient and imperative, but there is real redundancy: the 'Development workflow' section restates the 'Prerequisites' and 'Priority order' sections (re-explaining the embedded-docs vs. remote-docs split), `references/embedded-docs.md` is linked five separate times, and 'don't trust internal knowledge' guidance appears in three sections ('Critical: Do not trust internal knowledge', 'Never write code without checking current docs first', 'When you see errors'). This is more than the 'minor instances' of a 4 but nowhere near the heavy padding of a 2. | 3 / 5 |
Actionability | Concrete, mostly executable guidance throughout: `ls node_modules/@mastra/`, `npm run dev`, `npx skills add mastra-ai/skills --skill mastra-factory --agent <agent> -g`, specific error signatures ('Property X does not exist on type Y'), and a named script to run. Minor gap: 'run this' for `scripts/provider-registry.mjs` without the actual invocation command keeps it from a 5. | 4 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced ('Priority order' 1→2→3, 'Development workflow' 4 steps) and the 'When you see errors' section provides a genuine feedback loop (check common-errors → verify current API → don't assume user mistake). Not a 5 because no explicit validation checkpoints exist — e.g., verifying the `mastra api trace query` command exists before use is stated but there is no verify-output step in the development workflow. | 4 / 5 |
Progressive Disclosure | A routing table maps user questions to each of the 10 reference files (all verified present in the bundle) with a purpose summary per row, plus the script is listed with its role. All references are one level deep, clearly signaled, and the body stays a lean overview that delegates detail to those files. | 5 / 5 |
Total | 16 / 20 Passed |