Markstream Migration
Developmentmarkstream-migrationMarkstream 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
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
- 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.
- 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.
- 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.
- Migrate custom renderers.
- Convert tag-based renderers into node-type overrides with scoped
setCustomComponents. - For trusted tag-like content, prefer
customHtmlTags.
- Convert tag-based renderers into node-type overrides with scoped
- 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.
- 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, andmode="minimal"for lightweight non-chat surfaces. - If the app streams
contentand only needs pacing,smooth-streaming="auto"(the default) handles it without requiringnodes. - Move to
nodesonly 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". Usemode="docs"only for separate rich document surfaces.
- For Vue 3, choose
- 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"andmermaidProps.isStrict = falseinstead of weakening defaults everywhere.
Useful Doc Targets
docs/guide/react-markdown-migration.mddocs/guide/react-markdown-migration-cookbook.mddocs/guide/ai-chat-streaming.mddocs/guide/installation.mddocs/guide/component-overrides.mddocs/guide/advanced.md