ComPDF Conversion CLI Skill

Purpose

• - Wraps the ComPDFKitConversion Python SDK into a reusable local conversion workflow, supporting PDF / image to Word, PPT, Excel, HTML, RTF, Image, TXT, JSON, Markdown, and CSV (10 output formats in total).

Agent Skills Standard Compatibility

• - This Skill uses an Anthropic Agent Skills-compatible directory structure: compdf-conversion-cli/.
• The entry point is SKILL.md; helper scripts are placed in scripts/.
• The document uses $ARGUMENTS and ${CLAUDE_SKILL_DIR} conventions for distribution and execution in Claude Code / Agent Skills-compatible environments.

Input / Output

• - Input: The target format (word/excel/ppt/html/rtf/image/txt/json/markdown/csv), the PDF or image path, and the output path are passed via Skill arguments or the command line. An optional PDF password and conversion parameters may also be provided.
• Supported input file types:

• - Output: A file in the corresponding format (.docx, .pptx, .xlsx, .html, .rtf, image, .txt, .json, .md, .csv), or a clear error message.

Prerequisites

• - Supports Windows and macOS.
• The conversion SDK must be installed first:

  pip install ComPDFKitConversion
  

• - On first run, the script automatically downloads license.xml from the ComPDF server and caches it in the scripts/ directory:

  https://download.compdf.com/skills/license/license.xml
  

• - The script reads the <key>...</key> field from license.xml and uses that key for LibraryManager.license_verify(...) authentication — it does not pass the XML file path directly to the SDK.
• To use a custom license, place your own license.xml in the scripts/ directory; the script will use it directly without downloading.
• During SDK initialization, the resource directory is always set to the directory containing compdf_conversion_cli.py, i.e., the scripts/ directory itself.
• When --enable-ocr or --enable-ai-layout (enabled by default) is used, the Skill also requires scripts/documentai.model. If the file does not exist, the script will automatically download it from:

  https://download.compdf.com/skills/model/documentai.model
  

• - To reuse an existing model file, you can override the default model path via an environment variable:

Workflow

1. 1. Confirm the Python package is installed:

   python -m pip show ComPDFKitConversion
   

1. 2. The script automatically downloads license.xml on first run; the scripts/ directory is used directly as the SDK resource path.
2. In Agent Skills / Claude Code environments, prefer using the Skill's built-in script path variable:

   python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" word input.pdf output.docx
   python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" ppt input.pdf output.pptx
   python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" excel input.pdf output.xlsx
   

1. 4. For more control, append common parameters:

   python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" excel input.pdf output.xlsx --page-ranges "1-3,5" --excel-all-content --excel-worksheet-option for-page
   python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" word input.pdf output.docx --enable-ocr --page-layout-mode flow
   

1. 5. On startup, the script ensures scripts/license.xml exists (downloading it automatically from the ComPDF server if missing), reads the <key> field for SDK authentication, and uses the scripts/ directory as the resource path.
2. If --enable-ocr or --enable-ai-layout (enabled by default) is active, the script checks whether scripts/documentai.model exists; if not, it downloads the file automatically before initializing the Document AI model.
3. Check the return code; if it is not SUCCESS, handle license, password, resource, model, or input file issues according to the error name.

documentai.model Download Optimization

• - The script preferentially uses the model file pointed to by COMPDF_DOCUMENT_AI_MODEL.
• The default model path is scripts/documentai.model.
• During automatic download, the file is first written to documentai.model.part and then atomically renamed to the final file upon success, preventing partial file corruption.
• On download failure, the script retries automatically with back-off intervals of 2s / 5s / 10s.

Invoking Directly as a Skill

• - In environments that support Agent Skills, the Skill can be called directly:

  /compdf-conversion-cli word input.pdf output.docx
  /compdf-conversion-cli excel input.pdf output.xlsx --excel-worksheet-option for-page
  

• - When the Skill receives arguments, it passes them through to the script as-is:

  python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" $ARGUMENTS
  

