# Conversation Json To Md

> Use when converting chat export JSON into per-conversation Markdown files with preserved user-assistant Q/A and normalized headings.

- **Type:** Skill
- **Install:** `agentstack add skill-yangsonhung-awesome-agent-skills-conversation-json-to-md`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [YangsonHung](https://agentstack.voostack.com/s/yangsonhung)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [YangsonHung](https://github.com/YangsonHung)
- **Source:** https://github.com/YangsonHung/awesome-agent-skills/tree/main/skills/en/conversation-json-to-md

## Install

```sh
agentstack add skill-yangsonhung-awesome-agent-skills-conversation-json-to-md
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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 `.md` files
- 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

1. Read the input file path provided by the user. Do not assume default file names.
2. Detect conversation/message structure automatically.
3. Export one markdown file per conversation.
4. Keep only user/assistant Q&A content.
5. Format each Q/A block as:
   - `## `
   - `### Answer`
6. Preserve answer markdown and demote answer-internal heading levels by one level.
7. 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

```bash
python3 scripts/convert_conversations.py \
  --input /path/to/.json \
  --output-dir /path/to/output_md \
  --clean
```

## Output Format

Each output file uses this structure:

```md
# 

## 
### Answer

## 
### Answer

```

## Second-Pass Formatting (Required)

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

1. Filename normalization:
- Keep title-only naming
- Remove illegal filename characters
- Resolve duplicates with ` (2)`, ` (3)`...

2. Heading normalization:
- Keep only one H1: `# `
- Ensure questions are H2
- Ensure responses are exactly `### Answer`

3. Body normalization:
- Keep answer body markdown
- Keep answer-internal heading demotion

4. 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 `### Answer`
- Output preserves markdown rendering correctly

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [YangsonHung](https://github.com/YangsonHung)
- **Source:** [YangsonHung/awesome-agent-skills](https://github.com/YangsonHung/awesome-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-yangsonhung-awesome-agent-skills-conversation-json-to-md
- Seller: https://agentstack.voostack.com/s/yangsonhung
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.