Content
92%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 strong, well-disciplined SKILL.md body: executable commands and complete code samples, two clearly sequenced workflows with pre-checks and error-recovery loops, and clean one-level progressive disclosure into four real, well-annotated reference files. The only notable weakness is minor over-explanation in the bulk-evaluation rationale and an inline version note that would fit better in a dedicated old-patterns section.
Suggestions
Trim the prose paragraph after the `evaluate()` code examples — the avoid/prefer comments plus one sentence on `bulkDecide` already convey why `evaluate()` is preferred; move the deeper latency rationale to references/api.md under `evaluate`.
Move the adapter version guidance (`flags` 4.2.0+ by-reference vs. the older called form `vercelAdapter()`) into a short 'Version differences' or old-patterns note near the top of the reference material instead of inline in Core concepts, keeping the body version-number-free.
Add a final verification step to 'Set up the SDK' (e.g., confirm the Flags Explorer endpoint responds at `/.well-known/vercel/flags` or that a sample flag evaluates locally) so the setup workflow ends with an explicit pass/fail checkpoint.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by executable code, tables, and terse directives, but two spots over-explain: the paragraph after the `evaluate()` examples re-explains latency characteristics already shown by the avoid/prefer code comments, and the inline "Version note" carries version-specific details (`flags` 4.2.0+, called vs. by-reference adapter form) that the guidelines say belong in a dedicated old-patterns/deprecated section. These are minor trims rather than the 'some unnecessary explanation' of level 3, so level 4 fits best. | 4 / 5 |
Actionability | Nearly everything is copy-paste executable: `pnpm i flags @flags-sdk/vercel`, `vercel flags create <flag-key> --kind boolean --description "<description>"`, `vercel env pull`, complete TypeScript snippets for flag declaration, usage, discovery route, and SvelteKit handle. Common cases are covered end-to-end; the few deferred snippets (toolbar wiring, precompute middleware) point to complete code in the reference files, which is endorsed disclosure rather than a gap — so level 5 holds over level 4. | 5 / 5 |
Workflow Clarity | Both main workflows (Set up the SDK, Create a flag) are numbered with 'Before you start' checklists that detect already-done state, explicit validation (`vercel project inspect --non-interactive`, checking `.env.local` for `VERCEL_OIDCTOKEN=`, `flags.ts` existing before the discovery route), and written feedback loops ("If it reports `link_required`, run `vercel link`"; auth-error re-pull fallback; routing to the existing-flag flow when the key already exists). Destructive operations (archive/rm) are explicitly delegated to the vercel-flags skill with its checks required, so the level-3 cap does not apply; checklists + validation + error recovery match the level-5 anchor. | 5 / 5 |
Progressive Disclosure | The body is a genuine overview: framework and provider detail plus the full API reference live in four real, one-level-deep reference files (nextjs.md, sveltekit.md, providers.md, api.md), each introduced with an annotated summary of its contents, and every inline anchor link checked out against actual headings in those files. The inline summary tables (key parameters, encryption functions) keep only essentials in the body with bulk detail in references, matching the level-5 anchor's 'clear overview with well-signaled one-level-deep references'. | 5 / 5 |
Total | 19 / 20 Passed |