• - If the environment does not support direct Skill invocation, fall back to a regular command-line call.

Supported Output Formats

• - word → calls INLINECODE65
• INLINECODE66 → calls INLINECODE67
• INLINECODE68 → calls INLINECODE69
• INLINECODE70 → calls INLINECODE71
• INLINECODE72 → calls INLINECODE73
• INLINECODE74 → calls INLINECODE75
• INLINECODE76 → calls INLINECODE77
• INLINECODE78 → calls INLINECODE79
• INLINECODE80 → calls INLINECODE81
• INLINECODE82 → reuses CPDFConversion.start_pdf_to_excel with table/Excel parameters to produce CSV-friendly output

Input Source Types

• - The script supports PDF and image as input sources. The SDK's start_pdf_to_* interfaces natively accept image files with no pre-processing required.
• By default, the script auto-detects the input type from the file extension:

• - You can also specify the source type explicitly:

  python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" word input.png output.docx --source-type image
  

• - image -> * and pdf -> * share the same set of CPDFConversion.start_pdf_to_* interfaces; only the input file type differs.

Smart Defaults

When triggered, the script prints a notice to stderr, for example:
CODEBLOCK10

All Parameters

Positional Parameters

Parameter	Description
INLINECODE103	Target format: word/excel/ppt/html/rtf/image/txt/json/markdown/INLINECODE113
INLINECODE114

Input file path (PDF or image) |

General Parameters

Parameter	Type	Default	Description
INLINECODE116	Option	INLINECODE117	Input source type: auto/pdf/INLINECODE120
INLINECODE121

String | "" | PDF open password |

Layout Parameters

Parameter	Type	Default	Description
INLINECODE127	Boolean	True	AI layout analysis (disable with --no-enable-ai-layout)
INLINECODE129

Option | SDK default flow (auto-switched to box for HTML output) | Page layout: box (box layout) / flow (flow layout) |

Content Retention Parameters

Parameter	Type	Default	Description
INLINECODE134	Boolean	True	Retain images (disable with --no-contain-image)
INLINECODE136

Boolean | True | Retain annotations (disable with --no-contain-annotation) |

Output Control Parameters

Parameter	Type	Default	Description
INLINECODE142	Boolean	False	Split output into one document per page
INLINECODE143

Boolean | True | Automatically create output directory (disable with --no-auto-create-folder) |

OCR Parameters

Parameter	Type	Default	Description
INLINECODE145	Boolean	False (auto-enabled for image input)	Enable OCR
INLINECODE146

Option | SDK default all | OCR scope: invalid-character/scan-page/invalid-character-and-scan-page/all |

Excel-Specific Parameters

Parameter	Type	Default	Description
INLINECODE170	Boolean	False	Include all content in Excel output
INLINECODE171

Boolean | False | Output Excel result in CSV format |

JSON-Specific Parameters

Parameter	Type	Default	Description
INLINECODE177	Boolean	True	Include table data in JSON output (disable with --no-json-contain-table)

TXT-Specific Parameters

Parameter	Type	Default	Description
INLINECODE179	Boolean	True	Enable table formatting in TXT output (disable with --no-txt-table-format)

HTML-Specific Parameters

Parameter	Type	Default	Description
INLINECODE181	Option	SDK default INLINECODE182	HTML output mode: single-page/single-page-with-bookmark/multiple-page/INLINECODE186

Image-Specific Parameters

Parameter	Type	Default	Description
INLINECODE187	Option	SDK default INLINECODE188	Image output format: jpg/jpeg/jpeg2000/png/bmp/tiff/tga/gif/INLINECODE197
INLINECODE198

Option | SDK default color | Image color mode: color/gray/binary |

Parameter Default Value Rules

• - Parameters that default to True (--enable-ai-layout/--contain-image/--contain-annotation/--contain-page-background-image/--auto-create-folder/--json-contain-table/--txt-table-format) use BooleanOptionalAction; pass --no-xxx to disable.
• Parameters that default to False (--enable-ocr/--formula-to-image/--transparent-text/--output-document-per-page/--excel-all-content/--excel-csv-format/--image-path-enhance) use store_true; passing the flag enables them.
• All CLI parameter defaults are fully consistent with the SDK's ConvertOptions() defaults — omitting a parameter is equivalent to using the SDK's original default value.

