Skillzwave

Build a Documentation Pipeline in Minutes, Not Weeks

Updated
10 min read

Seven AI agents just built an entire documentation pipeline without writing a single line of code. Here's how you can do it too - and solve the common pain of converting Markdown with Mermaid diagrams into stakeholder-ready PDFs and Word documents.

Documentation pipeline showing flow from Markdown input through seven agents to PDF and Word output
The complete documentation pipeline from Markdown to professional documents

Pipeline Results

4
Markdown files processed
8
Diagrams extracted
5
PDFs created
0
Lines of code written

The Problem That Started Everything

You know the pain: Markdown files with Mermaid diagrams that stakeholders can't view. Management wants Word docs for tracking changes. Everyone needs PDFs. Converting between formats triggers UTF-8 errors that break everything.

The traditional solution requires:

  • Expertise in Python or another scripting language
  • Mastery of regular expressions (regex)
  • Complex error handling patterns
  • Knowledge of character encoding
  • Days or weeks of development time

The Claude Code solution requires: the ability to describe what you want in English.

Prerequisites

Before building the pipeline, install the required tools: 

# Install Mermaid CLI for diagram generation
npm install -g @mermaid-js/mermaid-cli

# Install Pandoc for document conversion
brew install pandoc  # macOS
# or: apt-get install pandoc  # Ubuntu/Debian
# or: choco install pandoc  # Windows

Step 1: Create the Directory Structure

mkdir -p .claude/agents
mkdir -p docs/{markdown,mermaid,images,pdf,word}

Step 2: Define the Workflow Orchestrator

The orchestrator is the conductor of your agent orchestra. It never does the actual work - it just coordinates the specialists.

.claude/agents/workflow-orchestrator.md

---
name: workflow-orchestrator
description: Main coordinator for mermaid-to-PDF conversion workflow
tools: Read, Write, Bash, Glob, Task
---

You are the Workflow Orchestrator for the documentation pipeline.

## Workflow Sequence

1. Initialize: Set up directory structure via `file-organizer`
2. Extract: Use `mermaid-extractor` to find all diagrams
3. Generate: Invoke `image-generator` for PNG creation
4. Rebuild: Call `markdown-rebuilder` to update documents
5. Convert: Use `pandoc-converter` for PDF/Word generation
6. Handle Errors: Activate `utf-sanitizer` if encoding issues occur
7. Finalize: Organize outputs with `file-organizer`

## Error Handling Strategy

- Isolate failures to individual files
- Attempt recovery before failing entire pipeline
- Provide detailed error reports for debugging
- Continue processing other files even if one fails

Always delegate specific tasks to specialized agents.

Step 3: Define the Mermaid Extractor

This agent scans Markdown files like a detective, identifying every Mermaid code block and extracting it into separate files.

.claude/agents/mermaid-extractor.md

---
name: mermaid-extractor
tools: Read, Write, Glob
---

You extract mermaid diagram code blocks from markdown files.

## Extraction Process

