Content
75%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 highly actionable, well-sequenced debugging runbook with executable CLI commands and expected-outcome checkpoints for every step. The main costs are repetition (tag-granularity and PPR guidance restated in multiple sections) and small structural blemishes — a dangling "curl above" reference and a misplaced inspection section.
Suggestions
Consolidate the tag-granularity/blast-radius guidance (currently in Key concepts, Time-based vs. tag-based revalidation, and Reducing ISR cost) into one section and cross-reference it elsewhere.
Fix the "per-path header inspection (`curl` above)" reference — the curl command actually appears later in the document — and move "Inspect one path" into the "Investigating cache issues" section where it is used.
Consider moving the cacheReason and ppr_state lookup tables into a references/ file so the main body stays a lean overview, keeping the inline examples that drive the workflow.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with Vercel-specific operational knowledge Claude won't reliably know (cacheReason semantics, 8 KB ISR billing units, "--limit is per time bucket", internal-only headers), but it repeats itself: tag-granularity advice ("prefer granular tags (product-${id})") appears in Key concepts, Time-based vs. tag-based revalidation, and Reducing ISR cost; the "no holes = plain ISR" point appears in both Key concepts and the FAQ; and "needs Observability Plus or a Priority project" is stated twice. Mostly efficient but could be tightened — no generic-concept padding, so not a 2. | 3 / 5 |
Actionability | Fully copy-paste ready commands throughout: concrete `vercel metrics` invocations with real filter/group-by flags (e.g. `-f "cache_result:MISS AND path_type:prerender" --group-by request_path`), a zero-dependency `curl -sSI ... | grep` inspection one-liner, jq examples for `vercel logs --json`, and interpretation thresholds ("near or below ~1 means you regenerate about as fast as the page is read"). Specific examples cover the common debugging cases. | 5 / 5 |
Workflow Clarity | The diagnostic flow is explicitly sequenced with transitions ("Start here for an overall picture" → "Once you know hit rate" → "Before tuning headers..."), Step 1/Step 2 structure, and "What to expect" checkpoints that act as validation against expected outcomes. Two minor gaps keep it from a 5: the Cache hit rate section references "per-path header inspection (`curl` above)" but the curl section appears later in the document (a dangling forward reference), and the "Inspect one path" section is oddly placed under "Reducing ISR cost" rather than in the investigation flow. Operations are read-only diagnostics, so the destructive/batch validation cap does not apply. | 4 / 5 |
Progressive Disclosure | No bundle files exist (no references/, scripts/, or assets/), so everything lives in a single ~215-line SKILL.md. Structure is good: clear section headers, well-formed lookup tables, a Related skills section, and a one-level References list of external Vercel doc links. The large reference tables (eleven cacheReason values, three ppr_state values) could arguably be split into a references/ file to keep the main body lean, and "Inspect one path" is misplaced under "Reducing ISR cost" — minor organization gaps consistent with a 4. | 4 / 5 |
Total | 16 / 20 Passed |