Recommended Command Examples

PDF to Word (default parameters, AI layout analysis enabled)

PDF to Word, box layout, no images, no AI layout analysis

PDF to Word, retain annotations and background images, one document per page

PDF to Excel, include all content and split worksheets by page

PDF to TXT, with table formatting enabled

PDF to HTML, multi-page with bookmarks mode

PDF to Image, PNG format, grayscale, 2x scaling

Image to Word (OCR auto-enabled, specify Chinese language)

python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" word input.png output.docx --ocr-language chinese

Note: For image input, the script automatically enables OCR — there is no need to pass --enable-ocr manually. To specify an OCR language, --ocr-language can still be used.

PDF with OCR enabled (multiple languages)

Trial License and Usage Limits

• - The scripts/license.xml auto-downloaded from the ComPDF server is a Trial License, allowing a maximum of 200 conversions.
• The script uses a SHA-256 fingerprint to detect whether the current License is the default trial key; no usage limit applies when using any other License.
• After each successful conversion using the trial License, the script prints the current used/remaining count to stderr, for example:

  Trial license: 5/200 conversions used, 195 remaining.
  

• - When the trial limit is reached (200 conversions), the script refuses to convert and prompts the user to purchase a full License:

  Error: Trial license usage limit reached (200 conversions). Please purchase a license at: https://www.compdf.com/contact-sales
  

• - When the trial License has expired (SDK authentication fails), the error message also includes a purchase link.
• After purchasing a full License, place a custom license.xml containing the new <key> in scripts/ (overwriting the auto-downloaded trial file) — no script modifications or counter file cleanup are required.

Confirmed Facts

• - ComPDFKitConversion 3.9.0 has been successfully installed on the local machine.
• The installed package provides 10 conversion methods including CPDFConversion.start_pdf_to_word/start_pdf_to_ppt/start_pdf_to_excel.
• INLINECODE233 provides initialize, license_verify, release, set_document_ai_model, and set_ocr_language.
• Official documentation confirms support for PDF to Word / Excel / PPT / HTML / RTF / Image / TXT / JSON / Markdown.
• The SDK's start_pdf_to_* interfaces natively accept image file input (PNG → Word has been verified successfully).
• INLINECODE240 defaults to True in the SDK; set_document_ai_model() must be called first to load the model before use, otherwise a 0xC0000005 crash will occur.
• INLINECODE243 supports specifying multiple languages simultaneously (e.g. --ocr-language chinese english).

Risks / Notes

• - The official requirements page states Python >=3.6, while the demo page states <3.11, but PyPI currently provides a cp314 wheel in practice; treat the locally installable wheel as the source of truth, but always verify installation in a new environment first.
• If the script cannot download license.xml from the server (network issue) and no manual file exists in scripts/, or the <key> field is empty, the script cannot complete SDK authentication and cannot perform any real conversions.
• INLINECODE251 is a large file (approximately 525 MB); there will be a noticeable download delay the first time OCR / AI layout is enabled. Because --enable-ai-layout defaults to True, the model download will be triggered on the very first run.
• If the runtime environment cannot access https://download.compdf.com/skills/model/documentai.model, place documentai.model in the scripts/ directory in advance.
• Do not directly apply the initialization patterns from ComPDF SDKs for other languages to the Python package; this Skill is based on the locally verified LibraryManager / CPDFConversion API.

Resource Navigation

