synthkit 0.3.0

Convert AI-generated Markdown into production-ready documents

Synthkit

Synthkit was born from building Satori — a platform that deploys AI agents to scale security operations. When AI generates content at volume, you need tooling to bridge the gap between raw output and what the organization actually needs. Synthkit is that bridge.

A "last-mile" toolkit for working with generative AI. Synthkit bridges the gap between raw LLM output and production-ready deliverables through:

• Document conversion — Transform AI-generated Markdown into Word, HTML, PDF, or clipboard-ready email
• Structured exploration — Guided discovery sessions that draw out your domain knowledge before generating anything
• Prompt templates — Curated templates for structured AI interactions (reports, emails, analysis)
• Guidelines — Reference standards and style guides to steer AI output quality

Installation

# Run directly with uvx (no install needed)
uvx synthkit html document.md

# Or install globally
uv tool install synthkit

# Or install with pip
pip install synthkit

Pandoc is bundled automatically via pypandoc_binary — no separate install needed.

Claude Code Plugin

Synthkit is also available as a Claude Code plugin, adding skills directly into your coding assistant:

/plugin install synthkit

This gives you slash commands inside Claude Code:

Command	Description
/synthkit:explore-with-me	Guided exploration — Claude interviews you to structure your thinking before writing anything
/synthkit:init-discovery	Scaffold a multi-session discovery project — interviews you and generates CLAUDE.md + working files
/synthkit:md2pdf	Convert markdown to PDF
/synthkit:md2docx	Convert markdown to Word
/synthkit:md2html	Convert markdown to HTML
/synthkit:md2email	Convert markdown to clipboard-ready email

The explore-with-me skill is particularly useful for thinking through architecture decisions, incident postmortems, risk assessments, or any situation where you know more than the AI and premature generation would anchor on the wrong framing.

Document Conversion

System dependencies for PDF

PDF conversion uses WeasyPrint, which requires system libraries:

Platform	Install command
macOS	brew install pango
Ubuntu/Debian	apt install libpango1.0-dev libcairo2-dev libgdk-pixbuf2.0-dev
Windows	See WeasyPrint docs

doc, html, and email commands work without these.

Usage

Unified CLI

synthkit doc report.md           # → report.docx
synthkit html report.md          # → report.html
synthkit pdf report.md           # → report.pdf
synthkit email report.md         # → clipboard

# Batch processing
synthkit doc *.md
synthkit html *.md --hard-breaks

# Mermaid diagrams (requires mermaid-filter)
synthkit html report.md --mermaid

Backward-compatible commands

md2doc report.md
md2html report.md
md2pdf report.md
md2email report.md

Options

Flag	Description
--hard-breaks	Preserve line breaks from source markdown
--mermaid	Enable Mermaid diagram rendering (requires mermaid-filter)

Configuration

Each converter looks for optional config files under ~/.config/<toolname>/:

Converter	Config Files
doc	~/.config/md2doc/reference.docx
email	~/.config/md2email/style.css
html	~/.config/md2html/style.css
pdf	~/.config/md2pdf/style.css

Structured Exploration

Synthkit includes a method called Structured Elicitation for using AI as an interviewer rather than a generator — the human holds domain knowledge, and the AI structures the thinking, identifies gaps, and pressure-tests assumptions before anything gets written.

There are two ways to use it, depending on scope:

Approach	When to use	How
Skill (/synthkit:explore-with-me)	Single-session exploration — a decision, a diagnosis, a quick risk assessment	Invoke the slash command in Claude Code. Claude runs the session interactively and writes findings when done.
Skill (/synthkit:init-discovery)	Multi-session initiative — a weeks-long project with multiple stakeholders, evolving deliverables, and a file structure	Invoke the slash command. Claude interviews you about the initiative and generates a customized CLAUDE.md plus working file structure.

Use explore-with-me for things you can resolve in one conversation. Use init-discovery to set up sustained work where you need Claude to maintain context across sessions and produce multiple evolving documents.

Both use the same underlying method documented in skills/explore-with-me/references/structured-elicitation.md.

Prompt Templates

The prompt-templates/ directory contains pointers to canonical templates maintained alongside their skills. If you're using Claude Code, the skills fill these in for you automatically.

Template	Canonical source	Claude Code shortcut
structured-discovery.md	skills/init-discovery/references/	/synthkit:init-discovery

Guidelines

The guidelines/ directory contains reference standards and methods that can be provided as context to AI models.

Guideline	Purpose
structured-elicitation.md	The Structured Elicitation method (canonical source: skills/explore-with-me/references/)
markdown-conventions.md	Markdown formatting standards for AI-generated content

Testing

# Run tests
uv run --extra dev pytest

# With coverage
uv run --extra dev pytest --cov=synthkit --cov-report=term-missing

Tests run automatically on push/PR to main across Python 3.10-3.13 on Linux, macOS, and Windows.

Repository Structure

├── .claude-plugin/        # Claude Code plugin metadata
│   └── plugin.json
├── .github/workflows/
│   ├── tests.yml          # CI: test on push/PR to main
│   └── publish.yml        # CD: publish to PyPI on release
├── pyproject.toml
├── src/synthkit/          # Python package
│   ├── cli.py             # Click CLI with subcommands
│   ├── base.py            # Shared conversion logic
│   ├── doc.py             # Word conversion
│   ├── email.py           # Email clipboard conversion
│   ├── html.py            # HTML conversion
│   └── pdf.py             # PDF conversion (via WeasyPrint)
├── skills/                # Claude Code plugin skills
│   ├── explore-with-me/   # Structured exploration interviews
│   ├── init-discovery/    # Multi-session project scaffolding
│   ├── md2pdf/            # PDF conversion skill
│   ├── md2docx/           # Word conversion skill
│   ├── md2html/           # HTML conversion skill
│   └── md2email/          # Email conversion skill
├── hooks/                 # Claude Code plugin hooks
│   └── hooks.json         # SessionStart dependency check
├── tests/                 # Test suite (pytest)
│   ├── conftest.py        # Shared fixtures
│   ├── test_base.py       # Base module tests
│   ├── test_cli.py        # CLI + integration tests
│   ├── test_doc.py        # Word converter tests
│   ├── test_email.py      # Email converter tests
│   ├── test_html.py       # HTML converter tests
│   └── test_pdf.py        # PDF converter tests
├── style.css              # Default stylesheet
├── prompt-templates/      # AI interaction prompt templates
└── guidelines/            # Reference guidelines

Dependencies

Package	Purpose	Bundled?
click	CLI framework	pip
pypandoc_binary	Pandoc document converter	pip (includes binary)
pyperclip	Cross-platform clipboard	pip
weasyprint	PDF engine	pip (needs system libs)
mermaid-filter	Mermaid diagrams	Optional, external