conversation-json-to-md
Use when converting chat export JSON into per-conversation Markdown files with preserved user-assistant Q/A and normalized headings.
How do I install this agent skill?
npx skills add https://github.com/yangsonhung/awesome-agent-skills --skill conversation-json-to-mdIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill converts chat export JSON files into Markdown per-conversation. It runs a local Python script to perform the conversion and does not require network access. The verdict is low because the skill processes untrusted chat data which the agent is then instructed to review, creating a potential surface for indirect prompt injection.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/2 files flagged
What does this agent skill do?
Conversation JSON To MD
Overview
Convert a user-provided chat-export JSON into multiple Markdown files with consistent Q/A formatting. The workflow keeps only user-assistant exchanges, writes one conversation per Markdown file, preserves answer Markdown, and runs a second pass to normalize filenames and heading structure.
When to Use
Use this skill when the user asks for:
- Splitting one JSON chat export into many
.mdfiles - One conversation per markdown file
- Keeping only question/answer content from user and assistant
- Renaming response sections to
Answer - 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>### Answer
- 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_listwithphase=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>
### Answer
<assistant answer markdown>
## <user question 2>
### Answer
<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
### Answer
- 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
## REQUESTor## RESPONSEheaders in output - Response blocks are present as
### Answer - Output preserves markdown rendering correctly
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/yangsonhung/awesome-agent-skills/conversation-json-to-md">View conversation-json-to-md on skillZs</a>