• - License file: INLINECODE258
• Script: INLINECODE259
• SDK authentication file: scripts/license.xml (auto-downloaded from https://download.compdf.com/skills/license/license.xml if missing)
• SDK authentication source: the <key> field in INLINECODE263
• SDK resource path: INLINECODE264
• OCR / AI layout model: scripts/documentai.model (auto-downloaded if missing)
• Purchase a full License: INLINECODE266
• Official documentation:

Acceptance Checklist

• - [ ] python -m pip show ComPDFKitConversion shows the installed package
• [ ] Running python "${CLAUDE_SKILL_DIR}/scripts/compdf_conversion_cli.py" --help or an equivalent local command produces normal output
• [ ] The script auto-downloads scripts/license.xml if missing, then extracts the license key from the <key> field for authentication
• [ ] The script uses the scripts/ directory as the SDK resource path
• [ ] The script recognizes all 10 target formats: word/excel/ppt/html/rtf/image/txt/json/markdown/INLINECODE286
• [ ] The script accepts both PDF and image files (.png/.jpg/.jpeg/.bmp/.tif/.tiff/.gif/.webp/.tga) as input
• [ ] When --enable-ocr or --enable-ai-layout (enabled by default) is active and documentai.model is missing, the script auto-downloads the model
• [ ] When license.xml cannot be obtained (download fails and no manual file exists) or authentication fails, a clear error is output rather than a silent failure
• [ ] The 7 parameters that default to True can be disabled with INLINECODE300
• [ ] --ocr-language supports specifying multiple languages simultaneously
• [ ] After a conversion using the trial License, the usage count increments
• [ ] When the trial License reaches 200 conversions, the script refuses to convert and outputs a purchase link
• [ ] When using a non-trial License, no usage limit applies
• [ ] For image input, even if --enable-ocr is not passed, the script automatically enables OCR and prints a notice to INLINECODE303
• [ ] For HTML output, even if --page-layout-mode is not passed, the script automatically uses box (box layout) and prints a notice to INLINECODE306
• [ ] For HTML output, explicitly passing --page-layout-mode flow overrides the automatic box layout behavior

Distribution Notes

• - This Skill does not depend on any machine-specific absolute paths.
• When distributing to other users, the following directory structure is sufficient:

  compdf-conversion-cli/
  ├── SKILL.md
  ├── License.txt
  └── scripts/
      └── compdf_conversion_cli.py
  

• - Users place this directory under their own skills root directory and the Skill is ready to use.
• INLINECODE308 is auto-downloaded at runtime; no need to include it in the distribution package.

Common Pitfalls

• - scripts/license.xml is missing and cannot be auto-downloaded (network unavailable or server error): the script will error out before authentication. If you are in an offline environment, place license.xml manually in the scripts/ directory.
• INLINECODE312 is missing the <key> field or its value is empty: the script will error out before authentication.
• SDK resource files required by the SDK are absent from the scripts/ directory: conversion may fail after LibraryManager.initialize().
• A password-protected PDF is provided without --password: this will trigger PDF_PASSWORD_ERROR.
• OCR / AI layout is enabled but documentai.model is not present locally and the network is unavailable: the model download will fail; place the file in the scripts/ directory manually in advance.
• When the Excel output strategy is unclear, prefer passing --excel-worksheet-option explicitly to avoid unexpected result structures.
• When converting images to other formats, the script already enables OCR automatically; if the output still contains no text, check whether documentai.model is complete and whether the OCR language matches.
• Once the trial License usage limit is exhausted, a full License must be purchased to continue; purchase link: https://www.compdf.com/contact-sales.

Copyright

This Skill is built on top of the ComPDFKit Conversion SDK.

CODEBLOCK23

• - SDK Name: ComPDFKitConversion
• SDK Author: PDF Technologies, Inc.
• License Type: Commercial License (Commercial / Proprietary) — non-exclusive, non-transferable, non-sublicensable, revocable
• Official Website: https://www.compdf.com
• Contact: support@compdf.com
• Terms of Service: https://www.compdf.com/terms-of-service
• Privacy Policy: https://www.compdf.com/privacy-policy

Important: Under the ComPDFKit Terms of Service, distributing the documentation, sample code, or source code of the ComPDFKit Conversion SDK to third parties is prohibited. Please ensure you have obtained a valid ComPDFKit License before using this Skill.