bruce-doc-converter-skill

Name: bruce-doc-converter-skill
Author: bruc3van

56stars7forks

How to install bruce-doc-converter-skill?

bruc3van/bruce-doc-converter/bruce-doc-converter-skill

$npx -y skills add bruc3van/bruce-doc-converter --skill bruce-doc-converter-skill

Installs into the current project.

Summary

双向文档转换工具，将 Word (.docx)、Excel (.xlsx)、PowerPoint (.pptx) 和 PDF (.pdf) 转换为 AI 友好的 Markdown，或将 Markdown (.md) 转换为 Word (.docx)（支持 Mermaid 图表自动渲染为 PNG）。当用户请求文档转换、导出、读取、分析 Office/PDF/Markdown 文件，或上传这些格式并询问内容时使用。

Files · 1

View on GitHub

SKILL.md

1	# Bruce Doc Converter
2
3	Agent-facing document converter CLI..
4
5	## When to use
6
7	Use this skill when the user asks to:
8
9	- Convert `.docx`, `.xlsx`, `.pptx`, `.pdf`, or `.md` files.
10	- Read, summarize, inspect, or analyze Office/PDF documents.
11	- Export Markdown as Word.
12	- Process uploaded document files whose content the agent cannot directly read.
13
14	## Setup and version check
15
16	Run this first — it checks installation status and current version in one step:
17
18	```bash
19	bdc --help-json
20	```
21
22	- Command not found → not installed. Install using one of the methods below, then re-run.
23	- Returns JSON with `cli_version` → installed. Compare against the latest on PyPI:
24	```bash
25	pip index versions bruce-doc-converter 2>/dev/null \| head -1
26	```
27	If the versions differ, upgrade (see Upgrade section), then re-run `bdc setup-node` if Markdown to Word was previously set up.
28
29	### Install (if not already installed)
30
31	Try the following in order — stop at the first that succeeds:
32
33	```bash
34	# 1. pipx (preferred — isolated, bdc lands in PATH)
35	pipx install bruce-doc-converter
36
37	# 2. uv (if available — fast, isolated, bdc lands in PATH)
38	uv tool install bruce-doc-converter
39
40	# 3. pip --user (most universally available, bdc lands in PATH)
41	pip3 install --user bruce-doc-converter # macOS/Linux
42	pip install --user bruce-doc-converter # Windows
43	# or universally: python3 -m pip install --user bruce-doc-converter (use `python` on Windows)
44
45	# 4. venv fallback (works everywhere, but bdc will NOT be in PATH)
46	python3 -m venv .venv
47	.venv/bin/pip install bruce-doc-converter
48	# Windows: .venv\Scripts\pip install bruce-doc-converter
49	```
50
51	> venv note: If you used the venv fallback, replace every `bdc` command below with `.venv/bin/bdc` (macOS/Linux) or `.venv\Scripts\bdc` (Windows).
52
53	> Windows note: Use `python` instead of `python3` if the former is not recognized.
54
55	## Command
56
57	Run:
58
59	```bash
60	bdc convert "<file>"
61	```
62
63	For Markdown files with Mermaid diagrams, PNG rendering defaults to scale `4`. Increase or decrease it when needed:
64
65	```bash
66	bdc convert "<file.md>" --mermaid-scale 5
67	```
68
69	For batch conversion:
70
71	```bash
72	bdc batch "<directory>"
73	bdc batch "<directory>" --mermaid-scale 5
74	```
75
76	For Markdown to Word, initialize the Node.js dependencies explicitly before first use:
77
78	```bash
79	bdc setup-node
80	```
81
82	If the Markdown contains Mermaid diagrams (` ```mermaid ` blocks), they will be automatically rendered as PNG images embedded in the Word document. The CLI automatically detects and uses the user's local Chrome / Edge / Chromium during conversion, launching it headlessly with a temporary browser profile, so do not install a bundled browser unless local browser detection fails.
83
84	If no local browser is available, explicitly install Puppeteer's dedicated browser:
85
86	```bash
87	bdc setup-node --install-browser
88	```
89
90	If your environment specifically requires npm lifecycle scripts, run:
91
92	```bash
93	bdc setup-node --allow-scripts --install-browser
94	```
95
96	> Linux note: Mermaid rendering is disabled by default on Linux sandboxed environments. Set `BRUCE_DOC_CONVERTER_ALLOW_CHROMIUM_NO_SANDBOX=1` if your environment requires it and you understand the risk.
97
98	The CLI prints JSON to stdout by default. Progress logs may appear on stderr.
99
100	## Output handling
101
102	Parse stdout as JSON.
103
104	On success:
105
106	- `success` is `true`.
107	- `output_path` points to the generated file.
108	- Office/PDF inputs include `markdown_content` for direct analysis.
109	- `.md` inputs produce a `.docx` file and may omit `markdown_content`.
110
111	On failure:
112
113	- `success` is `false`.
114	- Use `error_code`, `retryable`, optional `next_command`, `error`, and optional `suggestion` to decide the next step.
115	- Do not pre-check Python dependencies. Run the command first and react to JSON failure.
116	- If Markdown to Word returns `DEPENDENCY_INSTALL_REQUIRED`, run `next_command` when present, otherwise run `bdc setup-node`, then retry.
117	- `bdc setup-node` is idempotent and may return `already_installed: true` with `install_action: "skipped"`.
118
119	## Upgrade
120
121	To upgrade to the latest version, use the same tool you used to install:
122
123	```bash
124	pipx upgrade bruce-doc-converter # if installed via pipx
125	uv tool upgrade bruce-doc-converter # if installed via uv
126	pip install --user --upgrade bruce-doc-converter # if installed via pip --user
127	.venv/bin/pip install --upgrade bruce-doc-converter # if installed in a venv (macOS/Linux)
128	.venv\Scripts\pip install --upgrade bruce-doc-converter # venv on Windows
129	```
130
131	After upgrading, re-run `bdc setup-node` if you use Markdown to Word conversion, as Node.js dependencies may also have been updated.
132
133	## Troubleshooting installation
134
135	\| Error \| Cause \| Fix

People who liked this also viewed

6 picks

Type

bruce-doc-converter-skill

56stars7forks

View on GitHub

How to install bruce-doc-converter-skill?

bruc3van/bruce-doc-converter/bruce-doc-converter-skill

$npx -y skills add bruc3van/bruce-doc-converter --skill bruce-doc-converter-skill

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Bruce Doc Converter
2
3	Agent-facing document converter CLI..
4
5	## When to use
6
7	Use this skill when the user asks to:
8
9	- Convert `.docx`, `.xlsx`, `.pptx`, `.pdf`, or `.md` files.
10	- Read, summarize, inspect, or analyze Office/PDF documents.
11	- Export Markdown as Word.
12	- Process uploaded document files whose content the agent cannot directly read.
13
14	## Setup and version check
15
16	Run this first — it checks installation status and current version in one step:
17
18	```bash
19	bdc --help-json
20	```
21
22	- Command not found → not installed. Install using one of the methods below, then re-run.
23	- Returns JSON with `cli_version` → installed. Compare against the latest on PyPI:
24	```bash
25	pip index versions bruce-doc-converter 2>/dev/null \| head -1
26	```
27	If the versions differ, upgrade (see Upgrade section), then re-run `bdc setup-node` if Markdown to Word was previously set up.
28
29	### Install (if not already installed)
30
31	Try the following in order — stop at the first that succeeds:
32
33	```bash
34	# 1. pipx (preferred — isolated, bdc lands in PATH)
35	pipx install bruce-doc-converter
36
37	# 2. uv (if available — fast, isolated, bdc lands in PATH)
38	uv tool install bruce-doc-converter
39
40	# 3. pip --user (most universally available, bdc lands in PATH)
41	pip3 install --user bruce-doc-converter # macOS/Linux
42	pip install --user bruce-doc-converter # Windows
43	# or universally: python3 -m pip install --user bruce-doc-converter (use `python` on Windows)
44
45	# 4. venv fallback (works everywhere, but bdc will NOT be in PATH)
46	python3 -m venv .venv
47	.venv/bin/pip install bruce-doc-converter
48	# Windows: .venv\Scripts\pip install bruce-doc-converter
49	```
50
51	> venv note: If you used the venv fallback, replace every `bdc` command below with `.venv/bin/bdc` (macOS/Linux) or `.venv\Scripts\bdc` (Windows).
52
53	> Windows note: Use `python` instead of `python3` if the former is not recognized.
54
55	## Command
56
57	Run:
58
59	```bash
60	bdc convert "<file>"
61	```
62
63	For Markdown files with Mermaid diagrams, PNG rendering defaults to scale `4`. Increase or decrease it when needed:
64
65	```bash
66	bdc convert "<file.md>" --mermaid-scale 5
67	```
68
69	For batch conversion:
70
71	```bash
72	bdc batch "<directory>"
73	bdc batch "<directory>" --mermaid-scale 5
74	```
75
76	For Markdown to Word, initialize the Node.js dependencies explicitly before first use:
77
78	```bash
79	bdc setup-node
80	```
81
82	If the Markdown contains Mermaid diagrams (` ```mermaid ` blocks), they will be automatically rendered as PNG images embedded in the Word document. The CLI automatically detects and uses the user's local Chrome / Edge / Chromium during conversion, launching it headlessly with a temporary browser profile, so do not install a bundled browser unless local browser detection fails.
83
84	If no local browser is available, explicitly install Puppeteer's dedicated browser:
85
86	```bash
87	bdc setup-node --install-browser
88	```
89
90	If your environment specifically requires npm lifecycle scripts, run:
91
92	```bash
93	bdc setup-node --allow-scripts --install-browser
94	```
95
96	> Linux note: Mermaid rendering is disabled by default on Linux sandboxed environments. Set `BRUCE_DOC_CONVERTER_ALLOW_CHROMIUM_NO_SANDBOX=1` if your environment requires it and you understand the risk.
97
98	The CLI prints JSON to stdout by default. Progress logs may appear on stderr.
99
100	## Output handling
101
102	Parse stdout as JSON.
103
104	On success:
105
106	- `success` is `true`.
107	- `output_path` points to the generated file.
108	- Office/PDF inputs include `markdown_content` for direct analysis.
109	- `.md` inputs produce a `.docx` file and may omit `markdown_content`.
110
111	On failure:
112
113	- `success` is `false`.
114	- Use `error_code`, `retryable`, optional `next_command`, `error`, and optional `suggestion` to decide the next step.
115	- Do not pre-check Python dependencies. Run the command first and react to JSON failure.
116	- If Markdown to Word returns `DEPENDENCY_INSTALL_REQUIRED`, run `next_command` when present, otherwise run `bdc setup-node`, then retry.
117	- `bdc setup-node` is idempotent and may return `already_installed: true` with `install_action: "skipped"`.
118
119	## Upgrade
120
121	To upgrade to the latest version, use the same tool you used to install:
122
123	```bash
124	pipx upgrade bruce-doc-converter # if installed via pipx
125	uv tool upgrade bruce-doc-converter # if installed via uv
126	pip install --user --upgrade bruce-doc-converter # if installed via pip --user
127	.venv/bin/pip install --upgrade bruce-doc-converter # if installed in a venv (macOS/Linux)
128	.venv\Scripts\pip install --upgrade bruce-doc-converter # venv on Windows
129	```
130
131	After upgrading, re-run `bdc setup-node` if you use Markdown to Word conversion, as Node.js dependencies may also have been updated.
132
133	## Troubleshooting installation
134
135	\| Error \| Cause \| Fix

People who liked this also viewed

6 picks

Type