Portable Text Conversion

What it does

When your agent uses it

• Migrating content from legacy CMSs
• Markdown into Sanity
• Building content pipelines that ingest external content
• Converting rich text between formats

Example prompts

• “/portable-text-conversion”

Workflow steps

3 steps, taken from the first numbered list in SKILL.md.

1. 1markdownToPortableText — Convert Markdown directly using @portabletext/markdown (recommended for Markdown)
2. 2htmlToBlocks — Parse HTML into PT blocks using @portabletext/block-tools (for HTML migration)
3. 3Manual construction — Build PT blocks directly from any source (APIs, databases, etc.)

What it can do on your machine

Read from SKILL.md and the folder at commit 88d6cdf. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  No scripts in the folder and no shell commands in SKILL.md (its code samples are json).

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  No URLs in SKILL.md.

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Portable Text Conversion loads about 664 tokens when it runs. Until then it costs about 129 tokens; SKILL.md has 169 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~129

When it runs · the whole SKILL.md, loaded when a task matches

~664

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from sanity-io/agent-toolkit at commit 88d6cdf, republished under its MIT licence (© sanity-io). 169 words, ~664 tokens.

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

metadata.version

1.0.0

[
  {
    "_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"}
  }
]

© sanity-io, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files in skills/portable-text-conversion of sanity-io/agent-toolkit.

• SKILL.md
• rules/html-to-pt.md
• rules/manual-construction.md
• rules/markdown-to-pt.md

Open the folder on GitHubat commit 88d6cdf

Used in 1 other repository

We found 1 copy of this SKILL.md (exact, near-identical or edited) in other folders, from 1 other GitHub owner. This page covers the copy in sanity-io/agent-toolkit, which our catalogue first saw on October 7, 2026.

• robotostudio/turbo-start-sanity.claude/skills/portable-text-conversion