[skills] Extend cdn-caching with per-request cache reason guidance#110
Merged
Conversation
Adds a `cache-reason` skill that explains the per-request `cacheReason` field (cold, collapsed, error, draft_mode, prerender_bypass, crawler, stale_time, stale_tag, stale_error) — why a single request was a MISS, STALE, or BYPASS. Complements `cdn-caching`, which covers aggregate hit rate and ISR cost via `vercel metrics`. Written for the public audience: all observation paths route through the dashboard Logs "Reason" row and `vercel logs --json`. The internal-only `x-vercel-cache-reason` response header (gated behind is_timing_header_visible) is explicitly flagged as not user-visible, and the skill avoids the not-yet-published /docs/caching/cache-status anchors. - New: skills/cache-reason/SKILL.md (with promptSignals + retrieval block) - vercel.md: graph reference in the caching section - README.md: skills table row + count - cdn-caching: mutual cross-link - Regenerated skill-manifest.json, skill-catalog.md, build-from-skills.manifest.json Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
Adds a new public-facing cache-reason skill to help agents explain why a single request resulted in MISS/STALE/BYPASS by using per-request logs (cacheReason), complementing the existing aggregate-focused cdn-caching skill.
Changes:
- Introduces
skills/cache-reason/SKILL.mdwith definitions for the nine canonical cache reasons and how to retrieve them via Dashboard Logs /vercel logs --json. - Wires the new skill into cross-references and the skills index (
vercel.md,README.md,skills/cdn-caching/SKILL.md). - Regenerates derived catalogs/manifests under
generated/to include the new skill.
Reviewed changes
Copilot reviewed 4 out of 7 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| vercel.md | Adds cache-reason to the caching-related skills list in the ecosystem graph. |
| skills/cdn-caching/SKILL.md | Adds a related-skill cross-link to cache-reason. |
| skills/cache-reason/SKILL.md | New skill documenting per-request cacheReason meanings + how to find them in logs. |
| README.md | Adds cache-reason to the skills table and bumps the skill count. |
| generated/skill-manifest.json | Includes the new skill entry and updates generation timestamp. |
| generated/skill-catalog.md | Adds cache-reason to the catalog/TOC and bash-pattern competition list. |
| generated/build-from-skills.manifest.json | Updates generation timestamp for the build-from-skills manifest. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
…w skill Fold the per-request cacheReason content into the existing cdn-caching skill (from #108) rather than shipping a separate cache-reason skill: - cdn-caching: add the 9-value cacheReason table (cold, collapsed, error, draft_mode, prerender_bypass, crawler, stale_time, stale_tag, stale_error) refining the x-vercel-cache status, the MISS→BYPASS displayed-status rule, and how to read cacheReason via `vercel logs --json` / the Logs "Reason" row (with the internal-only x-vercel-cache-reason header caveat). - Absorb cache-reason prompt signals + add a retrieval block so questions like "why is my page stale" / "what does stale_tag mean" route here. - Remove skills/cache-reason/ and revert its README/vercel.md wiring (back to 30 skills). - Regenerate manifest, catalog, build-from-skills manifest. Verified: 899 tests pass; the real UserPromptSubmit hook injects cdn-caching for the three cache-reason prompts and correctly ignores unrelated prompts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
shinapatel
changed the title
Condense the skill while keeping all 6 cache statuses and all 9 cache reasons (3 MISS: cold/collapsed/error, 3 BYPASS: draft_mode/ prerender_bypass/crawler, 3 STALE: stale_time/stale_tag/stale_error). Cut verbose prose, repeated metrics examples, and the FAQ; keep the two reference tables, the core metrics/logs investigation commands, and the cacheReason observation guidance. Add [cache, miss] prompt signal so MISS questions trigger. Verified: 899 tests pass; the real UserPromptSubmit hook injects cdn-caching for MISS/STALE/BYPASS/hit-rate prompts and ignores unrelated and generic-error prompts. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…d, stale_time)
The retrieval.entities list included some cache reasons but omitted
`error` (and `collapsed`, `stale_time`), making it inconsistent with the
canonical 9-reason table. List all nine reason slugs, ordered to mirror
the table.
Low-risk: the "error" token was already in the lexical index via
stale_error, and injection is gated on exact score — verified generic
error prompts ("fix this null pointer error", etc.) still inject nothing,
while MISS/STALE/BYPASS/hit-rate prompts still route to cdn-caching.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The cdn-cache docs URL was inadvertently removed while tightening the docs list; it's the canonical CDN-cache reference for this skill. Restore it alongside the caching overview, ISR, metrics, and logs links. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Prior commits had rewritten (gutted) the existing cdn-caching skill. Restore the original #108 skill verbatim and add only what's needed: - A 9-row cacheReason table under Key concepts (3 MISS: cold/collapsed/ error, 3 BYPASS: draft_mode/prerender_bypass/crawler, 3 STALE: stale_time/stale_tag/stale_error), the MISS→BYPASS displayed-status rule, and how to read cacheReason (vercel logs / Logs panel; the x-vercel-cache-reason header is internal-only). - Additive promptSignals + a retrieval block so cache-reason questions route here. Net diff vs the original: +47 / -2 lines. All existing metrics/ISR/BYPASS runbook content preserved. 899 tests pass; routing verified via the real UserPromptSubmit hook. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Previously only stale_tag was a phrase. Add the other distinctive reason slugs so pasting any of them from a log triggers the skill: stale_time, stale_error, draft_mode, prerender_bypass (+ existing stale_tag). Add 'cold cache' and 'request collapsed' to anyOf for MISS coverage. Bare cold/collapsed/error are intentionally NOT phrases — as ordinary English words they would false-match unrelated prose. Verified: "cacheReason: stale_error" and "prerender_bypass" fire cdn-caching, while "fix this null pointer error" / "handle the error case" inject nothing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
mknichel
approved these changes
Jul 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
adds the per-request cache reason (
cacheReason) to the existingcdn-cachingskill (from #108). this is a small additive change, not a new skillAdded to
cdn-cachingcacheReasontable, grouped by the status each refines:cold/collapsed/error(MISS),draft_mode/prerender_bypass/crawler(→BYPASS),stale_time/stale_tag/stale_error(STALE).MISS+draft_mode/prerender_bypass/crawler→ displayed asBYPASSrule, and how to readcacheReason(vercel logs --json/ dashboard; thex-vercel-cache-reasonheader is internal-only).retrievalblock so cache-reason questions route here.Tests run
bun run validateworkflowwarning)bun test(45 files)hooks-json-structuralRouting (real
UserPromptSubmithook):cdn-cachingvercel-cli(unaffected)Not run: live in-session model invocation (needs WezTerm for
vercel-plugin-eval).