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.
The body is a highly actionable API reference with complete, copy-paste-ready code for every feature, and the workflow guidance that exists (codegen, lifecycle, mistakes) is clear and well-sequenced. Its weaknesses are redundancy from repeating the same examples and close-pattern three times over, and a monolithic single-file structure with no progressive disclosure despite the content volume clearly warranting reference files.
Suggestions
Deduplicate code: show the base weather server once and show only the stdio/middleware deltas in the variants, cutting ~60 repeated lines.
Split long peripheral sections (MCP Apps client-side bridge, OAuth redirect-flow caveats, lifecycle variants) into references/ files linked one level deep, and fix the docs/mcp/apps.md pointer to a real bundle file.
Add a verification step to the Codegen CLI workflow (e.g. re-run generate when servers change and let missing keys be a compile error) to close the workflow-clarity gap.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Prose is mostly telegraphic and documents non-obvious package facts Claude cannot know, but there is notable redundancy: the base weather-server example is repeated nearly verbatim in the HTTP and stdio hosting sections (~20 identical lines), the close-in-middleware pattern appears three times (Lifecycle, Complete server-route example, Common Mistakes), and "Mount handleMcp on GET, POST, and DELETE" is stated twice. Not 4: the repetition is more than minor trimming — several full code blocks could be collapsed or referenced. | 3 / 5 |
Actionability | Every section ships complete, executable TypeScript with imports, realistic config objects, and exact subpath imports (e.g. '@tanstack/ai-mcp/stdio', '@tanstack/ai-mcp/server'), plus runnable CLI commands (npx @tanstack/ai-mcp generate) and wrong/correct pairs in Common Mistakes. Not 4: coverage spans all common cases — transports, both auth levels, tool policy, lifecycle variants, error classes — copy-paste ready throughout. | 5 / 5 |
Workflow Clarity | Multi-step processes are well sequenced: Codegen CLI gives a numbered 1-2-3 workflow (create mcp.config.ts, run generate, use types), lifecycle guidance is explicit with three ordered options and a when-to-use decision table, and Common Mistakes are severity-graded with fixes. Not 5: the MCP input-request interrupt flow is split across two sections without an explicit ordered sequence or resume checkpoint, and there are no verification checkpoints (e.g. how to confirm a generated file is current). Not 3: sequence and checkpoints are largely present. | 4 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent), and the body is a ~1,280-line monolith with clearly separable material inlined: MCP Apps client-side React detail, three full lifecycle code variants, and OAuth redirect-flow caveats would all fit better in one-level-deep reference files. References are also shaky — "See docs/mcp/apps.md" points at the source library, not a file in this skill's bundle. Not 4: significant content that should be split out is inline and the apps reference is not clearly signaled as external to the bundle. | 3 / 5 |
Total | 15 / 20 Passed |