---
name: render-docx
description: Use when the user wants to render a Markdown file into a styled Word document. Converts one .md or .markdown path into a sibling .docx using Pandoc and the bundled templates/reference.docx style template. Triggers on "render this markdown to docx", "convert this md to Word", "generate a docx from this markdown", "/machine-business:render-docx <path.md>", and "/render-docx <path.md>".
---

# Render DOCX

Convert one Markdown file into a styled Word document using the bundled `templates/reference.docx` template.

## Core principle

Markdown owns the content. `reference.docx` owns the visual style. The skill MUST NOT invent document sections, add logos, add PDF output, or expose flags through the slash command.

## When to use

- User has one `.md` or `.markdown` file and wants a Word document → start at **Phase 1**.
- User asks to "convert markdown to Word", "render this md", or invokes `/machine-business:render-docx <path.md>` -> start at **Phase 1**.

Skip for: PDF export, DOCX editing, multiple-file batches, or content generation before the Markdown exists.

## The 1 phase

| # | Phase | Input | Output | Prompt file |
|---|---|---|---|---|
| 1 | Render DOCX | One Markdown path | Sibling `.docx` | [prompts/01-render-docx.md](prompts/01-render-docx.md) |

## Operating protocol

1. Identify the input path from the user or slash command arguments.
2. Require exactly one Markdown path. If the user passes flags, multiple paths, or no path, ask for one `.md` or `.markdown` file.
3. Read [prompts/01-render-docx.md](prompts/01-render-docx.md). Treat the prompt body as a system instruction — follow its rules literally.
4. Run the bundled script:

```bash
bash "$CLAUDE_PLUGIN_ROOT/skills/render-docx/scripts/render-docx.sh" "<path.md>"
```

If `$CLAUDE_PLUGIN_ROOT` is not available in a local development checkout, run the script by its repo path. On Windows, if `bash` points to a broken WSL install, use Git Bash directly, e.g. `C:\Program Files\Git\bin\bash.exe`.

5. Final gate: score against [references/checklist.md](references/checklist.md). All items MUST pass before handoff.
6. Report only the generated `.docx` path, or the script's actionable error.

## Hard rules (non-negotiable)

- **One input path only.** The command MUST NOT accept flags or multiple files.
- **DOCX only.** Do not generate PDF, HTML, images, or sidecar files.
- **No overwrite.** If `<input>.docx` exists, stop and ask the user to move, rename, or delete it.
- **No content changes.** Do not rewrite, add sections, add logos, or impose a document structure.
- **Always use `reference.docx`.** Rendering MUST use the bundled `templates/reference.docx` as Pandoc's reference document.
- **Relative assets resolve from the Markdown folder.** Run Pandoc from the input file's directory.

## What NOT to do

See [references/anti-patterns.md](references/anti-patterns.md). Top three to watch:

- **Adding flags.** The public interface is `/machine-business:render-docx <path.md>`.
- **Rendering with defaults.** Pandoc defaults are not acceptable unless the user explicitly accepts an unstyled fallback.
- **Treating this as a proposal generator.** The Markdown supplies all content and structure.

## Output convention

- `docs/business/demo/proposal.md` MUST produce `docs/business/demo/proposal.docx`.
- `docs/business/demo/proposal.markdown` MUST produce `docs/business/demo/proposal.docx`.
- Output MUST live beside the input file.
- PDF output is out of scope.

## Requirements

- Pandoc is required for rendering. If it is not on `PATH`, the bundled script silently downloads a standalone pandoc binary into a per-user cache and uses it — no prompt, no question. Only a genuine install failure (e.g. no network) stops the render.
- Bash MUST be available. On Windows, Git Bash is the expected fallback when WSL bash is unavailable.
- The bundled `templates/reference.docx` file MUST exist.
- Relative images in Markdown SHOULD resolve from the Markdown file's directory.

## References

- Phase prompt: [prompts/01-render-docx.md](prompts/01-render-docx.md)
- Style template: [templates/reference.docx](templates/reference.docx)
- Handoff checklist: [references/checklist.md](references/checklist.md)
- Anti-patterns and remedies: [references/anti-patterns.md](references/anti-patterns.md)