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 delivers largely executable, well-organized guidance with an exemplary refusal-handling workflow, but it is a monolithic single-file skill: everything from the CLI reference to framework recipes is inlined, and Next.js/Nuxt lack the code examples the other frameworks get. Splitting detailed material into references/ files and sequencing the check command into a validation workflow would lift the two weakest dimensions.
Suggestions
Move the detailed material into references/ files (e.g. references/cli.md for the full init/check options and the refusal JSON envelope, references/frameworks.md for per-framework setup patterns) and keep SKILL.md as a lean overview with clearly signaled one-level-deep links.
Add executable setup examples for Next.js (@arkenv/nextjs) and Nuxt (@arkenv/nuxt) matching the quality of the Vite and Bun sections, since framework integration is a headline capability in the description.
Sequence the check command into the schema workflow with an explicit checkpoint (e.g. after defining/updating env.ts, run pnpm arkenv check --verify-example and fix reported diagnostics before integrating).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is code-first and assumes Claude's competence (no padding explaining what Vite, Zod, or env validation are), with one-line intros per section. Minor over-explanation could be trimmed — e.g. the 26-line refusal JSON envelope could be reduced to its key fields, and phrases like "single canonical surface" are lightly marketing-flavored — matching 'efficient; minor instances of over-explanation' (anchor 4) rather than 'every token earns its place' (anchor 5). | 4 / 5 |
Actionability | Most guidance is copy-paste ready: complete env.ts examples for ArkType, Zod, and Valibot, a consumption example, full vite.config.ts and bunfig.toml/Bun.build snippets, and concrete CLI invocations with flags. It falls short of anchor 5 because Next.js and Nuxt integration — two of the five advertised frameworks — are described in prose ("Build-time and runtime validation with automatic client/server isolation proxy") without any executable setup code, and the two-module secret recipe is sketched abstractly. | 4 / 5 |
Workflow Clarity | The agent-init workflow is well sequenced with explicit validation ("Parse the JSON settlement envelope on stdout. Success is ok: true") and a genuine feedback loop for error recovery (inspect error.code and nextActions, only re-run with --force once deliberately decided safe). It stays at anchor 4 rather than 5 because the check command is documented as options only and never sequenced into a workflow (e.g. after defining a schema, run arkenv check to validate), leaving a checkpoint implicit. | 4 / 5 |
Progressive Disclosure | The single 245-line SKILL.md has clear headers and easy navigation, but there are no bundle files at all: a full CLI reference, the complete refusal JSON envelope, and per-framework setup patterns are all inlined where references/ files would keep the overview lean. This matches 'some structure but could be better organized; content that should be separate is inline' (anchor 3); it is above anchor 2 because the inlined content is well sectioned, and below anchor 4 because nothing is split out — anchor 4 expects the bulk of detailed material in a separate file. | 3 / 5 |
Total | 15 / 20 Passed |