What input formats are supported?

The script supports common export formats including mapping trees (root/children/fragments), Qwen-like exports (data[].chat.messages[], content_list phase=answer), Claude-style exports, and generic arrays (messages, history, conversations, etc.).

How are questions and answers formatted in the output?

Questions are rendered as '## ' and answers as '### 回答', with the answer body preserved and any internal headings demoted by one level.

How are filenames and headings normalized after export?

A second-pass normalization fixes illegal filename characters, resolves duplicates by appending ' (2)', ' (3)', and ensures only one top-level title ('# ') with '##' for questions and '### 回答' for answers.

conversation-json-to-md

npx machina-cli add skill YangsonHung/awesome-agent-skills/conversation-json-to-md --openclaw

Files (1)

SKILL.md

3.2 KB

Conversation JSON To MD

Convert a user-provided chat-export JSON into multiple Markdown files with consistent Q/A formatting.

When to Use

Use this skill when the user asks for:

Splitting one JSON chat export into many .md files
One conversation per markdown file
Keeping only question/answer content from user and assistant
Renaming response section to 回答
Normalizing exported files with a second formatting pass

Do not use

Do not use this skill for:

Plain text transformation that does not involve JSON chat exports
Non-conversation JSON processing tasks
Requests requiring semantic summarization instead of structural conversion

Instructions

Read the input file path provided by the user. Do not assume default file names.
Detect conversation/message structure automatically.
Export one markdown file per conversation.
Keep only user/assistant Q&A content.
Format each Q/A block as:
- ## <question text>
- ### 回答
Preserve answer markdown and demote answer-internal heading levels by one level.
Run an independent second-pass formatting check and fix naming/title structure before final delivery.

Supported Input Structures

The bundled script supports common export formats including:

DeepSeek/ChatGPT-like mapping tree (mapping/root/children/fragments)
Qwen-like exports (data[].chat.messages[], content_list with phase=answer)
Claude web export style (list[{ name, chat_messages: [...] }])
Generic message arrays (messages, history, conversations, dialog, turns)
Pair fields (question-answer, prompt-response, input-output)

If format detection fails, stop and ask the user for a sample snippet, then extend parsing rules.

Run Script

python3 scripts/convert_conversations.py \
  --input /path/to/<user-provided>.json \
  --output-dir /path/to/output_md \
  --clean

Output Format

Each output file uses this structure:

# <conversation title>

## <user question 1>
### 回答
<assistant answer markdown>

## <user question 2>
### 回答
<assistant answer markdown>

Second-Pass Formatting (Required)

After export, run a second-pass check/fix on output files:

Filename normalization:

Keep title-only naming
Remove illegal filename characters
Resolve duplicates with (2), (3)...

Heading normalization:

Keep only one H1: # <conversation title>
Ensure questions are H2
Ensure responses are exactly ### 回答

Body normalization:

Keep answer body markdown
Keep answer-internal heading demotion

Final verification:

Confirm no files still violate naming or heading rules

Validation Checklist

File count equals detected conversation count
No random suffixes in filenames
No ## REQUEST or ## RESPONSE headers in output
Response blocks are present as ### 回答
Output preserves markdown rendering correctly

Source

git clone https://github.com/YangsonHung/awesome-agent-skills/blob/main/skills/en/conversation-json-to-md/SKILL.mdView on GitHub

Overview

Converts a user-provided chat-export JSON into multiple Markdown files, one per conversation. It preserves only the user and assistant Q/A, formats each question as a heading, keeps the assistant's Markdown responses, and runs a second-pass normalization to fix filenames and headings (including renaming the response section to 回答).

How This Skill Works

Reads the input, auto-detects the conversation structure, and exports one Markdown file per conversation. Each Q/A block is formatted as '## <question>' and '### 回答', preserving the answer Markdown and demoting internal headings by one level; a second-pass check fixes naming and title structure before delivery.

When to Use It

Split a single JSON chat export into multiple Markdown files (one file per conversation).
Create a separate Markdown file for every conversation in the export.
Keep only user questions and assistant answers, discarding other metadata.
Rename the answer section to the Chinese header '回答'.
Run a second-pass normalization to clean filenames and headings after export.

Quick Start

Step 1: Run the script with --input /path/to/file.json --output-dir /path/to/output --clean
Step 2: Review the generated MD files to verify Q/A formatting and per-conversation files
Step 3: Run the second-pass normalization if needed and confirm no naming/heading violations

Best Practices

Ensure the input JSON's structure is detectable by the script.
Limit content to user/assistant Q/A and avoid semantic changes.
Verify each conversation yields exactly one Markdown file.
Check heading levels: Q as H2 ('##') and answer header as '### 回答'.
Run the second-pass normalization and validation to catch illegal characters or duplicates.

Example Use Cases

Export with 3 conversations becomes 3 separate MD files, each with properly formatted Q/A blocks.
A long QA thread is split, and inner headings in answers are demoted correctly.
Filenames are normalized to safe titles, removing illegal characters.
Only user prompts and assistant replies are preserved in output.
No stray headers like '## REQUEST' or '## RESPONSE' remain after processing.

Frequently Asked Questions

Add this skill to your agents