@skill-graph/cli 0.5.6

package/marketplace/skills/microcopy/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: microcopy
+description: "Use when writing or reviewing functional UI text: button labels, empty states, tooltips, dialogs, placeholders, loading/progress messages, toasts, inline validation, permission copy, or onboarding steps. Covers interface-copy patterns such as verb-first action labels, acknowledge-explain-guide empty states, one-sentence tooltips, consequence-first confirmations, progressive loading language, and blur/fix validation messages. Do NOT use for marketing persuasion, documentation prose/guide structure, feedback-state staging, or general linguistic rationale behind wording."
+license: MIT
+compatibility: "Stack-agnostic UX-writing patterns. The button-label, empty-state, tooltip, dialog, loading, validation, and toast rules apply to any web, mobile, or desktop UI; example product copy uses generic e-commerce framings (storefront, fulfillment partner, orders) — substitute the equivalents from your own product domain."
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"design\",\"domain\":\"design/ux\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-06\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-06\\\\\\\"}\",\"eval_artifacts\":\"present\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"button label microcopy\\\\\\\",\\\\\\\"empty-state copy\\\\\\\",\\\\\\\"tooltip text rule\\\\\\\",\\\\\\\"confirmation dialog wording\\\\\\\",\\\\\\\"inline validation message\\\\\\\",\\\\\\\"toast notification copy\\\\\\\",\\\\\\\"placeholder text rule\\\\\\\",\\\\\\\"loading-state messaging\\\\\\\",\\\\\\\"functional UI text\\\\\\\",\\\\\\\"ux writing patterns\\\\\\\",\\\\\\\"destructive-action confirmation copy\\\\\\\",\\\\\\\"permission request copy\\\\\\\",\\\\\\\"onboarding step copy\\\\\\\",\\\\\\\"microcopy verb-first button\\\\\\\",\\\\\\\"acknowledge-explain-guide empty state\\\\\\\",\\\\\\\"blame-free toast wording\\\\\\\"]\",\"examples\":\"[\\\\\\\"rewrite this button label so it names the actual action instead of saying Submit\\\\\\\",\\\\\\\"what should the empty state say when a user has no orders yet?\\\\\\\",\\\\\\\"draft tooltip text for a production-cost field that explains what it means in one sentence\\\\\\\",\\\\\\\"this destructive confirmation dialog says OK — what should the button label be instead?\\\\\\\",\\\\\\\"the inline validation message says Invalid input — make it specific and actionable\\\\\\\",\\\\\\\"draft a toast message for a successful order export with undo\\\\\\\",\\\\\\\"what should the loading state say when a sync takes longer than 10 seconds?\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"write the marketing headline for the pricing page\\\\\\\",\\\\\\\"review this WCAG 2.2 contrast violation on the dashboard\\\\\\\",\\\\\\\"explain the morphology rule behind verb-first function names\\\\\\\",\\\\\\\"restructure this help-center article into a tutorial\\\\\\\",\\\\\\\"decide the kebab-case format for this new CSS class\\\\\\\",\\\\\\\"rename this React component across all call-sites\\\\\\\"]\",\"relations\":\"{\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"linguistics\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"linguistics owns the underlying language rules (morphology, polysemy, audience register, blame-free framing as a general principle); microcopy owns the specific UI-text patterns where those rules apply (button label rule, empty-state structure, tooltip rule, confirmation-dialog rule) — the same 'rewrite this UI text' prompt routes by whether the user wants the linguistic rationale or the concrete UX-writing pattern\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"a11y\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"a11y owns the accessibility contracts that govern how copy is announced (aria-live regions, aria-label fallbacks, screen-reader semantics); microcopy owns the words themselves — the same 'fix this UI text' prompt routes by whether the trigger is accessibility compliance or copy quality\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"interaction-feedback owns when, where, and how feedback states appear; microcopy owns the words inside those states\\\\\\\"}],\\\\\\\"related\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"task-analysis\\\\\\\",\\\\\\\"intent-recognition\\\\\\\",\\\\\\\"interaction-feedback\\\\\\\",\\\\\\\"form-ux-architecture\\\\\\\"],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"linguistics\\\\\\\",\\\\\\\"a11y\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":365,\\\\\\\"review_cadence\\\\\\\":\\\\\\\"quarterly\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/microcopy/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/microcopy/SKILL.md
+---
+
+# Microcopy
+
+## Coverage
+
+Functional UI text patterns across all interactive surfaces:
+
+- **Button labels** — verb-first, specific action, max 3 words; never generic ("Submit", "OK", "Yes", "Continue")
+- **Empty states** — three-part structure: acknowledge → explain → guide, with one primary action
+- **Tooltips** — one sentence, no terminal period, answers "what is this?"
+- **Confirmation dialogs** — state the consequence first, name the action in the button, always provide an escape
+- **Placeholder text** — example format not instruction; never the only label for a field
+- **Loading and progress messages** — progressive disclosure: nothing → spinner → skeleton → message → reassurance, by elapsed time
+- **Error / success / warning messages** — three-part What → Why → What-to-do structure with blame-free framing
+- **Inline form-validation messages** — appear on blur, disappear on fix, specific not generic
+- **Toast / snackbar messages** — action plus context, undo for reversible actions, auto-dismiss after 5 seconds, max 2 lines
+- **Permission request copy** — explain *why* before asking
+- **Onboarding step copy** — one action per step, progressive disclosure, time-honest
+
+## Philosophy
+
+Microcopy is the most-read, least-reviewed text in any application. A user may never read the docs, skip the onboarding, and ignore the marketing — but they will read the button label before clicking it. They will read the error message when something fails. They will read the empty state when they first arrive. These micro-moments determine whether the user feels confident or confused, and they compound across every interaction.
+
+The failure mode is predictable: developers write placeholder microcopy during implementation ("Click here", "Error occurred", "No data"), it ships because nobody reviews it, and it stays forever. Agents make it worse — they default to verbose, hedged, generic text ("An error has occurred while processing your request. Please try again later.") when users need short, specific, actionable text ("Payment failed — check your card number.").
+
+This skill exists because microcopy quality is structurally unowned in most projects. Marketing copy has a copywriter. Documentation has a tech writer. Naming has a convention. But nobody owns the words *inside* the working interface — the button that says "Submit" when it should say "Save Changes", the empty state that says "No items" when it should say "No orders yet — connect your storefront to start syncing." The cost of that gap is paid one click at a time.
+
+> **Scope boundary:** microcopy writes FUNCTIONAL UI text — button labels, error messages, empty states, tooltips, confirmation dialogs. It does NOT cover marketing copy or content-strategy decisions; those belong to dedicated copywriting and content-strategy skills.
+
+---
+
+## 1. Button Labels
+
+Buttons are the primary action interface. Every button label is a micro-contract: it promises what will happen when clicked.
+
+**Rules:**
+
+1. **Verb-first**: "Save Changes", "Connect Storefront", "Export CSV" — not "Changes", "Storefront", "CSV"
+2. **Specific action**: "Delete Order" not "Delete", "Send Invitation" not "Send"
+3. **Max 3 words** for primary actions: "Save", "Save Changes", "Save and Close"
+4. **Match the consequence**: if clicking deletes data, the button says "Delete" not "OK". If it sends an email, it says "Send Email" not "Confirm"
+5. **Avoid generic labels**: "Submit", "OK", "Yes", "Continue" are almost always wrong — name the actual action
+6. **Cancel is always available**: destructive dialogs need both the action ("Delete Order") and the escape ("Cancel")
+
+**Button label patterns by context:**
+
+| Context | Bad | Good |
+| --- | --- | --- |
+| Save form | Submit | Save Changes |
+| Delete item | OK | Delete Order |
+| Connect platform | Continue | Connect Storefront |
+| Export data | Download | Export as CSV |
+| Confirm send | Yes | Send Invitation |
+| Dismiss dialog | Close | Cancel |
+
+---
+
+## 2. Empty States
+
+Empty states are the first impression for every new feature. They must acknowledge, explain, and guide.
+
+**Three-part structure:**
+
+1. **Acknowledge** — "No orders yet" — confirm the user is in the right place and the emptiness is expected
+2. **Explain** — "Orders will appear here once your storefront syncs" — tell them why it's empty and when it won't be
+3. **Guide** — "Connect Storefront" (button) — give them the action that fills the empty state
+
+**Rules:**
+
+- Never just "No data" or "Nothing to show" — this is a dead end
+- Use "yet" to imply future content: "No orders yet" vs "No orders"
+- Include one primary action button that resolves the empty state
+- For filtered empty states: "No orders match your filters" + "Clear filters" button
+- For error empty states: "Could not load orders" + "Try again" button + brief explanation
+
+**Common empty-state patterns:**
+
+| Surface | Message | Action |
+| --- | --- | --- |
+| Orders table (new user) | No orders yet | Connect Storefront |
+| Orders table (filtered) | No orders match these filters | Clear filters |
+| Dashboard (no data) | Connect a storefront to see your profits | Get Started |
+| Product list (empty) | No products synced yet | Sync Products |
+
+---
+
+## 3. Tooltips
+
+Tooltips answer one question: "What is this?"
+
+**Rules:**
+
+- One sentence maximum, no period at the end
+- Answer "what is this?" or "why would I use this?" — not "how does this work?"
+- Never repeat the label the tooltip is attached to
+- No links in tooltips (they disappear on mouseout)
+- Use sentence case for the first word only
+- Appear on hover after 300ms delay, dismiss on mouseout
+
+**Examples:**
+
+- Production-cost field: "Cost of goods sold, including production and shipping to your fulfillment center"
+- Confidence badge: "How complete the profit calculation is for this order"
+- Sync status icon: "Last synced 5 minutes ago from your storefront"
+
+---
+
+## 4. Confirmation Dialogs
+
+Confirmation dialogs exist for one reason: preventing irreversible mistakes.
+
+**Rules:**
+
+1. **State the consequence first**: "This will permanently delete 3 orders and their associated profit data."
+2. **Name the action in the button**: "Delete 3 Orders" not "Confirm" or "OK"
+3. **Provide the escape**: "Cancel" button, always present
+4. **No double negatives**: "Don't cancel" is never the right label
+5. **Include the count**: "Delete 3 orders" not "Delete selected orders"
+6. **Distinguish destructive from reversible**: red button + explicit "permanently" for destructive; normal button for reversible
+
+---
+
+## 5. Error Messages
+
+Error messages are the most important microcopy in the application. When something fails, the user needs clarity, not apology.
+
+**Three-part structure:**
+
+1. **What happened**: "Payment failed" — state the failure clearly
+2. **Why**: "Your card was declined" — give the specific reason if known
+3. **What to do**: "Check your card details or try a different payment method" — actionable next step
+
+**Rules:**
+
+- Never "An error occurred" — say *what* errored
+- Never "Please try again later" — say *what* to try or *when* later is
+- Blame-free framing: "We couldn't sync your orders" not "You have a sync error"
+- Include error codes only in technical contexts, never in user-facing messages
+- For transient errors: "Sync paused — retrying automatically" with a progress indicator
+
+The general blame-free / What → Why → What-to-do framing is the linguistic rule (see `linguistics`); microcopy applies it specifically to in-product error toasts, banners, and inline messages.
+
+---
+
+## 6. Loading and Progress
+
+Users tolerate waiting when they understand what's happening.
+
+**Progressive disclosure by elapsed time:**
+
+- **0 – 300 ms**: show nothing (the action feels instant)
+- **300 ms – 2 s**: show spinner or skeleton (brief acknowledgment)
+- **2 – 10 s**: show message ("Syncing your orders from your storefront…")
+- **10 s+**: show progress ("Syncing orders… 47 of 312")
+- **30 s+**: show reassurance ("This may take a few minutes for large stores. You can leave this page.")
+
+---
+
+## 7. Inline Validation Messages
+
+Validation messages appear at the field level, not the form level.
+
+**Rules:**
+
+- Appear on blur (not on keystroke — that's hostile)
+- Disappear as soon as the user fixes the input
+- Specific, not generic: "Email must include @" not "Invalid input"
+- Placed below the field, not in an alert box
+- Red text + icon for errors, green for success (with non-color indicator for accessibility)
+- Never use exclamation marks in validation messages
+
+---
+
+## 8. Toast / Snackbar Messages
+
+Toasts confirm completed actions. They are the UI's "done" signal.
+
+**Rules:**
+
+- Action + context: "Order #1234 deleted" not "Item deleted"
+- Include undo for reversible actions: "Order archived. Undo"
+- Auto-dismiss after 5 seconds (configurable for actions with undo)
+- Max 2 lines of text
+- Stack from bottom, newest on top
+- Never use toasts for errors — errors need persistent, in-context display
+
+---
+
+## Evals
+
+This skill ships a comprehension-eval artifact at [`examples/evals/microcopy.json`](https://github.com/jacob-balslev/skill-graph/blob/main/examples/evals/microcopy.json). The checklist below is the authoring gate for functional UI text; the eval file is the grader surface.
+
+## Verification
+
+After writing or reviewing UI text, verify:
+
+- [ ] Button labels are verb-first and name the actual action (no "Submit", "OK", "Yes", "Continue" alone)
+- [ ] Empty states acknowledge → explain → guide, with a real next-step button
+- [ ] Tooltips are one sentence, no terminal period, and answer "what is this?"
+- [ ] Confirmation dialogs state the consequence first and name the action in the button (with a Cancel escape)
+- [ ] Placeholder text is an example format, not the only label
+- [ ] Loading messages follow progressive disclosure by elapsed time, not a single state
+- [ ] Error messages follow What → Why → What-to-do, blame-free, with a specific action
+- [ ] Inline validation appears on blur and disappears on fix; messages are specific, not generic
+- [ ] Toasts include action + context and an undo path for reversible actions
+- [ ] Functional UI text stays inside the interface — does not drift into marketing or documentation territory
+
+## Do NOT Use When
+
+| Instead, use | Why |
+| --- | --- |
+| `linguistics` | The user wants the underlying linguistic rule (morphology, polysemy, register), not the specific UI-text pattern. Linguistics owns the *why*; microcopy owns the *what to write*. |
+| `documentation` | Writing or restructuring long-form prose for guides, tutorials, reference docs, or help-center articles. Documentation owns doc architecture and prose; microcopy owns in-product UI text. |
+| `a11y` | Auditing UI text for screen-reader announcement, aria-live behavior, or color-contrast compliance. A11y owns the accessibility contracts; microcopy owns the words. |
+| `naming-conventions` | Deciding the casing format for an artifact kind (kebab vs camel vs snake). Naming-conventions is for code identifiers, not user-facing UI strings. |
+| `intent-recognition` | Disambiguating a user's intent from an ambiguous prompt. Intent-recognition is upstream of any UI; microcopy is the words the UI uses to respond. |
+| (a copywriting skill) | Marketing headlines, pricing copy, landing-page persuasion, brand-voice work. Copywriting owns persuasive product surfaces; microcopy owns functional in-product text. |
+| (a content-strategy skill) | Page structure, funnel strategy, or what content belongs on each page. Content strategy is upstream of microcopy. |
+| `interaction-feedback` | When and how feedback states appear (timing, placement, persistence, recovery). Interaction-feedback owns the staging; microcopy owns the words inside the staged element. |

package/marketplace/skills/middleware-patterns/SKILL.md

@@ -0,0 +1,363 @@
+---
+name: middleware-patterns
+description: "Use when designing or reviewing Next.js middleware (`middleware.ts`): cross-cutting request/response transforms before route resolution, Edge Runtime constraints, `matcher` config, `NextRequest`/`NextResponse` API, the four response shapes (next/rewrite/redirect/direct), canonical patterns (auth gate, locale routing, A/B testing, header injection, geo-routing, bot blocking), and the design rule that middleware is for cross-cutting concerns across many routes — never per-route business logic. Do NOT use for per-route HTTP endpoint logic (use route-handler-design), Server Action mutations (use server-actions-design), abstract HTTP semantics (use http-semantics), CSP and hardening (use security-fundamentals), or the cross-cutting streaming model (use streaming-architecture)."
+license: MIT
+allowed-tools: Read Grep
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"engineering\",\"domain\":\"engineering/frontend\",\"scope\":\"reference\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-05-17\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-17\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"Next.js middleware\\\\\\\",\\\\\\\"middleware.ts file\\\\\\\",\\\\\\\"NextRequest NextResponse\\\\\\\",\\\\\\\"matcher config middleware\\\\\\\",\\\\\\\"Edge Runtime constraints\\\\\\\",\\\\\\\"NextResponse.redirect rewrite next\\\\\\\",\\\\\\\"auth check before route\\\\\\\",\\\\\\\"locale routing i18n middleware\\\\\\\",\\\\\\\"A/B testing variant rewrite\\\\\\\",\\\\\\\"CSP nonce middleware\\\\\\\",\\\\\\\"geo-routing X-Vercel-IP-Country\\\\\\\",\\\\\\\"request header injection\\\\\\\",\\\\\\\"bot blocking middleware\\\\\\\",\\\\\\\"middleware cookie set\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do I redirect unauthenticated users to login in Next.js\\\\\\\",\\\\\\\"how do I run code before every request in Next.js\\\\\\\",\\\\\\\"how do I set security headers globally in Next.js\\\\\\\",\\\\\\\"how do I do locale routing in App Router\\\\\\\",\\\\\\\"how do I do an A/B test with rewrites\\\\\\\",\\\\\\\"why does my middleware run on static assets\\\\\\\",\\\\\\\"can middleware do a database query\\\\\\\",\\\\\\\"how do I generate a CSP nonce per request\\\\\\\"]\",\"examples\":\"[\\\\\\\"design middleware that redirects unauthenticated users to /login while letting public routes through, configured via a matcher\\\\\\\",\\\\\\\"add a middleware that generates a per-request CSP nonce and injects it into both the request and response headers\\\\\\\",\\\\\\\"implement locale routing that detects Accept-Language and rewrites /about to /en/about for new visitors\\\\\\\",\\\\\\\"add bot blocking that returns 403 for known scraper user-agents while letting search-engine bots through\\\\\\\",\\\\\\\"tune a middleware that runs on every request down to 5ms so it stops adding latency to image fetches\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"implement a /api/posts POST endpoint (use route-handler-design)\\\\\\\",\\\\\\\"implement a delete-comment mutation triggered from a form button (use server-actions-design)\\\\\\\",\\\\\\\"explain what an HTTP 308 means vs 307 (use http-semantics)\\\\\\\",\\\\\\\"design the full CSP policy and the rest of the security-header strategy (use security-fundamentals)\\\\\\\",\\\\\\\"design a long-lived SSE stream from middleware (use streaming-architecture)\\\\\\\",\\\\\\\"design the CSP policy, threat model, or OWASP audit for a system (use security-fundamentals)\\\\\\\",\\\\\\\"decide what an HTTP method, status code, or header should mean per RFC 9110 (use http-semantics)\\\\\\\",\\\\\\\"design signature verification, idempotency, or retry semantics for vendor webhooks (use webhook-integration)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"route-handler-design\\\\\\\",\\\\\\\"server-actions-design\\\\\\\",\\\\\\\"http-semantics\\\\\\\",\\\\\\\"security-fundamentals\\\\\\\",\\\\\\\"server-components-design\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"webhook-integration\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"route-handler-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"middleware runs once before route resolution and applies to many routes via a matcher; route-handler-design runs for one route and one method after route resolution. Middleware owns the cross-cutting layer (auth gate, locale rewrite, header injection); route handlers own the per-route logic. They compose: middleware passes through to the handler, the handler executes, the response flows back.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"server-actions-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"server-actions-design owns the internal-mutation surface invoked from the app's own UI; middleware is the cross-cutting request preprocessor that runs before any route or action. A Server Action call passes through middleware on its way to the server.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"server-components-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"server-components-design owns the render path that produces a page; middleware runs upstream of render and can rewrite, redirect, or pass through. Middleware does not replace render; it gates and rewrites it.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"security-fundamentals\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Middleware is to a Next.js app what a building's lobby concierge is to its offices — every visitor passes through the lobby before reaching any specific floor; the concierge can check ID badges (auth gate), redirect visitors to the right elevator (locale or A/B rewrite), hand out lanyards with security policies attached (CSP nonce, request-ID header), or turn away bad-faith visitors at the door (bot block). The concierge cannot do the work of any specific office (per-route business logic) — that happens after the visitor gets off the elevator — but they enforce the rules that apply to every floor.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"Next.js middleware is a single async function exported as default from `middleware.ts` at the project root that runs on the Edge Runtime before route resolution for every request matching its `matcher` config. It receives a `NextRequest` and returns a `NextResponse` (or implicitly `NextResponse.next()`), and can do four things: pass through (`next`), rewrite to a different internal path (`rewrite`), redirect to a different URL (`redirect`), or short-circuit with a direct response. It runs once per request before any page render, Server Component fetch, Server Action, or Route Handler executes — making it the only place to apply genuinely cross-cutting concerns without per-route ceremony.\\\\\\\",\\\\\\\"mental_model\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"purpose\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"boundary\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"taxonomy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"analogy\\\\\\\":\\\\\\\"|\\\\\\\",\\\\\\\"misconception\\\\\\\":\\\\\\\"|\\\\\\\"}\",\"skill_graph_source_repo\":\"https://github.com/jacob-balslev/skill-graph\",\"skill_graph_protocol\":\"Skill Metadata Protocol v5\",\"skill_graph_project\":\"Skill Graph\",\"skill_graph_canonical_skill\":\"skills/middleware-patterns/SKILL.md\"}"
+  skill_graph_source_repo: "https://github.com/jacob-balslev/skill-graph"
+  skill_graph_protocol: Skill Metadata Protocol v4
+  skill_graph_project: Skill Graph
+  skill_graph_canonical_skill: skills/middleware-patterns/SKILL.md
+  skill_graph_export_description: shortened for Agent Skills 1024-character description limit; canonical source keeps the full routing contract
+  skill_graph_canonical_description_length: "1178"
+---
+
+# Middleware Patterns
+
+## Coverage
+
+The discipline of designing Next.js middleware: the one-file-per-project contract (`middleware.ts` at the root or under `src/`, single default export), the Edge Runtime constraints that govern what code can and cannot run there, the `matcher` config that filters which paths trigger middleware, the `NextRequest` / `NextResponse` API surface (cookies, geo, IP, headers), the four response shapes (`next`, `rewrite`, `redirect`, direct response), the canonical pattern library (authentication gate, locale routing, A/B testing, security header injection, geo-routing, bot blocking, request-id correlation), the performance discipline that every matched request pays the cost, and the central design rule: middleware is for cross-cutting concerns that apply across many routes — never for per-route business logic.
+
+## Philosophy
+
+The Pages Router's request lifecycle was: server hits `getServerSideProps`, which returns props, which render the page. The App Router added more layers (Server Components, Server Actions, Route Handlers), but kept one thing constant — they all run *after* the route is resolved.
+
+Middleware runs *before*. It is the only layer where you can intercept a request without knowing which route it will eventually hit. That makes it the right home for concerns that apply across the entire app or large subsets of it: "every request needs an auth check", "every request needs a request-id header", "every request to `/admin/*` needs a role check", "every page needs a CSP nonce".
+
+The architectural trade is **breadth for power**. Middleware:
+
+- Runs on the Edge Runtime — limited APIs, no Node-specific dependencies, no large packages.
+- Runs on every matched request — performance ceiling matters because the cost multiplies.
+- Has no per-route knowledge until the rewrite/redirect resolves — cannot read route-specific params or query the database for that route's data.
+- Cannot read the response body — it sits in front of the response, not over it.
+
+In exchange, it can shape the entire request/response edge in a single place. Done well, it removes ceremony from every route; done badly, it adds latency to every request and concentrates business logic in a file that's hard to test.
+
+**The discipline of middleware is to keep it small, fast, and cross-cutting.** When a piece of logic only applies to one route, it does not belong here. When it requires a database lookup that adds 50ms, it does not belong here. When the code is hard to reason about, it definitely does not belong here.
+
+## The File Contract
+
+```ts
+// middleware.ts (project root, or src/ if using src layout)
+import { NextResponse } from 'next/server'
+import type { NextRequest } from 'next/server'
+
+export async function middleware(request: NextRequest) {
+  // ... transform or gate the request ...
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
+}
+```
+
+- **One file per project.** There is no chain of middleware files. Compose multiple concerns inside a single `middleware` function.
+- **Default export.** The named export pattern (`export async function middleware`) and the default export both work; pick one.
+- **`config.matcher`** filters which paths trigger middleware. **Critical**: the default — no matcher — runs on every single request including static assets. Always set a matcher.
+
+### Matcher syntax
+
+```ts
+export const config = {
+  matcher: [
+    '/dashboard/:path*',                                          // glob
+    '/((?!api|_next/static|_next/image|favicon.ico).*)',          // negative lookahead — everything except these
+    {
+      source: '/api/admin/:path*',
+      missing: [{ type: 'header', key: 'next-action' }],          // exclude Server Action calls
+    },
+  ],
+}
+```
+
+Matchers compile to regular expressions at build time. They cannot use runtime values. Complex negative lookaheads are common because the default-matches-everything behavior is rarely what you want — image fetches, static assets, prefetch requests, and webhook routes should usually be excluded.
+
+The biggest middleware footgun is forgetting to exclude `/_next/static` and `/_next/image`, which makes every image fetch run middleware code on the hot path.
+
+## The Four Response Shapes
+
+```ts
+import { NextResponse } from 'next/server'
+
+// 1. Pass through — let the request continue to its route
+return NextResponse.next()
+
+// 2. Rewrite — internally route to a different path; URL bar unchanged
+return NextResponse.rewrite(new URL('/en/about', request.url))
+
+// 3. Redirect — send a 30x to the browser; URL bar changes
+return NextResponse.redirect(new URL('/login', request.url))
+
+// 4. Direct response — short-circuit; return a response without hitting any route
+return new NextResponse('Forbidden', { status: 403 })
+```
+
+Choose based on what the user should see and what should change:
+
+| Goal | Use |
+|---|---|
+| Continue to the originally requested route, possibly with modified headers/cookies | `next()` (often with `.headers.set()` on the response) |
+| Serve a different route's content under the same URL (A/B test, locale variant, feature flag) | `rewrite` |
+| Send the user to a different URL (login redirect, canonical redirect, locale-detection redirect) | `redirect` |
+| Block the request entirely (rate limit hit, bot blocked, missing auth on protected API) | direct response with appropriate status |
+
+**Rewrite vs redirect** is a load-bearing distinction: rewrites are invisible to the user (the URL stays the same), redirects are visible (the URL changes and the browser does a second request). If you want the user to see they've been moved (`/old-path` → `/new-path`), redirect. If you want to keep their URL and serve different content (A/B variant, internal locale path), rewrite.
+
+## Edge Runtime Constraints
+
+Middleware runs on Edge. Things to know:
+
+| Capability | Available |
+|---|---|
+| `fetch` | ✅ |
+| Web Crypto (`crypto.subtle`, `crypto.randomUUID`) | ✅ |
+| Web Streams (`ReadableStream`, `TransformStream`) | ✅ |
+| `URL`, `URLSearchParams`, `Request`, `Response` | ✅ |
+| `setTimeout` / `setInterval` | ⚠️ best-effort, may not fire after response |
+| Node `crypto` module | ❌ |
+| Node `fs`, `child_process`, `net`, `dns` | ❌ |
+| Most npm packages that aren't pure JS | ❌ |
+| Large bundle sizes | ❌ (Vercel: ~1MB ceiling on middleware code) |
+
+Middleware code is bundled and shipped to Edge nodes globally. Cold-start is fast (~10–50ms) but the trade is a tight capability surface. Anything you import — including transitive dependencies — must be Edge-compatible. A single `import` of a Node-only package breaks the build.
+
+**Practical consequence**: don't reach for ORMs, full SDKs, or complex libraries in middleware. Hand-roll the small piece you need (decode a JWT, hash a token, parse a cookie). If the work genuinely needs Node — verifying a webhook signature with a vendor SDK, hitting a database — push it down into a Route Handler or Server Action instead.
+
+## The Canonical Pattern Library
+
+### 1. Authentication gate
+
+```ts
+export async function middleware(request: NextRequest) {
+  const session = request.cookies.get('session')?.value
+  const { pathname } = request.nextUrl
+
+  const isProtected = pathname.startsWith('/dashboard') || pathname.startsWith('/admin')
+  if (isProtected && !session) {
+    const url = new URL('/login', request.url)
+    url.searchParams.set('redirectTo', pathname)
+    return NextResponse.redirect(url)
+  }
+
+  return NextResponse.next()
+}
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+}
+```
+
+The session cookie is *checked*, not *verified*. Cryptographic verification belongs inside the routes — middleware is for fast cookie presence checks. A signed-cookie verification that requires a JWT library is fine if the library is Edge-compatible; a database lookup to validate the session is not — that 50ms hits every protected page load.
+
+### 2. Locale routing
+
+```ts
+const LOCALES = ['en', 'es', 'fr', 'de']
+const DEFAULT_LOCALE = 'en'
+
+export async function middleware(request: NextRequest) {
+  const { pathname } = request.nextUrl
+  const hasLocale = LOCALES.some((l) => pathname.startsWith(`/${l}/`) || pathname === `/${l}`)
+  if (hasLocale) return NextResponse.next()
+
+  const accept = request.headers.get('accept-language') ?? ''
+  const detected = LOCALES.find((l) => accept.includes(l)) ?? DEFAULT_LOCALE
+
+  return NextResponse.redirect(new URL(`/${detected}${pathname}`, request.url))
+}
+```
+
+A first-visit user lands on `/about`, gets redirected to `/en/about`. Subsequent visits to locale-prefixed paths pass through. The redirect-once pattern keeps the URL canonical and lets the rest of the app assume locale is in the path.
+
+### 3. A/B testing via rewrite
+
+```ts
+export async function middleware(request: NextRequest) {
+  if (request.nextUrl.pathname !== '/pricing') return NextResponse.next()
+
+  let variant = request.cookies.get('pricing-variant')?.value
+  if (!variant) {
+    variant = Math.random() < 0.5 ? 'a' : 'b'
+  }
+
+  const url = new URL(`/pricing-${variant}`, request.url)
+  const response = NextResponse.rewrite(url)
+  response.cookies.set('pricing-variant', variant, { maxAge: 60 * 60 * 24 * 30 })
+  return response
+}
+```
+
+The user sees `/pricing` in their URL bar but receives `/pricing-a` or `/pricing-b`. The cookie pins their variant so subsequent visits are consistent. The rewrite preserves the canonical URL for analytics and sharing.
+
+### 4. Security header injection (with per-request CSP nonce)
+
+```ts
+export async function middleware(request: NextRequest) {
+  const nonce = Buffer.from(crypto.randomUUID()).toString('base64')
+
+  const csp = [
+    `default-src 'self'`,
+    `script-src 'self' 'nonce-${nonce}' 'strict-dynamic'`,
+    `style-src 'self' 'nonce-${nonce}'`,
+    `img-src 'self' blob: data:`,
+    `font-src 'self'`,
+    `object-src 'none'`,
+    `base-uri 'self'`,
+    `form-action 'self'`,
+    `frame-ancestors 'none'`,
+    `upgrade-insecure-requests`,
+  ].join('; ')
+
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set('x-nonce', nonce)
+  requestHeaders.set('content-security-policy', csp)
+
+  const response = NextResponse.next({ request: { headers: requestHeaders } })
+  response.headers.set('content-security-policy', csp)
+  response.headers.set('x-content-type-options', 'nosniff')
+  response.headers.set('referrer-policy', 'strict-origin-when-cross-origin')
+  response.headers.set('permissions-policy', 'camera=(), microphone=(), geolocation=()')
+  return response
+}
+```
+
+The nonce flows to the request headers (so Server Components can read it via `headers()` and inject it into `<script>` tags) and to the response headers (so the browser enforces the CSP). The policy itself is just an example; the actual rules belong to the broader security strategy in `security-fundamentals`.
+
+### 5. Geo-routing
+
+```ts
+export async function middleware(request: NextRequest) {
+  const country = request.geo?.country ?? 'US'   // populated by Vercel
+
+  if (country === 'GB' && !request.nextUrl.pathname.startsWith('/uk')) {
+    return NextResponse.redirect(new URL(`/uk${request.nextUrl.pathname}`, request.url))
+  }
+
+  return NextResponse.next()
+}
+```
+
+`request.geo` is populated by Vercel from the request's IP-derived location. On other hosts it may be undefined — read it defensively.
+
+### 6. Bot blocking
+
+```ts
+const BLOCKED_AGENTS = [/AhrefsBot/i, /SemrushBot/i, /MJ12bot/i]
+
+export async function middleware(request: NextRequest) {
+  const ua = request.headers.get('user-agent') ?? ''
+  if (BLOCKED_AGENTS.some((re) => re.test(ua))) {
+    return new NextResponse('Forbidden', { status: 403 })
+  }
+  return NextResponse.next()
+}
+```
+
+UA strings are trivially spoofable — bot blocking via user-agent works for honest crawlers but does not stop adversaries. Use this for noise reduction, not security.
+
+### 7. Request-ID correlation
+
+```ts
+export async function middleware(request: NextRequest) {
+  const requestId = request.headers.get('x-request-id') ?? crypto.randomUUID()
+  const requestHeaders = new Headers(request.headers)
+  requestHeaders.set('x-request-id', requestId)
+
+  const response = NextResponse.next({ request: { headers: requestHeaders } })
+  response.headers.set('x-request-id', requestId)
+  return response
+}
+```
+
+The request-id flows through to the route (readable via `headers()`) and back out to the client (visible in DevTools). Pair with structured logging that includes the id, and you get end-to-end traceability.
+
+## Composing Multiple Concerns
+
+There is one `middleware.ts`. Combine concerns inside it — typically in a clear order:
+
+```ts
+export async function middleware(request: NextRequest) {
+  // 1. Block bots first — fast reject
+  const ua = request.headers.get('user-agent') ?? ''
+  if (BLOCKED_AGENTS.some((re) => re.test(ua))) {
+    return new NextResponse('Forbidden', { status: 403 })
+  }
+
+  // 2. Locale detection — redirect once for first-visit users
+  const localeRedirect = applyLocaleRouting(request)
+  if (localeRedirect) return localeRedirect
+
+  // 3. Auth gate — redirect to login for protected routes
+  const authRedirect = applyAuthGate(request)
+  if (authRedirect) return authRedirect
+
+  // 4. Pass through with security headers + request-id
+  return applyHeaders(request)
+}
+```
+
+Each helper returns either a short-circuit `NextResponse` or `null` (continue). The shape is a small chain of guards; the file stays readable. When the chain grows past ~5 concerns, it's a signal that the middleware is doing too much — push something down to per-route logic or to a separate request-time hook.
+
+## Performance Discipline
+
+Every matched request pays the middleware cost. Three rules:
+
+1. **Tune the matcher.** If only `/dashboard/*` needs auth, match only `/dashboard/*`. Don't run auth checks against image fetches.
+2. **Cap the time budget.** Target <10ms p99 for middleware execution. Slow middleware degrades every page on the site.
+3. **No database calls.** A network round-trip in middleware is a tax on every request. Cache aggressively; use signed cookies that carry the data middleware needs without a lookup; defer DB checks to the route.
+
+The performance budget is invisible until you load-test the site and see middleware dominate the latency profile. Build it in from the start.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong | Fix |
+|---|---|---|
+| No matcher — middleware runs on `/_next/static`, `/_next/image`, `/favicon.ico` | Adds latency to every image fetch and static asset | Set a matcher with negative lookahead excluding `_next` paths and assets |
+| Database query in middleware | Network round-trip on every request | Use signed cookies that carry the data, or push the lookup down to the route |
+| Putting per-route business logic in middleware | Centralized file that hides the logic from the route that owns it | Move to the route; keep middleware for genuine cross-cutting |
+| Importing a Node-only package | Edge build fails | Use Edge-compatible alternatives, or move the work to a Route Handler |
+| Verifying a JWT signature against a remote JWKS endpoint without caching | Network call per request | Cache the JWKS in memory; or defer verification to the route |
+| `redirect` when `rewrite` was meant (or vice versa) | URL changes when it shouldn't, or stays the same when it should | Choose based on whether the user should see the URL change |
+| Forgetting to copy headers to the response when modifying request headers | Request-side changes invisible to client | Use `NextResponse.next({ request: { headers: ... } })` AND set the same on `response.headers` if the client needs to see them |
+| Setting cookies on the request — middleware can't modify the request cookies the client sees | Cookie set silently lost | Set cookies on the response via `response.cookies.set(...)` |
+| Running middleware on webhook routes that need raw body access | Middleware can consume the body or otherwise interfere with HMAC verification | Exclude webhook paths from the matcher |
+| Single 100-line middleware doing 8 different things | Untestable, slow, hard to reason about | Decompose into named helpers; consider whether some concerns belong per-route |
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] `config.matcher` is set and excludes `_next/static`, `_next/image`, `favicon.ico`, and any other paths that don't need middleware (typically webhooks).
+- [ ] No database queries or other I/O that adds >10ms to the request happen inside middleware.
+- [ ] All imported packages are Edge-Runtime-compatible (no Node `crypto`, `fs`, `child_process`, `net`).
+- [ ] Cookies that need to reach the client are set on the response (`response.cookies.set`), not on the request.
+- [ ] Modified request headers use `NextResponse.next({ request: { headers } })` so they flow to the route.
+- [ ] The choice between `rewrite` and `redirect` matches whether the URL should visibly change.
+- [ ] Webhook routes are excluded from the matcher to preserve raw-body access.
+- [ ] Multiple concerns are decomposed into named helpers; one concern per helper.
+- [ ] Auth checks are fast cookie/signature checks, not database lookups — deeper verification is deferred to the route.
+- [ ] Security-header injection (if used) coordinates with the broader security strategy defined in `security-fundamentals`.
+
+## Grounding Sources
+
+- Next.js docs — [Middleware](https://nextjs.org/docs/app/building-your-application/routing/middleware). The canonical reference for the `middleware.ts` convention.
+- Next.js docs — [Matcher config](https://nextjs.org/docs/app/building-your-application/routing/middleware#matcher). The path-filtering rules.
+- Vercel docs — [Edge Runtime API reference](https://vercel.com/docs/functions/runtimes/edge-runtime). The capability surface middleware runs against.
+- MDN — [Fetch API: Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response). The Web-standard interface underlying `NextRequest`/`NextResponse`.
+- RFC 9110 — [HTTP Semantics](https://datatracker.ietf.org/doc/html/rfc9110). The protocol middleware operates on — methods, status codes, headers.
+- OWASP — [Secure Headers Project](https://owasp.org/www-project-secure-headers/). The canonical reference for the security-header set middleware can inject.
+- Vercel — [Building a strict CSP with nonces in Next.js](https://nextjs.org/docs/app/building-your-application/configuring/content-security-policy). The canonical per-request nonce pattern.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Per-route HTTP endpoint logic — JSON APIs, webhook handlers, streaming responses | `route-handler-design` | Route Handlers own per-route per-method logic; middleware owns cross-cutting preprocessing. |
+| Internal mutations triggered from this app's UI | `server-actions-design` | Server Actions are the in-app mutation surface; middleware sits upstream of them but does not replace them. |
+| Understanding what each HTTP status or method means in the abstract | `http-semantics` | http-semantics owns the protocol; this skill owns honoring it in middleware. |
+| Designing the full Content Security Policy or the broader hardening discipline | `security-fundamentals` | security-fundamentals owns the policy; middleware is one delivery surface. |
+| The cross-cutting streaming model (Web Streams, SSE, backpressure) | `streaming-architecture` | Middleware can set headers for streamed responses but does not author the streaming logic. |
+| The serialization/directive mechanics of `'use client'` and `'use server'` | `client-server-boundary` | Different boundary — that's the bundler component split, not the HTTP request edge. |
+| The full webhook reliability story (HMAC verification, idempotency, retries) | `webhook-integration` | Webhook routes should generally be excluded from middleware; their handler owns the reliability discipline. |