vm-document-markdown-converter

# VM Document Markdown Converter

Converts documents from various formats into well-structured markdown files for agent consumption.

## Brownfield Context

In brownfield workflows, requirement input arrives in many formats — Word documents, PDFs, Excel worksheets, legacy system appreciation documents, and HTML pages. This skill normalizes those formats into agent-processable markdown so that Change Impact Analysis, Requirement Gap Analysis, and other agents can reason over the content regardless of source format.

## When to Use This Skill

- Converting requirement documents (Word, PDF) to markdown for change impact analysis
- Processing system appreciation documents for gap analysis
- Ingesting legacy specifications, SRS documents, or functional specs
- Converting Excel-based requirement trackers into structured markdown tables
- Standardizing any external document for downstream agent processing

## Unitary Function

**ONE RESPONSIBILITY:** Convert document formats to well-structured markdown with intelligent section organization

**NOT RESPONSIBLE FOR:**
- Document metadata extraction
- Document summarization (that is the calling agent's responsibility)
- Document validation or compliance checking
- Content generation or rewriting

## Supported Formats

- PDF (`.pdf`)
- Microsoft Word (`.docx`, `.doc`)
- Microsoft Excel (`.xlsx`, `.xls`, `.csv`)
- Microsoft PowerPoint (`.pptx`, `.ppt`)
- HTML (`.html`, `.htm`)
- XML (`.xml`)
- Images with OCR (`.jpg`, `.png`, `.gif`, `.tiff`)
- Plain text (`.txt`), Rich Text Format (`.rtf`)

## Input

```json
{
  "file_path": "Absolute path to document file to convert",
  "output_path": "Optional: where to write the markdown file",
  "preserve_tables": true,
  "section_headers": true
}
```

## Output

```json
{
  "conversion_id": "uuid",
  "generated_by": {
    "skill": "vm-document-markdown-converter",
    "version": "1.0.0"
  },
  "source_file": "string",
  "output_file": "string",
  "format_detected": "pdf|docx|xlsx|html|...",
  "sections_found": 0,
  "tables_found": 0,
  "markdown_content": "Full markdown text of converted document"
}
```

## Conversion Strategy

1. Use markitdown MCP server to perform the raw format conversion
2. Analyze the output structure and identify logical section boundaries
3. Normalize heading hierarchy (ensure H1 → H2 → H3 nesting is consistent)
4. Preserve tables as markdown tables
5. Remove formatting artifacts (page numbers, headers/footers repeated on each page)
6. Write the normalized markdown to the output path

## Error Handling

- If markitdown MCP is unavailable: report the dependency gap clearly — do not attempt to parse binary formats with text tools
- If the file is password-protected: report the protection status and stop
- If OCR is required but no image processing is available: report the limitation