diff --git a/package.json b/package.json
index b7c829c..bdce18d 100644
--- a/package.json
+++ b/package.json
@@ -4,11 +4,13 @@
   "description": "AI agent resources for Sanity development",
   "private": true,
   "scripts": {
-    "validate": "skills-ref validate ./skills/sanity-best-practices && skills-ref validate ./skills/content-modeling-best-practices && skills-ref validate ./skills/seo-aeo-best-practices && skills-ref validate ./skills/content-experimentation-best-practices",
+    "validate": "skills-ref validate ./skills/sanity-best-practices && skills-ref validate ./skills/content-modeling-best-practices && skills-ref validate ./skills/seo-aeo-best-practices && skills-ref validate ./skills/content-experimentation-best-practices && skills-ref validate ./skills/portable-text-serialization && skills-ref validate ./skills/portable-text-conversion",
     "validate:sanity": "skills-ref validate ./skills/sanity-best-practices",
     "validate:content-modeling": "skills-ref validate ./skills/content-modeling-best-practices",
     "validate:seo": "skills-ref validate ./skills/seo-aeo-best-practices",
-    "validate:experimentation": "skills-ref validate ./skills/content-experimentation-best-practices"
+    "validate:experimentation": "skills-ref validate ./skills/content-experimentation-best-practices",
+    "validate:pt-serialization": "skills-ref validate ./skills/portable-text-serialization",
+    "validate:pt-conversion": "skills-ref validate ./skills/portable-text-conversion"
   },
   "devDependencies": {
     "skills-ref": "^0.1.5"
diff --git a/rules/sanity-migration.mdc b/rules/sanity-migration.mdc
index cf8bd6f..a323165 100644
--- a/rules/sanity-migration.mdc
+++ b/rules/sanity-migration.mdc
@@ -40,18 +40,24 @@ const blocks = htmlToBlocks(htmlString, blockContentType, {
 ```
 
 ## 2. Markdown Import (Static Sites)
-Use `@sanity/block-content-to-markdown` (legacy name, often used in reverse) OR use a dedicated parser like `remark` to convert Markdown to HTML, then use `block-tools`.
+Use `@portabletext/markdown` for direct, schema-aware Markdown ↔ Portable Text conversion.
 
-**Recommended Path: Markdown -> HTML -> Portable Text**
-This is often more robust than direct Markdown-to-PT parsers because `block-tools` handles schema validation better.
+**Recommended: Direct Conversion with `@portabletext/markdown`**
+```typescript
+import {markdownToPortableText} from '@portabletext/markdown'
+
+const blocks = markdownToPortableText(markdownString)
+```
+
+This handles headings, lists, bold, italic, code, links, images, and tables. Use `@portabletext/sanity-bridge` to pass your Sanity schema so only valid types are produced.
+
+**Alternative: Markdown → HTML → Portable Text**
+For complex Markdown with non-standard extensions, convert to HTML first, then use `htmlToBlocks` (see above).
 
 1.  **Parse:** `marked` or `remark` to convert MD to HTML.
-2.  **Convert:** Use `htmlToBlocks` (see above).
+2.  **Convert:** Use `htmlToBlocks` from `@portabletext/block-tools`.
 
-**Alternative: Direct Parsing**
-If using a library like `markdown-to-sanity` or writing a custom `remark` serializer:
--   Ensure you handle "inline" vs "block" nodes correctly.
--   Map images to Sanity asset uploads.
+> **Note:** `@sanity/block-content-to-markdown` and `@sanity/block-tools` are deprecated. Use `@portabletext/markdown` and `@portabletext/block-tools` instead.
 
 ## 3. Image Handling (Universal)
 Don't just link to external images. Download them and upload to Sanity Asset Pipeline.
diff --git a/skills/portable-text-conversion/SKILL.md b/skills/portable-text-conversion/SKILL.md
new file mode 100644
index 0000000..9965873
--- /dev/null
+++ b/skills/portable-text-conversion/SKILL.md
@@ -0,0 +1,65 @@
+---
+name: portable-text-conversion
+description: Convert HTML and Markdown content into Portable Text blocks for Sanity. Use when migrating content from legacy CMSs, importing HTML or Markdown into Sanity, building content pipelines that ingest external content, converting rich text between formats, or programmatically creating Portable Text documents. Covers @portabletext/markdown (markdownToPortableText), @portabletext/block-tools (htmlToBlocks), custom deserializers, and the Portable Text specification for manual block construction.
+license: MIT
+metadata:
+  author: sanity
+  version: "1.0.0"
+---
+
+# Portable Text Conversion
+
+Convert external content (HTML, Markdown) into Portable Text for Sanity. Three main approaches:
+
+1. **`markdownToPortableText`** — Convert Markdown directly using `@portabletext/markdown` (recommended for Markdown)
+2. **`htmlToBlocks`** — Parse HTML into PT blocks using `@portabletext/block-tools` (for HTML migration)
+3. **Manual construction** — Build PT blocks directly from any source (APIs, databases, etc.)
+
+## Portable Text Specification
+
+Understand the target format before converting. PT is an array of blocks:
+
+```json
+[
+  {
+    "_type": "block",
+    "_key": "abc123",
+    "style": "normal",
+    "children": [
+      {"_type": "span", "_key": "def456", "text": "Hello ", "marks": []},
+      {"_type": "span", "_key": "ghi789", "text": "world", "marks": ["strong"]}
+    ],
+    "markDefs": []
+  },
+  {
+    "_type": "block",
+    "_key": "jkl012",
+    "style": "h2",
+    "children": [
+      {"_type": "span", "_key": "mno345", "text": "A heading", "marks": []}
+    ],
+    "markDefs": []
+  },
+  {
+    "_type": "image",
+    "_key": "pqr678",
+    "asset": {"_type": "reference", "_ref": "image-abc-200x200-png"}
+  }
+]
+```
+
+**Key rules:**
+- Every block and span needs `_key` (unique within the array)
+- `_type: "block"` is for text blocks; custom types use their own `_type`
+- `markDefs` holds annotation data; `marks` on spans reference `markDefs[*]._key` or are decorator strings
+- Lists use `listItem` ("bullet" | "number") and `level` (1, 2, 3...) on regular blocks
+
+## Conversion Rules
+
+Read the rule file matching your source format:
+
+- **Markdown → Portable Text**: `rules/markdown-to-pt.md` — `@portabletext/markdown` with `markdownToPortableText` (recommended)
+- **HTML → Portable Text**: `rules/html-to-pt.md` — `@portabletext/block-tools` with `htmlToBlocks`
+- **Manual PT Construction**: `rules/manual-construction.md` — build blocks programmatically from any source
+
+> **Note:** `@sanity/block-tools` is the legacy package name. Always use `@portabletext/block-tools` for new projects. The API is the same.
diff --git a/skills/portable-text-conversion/rules/html-to-pt.md b/skills/portable-text-conversion/rules/html-to-pt.md
new file mode 100644
index 0000000..153e88b
--- /dev/null
+++ b/skills/portable-text-conversion/rules/html-to-pt.md
@@ -0,0 +1,242 @@
+---
+title: Convert HTML to Portable Text
+description: Use @portabletext/block-tools with htmlToBlocks to convert HTML content into Portable Text blocks
+tags: [portable-text, html, conversion, migration, import]
+---
+
+# Convert HTML to Portable Text
+
+Use `@portabletext/block-tools` to parse HTML into Portable Text blocks. This is the primary tool for migrating HTML content from legacy CMSs. It has built-in support for content from Google Docs, Microsoft Word, and Notion.
+
+> **Note:** For Markdown sources, use `@portabletext/markdown` instead — it's simpler and more direct. See `rules/markdown-to-pt.md`.
+
+> **Note:** `@sanity/block-tools` is the legacy package name. Use `@portabletext/block-tools` for new projects. The API is identical.
+
+## Setup
+
+```bash
+npm install @portabletext/block-tools jsdom @sanity/schema
+```
+
+In Node.js, you must provide a `parseHtml` function that returns a DOM `Document`. Use JSDOM for this:
+
+```ts
+import {htmlToBlocks} from '@portabletext/block-tools'
+import {JSDOM} from 'jsdom'
+import Schema from '@sanity/schema'
+
+// JSDOM is passed to htmlToBlocks via the parseHtml option:
+// htmlToBlocks(html, blockContentType, {
+//   parseHtml: (html) => new JSDOM(html).window.document,
+// })
+```
+
+## Define Your Schema
+
+`htmlToBlocks` needs a compiled Sanity block content type to know which marks, styles, and custom types are valid. Use `@sanity/schema` to compile it:
+
+```ts
+const defaultSchema = Schema.compile({
+  name: 'mySchema',
+  types: [
+    {
+      name: 'post',
+      type: 'document',
+      fields: [
+        {
+          name: 'body',
+          type: 'array',
+          of: [
+            {
+              type: 'block',
+              marks: {
+                decorators: [
+                  {title: 'Strong', value: 'strong'},
+                  {title: 'Emphasis', value: 'em'},
+                  {title: 'Code', value: 'code'},
+                ],
+                annotations: [
+                  {
+                    name: 'link',
+                    type: 'object',
+                    fields: [{name: 'href', type: 'url'}],
+                  },
+                ],
+              },
+              styles: [
+                {title: 'Normal', value: 'normal'},
+                {title: 'H2', value: 'h2'},
+                {title: 'H3', value: 'h3'},
+                {title: 'Quote', value: 'blockquote'},
+              ],
+              lists: [
+                {title: 'Bullet', value: 'bullet'},
+                {title: 'Number', value: 'number'},
+              ],
+            },
+            {
+              name: 'image',
+              type: 'image',
+              fields: [{name: 'alt', type: 'string'}],
+            },
+          ],
+        },
+      ],
+    },
+  ],
+})
+
+const blockContentType = defaultSchema
+  .get('post')
+  .fields.find((f) => f.name === 'body').type
+```
+
+## Basic Conversion
+
+```ts
+const html = '<p>Hello <strong>world</strong></p><h2>Heading</h2>'
+
+const blocks = htmlToBlocks(html, blockContentType, {
+  parseHtml: (html) => new JSDOM(html).window.document,
+})
+```
+
+## Custom Deserializers
+
+Handle HTML elements that don't map directly to standard PT:
+
+```ts
+const blocks = htmlToBlocks(html, blockContentType, {
+  parseHtml: (html) => new JSDOM(html).window.document,
+  rules: [
+    // Convert <img> to image blocks
+    {
+      deserialize(el, next, block) {
+        if (el.tagName?.toLowerCase() !== 'img') return undefined
+
+        return block({
+          _type: 'image',
+          asset: {
+            _type: 'reference',
+            _ref: '', // Upload image separately, set ref after
+          },
+          alt: el.getAttribute('alt') || '',
+          _sanityAsset: `image@${el.getAttribute('src')}`, // for migration tooling
+        })
+      },
+    },
+    // Convert <a> with custom attributes
+    {
+      deserialize(el, next, block) {
+        if (el.tagName?.toLowerCase() !== 'a') return undefined
+
+        const href = el.getAttribute('href') || ''
+        const target = el.getAttribute('target') || ''
+
+        return {
+          _type: '__annotation',
+          markDef: {
+            _type: 'link',
+            href,
+            ...(target ? {target} : {}),
+          },
+          children: next(el.childNodes),
+        }
+      },
+    },
+    // Convert <iframe> to embed blocks
+    {
+      deserialize(el, next, block) {
+        if (el.tagName?.toLowerCase() !== 'iframe') return undefined
+
+        return block({
+          _type: 'embed',
+          url: el.getAttribute('src') || '',
+        })
+      },
+    },
+  ],
+})
+```
+
+## Pre-Process HTML Before Conversion
+
+Strip layout elements and extract metadata:
+
+```ts
+function preprocessHtml(rawHtml: string) {
+  const dom = new JSDOM(rawHtml)
+  const doc = dom.window.document
+
+  // Remove layout elements
+  const removeSelectors = ['header', 'footer', 'nav', '.sidebar', '.menu', 'script', 'style']
+  removeSelectors.forEach((sel) => {
+    doc.querySelectorAll(sel).forEach((el) => el.remove())
+  })
+
+  // Extract metadata
+  const title = doc.querySelector('h1')?.textContent || doc.title || ''
+  const description = doc.querySelector('meta[name="description"]')?.getAttribute('content') || ''
+
+  // Get cleaned body
+  const body = doc.querySelector('article')?.innerHTML || doc.body.innerHTML
+
+  return {title, description, body}
+}
+```
+
+## Upload Images During Migration
+
+Don't just link external images — upload them to Sanity:
+
+```ts
+import type {SanityClient} from '@sanity/client'
+
+async function uploadImage(client: SanityClient, url: string) {
+  const response = await fetch(url)
+  const buffer = await response.arrayBuffer()
+  const asset = await client.assets.upload('image', Buffer.from(buffer), {
+    filename: url.split('/').pop(),
+  })
+  return {
+    _type: 'image',
+    asset: {_type: 'reference', _ref: asset._id},
+  }
+}
+```
+
+## Full Migration Example
+
+```ts
+import {defineMigration, createOrReplace} from 'sanity/migrate'
+
+export default defineMigration({
+  title: 'Import WordPress posts',
+  async *migrate(documents, context) {
+    const posts = await fetchWordPressPosts()
+
+    for (const post of posts) {
+      const {title, description, body} = preprocessHtml(post.content)
+      const blocks = htmlToBlocks(body, blockContentType, {
+        parseHtml: (html) => new JSDOM(html).window.document,
+        rules: [/* custom rules */],
+      })
+
+      yield createOrReplace({
+        _id: `post-${post.slug}`,
+        _type: 'post',
+        title: title || post.title,
+        body: blocks,
+      })
+    }
+  },
+})
+```
+
+Run with: `sanity migration run import-wordpress-posts --no-dry-run`
+
+## Reference
+
+- [@portabletext/block-tools](https://github.com/portabletext/editor/tree/main/packages/block-tools) — part of the `portabletext/editor` monorepo
+- [Sanity Migration docs](https://www.sanity.io/docs/schema-and-content-migrations)
+- [portabletext.org](https://www.portabletext.org) — Editor docs and serializer list
diff --git a/skills/portable-text-conversion/rules/manual-construction.md b/skills/portable-text-conversion/rules/manual-construction.md
new file mode 100644
index 0000000..64dcd50
--- /dev/null
+++ b/skills/portable-text-conversion/rules/manual-construction.md
@@ -0,0 +1,210 @@
+---
+title: Manually Construct Portable Text Blocks
+description: Build Portable Text blocks programmatically from any data source
+tags: [portable-text, construction, api, programmatic, migration]
+---
+
+# Manually Construct Portable Text Blocks
+
+Build PT blocks directly when converting from non-HTML sources (APIs, databases, custom formats) or when you need precise control over the output.
+
+## Key Generation
+
+Every block, span, and markDef needs a unique `_key`:
+
+```ts
+import {randomKey} from '@sanity/util/content'
+
+const key = randomKey(12) // e.g., "a1b2c3d4e5f6"
+```
+
+Or use a simple helper:
+
+```ts
+const randomKey = () => Math.random().toString(36).slice(2, 14)
+```
+
+## Building Blocks
+
+### Simple Paragraph
+
+```ts
+{
+  _type: 'block',
+  _key: randomKey(),
+  style: 'normal',
+  children: [
+    {_type: 'span', _key: randomKey(), text: 'Hello world', marks: []}
+  ],
+  markDefs: []
+}
+```
+
+### Heading
+
+```ts
+{
+  _type: 'block',
+  _key: randomKey(),
+  style: 'h2', // h1, h2, h3, h4, h5, h6
+  children: [
+    {_type: 'span', _key: randomKey(), text: 'Section Title', marks: []}
+  ],
+  markDefs: []
+}
+```
+
+### Text with Decorators (Bold, Italic, Code)
+
+```ts
+{
+  _type: 'block',
+  _key: randomKey(),
+  style: 'normal',
+  children: [
+    {_type: 'span', _key: randomKey(), text: 'This is ', marks: []},
+    {_type: 'span', _key: randomKey(), text: 'bold', marks: ['strong']},
+    {_type: 'span', _key: randomKey(), text: ' and ', marks: []},
+    {_type: 'span', _key: randomKey(), text: 'italic', marks: ['em']},
+    {_type: 'span', _key: randomKey(), text: ' text.', marks: []},
+  ],
+  markDefs: []
+}
+```
+
+### Text with Annotations (Links)
+
+Annotations require a `markDef` entry and a matching key in `marks`:
+
+```ts
+const linkKey = randomKey()
+
+{
+  _type: 'block',
+  _key: randomKey(),
+  style: 'normal',
+  children: [
+    {_type: 'span', _key: randomKey(), text: 'Visit ', marks: []},
+    {_type: 'span', _key: randomKey(), text: 'Sanity', marks: [linkKey]},
+    {_type: 'span', _key: randomKey(), text: ' for more.', marks: []},
+  ],
+  markDefs: [
+    {_type: 'link', _key: linkKey, href: 'https://www.sanity.io'}
+  ]
+}
+```
+
+### Overlapping Marks
+
+A span can have multiple marks (both decorators and annotations):
+
+```ts
+const linkKey = randomKey()
+
+// "bold link" — both strong and linked
+{_type: 'span', _key: randomKey(), text: 'bold link', marks: ['strong', linkKey]}
+```
+
+### Lists
+
+Lists are regular blocks with `listItem` and `level`:
+
+```ts
+// Bullet list
+[
+  {
+    _type: 'block', _key: randomKey(), style: 'normal',
+    listItem: 'bullet', level: 1,
+    children: [{_type: 'span', _key: randomKey(), text: 'First item', marks: []}],
+    markDefs: []
+  },
+  {
+    _type: 'block', _key: randomKey(), style: 'normal',
+    listItem: 'bullet', level: 1,
+    children: [{_type: 'span', _key: randomKey(), text: 'Second item', marks: []}],
+    markDefs: []
+  },
+  {
+    _type: 'block', _key: randomKey(), style: 'normal',
+    listItem: 'bullet', level: 2, // nested
+    children: [{_type: 'span', _key: randomKey(), text: 'Nested item', marks: []}],
+    markDefs: []
+  },
+]
+```
+
+### Custom Block Types
+
+Any object with `_type` and `_key` can be a block:
+
+```ts
+// Image block
+{
+  _type: 'image',
+  _key: randomKey(),
+  asset: {_type: 'reference', _ref: 'image-abc123-800x600-png'},
+  alt: 'A description',
+}
+
+// Code block
+{
+  _type: 'code',
+  _key: randomKey(),
+  language: 'typescript',
+  code: 'const x = 42',
+}
+
+// YouTube embed
+{
+  _type: 'youtube',
+  _key: randomKey(),
+  url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
+}
+```
+
+## Helper Function
+
+A utility for building common blocks:
+
+```ts
+function createBlock(
+  text: string,
+  style: string = 'normal',
+  options?: {listItem?: string; level?: number}
+) {
+  return {
+    _type: 'block',
+    _key: randomKey(),
+    style,
+    ...(options?.listItem ? {listItem: options.listItem, level: options.level || 1} : {}),
+    children: [{_type: 'span', _key: randomKey(), text, marks: []}],
+    markDefs: [],
+  }
+}
+
+// Usage
+const blocks = [
+  createBlock('Introduction', 'h2'),
+  createBlock('This is a paragraph.'),
+  createBlock('First point', 'normal', {listItem: 'bullet', level: 1}),
+  createBlock('Second point', 'normal', {listItem: 'bullet', level: 1}),
+]
+```
+
+## Validation Checklist
+
+Before writing PT blocks to Sanity, verify:
+
+- [ ] Every block has `_type` and `_key`
+- [ ] Every span has `_type: "span"`, `_key`, `text`, and `marks`
+- [ ] Every annotation key in `marks[]` has a matching entry in `markDefs[]`
+- [ ] `markDefs` entries have `_type` and `_key`
+- [ ] `_key` values are unique within the array
+- [ ] `style` values match your schema's allowed styles
+- [ ] `listItem` values match your schema's allowed list types
+- [ ] Custom block `_type` values match registered schema types
+
+## Reference
+
+- [Portable Text Specification](https://github.com/portabletext/portabletext)
+- [@sanity/util](https://github.com/sanity-io/sanity/tree/next/packages/%40sanity/util) — provides `randomKey()` for generating `_key` values
diff --git a/skills/portable-text-conversion/rules/markdown-to-pt.md b/skills/portable-text-conversion/rules/markdown-to-pt.md
new file mode 100644
index 0000000..25e6679
--- /dev/null
+++ b/skills/portable-text-conversion/rules/markdown-to-pt.md
@@ -0,0 +1,204 @@
+---
+title: Convert Markdown to Portable Text
+description: Convert Markdown content into Portable Text blocks using @portabletext/markdown
+tags: [portable-text, markdown, conversion, migration, import]
+---
+
+# Convert Markdown to Portable Text
+
+Use `@portabletext/markdown` for direct Markdown ↔ Portable Text conversion. This is the official library, part of the `portabletext/editor` monorepo.
+
+```bash
+npm install @portabletext/markdown
+```
+
+## Basic Usage
+
+```ts
+import {markdownToPortableText} from '@portabletext/markdown'
+
+const blocks = markdownToPortableText('# Hello **world**')
+```
+
+Output:
+```json
+[{
+  "_type": "block",
+  "_key": "f4s8k2",
+  "style": "h1",
+  "children": [
+    {"_type": "span", "_key": "a9c3x1", "text": "Hello ", "marks": []},
+    {"_type": "span", "_key": "b7d2m5", "text": "world", "marks": ["strong"]}
+  ],
+  "markDefs": []
+}]
+```
+
+## Supported Markdown Features
+
+Out of the box:
+
+- Headings (h1–h6)
+- Paragraphs
+- Bold, italic, inline code, strikethrough
+- Links
+- Blockquotes
+- Ordered and unordered lists (including nested)
+- Code blocks (fenced with language)
+- Horizontal rules
+- Images
+- Tables (GFM)
+- HTML blocks (configurable)
+
+## Custom Schema Mapping
+
+Control how Markdown elements map to your PT schema. Define a schema with `@portabletext/schema`:
+
+```ts
+import {markdownToPortableText} from '@portabletext/markdown'
+import {defineSchema, compileSchema} from '@portabletext/schema'
+
+const schema = compileSchema(defineSchema({
+  styles: [{name: 'normal'}, {name: 'heading 1'}, {name: 'heading 2'}],
+  decorators: [{name: 'strong'}, {name: 'em'}],
+  annotations: [{name: 'link'}],
+  lists: [{name: 'bullet'}, {name: 'number'}],
+}))
+
+const blocks = markdownToPortableText(markdown, {
+  schema,
+  // Map Markdown heading levels to custom style names
+  block: {
+    h1: ({context}) => 'heading 1',
+    h2: ({context}) => 'heading 2',
+  },
+})
+```
+
+### Using a Sanity Studio Schema
+
+Use `@portabletext/sanity-bridge` to convert your Sanity block array schema:
+
+```ts
+import {markdownToPortableText} from '@portabletext/markdown'
+import {sanitySchemaToPortableTextSchema} from '@portabletext/sanity-bridge'
+
+// Convert a Sanity block array schema to a Portable Text schema
+const schema = sanitySchemaToPortableTextSchema(sanityBlockArraySchema)
+
+const blocks = markdownToPortableText(markdown, {schema})
+```
+
+## Custom Matchers
+
+Matchers are top-level options (not nested under a `matchers` key). Each receives `{context, value}` where `context.schema` lets you validate against the schema:
+
+```ts
+const blocks = markdownToPortableText(markdown, {
+  // Block matchers — map Markdown block elements to PT styles
+  block: {
+    h1: ({context}) => {
+      const style = context.schema.styles.find((s) => s.name === 'heading 1')
+      return style?.name // Return undefined to skip
+    },
+  },
+  // Mark matchers — map Markdown inline elements to PT marks
+  marks: {
+    strong: ({context}) => 'strong',
+  },
+  // Type matchers — map Markdown elements to custom PT block types
+  types: {
+    table: ({context, value}) => {
+      const tableType = context.schema.blockObjects.find((obj) => obj.name === 'table')
+      if (!tableType) return undefined
+      return {
+        _type: 'table',
+        _key: context.keyGenerator(),
+        rows: value.rows,
+        headerRows: value.headerRows,
+      }
+    },
+  },
+})
+```
+
+## Handling Inline HTML
+
+Configure how inline HTML in Markdown is processed:
+
+```ts
+const blocks = markdownToPortableText(markdown, {
+  html: {
+    inline: 'text', // 'text' preserves as text, 'skip' removes
+  },
+})
+```
+
+## Custom Key Generation
+
+Provide your own key generator:
+
+```ts
+import {randomKey} from '@sanity/util/content'
+
+const blocks = markdownToPortableText(markdown, {
+  keyGenerator: () => randomKey(12),
+})
+```
+
+## Bidirectional: Also Converts PT → Markdown
+
+The same package provides `portableTextToMarkdown()`:
+
+```ts
+import {portableTextToMarkdown} from '@portabletext/markdown'
+
+const markdown = portableTextToMarkdown(blocks)
+```
+
+See the `portable-text-serialization` skill's `rules/markdown.md` for details on PT → Markdown.
+
+## Migration Example
+
+```ts
+import {markdownToPortableText} from '@portabletext/markdown'
+import {createClient} from '@sanity/client'
+import fs from 'fs'
+import path from 'path'
+import matter from 'gray-matter'
+
+const client = createClient({projectId: 'xxx', dataset: 'production', token: '...'})
+
+// Import a directory of Markdown files
+const mdFiles = fs.readdirSync('./content').filter(f => f.endsWith('.md'))
+
+for (const file of mdFiles) {
+  const raw = fs.readFileSync(path.join('./content', file), 'utf-8')
+  const {data: frontmatter, content} = matter(raw)
+
+  const body = markdownToPortableText(content)
+
+  await client.createOrReplace({
+    _id: `post-${path.basename(file, '.md')}`,
+    _type: 'post',
+    title: frontmatter.title,
+    body,
+  })
+}
+```
+
+## When to Use htmlToBlocks Instead
+
+Use `@portabletext/block-tools` (`htmlToBlocks`) when:
+- Your source is HTML, not Markdown
+- You need custom deserializer rules for non-standard HTML elements
+- You're migrating from a CMS that exports HTML (WordPress, Contentful, etc.)
+- You need to handle complex HTML structures (tables with merged cells, nested divs, etc.)
+
+For Markdown sources, `@portabletext/markdown` is simpler and more direct.
+
+## Reference
+
+- [@portabletext/markdown](https://github.com/portabletext/editor/tree/main/packages/markdown)
+- Part of the [portabletext/editor](https://github.com/portabletext/editor) monorepo
+- Uses [markdown-it](https://github.com/markdown-it/markdown-it) internally
diff --git a/skills/portable-text-serialization/SKILL.md b/skills/portable-text-serialization/SKILL.md
new file mode 100644
index 0000000..3201098
--- /dev/null
+++ b/skills/portable-text-serialization/SKILL.md
@@ -0,0 +1,111 @@
+---
+name: portable-text-serialization
+description: Render and serialize Portable Text to React, Svelte, Vue, Astro, HTML, Markdown, and plain text. Use when implementing Portable Text rendering in any frontend framework, building custom serializers for non-standard block types, converting Portable Text to HTML strings server-side, converting Portable Text to Markdown, extracting plain text from Portable Text, or troubleshooting rendering issues with marks, blocks, lists, or custom types.
+license: MIT
+metadata:
+  author: sanity
+  version: "1.0.0"
+---
+
+# Portable Text Serialization
+
+Render Portable Text content across frameworks using the `@portabletext/*` library family. Each library follows the same component-mapping pattern: you provide a `components` object that maps PT node types to framework-specific renderers.
+
+## Portable Text Structure (Quick Reference)
+
+PT is an array of blocks. Each block has `_type`, optional `style`, `children` (spans), `markDefs`, `listItem`, and `level`.
+
+```
+Root array
+├── block (_type: "block")
+│   ├── style: "normal" | "h1" | "h2" | "blockquote" | ...
+│   ├── children: [span, span, ...]
+│   │   └── span: { _type: "span", text: "...", marks: ["strong", "<markDefKey>"] }
+│   ├── markDefs: [{ _key, _type: "link", href: "..." }, ...]
+│   ├── listItem: "bullet" | "number" (optional)
+│   └── level: 1, 2, 3... (optional, for nested lists)
+├── custom block (_type: "image" | "code" | any custom type)
+└── ...more blocks
+```
+
+**Marks** come in two forms:
+- **Decorators**: string values in `marks[]` like `"strong"`, `"em"`, `"underline"`, `"code"`
+- **Annotations**: keys in `marks[]` referencing entries in `markDefs[]` (e.g., links, internal references)
+
+## Component Mapping Pattern (All Frameworks)
+
+Every `@portabletext/*` library accepts a `components` object with these keys:
+
+| Key | Renders | Props/Data |
+|-----|---------|------------|
+| `types` | Custom block/inline types (image, code, CTA) | `value` (the block data) |
+| `marks` | Decorators + annotations | `children` + `value` (mark data) |
+| `block` | Block styles (h1, normal, blockquote) | `children` |
+| `list` | List wrappers (ul, ol) | `children` |
+| `listItem` | List items | `children` |
+| `hardBreak` | Line breaks within a block | — |
+
+## Framework-Specific Rules
+
+Read the rule file matching your framework:
+
+- **React / Next.js**: `rules/react.md` — `@portabletext/react` or `next-sanity`
+- **Svelte / SvelteKit**: `rules/svelte.md` — `@portabletext/svelte`
+- **Vue / Nuxt**: `rules/vue.md` — `@portabletext/vue`
+- **Astro**: `rules/astro.md` — `astro-portabletext`
+- **HTML (server-side)**: `rules/html.md` — `@portabletext/to-html`
+- **Markdown**: `rules/markdown.md` — `@portabletext/markdown`
+- **Plain text extraction**: `rules/plain-text.md` — `@portabletext/toolkit`
+
+### Additional Community Serializers
+
+These are listed on [portabletext.org](https://www.portabletext.org/integrations/serializers/) but don't have dedicated rule files:
+
+| Target | Package |
+|--------|---------|
+| React Native | `@portabletext/react-native-portabletext` |
+| React PDF | `@portabletext/react-pdf-portabletext` |
+| Solid | `solid-portabletext` |
+| Qwik | `portabletext-qwik` |
+| Shopify Liquid | `portable-text-to-liquid` |
+| PHP | `sanity-php` (SanityBlockContent class) |
+| Python | `portabletext-html` |
+| C# / .NET | `dotnet-portable-text` |
+| Dart / Flutter | `flutter_sanity_portable_text` |
+
+## Common Patterns (All Frameworks)
+
+### Custom Types Need Explicit Components
+
+PT renderers only handle standard blocks by default. Custom types (`image`, `code`, `callToAction`, etc.) require explicit component mappings — they won't render otherwise.
+
+### Keep Components Object Stable
+
+In React/Vue, define `components` outside the render function or memoize it. Recreating on every render causes unnecessary re-renders.
+
+### Handle Missing Components Gracefully
+
+All libraries accept `onMissingComponent` to control behavior when encountering unknown types:
+- `false` — suppress warnings
+- Custom function — log or report
+
+### Querying PT with GROQ
+
+Always expand references inside custom blocks:
+
+```groq
+body[]{
+  ...,
+  _type == "image" => {
+    ...,
+    asset->
+  },
+  markDefs[]{
+    ...,
+    _type == "internalLink" => {
+      ...,
+      "slug": @.reference->slug.current
+    }
+  }
+}
+```
diff --git a/skills/portable-text-serialization/rules/astro.md b/skills/portable-text-serialization/rules/astro.md
new file mode 100644
index 0000000..056c743
--- /dev/null
+++ b/skills/portable-text-serialization/rules/astro.md
@@ -0,0 +1,124 @@
+---
+title: Serialize Portable Text to Astro
+description: Render Portable Text in Astro using astro-portabletext
+tags: [portable-text, astro, serialization, rendering]
+---
+
+# Serialize Portable Text to Astro
+
+Use `astro-portabletext` to render PT in Astro projects. This is the officially recommended library for Sanity + Astro.
+
+```bash
+npm install astro-portabletext
+```
+
+## Basic Usage
+
+```astro
+---
+import {PortableText} from 'astro-portabletext'
+const {value} = Astro.props
+---
+
+<PortableText value={value} />
+```
+
+## Custom Components
+
+Pass custom components to override default rendering:
+
+```astro
+---
+import {PortableText} from 'astro-portabletext'
+import ImageBlock from './ImageBlock.astro'
+import CodeBlock from './CodeBlock.astro'
+import Link from './Link.astro'
+
+const {value} = Astro.props
+
+const components = {
+  type: {
+    image: ImageBlock,
+    code: CodeBlock,
+  },
+  mark: {
+    link: Link,
+  },
+  block: {
+    h1: 'h1',
+    h2: 'h2',
+    blockquote: 'blockquote',
+  },
+}
+---
+
+<PortableText {value} {components} />
+```
+
+### Custom Type Component
+
+```astro
+---
+// ImageBlock.astro
+const {node} = Astro.props
+---
+
+<figure>
+  <img src={urlFor(node).width(800).url()} alt={node.alt || ''} />
+  {node.caption && <figcaption>{node.caption}</figcaption>}
+</figure>
+```
+
+### Custom Mark Component
+
+```astro
+---
+// Link.astro
+const {node} = Astro.props
+const href = node?.href || ''
+const rel = href.startsWith('/') ? undefined : 'noreferrer noopener'
+---
+
+<a {href} {rel}><slot /></a>
+```
+
+## Using Slots for Customization
+
+`astro-portabletext` supports Astro's slot system for simpler customization:
+
+```astro
+---
+import {PortableText} from 'astro-portabletext'
+---
+
+<PortableText value={value}>
+  <fragment slot="block:h1">
+    <h1 class="text-4xl font-bold"><slot /></h1>
+  </fragment>
+  <fragment slot="mark:strong">
+    <strong class="font-black"><slot /></strong>
+  </fragment>
+</PortableText>
+```
+
+## usePortableText Helper
+
+For more control, use the `usePortableText` render function:
+
+```astro
+---
+import {usePortableText} from 'astro-portabletext'
+
+const {value} = Astro.props
+const {render} = usePortableText(value)
+---
+
+<div class="prose">
+  {render()}
+</div>
+```
+
+## Reference
+
+- [astro-portabletext](https://github.com/theisel/astro-portabletext)
+- [Sanity + Astro guide](https://www.sanity.io/guides/sanity-astro)
diff --git a/skills/portable-text-serialization/rules/html.md b/skills/portable-text-serialization/rules/html.md
new file mode 100644
index 0000000..0eb388b
--- /dev/null
+++ b/skills/portable-text-serialization/rules/html.md
@@ -0,0 +1,115 @@
+---
+title: Serialize Portable Text to HTML
+description: Convert Portable Text to HTML strings server-side using @portabletext/to-html
+tags: [portable-text, html, server-side, serialization, email]
+---
+
+# Serialize Portable Text to HTML
+
+Use `@portabletext/to-html` for server-side HTML string generation — useful for RSS feeds, emails, static rendering, or any non-framework context.
+
+```bash
+npm install @portabletext/to-html
+```
+
+## Basic Usage
+
+```ts
+import {toHTML} from '@portabletext/to-html'
+
+const html = toHTML(portableTextBlocks, {components})
+```
+
+## ⚠️ Security: Escape HTML
+
+Unlike framework renderers, `toHTML` returns raw strings. **You must sanitize output.**
+
+Use `htm` + `vhtml` for safe templating, or the built-in `escapeHTML` utility:
+
+```ts
+import {toHTML, escapeHTML, uriLooksSafe} from '@portabletext/to-html'
+import htm from 'htm'
+import vhtml from 'vhtml'
+
+const h = htm.bind(vhtml)
+```
+
+## Custom Components
+
+Components are functions returning HTML strings:
+
+```ts
+const components = {
+  types: {
+    image: ({value}) => {
+      return `<figure>
+        <img src="${escapeHTML(value.url)}" alt="${escapeHTML(value.alt || '')}" />
+        ${value.caption ? `<figcaption>${escapeHTML(value.caption)}</figcaption>` : ''}
+      </figure>`
+    },
+    code: ({value}) => {
+      return `<pre data-language="${escapeHTML(value.language)}"><code>${escapeHTML(value.code)}</code></pre>`
+    },
+  },
+
+  marks: {
+    link: ({children, value}) => {
+      const href = value?.href || ''
+      if (!uriLooksSafe(href)) return children
+      const rel = href.startsWith('/') ? '' : ' rel="noreferrer noopener"'
+      return `<a href="${escapeHTML(href)}"${rel}>${children}</a>`
+    },
+    strong: ({children}) => `<strong>${children}</strong>`,
+    em: ({children}) => `<em>${children}</em>`,
+    highlight: ({children}) => `<mark>${children}</mark>`,
+  },
+
+  block: {
+    h1: ({children}) => `<h1>${children}</h1>`,
+    h2: ({children}) => `<h2>${children}</h2>`,
+    blockquote: ({children}) => `<blockquote>${children}</blockquote>`,
+    normal: ({children}) => `<p>${children}</p>`,
+  },
+
+  list: {
+    bullet: ({children}) => `<ul>${children}</ul>`,
+    number: ({children}) => `<ol>${children}</ol>`,
+  },
+
+  listItem: {
+    bullet: ({children}) => `<li>${children}</li>`,
+  },
+}
+```
+
+## With htm/vhtml (Auto-Escaped)
+
+Using `htm` + `vhtml` auto-escapes attribute values, preventing XSS from user content that could break out of attributes in raw template literals:
+
+```ts
+const components = {
+  types: {
+    image: ({value}) => h`<img src=${value.url} alt=${value.alt || ''} />`,
+  },
+  marks: {
+    link: ({children, value}) => {
+      if (!uriLooksSafe(value?.href || '')) return children
+      return h`<a href=${value.href}>${children}</a>`
+    },
+  },
+}
+```
+
+## Use Cases
+
+| Use Case | Why toHTML |
+|----------|-----------|
+| RSS/Atom feeds | Need raw HTML string |
+| Email templates | No framework runtime |
+| Static site generation | Pre-render at build time |
+| API responses | Return HTML from endpoints |
+| PDF generation | Feed HTML to PDF libraries |
+
+## Reference
+
+- [@portabletext/to-html](https://github.com/portabletext/to-html)
diff --git a/skills/portable-text-serialization/rules/markdown.md b/skills/portable-text-serialization/rules/markdown.md
new file mode 100644
index 0000000..9469e3c
--- /dev/null
+++ b/skills/portable-text-serialization/rules/markdown.md
@@ -0,0 +1,123 @@
+---
+title: Serialize Portable Text to Markdown
+description: Convert Portable Text to Markdown strings using @portabletext/markdown
+tags: [portable-text, markdown, serialization, conversion]
+---
+
+# Serialize Portable Text to Markdown
+
+Use `@portabletext/markdown` to convert PT blocks to Markdown strings. Useful for AI/LLM pipelines, static site generators, README generation, and anywhere Markdown is the target format.
+
+```bash
+npm install @portabletext/markdown
+```
+
+## Basic Usage
+
+```ts
+import {portableTextToMarkdown} from '@portabletext/markdown'
+
+const markdown = portableTextToMarkdown(portableTextBlocks)
+```
+
+## Built-in Support
+
+Out of the box, `portableTextToMarkdown` handles:
+
+- Headings (h1–h6)
+- Paragraphs
+- Bold (`**`), italic (`_`), inline code (`` ` ``), strikethrough (`~~`)
+- Links (`[text](url)`)
+- Blockquotes (`>`)
+- Ordered and unordered lists (including nested)
+- Code blocks (fenced with language)
+- Horizontal rules (`---`)
+- Images (`![alt](url)`)
+- Tables (GFM)
+
+## Built-in Type Renderers
+
+The library exports default renderers for common block object types. Enable them explicitly:
+
+```ts
+import {
+  portableTextToMarkdown,
+  DefaultCodeBlockRenderer,
+  DefaultImageRenderer,
+  DefaultHorizontalRuleRenderer,
+  DefaultTableRenderer,
+  DefaultHtmlRenderer,
+} from '@portabletext/markdown'
+
+const markdown = portableTextToMarkdown(blocks, {
+  types: {
+    'code': DefaultCodeBlockRenderer,           // {code, language?} → fenced code block
+    'image': DefaultImageRenderer,              // {src, alt?, title?} → ![alt](src "title")
+    'horizontal-rule': DefaultHorizontalRuleRenderer, // → ---
+    'table': DefaultTableRenderer,              // {rows, headerRows?} → GFM table
+    'html': DefaultHtmlRenderer,                // {html} → raw HTML
+  },
+})
+```
+
+## Custom Renderers
+
+Handle custom block types and marks with renderer functions:
+
+```ts
+const markdown = portableTextToMarkdown(blocks, {
+  // Custom block types — receives {value, index, isInline}
+  types: {
+    callout: ({value}) => `> **${value.title}**\n> ${value.text}`,
+    image: ({value, isInline}) => {
+      if (isInline) return ''
+      return `![${value.alt || ''}](${value.url})`
+    },
+  },
+
+  // Custom block style renderers — receives {value, children, index}
+  block: {
+    h1: ({children}) => `# ${children}`,
+    blockquote: ({children}) => `> ${children}`,
+  },
+
+  // Custom mark renderers — receives {value, children, text, markType, markKey}
+  marks: {
+    highlight: ({children}) => `==${children}==`,
+    internalLink: ({children, value}) => `[${children}](/docs/${value.slug})`,
+  },
+
+  // Custom list item renderer — receives {value, children, listIndex}
+  listItem: ({children}) => children,
+
+  // Control spacing between blocks — function, not string
+  blockSpacing: ({current, next}) => {
+    if (current.listItem && next.listItem) return '\n'
+    return undefined // use default (\n\n)
+  },
+
+  // Handle unknown types gracefully
+  unknownType: ({value}) => `<!-- Unknown type: ${value._type} -->`,
+  unknownMark: ({children}) => children,
+})
+```
+
+## Use Cases
+
+| Use Case | Why Markdown |
+|----------|-------------|
+| AI/LLM context | Models work well with Markdown input |
+| Static site generators | Hugo, Jekyll, Eleventy consume Markdown |
+| README generation | Generate docs from Sanity content |
+| Email (with converter) | Markdown → HTML for email templates |
+| Export/backup | Human-readable content export |
+| Documentation pipelines | Sanity as docs CMS, output as Markdown |
+
+## Bidirectional: Also Converts Markdown → PT
+
+The same package also provides `markdownToPortableText()` for the reverse direction. See the `portable-text-conversion` skill for details.
+
+## Reference
+
+- [@portabletext/markdown](https://github.com/portabletext/editor/tree/main/packages/markdown)
+- Part of the [portabletext/editor](https://github.com/portabletext/editor) monorepo
diff --git a/skills/portable-text-serialization/rules/plain-text.md b/skills/portable-text-serialization/rules/plain-text.md
new file mode 100644
index 0000000..f6dfbc0
--- /dev/null
+++ b/skills/portable-text-serialization/rules/plain-text.md
@@ -0,0 +1,66 @@
+---
+title: Extract Plain Text from Portable Text
+description: Convert Portable Text to plain text strings for search, meta descriptions, and summaries
+tags: [portable-text, plain-text, search, seo, extraction]
+---
+
+# Extract Plain Text from Portable Text
+
+Every `@portabletext/*` library exports a `toPlainText()` utility. Use it for meta descriptions, search indexing, summaries, and anywhere you need raw text without markup.
+
+## Usage
+
+```ts
+// From any framework library:
+import {toPlainText} from '@portabletext/react'
+// or: import {toPlainText} from '@portabletext/svelte'
+// or: import {toPlainText} from '@portabletext/vue'
+// or: import {toPlainText} from '@portabletext/to-html'
+
+const plainText = toPlainText(portableTextBlocks)
+```
+
+## Common Patterns
+
+### Meta Description
+
+```ts
+function getMetaDescription(body: PortableTextBlock[]): string {
+  const text = toPlainText(body)
+  return text.length > 160 ? text.slice(0, 157) + '...' : text
+}
+```
+
+### Search Indexing
+
+```ts
+// Index document content for search
+const searchableText = toPlainText(document.body)
+```
+
+### Slug Generation
+
+```ts
+import slugify from 'slugify'
+
+const slug = slugify(toPlainText(blocks), {lower: true, strict: true})
+```
+
+### Character/Word Count
+
+```ts
+const text = toPlainText(blocks)
+const wordCount = text.split(/\s+/).filter(Boolean).length
+const charCount = text.length
+```
+
+## Behavior
+
+- Extracts text from all `span` children in `block` type nodes
+- Joins blocks with double newlines (`\n\n`)
+- Ignores custom block types (images, code blocks, etc.)
+- Strips all marks (bold, links, etc.) — returns raw text only
+
+## Reference
+
+- [`toPlainText` source](https://github.com/portabletext/toolkit)
diff --git a/skills/portable-text-serialization/rules/react.md b/skills/portable-text-serialization/rules/react.md
new file mode 100644
index 0000000..ecd8eb7
--- /dev/null
+++ b/skills/portable-text-serialization/rules/react.md
@@ -0,0 +1,142 @@
+---
+title: Serialize Portable Text to React
+description: Render Portable Text in React and Next.js using @portabletext/react
+tags: [portable-text, react, nextjs, serialization, rendering]
+---
+
+# Serialize Portable Text to React
+
+Use `@portabletext/react` (or re-exported from `next-sanity`) to render PT in React/Next.js.
+
+```bash
+npm install @portabletext/react
+```
+
+## Basic Usage
+
+```tsx
+import {PortableText} from '@portabletext/react'
+// or: import {PortableText} from 'next-sanity'
+
+export function Body({value}: {value: PortableTextBlock[]}) {
+  return <PortableText value={value} components={components} />
+}
+```
+
+## Typed Components Object
+
+```tsx
+import type {PortableTextComponents} from '@portabletext/react'
+
+const components: PortableTextComponents = {
+  // Block styles
+  block: {
+    h1: ({children}) => <h1 className="text-4xl font-bold">{children}</h1>,
+    h2: ({children}) => <h2 className="text-3xl font-semibold">{children}</h2>,
+    blockquote: ({children}) => (
+      <blockquote className="border-l-4 pl-4 italic">{children}</blockquote>
+    ),
+    // 'normal' is the default paragraph style
+  },
+
+  // Custom block types
+  types: {
+    image: ({value}) => (
+      <img
+        src={urlFor(value).width(800).url()}
+        alt={value.alt || ''}
+        loading="lazy"
+      />
+    ),
+    code: ({value}) => (
+      <pre data-language={value.language}>
+        <code>{value.code}</code>
+      </pre>
+    ),
+  },
+
+  // Marks (decorators + annotations)
+  marks: {
+    // Decorator
+    highlight: ({children}) => (
+      <span className="bg-yellow-200">{children}</span>
+    ),
+    // Annotation
+    link: ({children, value}) => {
+      const rel = !value?.href?.startsWith('/') ? 'noreferrer noopener' : undefined
+      return (
+        <a href={value?.href} rel={rel}>
+          {children}
+        </a>
+      )
+    },
+    internalLink: ({children, value}) => (
+      <a href={`/${value?.slug}`}>{children}</a>
+    ),
+  },
+
+  // Lists
+  list: {
+    bullet: ({children}) => <ul className="list-disc ml-6">{children}</ul>,
+    number: ({children}) => <ol className="list-decimal ml-6">{children}</ol>,
+  },
+  listItem: {
+    bullet: ({children}) => <li>{children}</li>,
+  },
+}
+```
+
+## Props Reference
+
+| Component type | Props received |
+|---------------|----------------|
+| `block.*` | `{children, value}` — `value` is the full block |
+| `types.*` | `{value, isInline}` — `value` is the custom block data |
+| `marks.*` | `{children, value, markType, markKey}` — `value` is the markDef data |
+| `list.*` | `{children, value}` |
+| `listItem.*` | `{children, value}` |
+
+## Performance: Stabilize the Components Object
+
+❌ **Bad** — recreated every render:
+```tsx
+function Body({value}) {
+  return <PortableText value={value} components={{
+    types: {image: ({value}) => <img src={value.url} />}
+  }} />
+}
+```
+
+✅ **Good** — defined outside or memoized:
+```tsx
+const components: PortableTextComponents = {
+  types: {image: ({value}) => <img src={value.url} />}
+}
+
+function Body({value}) {
+  return <PortableText value={value} components={components} />
+}
+```
+
+## Plain Text Extraction
+
+```tsx
+import {toPlainText} from '@portabletext/react'
+
+const text = toPlainText(blocks) // for meta descriptions, search indexing
+```
+
+## Tailwind Typography Shortcut
+
+For simple blogs without custom blocks, wrap in `prose`:
+
+```tsx
+<article className="prose lg:prose-xl">
+  <PortableText value={value} />
+</article>
+```
+
+## Reference
+
+- [@portabletext/react](https://github.com/portabletext/react-portabletext)
+- [Sanity docs: Presenting Portable Text](https://www.sanity.io/docs/presenting-block-text)
diff --git a/skills/portable-text-serialization/rules/svelte.md b/skills/portable-text-serialization/rules/svelte.md
new file mode 100644
index 0000000..b5e1560
--- /dev/null
+++ b/skills/portable-text-serialization/rules/svelte.md
@@ -0,0 +1,134 @@
+---
+title: Serialize Portable Text to Svelte
+description: Render Portable Text in Svelte 5 and SvelteKit using @portabletext/svelte
+tags: [portable-text, svelte, sveltekit, serialization, rendering]
+---
+
+# Serialize Portable Text to Svelte
+
+Use `@portabletext/svelte` (requires Svelte 5+) to render PT in Svelte/SvelteKit.
+
+```bash
+npm install @portabletext/svelte
+```
+
+## Basic Usage
+
+```svelte
+<script>
+  import {PortableText} from '@portabletext/svelte'
+
+  let {value} = $props()
+</script>
+
+<PortableText {value} components={components} />
+```
+
+## Custom Components
+
+Svelte components receive a `portableText` prop with `value`, `global`, and `indexInParent`. Child content is passed via Svelte snippets.
+
+### Block Styles
+
+```svelte
+<!-- Heading.svelte -->
+<script>
+  let {portableText, children} = $props()
+  const {value} = portableText
+</script>
+
+{#if value.style === 'h1'}
+  <h1 class="text-4xl font-bold">{@render children()}</h1>
+{:else if value.style === 'h2'}
+  <h2 class="text-3xl font-semibold">{@render children()}</h2>
+{:else}
+  <p>{@render children()}</p>
+{/if}
+```
+
+### Custom Types
+
+```svelte
+<!-- ImageBlock.svelte -->
+<script>
+  let {portableText} = $props()
+  const {value} = portableText
+</script>
+
+<figure>
+  <img src={urlFor(value).width(800).url()} alt={value.alt || ''} />
+  {#if value.caption}
+    <figcaption>{value.caption}</figcaption>
+  {/if}
+</figure>
+```
+
+### Mark Components (Annotations)
+
+```svelte
+<!-- Link.svelte -->
+<script>
+  let {portableText, children} = $props()
+  const {value} = portableText
+  const href = value?.href || ''
+</script>
+
+<a {href} rel={href.startsWith('/') ? undefined : 'noreferrer noopener'}>
+  {@render children()}
+</a>
+```
+
+## Assembling Components
+
+```svelte
+<script>
+  import {PortableText} from '@portabletext/svelte'
+  import ImageBlock from './ImageBlock.svelte'
+  import CodeBlock from './CodeBlock.svelte'
+  import Link from './Link.svelte'
+
+  let {value} = $props()
+
+  const components = {
+    types: {
+      image: ImageBlock,
+      code: CodeBlock,
+    },
+    marks: {
+      link: Link,
+    },
+    block: {
+      h1: ({children}) => `<h1>${children}</h1>`, // or use a component
+    },
+  }
+</script>
+
+<PortableText {value} {components} />
+```
+
+## Passing Context
+
+Pass external data to all components via `context`:
+
+```svelte
+<PortableText
+  {value}
+  {components}
+  context={{dataset: 'production', footnotes}}
+/>
+```
+
+Access in components via `portableText.global.context`.
+
+## Plain Text Extraction
+
+```js
+import {toPlainText} from '@portabletext/svelte'
+
+const text = toPlainText(blocks)
+```
+
+## Reference
+
+- [@portabletext/svelte](https://github.com/portabletext/svelte-portabletext)
+- [Sanity + SvelteKit guide](https://www.sanity.io/guides/sanity-sveltekit)
diff --git a/skills/portable-text-serialization/rules/vue.md b/skills/portable-text-serialization/rules/vue.md
new file mode 100644
index 0000000..a088ea0
--- /dev/null
+++ b/skills/portable-text-serialization/rules/vue.md
@@ -0,0 +1,125 @@
+---
+title: Serialize Portable Text to Vue
+description: Render Portable Text in Vue 3 and Nuxt using @portabletext/vue
+tags: [portable-text, vue, nuxt, serialization, rendering]
+---
+
+# Serialize Portable Text to Vue
+
+Use `@portabletext/vue` to render PT in Vue 3 / Nuxt applications.
+
+```bash
+npm install @portabletext/vue
+```
+
+## Basic Usage
+
+```vue
+<script setup lang="ts">
+import {PortableText} from '@portabletext/vue'
+import type {PortableTextBlock} from '@portabletext/types'
+
+const props = defineProps<{value: PortableTextBlock[]}>()
+</script>
+
+<template>
+  <PortableText :value="value" :components="components" />
+</template>
+```
+
+## Custom Components
+
+Vue components can be defined as render functions, SFCs, or JSX.
+
+### Render Function Style (Concise)
+
+```ts
+import {h} from 'vue'
+import type {PortableTextVueComponents} from '@portabletext/vue'
+
+const components: PortableTextVueComponents = {
+  types: {
+    image: ({value}) => h('img', {src: urlFor(value).width(800).url(), alt: value.alt || ''}),
+    code: ({value}) => h('pre', {'data-language': value.language}, h('code', value.code)),
+  },
+
+  marks: {
+    link: ({value}, {slots}) => {
+      const rel = !value?.href?.startsWith('/') ? 'noreferrer noopener' : undefined
+      return h('a', {href: value?.href, rel}, slots.default?.())
+    },
+    highlight: (_, {slots}) => h('span', {class: 'bg-yellow-200'}, slots.default?.()),
+  },
+
+  block: {
+    h1: (_, {slots}) => h('h1', {class: 'text-4xl font-bold'}, slots.default?.()),
+    h2: (_, {slots}) => h('h2', {class: 'text-3xl font-semibold'}, slots.default?.()),
+    blockquote: (_, {slots}) => h('blockquote', {class: 'border-l-4 pl-4 italic'}, slots.default?.()),
+  },
+
+  list: {
+    bullet: (_, {slots}) => h('ul', {class: 'list-disc ml-6'}, slots.default?.()),
+    number: (_, {slots}) => h('ol', {class: 'list-decimal ml-6'}, slots.default?.()),
+  },
+}
+```
+
+### SFC Style (For Complex Components)
+
+```vue
+<!-- ImageBlock.vue -->
+<script setup lang="ts">
+import type {PortableTextComponentProps} from '@portabletext/vue'
+
+const props = defineProps<PortableTextComponentProps<{
+  asset: {_ref: string}
+  alt?: string
+  caption?: string
+}>>()
+</script>
+
+<template>
+  <figure>
+    <img :src="urlFor(value).width(800).url()" :alt="value.alt || ''" />
+    <figcaption v-if="value.caption">{{ value.caption }}</figcaption>
+  </figure>
+</template>
+```
+
+Then register:
+
+```ts
+import ImageBlock from './ImageBlock.vue'
+
+const components = {
+  types: {
+    image: ImageBlock,
+  },
+}
+```
+
+## Props Pattern
+
+Custom components receive:
+
+| Prop | Description |
+|------|-------------|
+| `value` | The block/mark data |
+| `index` | Position in parent array |
+| `isInline` | Whether this is an inline element |
+| `renderNode` | Internal renderer (rarely needed) |
+
+Children are passed via **slots** (`slots.default?.()`), not props.
+
+## Plain Text Extraction
+
+```ts
+import {toPlainText} from '@portabletext/vue'
+
+const text = toPlainText(blocks)
+```
+
+## Reference
+
+- [@portabletext/vue](https://github.com/portabletext/vue-portabletext)
+- [Sanity + Nuxt guide](https://www.sanity.io/guides/sanity-nuxt)