@skill-graph/cli 0.5.6

package/marketplace/skills/seo-strategy/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: seo-strategy
+description: "SEO implementation strategy for building pages that rank -- covering content strategy, programmatic SEO at scale, marketplace-specific SEO, and AI search optimization."
+license: MIT
+compatibility: "Markdown, Git, agent-skill runtimes"
+allowed-tools: Read Grep Bash
+metadata:
+  metadata: "{\"schema_version\":6,\"version\":\"1.0.0\",\"type\":\"capability\",\"category\":\"quality\",\"domain\":\"quality/display\",\"scope\":\"portable\",\"owner\":\"skill-graph-maintainer\",\"freshness\":\"2026-03-28\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-03-28\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"seo strategy\\\\\\\",\\\\\\\"programmatic seo\\\\\\\",\\\\\\\"content strategy\\\\\\\",\\\\\\\"comparison page\\\\\\\",\\\\\\\"alternative page\\\\\\\",\\\\\\\"schema markup\\\\\\\",\\\\\\\"structured data\\\\\\\",\\\\\\\"ai seo\\\\\\\",\\\\\\\"marketplace seo\\\\\\\",\\\\\\\"etsy seo\\\\\\\",\\\\\\\"amazon seo\\\\\\\",\\\\\\\"shopify seo\\\\\\\",\\\\\\\"product page seo\\\\\\\",\\\\\\\"e-e-a-t\\\\\\\",\\\\\\\"topical authority\\\\\\\",\\\\\\\"blog cluster\\\\\\\",\\\\\\\"ai overview\\\\\\\"]\",\"triggers\":\"[\\\\\\\"seo-strategy-skill\\\\\\\",\\\\\\\"seo-skill\\\\\\\",\\\\\\\"programmatic-seo-skill\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"keywords\\\\\\\"]}\",\"portability\":\"{\\\\\\\"readiness\\\\\\\":\\\\\\\"scripted\\\\\\\",\\\\\\\"targets\\\\\\\":[\\\\\\\"skill-md\\\\\\\"]}\",\"lifecycle\":\"{\\\\\\\"stale_after_days\\\\\\\":90,\\\\\\\"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/seo-strategy/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/seo-strategy/SKILL.md
+---
+# SEO Strategy Skill
+
+## Domain Context
+
+**What is this skill?** SEO implementation strategy for building pages that rank -- covering content strategy, programmatic SEO at scale, marketplace-specific SEO, and AI search optimization.
+
+## Key Files
+
+| File | Purpose |
+|---|---|
+| `skills/seo-strategy/references/marketplace-seo-differences.md` | See for detailed algorithm breakdowns. |
+## Philosophy
+
+Auditing finds problems; this skill builds solutions. The distinction matters because agents conflate the two and either run a diagnostic when they should be building pages, or build pages without a strategy. SEO strategy is proactive — choosing the right page types, content structures, and schema markup before traffic data exists. The marketplace-specific sections exist because applying Google SEO assumptions to Etsy or Amazon actively hurts rankings: Etsy rewards recency and conversion rate, Amazon rewards sales velocity, and neither cares about backlinks. Without this skill, agents default to generic "add keywords" advice that misses the structural decisions (programmatic templates, hub-and-spoke linking, schema choice) that create ranking power at scale.
+
+## Coverage
+
+E-commerce SEO (product page optimization, collection page strategy, cross-selling internal links), SaaS SEO (comparison/alternative pages, feature pages, documentation SEO, blog cluster strategy), marketplace SEO algorithm differences (Shopify Google organic, Etsy recency and Category Relevance Score, Amazon A9/COSMO), programmatic SEO template patterns (comparison pages, integration pages, location pages), schema markup implementation (Product, FAQ, HowTo, BreadcrumbList, SoftwareApplication), and AI search optimization (AEO, GEO, LLMO for AI Overviews and chatbot citations).
+
+
+> seo-audit finds problems. This skill builds solutions.
+
+## When to Use This Skill
+
+Load this skill when:
+- Building new pages optimized for organic search
+- Planning content strategy for organic growth (blog clusters, comparison pages)
+- Implementing programmatic SEO at scale (100+ templated pages)
+- Optimizing product listings for marketplace search algorithms
+- Adding schema markup (JSON-LD structured data)
+- Adapting content for AI search (AI Overviews, chatbot citations)
+
+Do NOT use for:
+- Diagnosing existing SEO problems (use **seo-audit**)
+- Keyword research and clustering (use **keywords**)
+- Page hierarchy and navigation design (use **site-architecture**)
+- Conversion rate optimization (use **page-cro**)
+
+---
+
+## 1. Content Strategy by Site Type
+
+### Decision Tree
+
+```
+What type of site?
+├── E-commerce (Shopify/Etsy/Amazon)
+│   ├── Collection pages → target generic keywords (higher volume)
+│   ├── Product pages → target specific long-tail keywords
+│   └── Blog → build topical authority, link to collections
+├── SaaS
+│   ├── Comparison pages → "[product] vs [competitor]" at scale
+│   ├── Alternative pages → "[competitor] alternatives"
+│   ├── Feature pages → one page per feature, deep content
+│   ├── Integration pages → "[product] + [integration]" at scale
+│   └── Blog → educational content linking to product pages
+└── Content/Blog
+    ├── Pillar pages → comprehensive guides on core topics
+    ├── Cluster pages → specific subtopics linking to pillar
+    └── FAQ pages → question-based content for featured snippets
+```
+
+### E-Commerce SEO Strategy
+
+**Collection pages rank higher than product pages.** Prioritize collection page optimization:
+- Unique H1 with primary keyword
+- 200+ words of original descriptive content above and below the product grid
+- Internal links to related collections
+- Breadcrumb navigation with schema markup
+
+**Product pages target specific long-tail:**
+- Title: `[Brand] [Product Name] [Key Attribute] | [Store Name]`
+- Original description (never manufacturer copy)
+- All image alt tags descriptive and keyword-relevant
+- Related products section for internal linking
+- Product schema markup with price, availability, reviews
+
+### SaaS SEO Strategy
+
+**Comparison and alternative pages are highest-ROI for SaaS:**
+- Template: `[Your Product] vs [Competitor]: [Honest Comparison]`
+- Structure: feature table, pricing comparison, use case recommendations
+- Honest tone — acknowledge where competitors excel (builds E-E-A-T trust)
+- CTA at the end, not the beginning
+
+---
+
+## 2. Programmatic SEO
+
+### When to Use Programmatic SEO
+
+Use when you can generate 100+ unique pages from structured data with genuine value per page. Each page must pass the "would a human find this useful?" test.
+
+### Template Architecture
+
+```
+Data Source (DB/Spreadsheet/API)
+    ↓
+Template Engine (Next.js dynamic routes)
+    ↓
+Unique Page = Template + Dynamic Data + Unique Content Blocks
+    ↓
+Internal Linking (category → subcategory → page → related pages)
+    ↓
+XML Sitemap (auto-generated, all pages included)
+```
+
+### Programmatic SEO Patterns
+
+| Pattern | URL Structure | Example | Data Source |
+|---------|-------------|---------|-------------|
+| **Comparison** | `/compare/[a]-vs-[b]` | `/compare/printify-vs-printful` | Product database |
+| **Location** | `/[service]-in-[city]` | `/pod-suppliers-in-london` | City database |
+| **Integration** | `/integrations/[platform]` | `/integrations/shopify` | Integration catalog |
+| **Alternative** | `/alternatives/[competitor]` | `/alternatives/printful` | Competitor list |
+| **Template/Tool** | `/tools/[calculator-type]` | `/tools/profit-margin-calculator` | Tool catalog |
+
+### Thin Content Guardrails
+
+Every programmatic page MUST have:
+1. Unique title and H1 (not just variable swapped)
+2. At least one paragraph of unique descriptive content
+3. Unique data points (stats, features, pricing) not found on other pages
+4. Internal links to related pages in the same programmatic set
+5. No duplicate meta descriptions across pages
+
+**Red flags that trigger Google thin content penalties:**
+- 95%+ identical content across pages (only city name swapped)
+- No unique data — just template with variable substitution
+- Boilerplate FAQ repeated across all pages
+- Missing internal linking between related pages
+
+---
+
+## 3. Marketplace SEO Differences
+
+See `references/marketplace-seo-differences.md` for detailed algorithm breakdowns.
+
+### Quick Comparison
+
+| Factor | Shopify (Google) | Etsy | Amazon |
+|--------|-----------------|------|--------|
+| **Primary algorithm** | Google organic | Etsy search (proprietary) | A9 / COSMO |
+| **Ranking signal #1** | Backlinks + content quality | Recency + conversion rate | Sales velocity + conversion |
+| **Title optimization** | 50-60 chars, keyword at start | 140 chars, front-load keywords | 80 chars optimal, keyword-rich |
+| **Content depth** | Critical (500+ words ideal) | Less important (tags matter more) | Bullet points + A+ content |
+| **Reviews impact** | Indirect (trust signal) | Direct ranking factor | Direct ranking factor |
+| **Freshness** | Moderate (evergreen can rank) | High (recent listings boosted) | Moderate (sales velocity matters more) |
+| **External links** | Critical | Helpful (drives external traffic signal) | Not applicable |
+
+---
+
+## 4. Schema Markup Implementation
+
+### Which Schema for Which Page
+
+| Page Type | Schema Types | Priority |
+|-----------|-------------|----------|
+| Product page | `Product`, `AggregateRating`, `Offer`, `BreadcrumbList` | Critical |
+| Collection page | `CollectionPage`, `BreadcrumbList`, `ItemList` | High |
+| FAQ page | `FAQPage`, `Question`, `Answer` | High (enables rich results) |
+| How-to guide | `HowTo`, `Step`, `BreadcrumbList` | Medium |
+| SaaS pricing | `SoftwareApplication`, `Offer`, `AggregateRating` | High |
+| Blog post | `Article`, `Person` (author), `BreadcrumbList` | Medium |
+| Local business | `LocalBusiness`, `PostalAddress`, `GeoCoordinates` | Critical for local |
+
+### JSON-LD Implementation Pattern
+
+Always use JSON-LD (not Microdata or RDFa). Place in `<head>` or at end of `<body>`.
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "Product",
+  "name": "Product Name",
+  "description": "...",
+  "image": "https://...",
+  "offers": {
+    "@type": "Offer",
+    "price": "29.99",
+    "priceCurrency": "USD",
+    "availability": "https://schema.org/InStock"
+  }
+}
+</script>
+```
+
+**Detection limitation:** `web_fetch` and `curl` cannot detect JS-injected schema. Use Google Rich Results Test or browser DevTools to verify. See `seo-audit` skill for details.
+
+---
+
+## 5. AI Search Optimization
+
+### AEO (Answer Engine Optimization)
+
+Optimize for AI Overviews (Google), ChatGPT, Perplexity, and Claude citations.
+
+**Key patterns:**
+1. **Concise answer paragraphs:** Start sections with a direct, 2-3 sentence answer before elaborating
+2. **Entity clarity:** Use proper nouns, define terms, be specific (not "the tool" but "Printify's production API")
+3. **Structured data:** Tables, lists, and clear headings that AI can parse
+4. **Citation-worthy statements:** Include specific numbers, dates, and verifiable facts
+5. **FAQ format:** Question-answer pairs that directly match search queries
+
+### What AI Search Engines Cite
+
+| Signal | Why It Gets Cited |
+|--------|------------------|
+| Specific data points | "Printify charges $12.50 per standard tee" — concrete, verifiable |
+| Step-by-step instructions | Procedural knowledge that AI can relay as guidance |
+| Comparison tables | Structured data AI can extract and present |
+| Expert attribution | Named author with credentials increases citation likelihood |
+| Recency | AI prefers recently-updated pages for rapidly-changing topics |
+
+---
+
+## Related Skills
+
+- **seo-audit** — Diagnose existing SEO problems (this skill builds, seo-audit audits)
+- **keywords** — Research and choose the right keywords before building pages
+- **site-architecture** — Plan page hierarchy and URL structure
+- **page-cro** — Optimize pages for conversion (not just ranking)
+- **copywriting** — Write the content that goes on SEO-optimized pages
+
+## Verification
+
+After applying this skill, verify:
+- [ ] Content strategy matches the correct site type (e-commerce, SaaS, content/blog)
+- [ ] Programmatic SEO pages pass the thin content guardrails (unique title, unique content, unique data)
+- [ ] Marketplace SEO uses platform-specific factors (not Google SEO assumptions)
+- [ ] Schema markup uses JSON-LD format with correct @type for the page type
+- [ ] AI search optimization includes concise answer paragraphs and entity clarity
+- [ ] Internal linking follows hub-and-spoke pattern where applicable
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Diagnosing existing SEO problems or traffic drops | `seo-audit` | seo-audit diagnoses; seo-strategy builds |
+| Keyword research and clustering | `keywords` | keywords owns research methodology |
+| Page hierarchy and navigation design | `site-architecture` | site-architecture owns IA structure |
+| Conversion rate optimization | `page-cro` | page-cro owns conversion, not ranking |
+
+---
+
+*Version 1.1.0 — 2026-03-28. Added Philosophy, Verification, Do NOT Use When.*

package/marketplace/skills/server-actions-design/SKILL.md

@@ -0,0 +1,243 @@
+---
+name: server-actions-design
+description: "Use when designing or reviewing Server Actions: the 'use server' directive contract, how a server-side function becomes invokable from the browser without an API route, form integration via the `action` attribute, the React 19 hooks useActionState / useFormStatus, progressive enhancement (works without JS), server-side validation and authorization as mandatory rather than optional, revalidation primitives (revalidatePath, revalidateTag, redirect), error handling and bound arguments, and the security boundary that makes Server Actions a public endpoint despite their function-like syntax. Covers Next.js App Router as the canonical implementation. Do NOT use for read-path data fetching with RSC (use server-components-design), for the broader 'use client' / 'use server' boundary semantics (use client-server-boundary), for designing externally-facing API contracts (use api-design), or for form UX patterns at the component level (use form-ux-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-16\",\"drift_check\":\"{\\\\\\\"last_verified\\\\\\\":\\\\\\\"2026-05-16\\\\\\\"}\",\"eval_artifacts\":\"planned\",\"eval_state\":\"unverified\",\"routing_eval\":\"absent\",\"comprehension_state\":\"present\",\"stability\":\"experimental\",\"keywords\":\"[\\\\\\\"Server Actions\\\\\\\",\\\\\\\"Server Function declaration\\\\\\\",\\\\\\\"form action attribute\\\\\\\",\\\\\\\"useActionState\\\\\\\",\\\\\\\"useFormStatus\\\\\\\",\\\\\\\"forms that work without JavaScript\\\\\\\",\\\\\\\"revalidatePath\\\\\\\",\\\\\\\"revalidateTag\\\\\\\",\\\\\\\"server mutation Next.js\\\\\\\",\\\\\\\"validate Server Action inputs\\\\\\\",\\\\\\\"bound arguments Server Action\\\\\\\",\\\\\\\"redirect after action\\\\\\\"]\",\"triggers\":\"[\\\\\\\"how do I submit a form to the server\\\\\\\",\\\\\\\"do I need an API route for this mutation\\\\\\\",\\\\\\\"how do I call a server function from a button\\\\\\\",\\\\\\\"why is my Server Action exposed as an endpoint\\\\\\\",\\\\\\\"useActionState vs useFormState\\\\\\\",\\\\\\\"how do I revalidate after mutation\\\\\\\",\\\\\\\"can Server Actions run in event handlers\\\\\\\"]\",\"examples\":\"[\\\\\\\"design a 'create comment' form using Server Actions plus useActionState so it works without JavaScript and reports server-side validation errors\\\\\\\",\\\\\\\"decide whether a delete button should call a Server Action or an API route\\\\\\\",\\\\\\\"audit a Server Action for missing authorization (the function looks like a normal call but is publicly invokable)\\\\\\\",\\\\\\\"design the revalidation strategy for a mutation that affects multiple cached routes\\\\\\\"]\",\"anti_examples\":\"[\\\\\\\"design a Server Component that reads data on render (use server-components-design)\\\\\\\",\\\\\\\"design a public REST API consumed by mobile clients (use api-design)\\\\\\\",\\\\\\\"choose between SSR and SSG (use rendering-models)\\\\\\\",\\\\\\\"design the visual UX of a form's validation states (use form-ux-architecture)\\\\\\\",\\\\\\\"design the visual states and accessibility of a form (use form-ux-architecture)\\\\\\\",\\\\\\\"design a public HTTP contract for mobile, third-party, or server-to-server callers (use api-design)\\\\\\\"]\",\"relations\":\"{\\\\\\\"related\\\\\\\":[\\\\\\\"server-components-design\\\\\\\",\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"form-ux-architecture\\\\\\\",\\\\\\\"api-design\\\\\\\",\\\\\\\"hooks-patterns\\\\\\\"],\\\\\\\"boundary\\\\\\\":[{\\\\\\\"skill\\\\\\\":\\\\\\\"server-components-design\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"server-components-design owns the read path — Server Components fetch data on render; server-actions-design owns the write path — Server Actions execute mutations triggered from the client. They share infrastructure (RSC, 'use server') but solve distinct problems.\\\\\\\"},{\\\\\\\"skill\\\\\\\":\\\\\\\"client-server-boundary\\\\\\\",\\\\\\\"reason\\\\\\\":\\\\\\\"client-server-boundary owns the serialization and directive mechanics of the boundary itself; server-actions-design owns the discipline of using the 'use server' side of that boundary for mutations.\\\\\\\"}],\\\\\\\"verify_with\\\\\\\":[\\\\\\\"code-review\\\\\\\",\\\\\\\"api-design\\\\\\\"]}\",\"mental_model\":\"|\",\"purpose\":\"|\",\"boundary\":\"|\",\"analogy\":\"Server Actions are to React mutations what stored procedures are to database access — the function looks like an ordinary call in client code, but the work happens on the privileged side of a trust boundary, with the same security implications: the caller controls the arguments, but cannot see the implementation; the implementation must validate every input and authorize every call as if the caller were a hostile script with curl, because functionally they could be.\",\"misconception\":\"|\",\"concept\":\"{\\\\\\\"definition\\\\\\\":\\\\\\\"A Server Action is a JavaScript function marked with 'use server' (either at the module level or as the first line of the function body) that executes on the server but is invokable from the client. The bundler turns calls to it from Client Components into a network round-trip: arguments are serialized, the function runs server-side, the return value is serialized back. The function itself looks like an ordinary import in client code, which is the design's main strength and its main security trap — what looks like a function call is a public POST endpoint.\\\\\\\",\\\\\\\"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/server-actions-design/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/server-actions-design/SKILL.md
+---
+
+# Server Actions Design
+
+## Coverage
+
+The discipline of designing Server Actions: what `'use server'` actually does (turns a function into a public POST endpoint with serialized arguments), how Server Actions integrate with HTML forms via the `action` attribute, how `useActionState` and `useFormStatus` give React-aware state and pending UI, why progressive enhancement (form works without JavaScript) is the design's load-bearing feature, why server-side validation and authorization are not optional, how `revalidatePath` / `revalidateTag` / `redirect` participate in the mutation pipeline, how bound arguments propagate state across action calls, and the central security insight: a Server Action that looks like a function call is a publicly-reachable endpoint and must be treated as one.
+
+## Philosophy
+
+Before Server Actions, a "mutation from the browser" required two parallel structures: a client-side function that called `fetch('/api/foo', { method: 'POST', body: JSON.stringify({...}) })`, and a server-side route handler that parsed the body, validated, authorized, executed the mutation, and serialized a response. The two had to agree on a wire format, type contracts had to be duplicated or shared via a runtime validator, and CSRF tokens had to be plumbed through.
+
+Server Actions collapse that into one declaration. A function with `'use server'` at its top is invokable from Client Components as if it were imported normally. The bundler rewrites the call site to a network round-trip; the function executes server-side. There is no manual wire format, no client-side fetch boilerplate, no separate API route to keep in sync.
+
+The collapse is *syntactic*, not *semantic*. The function is still invoked over the network, by anyone who finds the action's identifier, with arguments they control. The server has none of the type guarantees the call site appears to provide. **The discipline of Server Actions is to treat the function as a public endpoint disguised as a function**: validate every input, authorize every call, fail loudly on any assumption that the caller is your own UI rather than an attacker with curl.
+
+The second principle of Server Actions is **progressive enhancement**. A Server Action attached to an HTML form via `<form action={serverAction}>` works without JavaScript: the browser performs a native POST to the action's endpoint, the server returns a redirect, the page navigates. With JavaScript, React intercepts the submission, runs the action, applies the result without a full page reload, and updates `useFormStatus` while the action is in flight. The form does not have two code paths — it has one path that gracefully upgrades when JS arrives. Designing actions that rely on JS-only state defeats the architecture; designing actions that work form-first and JS-second uses it well.
+
+## The `'use server'` Contract
+
+Three ways to declare a Server Action:
+
+1. **Module-level directive**: a file with `'use server'` at the top exports only Server Actions.
+   ```ts
+   // app/actions/comments.ts
+   'use server'
+   export async function createComment(formData: FormData) { ... }
+   export async function deleteComment(id: string) { ... }
+   ```
+
+2. **Inline directive in a Server Component**: a function defined inside a Server Component, with `'use server'` as its first statement.
+   ```tsx
+   // app/posts/[id]/page.tsx (Server Component)
+   export default async function Post({ params }) {
+     async function addComment(formData: FormData) {
+       'use server'
+       // runs on the server, can close over server-side state
+     }
+     return <form action={addComment}>...</form>
+   }
+   ```
+
+3. **Re-exported from a `'use server'` module to a Client Component**: client code imports the function and invokes it directly.
+
+The bundler treats `'use server'`-marked functions specially: it strips the function body from the client bundle, replacing it with a reference that the runtime resolves to a network call. The function's *signature* (name, parameter types) is preserved at the call site; the function's *implementation* never reaches the client.
+
+Arguments and return values must be serializable across the boundary — strings, numbers, plain objects, arrays, FormData, Date, Map, Set, typed arrays, Promise (React 19). Functions, class instances, and DOM nodes cannot cross.
+
+## The Form Integration Pattern
+
+The canonical Server Action consumes a `FormData` object via the `action` prop on a `<form>`:
+
+```tsx
+'use server'
+import { z } from 'zod'
+import { db } from '@/db'
+import { revalidatePath } from 'next/cache'
+import { auth } from '@/auth'
+
+const CommentSchema = z.object({
+  postId: z.string().uuid(),
+  body: z.string().min(1).max(1000),
+})
+
+export async function addComment(formData: FormData) {
+  const session = await auth()
+  if (!session) throw new Error('Unauthorized')   // public endpoint — must check
+  
+  const parsed = CommentSchema.safeParse({
+    postId: formData.get('postId'),
+    body: formData.get('body'),
+  })
+  if (!parsed.success) return { error: parsed.error.flatten() }
+  
+  await db.comment.create({
+    data: { ...parsed.data, authorId: session.userId },
+  })
+  
+  revalidatePath(`/posts/${parsed.data.postId}`)
+  return { success: true }
+}
+```
+
+```tsx
+// In a Server Component (or Client Component):
+<form action={addComment}>
+  <input type="hidden" name="postId" value={postId} />
+  <textarea name="body" required />
+  <button type="submit">Post</button>
+</form>
+```
+
+The form posts to the action. Without JavaScript, the browser navigates to the action's endpoint and back. With JavaScript, React handles the submission inline. Either way, `revalidatePath` instructs Next.js to invalidate the cached version of the post page, so the new comment appears on next render.
+
+## `useActionState` and `useFormStatus`
+
+These two React 19 hooks let Client Components observe action state without imperative wiring.
+
+**`useActionState`** wraps an action and returns the action's last result alongside a wrapper function:
+
+```tsx
+'use client'
+import { useActionState } from 'react'
+import { addComment } from '@/app/actions/comments'
+
+export function CommentForm({ postId }) {
+  const [state, formAction, isPending] = useActionState(addComment, { error: null })
+  return (
+    <form action={formAction}>
+      <input type="hidden" name="postId" value={postId} />
+      <textarea name="body" />
+      {state?.error && <p className="error">{state.error.body?.[0]}</p>}
+      <button disabled={isPending}>{isPending ? 'Posting…' : 'Post'}</button>
+    </form>
+  )
+}
+```
+
+The first argument is the action; the second is the initial state. `formAction` is what you pass to the form's `action` prop. `state` is whatever the action last returned. `isPending` tracks the in-flight status.
+
+**`useFormStatus`** is read from inside a `<form>`'s descendant components — it gives the pending status without prop drilling:
+
+```tsx
+'use client'
+import { useFormStatus } from 'react-dom'
+
+export function SubmitButton({ label }) {
+  const { pending } = useFormStatus()
+  return <button disabled={pending}>{pending ? 'Saving…' : label}</button>
+}
+```
+
+`useFormStatus` only reads the status of the nearest ancestor `<form>` — it cannot observe arbitrary form state. It is for the submit button's UI, not for global form state.
+
+## Revalidation — `revalidatePath`, `revalidateTag`, `redirect`
+
+A mutation that the user sees must invalidate the cached read paths it affects. Three primitives:
+
+| Primitive | What it does |
+|---|---|
+| `revalidatePath('/posts/123')` | Invalidates the cached Server Component output for the path; next request re-renders it |
+| `revalidatePath('/posts/[id]', 'page')` | Invalidates the dynamic route pattern (all `/posts/*` pages) |
+| `revalidateTag('comments')` | Invalidates all `fetch` calls or `cache(...)` reads tagged `'comments'`; finer-grained than path-based |
+| `redirect('/posts/123')` | Throws a special redirect signal that becomes a `Location:` header in the response |
+
+Design rule: every action that mutates state visible to a Server Component must call `revalidatePath` or `revalidateTag` to update the cache. Forgetting to revalidate produces stale UI after submission — the mutation succeeded server-side, but the page still shows the pre-mutation data.
+
+`redirect` is for actions that should navigate after success (e.g., create-and-redirect-to-detail-page). It cannot be inside a try/catch — `redirect` throws, and catching swallows the redirect signal.
+
+## Bound Arguments
+
+`.bind()` (the JavaScript built-in) pre-fills action arguments at the server side — useful for passing IDs without exposing them as form fields:
+
+```tsx
+// Server Component
+export default async function Post({ params }) {
+  const deletePost = deletePostAction.bind(null, params.id)
+  return (
+    <form action={deletePost}>
+      <button type="submit">Delete</button>
+    </form>
+  )
+}
+
+// 'use server' module
+export async function deletePostAction(id: string, formData: FormData) {
+  // id is bound; formData comes from the form
+}
+```
+
+Bound arguments do not need to be serialized at submission time because they were captured server-side. They are also not user-controllable from the form, so they are safer than `<input type="hidden">` for IDs that the user must not change. But they are still visible to anyone reading the network request — never bind a secret.
+
+## Security Discipline
+
+| Concern | Reality | Required action |
+|---|---|---|
+| Authorization | The function is publicly invokable by anyone who finds its identifier | Check the session in every action; reject anonymous calls explicitly |
+| Authentication of the *acting user* | The function does not know who's calling unless you check | Read the session from cookies/headers; do not trust client-supplied user IDs |
+| Input validation | The function receives FormData / serialized arguments; the server has no type guarantee from the call-site types | Validate every input with a runtime schema (Zod, Valibot, ArkType) |
+| Authorization of the *operation* | Even authenticated users may not be allowed to delete this post | Check ownership / permission inside the action body before mutating |
+| CSRF | Server Actions in Next.js include built-in same-origin checks; cross-origin POSTs are rejected | Default protection is on; configure `serverActions.allowedOrigins` only when explicitly proxying |
+| Rate limiting | The endpoint is public; spam is possible | Implement per-action rate limits in middleware or inside the action |
+| Bound arguments | Visible in the network request despite not being a form field | Never bind secrets, even via `.bind()` |
+
+The single most common Server Action bug: forgetting that the function is publicly reachable. A function called `deletePost(postId: string)` is a `POST` that any browser can craft with any `postId` — the type signature does not protect the server. Treat actions like API routes that happen to share types with your UI.
+
+## Common Anti-Patterns
+
+| Anti-pattern | Why it's wrong | Fix |
+|---|---|---|
+| Trusting client-supplied user ID as the actor | Anyone can submit any ID | Read user ID from the server-side session, not from form fields |
+| Validating only on the client | Server has no guarantee of client-side validation | Mandatory server-side validation; client-side is UX, not security |
+| Calling fetch('/api/...') instead of a Server Action for an internal mutation | Duplicate code, type drift between client and server | Use a Server Action — one declaration, one wire format |
+| Forgetting `revalidatePath` / `revalidateTag` | Cached Server Component shows stale data after mutation | Call the appropriate revalidation primitive in every mutation |
+| Wrapping `redirect` in try/catch | The redirect signal is swallowed | Place `redirect` outside the try block, or rethrow caught redirect signals |
+| Server Action that returns a non-serializable value (Date object with methods, function, class instance) | Cannot cross the boundary back to the client | Return plain objects only |
+| Form that doesn't work without JavaScript (e.g., requires a click handler that calls the action) | Defeats progressive enhancement | Use `<form action={serverAction}>`, not `<button onClick={() => serverAction()}>` |
+| Action that performs side effects regardless of validation result | Partial failure with database state changed and error returned | Validate before any mutation; structure as parse-then-mutate |
+
+## Verification
+
+After applying this skill, verify:
+
+- [ ] Every Server Action checks authentication before any mutation.
+- [ ] Every Server Action validates inputs with a runtime schema, not just TypeScript types.
+- [ ] Every Server Action that mutates Server-Component-visible state calls `revalidatePath` or `revalidateTag`.
+- [ ] No action trusts client-supplied user IDs, role flags, or permission claims.
+- [ ] Forms work without JavaScript: native browser submission to the action's endpoint produces the same result as the React-intercepted path.
+- [ ] No `redirect` is inside a try/catch (or, if it must be, redirect signals are explicitly rethrown).
+- [ ] Bound arguments via `.bind()` carry only non-secret data.
+- [ ] Rate limiting exists for actions that can be invoked frequently or anonymously.
+- [ ] Server Actions return only serializable values to Client Components.
+
+## Grounding Sources
+
+- React docs — [`'use server'`](https://react.dev/reference/rsc/use-server). The directive contract.
+- React docs — [`useActionState`](https://react.dev/reference/react/useActionState) and [`useFormStatus`](https://react.dev/reference/react-dom/hooks/useFormStatus). The React 19 hooks for action state and pending UI.
+- Next.js docs — [Server Actions and Mutations](https://nextjs.org/docs/app/building-your-application/data-fetching/server-actions-and-mutations). The canonical implementation reference.
+- Next.js docs — [`revalidatePath`](https://nextjs.org/docs/app/api-reference/functions/revalidatePath) and [`revalidateTag`](https://nextjs.org/docs/app/api-reference/functions/revalidateTag). Cache invalidation primitives.
+- Next.js docs — [`redirect`](https://nextjs.org/docs/app/api-reference/functions/redirect). The redirect-as-throw mechanism.
+- Vercel — [Server Actions security model and the Same-Origin Check](https://nextjs.org/blog/security-nextjs-server-components-actions). The framework's security defaults and what they don't cover.
+- Wieruch, R. — [Server Actions in Next.js](https://www.robinwieruch.de/next-server-actions/). Comprehensive walkthrough with progressive-enhancement and form-state patterns.
+
+## Do NOT Use When
+
+| Instead of this skill | Use | Why |
+|---|---|---|
+| Designing the read path (fetching data on render with Server Components) | `server-components-design` | server-components-design owns the read path; this skill owns the write path. They share infrastructure but solve different problems. |
+| The serialization mechanics of the `'use client'` / `'use server'` boundary | `client-server-boundary` | client-server-boundary owns the boundary semantics; this skill applies them to mutations specifically. |
+| Designing a public REST API consumed by mobile clients or third parties | `api-design` | api-design owns HTTP contracts intended for external consumption. Server Actions are internal to one app's UI. |
+| Form UX patterns (validation states, layout, accessibility, microcopy) | `form-ux-architecture` | form-ux-architecture owns the visual/interaction design of the form; this skill owns the server execution model. |
+| Hook discipline (Rules of Hooks, dependency arrays, custom hooks) | `hooks-patterns` | hooks-patterns covers Client Component hook usage. `useActionState` is a hook called inside Client Components but governed by hooks-patterns' rules. |