1. **Pattern Recognition**
   - Scan for ```mermaid code blocks
   - Identify diagram type (flowchart, sequence, etc.)
   - Note line numbers for context preservation

2. **File Naming Convention**
   - Format: `_NN_.mmd`
   - NN: Two-digit sequence (01, 02, etc.)

3. **Output Organization**
   - Save to docs/mermaid/
   - Create manifest of extracted diagrams

Step 4: Define the Image Generator

This agent converts Mermaid code to PNG images using the Mermaid CLI.

.claude/agents/image-generator.md

---
name: image-generator
tools: Bash, Write, Read
---

You generate PNG/SVG images from .mmd files using mermaid CLI.

## Image Generation Process

1. **Environment Verification**
   - Check mermaid CLI installation: `mmdc --version`
   - Verify input directory exists

2. **CLI Command Execution**
   mmdc -i input.mmd -o output.png --theme default --width 800

3. **Output Management**
   - Save to docs/images/
   - Maintain naming consistency with source files

Step 5: Define the Markdown Rebuilder

.claude/agents/markdown-rebuilder.md

---
name: markdown-rebuilder
tools: Read, Write
---

You create new markdown files with mermaid code blocks
replaced by image links.

## Rebuild Process

1. Read original markdown file
2. Find each mermaid code block
3. Replace with image reference: ![diagram](../images/name.png)
4. Save to docs/markdown/ with same filename

Step 6: Define the Pandoc Converter

.claude/agents/pandoc-converter.md

---
name: pandoc-converter
tools: Bash, Read, Write
---

You generate PDF and Word documents from processed markdown.

## Conversion Commands

# For PDF
pandoc input.md -o output.pdf --pdf-engine=xelatex

# For Word
pandoc input.md -o output.docx

## Error Detection

Watch for UTF-8 encoding errors in output.
If detected, signal that utf-sanitizer is needed.

Step 7: Define the UTF Sanitizer

This agent only activates when UTF-8 errors occur. It intelligently replaces problematic characters with ASCII equivalents.

.claude/agents/utf-sanitizer.md

---
name: utf-sanitizer
tools: Read, Write, Bash
---

You clean UTF-8 encoding issues from markdown files.

## Common Replacements

- Smart quotes -> straight quotes
- Em dashes -> regular dashes
- Ellipsis character -> three periods
- Non-breaking spaces -> regular spaces

## Process

1. Read file with encoding errors
2. Apply character replacements
3. Save cleaned version
4. Signal pandoc-converter to retry

Step 8: Define the File Organizer

.claude/agents/file-organizer.md

---
name: file-organizer
tools: Bash, Write
---

You manage directory structure and file organization.

## Responsibilities

1. Create required directories at pipeline start
2. Move generated files to proper locations
3. Clean up temporary files at pipeline end
4. Generate summary report of outputs

Running the Pipeline

With all agents defined, running the pipeline is remarkably simple: 

# In Claude Code, just say:
> Use workflow-orchestrator to process all markdown files
  and generate PDFs and Word documents

Or even simpler: 

> Generate mermaid diagrams, word docs, pdf docs, everything... go

Real-World Results

From an actual implementation:

  • Markdown files processed 4
  • Mermaid diagrams extracted and converted 8
  • PNG images generated 8
  • PDF documents created 5
  • Word documents produced 4
  • UTF-8 errors automatically resolved 27
  • Total time ~15 minutes
  • Human intervention Zero

Why This Works

The Orchestrator Pattern is Key

Having one agent coordinate others transformed inconsistent results into reliable automation. The orchestrator pattern provides:

  • Clear delegation - Each agent has one job
  • Error isolation - One failure doesn't crash everything
  • Automatic recovery - UTF sanitizer activates only when needed
  • State management - Orchestrator tracks progress through the pipeline

Self-Healing Behavior

Unlike traditional code, agents can:

  • Install missing dependencies
  • Fix version mismatches
  • Retry failed operations with different approaches
  • Ask for clarification when needed

Customizing the Pipeline

The beauty of this approach is how easy it is to extend. Want to add Confluence upload? Create a new agent:

.claude/agents/confluence-uploader.md

---
name: confluence-uploader
tools: Bash, Read
---

You upload generated documents to Confluence.

## Process

1. Read the generated PDF or Word document
2. Use Confluence API to create/update page
3. Attach document to the page
4. Report success with page URL

Then update the orchestrator's workflow sequence to include the new step.

The Bottom Line

This pipeline replaced days to weeks of traditional development with minutes of agent configuration. The system is more maintainable, adaptable, and accessible than any code that could have been written manually.

Most remarkably? It worked perfectly on the first attempt. No debugging. No Stack Overflow. Just natural language transforming into a production-ready system.

"The future of automation isn't about writing better code - it's about orchestrating intelligent agents. And that future is available today with Claude Code."

What Will You Automate?

Ready to build your own agent orchestration? Browse existing skills for inspiration or explore more advanced patterns.

Browse Skills Advanced Patterns