OpenParable
Skip to content
← Back to skills

Markstream Migration

Development
markstream-migration

Markstream Migration is an Agent Skill for development published in the Simon-He95/markstream-vue repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Audit and migrate existing Markdown rendering to Markstream. Use when Codex needs to replace another renderer, classify direct vs custom vs plugin-heavy usage, preserve behavior during adoption, migrate custom renderers into scoped Markstream overrides, or decide when `nodes` streaming is worth adopting.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/Simon-He95/markstream-vue/blob/HEAD/.agents/skills/markstream-migration/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/markstream-migration, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Markstream Migration

Use this skill when a repo already renders Markdown and the task is to adopt Markstream safely.

Read references/adoption-checklist.md before changing code.

Workflow

  1. Audit the repo's current renderer usage.
    • Search for markdown renderers, plugin chains, raw HTML handling, security props, and custom renderers.
    • List every call site that will be touched.
  2. Classify the migration.
    • direct: simple string-in renderer swap.
    • renderer-custom: custom renderers but limited parser work.
    • plugin-heavy: remark, rehype, markdown-it, or other transform-heavy pipelines.
    • security-heavy: allow or deny lists, URL rewriting, sanitization, or raw HTML policies.
  3. Swap the renderer first.
    • Introduce the correct Markstream package and CSS.
    • Import Markstream CSS through the package CSS subpath; do not rely on the renderer import to inject styles.
    • Preserve user-visible behavior before adding richer Markstream-only features.
    • Audit whether the old renderer allowed broad raw HTML or Mermaid loose-mode HTML labels before claiming parity.
  4. Migrate custom renderers.
    • Convert tag-based renderers into node-type overrides with scoped setCustomComponents.
    • For trusted tag-like content, prefer customHtmlTags.
  5. Review gaps honestly.
    • Do not claim 1:1 parity where none exists.
    • Call out parser, plugin, security, or HTML behavior that still needs manual review.
  6. Consider renderer mode and smooth streaming before jumping to nodes.
    • For Vue 3, choose mode="chat" for AI/SSE output, mode="docs" for rich document surfaces, and mode="minimal" for lightweight non-chat surfaces.
    • If the app streams content and only needs pacing, smooth-streaming="auto" (the default) handles it without requiring nodes.
    • Move to nodes only when the app needs custom AST control, worker preparsing, or high-frequency structural updates.
    • When smooth streaming is on outside Vue 3 mode="chat" defaults, pair it with :fade="false".
    • Streaming vs recovering history: when migrating a chat UI, keep mode="chat" on the same chat row and switch pacing/animation props instead. Vue 3 streaming: mode="chat", smooth-streaming="auto", :fade="false". Vue 3 completed chat history: mode="chat", :smooth-streaming="false", optional :fade="true". Use mode="docs" only for separate rich document surfaces.
  7. Validate and summarize.
    • Run the smallest relevant tests or build.
    • Report direct mappings, TODOs, and remaining verification work.

Default Decisions

  • Renderer swap first, streaming optimization second.
  • Smooth streaming is an intermediate option between "just content" and "full nodes migration": it paces visible output without requiring AST control.
  • Preserve safety over feature parity when HTML or security rules are involved.
  • Prefer explicit TODOs over vague claims.
  • Recommend against migration when the current stack depends heavily on transforms that Markstream does not mirror directly.
  • When preserving trusted legacy behavior is necessary, use scoped htmlPolicy / html-policy="trusted" and mermaidProps.isStrict = false instead of weakening defaults everywhere.

Useful Doc Targets

  • docs/guide/react-markdown-migration.md
  • docs/guide/react-markdown-migration-cookbook.md
  • docs/guide/ai-chat-streaming.md
  • docs/guide/installation.md
  • docs/guide/component-overrides.md
  • docs/guide/advanced.md